Installation¶

This guide covers installing BamDude manually. For Docker (recommended), see the Docker guide.

Requirements¶

Requirement	Details
Python	3.12+ (native install only — Docker and the Windows installer bring their own)
Network	Same LAN as your Bambu Lab printer
Printer	Developer Mode enabled (see guide)
SD Card	Inserted in the printer (required for file transfers)

Docker Alternative

If you prefer containers, check out the Docker installation guide -- it's even simpler!

Manual Install¶

Ubuntu/Debian macOS

# Install prerequisites
sudo apt update
sudo apt install python3 python3-venv python3-pip git

# Clone and setup
git clone https://github.com/kainpl/bamdude.git
cd bamdude
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

# Run
uvicorn backend.app.main:app --host 0.0.0.0 --port 8000

# Install prerequisites (if needed)
brew install [email protected]

# Clone and setup
git clone https://github.com/kainpl/bamdude.git
cd bamdude
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

# Run
uvicorn backend.app.main:app --host 0.0.0.0 --port 8000

Open http://localhost:8000 in your browser.

Windows (native installer)¶

Windows 10/11 has a self-contained .exe installer — no Docker, no WSL, and no separate Python or Node install. The setup bundles an embedded Python runtime and a static ffmpeg, lays everything down, and registers BamDude as a Windows Service that starts on boot.

Download the latest bamdude-<version>-windows-x64-setup.exe from the Releases page.
Run it (it needs Administrator rights — it registers a service and writes to ProgramData).
When it finishes, your browser opens http://localhost:8000.

That's it — the service is already running.

SmartScreen: the installer is not code-signed

Windows SmartScreen shows "Windows protected your PC" on first run — click More info → Run anyway. The upstream binaries bundled inside the installer (embedded Python, NSSM, ffmpeg) carry their own vendors' signatures or none. What the app sends out, and how to switch telemetry off: Privacy & Telemetry.

What the installer lays down¶

What	Where
Program files (embedded Python 3.12, backend + pre-built frontend, NSSM, ffmpeg)	`C:\Program Files\BamDude`
Your data (database, archives, plate calibration)	`C:\ProgramData\BamDude\data`
Logs	`C:\ProgramData\BamDude\logs`

The installer also adds Start-Menu shortcuts (Open BamDude Dashboard, BamDude Logs, Uninstall), an optional desktop shortcut, and — if you leave the box ticked — a Windows Firewall rule opening port 8000.

Your data survives uninstall + upgrade

Everything under C:\ProgramData\BamDude is left untouched on uninstall. Re-installing (or installing a newer build on top) picks the same database and archives back up automatically.

:material-service-toggle: The BamDude service¶

The installer registers a Windows Service named BamDude (supervised by NSSM) that runs as LocalSystem, starts automatically on boot, and serves the dashboard on http://localhost:8000. Manage it with the standard cmdlets:

Get-Service BamDude          # Check status
Start-Service BamDude        # Start
Stop-Service BamDude         # Stop
Restart-Service BamDude      # Restart

Updating¶

Download a newer bamdude-<version>-windows-x64-setup.exe and run it — it stops the service, overwrites the program files in place, and restarts. Your database, archives, and logs under C:\ProgramData\BamDude are preserved.

Then open http://localhost:8000.

Configuration¶

Configure BamDude using environment variables or a .env file:

cp .env.example .env
nano .env

Environment Variables¶

Core¶

Variable	Default	Description
`DEBUG`	`false`	Enable debug mode (verbose logging; in dev also re-runs the latest migration on every boot)
`LOG_LEVEL`	`INFO`	Log level: `DEBUG`, `INFO`, `WARNING`, `ERROR`
`LOG_TO_FILE`	`true`	Write logs to `logs/bamdude.log`
`DATA_DIR`	`<repo>/data`	Override the persistent-data directory (DB + archives + plate calibration)
`LOG_DIR`	`<repo>/logs`	Override the log directory
`PORT`	`8000`	Port the bundled `python -m backend.app.main` entrypoint binds to
`TZ`	system	Timezone string passed to Python (e.g. `Europe/Kyiv`)

