advantys/roster repository overview

⁠advantys/roster

Production Docker image for Roster deployments.

This image contains the Roster platform runtime, platform UI, REST API, remote MCP/OAuth connector endpoints, background worker, and production licensing.

⁠Image

• Audience: Production deployments
• Current image tag: latest
• Version tag example: 1.2.2
• Date tag format: 1.2.2-YYYYMMDD
• Architectures: linux/amd64, linux/arm64

⁠Production Editions

The same production image supports Free, Pro, and Enterprise.

Free team-member limits count human team members only. AI agents and service accounts are not counted in the 5-member Free limit.

Use the license key provided with your Pro or Enterprise subscription.

Structured stdout logs, liveness/readiness probes, and trace correlation are included in every edition. OTLP trace/metric export, the admin System health page, and its REST/MCP status interfaces require Enterprise in production.

For PostgreSQL 17/18 deployment, migration-role separation, backups, and high availability, see the public Database⁠ and High Availability⁠ guides. Existing SQLite deployments can continue using their current /data volume.

For OpenTelemetry configuration, privacy boundaries, and the local reference stack, see the public Telemetry⁠ guide.

⁠Run Locally

Pull the image:

docker pull advantys/roster:latest

Or pin a specific version:

docker pull advantys/roster:1.2.2

⁠Linux And macOS

Create a protected launch environment file:

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-prod.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"

For Pro or Enterprise, add the license key to the same environment file:

printf 'ROSTER_LICENSE_KEY=%s\n' '<license-jwt>' >> "$roster_env_file"

Start the container:

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

unset bootstrap_admin_password

Follow docker logs --follow roster-prod, press Ctrl+C to stop following the logs, and confirm readiness with:

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

Open:

http://localhost:3000/dashboard

A clean database bootstraps [email protected] with the generated bootstrap password. Roster reminds the administrator to change it after signing in and allows Skip for now for the current session by default.

⁠Windows PowerShell

Requirement: Docker Desktop must use the WSL 2 backend with Linux containers enabled. This Roster image is a Linux container image and does not run in Windows containers mode.

Create a protected launch environment file:

$authSecret = [Convert]::ToBase64String([System.Security.Cryptography.RandomNumberGenerator]::GetBytes(48))
$bootstrapAdminPassword = "Roster-1!" + [Convert]::ToBase64String([System.Security.Cryptography.RandomNumberGenerator]::GetBytes(32))
$providerSecret = [Convert]::ToBase64String([System.Security.Cryptography.RandomNumberGenerator]::GetBytes(48))
$rosterConfigDir = Join-Path $env:USERPROFILE ".roster"
$rosterEnvFile = Join-Path $rosterConfigDir "roster-prod.env"

New-Item -ItemType Directory -Force -Path $rosterConfigDir | Out-Null

@"
ROSTER_AUTH_SECRET=$authSecret
ROSTER_BOOTSTRAP_ADMIN_PASSWORD=$bootstrapAdminPassword
ROSTER_PROVIDER_SECRET_ENCRYPTION_KEY=$providerSecret
"@ | Set-Content -Path $rosterEnvFile -Encoding ascii

Write-Host "Save this bootstrap admin password now: $bootstrapAdminPassword"

For Pro or Enterprise, add the license key to the same environment file:

Add-Content -Path $rosterEnvFile -Value "ROSTER_LICENSE_KEY=<license-jwt>"

Start the container:

