Deploy with Docker Compose
Build BOS API from source and manage private configuration, the app, MySQL, Redis, HTTPS, and routine operations.
Prerequisites & deployment approach
Use ./deploy/stack.sh up --source for both initial deployment and subsequent source updates. It generates deploy/stack.env when missing, reuses existing passwords, keys, and custom settings, then builds and starts services. A separate init command is unnecessary. Run it in the bos-api application repository, not this website repository. It does not fetch Git.
This guide targets a single Linux host, with host Nginx serving the static frontend and Go serving APIs by default. up --source creates a missing static root, invoking sudo when its parent is not writable. Configure Nginx after startup and publication; updates reuse those settings. For an existing instance, review backups, the target release, and original configuration first.
| Item | Requirement |
|---|---|
| Docker | Docker Engine, Compose v2 with up --wait support, and Buildx. Use a local Docker daemon accessible through docker info. |
| CLI tools | Git, Bash, OpenSSL, and curl. Run commands as root or a deployment user with Docker access, consistently using the same user and Docker daemon. |
| Static frontend | Default Nginx mode requires host Nginx, Python 3.9+, and a static root writable by the deployment user and readable by Nginx. |
| Network & resources | Allow access to the source repository, selected image registries, npm/pnpm, and Go modules. Allow enough memory and disk for compilation, images, and persistent data. |
| Default ports | The app uses 127.0.0.1:18080 and MySQL uses 127.0.0.1:13306. Redis has no published host port. Public HTTPS also requires ports 80 / 443. |
docker info
docker compose version
docker buildx version
git --version
bash --version
openssl version
curl --version- Host installations of Go, Node.js, MySQL, and Redis are unnecessary. BOS_WEB_DELIVERY=go serves the frontend through the app and skips static publication and its Python requirement. Nginx can also proxy all requests to the app.
- The Compose project name is fixed to bosapi-stack. Do not create another default instance alongside the one-command installation on the same Docker daemon. Copying a directory does not isolate containers, ports, or data volumes.
Step 1: get the source
Clone the BOS API application repository on the deployment server. Run subsequent commands from that application repository root. The boss-api-protal website repository hosts this documentation.
git clone https://github.com/secure-typex/bos-api.git bos-api
cd bos-api
git rev-parse HEADRecord the commit ID to identify the deployed revision. If the repository requires authentication, use your existing Git credentials and keep tokens out of commands and documentation.
- For production, select a reviewed tag or commit before initialization. Ensure it contains deploy/stack.sh, docker-compose.yml, and backend/Dockerfile used by this guide.
- The build needs frontend/, backend/, and the complete build context. Downloading docker-compose.yml alone is insufficient. Public downloads may return 404 while the repository is private.
Step 2: review static storage and optionally edit configuration
Defaults are BOS_WEB_DELIVERY=nginx and BOS_WEB_ROOT=/var/www/bosapi. You can proceed directly to up --source: it checks Docker, creates and validates a missing static root, then initializes configuration and starts services. New directories use mode 0755; sudo access is needed when the parent is not writable. Existing directories and permissions are preserved; correct any missing write access separately. The script does not install or configure Nginx.
The static root must be a dedicated absolute path, not the filesystem root, inside the application checkout, or a parent of the checkout. Neither the root nor its parents may be symlinks. start and publish-web check an existing root but do not create it; older scripts may still require manual preparation.
sudo install -d -o "$(id -un)" -g "$(id -gn)" -m 0755 /var/www/bosapiup --source already creates a missing root, so this command is usually unnecessary. For manual preparation, use the account that will deploy the app. Keep the static root outside the checkout, with no symlinks in the root or its parents. Nginx needs read and directory traversal permissions.
./deploy/stack.sh initUse this step only to edit the port, administrator email, or frontend mode before startup. init generates or reuses configuration without starting containers; the current script prints the initial administrator email and password in the terminal. up --source already initializes configuration and ends with the credentials file location.
BOS_WEB_DELIVERY=nginx
BOS_WEB_ROOT=/var/www/bosapi
BOSAPI_BIND_IP=127.0.0.1
BOSAPI_PORT=18080
BOS_ADMIN_EMAIL=owner@example.com
TZ=Asia/ShanghaiThis is an excerpt, not a replacement file. Edit existing fields while retaining all passwords and keys. To skip static publication, set BOS_WEB_DELIVERY to go and omit static-root preparation.
- With complete existing configuration, up --source reuses passwords, keys, data mounts, and frontend mode without resetting existing administrator accounts.
- stack.sh loads deploy/stack.env automatically. Direct Compose commands still require --env-file deploy/stack.env and -f deploy/docker-compose.yml. Do not execute the configuration with source.
- If data exists but stack.env is missing, restore the original configuration and keys before init or up. The management script lacks the entry installer’s old-volume protection; new keys cannot decrypt old data.
Step 3: build and start services
Use the same command for first deployment and updates. The script checks Docker, creates a missing static root and checks permissions in Nginx mode, generates private configuration when needed, builds both applications, waits for service health, and publishes the frontend. Run all commands from the bos-api root.
| Command | Build and update behavior |
|---|---|
| ./deploy/stack.sh up --source | Builds the current checkout. After backend readiness, removes the old deploy/image.env so later runs default to source mode. |
| ./deploy/stack.sh up --image IMAGE_REFERENCE | Replace IMAGE_REFERENCE with the intended version tag or digest. Pulls and resolves it to an immutable local image ID, then saves deploy/image.env after backend readiness without building application source. |
| ./deploy/stack.sh up | Reuses the pinned image without pulling or building when deploy/image.env exists; otherwise builds source. Use --source explicitly after uploading new source. |
| ./deploy/stack.sh start | Starts with the existing mode and local images without building source or fetching a newer application image. |
./deploy/stack.sh up --source./deploy/stack.sh status- The app’s depends_on starts MySQL and Redis and waits for their health checks. The first build downloads dependencies and compiles both applications. Startup applies pending database migrations.
- --source explicitly builds the current checkout even if this host previously pinned an image. It does not fetch Git; upload or fetch the target source first. start or docker compose pull alone does not build new code.
- Nginx mode publishes the frontend from the healthy app image and atomically switches /var/www/bosapi/current. Routine updates require no manual frontend copy or Nginx reload. Validate and reload when changing Nginx configuration itself.
- If startup fails, inspect logs, fix the error, and repeat the start command. Preserve stack.env and data volumes throughout recovery.
Step 4: verify, sign in, and configure access
Check backend readiness and the frontend on the server. The readiness response should have data.status equal to ok, and the login page should return HTML. Replace 18080 if you configured a different port.
curl -fsS http://127.0.0.1:18080/health/ready
curl -fsS -o /dev/null http://127.0.0.1:18080/loginssh -N -L 18080:127.0.0.1:18080 deploy-user@server.example.comReplace the SSH user and server address, keep the tunnel running, and open http://127.0.0.1:18080/login locally. Default ports listen only on loopback; opening the firewall alone does not enable public-IP access.
- Read BOS_ADMIN_EMAIL and BOS_ADMIN_PASSWORD privately from deploy/stack.env on the server. up ends with the credentials file location; a separate init prints the initial credentials. Enroll an MFA authenticator on first login.
- After login, save the final endpoint as described under Save the actual API address below. Then configure upstream accounts or API keys, channels, and models; create an organization and assign channels/models; create an organization gateway key and verify an authorized request and its usage record.
- Readiness checks the database connection; verify Redis through container status and actual features. Deployment includes no model credits or upstream permissions. Verify administrator login and a real model request as well.
Configure Nginx static access once
After the app starts and publishes its frontend, configure Nginx on the same host. These snippets use the default static root and port 18080. Back up and merge existing site configuration, retaining certificates, domains, and other settings. Deployment scripts do not install, edit, or reload Nginx.
sudo mkdir -p /etc/nginx/snippets
sudo cp deploy/nginx/bosapi-proxy.conf /etc/nginx/snippets/
sudo cp deploy/nginx/bosapi-static.conf /etc/nginx/snippets/Add the map from deploy/nginx/bosapi-connection.conf once in the Nginx http context, reusing an existing map with that name. The http context must also load mime.types. Adjust bosapi-proxy.conf for a custom app port.
server {
listen 80;
server_name bosapi.example.com;
client_max_body_size 128m;
include /etc/nginx/snippets/bosapi-static.conf;
}Replace the domain and enable the site through your host’s existing setup. Configure HTTPS for public production use. In an existing HTTPS site, retain TLS settings and replace the catch-all location / with this include. This example does not obtain certificates.
sudo nginx -t && sudo systemctl reload nginx
curl -fsS https://bosapi.example.com/health/ready
curl -fsS -o /dev/null https://bosapi.example.com/loginUse the configured domain and protocol; use http:// if only the HTTP example is enabled. Also verify pages, static assets, login, and streaming model requests in the browser.
- Nginx reads /var/www/bosapi/current directly and forwards APIs to 127.0.0.1:18080. Keep the app on loopback and expose the required public ports 80 / 443.
- After choosing Nginx static mode, use ./deploy/stack.sh up --source for deployment and updates. Avoid install.sh --local for this mode: that entry point resets BOS_WEB_DELIVERY to go on every run.
- If static publication alone fails, the backend may already be updated. Fix storage or publication errors and retry ./deploy/stack.sh publish-web. This does not roll back the backend or database.
Alternative: enable HTTPS through Caddy
As an alternative to Nginx static access, let Go serve the frontend and Caddy provide HTTPS. Point the domain’s A / AAAA records to the server, free ports 80 / 443, and allow them through the host firewall and cloud security group. These commands add HTTPS to the same initialized instance.
BOS_WEB_DELIVERY=go
BOS_INSTALL_DOMAIN=api.example.comReplace the example domain and retain all other settings. BOS_INSTALL_DOMAIN is a hostname without a scheme, path, or port. Save the client API address separately in the console as described in the next section.
touch deploy/https.enabled
./deploy/stack.sh up --source
./deploy/stack.sh statusThe marker makes stack.sh merge Caddy and enabled monitoring and updater settings. This command retains the guide’s source deployment mode. For a pinned-image installation only adding HTTPS, use ./deploy/stack.sh start. Caddy obtains and renews certificates; up --wait does not verify public certificates, so check HTTPS next.
curl -fsS https://api.example.com/health/ready
curl -fsS -o /dev/null https://api.example.com/loginReplace the domain and allow time for certificate issuance. Verify the login page from an external network. Direct Compose commands still require explicit HTTPS and other enabled overlays.
- If 1Panel, Nginx, or another HTTPS entry point exists, reuse it instead of starting Caddy. A host proxy can forward to 127.0.0.1:18080. Inside a container, 127.0.0.1 refers to that container, so plan connectivity separately.
- Preserve streaming response delivery and set the proxy read timeout at least as high as BOS_GATEWAY_TIMEOUT_SECONDS (300 seconds by default).
Step 5: save the actual API address
Once the chosen Nginx, Caddy, or other entry point is available, sign in as the super administrator and save the address clients can actually reach in Settings > API Address, for example https://api.example.com. This setting persists in the current database. Check existing instances for an old domain or test-environment address.
curl -fsS http://127.0.0.1:18080/api/v1/platform/config
curl -fsS https://api.example.com/api/v1/platform/configSubstitute the actual domain, protocol, and backend port. Both responses should have data.gateway_endpoint equal to the saved address; it is empty for a new database before configuration.
- The frontend reads this address through /api/v1/platform/config. Documentation and client examples derive their /v1 base URL from it and show YOUR_API_ADDRESS while unconfigured. VITE_GATEWAY_URL, BOS_PRIMARY_DOMAIN, and Caddy’s BOS_INSTALL_DOMAIN do not replace this console setting.
- The SSH tunnel address 127.0.0.1:18080 only suits local clients on the same workstation using that tunnel. For remote users, save the public or private-network entry point they can reach. The container address app:8081 is unsuitable for ordinary external clients.
Common settings & build networking
| Field | Purpose |
|---|---|
| BOSAPI_PORT | Application host port, default 18080, with its binding controlled by BOSAPI_BIND_IP. Does not change the fixed MySQL mapping at 13306. |
| BOSAPI_BIND_IP | Defaults to 127.0.0.1. The --local --public installer saves 0.0.0.0 for direct access without Nginx; later Compose and update commands reuse it. Public access also requires the selected TCP port through the security group and host firewall. |
| BOS_WEB_DELIVERY | Defaults to nginx for static files served by Nginx. go serves the frontend through the app and skips static publication. up --source retains the existing mode. |
| BOS_WEB_ROOT | Defaults to /var/www/bosapi for static publication. When customizing it, update both static roots in the Nginx configuration. |
| BOS_GATEWAY_TIMEOUT_SECONDS | Upstream timeout, default 300, in positive integer seconds. Adjust proxy timeouts accordingly. |
| BOS_MAX_REQUEST_BODY_MB | Request body size setting, default 128 in Compose. Align the public proxy’s body-size limit. |
| BOS_GEMINI_OAUTH_CLIENT_ID / BOS_GEMINI_OAUTH_CLIENT_SECRET | Optional Gemini CLI / Code Assist client override. Leave both empty for built-in defaults; set both when overriding. |
| BOS_ANTIGRAVITY_OAUTH_CLIENT_ID / BOS_ANTIGRAVITY_OAUTH_CLIENT_SECRET | Optional Antigravity client override, independent of Gemini. Leave both empty for built-in defaults; an incomplete pair is rejected. |
| BOS_MYSQL_IMAGE / BOS_REDIS_IMAGE | Data-service image sources; retain versions compatible with the project. |
| BOS_BASE_IMAGE_REGISTRY / BOS_GOPROXY | Base-image prefix and Go module proxy for application builds. Rebuild after changes. |
BOS_MYSQL_IMAGE=mysql:8.4
BOS_REDIS_IMAGE=redis:7.4-alpine
BOS_BASE_IMAGE_REGISTRY=docker.io/library
BOS_GOPROXY=https://proxy.golang.orgUse these sources when reachable from the server. Omit https:// from BOS_BASE_IMAGE_REGISTRY. Retain other fields and existing passwords when changing build-network settings.
- The Compose file defaults include image mirrors and goproxy.cn. Select reachable sources in stack.env when needed; changing addresses does not guarantee faster downloads.
- Shell environment variables can override --env-file values. Check the current shell when settings differ from expectations. Avoid publicly printing resolved docker compose config, which includes service passwords.
Apply subscription OAuth settings
Gemini CLI and Antigravity have built-in default clients, so normal deployments need no overrides. For a compatible custom client, set the complete pair in the existing private deploy/stack.env while retaining passwords and encryption keys. Deploy the updated backend and Compose definition first; for environment-only changes, run the command below to recreate affected containers using existing images. A plain container restart does not inject new variables; the stack does not read backend/.env.example.
./deploy/stack.sh startRoutine operations & applying settings
Use stack.sh for routine operations. It loads enabled HTTPS, monitoring, and updater overlays and publishes the frontend in Nginx mode. Direct Compose commands with explicit configuration can inspect component logs.
docker compose --env-file deploy/stack.env \
-f deploy/docker-compose.yml ps
docker compose --env-file deploy/stack.env \
-f deploy/docker-compose.yml logs -f app mysql redisPress Ctrl+C to stop following logs; services keep running.
./deploy/stack.sh down./deploy/stack.sh startrestart does not load new environment variables. start does not build new code. Use ./deploy/stack.sh up --source after source, Dockerfile, or build-argument changes.
./deploy/stack.sh status
./deploy/stack.sh logsThe script uses the same Compose file and private configuration. deploy/https.enabled automatically adds the Caddy overlay. Direct Compose commands still need enabled overlays added explicitly.
Persistence, backups & recovery
| Object | Default location |
|---|---|
| Private configuration | deploy/stack.env in the deployment directory, including the original encryption key required for recovery. Pinned-image deployments also retain deploy/image.env. |
| MySQL data & migration history | bosapi-stack_mysql_data → /var/lib/mysql. |
| Redis data | bosapi-stack_redis_data → /data. |
| Gateway data | bosapi-stack_gateway_data → /app/data. |
| HTTPS (optional) | deploy/https.enabled, Caddyfile, and bosapi-stack_caddy_data / bosapi-stack_caddy_config. |
- The table lists default named volumes. Back up actual volumes or paths if mounts are customized. down retains volumes; down -v, volume deletion, or clearing mounted directories removes data.
- Pause writes in a maintenance window and use a consistent database backup, or stop the stack before backing up data volumes. Do not copy a live MySQL data directory.
- Keep an off-host backup of private configuration, data, source revision, a recoverable app image, and proxy/certificate settings. Verify restoration; recording an image ID alone does not retain the image.
- On a new host, prepare matching source/images, restore the original configuration, keys, and all data to the correct mounts, then start and verify. Do not attach fresh keys to an existing database.
Upgrades & rollback boundaries
Once the source is ready, updates use the same ./deploy/stack.sh up --source command as initial deployment. Existing configuration is reused; no separate init, static-root creation, or Nginx installation is needed again. The script does not fetch source. First review working-tree changes, the target release, migration compatibility, and a verified backup with a recoverable old image.
git status --short
git rev-parse HEAD
git fetch --tags origin
git show --no-patch --oneline APPROVED_TAG_OR_COMMIT
git switch --detach APPROVED_TAG_OR_COMMITReview git show output and local modifications before switching. Preserve local changes; avoid forced checkout, reset, or overwriting configuration.
./deploy/stack.sh up --source
./deploy/stack.sh status
curl -fsS http://127.0.0.1:18080/health/readyRetain original keys, frontend mode, mounts, and enabled markers. Nginx mode publishes the frontend automatically. Recheck HTTPS on the actual domain, static assets, login, inference, and usage. Rebuild deployment can briefly interrupt service.
- Migrations are embedded in the app image, so SQL changes require rebuilding. Do not edit applied migrations or delete migration history to attempt rollback.
- Source/image mode is saved after backend readiness and before frontend publication. If only publication fails, the backend and saved mode may already have changed. Inspect status and current, fix the cause, and retry publish-web. Avoid deploying concurrently with a background image update.
- Reverting the image does not reverse database changes. Check old-app compatibility with the current schema, or restore a coordinated backup.
Troubleshooting & references
| Symptom | What to check |
|---|---|
| Missing variables or stack.env | up --source initializes when needed after Docker and static-root checks pass. Resolve preflight errors first. Restore original configuration for existing data. Direct Compose commands require --env-file and -f. |
| Script requests a static root or Python | nginx requires Python 3.9+. up creates a missing root, using sudo when its parent is not writable; it preserves existing permissions. start and publish-web only validate an existing root. To skip publication, use optional init and set BOS_WEB_DELIVERY=go; check shell overrides. |
| The old image still runs after uploading source | Check ./deploy/stack.sh status and deploy/image.env. A plain up neither pulls nor builds when an image is pinned. Use up --source for source updates or up --image with the intended reference for image updates. |
| Client examples lack an address or show an old domain | Save the actual endpoint in Settings > API Address and check gateway_endpoint in /api/v1/platform/config. Changing BOS_PRIMARY_DOMAIN does not update this setting. |
| Image pulls or source builds fail | Inspect network access, dependency sources, build memory, and disk. Fix the reported error and retry while retaining keys and volumes. |
| Port conflict or unhealthy containers | Check ports 18080, 13306, and HTTPS ports 80 / 443. Inspect ps and service logs. BOSAPI_PORT does not change MySQL’s port. |
| Migration or decryption failure | Verify the original stack.env, encryption key, data mounts, and release. Preserve the failure state and follow migration recovery instructions without regenerating configuration. |
| OAuth callback is unreachable | Default Compose binds the callback to 127.0.0.1:1455 inside the container without publishing it on the host. Ordinary Nginx/Caddy API proxying and app health checks do not verify this flow. Review the application repository’s current limitations. |
Match capabilities and procedures to your deployment version. Read the documentation scope