# How Shadowbroker Backend Services Are Deployed

> Discover how Shadowbroker deploys its backend services using containerized FastAPI, Docker, and Docker Compose for efficient orchestration and robust management.

- Repository: [Shadowbroker/Shadowbroker](https://github.com/BigBodyCobain/Shadowbroker)
- Tags: how-to-guide
- Published: 2026-05-07

---

**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](https://github.com/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`](https://github.com/BigBodyCobain/Shadowbroker/blob/main/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`](https://github.com/BigBodyCobain/Shadowbroker/blob/main/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`](https://github.com/BigBodyCobain/Shadowbroker/blob/main/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`](https://github.com/BigBodyCobain/Shadowbroker/blob/main/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`](https://github.com/BigBodyCobain/Shadowbroker/blob/main/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:

```bash
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:

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

```

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

```bash
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`](https://github.com/BigBodyCobain/Shadowbroker/blob/main/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`](https://github.com/BigBodyCobain/Shadowbroker/blob/main/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`](https://github.com/BigBodyCobain/Shadowbroker/blob/main/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`](https://github.com/BigBodyCobain/Shadowbroker/blob/main/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.