Deployment

Local / Development

make install-dev
source venv/bin/activate    # Linux/macOS
# venv\Scripts\activate     # Windows

cp .env.example .env
# Edit .env
make generate-key           # Add key to .env
make run

The server listens on http://0.0.0.0:8080 by default.

Docker

Build

make docker-build
# or: docker build -f docker/Dockerfile -t aegis-gitea-mcp .

Configure

Create a .env file (copy from .env.example) with your settings before starting the container.

Run

make docker-up
# or: docker-compose up -d

Logs

make docker-logs
# or: docker-compose logs -f

Stop

make docker-down
# or: docker-compose down

docker-compose.yml Overview

The included docker-compose.yml provides:

Health check: polls GET /health every 30 seconds
Audit log volume: mounts a named volume at /var/log/aegis-mcp so logs survive container restarts
Resource limits: 1 CPU, 512 MB memory
Security: non-root user, no-new-privileges
Traefik labels: commented out — uncomment and set MCP_DOMAIN to enable automatic HTTPS via Traefik

Enabling Traefik

Set MCP_DOMAIN=mcp.yourdomain.com in .env.
Uncomment the Traefik labels in docker-compose.yml.
Make sure Traefik is running with a web and websecure entrypoint and Let's Encrypt configured.

Dockerfile Details

The image uses a multi-stage build:

Stage	Base image	Purpose
`builder`	`python:3.11-slim`	Install dependencies
`final`	`python:3.11-slim`	Minimal runtime image

The final image:

Runs as user aegis (UID 1000, GID 1000)
Exposes port 8080
Entry point: python -m aegis_gitea_mcp.server

Production Checklist

AUTH_ENABLED=true and MCP_API_KEYS set to a strong key
GITEA_TOKEN belongs to a dedicated bot user with minimal permissions
TLS terminated at the reverse proxy (Traefik, nginx, Caddy, etc.)
AUDIT_LOG_PATH points to a persistent volume
Log rotation configured for the audit log file
API key rotation scheduled (every 90 days recommended)
MAX_AUTH_FAILURES and AUTH_FAILURE_WINDOW tuned for your threat model
Resource limits configured in Docker/Kubernetes

Kubernetes (Basic)

A minimal Kubernetes deployment is not included, but the server is stateless and the Docker image is suitable for use in Kubernetes. Key considerations:

Store .env values as a Secret and expose them as environment variables.
Mount an emptyDir or PersistentVolumeClaim at the audit log path.
Use a readinessProbe and livenessProbe on GET /health.
Set resources.requests and resources.limits for CPU and memory.

Updating

git pull
make docker-build
make docker-up

If you added a new key via make generate-key during the update, restart the container to pick up the new .env:

docker-compose restart aegis-mcp

2.9 KiB Raw Blame History