Deployment Overview

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. The public Docker Hub repository is advantys/roster.

Choose a deployment shape

Shape	Database	Roster instances	Availability
Standalone	SQLite	One	All editions
Standalone	PostgreSQL 17 or 18	One	Enterprise
High availability	PostgreSQL 17 or 18	Two or more	Enterprise

Standalone SQLite deployments keep the database and runtime state on durable /data storage. PostgreSQL deployments use a managed database and a dedicated migration job; high availability adds multiple identical Roster instances.

Use SQLite for the simplest evaluation and for a single-instance deployment that can attach durable block storage. Choose standalone PostgreSQL when an Enterprise deployment needs managed database operations without multiple Roster instances. Choose high availability only when both the Roster runtime and PostgreSQL are designed and operated as redundant services.

See Databases and Migrations before choosing storage, migration, or backup settings. Use High Availability for a multi-instance Roster cluster with PostgreSQL failover.

Run locally with SQLite

Run these commands in a terminal on the machine where Docker is installed. For the local quick start, use the same machine as your browser. The commands assume a Bash-compatible shell on Linux or macOS; on Windows, use WSL or Git Bash. Confirm that Docker, OpenSSL, and curl are available before continuing:

docker --version
openssl version
curl --version

bootstrap_admin_password='Roster-1!'"$(openssl rand -hex 24)"
roster_config_dir="${XDG_CONFIG_HOME:-$HOME/.config}/roster"
roster_env_file="$roster_config_dir/roster.env"

mkdir -p "$roster_config_dir"
chmod 700 "$roster_config_dir"

cat > "$roster_env_file" <<EOF
ROSTER_AUTH_SECRET=$(openssl rand -base64 48)
ROSTER_BOOTSTRAP_ADMIN_PASSWORD=$bootstrap_admin_password
ROSTER_PROVIDER_SECRET_ENCRYPTION_KEY=$(openssl rand -base64 48)
EOF

chmod 600 "$roster_env_file"

printf 'Save this bootstrap admin password now: %s\n' "$bootstrap_admin_password"

docker pull advantys/roster:latest

docker run -d \
  --name roster \
  -p 127.0.0.1:3000:3000 \
  -v roster_data:/data \
  --env-file "$roster_env_file" \
  advantys/roster:latest

unset bootstrap_admin_password

Follow the startup logs:

docker logs --follow roster

Press Ctrl+C to stop following the logs; this does not stop the container. Confirm that Roster is ready:

curl -fsS http://localhost:3000/health/ready

Then open http://localhost:3000/dashboard. A new data volume bootstraps admin@roster.local with the generated bootstrap password and asks for a password change after first sign-in.

Save the printed bootstrap password in your password manager. Keep the mode-0600 launch file: its auth and provider-encryption secrets must remain stable when the container is recreated or upgraded. After you change the bootstrap administrator password, remove only the ROSTER_BOOTSTRAP_ADMIN_PASSWORD=... line from that file. Roster does not display or recover the bootstrap value.

This setup uses the default SQLite database at /data/roster.db.

This local launch does not require a model provider API key to start the container, sign in, configure settings, or explore the platform. Resolve and Model Runs require one configured model provider key, such as OPENAI_API_KEY; until then, model-backed requests return a configuration error.

Explore the local evaluation

Sign in as admin@roster.local with the saved bootstrap password.
Follow Create your first project and participant to add a test project and a routing role through the web interface.
For a people-resolution result, configure a Directory Connector, reopen the participant, and associate a directory user or group. A fresh Roster database does not contain external directory people to add manually; you can skip this step when you only want to inspect participant-role selection.
Configure a Model Provider when you are ready to test Resolve—asking Roster which role or person should handle a request.
Open Playground, select Test mode and the sample project, then ask: Who should handle vendor security review for the Atlas onboarding project?
Inspect the matched role on the Participants tab. If you associated a directory user or group, inspect the Users tab as well. Open Resolve Requests to review the saved request.

