Installation#

Self Hosted

BrewGraph runs as a set of Docker containers orchestrated with Docker Compose. The only hard requirements are Docker and Docker Compose (v2).

Warning

BrewGraph is designed for trusted LAN deployment only. It has no built-in login — anyone who can reach the server over the network can access its data.

Do not expose BrewGraph directly to the public internet. If remote access is required, place it behind a VPN (e.g. WireGuard or Tailscale) or a reverse proxy that enforces its own authentication layer.

Prerequisites#

  • Docker Engine 24+ and Docker Compose v2

  • A Linux, macOS, or Windows (WSL2) host

  • For BLE ingestion: a Linux host with Bluetooth hardware and BlueZ installed

  • For mDNS discovery: network_mode: host support (Linux preferred)

Quick start — pre-built images#

This is the recommended path for most users. Pre-built images are published to Docker Hub under mpse2/brewgraph-* and require no local build step.

  1. Download the compose file:

    curl -o docker-compose.yaml https://raw.githubusercontent.com/mp-se/brewgraph/main/docker-compose.example.yaml

  2. Create a .env file with your secrets — the compose file refuses to start without them:

    cat <<'EOF' > .env
API_KEY=change-me-to-a-strong-secret
POSTGRES_PASSWORD=change-me-to-a-strong-secret
EOF

    If you’ll use mDNS discovery or BLE ingestion, also set WEBSERVER_IP to your host’s own LAN IP address — the brewgraph-mdns and brewgraph-ble sidecars need it to reach the API, and the compose file refuses to start them without it:

    echo "WEBSERVER_IP=192.0.2.10" >> .env

  3. Start the core services:

    docker compose up -d

  4. The web UI is now available at http://localhost:80. The API is proxied through Nginx at http://localhost:80/api.

Note

The interactive API docs (/docs) are blocked at the Nginx proxy. During development run make run in api/ to start the API directly on port 8080 where /docs is accessible.

Quick start — build from source#

Use this path if you want to modify the code or run the latest unreleased version.

  1. Clone the repository:

    git clone https://github.com/mp-se/brewgraph.git
cd brewgraph
cp docker-compose.example.yaml docker-compose.yaml

  2. Create a .env file with your secrets — the compose file refuses to start without them:

    cat <<'EOF' > .env
API_KEY=change-me-to-a-strong-secret
POSTGRES_PASSWORD=change-me-to-a-strong-secret
EOF

    If you’ll use mDNS discovery or BLE ingestion, also set WEBSERVER_IP to your host’s own LAN IP address — the brewgraph-mdns and brewgraph-ble sidecars need it to reach the API, and the compose file refuses to start them without it:

    echo "WEBSERVER_IP=192.0.2.10" >> .env

  3. Build and start:

    docker compose build
docker compose up -d

The docker-compose.yaml file#

The canonical Compose configuration is maintained with the Self Hosted application, not copied into these docs. Download or inspect the current docker-compose.example.yaml. It starts the web UI, API, PostgreSQL, Redis, device log collector, mDNS discovery, and BLE ingestion services. The named volumes preserve the database, Redis data, exports, and device logs across restarts.

The web UI is published on port 80. The API is also published as host port 8080, bound to 127.0.0.1 only — reachable from the host itself, but not exposing the raw, unproxied API (no Nginx, no TLS) to the rest of the network. brewgraph-mdns and brewgraph-ble run with network_mode: host and reach the API through Nginx instead, using API_HOST=${WEBSERVER_IP}:80; the web UI and log collector remain on the internal Compose network and use API_HOST=brewgraph-api.

Before deploying, set API_KEY, POSTGRES_PASSWORD, and — if you’re using mDNS or BLE — WEBSERVER_IP. The web/certs mount is commented out by default; enable it only when HTTPS certificates are available — see below.

Note

brewgraph-ble and brewgraph-mdns use network_mode: host and only work correctly on Linux. On macOS the containers start but cannot access LAN multicast or the host Bluetooth stack.

HTTPS (optional)#

To serve the web UI over HTTPS, place your certificate and key in web/certs/:

web/certs/cert.pem
web/certs/key.pem

The Nginx entrypoint script detects the presence of these files and switches to the HTTPS configuration automatically. No other changes are required.

Updating#

Pre-built images:

docker compose pull
docker compose up -d

Built from source:

git pull
docker compose build
docker compose up -d