Docker Installation¶

Self Signed CA Certificate Support

By default Bambuddy uses the built in httpx library trust store for all HTTPS requests. If you have a standalone Home Assistant instance and are using a self signed CA certificate then access to this instance will be denied. To include your own CA certifcate add it to a directory and add the following to your docker compose file:

volume:
  - /path/to/your/ca-cert-dir:/usr/local/share/ca-certificates:ro
environment:
  - USE_SYSTEM_TRUST_STORE=true

When the USE_SYSTEM_TRUST_STORE environment variable is defined Bambuddy will update the CA Certifcates at boot up and enable the httpx library to use the System Trust Store. USE_SYSTEM_TRUST_STORE only takes effect when the container starts as root; remove any explicit user: directive if you set this flag.

Embedding Bambuddy in Home Assistant's Webpage panel

By default, Bambuddy emits strict iframe-blocking headers (X-Frame-Options: SAMEORIGIN and CSP frame-ancestors 'none') to protect against clickjacking on internet-exposed deployments. This blocks embedding Bambuddy inside Home Assistant's Webpage dashboard panel even on a trusted LAN, because HA on port 8123 and Bambuddy on port 8000 are different origins to the browser.

To allow embedding from your HA instance, set:

environment:
  - TRUSTED_FRAME_ORIGINS=http://homeassistant.local:8123

Replace the URL with your actual HA origin (scheme://host[:port] only — no paths, no wildcards). Multiple origins can be comma-separated. When set, X-Frame-Options is removed and the CSP frame-ancestors directive lists 'self' plus your configured origins. Plain Docker / bare-metal deployments without this variable retain the strict default.

HTTPS Home Assistant (Nabu Casa, custom domain, anything with TLS in front): browsers refuse to embed an HTTP iframe inside an HTTPS page (mixed-content block — Chrome and Firefox enforce this and the user can't override it for individual sites). If your HA instance is HTTPS, Bambuddy must also be reachable over HTTPS.

The simplest recipe for HA users is the Nginx Proxy Manager addon from the HA addon store. NPM does DNS-01 Let's Encrypt against your own domain, so no port-forwarding is required and Bambuddy never has to be exposed publicly:

1. Install and start the Nginx Proxy Manager addon from the HA addon store.
2. In NPM, add a Proxy Host: domain bambuddy.<your-domain>, scheme http, forward host <bambuddy-host-on-LAN>, forward port 8000.
3. Under SSL, request a Let's Encrypt cert via DNS Challenge for bambuddy.<your-domain> — NPM has dropdowns for Cloudflare, Hetzner, Route53, and many other DNS providers.
4. Set TRUSTED_FRAME_ORIGINS=https://homeassistant.<your-domain> (or whatever your HA HTTPS origin is) on Bambuddy and restart.
5. In HA, add a Webpage dashboard panel with url: https://bambuddy.<your-domain>.

Both ends are HTTPS, the certificate is publicly trusted, and Bambuddy stays on the LAN — DNS-01 only needs API access to your DNS provider, not inbound connectivity. If you don't have a domain, any other reverse proxy works the same way (Caddy, Traefik, plain nginx outside the addon ecosystem) — the only requirement is that Bambuddy ends up behind a trusted HTTPS certificate that matches the URL you embed in the Webpage panel.

Path-prefixed reverse proxies (e.g. https://example.com/bambuddy/ via Traefik path prefix, nginx location /bambuddy/, Cloudflare Tunnel with path routing) are supported as of v0.2.4b2 — assets load correctly under any subpath. API calls still go to the host root, so the proxy must route /api/v1/* to the same Bambuddy upstream as /bambuddy/* (most users either reverse-proxy Bambuddy at a dedicated subdomain or expose /api/v1/ at the host root alongside the subpath).

External PostgreSQL Database

By default, Bambuddy uses a built-in SQLite database that requires zero configuration. For larger setups or when you prefer a dedicated database server, set DATABASE_URL to point to an external PostgreSQL instance:

environment:
  - DATABASE_URL=postgresql+asyncpg://bambuddy:yourpassword@db-host:5432/bambuddy

Bambuddy will automatically create all tables on first startup. Backup/restore uses pg_dump/pg_restore instead of file copy.

Backup

To backup your data, simply copy these files/directories. See Backup & Restore for the built-in backup feature.

Stale docker-compose.yml?

Releases since 0.2.2 added cap_add: NET_BIND_SERVICE, extra virtual-printer ports for bridge mode (2024-2026), and an optional PostgreSQL block. If your compose file is older, bridge-mode users (macOS/Windows) may silently lose FTP and RTSP proxies. Compare yours against the current file and merge by hand.

Host mode not an option? Bridge works too

Host mode is the default because SSDP printer discovery needs L2 multicast — but it's a deliberate trade-off, not a one-size-fits-all default. If you run Bambuddy on a multi-service Linux host (NAS, dedicated Docker VM, Synology DSM, Unraid) where another container already binds a port Bambuddy wants, host mode isn't an option for you. Bridge mode is a fully supported alternative for setups that add printers by IP and skip discovery — read the Bridge Mode section below for the port-exposure rules. Both Linux multi-service hosts and Docker Desktop (macOS / Windows) follow the same configuration there.

PASV Address

Bridge mode hides the host's real IP from the FTP server inside the container. Set VIRTUAL_PRINTER_PASV_ADDRESS (commented in the snippet above) to your Docker host's LAN IP so the FTP server tells slicers the right address for the passive data connection.

Finding Your Subnet

Your subnet is typically your IP address with the last number replaced by 0/24. For example:

• If your computer's IP is 192.168.1.50, use 192.168.1.0/24
• If your computer's IP is 10.0.0.25, use 10.0.0.0/24