Skip to main content

Local Deployment

This guide covers local deployment setup using docker compose to orchestrate all services in a "production-like" but still local environment.

The stack of services we are going to deploy are the following:

  • FastAPI backend (accessible at :8000/docs)
  • Next.js frontend (:3000)
  • APISIX API Gateway (:9080) - handles routing and injects user headers
  • PostgreSQL database with persistent volumes
  • Migrate service - runs Alembic migrations automatically
  • Abraxas Worker - Temporal-based worker for batch/regular workflows

Prerequisites​

  • Docker and Docker Compose (latest versions)
  • GemFury credentials for private package access (can be found in bitwarden)

Local Deployment Steps​

1. Environment Configuration​

Set GemFury credentials as environment variables:

# most important is to set UV_EXTRA_INDEX_URL before attempting docker compose build
export UV_EXTRA_INDEX_URL="..."

Create local environment file:

cp deployment/docker/.env.docker.local deployment/docker/.env.docker.local.example

Then set the env variables to add your API keys etc as appropriate.

2. Build Images​

# Build all images
docker compose -p {{project_name}} -f deployment/docker/docker-compose.yml build

This builds:

  • {{project_name}}-fastapi: the image for the fastapi backend container and the migration container
  • {{project_name}}-frontend: the image for the frontend container
  • {{project_name}}-worker: the image for the worker container

3. Start Services​

docker compose -p {{project_name}} -f docker/docker-compose.yml up

Migrations run automatically once PostgreSQL is ready.

4. Verify Local Deployment​

Use localhost:9080 for testing (not :3000) to ensure proper routing through APISIX.

Checklist:

  • Check migration logs: docker compose -p {{project_name}} -f deployment/docker/docker-compose.yml logs migrate
  • Verify FastAPI: http://localhost:8000/docs
  • Verify Frontend: http://localhost:9080 (recommended) or http://localhost:3000 (debugging only)
  • Check worker logs: docker compose -p {{project_name}} -f deployment/docker/docker-compose.yml logs worker
  • Verify all services running: docker compose -p {{project_name}} -f deployment/docker/docker-compose.yml ps

Note: APISIX injects hardcoded test user headers locally:

{
  "email": "hello@mistral.ai",
  "first_name": "Fake",
  "last_name": "User"
}

5. Next Steps​

Once everything is running fine locally, you can move on to the next section to deploy in k8s prod environment.

Data Persistence​

  • PostgreSQL: Data persisted to Docker volumes
  • Azurite: Not yet integrated in the local stack (PRs welcome)

Troubleshooting​

Common Issues​

Build failures: Verify GemFury credentials are set correctly

Migration errors: Check PostgreSQL logs and ensure database is ready:

docker compose -p {{project_name}} -f deployment/docker/docker-compose.yml logs postgres

307 redirects: Use APISIX endpoint (:9080) instead of direct service ports

Individual service debugging: Each service is accessible on localhost for debugging:

  • FastAPI: :8000
  • Frontend: :3000
  • APISIX: :9080

Docker Compose Structure​

docker/
├── apisix_conf/
│   ├── apisix.yaml       # APISIX routing configuration
│   └── config.yaml       # APISIX service configuration
├── docker-compose.yml    # Service orchestration
├── Dockerfile.fastapi    # FastAPI image
├── Dockerfile.frontend   # Next.js image
├── Dockerfile.worker     # Abraxas worker image
└── README.md