ben/Bambu-Run
1
0
Fork 0
mirror of https://github.com/RunLit/Bambu-Run.git synced 2026-06-22 14:09:04 +01:00
Code Issues Packages Projects Releases Wiki Activity

added cover image

Browse Source
This commit is contained in:
RNL
2026-02-22 22:59:26 +11:00
parent ab6a7c0bcc
commit 11cc0e0817
1 changed files with 45 additions and 136 deletions
Download Patch File Download Diff File Expand all files Collapse all files

181
README.md
View File

@@ -1,5 +1,9 @@
# Bambu-Run # Bambu-Run
<p align="center">
<img src="docs/BambuRun.png" alt="Bambu-Run Logo" width="300"/>
</p>
Unlock richer data access and powerful customization capabilities for your Bambu Lab 3D printer. Unlock richer data access and powerful customization capabilities for your Bambu Lab 3D printer.
Bambu-Run is a self-hosted web dashboard that tracks data of your Bambu Lab printer. It gives you: Bambu-Run is a self-hosted web dashboard that tracks data of your Bambu Lab printer. It gives you:
@@ -11,227 +15,132 @@ all running on hardware you own.
Recommend a raspberry pi, installed with Raspberry Pi OS (low cost running at the background) or an old PC/Laptop you probably never going to use again (install Linux). Recommend a raspberry pi, installed with Raspberry Pi OS (low cost running at the background) or an old PC/Laptop you probably never going to use again (install Linux).
## Getting Started (Beginner Friendly) ## Quick Start: One-Click Docker Setup — Beginner Friendly
This guide walks you through setting up Bambu-Run on a **Raspberry Pi** from scratch. No prior server experience needed. Get Bambu-Run running on a **Raspberry Pi** in minutes. No prior server experience needed.
### What You'll Need ### What You'll Need
- A Raspberry Pi (3B+, 4, or 5) with Raspberry Pi OS installed and connected to your network - A Raspberry Pi (3B+, 4, or 5) with Raspberry Pi OS, connected to your network
- Your Bambu Lab printer on the **same local network** as the Pi - Your Bambu Lab printer on the **same local network**
- Your printer's **IP address**, **access token**, and **serial number** (we'll show you how to find these below) - Your Bambu Lab account **email and password**
- A computer on the same network to SSH into the Pi - A computer to SSH into the Pi
### Step 1: Find Your Bambu Lab Account Credentials ### Step 1: Connect to Your Raspberry Pi
Bambu-Run connects to your printer through the **Bambu Lab Cloud** using your account login — the same email and password you use for Bambu Handy or Bambu Studio. From your computer, open a terminal (Mac/Linux) or PowerShell (Windows):
You'll need:
- **BAMBU_USERNAME** — Your Bambu Lab account email
- **BAMBU_PASSWORD** — Your Bambu Lab account password
> **First-time login requires email verification.** Bambu Lab will send a 6-digit code to your email. You'll enter this code during Step 5a below. After that, you'll receive a token that skips verification on future startups.
### Step 2: Connect to Your Raspberry Pi
From your computer, open a terminal (Mac/Linux) or PowerShell (Windows) and SSH into the Pi:
```bash ```bash
ssh pi@raspberrypi.local ssh pi@raspberrypi.local
``` ```
> If `raspberrypi.local` doesn't work, use your Pi's IP address instead (check your router's admin page to find it). > Can't connect? Use your Pi's IP address (find it in your router's admin page). Default password: `raspberry`
The default password is `raspberry` (you should change it after first login with `passwd`). ### Step 2: Install Docker
### Step 3: Install Docker
Docker lets you run Bambu-Run in a container — no need to install Python, databases, or anything else manually.
Run these commands one at a time:
```bash ```bash
# Download and run Docker's install script
curl -fsSL https://get.docker.com | sudo sh curl -fsSL https://get.docker.com | sudo sh
# Let your user run Docker without sudo
sudo usermod -aG docker $USER sudo usermod -aG docker $USER
``` ```
Installation issue? check installation methods for raspberry pi: https://docs.docker.com/engine/install/raspberry-pi-os/#installation-methods
**Important:** Log out and log back in for the group change to take effect: Log out and back in for the change to take effect, then verify:
```bash ```bash
exit exit
``` ```
Then SSH back in:
```bash ```bash
ssh pi@raspberrypi.local ssh pi@raspberrypi.local
docker --version # should show Docker version 27.x.x
``` ```
Verify Docker is working: > Installation issues? See: https://docs.docker.com/engine/install/raspberry-pi-os/
### Step 3: Download and Configure
```bash ```bash
docker --version
```
You should see something like `Docker version 27.x.x` — the exact number doesn't matter.
### Step 4: Download and Configure Bambu-Run
```bash
# Clone the project
git clone https://github.com/RunLit/Bambu-Run.git git clone https://github.com/RunLit/Bambu-Run.git
cd Bambu-Run cd Bambu-Run
# Create your configuration file
cp .env.example .env cp .env.example .env
```
Now edit the `.env` file with your printer details:
```bash
nano .env nano .env
``` ```
Fill in your Bambu Lab account credentials from Step 1: Fill in your Bambu Lab credentials:
``` ```
BAMBU_USERNAME=your_email@example.com BAMBU_USERNAME=your_email@example.com
BAMBU_PASSWORD=your_password BAMBU_PASSWORD=your_password
TIMEZONE=Australia/Melbourne # optional — find yours at https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
``` ```
Optionally set your timezone (defaults to UTC): Save: `Ctrl + X`, `Y`, `Enter`
``` ### Step 4: Build the Container
TIMEZONE=Australia/Melbourne
```
> You can find your timezone name at https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
To save and exit nano: press `Ctrl + X`, then `Y`, then `Enter`.
### Step 5: Build and Start Bambu-Run
First, build the container:
```bash ```bash
docker compose build docker compose build
``` ```
This downloads all required software (takes a few minutes the first time). This takes a few minutes the first time — it downloads all required software.
### Step 5a: First-Time Authentication ### Step 5: First-Time Authentication
The first time you connect, Bambu Lab requires email verification. You need to run the collector **interactively** (not in the background) so you can enter the 6-digit code. Bambu Lab requires email verification on first login. Run these two commands:
First, set up the database:
```bash ```bash
docker compose run --rm bambu-run python standalone/manage.py migrate --noinput docker compose run --rm bambu-run python standalone/manage.py migrate --noinput
```
Then run the collector (this is what triggers Bambu Lab to send the verification email):
```bash
docker compose run --rm bambu-run python standalone/manage.py bambu_collector --once docker compose run --rm bambu-run python standalone/manage.py bambu_collector --once
``` ```
You'll see output like: When prompted, enter the 6-digit code sent to your email. On success you'll see a token printed — copy it and add it to your `.env`:
``` ```bash
BambuLab Authentication nano .env
Authenticating as: your_email@example.com
...
EMAIL VERIFICATION REQUIRED
A verification code has been sent to your email.
Enter verification code:
``` ```
1. Check your email for the 6-digit code from Bambu Lab ```
2. Type the code and press Enter BAMBU_TOKEN=eyJhbGciOiJIUzI1N...paste_full_token_here
3. On success, you'll see a token printed: ```
```
Authentication successful!
Token: eyJhbGciOiJIUzI1N...
TIP: Save this token to BAMBU_TOKEN env var to skip login next time
```
4. **Copy the full token** and paste it into your `.env` file: > Saving the token lets future restarts skip re-verification automatically.
```bash
nano .env
```
Add/uncomment the `BAMBU_TOKEN` line:
```
BAMBU_TOKEN=eyJhbGciOiJIUzI1N...paste_full_token_here
```
> **Why save the token?** With the token saved, future container restarts authenticate instantly without needing email verification again. Without it, you'd need to repeat this step every time the container restarts. ### Step 6: Start Bambu-Run and Create Your Login
### Step 5b: Start Bambu-Run
Now start everything in the background:
```bash ```bash
docker compose up -d docker compose up -d
```
Check that it's running:
```bash
docker compose ps
```
You should see the `bambu-run` service with status `Up`.
### Step 6: Create Your Login Account
```bash
docker compose exec bambu-run python standalone/manage.py createsuperuser docker compose exec bambu-run python standalone/manage.py createsuperuser
``` ```
You'll be prompted to choose a username, email (optional), and password. This is your login for the dashboard. Choose a username and password — this is your dashboard login.
### Step 7: Open the Dashboard ### Step 7: Open the Dashboard
On any device connected to your network (phone, tablet, computer), open a browser and go to: On any device on your network, open a browser and go to:
``` ```
http://raspberrypi.local:8000 http://raspberrypi.local:8000
``` ```
> If that doesn't work, use your Pi's IP address: `http://<pi-ip-address>:8000` > If that doesn't work, use your Pi's IP: `http://<pi-ip-address>:8000`
Log in with the account you just created. You should see your printer dashboard with live data flowing in. Log in with the account you just created. Your printer dashboard should be live.
### Troubleshooting ### Troubleshooting
**"Cannot connect to printer" or no data showing:** **No data / cannot connect to printer:** Make sure the printer is on and on the same network. Check logs: `docker compose logs -f`. If you see auth errors, re-run Step 5 to get a fresh token.
- Make sure your printer is turned on and connected to the network
- Check the logs: `docker compose logs -f`
- If you see authentication errors, your token may have expired — re-run Step 5a to get a fresh token
**"Verification code" or "401 Unauthorized" errors:** **401 Unauthorized / verification loop:** Remove `BAMBU_TOKEN` from `.env` and re-run Step 5.
- Your `BAMBU_TOKEN` may have expired. Remove it from `.env` and re-run Step 5a
- Make sure `BAMBU_USERNAME` and `BAMBU_PASSWORD` are correct in your `.env` file
**"Cannot connect to Docker daemon":** **Docker daemon error:** Log out and back in after Step 2 — the group change requires a new session.
- Did you log out and back in after Step 3? Docker group changes require a new session
**Dashboard not loading in browser:** **Dashboard not loading:** Run `docker compose ps` to confirm the service is `Up`, then try the Pi's IP address directly.
- Verify the container is running: `docker compose ps`
- Try using the Pi's IP address instead of `raspberrypi.local`
**Updating to a newer version:** **Update Bambu-Run:**
```bash ```bash
cd ~/Bambu-Run cd ~/Bambu-Run && git pull && docker compose up -d --build
git pull
docker compose up -d --build
``` ```
**Stopping Bambu-Run:** **Stop Bambu-Run:**
```bash ```bash
docker compose down docker compose down
``` ```