Initial commit

This is a FastAPI backend microservice template used with `copier` utility.

Features of applied template are:
- Configuration file processing logic
- Metrics and tracing (both optional) configuration available
- Debug endpoints
- Database migration commands, prepared Alembic environment
- Database usage example in ping_db endpoint
- gitea sanity check pipeline

deploy/Dockerfile.jinja

@@ -0,0 +1,23 @@
+FROM python:3.14-slim
+
+RUN groupadd --gid 1500 uvicorn && useradd uvicorn --gid 1500 --uid 1500
+
+RUN apt update && apt install -y --no-install-recommends \
+        build-essential \
+        curl \
+        python3-dev && \
+    apt clean && rm -rf /var/lib/apt/lists/*
+
+WORKDIR /app
+
+COPY pyproject.toml README.md /app/
+
+RUN mkdir {{project_slug}} && touch {{project_slug}}/__init__.py && pip install .
+
+COPY {{project_slug}} /app/{{project_slug}}
+
+RUN pip install .
+
+USER uvicorn
+
+CMD ["uvicorn", "{{project_slug}}.fastapi_init:app", "--host", "0.0.0.0", "--port", "8080"]

deploy/README.md

@@ -0,0 +1,21 @@
+# deploy example
+
+This is a complete deployment example with following services:
+
+- `postgres` database (with initialization and rootless user):
+    - 5432 port exposure commented
+- `api` (with data migrations) with 8080 port exposure:
+    - configured by [configs/api.yaml](./configs/api.yaml)
+    - exposes 8080 port
+    - 9090 metrics port not exposed
+- `prometheus` to collect metrics
+    - configured by [configs/prometheus.yaml](./configs/prometheus.yaml)
+    - exposes 9090 port with prometheus UI (optional)
+- `grafana` as a powerful UI for metrics visualization
+    - exposes 3000 port, default user:password is `admin`:`admin`
+    - prometheus metrics are available at `http://prometheus:9090`
+- `jaeger` to collect and show traces
+    - exposes UI at port 16686
+- `otel` (OpenTELemetry) agent working as proxy for jaeger
+    - configured by [configs/otel.yaml](./configs/otel.yaml)
+    - does not expose 4317/4318 ports as containers use it inside the internal network

deploy/configs/api.yaml.jinja

@@ -0,0 +1,27 @@
+app:
+  host: 0.0.0.0
+  port: 8080
+  debug: true
+  cors:
+    allow_origins: ["*"]
+    allow_methods: ["*"]
+    allow_headers: ["*"]
+    allow_credentials: True
+db:
+  master:
+    host: {{project_slug}}_db
+    port: 5432
+    database: {{project_slug}}_db
+    user: postgres
+    password: postgres
+    pool_size: 2
+logging:
+  level: INFO
+observability:
+  prometheus:
+    host: 0.0.0.0
+    port: 9090
+    urls_mapping:
+      /api/debug/.*: /api/debug/*
+  jaeger:
+    endpoint: http://otel:4318/v1/traces

deploy/configs/otel.yaml.jinja

@@ -0,0 +1,30 @@
+receivers:
+  otlp:
+    protocols:
+      grpc:
+        endpoint: 0.0.0.0:4317
+      http:
+        endpoint: 0.0.0.0:4318
+
+exporters:
+  otlp/jaeger:
+    endpoint: "http://jaeger:4317"
+    tls:
+      insecure: true
+  debug:
+    verbosity: detailed
+
+processors:
+  batch:
+
+service:
+  pipelines:
+    traces:
+      receivers: [otlp]
+      exporters: [debug, otlp/jaeger]
+    metrics:
+      receivers: [otlp]
+      exporters: [debug]
+    logs:
+      receivers: [otlp]
+      exporters: [debug]

deploy/configs/prometheus.yml.jinja

@@ -0,0 +1,13 @@
+global:
+  scrape_interval: 15s
+  evaluation_interval: 15s
+
+scrape_configs:
+  - job_name: prometheus
+    static_configs:
+      - targets:
+        - "localhost:9090"
+  - job_name: {{project_name}}
+    static_configs:
+      - targets:
+        - "{{project_name}}:9090"

deploy/docker-compose.yaml.jinja

@@ -0,0 +1,146 @@
+name: {{project_name}}
+
+services:
+  # postgres database
+
+  database-init:
+    image: postgres:17
+    container_name: {{project_slug}}_db-init
+    volumes: &postgres-volumes
+      - ./data/postgres:/var/lib/postgresql/data
+    entrypoint: ["chown", "-R", "postgres:postgres", "/var/lib/postgresql/data"]
+
+  database:
+    container_name: {{project_slug}}_db
+    image: postgres:17 # or postgis/postgis:17-3.5
+    restart: unless-stopped
+    depends_on:
+      database-init:
+        condition: service_completed_successfully
+    environment:
+      POSTGRES_USER: ${POSTGRES_USER:-postgres}
+      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:-postgres}
+      POSTGRES_DB: ${POSTGRES_DB:-{{project_slug}}_db}
+    # ports:
+    #   - 5432:5432
+    volumes: *postgres-volumes
+    healthcheck:
+      test: pg_isready -d postgres
+      interval: 15s
+      timeout: 5s
+      retries: 3
+      start_period: 5s
+    user: "postgres"
+    logging: &json-logging
+      driver: "json-file"
+      options:
+        max-size: "50m"
+        max-file: "4"
+
+  # api schema migrator running before the app launch
+
+  migrator:
+    container_name: {{project_name}}-migrator
+    build: &api-build-section
+      context: ..
+      dockerfile: deploy/Dockerfile
+    environment: &api-environment-section
+      CONFIG_PATH: /app/config.yaml
+    volumes: &api-volumes-section
+      - ./configs/api.yaml:/app/config.yaml
+    depends_on:
+      database:
+        condition: service_healthy
+    entrypoint: ["/bin/sh", "-c"]
+    command: ["cd /app/{{project_slug}}/db && alembic upgrade head; if [ $? = 0 ]; then echo \"Database schema synchronized\"; else echo \"alembic upgrade has failed, database state is undetermined\"; exit 1; fi"]
+    logging: *json-logging
+
+  # API server
+
+  api:
+    container_name: {{project_name}}
+    build: *api-build-section
+    restart: unless-stopped
+    ports:
+      - ${EXPORT_API_PORT:-8080}:${PORT:-8080}
+    environment: *api-environment-section
+    volumes: *api-volumes-section
+    depends_on:
+      migrator:
+        condition: service_completed_successfully
+      prometheus: # optional
+        condition: service_started
+      otel: # optional
+        condition: service_started
+    healthcheck:
+      test: ["CMD", "curl", "-f", "http://localhost:${PORT:-8080}/health_check/ping"]
+      interval: 10s
+      timeout: 5s
+      start_period: 5s
+    logging: *json-logging
+
+  # prometheus + grafana monitoring
+
+  prometheus-init:
+    image: prom/prometheus:latest
+    container_name: prometheus-init
+    volumes: &prometheus-volumes-section
+      - ./configs/prometheus.yml:/etc/prometheus/prometheus.yml
+      - ./data/prometheus:/prometheus
+    entrypoint: ["chown", "-R", "65534:65534", "/prometheus"]
+    user: "root"
+
+  prometheus:
+    image: prom/prometheus:latest
+    container_name: prometheus
+    restart: unless-stopped
+    ports:
+      - 9090:9090
+    volumes: *prometheus-volumes-section
+    logging: *json-logging
+
+  grafana-init:
+    image: grafana/grafana-enterprise:latest
+    container_name: grafana-init
+    volumes: &grafana-volumes-section
+      - ./data/grafana:/var/lib/grafana
+    user: "root"
+    entrypoint: ["chown", "-R", "472:0", "/var/lib/grafana"]
+
+  grafana:
+    image: grafana/grafana-enterprise:latest
+    container_name: grafana
+    restart: unless-stopped
+    ports:
+      - 3000:3000
+    volumes: *grafana-volumes-section
+    depends_on:
+      grafana-init:
+        condition: service_completed_successfully
+    logging: *json-logging
+
+  # jaeger tracing
+
+  jaeger:
+    container_name: jaeger
+    image: cr.jaegertracing.io/jaegertracing/jaeger:2.11.0
+    ports:
+      - 16686:16686
+      # - 5778:5778
+      # - 9411:9411
+    restart: unless-stopped
+    logging: *json-logging
+    
+  otel:
+    container_name: otel
+    image: otel/opentelemetry-collector
+    # ports:
+    #   - 4317:4317
+    #   - 4318:4318
+    restart: unless-stopped
+    volumes:
+      - ./configs/otel.yaml:/etc/otelcol/config.yaml 
+    depends_on:
+      - jaeger
+    logging: *json-logging
+