Local development setup
Run the Go backend and Vite frontend locally with dedicated MySQL and Redis services, then verify login, debugging, and builds.
Prerequisites
Use this guide to edit and debug BOS API locally. The Go backend and Vite frontend run on the host; Docker Compose supplies only development MySQL and Redis. Commands use Bash for macOS, Linux, or Windows WSL2 with the required tools.
| Item | Requirement |
|---|---|
| Go | Use Go 1.26.6 or a newer compatible version, as specified by backend/README.md. go.mod declares Go 1.26. |
| Node.js / pnpm | Node.js 22 and pnpm 9.15.9, matching the frontend build tools in the current Dockerfile. |
| Docker | A working local Docker daemon and Compose with up --wait support. You may use existing dedicated MySQL 8.4 / Redis 7.4 development services instead. |
| Other tools | Git, Bash, OpenSSL, and curl, plus access to source, image registries, npm/pnpm, and Go modules. |
go version
node --version
pnpm --version
docker info
docker compose version
openssl version- Use dedicated development data and credentials. Backend startup applies migrations automatically, so keep local development configuration separate from production data.
- Local ports: frontend 3000, backend 8081, OAuth callback 1455, MySQL 13307, and Redis 16380. Dependency containers bind only to loopback.
Step 1: get source and frontend dependencies
Clone the BOS API application repository and run subsequent steps from its root. boss-api-protal is the documentation website; run application startup commands in bos-api.
git clone https://github.com/secure-typex/bos-api.git bos-api
cd bos-api
git rev-parse HEADSkip cloning if you already have a checkout. Use existing Git authentication when needed, keeping tokens out of commands.
corepack enable
corepack prepare pnpm@9.15.9 --activateSkip if the matching pnpm version is available. If your distribution omits Corepack, install pnpm 9.15.9 through your package manager.
pnpm --dir frontend install --frozen-lockfileDependencies install locally using the repository lockfile. Check Node/pnpm versions and download sources if installation fails.
Step 2: generate and retain local configuration
Save the script below as .dev/init-env.sh inside the application repository (create .dev first), then run bash .dev/init-env.sh from the repository root. The same script is available below. It generates configuration without connecting to a database or starting services.
#!/usr/bin/env bash
# Run from the bos-api application repository root, not the website repository.
set -euo pipefail
umask 077
mkdir -p .dev
if [[ -e .dev/backend.env ]]; then
printf 'Keep the existing .dev/backend.env and encryption key. Configuration was not replaced.\n' >&2
exit 1
fi
mysql_password=$(openssl rand -hex 24)
mysql_root_password=$(openssl rand -hex 24)
redis_password=$(openssl rand -hex 24)
encryption_key=$(openssl rand -base64 32)
jwt_key=$(openssl rand -hex 32)
admin_password=$(openssl rand -hex 24)
cat > .dev/backend.env <<ENV
MYSQL_DATABASE=bosapi_dev
MYSQL_USER=bosapi_dev
MYSQL_PASSWORD=$mysql_password
MYSQL_ROOT_PASSWORD=$mysql_root_password
REDIS_PASSWORD=$redis_password
BOS_LISTEN=127.0.0.1:8081
BOS_CALLBACK_LISTEN=127.0.0.1:1455
BOS_DATA_FILE=../.dev/gateway.enc
BOS_ENCRYPTION_KEY=$encryption_key
BOS_DATABASE_DSN='bosapi_dev:$mysql_password@tcp(127.0.0.1:13307)/bosapi_dev?charset=utf8mb4&parseTime=true&loc=UTC'
BOS_REDIS_URL=redis://:$redis_password@127.0.0.1:16380/0
BOS_JWT_SIGNING_KEY=$jwt_key
BOS_ADMIN_EMAIL=admin@bosapi.local
BOS_ADMIN_PASSWORD=$admin_password
BOS_WEB_DIR=
BOS_MAX_REQUEST_BODY_MB=128
BOS_GATEWAY_TIMEOUT_SECONDS=300
BOS_USAGE_REPORTING_FORCE_DISABLED=true
TZ=Asia/Shanghai
ENV
chmod 600 .dev/backend.env
printf 'Created .dev/backend.env (mode 600). Read initial administrator credentials privately from this file.\n'
The generated .dev/backend.env is a private mode-600 file with independent random passwords and keys. Rerunning refuses to overwrite it; retain the file and original encryption key.
- The generated backend.env supports both Compose dotenv and shell assignments. Load only this self-generated, controlled file using the dot command below; do not execute production stack.env as shell code.
- BOS_DATA_FILE=../.dev/gateway.enc assumes the backend working directory. Adjust the path if you change directories, retaining data and the original key.
- The current application repository ignores .dev/. Check git status to keep private configuration, runtime data, and passwords out of commits.
Step 3: start development data services
Save the following as .dev/compose.yml in the application repository. It uses project name bosapi-local-dev, dedicated named volumes, and host ports 13307 / 16380, separate from production bosapi-stack data.
name: bosapi-local-dev
services:
mysql:
image: mysql:8.4
ports:
- "127.0.0.1:13307:3306"
environment:
MYSQL_DATABASE: ${MYSQL_DATABASE:?Generate .dev/backend.env first}
MYSQL_USER: ${MYSQL_USER:?Generate .dev/backend.env first}
MYSQL_PASSWORD: ${MYSQL_PASSWORD:?Generate .dev/backend.env first}
MYSQL_ROOT_PASSWORD: ${MYSQL_ROOT_PASSWORD:?Generate .dev/backend.env first}
TZ: Asia/Shanghai
command:
- --character-set-server=utf8mb4
- --collation-server=utf8mb4_0900_ai_ci
volumes:
- mysql_data:/var/lib/mysql
healthcheck:
test: ["CMD-SHELL", "MYSQL_PWD=\"$${MYSQL_PASSWORD}\" mysql -h 127.0.0.1 -u \"$${MYSQL_USER}\" -D \"$${MYSQL_DATABASE}\" -Nse 'SELECT 1' >/dev/null 2>&1"]
interval: 10s
timeout: 5s
retries: 20
start_period: 60s
redis:
image: redis:7.4-alpine
ports:
- "127.0.0.1:16380:6379"
environment:
REDIS_PASSWORD: ${REDIS_PASSWORD:?Generate .dev/backend.env first}
command: ["redis-server", "--appendonly", "yes", "--requirepass", "${REDIS_PASSWORD:?Generate .dev/backend.env first}"]
volumes:
- redis_data:/data
healthcheck:
test: ["CMD-SHELL", "REDISCLI_AUTH=\"$${REDIS_PASSWORD}\" redis-cli ping | grep -q PONG"]
interval: 10s
timeout: 3s
retries: 10
volumes:
mysql_data:
redis_data:
docker compose --env-file .dev/backend.env -f .dev/compose.yml config --quiet
docker compose --env-file .dev/backend.env -f .dev/compose.yml up -d --wait
docker compose --env-file .dev/backend.env -f .dev/compose.yml psAllow time for first image pulls and MySQL initialization. Continue when both services are healthy.
- The Go process runs on the host. Use 127.0.0.1 with published ports for MySQL and Redis, rather than container addresses mysql:3306 or redis:6379.
- If you use existing local services, skip this Compose file and update BOS_DATABASE_DSN and BOS_REDIS_URL, while retaining the complete administration database and JWT configuration.
Step 4: start the Go backend
Terminal A: load the generated private variables from the application root, then run from backend. The backend reads process environment variables; it does not automatically load backend/.env or .dev/backend.env.
set -a
. ./.dev/backend.env
set +a
cd backend
go mod download
go run .Keep this terminal running. The backend listens at http://127.0.0.1:8081 and uses 127.0.0.1:1455 for OAuth callbacks. The browser frontend starts separately.
- Startup applies pending SQL migrations. A new database creates the initial super administrator from BOS_ADMIN_EMAIL / BOS_ADMIN_PASSWORD. Environment variables do not reset existing administrator passwords.
- The initial random password is stored in .dev/backend.env; read it privately on your machine. Keep full environment dumps and credential screenshots out of chats and tickets.
- Some gateway features can run without a database, but that does not verify complete portal login, organization, key, and usage workflows. This guide keeps MySQL and JWT configured.
Step 5: start the Vite frontend
Terminal B: open the application repository root in a new terminal and run the command below. Set VITE_BACKEND_URL explicitly because the current Vite configuration defaults to a remote test service.
cd frontend
VITE_BACKEND_URL=http://127.0.0.1:8081 \
VITE_API_BASE_URL=/api/v1 \
pnpm run dev --host 127.0.0.1 --port 3000 --strictPortOpen http://127.0.0.1:3000/login. --strictPort fails if port 3000 is occupied instead of silently selecting another port.
- Vite proxies /api, /v1, /images, and /health to local port 8081. Keep the frontend API base at /api/v1 so administration requests use the same-origin proxy.
- The current frontend reads the saved API address from /api/v1/platform/config and no longer falls back to VITE_GATEWAY_URL or BOS_PRIMARY_DOMAIN. After first login, save the local endpoint in Settings > API Address as described below.
- You may store Vite variables in frontend/.env.local without overwriting existing local settings. Restart Vite after changing variables or proxy configuration, and restart Go after changing its environment.
- The frontend supports hot updates. Plain go run does not restart the backend automatically; stop with Ctrl+C and rerun go run . after editing Go code.
Step 6: verify login and local requests
curl -fsS http://127.0.0.1:8081/health/ready
curl -fsS http://127.0.0.1:3000/health/ready
curl -fsS -o /dev/null http://127.0.0.1:3000/logincurl -fsS http://127.0.0.1:8081/api/v1/platform/config
curl -fsS http://127.0.0.1:3000/api/v1/platform/configSave the API address as described below first. Both responses should have data.gateway_endpoint equal to http://127.0.0.1:8081. An empty value is normal for a new database before configuration.
- Both readiness responses should have data.status equal to ok. This checks the database connection; verify Redis through its container and actual features. The development login page comes from port 3000. Without BOS_WEB_DIR, Go does not serve the complete frontend at 8081/login.
- Sign in with the initial account in .dev/backend.env and enroll MFA. In browser network tools, confirm requests use /api/v1 on port 3000 and are handled by the local backend.
- As the super administrator, open Settings > API Address, save http://127.0.0.1:8081, then run the configuration checks above. Documentation and client examples derive their /v1 base URL from this address and show YOUR_API_ADDRESS while unconfigured. The setting persists in the current database across restarts. Check existing development databases for a previously saved remote address.
- To verify inference, configure upstream accounts or API keys you are authorized to use, channels, and models; create an organization, assign models, and create its gateway key. Local setup supplies no model credits.
- Verify an authorized request, response, and record, then test relevant access and error cases. A visible UI or passing health check alone is not full business validation.
Optional: build and serve the frontend through Go
To verify built assets, stop the Go process in terminal A and run the commands below from the repository root. BOS_WEB_DIR must be an absolute directory containing index.html.
VITE_API_BASE_URL=/api/v1 pnpm --dir frontend run build
set -a
. ./.dev/backend.env
set +a
export BOS_WEB_DIR="$(pwd)/frontend/dist"
cd backend
go run .Open http://127.0.0.1:8081/login. Vite is unnecessary in this mode; rebuild after frontend edits. Reload backend.env to clear BOS_WEB_DIR when returning to two-process development.
- The repository also provides make build, make run, make dev-backend, and make dev-frontend. These still require installed frontend dependencies, loaded backend variables, and an explicit local Vite proxy target.
Stopping, restarting & retaining development data
Stop Go and Vite with Ctrl+C in their terminals first. The commands below manage only the dedicated local MySQL / Redis project, separate from bosapi-stack.
docker compose --env-file .dev/backend.env -f .dev/compose.yml logs -f mysql redisdocker compose --env-file .dev/backend.env -f .dev/compose.yml downdocker compose --env-file .dev/backend.env -f .dev/compose.yml up -d --wait- Retain .dev/backend.env, .dev/gateway.enc, bosapi-local-dev_mysql_data, and bosapi-local-dev_redis_data. Back up the original encryption key with the data.
- down retains volumes. down -v or volume deletion removes the development database and cache; avoid using these as routine fixes for login or migration errors.
- After opening a new terminal, reload the original backend.env from the repository root before running from backend. Do not generate a new BOS_ENCRYPTION_KEY on every startup.
Troubleshooting & references
| Symptom | What to check |
|---|---|
| Encryption-key or JWT validation fails | Load the original private file with set -a. The encryption key must decode to 32 bytes; database mode requires a JWT key of at least 32 bytes. |
| Frontend requests reach a remote service | Set VITE_BACKEND_URL=http://127.0.0.1:8081, keep VITE_API_BASE_URL=/api/v1, and restart Vite. |
| Client examples show YOUR_API_ADDRESS or a remote address | As the super administrator, save http://127.0.0.1:8081 in Settings > API Address and check gateway_endpoint in /api/v1/platform/config. VITE_GATEWAY_URL and BOS_PRIMARY_DOMAIN no longer supply fallback addresses. |
| Dependencies fail or database access is denied | Check health status, port mappings 13307 / 16380, DSN, and passwords. Editing bootstrap variables does not change passwords in an existing MySQL volume. |
| Port 8081 or 1455 is occupied | Stop the old process occupying the port normally. If changing BOS_LISTEN, update the frontend proxy, saved API address, and verification URLs. OAuth currently redirects to the fixed http://localhost:1455/auth/callback address. Retain port 1455 for OAuth; changing BOS_CALLBACK_LISTEN alone does not update that redirect. |
| Login fails or administration APIs are unavailable | Load BOS_DATABASE_DSN, BOS_JWT_SIGNING_KEY, and bootstrap credentials and check migration success. BOS_ADMIN_PASSWORD does not reset an existing account. |
| Backend login page returns 404 | Use 3000/login during development. Go serves the complete frontend only after a frontend build and BOS_WEB_DIR configuration. |
| Go or pnpm installation/build fails | Check project tool versions, lockfiles, network, and disk. Go edits require a restart; static asset changes require rebuilding. |
Match capabilities and procedures to your deployment version. Read the documentation scope