Встановлення¶

Цей посібник описує ручну інсталяцію BamDude. Для Docker (рекомендовано) дивіться посібник з Docker.

Вимоги¶

Вимога	Деталі
Python	3.12+ (лише для нативної інсталяції — Docker і Windows-інсталятор везуть власний)
Мережа	Та сама локальна мережа, що й принтер Bambu Lab
Принтер	Увімкнений Developer Mode (інструкція)
SD-карта	Вставлена в принтер (потрібна для передачі файлів)

Альтернатива -- Docker

Якщо ви віддаєте перевагу контейнерам, перегляньте посібник зі встановлення Docker -- це ще простіше!

Ручна інсталяція¶

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

Відкрийте http://localhost:8000 у браузері.

Windows (нативний інсталятор)¶

Для Windows 10/11 є самодостатній .exe-інсталятор — без Docker, без WSL і без окремого встановлення Python чи Node. Setup несе в собі embedded Python runtime і статичний ffmpeg, розкладає все по місцях і реєструє BamDude як Windows Service, що стартує при завантаженні системи.

Завантаж останній bamdude-<version>-windows-x64-setup.exe зі сторінки Releases.
Запусти його (потрібні права Administrator — він реєструє сервіс і пише в ProgramData).
Коли завершиться, браузер відкриє http://localhost:8000.

От і все — сервіс уже працює.

SmartScreen: інсталятор не підписаний

Windows SmartScreen на першому запуску показує «Windows protected your PC» — натисни More info → Run anyway. Чужі бінарники всередині інсталятора (embedded Python, NSSM, ffmpeg) несуть підписи своїх вендорів або не несуть жодного. Що застосунок надсилає назовні і як вимкнути телеметрію: Приватність і телеметрія.

Що розкладає інсталятор¶

Що	Куди
Файли програми (embedded Python 3.12, backend + зібраний frontend, NSSM, ffmpeg)	`C:\Program Files\BamDude`
Твої дані (база, архіви, plate calibration)	`C:\ProgramData\BamDude\data`
Логи	`C:\ProgramData\BamDude\logs`

Інсталятор також додає ярлики в Start-Menu (Open BamDude Dashboard, BamDude Logs, Uninstall), опціональний ярлик на робочому столі, і — якщо не знімати галочку — правило Windows Firewall, що відкриває порт 8000.

Твої дані переживають uninstall + оновлення

Усе під C:\ProgramData\BamDude лишається недоторканим при uninstall. Перевстановлення (чи встановлення новішого білда поверх) автоматично підхоплює ту саму базу й архіви.

:material-service-toggle: Сервіс BamDude¶

Інсталятор реєструє Windows Service з іменем BamDude (під наглядом NSSM), що працює як LocalSystem, стартує автоматично при завантаженні й обслуговує дашборд на http://localhost:8000. Керуй ним стандартними cmdlet-ами:

Get-Service BamDude          # Статус
Start-Service BamDude        # Старт
Stop-Service BamDude         # Стоп
Restart-Service BamDude      # Рестарт

Оновлення¶

Завантаж новіший bamdude-<version>-windows-x64-setup.exe і запусти — він зупиняє сервіс, перезаписує файли програми на місці й перезапускає. Твоя база, архіви та логи під C:\ProgramData\BamDude зберігаються.

Далі відкрий http://localhost:8000.

Конфігурація¶

Налаштуйте BamDude через змінні середовища або файл .env:

cp .env.example .env
nano .env

Змінні середовища¶

Основні¶

Змінна	За замовчуванням	Опис
`DEBUG`	`false`	Увімкнення debug-режиму (детальне логування; у dev також перезапускає останню міграцію при кожному старті)
`LOG_LEVEL`	`INFO`	Рівень логування: `DEBUG`, `INFO`, `WARNING`, `ERROR`
`LOG_TO_FILE`	`true`	Запис логів у `logs/bamdude.log`
`DATA_DIR`	`<repo>/data`	Перевизначити директорію персистентних даних (БД + архіви + plate calibration)
`LOG_DIR`	`<repo>/logs`	Перевизначити директорію логів
`PORT`	`8000`	Порт, на якому слухає вбудований entrypoint `python -m backend.app.main`
`TZ`	system	Часовий пояс, що передається в Python (наприклад, `Europe/Kyiv`)

