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.3.0
• Date tag format: 1.3.0-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.

⁠What's New In 1.3.0

• Resolve expands readable nested groups through 10 subgroup levels by default, without duplicate users, and existing group associations refresh automatically.
• Directory details display direct and indirect users, subgroups and parent groups, with one row per related record and clear relationship labels.
• User records show Member of and hide the inapplicable Members section.

Set ROSTER_DIRECTORY_GROUP_MAX_DEPTH in the launch environment to configure 1 to 32 subgroup levels, with 10 by default (root level 0). Recreate containers and refresh connectors after changing it; no image rebuild is needed. Connector support depends on the available relationships: Okta groups remain flat, and Workday nesting requires suitable reports and has no live-account validation. See the Directory records⁠ guide and connector compatibility⁠.

See the Changelog⁠ for public release notes.

⁠Run Locally

Pull the versioned image:

docker pull advantys/roster:1.3.0

⁠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:1.3.0

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:1.3.0

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.3.0

Pull advantys/roster:1.3.0, 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.3.0 adds an index for efficient parent-group lookups without introducing new hierarchy tables. Existing group associations discover readable nested memberships during refresh; reattaching each subgroup is not required. Resolve REST and MCP response formats remain unchanged.

Back up the database and /data before upgrading. SQLite applies pending migrations during startup by default and continues using the same volume. For production PostgreSQL, apply migrations once with the privileged migration role before starting restricted application replicas. Follow the public Database upgrade procedure⁠.

Roster does not provide an automated SQLite-to-PostgreSQL migration; a new PostgreSQL deployment starts with a separate PostgreSQL database.

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:1.3.0

⁠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.3.0: current production image
• 1.3.0-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.