Deployment¶

Local development¶

Use the helper script:

bash run_local.sh

This starts MongoDB and Redis with Docker and runs the API locally with .env.dev.

Build the application image¶

bash build.sh

You can optionally pass an image name and push flag:

bash build.sh my-registry/xolo-api:0.1.0a0 1

Full Docker deployment¶

The repository includes a full stack docker-compose.yml.

Start it with:

./deploy.sh

The script:

1. loads deploy/env/compose.env
2. creates the Docker network if needed
3. runs docker compose up -d --build

Documentation deployment¶

The repository also includes a GitHub Pages workflow for the Zensical docs site:

• workflow file: .github/workflows/docs.yml
• build command: poetry run zensical build -f zensical.toml
• publish target: site/

Once GitHub Pages is enabled in the repository settings, pushes to the release branch build and publish the docs automatically.

Deployment files¶

Health model¶

The API container healthcheck requests:

/openapi.json

MongoDB and Redis are also configured with container healthchecks before the API service is considered ready.

Production checklist¶

• replace placeholder secrets
• review XOLO_JWT_SECRET
• review XOLO_LICENSE_SECRET_KEY
• set XOLO_SUPER_ADMIN_TOKENS
• configure mail provider credentials
• confirm MongoDB and Redis authentication posture
• verify the external port mapping
• put the API behind HTTPS and a reverse proxy if exposed publicly

Deploying with root_path¶

If deploying Xolo behind a reverse proxy that serves it at a non-root path (e.g., https://example.com/api/xolo/), configure FastAPI's root_path parameter:

# In server.py or your deployment configuration
app = FastAPI(
    root_path="/api/xolo",  # Match your reverse proxy path
    # ... other config
)

The admin UI and all routes automatically respect the root_path:

• Session cookies are scoped to the root path
• Template URLs are generated with the root path included
• All redirects and navigation work correctly

No additional admin UI configuration is needed—just set root_path and everything adapts automatically.