How Shadowbroker Backend Services Are Deployed

Shadowbroker deploys its backend as a containerized FastAPI service using a multi-stage Docker build and Docker Compose orchestration, with automated health checks and persistent volume management.

The Shadowbroker project (BigBodyCobain/Shadowbroker) provides a containerized backend infrastructure built on FastAPI. Understanding how these backend services are deployed requires examining the build pipeline defined in backend/Dockerfile, the orchestration logic in docker-compose.yml, and the environment configuration templates that manage runtime secrets. This deployment architecture also supports Podman and Kubernetes via Helm charts according to the repository documentation.

Multi-Stage Container Build Process

The deployment begins with a multi-stage build defined in backend/Dockerfile. The first stage compiles the Rust privacy-core library into a shared object file, while the second stage constructs the Python runtime environment.

Key build characteristics include:

• Rust compilation: The initial stage builds the privacy-core Rust library and produces a .so file that backend/wormhole_server.py imports for high-performance operations.
• UV package management: The build uses UV (a fast Python resolver) with the uv.lock file to install exact dependency versions declared in backend/pyproject.toml.
• Security hardening: The final image runs as a non-root user backenduser (UID 1001) with write permissions restricted to /app.
• Entrypoint script: backend/docker-entrypoint.sh seeds static JSON data into the volume before launching Uvicorn to serve the FastAPI application.

Docker Compose Orchestration

The docker-compose.yml file defines the complete runtime environment, orchestrating the backend service alongside the frontend. According to the Shadowbroker source code, the configuration implements several production-ready patterns.

Service Dependencies and Health Checks

The backend service exposes port 8000 and includes a health check that periodically curls http://localhost:8000/api/health. The frontend service declares a dependency on the backend’s health status, ensuring it only starts after the health check succeeds.

Persistent Storage

A named Docker volume backend_data is mounted at /app/data inside the container. This ensures that JSON data files survive container restarts and updates.

Resource Constraints

Default resource limits are set to 4 GiB of memory and 2 CPU cores, though these values can be customized via environment variables.

Image Source

The compose file references pre-built images from GitHub Container Registry (ghcr.io/bigbodycobain/shadowbroker-backend:latest), though local builds are supported for development.

Environment Configuration and Secrets

Runtime configuration is managed through environment variables defined in backend/.env.example. When Docker Compose starts, variables are injected into the backend service using ${VAR:-default} placeholder syntax.

Required secrets include:

• OPENSKY_CLIENT_ID and OPENSKY_CLIENT_SECRET for aviation data APIs
• AIS_API_KEY for vessel tracking services
• MESH_PEER_PUSH_SECRET for mesh networking authentication

The backend binds to ${BIND:-127.0.0.1}:${BACKEND_PORT:-8000}:8000, defaulting to localhost-only access on port 8000.

Running the Deployment

To deploy the complete stack locally, clone the repository and use Docker Compose:

git clone https://github.com/bigbodycobain/Shadowbroker.git
cd Shadowbroker
cp backend/.env.example .env

# Edit .env to add your API keys

docker compose pull
docker compose up -d

Verify the backend health with:

curl -fs http://localhost:8000/api/health && echo "OK"

For testing or CI environments, run the backend container independently:

docker run --rm \
  -p 8000:8000 \
  -v $(pwd)/backend_data:/app/data \
  -e OPENSKY_CLIENT_ID=YOUR_ID \
  -e OPENSKY_CLIENT_SECRET=YOUR_SECRET \
  ghcr.io/bigbodycobain/shadowbroker-backend:latest

Summary

• Multi-stage builds: The backend/Dockerfile compiles Rust libraries before building the Python FastAPI application.
• Docker Compose orchestration: The docker-compose.yml manages service dependencies, health checks, and resource limits.
• Persistent storage: Named volumes ensure data survives container restarts at /app/data.
• Security: The container runs as non-root user backenduser (UID 1001) with secrets injected via .env files.
• FastAPI entry point: The backend/wormhole_server.py serves the application on port 8000 with a /api/health endpoint.

Frequently Asked Questions

Can I deploy Shadowbroker backend using Podman instead of Docker?

Yes, the containerized deployment is compatible with Podman. The docker-compose.yml syntax and rootless container configuration work with Podman Compose, as the project follows standard OCI container specifications without Docker-specific dependencies.

How do I update the backend to a new version without losing data?

Pull the latest image from GitHub Container Registry and recreate the container. The backend_data volume mounted at /app/data persists JSON data files across container restarts, so your data remains intact when you run docker compose pull followed by docker compose up -d.

What is the purpose of the Rust privacy-core library in the build process?

The Rust privacy-core library provides compiled cryptographic or privacy-preserving utilities that Python cannot efficiently handle natively. During the multi-stage build, the library compiles to a .so file that backend/wormhole_server.py imports, enabling high-performance privacy operations within the FastAPI application.

How do I troubleshoot if the backend fails to start?

Check the container logs with docker compose logs backend to verify environment variable loading from your .env file. Ensure the backend_data directory has correct permissions for UID 1001, and confirm that the health endpoint responds with curl http://localhost:8000/api/health before the frontend attempts to connect.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}