Database¶

Variable	Default	Description
`DATABASE_URL`	unset (SQLite)	`embedded` for the bundled PostgreSQL 18, or a URL such as `postgresql+asyncpg://user:pass@host:5432/bamdude` for your own server. Empty means SQLite. See PostgreSQL Support.
`EMBEDDED_PG_PORT`	picked once, remembered	Pin the bundled server's port (e.g. `6432`) so `psql` or DBeaver can reach it.

The installer asks for you

install.sh offers SQLite, the bundled PostgreSQL, or an external server — interactively, or unattended with --db sqlite|embedded|external (plus --database-url for the last). Re-running over an existing install keeps the backend you already use.

Auth & reverse-proxy¶

Variable	Default	Description
`JWT_SECRET_KEY`	auto-generated and persisted under `data/`	Override the JWT signing key. Don't change this on a running install or every issued token will be invalidated.
`TRUSTED_PROXY_IPS`	empty	Comma-separated reverse-proxy IPs whose `X-Forwarded-For` is trusted (right-to-left resolution). Required behind nginx for accurate per-IP rate limiting.
`AUTH_REFRESH_COOKIE_SECURE`	unset (auto-detect)	Force `Secure` polarity on the refresh-token cookie. Auto-detect from the request scheme is the right default; set `true` to force, `false` to disable (LAN HTTP dev only).
`MFA_ENCRYPTION_KEY`	unset	URL-safe base64 Fernet key. When set, TOTP secrets and OIDC client secrets are encrypted at rest. Plaintext fallback works without it but logs a warning at boot.
`APP_URL`	`http://localhost:5173`	Public-facing base URL of BamDude. Used to build absolute links in password-reset / MFA-recovery emails, OIDC callback URL, and the Obico cached-frame URL the Obico ML API fetches back. The `external_url` setting under Settings → System overrides this when set.

Integrations (optional)¶