База даних¶

Змінна	За замовчуванням	Опис
`DATABASE_URL`	не задано (SQLite)	`embedded` — вбудований PostgreSQL 18; або URL на кшталт `postgresql+asyncpg://user:pass@host:5432/bamdude` для власного сервера. Порожнє значення означає SQLite. Див. Підтримка PostgreSQL.
`EMBEDDED_PG_PORT`	обирається один раз і запам'ятовується	Запінити порт вбудованого сервера (наприклад `6432`), щоб до нього діставали `psql` чи DBeaver.

Інсталятор питає сам

install.sh пропонує SQLite, вбудований PostgreSQL або зовнішній сервер — в інтерактиві або без нього через --db sqlite|embedded|external (плюс --database-url для останнього). Повторний запуск поверх наявної інсталяції лишає той бекенд, яким ви вже користуєтесь.

Автентифікація та реверс-проксі¶

Змінна	За замовчуванням	Опис
`JWT_SECRET_KEY`	автогенерація, зберігається в `data/`	Перевизначити ключ підпису JWT. Не змінюйте на запущеній інсталяції -- усі видані токени стануть недійсними.
`TRUSTED_PROXY_IPS`	порожньо	Розділені комою IP реверс-проксі, чий `X-Forwarded-For` довіряємо (резолвінг справа наліво). Потрібно за nginx для коректного per-IP rate limit.
`AUTH_REFRESH_COOKIE_SECURE`	не задано (автовизначення)	Примусово виставити полярність `Secure` на cookie refresh-токена. Автовизначення зі схеми запиту -- правильний дефолт; ставте `true`, щоб примусово увімкнути, `false` -- щоб вимкнути (тільки для LAN HTTP dev).
`MFA_ENCRYPTION_KEY`	не задано	URL-safe base64 Fernet-ключ. Якщо задано, TOTP-секрети та OIDC client secrets шифруються at-rest. Plaintext fallback працює без нього, але логує попередження при старті.
`APP_URL`	`http://localhost:5173`	Публічний базовий URL BamDude. Використовується для абсолютних посилань у password-reset / MFA-recovery листах, OIDC callback URL і Obico cached-frame URL, який ML-API Obico забирає назад. Налаштування `external_url` під Settings → System перебиває цю змінну, якщо задане.

Інтеграції (опціонально)¶

Змінна Опис

HA_URL, HA_TOKEN Базовий URL Home Assistant + long-lived token. Якщо задано обидва, HA-інтеграція авто-увімкнена і відповідні DB-сетинги стають read-only (env переб'є). Рекомендовано для HA Add-on; нативні інсталяції можуть вмикати HA через Settings → Integrations без env-змінних.

VIRTUAL_PRINTER_PASV_ADDRESS Перевизначити FTP-PASV адресу, яку анонсує віртуальний принтер (встановіть, якщо BamDude працює за NAT і слайсери не можуть досягти bind IP).

Container detection¶

Будь-яка з цих env-змінних (будь-яке непорожнє значення) маркує середовище як container, що змінює поведінку SSDP-discovery. Зазвичай ставиться автоматично container-runtime — перевизначай тільки якщо запускаєш натив, але хочеш container-style discovery.

Змінна	Опис
`CONTAINER`	Generic container marker.
`DOCKER_CONTAINER`	Docker-specific marker.

Docker compose helpers (читаються `docker-compose.yml`, не самим BamDude)¶

Змінна	Опис
`PUID` / `PGID`	UID / GID, від яких запускається bamdude-контейнер. Виставляй у відповідність власника твоїх mounted volumes, щоб уникнути permission-помилок при запису архівів. Дізнатись: `id -u && id -g`.

First-boot setup¶

Автентифікація в BamDude завжди увімкнена — режиму "no-auth" не існує. На самому першому запуску API відхиляє кожен запит з 503 {"detail": "setup_required"}, поки не буде створено початкового адміністратора. Whitelist, що обходить гейт, — це рівно три маршрути (/api/v1/auth/status, /api/v1/auth/setup, /api/v1/system/health); login і всі інші ендпоінти лишаються закритими, поки setup не завершиться.

Setup wizard (браузер)¶

Відкрийте BamDude у браузері. Frontend читає /api/v1/auth/status, бачить requires_setup=true і рендерить форму setup-у:

Поле	Обов'язкове	Примітки
Username	так	Стає першим адміном. Макс 150 символів.
Password	так	Мін 8 символів, має містити мінімум одну велику + одну малу + одну цифру. Правила на спецсимвол немає — BamDude слідує NIST SP 800-63B, який явно радить проти composition-rules поза length + basic mix. Макс 256 символів. Зберігається як bcrypt-хеш.
Email	опціонально	Макс 254 символи. Використовується для password-reset флоу + email-OTP MFA пізніше.

Submit створює адміністратора, скидає setup-гейт і логінить вас. Форма більше ніколи не показується — як тільки існує будь-який адмін, навігація на /setup редіректить на /login.

Setup через API¶

Скрипти і bootstrap-автоматизація можуть POST /api/v1/auth/setup напряму:

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]"}'

