Deployment¶
AugMed supports multiple deployment options, from one-click cloud platforms to full AWS infrastructure.
Deployment Options¶
| Option | Monthly Cost | Technical Skill | Best For |
|---|---|---|---|
| Railway | ~$5-8 | None | Quick demos, small studies |
| Render | ~$21 | Low | Small-medium studies |
| Docker Compose | ~$6-12 (VPS) | Medium | Institutional servers, privacy requirements |
| AWS (Terraform) | ~$30-50 | High | Large-scale production, existing AWS infrastructure |
Railway (One-Click)¶
The fastest way to deploy. See the full guide: One-Click Deploy.
Railway deploys all four services (API, Frontend, RL, PostgreSQL) from a template. Environment variables auto-configure. Demo data seeds on first boot.
Render (Blueprint)¶
This repository includes a render.yaml Blueprint that defines all services.
- Log in to Render
- Click "New" → "Blueprint"
- Connect the
augmed-api-v2repository - Render will detect
render.yamland configure all services automatically
The Blueprint creates: API (web service), Frontend (web service), RL service (web service), and PostgreSQL database. Secrets are auto-generated.
Docker Compose (Self-Hosted)¶
See the full guide: Self-Hosted Deploy.
git clone https://github.com/DHEPLab/augmed-api-v2.git
git clone https://github.com/DHEPLab/augmed-app-v2.git
git clone https://github.com/DHEPLab/augmed-rl.git
cd augmed-api-v2
docker compose -f docker-compose.full.yml up --build
Access at http://localhost:8080. For production VPS deployment, add a reverse proxy (Caddy/nginx) for HTTPS.
AWS (Advanced)¶
For teams with existing AWS infrastructure or large-scale production needs. This is the original deployment method and remains fully supported.
Infrastructure Overview¶
Production infrastructure is managed via Terraform and lives in the augmed-infra repository. The main components are:
Internet
│
▼
Route 53 (DNS)
│
▼
Application Load Balancer (ALB)
│
├── /api/* ──► ECS Fargate Service (Flask API)
│ │
│ ▼
│ RDS PostgreSQL
│
└── /* ──────► [Frontend hosting - separate]
AWS Services Used¶
| Service | Purpose |
|---|---|
| ECS Fargate | Runs the containerized Flask API — no servers to manage |
| ECR | Container registry — Docker images are pushed here and pulled by ECS |
| RDS PostgreSQL | Managed PostgreSQL database |
| ALB | Application Load Balancer — routes traffic, handles SSL termination |
| Route 53 | DNS — maps augmed1.dhep.org to the ALB |
| S3 | Static assets and deployment artifacts |
| CloudWatch | Logs and monitoring |
CI/CD Pipeline¶
GitHub Actions handles building and deploying. The workflow file is at .github/workflows/ in the repository.
On push to main:
1. Run tests (pytest)
2. Build Docker image
3. Push image to ECR with the git commit SHA as the tag
4. Update the ECS service to use the new image (rolling deployment)
Manual deployment:
# Build and push image manually (requires AWS CLI configured)
aws ecr get-login-password --region us-east-1 | \
docker login --username AWS --password-stdin <account>.dkr.ecr.us-east-1.amazonaws.com
docker build -t augmed-api .
docker tag augmed-api:latest <account>.dkr.ecr.us-east-1.amazonaws.com/augmed-api:latest
docker push <account>.dkr.ecr.us-east-1.amazonaws.com/augmed-api:latest
# Force ECS to pick up the new image
aws ecs update-service \
--cluster augmed-cluster \
--service augmed-api-service \
--force-new-deployment
Terraform Setup¶
See the augmed-infra repository for full Terraform configuration.
Quick reference for applying infrastructure changes:
cd augmed-infra
terraform init
terraform plan # Preview changes
terraform apply # Apply changes
Warning
Terraform changes to RDS (database) can cause downtime or data loss. Always review the plan carefully before applying, especially for database-related resources.
Environment Variables¶
The Flask API reads configuration from environment variables. In production, these are set in the ECS task definition.
| Variable | Required | Description |
|---|---|---|
DATABASE_URL |
Yes | PostgreSQL connection string: postgresql://user:pass@host:5432/dbname |
JWT_SECRET_KEY |
Yes | Secret key for signing JWT tokens — must be strong and kept private |
JWT_ACCESS_TOKEN_EXPIRES |
No | Access token lifetime in seconds (default: 259200 = 3 days) |
JWT_REFRESH_TOKEN_EXPIRES |
No | Refresh token lifetime in seconds (default: 259200 = 3 days) |
POSTGRES_USER |
Yes | Database username (used by export scripts) |
POSTGRES_PASSWORD |
Yes | Database password (used by export scripts) |
POSTGRES_DB |
Yes | Database name |
POSTGRES_HOST |
Yes | Database host (used by export scripts) |
POSTGRES_PORT |
No | Database port (default: 5432) |
EXPORT_API_KEY |
Yes | API key for the export endpoint (used by RL service for service-to-service auth) |
CORS_ORIGINS |
No | Comma-separated allowed origins, or * for all (default: *) |
SEED_DEMO_DATA |
No | Set to true to seed demo data on first boot (default: false) |
GUNICORN_WORKERS |
No | Number of gunicorn worker processes (default: 2) |
Updating Secrets¶
In production, update secrets through the AWS console (ECS task definition) or via the AWS CLI:
aws ssm put-parameter \
--name "/augmed/production/jwt-secret" \
--value "new-secret-value" \
--type SecureString \
--overwrite
Then update the ECS task definition to reference the new parameter version and redeploy.
Docker Configuration¶
The Dockerfile at the project root builds the API image. The container uses entrypoint.sh which runs database migrations, optionally seeds demo data, and starts gunicorn (production WSGI server).
# Key build steps (abbreviated — see actual Dockerfile for full content)
FROM python:3.11-slim
WORKDIR /usr/src/app
COPY Pipfile Pipfile.lock ./
RUN pip install pipenv && pipenv install --deploy --ignore-pipfile
COPY . .
CMD ["/usr/src/app/entrypoint.sh"]
Build locally:
docker build -t augmed-api:local .
docker run -p 5000:5000 --env-file .env augmed-api:local
Database Migrations¶
Alembic (via Flask-Migrate) manages database schema changes. Migrations run automatically when the API starts (upgrade() is called in create_app()).
Creating a new migration:
cd src
flask db migrate -m "Add new column to user table"
# Review the generated script in src/migrations/versions/
flask db upgrade
Important
Always review generated migration scripts before running upgrade. Auto-generated scripts sometimes include drop_table or other destructive operations that are not intended.
Rolling back:
flask db downgrade
Health Check¶
The ALB uses the health check endpoint to determine if instances are healthy:
GET /api/healthcheck
Expected response:
{"status": "OK", "message": "Service is up and running."}
HTTP 200 = healthy. The ALB will route traffic away from unhealthy instances automatically.
Monitoring¶
CloudWatch Logs — Container logs (stdout/stderr from Flask) stream to CloudWatch. Access through the AWS console: CloudWatch → Log Groups → /ecs/augmed-api.
ECS Service Events — Deployment events and instance health changes appear in: ECS → Clusters → augmed-cluster → Services → augmed-api-service → Events tab.
Related Documentation¶
- Troubleshooting — Common issues and solutions
- Database — Schema and migration details
- Configuration — System and answer config setup