Variable	Description
`HA_URL`, `HA_TOKEN`	Home Assistant base URL + long-lived token. When both are set, HA integration is auto-enabled and the matching DB settings become read-only (env wins). Recommended for the HA Add-on; native installs can also enable HA via Settings → Integrations without env vars.
`VIRTUAL_PRINTER_PASV_ADDRESS`	Override the FTP-PASV address advertised by the virtual printer (set this if BamDude runs behind NAT and slicers can't reach the bind IP).

Container detection¶

Either of these env vars (any non-empty value) marks the runtime as a container, which adjusts SSDP discovery behaviour. Normally set automatically by the container runtime — only override if you're running native but want container-style discovery.

Variable	Description
`CONTAINER`	Generic container marker.
`DOCKER_CONTAINER`	Docker-specific marker.

Docker compose helpers (read by `docker-compose.yml`, not by BamDude itself)¶

Variable	Description
`PUID` / `PGID`	UID / GID the bamdude container runs as. Match these to the owner of your mounted volumes to avoid permission errors on archive writes. Get them with `id -u && id -g`.

First-Boot Setup¶

BamDude has authentication always on — there is no "no-auth" mode. On the very first start the API rejects every request with 503 {"detail": "setup_required"} until the initial admin user is created. The whitelist that bypasses the gate is exactly three routes (/api/v1/auth/status, /api/v1/auth/setup, /api/v1/system/health), so login and every other endpoint stay closed until setup completes.

Setup wizard (browser)¶

Open BamDude in a browser. The frontend reads /api/v1/auth/status, sees requires_setup=true, and renders the setup form:

Field	Required	Notes
Username	yes	Becomes the first admin. Max 150 chars.
Password	yes	Min 8 chars, must include at least one uppercase + one lowercase + one digit. No special-character rule — BamDude follows NIST SP 800-63B which explicitly advises against composition rules beyond length + a basic mix. Max 256 chars. Stored as a bcrypt hash.
Email	optional	Max 254 chars. Used for password-reset flows + email-OTP MFA later.

Submit creates the admin, drops the setup gate, and signs you in. The form never shows again — once any admin exists, navigating to /setup redirects to /login.

Setup over API¶

Scripts and bootstrap automation can POST /api/v1/auth/setup directly:

curl -X POST http://localhost:8000/api/v1/auth/setup \
  -H "Content-Type: application/json" \
  -d '{"admin_username":"admin","admin_password":"ChangeMe123","admin_email":"[email protected]"}'

The endpoint is one-shot — once any admin exists, subsequent calls return 403 Forbidden with "Setup has already been completed.". Calls before setup don't need a token; calls after setup must use a JWT.

Recovery — lost all admins¶

If every admin account is deleted or disabled and nobody can sign in any more, run the rescue CLI to clear the setup-completed flag. The next boot re-enters the wizard. All other data is preserved — only the gate flag is cleared.

Native install Docker

cd /path/to/bamdude
source venv/bin/activate
python -m backend.app.cli reset_admin

docker compose exec bamdude python -m backend.app.cli reset_admin

The CLI refuses to run while at least one admin still exists — delete the dead accounts directly in the DB first (or via the admin UI if you have any working admin left), then re-run.

Full auth docs

Sessions, refresh-token rotation, MFA (TOTP / email OTP / backup codes), OIDC, LDAP, API keys, and rate limiting all live in Authentication. The setup gate is just step zero.

Running as a Service¶

systemd (Linux)

Create the service file:

sudo nano /etc/systemd/system/bamdude.service

[Unit]
Description=BamDude Print Farm Manager
After=network.target

[Service]
Type=simple
User=YOUR_USERNAME
Group=YOUR_USERNAME
WorkingDirectory=/home/YOUR_USERNAME/bamdude
Environment="PATH=/home/YOUR_USERNAME/bamdude/venv/bin"
ExecStartPre=-/usr/bin/pkill -9 ffmpeg
ExecStopPost=-/usr/bin/pkill -9 ffmpeg
ExecStart=/home/YOUR_USERNAME/bamdude/venv/bin/uvicorn backend.app.main:app --host 0.0.0.0 --port 8000
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target

Enable and start:

sudo systemctl daemon-reload
sudo systemctl enable bamdude
sudo systemctl start bamdude

Network Requirements¶

Outbound to your printers (BamDude → printer):

Port	Protocol	Purpose
8883	MQTT/TLS	Live state, control commands
990	FTPS	3MF upload, archive download

Inbound to BamDude (browser / slicer / Telegram → BamDude):

Port	Protocol	Purpose
8000	HTTP / WS	Web UI + REST API + WebSocket for live updates

Inbound to BamDude when the virtual-printer feature is enabled (slicer "Send to Printer" → BamDude pretending to be a printer). Only required if you use Virtual Printer; native installs can run with just port 8000:

Port	Protocol	Purpose
322	RTSP	Camera proxy (X1 / H2 / P2 series)
990	FTPS control	Slicer upload session
3000, 3002	TCP	Bambu proprietary bind/detect protocol
6000	TCP	File-transfer tunnel
8883	MQTTS	Slicer→printer MQTT emulation
50000–50100	TCP	FTP passive-mode data range

Linux deployments using network_mode: host in compose pick all of these up automatically. Bridge-mode Docker on macOS / Windows needs every port mapped explicitly — see the Docker guide.

Build Frontend from Source¶

The repository includes pre-built frontend files. To build from source:

cd frontend
npm install
npm run build
cd ..

Next Steps¶

Add Your Printer
Connect your first printer

Try Docker Instead
Even simpler setup

Troubleshooting
Installation issues?

Originally based on Bambuddy documentation.