Without a directory association, a routing-only run can still select the sample participant, but the Users tab remains empty and the resolution status is not_found. This means Roster matched the role but could not resolve it to a person; it is not a container or model-provider setup failure.

Model-provider values are container environment settings. After adding them to the protected launch file, recreate only the roster container. The named volume remains intact, so projects, participants, and other evaluation data are preserved:

roster_env_file="${XDG_CONFIG_HOME:-$HOME/.config}/roster/roster.env"

docker rm -f roster
docker run -d \
  --name roster \
  -p 127.0.0.1:3000:3000 \
  -v roster_data:/data \
  --env-file "$roster_env_file" \
  advantys/roster:latest

Follow the startup logs and repeat the readiness check shown above before continuing the evaluation.

Reset the local evaluation

Warning: The following commands permanently delete the local evaluation container and all data in its Docker volume. Do not use them for a deployment whose data you need to keep.

docker rm -f roster
docker volume rm roster_data

Run the complete local quick-start block again to create a fresh volume, bootstrap password, and launch environment file.

Container contract and defaults

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

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

The image defaults to:

NODE_ENV=production
HOST=0.0.0.0
PORT=3000
ROSTER_DATA_DIR=/data

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

ROSTER_AUTH_URL defaults to http://localhost:${PORT} when unset, which is useful for same-machine local container tests. Set it to the final public HTTPS origin before exposing the deployment or connecting OAuth-based MCP clients.

Roster derives the MCP OAuth resource URI automatically as ${ROSTER_AUTH_URL}/mcp.

ROSTER_MCP_AUTH_MODE is optional and defaults to api_key,oauth. Set it only when you need to restrict MCP to api_key, oauth, or local-only none.

For a new deployment, continue with Production configuration. Use the next section only when upgrading an existing installation.

Upgrade an existing Docker deployment

Before upgrading, complete the SQLite backup and restore procedure, keep the current deployment secrets available, and record the current container’s ports, volume mounts, network, restart policy, and environment source.

If the existing deployment was created with the local Docker procedure on this page, upgrade it with the following sequence. For a customized deployment, use the same sequence but preserve its existing container settings and /data mount exactly.

roster_env_file="${XDG_CONFIG_HOME:-$HOME/.config}/roster/roster.env"

docker pull advantys/roster:1.2.2
docker stop roster
docker rm roster

docker run -d \
  --name roster \
  -p 127.0.0.1:3000:3000 \
  -v roster_data:/data \
  --env-file "$roster_env_file" \
  advantys/roster:1.2.2

(
  for attempt in $(seq 1 60); do
    if curl -fsS http://localhost:3000/health/ready; then
      exit 0
    fi

    if [ "$attempt" -eq 60 ]; then
      docker logs --tail 100 roster
      printf >&2 'Roster did not become ready. Keep the container stopped from production traffic and inspect the logs above.\n'
      exit 1
    fi

    sleep 2
  done
)

If the readiness check reports a failure, do not continue the rollout until the startup problem has been diagnosed and corrected. The parenthesized readiness check returns a non-zero status without closing an interactive terminal.

Removing the old container does not remove the roster_data volume. Do not delete or replace that volume during an upgrade. Confirm login and a representative project read before removing the pre-upgrade backup. If the new version cannot be accepted, restore the pre-upgrade backup instead of starting an older image against a database already modified by the new version.

Existing installations do not need to add ROSTER_BOOTSTRAP_ADMIN_PASSWORD if the bootstrap administrator already exists. The container entrypoint applies required database migrations during normal startup; no separate migration command or data conversion is required. This describes an existing SQLite deployment continuing on SQLite. Roster does not provide an automated SQLite-to-PostgreSQL migration; see Changing database engines.

Keep ROSTER_AUTH_SECRET and ROSTER_PROVIDER_SECRET_ENCRYPTION_KEY unchanged.

Additional steps when upgrading from Roster 1.0.2 or earlier

