Deploy with Docker Compose

Build BOS API from source and manage private configuration, the app, MySQL, Redis, HTTPS, and routine operations.

Installation & operations guideUpdated Oct 28, 2026

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.

ItemRequirement
DockerDocker Engine, Compose v2 with up --wait support, and Buildx. Use a local Docker daemon accessible through docker info.
CLI toolsGit, Bash, OpenSSL, and curl. Run commands as root or a deployment user with Docker access, consistently using the same user and Docker daemon.
Static frontendDefault Nginx mode requires host Nginx, Python 3.9+, and a static root writable by the deployment user and readable by Nginx.
Network & resourcesAllow 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 portsThe 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.
Check the deployment environment
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.

Clone the application source
git clone https://github.com/secure-typex/bos-api.git bos-api
cd bos-api
git rev-parse HEAD

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

Optional: prepare the Nginx static root manually
sudo install -d -o "$(id -un)" -g "$(id -gn)" -m 0755 /var/www/bosapi

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

Optional: generate configuration for editing before startup
./deploy/stack.sh init

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

Optional: edit these fields in deploy/stack.env
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/Shanghai

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

CommandBuild and update behavior
./deploy/stack.sh up --sourceBuilds 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_REFERENCEReplace 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 upReuses 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 startStarts with the existing mode and local images without building source or fetching a newer application image.
Use for initial deployment and source updates
./deploy/stack.sh up --source
Inspect container status
./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.

Check services on the server
curl -fsS http://127.0.0.1:18080/health/ready
curl -fsS -o /dev/null http://127.0.0.1:18080/login
Open an SSH tunnel from your workstation
ssh -N -L 18080:127.0.0.1:18080 deploy-user@server.example.com

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

Install the supplied configuration snippets
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.

Example HTTP site
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.

Validate, reload, and verify the actual entry point
sudo nginx -t && sudo systemctl reload nginx
curl -fsS https://bosapi.example.com/health/ready
curl -fsS -o /dev/null https://bosapi.example.com/login

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

Add or edit fields in the original deploy/stack.env
BOS_WEB_DELIVERY=go
BOS_INSTALL_DOMAIN=api.example.com

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

Enable the HTTPS overlay and start through the management script
touch deploy/https.enabled
./deploy/stack.sh up --source
./deploy/stack.sh status

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

Verify public access
curl -fsS https://api.example.com/health/ready
curl -fsS -o /dev/null https://api.example.com/login

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

Check backend and public configuration after saving
curl -fsS http://127.0.0.1:18080/api/v1/platform/config
curl -fsS https://api.example.com/api/v1/platform/config

Substitute 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

FieldPurpose
BOSAPI_PORTApplication host port, default 18080, with its binding controlled by BOSAPI_BIND_IP. Does not change the fixed MySQL mapping at 13306.
BOSAPI_BIND_IPDefaults 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_DELIVERYDefaults 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_ROOTDefaults to /var/www/bosapi for static publication. When customizing it, update both static roots in the Nginx configuration.
BOS_GATEWAY_TIMEOUT_SECONDSUpstream timeout, default 300, in positive integer seconds. Adjust proxy timeouts accordingly.
BOS_MAX_REQUEST_BODY_MBRequest body size setting, default 128 in Compose. Align the public proxy’s body-size limit.
BOS_GEMINI_OAUTH_CLIENT_ID / BOS_GEMINI_OAUTH_CLIENT_SECRETOptional 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_SECRETOptional Antigravity client override, independent of Gemini. Leave both empty for built-in defaults; an incomplete pair is rejected.
BOS_MYSQL_IMAGE / BOS_REDIS_IMAGEData-service image sources; retain versions compatible with the project.
BOS_BASE_IMAGE_REGISTRY / BOS_GOPROXYBase-image prefix and Go module proxy for application builds. Rebuild after changes.
Optional: select official images and a Go proxy in stack.env
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.org

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

Apply environment changes from the application deployment directory
./deploy/stack.sh start

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

Inspect status and 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 redis

Press Ctrl+C to stop following logs; services keep running.

Stop services and retain volumes
./deploy/stack.sh down
Start with existing images or apply runtime settings
./deploy/stack.sh start

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

Inspect app status and logs
./deploy/stack.sh status
./deploy/stack.sh logs

The 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

ObjectDefault location
Private configurationdeploy/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 historybosapi-stack_mysql_data → /var/lib/mysql.
Redis databosapi-stack_redis_data → /data.
Gateway databosapi-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.

Inspect and select the target source revision
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_COMMIT

Review git show output and local modifications before switching. Preserve local changes; avoid forced checkout, reset, or overwriting configuration.

Rebuild and start with preserved configuration and data
./deploy/stack.sh up --source
./deploy/stack.sh status
curl -fsS http://127.0.0.1:18080/health/ready

Retain 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

SymptomWhat to check
Missing variables or stack.envup --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 Pythonnginx 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 sourceCheck ./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 domainSave 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 failInspect network access, dependency sources, build memory, and disk. Fix the reported error and retry while retaining keys and volumes.
Port conflict or unhealthy containersCheck ports 18080, 13306, and HTTPS ports 80 / 443. Inspect ps and service logs. BOSAPI_PORT does not change MySQL’s port.
Migration or decryption failureVerify 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 unreachableDefault 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

BOS API · TYPEX

Sales consultation is unavailable

Sales reception could not be initialized. Please try again later. Documentation and free self-hosting remain available.

Read the docsSelf-host for free