GAME (Goals And Motivation Engine) is a system designed to foster motivation and achievement of goals through gamification. This open-source project utilizes a PostgreSQL database and is developed with FastAPI in Python, managed via Poetry for environment handling.
- Python 3.8+
- PostgreSQL
- Docker and Docker Compose (optional, for local database deployment)
- Poetry
The GAME project is structured to facilitate easy navigation and understanding for developers looking to contribute or integrate new features. Below is an overview of the project's directory structure and a brief explanation of each component:
.
├── alembic.ini # Configuration for Alembic migrations
├── app # Main application directory
│ ├── api # API route definitions
│ │ └── v1 # Version 1 of the API
│ │ ├── endpoints # API endpoints
│ │ └── routes.py # API route registrations
│ ├── core # Core application components (config, security)
│ ├── model # Database models
│ ├── repository # Data access layer
│ ├── schema # Pydantic schemas for request and response objects
│ ├── services # Business logic layer
│ └── util # Utility functions and classes
├── classes.png # Class diagram (if applicable)
├── default_strategy.json # Default strategy configuration
├── deployFiles # Deployment related files (if applicable)
├── doc # Documentation files and images
├── docker # Dockerfiles for containerization
├── docker-compose-dev.yml # Docker Compose for development
├── docker-compose.yml # Docker Compose for production
├── migrations # Alembic migrations
├── packages.png # Package diagram (if applicable)
├── poetry.lock # Poetry lock file (dependencies)
├── pyproject.toml # Poetry configuration and project metadata
├── README.md # Project README
├── requirements.txt # Python requirements (for non-Poetry environments)
├── strategies.md # Documentation on strategy patterns used
└── tests # Test suite (unit and integration tests)
This table uses emojis to denote the type of content (📁 for directories, 📄 for files) and provides a brief description to help in understanding their purpose:
Type | Path | Description |
---|---|---|
📁 | /app |
Root directory for application code. Contains all the service logic, models, and API endpoints. |
📁 | /app/api/v1 |
Contains version 1 of the API endpoints. This is where you define all the route handlers. |
📄 | /app/api/v1/endpoints/*.py |
API endpoint files like games.py , strategy.py , etc., defining the logic for each endpoint. |
📁 | /app/core |
Core configurations and utilities for the app, including database connection and configurations. |
📁 | /app/model |
Definitions of database models, mapping the database schema to Python code. |
📁 | /app/repository |
Data access layer, containing files that interact with the database models. |
📁 | /app/schema |
Schemas for request and response validation and serialization. |
📁 | /app/services |
Business logic layer, where the main application operations are defined. |
📄 | /app/main.py |
The entry point for the Flask application. Contains app initialization and route definitions. |
📄 | /docker-compose.yml |
Docker Compose configuration file for local development, defining how your containers are built. |
📁 | /docker |
Contains Dockerfiles for different services, useful for containerizing your application. |
📁 | /kubernetes |
Kubernetes configurations for deployment, including deployments, services, and persistent volumes. |
📁 | /migrations |
Alembic migrations for database schema management. Contains scripts for database versioning. |
📁 | /tests |
Contains all the test code, including unit and integration tests, organized by test type. |
📄 | /README.md |
The main documentation file for the project, explaining how to set up and run the project. |
Before starting the project, it's necessary to configure the environment variables. Copy the environment variables defined in .env.sample
to .env
. Below is an example and explanation of each variable:
VERSION_APP="1.0.0" # Version of GAME API
ENV=dev # Indicates whether the environment is development or production (dev|production)
DB_ENGINE=postgresql # Database engine
DB_NAME=game_dev_db # Database name
DB_USER=root # Database user
DB_PASSWORD=example # Database password
DB_HOST=localhost # Database host
DB_PORT=5432 # Database port
DEFAULT_CONVERSION_RATE_POINTS_TO_COIN=100 # Default conversion rate of points to coins
DATABASE_URL=postgresql://root:example@localhost:5432/game_dev_db # Database connection URL
IMPORTANT: Several points is protected, in this case you must define a Role into de Realm that you choose, and add the "AdministratorGAME" into the client called "account", after this, add the "AdministratorGAME" role to the selected user
To activate the Poetry environment, run:
poetry shell
If it's your first time running the project, install all dependencies with:
poetry install
To bring up the database locally, run:
docker-compose -f docker-compose.yml up --build
If it's the first time deploying the database, you should initialize it with Alembic:
alembic upgrade head
To deploy the REST API, run:
poetry run uvicorn app.main:app --host 0.0.0.0 --reload
Docker provides a way to run applications securely isolated in a container, packaged with all its dependencies and libraries. For the GAME project, Docker and Docker Compose are used to simplify the deployment of the PostgreSQL database and the FastAPI application, ensuring consistent environments from development to production.
- Docker
- Docker Compose
Ensure Docker and Docker Compose are installed on your machine. Docker Compose will use the docker-compose.yml
for production deployments and docker-compose-dev.yml
for development environments.
Dockerfile
: Contains the instructions for building the application's Docker image.docker-compose.yml
: Defines the production services, networks, and volumes.docker-compose-dev.yml
: Used for setting up the development environment with Docker Compose.
To set up the development environment, run:
docker-compose -f docker-compose-dev.yml up --build
This command builds the application image from the Dockerfile, sets up the PostgreSQL database, and runs the application in development mode.
For production deployment, use:
docker-compose up --build
This will pull the necessary images, set up the database, and run the application in production mode.
-
To build the Docker image for the application, navigate to the directory containing the Dockerfile and run:
docker build -t gamification-engine .
-
To run the application using Docker directly, you can use:
docker run -p 80:80 gamification-engine
- Kubernetes cluster: You can set up a cluster on cloud platforms like Google Kubernetes Engine (GKE), Amazon Elastic Kubernetes Service (EKS), Azure Kubernetes Service (AKS), or on-premises using Minikube or kubeadm.
- kubectl: The Kubernetes command-line tool,
kubectl
, allows you to run commands against Kubernetes clusters.
You've uploaded several configuration files, which are crucial for deploying applications on Kubernetes. Here's a brief overview of each:
deploy-kubernetes.sh
: Likely a shell script to automate the deployment process.env-prod-configmap.yaml
: Defines environment variables for your applications in a ConfigMap, making it easier to configure different environments.postgres-data-persistentvolumeclaim.yaml
: Creates a PersistentVolumeClaim (PVC) for PostgreSQL, ensuring data persists across pod restarts.ingress.yaml
: Defines rules for routing external HTTP(S) traffic to your services.gamificationengine-service.yaml
: Configures a service for the gamification engine, making it accessible within the cluster.postgres-service.yaml
: Creates a service for PostgreSQL, allowing other components to communicate with the database.postgres-deployment.yaml
: Defines the deployment for a PostgreSQL database, including its container image, environment variables, and storage.gamificationengine-deployment.yaml
: Describes the deployment for your gamification engine application..env
: Contains environment variables for your setup, not directly used by Kubernetes but could be used by your scripts or applications.
The deploy-kubernetes.sh
script is designed to automate the deployment of Kubernetes resources with the following options:
-
--postgres
: Apply only the PostgreSQL deployment and its dependencies. This option is useful for setting up or updating the database component of your application without affecting other parts. -
--api
: Apply only the API deployment and its dependencies. This allows for deploying or updating the API layer separately, which can be particularly handy for rolling updates or when testing new API features. -
--verbose
: Display verbose output. When this flag is used, the script provides more detailed information about the commands being executed, which is helpful for debugging or for more detailed logging purposes. -
--help
: Display the help message. This option shows usage information, including a description of each flag and examples of how to use the script.
bash deploy-kubernetes.sh
Ensure your Kubernetes cluster is up and running.
Configure kubectl
to connect to your Kubernetes cluster. This step varies depending on your cloud provider or local setup.
Navigate to the directory containing your Kubernetes configuration files and apply them using kubectl
. For example:
kubectl apply -f env-prod-configmap.yaml
kubectl apply -f postgres-data-persistentvolumeclaim.yaml
kubectl apply -f ingress.yaml
kubectl apply -f gamificationengine-service.yaml
kubectl apply -f postgres-service.yaml
kubectl apply -f postgres-deployment.yaml
kubectl apply -f gamificationengine-deployment.yaml
You can monitor the status of your deployments using:
kubectl get pods
kubectl get services
kubectl describe deployment <deployment-name>
- Ingress: If you're using an ingress, you'll need to configure DNS for your domain to point to your ingress IP.
- Port-Forwarding: For quick access or testing, you can use
kubectl port-forward
.
kubectl port-forward service/gamificationengine-service 8080:80
docker-compose -f docker-compose-dev.yml up --build
It will reload automatically when changes are detected
alembic upgrade head
: Applies all migrations.alembic downgrade base
: Reverts all migrations.alembic revision --autogenerate -m "revision_name"
: Creates a new migration.alembic history
: Shows Alembic revision history.
poetry run uvicorn app.main:app
: Runs the development server.- Options:
--host 0.0.0.0
: Specifies the host.--port 8000
: Specifies the port.
- Options:
poetry run uvicorn app.main:app --host 0.0.0.0 --reload
In the "dashboard" folder excecute the following commands
npm i
: Install all necesaries dependenciesnpm start
: Start dashboard in dev mode in the port 3000
First, you should activate poetry environment
With hotreload poetry run sphinx-autobuild docs/source docs/build/html --port 9000
. The documentation will be available at http://localhost:9000
.
poetry run pytest
: Runs basic tests.poetry run pytest --cov=app --cov-report=term-missing
: Runs tests with coverage and displays the report in the terminal.poetry run pytest --cov=app --cov-report=html
: Generates a coverage report in HTML.
This project uses unit tests to ensure the correctness of the code and maintain high standards of code quality. The tests are integrated with Codecov, which provides a detailed analysis of the code coverage across different parts of the codebase. Below is a visual representation of the current test coverage: