🚀 Project Deployment Guide

This document describes how to run and develop the project locally (via Docker) and how to deploy it into Kubernetes (via Helm).
It also provides guidance on environment setup, migrations, testing, and code quality checks.

---

⚙️ Requirements

Before starting, make sure you have installed:

• Docker (Containerized local development)
• Poetry (Python dependencies management)
• Helm (Kubernetes deployment)
• SOPS (Helm secrets encryption)
• pre-commit (Code checks and secrets auto-encryption before commit)

---

🌍 Environment Setup

The project relies on .env files and pre-commit hooks for correct operation.

1. Global .env (in the repository root)

⚠️ This step is required for Docker builds to access private repositories during the image build process.

Create .env in the root of the project (based on .env.example).
It must contain a path to your GitHub access token file:

GITHUB_ACCESS_TOKEN_FILE=/path/to/token/file

2. Service-specific .env

Each service (services/<SERVICE>/) contains its own .env.example. Before local development or running migrations, copy it to .env and fill in the required credentials:

cp services/<SERVICE>/.env.example services/<SERVICE>/.env

3. Setup pre-commit

Run once in the root of the repository:

pre-commit install

This will ensure that before each commit:

• code style and linters are checked.
• secrets.yaml is encrypted into secrets.enc.yaml automatically.

⚠️ Without these steps:

• Docker containers will not start correctly.
• Database migrations (Alembic) will fail.
• Secrets won’t be encrypted before commit.

---

📂 Project Structure

.
├── .github/                    # GitHub Actions workflows
├── helm/                       # Base Helm charts
├── k6/                         # Grafana k6 load tests
├── scripts/                    # Helper scripts
├── services/                   # Microservices (auth, user, etc.)
│   └── <service>/
│       ├── docker/             # Docker configuration (Dockerfile, docker-compose)
│       ├── helm/               # Helm chart for Kubernetes
│       ├── src/                # Source code
│       └── pyproject.toml      # Poetry configuration
├── .env                        # Global environment variables (github access token)
├── .pre-commit-config.yaml     # Pre-commit configuration (code quality checks)
├── .sops.yaml                  # SOPS GPG fingerprints (secrets.yaml encryption/decryption)
├── Makefile                    # Global commands (docker, helm, testing, linting)
└── team-keys.asc               # Team GPG keys for SOPS

---

🐳 Local Development with Docker

⚠️ Make sure .env files are created both in the project root and inside each service before starting containers.

Each service can be built and started individually. All commands are executed via make.

1. Build image

make build <SERVICE>

2. Start container

make up <SERVICE>

3. Stop container

make stop <SERVICE>

4. Remove container

make down <SERVICE>

5. Rebuild image (clean build)

make rebuild <SERVICE>

6. Destroy image

make destroy <SERVICE>

Example for the auth service:

make build auth
make up auth

---

☸️ Kubernetes Deployment with Helm

Kubernetes deployment is based on Helm charts with helm-secrets and sops for secret management. A detailed guide is available here: 👉 Helm Deployment Guide

---

🔧 Database Migrations (Alembic)

⚠️ Requires valid .env for the target service (copied from .env.example).

Create new migration

make revision <SERVICE> msg="add new table"

Apply migrations

make upgrade <SERVICE>

Revert migrations

make downgrade <SERVICE>

---

🧪 Testing

Run tests for a specific service:

make pytest <SERVICE>

Run tests with coverage report:

make pytest-cov <SERVICE>

---

🧹 Code Quality

Format and check code for a specific service:

• Lint:

  make lint <SERVICE>

• Format imports:

  make isort <SERVICE>

• Format code:

  make black <SERVICE>

• Type check:

  make mypy <SERVICE>

• Full check (lint, format, mypy, tests, helm-encrypt):

  make check <SERVICE>

---

🔐 Secrets Management

• Always work with secrets.yaml (plain text).

• secrets.enc.yaml is never edited manually — it is generated automatically:

  • during the global check step (make check <SERVICE>), or
  • via pre-commit hooks (if installed).

• If you use pre-commit, you don’t need to run make check manually before committing.

---

✅ Recommendations

• Use Docker for local development.
• Use Helm for deploying into Kubernetes clusters.
• Keep secrets only in secrets.yaml (do not commit plain text to git).
• Trust pre-commit to handle secret encryption automatically.
• Run make check <SERVICE> manually only if you want to verify locally without committing.