Ендпоінт one-shot — як тільки існує будь-який адмін, наступні виклики повертають 403 Forbidden з "Setup has already been completed.". Виклики до setup-у не потребують токена; виклики після setup-у мають використовувати JWT.

Recovery — втрата всіх адмінів¶

Якщо всі акаунти адмінів видалено або відключено і ніхто не може залогінитися, запустіть rescue-CLI, щоб скинути setup-completed flag. Наступний boot знову входить у wizard. Усі інші дані зберігаються — скидається лише прапорець гейту.

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

CLI відмовляється запускатися, поки існує хоча б один адмін — спочатку видаліть мертві акаунти прямо в БД (або через admin UI, якщо в вас лишився хоч один робочий адмін), потім запустіть знову.

Повна документація з автентифікації

Сесії, ротація refresh-токенів, MFA (TOTP / email OTP / backup-коди), OIDC, LDAP, API-ключі та rate limiting — усе живе в Автентифікація. Setup-гейт — це лише крок зеро.

Запуск як сервіс¶

systemd (Linux)

Створіть файл сервісу:

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

Активація та запуск:

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

Мережеві вимоги¶

Вихідне до принтерів (BamDude → принтер):

Порт	Протокол	Призначення
8883	MQTT/TLS	Live-стан, керуючі команди
990	FTPS	Завантаження 3MF, скачування архіву

Вхідне до BamDude (браузер / слайсер / Telegram → BamDude):

Порт	Протокол	Призначення
8000	HTTP / WS	Web UI + REST API + WebSocket для live-апдейтів

Вхідне до BamDude, якщо ввімкнений віртуальний принтер (слайсер "Send to Printer" → BamDude вдає принтера). Потрібно лише якщо використовуєш Virtual Printer; нативні інсталяції можуть жити з одним 8000:

Порт	Протокол	Призначення
322	RTSP	Camera-проксі (X1 / H2 / P2)
990	FTPS control	Сесія завантаження зі слайсера
3000, 3002	TCP	Bambu proprietary bind/detect
6000	TCP	Тунель file-transfer
8883	MQTTS	Емуляція MQTT слайсер→принтер
50000–50100	TCP	FTP passive-mode data range

Linux-деплой з network_mode: host у compose забирає всі ці порти автоматом. Bridge-mode Docker на macOS / Windows вимагає явного маппінгу кожного порта — див. гайд по Docker.

Збірка frontend з вихідного коду¶

Репозиторій містить попередньо зібрані файли frontend. Для збірки з вихідного коду:

cd frontend
npm install
npm run build
cd ..

Наступні кроки¶

Додайте принтер
Підключіть свій перший принтер

Спробуйте Docker
Ще простіше налаштування

Вирішення проблем
Проблеми з інсталяцією?

Початково базується на документації Bambuddy.