Docker Compose Deployment

The repository's docker-compose.example.yml is a complete single-host deployment, with every setting written directly in that one file: the API, two consoles, mail delivery, PostgreSQL, Redis, and two daily backups.

Requirements

ItemRequirement
HostLinux x86_64, at least 2 cores and 4 GB recommended
SoftwareDocker, Docker Compose v2, Git, OpenSSL
NetworkAccess to Docker Hub, an SMTP server, and the upstream APIs you need
DomainsOne each for the API, configuration console, and account console; HTTPS is provided by the reverse proxy

1. Get the deployment files

git clone https://github.com/xabcstack/xsi.git
cd xsi

umask 077
cp docker-compose.example.yml docker-compose.yml
sed -i "s/CHANGE_ME_POSTGRES_PASSWORD/$(openssl rand -hex 24)/g" docker-compose.yml
sed -i "s/CHANGE_ME_ROOT_KEY/sk-Xvs$(openssl rand -hex 24 | cut -c1-45)/" docker-compose.yml

The two sed commands generate the database password and the root account's API key. The root key lives in INIT_USERS and must be exactly 51 characters (the 6-character sk-Xvs prefix plus 45 random characters). docker-compose.yml and the backup directory are excluded by .gitignore.

2. Edit docker-compose.yml

Only these places need changes; keep the template values everywhere else:

WhereSettingDescription
x-site at the topXAI_SVC, XAI_API, XAI_ADMIN, XAI_MANAGE, XAI_DOCSDomains for the site, API, Admin Console, Manage Console and docs; hostname only, without scheme, path or /v1. The API and console services share this one block
x-tz at the topTime zoneDefault Asia/Shanghai; determines date-based statistics and when the daily quota resets. If you change it, update TimeZone in POSTGRES_DSN too
xsirouter-xsiINIT_USERS, XAI_MAILReplace [email protected] with your root email, which also receives platform notifications
xsirouter-xsiTRUSTED_PROXY_CIDRSTrusted reverse proxy ranges; see Reverse proxy
xsirouter-xsiSIGN_ENABLEWhether self-service signup is open, default true; finish the mail configuration before opening it
xsirouter-mailEMAIL_SMTP, EMAIL_PORT, EMAIL_TLS, EMAIL_AUTH, EMAIL_PASSYour SMTP service; EMAIL_TLS: "true" means implicit TLS (usually port 465)
xsirouter-pagesBRAND_NAME, LICENSE_ID, XPAY_API, SUPPORT_QR_URLConsole brand name, plus the optional commercial license ID, payment gateway URL (such as https://pay.example.com/t/my-tenant) and support QR code
Backup servicesBACKUP_RETENTION_DAYSBackup retention in days, default 3

Ports are bound to 127.0.0.1 for a reverse proxy on the same host; if the proxy runs elsewhere, bind a reachable address and restrict access. Write a literal $ in any value as $$. For the full list of environment variables, see Configuration reference.

3. Start

docker compose config --quiet   # Validate the configuration
docker compose up -d
docker compose ps
curl --fail http://127.0.0.1:5443/healthz   # Returns OK

The template uses pull_policy: always, so every start pulls the latest images. /healthz returning OK only means the HTTP service is ready; calling models also requires the upstream setup below.

Services

ServiceImagePortsDescription
xsirouter-xsiproxyxai/xsi5443 β†’ 3443API; 60-second stop grace period, file descriptor limit 1048576
xsirouter-pagesproxyxai/xsi-pages5080 β†’ 8080, 5081 β†’ 8081Configuration and account consoles
xsirouter-mailproxyxai/mailβ€”Consumes the mail queue in Redis DB 1 and delivers over SMTP; 40-second stop grace period
xsirouter-postgrespostgres:18β€”Business data, named volume mounted at /var/lib/postgresql
xsirouter-redisredis:alpineβ€”Configuration, cache, usage, and queues, named volume mounted at /data
xsirouter-postgres-backuppostgres:18β€”Daily pg_dump to backups/postgres/
xsirouter-redis-backupredis:alpineβ€”Daily RDB snapshot to backups/redis/

PostgreSQL and Redis are reachable only on the internal Compose network and publish no host ports.

The template pins the following runtime settings for the API; adjust them in docker-compose.yml as needed:

VariableTemplate valueDescription
USER_MIN_BALANCE2Calls are frozen when the balance falls below 1.99
XAI_CREDIT0Self-service signups receive no bonus credit
MODEL_FAILOVER_THRESHOLD22 consecutive failures of a model trigger group switchover or model failover
EMAIL_SMTP, EMAIL_AUTH, EMAIL_PASSEmptyThe API has no default SMTP; the mail service handles all delivery. Tenants can configure their own SMTP

4. Configure HTTPS entry points

Point the three domains at the reverse proxy and configure certificates:

Entry pointPublic URLSame-host target
APIhttps://api.example.comhttp://127.0.0.1:5443
Configuration consolehttps://admin.example.comhttp://127.0.0.1:5080
Account consolehttps://manage.example.comhttp://127.0.0.1:5081

The API entry point must support streaming responses and WebSocket upgrades; see Reverse proxy for Nginx and Caddy examples. Each console's English interface is at its /en/ path.

5. Connect upstreams and create calling accounts

  1. Open the Admin Console and sign in with the root key (the sk-Xvs... value in INIT_USERS).
  2. Under "Model Providers", add upstream keys with Provider, SecretKey, and Level, for example OpenAI in Level 1 and Anthropic in Level 2. XSI generates LEVEL_MAPPER automatically based on the provider.
  3. Under "System Config", check LEVEL_MAPPER and set MODEL_MAPPER, SWITCH_OVER, and so on as needed; see Routing and failover.
  4. Review the default price table and override it with the tenant PRICING if needed.
  5. In the account console, create the sub-accounts that will actually make calls and allocate credit to them; applications use the sub-account keys.
The root key has full platform privileges. Use it only for administration, never for routine model calls or distribution to applications. INIT_USERS only creates accounts that do not exist yet; editing docker-compose.yml does not reset an existing root key. To rotate it, use POST /x-self.

6. Verify

export XSI_BASE_URL="https://api.example.com"
export XSI_API_KEY="<sub-account key>"

curl "$XSI_BASE_URL/dashboard/status" -H "Authorization: Bearer $XSI_API_KEY"

curl "$XSI_BASE_URL/v1/chat/completions" \
  -H "Authorization: Bearer $XSI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-6.2-sol", "messages": [{"role": "user", "content": "Hello"}]}'

Multi-tenant and multi-instance

NeedSetting
Self-registered users become independent tenants (bringing their own upstream keys)API environment variable SINGLE_TENANT=false
Scale out with multiple API instancesAll instances share the same PostgreSQL and Redis, with SINGLE_MODE=false

For a multi-instance deployment, all API instances share the same PostgreSQL and Redis, and each API container must explicitly set SINGLE_MODE: "false" in its environment (the template does not pass this variable by default); sticky bindings, rate limit counters, and change notifications are then shared through Redis. Before scaling out on the same host, remove the fixed container_name and 5443 port mapping from the template.