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

173
README.md
View File

@@ -1,5 +1,9 @@
# 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.
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).
## 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
- A Raspberry Pi (3B+, 4, or 5) with Raspberry Pi OS installed and connected to your network
- Your Bambu Lab printer on the **same local network** as the Pi
- Your printer's **IP address**, **access token**, and **serial number** (we'll show you how to find these below)
- A computer on the same network to SSH into the Pi
- A Raspberry Pi (3B+, 4, or 5) with Raspberry Pi OS, connected to your network
- Your Bambu Lab printer on the **same local network**
- Your Bambu Lab account **email and password**
- 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.
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:
From your computer, open a terminal (Mac/Linux) or PowerShell (Windows):
```bash
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 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:
### Step 2: Install Docker
```bash
# Download and run Docker's install script
curl -fsSL https://get.docker.com | sudo sh
# Let your user run Docker without sudo
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
exit
```
Then SSH back in:
```bash
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
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
cd Bambu-Run
# Create your configuration file
cp .env.example .env
```
Now edit the `.env` file with your printer details:
```bash
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_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`
```
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:
### Step 4: Build the Container
```bash
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.
First, set up the database:
Bambu Lab requires email verification on first login. Run these two commands:
```bash
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
```
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`:
```
BambuLab Authentication
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
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:
```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.
> Saving the token lets future restarts skip re-verification automatically.
### Step 5b: Start Bambu-Run
Now start everything in the background:
### Step 6: Start Bambu-Run and Create Your Login
```bash
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
```
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
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
```
> 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
**"Cannot connect to printer" or no data showing:**
- 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
**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.
**"Verification code" or "401 Unauthorized" errors:**
- 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
**401 Unauthorized / verification loop:** Remove `BAMBU_TOKEN` from `.env` and re-run Step 5.
**"Cannot connect to Docker daemon":**
- Did you log out and back in after Step 3? Docker group changes require a new session
**Docker daemon error:** Log out and back in after Step 2 — the group change requires a new session.
**Dashboard not loading in browser:**
- Verify the container is running: `docker compose ps`
- Try using the Pi's IP address instead of `raspberrypi.local`
**Dashboard not loading:** Run `docker compose ps` to confirm the service is `Up`, then try the Pi's IP address directly.
**Updating to a newer version:**
**Update Bambu-Run:**
```bash
cd ~/Bambu-Run
git pull
docker compose up -d --build
cd ~/Bambu-Run && git pull && docker compose up -d --build
```
**Stopping Bambu-Run:**
**Stop Bambu-Run:**
```bash
docker compose down
```