Production Deployment

Roster is distributed as the advantys/roster container image. The container serves the web platform, REST API, MCP endpoint, and background worker from one runtime.

Container Contract

Expose port 3000 from the container and mount durable storage at /data.

Image:  advantys/roster
Port:   3000
Volume: /data

Baseline environment:

NODE_ENV=production
HOST=0.0.0.0
PORT=3000
ROSTER_DATA_DIR=/data
ROSTER_AUTH_URL=https://roster.example.com
ROSTER_AUTH_SECRET=<generated-secret>
ROSTER_MCP_AUTH_MODE=oauth
ROSTER_MCP_RESOURCE_URI=https://roster.example.com/mcp

With ROSTER_DATA_DIR=/data and no ROSTER_DATABASE_URL, the container uses /data/roster.db.

Add model runtime settings for participant resolution:

OPENAI_API_KEY=<secret-or-gateway-token>
OPENAI_BASE_URL=https://api.openai.com/v1
ROSTER_MODEL_PROVIDER=openai-responses
ROSTER_MODEL_NAME=gpt-5.4
ROSTER_MODEL_EFFORT=low
ROSTER_MODEL_ALLOWED=openai-responses:gpt-5.4

For Mistral:

MISTRAL_API_KEY=<secret>
MISTRAL_BASE_URL=https://api.mistral.ai/v1
ROSTER_MODEL_PROVIDER=mistral-chat-completions
ROSTER_MODEL_NAME=mistral-medium-3-5
ROSTER_MODEL_EFFORT=low
ROSTER_MODEL_ALLOWED=mistral-chat-completions:mistral-medium-3-5

For Anthropic:

ANTHROPIC_API_KEY=<secret>
ANTHROPIC_BASE_URL=https://api.anthropic.com
ROSTER_MODEL_PROVIDER=anthropic-messages
ROSTER_MODEL_NAME=claude-sonnet-4-20250514
ROSTER_MODEL_EFFORT=low
ROSTER_MODEL_ALLOWED=anthropic-messages:claude-sonnet-4-20250514

*_BASE_URL values are optional. Set them only when routing model requests through a provider proxy, regional endpoint, or approved gateway.

Use this when only OAuth MCP clients should connect:

ROSTER_MCP_AUTH_MODE=oauth
ROSTER_MCP_RESOURCE_URI=https://roster.example.com/mcp

Use api_key,oauth only when production automation also needs API-key MCP access alongside OAuth-based end-user MCP clients. Keep ROSTER_OAUTH_DYNAMIC_CLIENT_REGISTRATION and ROSTER_OAUTH_UNAUTHENTICATED_CLIENT_REGISTRATION enabled only when the deployment intentionally accepts MCP clients that register themselves.

Add these before storing directory connector credentials:

ROSTER_PROVIDER_SECRET_ENCRYPTION_KEY=<high-entropy-secret>
ROSTER_PROVIDER_SECRET_KEY_ID=env:prod-2026-05

Platform Checklist

• Terminate TLS at the platform load balancer, ingress, or proxy.
• Preserve the public host and scheme through forwarding headers.
• Mount /data on durable storage with backups.
• Store secrets in the provider’s secret manager, not in image configuration.
• Configure health checks against the web service.
• Configure log export for container logs and worker journals.
• Keep API keys and provider credentials scoped to the minimum required access.

Backups

Treat the mounted /data volume as the source of production state. A production backup policy should:

• Back up the full /data volume, not only /data/roster.db.
• Include SQLite sidecar files such as roster.db-wal and roster.db-shm when they are present.
• Preserve connector files and runtime state stored under /data.
• Store backups off-host, encrypted at rest, and with a defined retention policy.
• Take a fresh backup before image upgrades, platform changes, or database migrations.
• Test restores regularly in an isolated deployment before relying on the backup process for production recovery.

AWS

Use one of the managed container runtimes:

Service	Fit
ECS on Fargate	General production container hosting without managing instances.
App Runner	Simpler HTTP container deployment with managed ingress.
EKS	Kubernetes-based deployments and teams already standardized on Kubernetes.

For persistent /data, use a durable volume strategy such as EFS for ECS/EKS or an equivalent managed persistent storage pattern. Store ROSTER_AUTH_SECRET, MCP settings, and provider encryption keys in AWS Secrets Manager or SSM Parameter Store.

Google Cloud

Use one of the managed container runtimes:

Service	Fit
Cloud Run	Managed HTTP container service with simple autoscaling.
GKE	Kubernetes-based deployments and custom network/storage control.

For Cloud Run, attach a durable storage strategy for /data before production use. Store secrets in Secret Manager and pass them as environment variables. Use a custom domain so ROSTER_AUTH_URL and ROSTER_MCP_RESOURCE_URI match the public HTTPS URL.

Azure

Use one of the managed container runtimes:

Service	Fit
Azure Container Apps	Managed container apps with ingress and scaling.
Azure App Service for Containers	Simple web container hosting.
AKS	Kubernetes-based deployments and custom platform control.

Mount durable storage for /data, store secrets in Key Vault, and expose the service through HTTPS. Set ROSTER_AUTH_URL to the final public URL.

Fly.io

Fly.io is a good fit for a single-container Roster deployment with a mounted volume:

flyctl volumes create roster_data -a roster -r cdg -s 1
flyctl secrets set ROSTER_AUTH_SECRET=...
flyctl secrets set ROSTER_MCP_AUTH_MODE=oauth
flyctl secrets set ROSTER_MCP_RESOURCE_URI=https://roster.example.com/mcp
flyctl secrets set ROSTER_PROVIDER_SECRET_ENCRYPTION_KEY=...
flyctl deploy

Set the app image to advantys/roster, mount the Fly volume at /data, and serve container port 3000.

Kubernetes

For Kubernetes-based platforms, deploy Roster as a single Deployment with a PersistentVolumeClaim mounted at /data.

Core requirements:

• one container using advantys/roster
• containerPort: 3000
• readiness/liveness checks on the HTTP service
• PersistentVolumeClaim mounted at /data
• secrets injected as environment variables
• ingress with HTTPS and stable public hostname

Use one replica unless the deployment shares a database and coordinates worker execution externally.

After Deployment

1. Open the public Roster URL and confirm login works.
2. Create or configure the first production administrator.
3. Configure identity providers for human access.
4. Configure directory connectors and verify refreshes.
5. Create scoped API keys for REST, CLI automation, and MCP clients.
6. Connect MCP clients only after ROSTER_MCP_AUTH_MODE is authenticated.