Version: 1.1.0 | View Changelog
A comprehensive web application for managing 3D printers, including print history tracking, model library management, real-time printer monitoring via MQTT, cloud synchronization with Bambu MakerWorld, and complete database backup & maintenance tools.
- Authentication: Secure login with OIDC support (Authentik, Keycloak, Auth0, etc.)
- Print History: Track all your prints with cover images from MakerWorld, paginated display, per-device filtering
- Model Library: Upload and manage your 3D model files (.3mf, .stl, .gcode)
- Printer Monitoring: Real-time status updates via MQTT including AMS data
- Cloud Sync: Automatic synchronization with Bambu Cloud
- Timelapse Videos: Download and convert print timelapses
- Statistics: View print success rates and analytics
- Duplicate Detection: Find duplicate models in your library
- User Management: Multi-user support with admin controls
- Dynamic Theming: Customizable accent colors applied throughout the app
- Database Maintenance: Vacuum, Analyze, and Reindex operations with detailed results
- Automatic Backups: Schedule automatic database backups (local storage)
- Remote Backups: Upload backups to SFTP or FTP servers
- Backup Retention: Automatic cleanup of old backups based on retention policy
- Settings Management: Organized settings with collapsible categories
- Maintenance Tracking: Track scheduled printer maintenance tasks with history logs
- Maintenance Intervals: Set maintenance schedules based on print hours
- Per-Device Maintenance: Track maintenance separately for each printer
- Maintenance History: View completion history for each task
- Task Management: Mark maintenance tasks as complete and track history
- Maintenance Alerts: Get notified via Discord when maintenance is due
- Discord Webhooks: Get notifications for print failures and maintenance alerts
- MQTT Monitoring: Real-time printer status and AMS updates
- SFTP/FTP Backup: Upload database backups to remote servers
- OAuth/SSO: Enterprise authentication with OIDC providers
- Container-Safe Supervision: Watchdog process manager that doesn't kill containers on app restart
- Configurable Logging: Dynamic log level control (DEBUG/INFO/WARNING/ERROR) in Settings
- Version Tracking: Automatic semantic versioning from package.json
- Node.js 18+ or Docker
- Bambu printer account
- (Optional) OIDC identity provider for SSO
- (Optional) SFTP/FTP server for remote backups
- Pull the latest image:
docker pull ghcr.io/tr1ckz/printhive:latest- Create a docker-compose.yml:
version: '3.8'
services:
printhive:
image: ghcr.io/tr1ckz/printhive:latest
container_name: printhive
restart: unless-stopped
ports:
- "3000:3000"
volumes:
- ./data:/app/data
- ./sessions:/app/sessions
- ./library:/app/library
- ./videos:/app/data/videos
- ./backups:/app/data/backups
environment:
- SESSION_SECRET=your-random-secret-key
- PUBLIC_URL=https://your-domain.com
- LOG_LEVEL=info- Start the container:
docker-compose up -dFor detailed Docker and Unraid instructions, see DOCKER.md.
- Clone the repository:
git clone https://github.com/YOUR_USERNAME/printhive.git
cd printhive- Install dependencies:
npm install- Configure environment:
cp .env.example .env
# Edit .env with your configuration- Start the development server:
npm run devSee README-ENV.md for detailed environment variable documentation.
SESSION_SECRET: Random secret key for session encryptionPUBLIC_URL: Your application's public URL
OAUTH_ISSUER: OIDC provider URLOAUTH_CLIENT_ID: OAuth client IDOAUTH_CLIENT_SECRET: OAuth client secretDISCORD_WEBHOOK_URL: Discord webhook for notificationsMQTT_BROKER: MQTT broker address
Access database maintenance tools in Settings > Advanced > System:
- Vacuum Database: Removes unused space (shows size before/after and space saved)
- Analyze Database: Updates query statistics for optimization
- Rebuild Indexes: Rebuilds all database indexes
- Manual Backup: Create an immediate backup
All operations display detailed results in a modal popup.
Configure in Settings > Advanced > System > Backup Schedule:
- Local Backups: Automatic daily/weekly backups stored in
/data/backups - Backup Interval: Set frequency (1-365 days)
- Retention Period: Automatic cleanup after X days
Choose what to include in your backups:
- ✅ Timelapse Videos - Include all print timelapse videos
- ✅ Library Files - Include .3mf, .stl, .gcode files
- ✅ Cover Images - Include model cover images
- Database is always included
Uncheck options to create smaller, faster backups.
- Enable in Settings > Advanced > System > Remote Backup Location
- Choose protocol: SFTP (secure) or FTP
- Configure host, port, username, password, and remote path
- Click Test Connection to verify settings
- Save - backups will auto-upload when created
- Go to Settings > Advanced > System > Restore from Backup
- Select a backup from the dropdown list
- Click Refresh List to see the latest backups
- Click Restore Backup and confirm
- After restore completes, refresh the page
Configure in Settings > Advanced > System:
- Add maintenance tasks with intervals
- Set alerts and notifications
- Track completion history
- Get Discord alerts when maintenance is due
Manage users in Settings > Administration > User Management:
- Create new users
- Assign roles (user, admin, superadmin)
- Enable/disable accounts
- Reset passwords
- View user activity
Settings are organized in collapsible categories:
- Printer Connection: Bambu Lab account, FTP settings, RTSP camera
- Account: Profile, security, password changes
- Preferences: Cost calculator, UI settings
- Integrations: Discord webhooks, OAuth/SSO
- Advanced: Watchdog, database maintenance, backups
- Administration: User management (admins only)
See DOCKER.md for complete Docker and Unraid deployment instructions including:
- Docker Hub installation
- Docker Compose setup
- Unraid step-by-step guide with volume mappings
- Troubleshooting common issues
Local Backups:
/app/data/backups/
├── printhive_backup_2024-01-06_1704528000000.db
├── printhive_backup_2024-01-05_1704441600000.db
└── ... (older backups auto-deleted based on retention)
Remote Backups:
- Enable SFTP/FTP in settings
- Backups automatically upload to remote server
- Same retention policy applies (files deleted after retention period)
# Install dependencies
npm install
# Start development server (frontend + backend)
npm run dev
# Build for production
npm run build
# Run production server
npm start
# Reset admin user
npm run reset-admin- Backend: Node.js, Express.js
- Frontend: React 19.2, Vite 7.2, TypeScript
- Database: SQLite (printhive.db)
- Authentication: OpenID Connect (OIDC)
- Real-time: MQTT for printer monitoring
- Backup: SFTP & FTP support
- Container: Docker with multi-architecture support
- Fork the repository
- Create a feature branch
- Make your changes
- Submit a pull request
See CONTRIBUTING.md for detailed guidelines.
- Never commit your
.envfile with actual credentials - Use strong, random
SESSION_SECRETin production - Configure HTTPS in production deployments
- Passwords in database settings are masked (only updated if explicitly changed)
- Remote backup credentials are stored encrypted in config
- ✨ Added 10-second countdown to restart splash screen with manual refresh fallback
- ✨ Added filter UI to maintenance tasks for viewing/deleting old tasks
- ✨ Auto-refresh on server recovery when app restarts
- ✨ Added
/api/versionendpoint for version tracking - 🔧 Removed LOG_LEVEL from docker-compose (now managed in Settings)
- 🐛 Fixed splash screen to remove spinning animation and use splash.png background
- 📝 Improved maintenance task display with per-device filtering
- 🚀 Bump to semantic versioning with automatic sync
- 🎉 Full 3D printer management system
- 📊 Print history and statistics
- 🖼️ Model library with MakerWorld integration
- 🔄 Real-time MQTT monitoring with AMS support
- 🛡️ OIDC authentication with role-based access
- 🔐 Database maintenance and backup tools
- 📋 Maintenance task tracking with history
- 🐳 Docker container with watchdog process management
- 🎨 Dynamic theme customization
- 📱 Responsive web UI
MIT License - feel free to use and modify as needed.
- Issues: Report bugs via GitHub Issues
- Documentation: Check README-ENV.md, DOCKER.md, and CONTRIBUTING.md
- Community: Contributions welcome!
- Bambu Lab for their 3D printers and API
- MakerWorld community for model sharing
- Contributors and testers
This is an unofficial integration with Bambu Lab cloud services. It is not affiliated with, endorsed by, or supported by Bambu Lab. Use at your own risk.