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
| Item | Requirement |
|---|---|
| Host | Linux x86_64, at least 2 cores and 4 GB recommended |
| Software | Docker, Docker Compose v2, Git, OpenSSL |
| Network | Access to Docker Hub, an SMTP server, and the upstream APIs you need |
| Domains | One 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.ymlThe 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:
| Where | Setting | Description |
|---|---|---|
x-site at the top | XAI_SVC, XAI_API, XAI_ADMIN, XAI_MANAGE, XAI_DOCS | Domains 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 top | Time zone | Default Asia/Shanghai; determines date-based statistics and when the daily quota resets. If you change it, update TimeZone in POSTGRES_DSN too |
xsirouter-xsi | INIT_USERS, XAI_MAIL | Replace [email protected] with your root email, which also receives platform notifications |
xsirouter-xsi | TRUSTED_PROXY_CIDRS | Trusted reverse proxy ranges; see Reverse proxy |
xsirouter-xsi | SIGN_ENABLE | Whether self-service signup is open, default true; finish the mail configuration before opening it |
xsirouter-mail | EMAIL_SMTP, EMAIL_PORT, EMAIL_TLS, EMAIL_AUTH, EMAIL_PASS | Your SMTP service; EMAIL_TLS: "true" means implicit TLS (usually port 465) |
xsirouter-pages | BRAND_NAME, LICENSE_ID, XPAY_API, SUPPORT_QR_URL | Console 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 services | BACKUP_RETENTION_DAYS | Backup 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 OKThe 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
| Service | Image | Ports | Description |
|---|---|---|---|
xsirouter-xsi | proxyxai/xsi | 5443 β 3443 | API; 60-second stop grace period, file descriptor limit 1048576 |
xsirouter-pages | proxyxai/xsi-pages | 5080 β 8080, 5081 β 8081 | Configuration and account consoles |
xsirouter-mail | proxyxai/mail | β | Consumes the mail queue in Redis DB 1 and delivers over SMTP; 40-second stop grace period |
xsirouter-postgres | postgres:18 | β | Business data, named volume mounted at /var/lib/postgresql |
xsirouter-redis | redis:alpine | β | Configuration, cache, usage, and queues, named volume mounted at /data |
xsirouter-postgres-backup | postgres:18 | β | Daily pg_dump to backups/postgres/ |
xsirouter-redis-backup | redis: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:
| Variable | Template value | Description |
|---|---|---|
USER_MIN_BALANCE | 2 | Calls are frozen when the balance falls below 1.99 |
XAI_CREDIT | 0 | Self-service signups receive no bonus credit |
MODEL_FAILOVER_THRESHOLD | 2 | 2 consecutive failures of a model trigger group switchover or model failover |
EMAIL_SMTP, EMAIL_AUTH, EMAIL_PASS | Empty | The 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 point | Public URL | Same-host target |
|---|---|---|
| API | https://api.example.com | http://127.0.0.1:5443 |
| Configuration console | https://admin.example.com | http://127.0.0.1:5080 |
| Account console | https://manage.example.com | http://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
- Open the Admin Console and sign in with the root key (the
sk-Xvs...value inINIT_USERS). - 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_MAPPERautomatically based on the provider. - Under "System Config", check
LEVEL_MAPPERand setMODEL_MAPPER,SWITCH_OVER, and so on as needed; see Routing and failover. - Review the default price table and override it with the tenant
PRICINGif needed. - In the account console, create the sub-accounts that will actually make calls and allocate credit to them; applications use the sub-account keys.
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
| Need | Setting |
|---|---|
| Self-registered users become independent tenants (bringing their own upstream keys) | API environment variable SINGLE_TENANT=false |
| Scale out with multiple API instances | All 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.