docker run -d `
  --name roster-prod `
  -p 127.0.0.1:3000:3000 `
  -v roster_prod_data:/data `
  --env-file "$rosterEnvFile" `
  advantys/roster:latest

Follow docker logs --follow roster-prod, press Ctrl+C to stop following the logs, and confirm readiness with:

Invoke-RestMethod http://localhost:3000/health/ready

Open:

http://localhost:3000/dashboard

A clean database bootstraps [email protected] with the generated bootstrap password. Roster reminds the administrator to change it after signing in and allows Skip for now for the current session by default.

Keep the launch file so its auth and provider-encryption secrets remain stable when the container is recreated or upgraded. After confirming the bootstrap administrator exists, remove only the ROSTER_BOOTSTRAP_ADMIN_PASSWORD=... line. Save the bootstrap password in your password manager before removing that line.

⁠Run Through A Public URL

Use a stable HTTPS URL when connecting remote MCP/OAuth clients such as Claude, Codex, or other connector clients.

Set the public URL in the container environment:

ROSTER_AUTH_URL=<your-roster-public-url>
ROSTER_AUTH_TRUSTED_ORIGINS=<your-roster-public-url>

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

The remote MCP endpoint is:

<your-roster-public-url>/mcp

⁠Persistent Data

The container stores runtime data under:

/data

Use a durable Docker volume or platform volume to keep state between restarts:

-v roster_prod_data:/data

Treat the mounted /data volume as production state. Back it up before image upgrades, platform changes, or database migrations.

⁠Upgrade To Roster 1.2.2

Pull advantys/roster:1.2.2, recreate the container with the same protected launch file and roster_prod_data volume, and keep both stable encryption secrets unchanged. An existing database whose bootstrap administrator already exists does not need ROSTER_BOOTSTRAP_ADMIN_PASSWORD.

Roster 1.2.2 improves Workday RaaS report loading, transient-failure handling, and duplicate membership handling without changing the normalized directory contract. Roster 1.2.1 improved Resolve model-provider compatibility without changing the Resolve API response shape. Roster 1.2.0 introduced vendor-neutral OpenTelemetry traces and metrics, an admin System health view, and matching REST/MCP status interfaces. Export remains disabled by default, so existing deployments do not need observability configuration. Enterprise operators can opt in by following the public Telemetry⁠ guide.

An existing SQLite deployment needs no operator-run database or data migration and continues using the same /data volume. Back up /data before upgrading. Roster does not provide an automated SQLite-to-PostgreSQL migration; a new PostgreSQL deployment starts with a separate PostgreSQL database and follows the public database migration procedure.

Roster updates protected authentication data automatically during startup. Rolling back below 1.0.3 requires restoring the pre-upgrade backup because an older image cannot read the updated representation.

Credentialed connector continuation URLs must remain on their configured origin. CSV connector files must live below /data/connectors/csv and below the connector's configured local_base_path. Adjust older custom connector paths before upgrading when necessary.

To reset a local disposable production-image test:

docker rm -f roster-prod
docker volume rm roster_prod_data

⁠Required Secrets

Generate fresh values per environment:

openssl rand -base64 48

Required runtime secrets:

• ROSTER_AUTH_SECRET
• ROSTER_PROVIDER_SECRET_ENCRYPTION_KEY

Required only for the first start of a fresh production database:

• ROSTER_BOOTSTRAP_ADMIN_PASSWORD

Save the bootstrap password for first login, confirm the bootstrap account, then remove it from the launch configuration. Existing databases do not need it.

Password-change prompts default to remind. Optionally set ROSTER_BOOTSTRAP_ADMIN_PASSWORD_CHANGE_MODE=required to block protected actions until rotation, or off to hide the prompt.

Required for Pro and Enterprise only:

• ROSTER_LICENSE_KEY or ROSTER_LICENSE_FILE

⁠License Key Examples

Use ROSTER_LICENSE_KEY when you want to pass the license key directly as an environment value:

ROSTER_LICENSE_KEY='<license-jwt>'

Use ROSTER_LICENSE_FILE when you want to mount the license key as a file:

printf '%s' '<license-jwt>' > ./roster-license.key
chmod 600 ./roster-license.key

docker run -d \
  --name roster-prod \
  -p 127.0.0.1:3000:3000 \
  -v roster_prod_data:/data \
  -v "$PWD/roster-license.key:/run/secrets/roster-license.key:ro" \
  --env-file "${XDG_CONFIG_HOME:-$HOME/.config}/roster/roster-prod.env" \
  -e ROSTER_LICENSE_FILE=/run/secrets/roster-license.key \
  advantys/roster:latest

⁠Resolve Model Provider

Configure model provider secrets such as OPENAI_API_KEY, MISTRAL_API_KEY, or ANTHROPIC_API_KEY only when the deployment uses those providers for Resolve or Model Runs.

For provider selection, supported model IDs, OpenRouter gateway setup, and recommended Resolve models, see the public Model Providers⁠ documentation.

Do not reuse temporary test secrets for production, shared demos, or public sessions.

⁠Tags

• latest: current stable production image
• 1.2.2: current production image
• 1.2.2-YYYYMMDD: daily traceable image

⁠Notes

This image is the production release channel for Roster. Without a license key, it starts in Free edition. With a valid Pro or Enterprise license key, it applies the licensed paid edition locally.