Roster 1.0.3 introduced protected authentication-data encryption. When upgrading directly from Roster 1.0.2 or earlier, startup applies that protection automatically. Older images cannot read the updated representation, so rolling back requires restoring the pre-upgrade /data backup.

Roster 1.0.3 also introduced stricter connector boundaries. Credentialed pagination and follow-up URLs must stay on the connector’s configured origin. CSV connector files must be stored below ${ROSTER_DATA_DIR}/connectors/csv (normally /data/connectors/csv in Docker), and each configured CSV file must remain below its connector’s local_base_path. Before upgrading, move files into that directory and update the connector if the older deployment used arbitrary host paths. These restrictions require no database or data-format migration.

Production configuration

For production or externally reachable deployments, set ROSTER_AUTH_URL to the final public HTTPS origin and store secrets in your deployment secret manager. Do not bake secrets into a custom image.

Generate separate high-entropy values for ROSTER_AUTH_SECRET, ROSTER_BOOTSTRAP_ADMIN_PASSWORD, and ROSTER_PROVIDER_SECRET_ENCRYPTION_KEY. Keep the encryption secrets stable across container restarts; changing them can invalidate sessions or prevent encrypted settings and provider credentials from decrypting.

openssl rand -base64 48

For the first start of a fresh production database, the minimum production environment is:

ROSTER_AUTH_URL=<your-roster-public-url>
ROSTER_AUTH_SECRET=<generated-auth-secret>
ROSTER_BOOTSTRAP_ADMIN_PASSWORD=<generated-strong-password>
ROSTER_PROVIDER_SECRET_ENCRYPTION_KEY=<generated-provider-secret-encryption-key>

ROSTER_BOOTSTRAP_ADMIN_PASSWORD is a first-start secret. After confirming the bootstrap administrator exists, remove it from the deployment configuration. Roster ignores it while the bootstrap administrator exists, but a fresh or reset database would reuse the retained bootstrap password. Keep ROSTER_AUTH_SECRET and ROSTER_PROVIDER_SECRET_ENCRYPTION_KEY configured and stable.

Add one model provider key before using Resolve or Model Runs. See Model Providers for supported providers, models, gateways, and runtime variables.

Use this MCP auth override only when OAuth MCP clients should connect and API-key automation should not:

ROSTER_MCP_AUTH_MODE=oauth

Unset or blank defaults to api_key,oauth for production automation and OAuth-based end-user MCP clients. Enable ROSTER_OAUTH_DYNAMIC_CLIENT_REGISTRATION and ROSTER_OAUTH_UNAUTHENTICATED_CLIENT_REGISTRATION only when the deployment intentionally accepts MCP clients that register themselves.

See Environment Variables for the complete public runtime and CLI variable reference.

Production checklist

Terminate TLS at the platform load balancer, ingress, or proxy.
Preserve the public host and scheme through forwarding headers.
Configure the database, migration mode, and backups in Databases and Migrations.
For multi-instance deployments, follow the High Availability architecture.
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.
Install and monitor the license required by the selected edition.

Continue deployment setup

Licensing covers editions, limits, license installation, expiration, and renewal.

Databases and Migrations covers database selection, migration jobs, roles, and backups.

High Availability covers Roster instances, load balancing, PostgreSQL primary/read-replica routing and failover, health probes, and shared runtime coordination.

Hosting Platforms covers AWS, Google Cloud, Azure, Fly.io, and Kubernetes.
Environment Variables is the complete runtime and CLI configuration reference.

Model Providers covers provider credentials, supported models, gateways, and API options.

After deployment

Open the public Roster URL and confirm login works.
Create or configure the first production administrator.
Create a project and representative participants.
Configure identity providers for human access.
Configure directory connectors and verify refreshes.
Configure a model provider and test a representative question in Playground.
Create scoped API keys for REST, CLI automation, and MCP clients.
Connect MCP clients only after MCP authentication is configured and tested.