thakares
58c0af6510
- Rewrite project overview - Update architecture documentation - Document Registry Validator and Repair Framework - Refresh CLI reference - Expand installation and deployment guides - Update feature matrix - Add roadmap and operational tooling - Update badges and version
BZOD
Self-hosted Multi-User URL Management Platform with Landing Pages, QR Analytics, Global Namespace Integrity, and Operational Tooling — written in Rust.
BZOD is a modern, lightweight, self-hosted platform for managing short URLs, landing pages, QR codes, analytics, and multi-user deployments.
Unlike traditional URL shorteners, BZOD is designed as a complete URL Management Platform that combines production-ready operational tooling, strong namespace integrity, multi-tenant isolation, and comprehensive administrative capabilities into a single deployable Rust binary powered entirely by SQLite.
Whether you're running a homelab, managing enterprise links, hosting marketing campaigns, operating educational portals, or deploying internal government services, BZOD provides complete ownership of your infrastructure without cloud dependencies or heavyweight external services.
Why BZOD?
Most URL shorteners focus solely on redirects.
BZOD takes a broader approach by combining URL management with operational tooling required for real-world production deployments.
Core capabilities include:
- URL Shortening
- Landing Pages
- QR Code Generation (PNG & SVG)
- QR Analytics
- Visitor Analytics
- Multi-User Platform
- REST API
- Role-Based Access Control (RBAC)
- Global Namespace Registry
- Registry Validation
- Transaction-safe Registry Repair
- Health Diagnostics
- Audit Logging
- Backup & Restore
- User Backup & Restore
- Disaster Recovery
- Upgrade Validation
- Single Binary Deployment
The result is a platform that is easy to deploy, lightweight to operate, and entirely controlled by its owner.
Designed For
BZOD is suitable for:
- 🏠 Homelabs
- 🚀 Startups
- 🏢 Small & Medium Businesses
- 🏭 Enterprise Deployments
- 🎓 Educational Institutions
- 🏛 Government Organizations
- 🌐 Internal Corporate Platforms
- ❤️ Self-hosting Enthusiasts
Complete Ownership
With BZOD, you own everything:
- URLs
- Landing Pages
- QR Codes
- Analytics
- Users
- Sessions
- API Tokens
- Audit Logs
- System Configuration
- Backups
No mandatory cloud services.
No telemetry.
No vendor lock-in.
No recurring subscription fees.
Runtime Efficiency (v0.5.3)
| Metric | Value |
|---|---|
| Release Binary | ~11 MB |
| Runtime Memory (RSS) | ~12 MB |
| Peak Memory | ~12 MB |
| Idle CPU Usage | ~0.02% |
| Swap Usage | 0 KB |
| Database | SQLite (WAL) |
Typical deployment on a 32 GB Linux server:
- Memory usage below 0.05%
- Negligible CPU consumption while idle
- Zero swap usage
- No external infrastructure requirements
BZOD behaves like lightweight infrastructure software rather than a traditional web application.
Installation
System Requirements
BZOD is intentionally lightweight and has minimal runtime requirements.
Minimum
| Component | Requirement |
|---|---|
| CPU | 1 Core |
| Memory | 512 MB |
| Storage | 100 MB |
| OS | Linux (x86_64) |
Recommended
| Component | Requirement |
|---|---|
| CPU | 2+ Cores |
| Memory | 2 GB |
| Storage | 5 GB SSD |
| Database | SQLite (WAL) |
Deployment Options
BZOD supports multiple deployment methods.
- Docker
- Docker Compose
- Native Linux Binary
- Systemd Service
- Reverse Proxy (Nginx, Caddy, Traefik, NPM)
No Kubernetes is required.
Docker
Example:
services:
bzod:
image: ghcr.io/thakares/bzod:latest
container_name: bzod
restart: unless-stopped
ports:
- "8654:8654"
volumes:
- ./data:/app/data
environment:
- RUST_LOG=info
Start:
docker compose up -d
Native Installation
Download the latest release.
chmod +x bzod
sudo mv bzod /usr/local/bin/
Verify:
bzod --help
Initialize
Create the administrator.
bzod create-admin
Start the server.
bzod serve
Default server:
http://localhost:8654
Systemd Service
Example:
[Unit]
Description=BZOD URL Management Platform
After=network.target
[Service]
ExecStart=/usr/local/bin/bzod serve
Restart=always
User=bzod
WorkingDirectory=/opt/bzod
[Install]
WantedBy=multi-user.target
Enable:
sudo systemctl enable bzod
sudo systemctl start bzod
Reverse Proxy
BZOD works behind:
- Nginx
- Caddy
- Apache
- Traefik
- Nginx Proxy Manager
TLS termination should be handled by the reverse proxy.
CLI Overview
bzod serve
bzod backup
bzod restore
bzod migrate
bzod stats
bzod validate
bzod doctor
bzod repair
bzod shorten
bzod expand
bzod create-admin
bzod create-user
bzod delete-user
bzod disable-user
bzod enable-user
bzod reset-password
bzod list-users
bzod backup-user
bzod restore-user
bzod admin-migrate
Health Diagnostics
Inspect platform health.
bzod doctor
Checks include:
- SQLite Integrity
- WAL Status
- Foreign Keys
- Registry Integrity
- Namespace Consistency
- Missing Databases
- Missing Records
- Ownership Validation
Registry Repair
Preview repairs.
bzod repair registry --dry-run
Repair all orphaned entries.
bzod repair registry --force
Repair a single slug.
bzod repair registry \
--slug my-page \
--force
Repairs are:
- Transaction Safe
- Atomic
- Non-destructive
- Fully Logged
Backup
Platform Backup
bzod backup
Restore
bzod restore backup.tar.gz
User Backup
Backup a single tenant.
bzod backup-user \
user@example.com
Restore.
bzod restore-user \
backup.tar.zst
Statistics
View platform statistics.
bzod stats
Displays:
- Users
- URLs
- Landing Pages
- QR Codes
- Analytics
- Databases
- Storage Usage
URL Management
Create a short URL.
bzod shorten \
https://example.com
Expand a short code.
bzod expand abc123
Administrator Commands
Create Administrator
bzod create-admin
List Users
bzod list-users
Disable User
bzod disable-user alice
Enable User
bzod enable-user alice
Delete User
bzod delete-user alice
Reset Password
bzod reset-password alice
Admin Migration
Preview migration.
bzod admin-migrate 2 --dry-run
Execute migration.
bzod admin-migrate 2 --force
REST API
BZOD provides a REST API for automation.
Examples include:
- URL Management
- Landing Pages
- Analytics
- QR Codes
- Administration
- User Management
Authentication uses API Tokens.
Security
Security features include:
- Argon2 Password Hashing
- Secure Cookies
- API Tokens
- RBAC
- Tenant Isolation
- Audit Logging
- Ownership Validation
- Namespace Validation
- SQLite Foreign Keys
- Transaction-safe Repairs
Backup & Disaster Recovery
Designed for long-term reliability.
Features include:
- Platform Backup
- Tenant Backup
- Restore Validation
- Upgrade Validation
- Registry Validation
- Registry Repair
- Backup Manifest
- WAL Recovery
Documentation
Additional documentation is available in the docs/ directory.
- ADMIN_GUIDE.md
- ARCHITECTURE.md
- BACKUP_RESTORE.md
- CHANGELOG.md
- CLI.md
- COMPARISON.md
- DATABASES.md
- INSTALL.md
- MULTI_USER.md
- RELEASE-NOTES.md
- SECURITY.md
- TESTING.md
- UPGRADE.md
Platform Architecture
BZOD is organized into independent functional layers, keeping the core lightweight while allowing future expansion.
Browser / API Client
│
▼
┌────────────────────┐
│ Axum Router │
└─────────┬──────────┘
│
┌───────────────────┼───────────────────┐
▼ ▼ ▼
Authentication Business Logic REST API
│ │ │
└──────────────┬────┴───────────────────┘
▼
Global Slug Registry
│
▼
Tenant Resolution Layer
│
┌──────────────┴───────────────┐
▼ ▼
Administrator Standard Users
│ │
▼ ▼
admin/*.db users/<id>/*.db
Multi-Tenant Architecture
BZOD is designed around complete tenant isolation.
Each user owns independent databases.
data/
├── admin/
│ ├── admin.db
│ ├── users.db
│ └── system.db
│
└── users/
├── 1/
│ ├── content.db
│ ├── analytics.db
│ └── profile.db
│
├── 2/
│ ├── content.db
│ ├── analytics.db
│ └── profile.db
│
└── ...
Benefits include:
- Complete tenant isolation
- Independent backups
- Faster restores
- Simplified migrations
- Better security
- Reduced blast radius
Global Namespace Registry
Unlike many URL shorteners, BZOD guarantees that every public slug is globally unique.
Examples:
/docs
/about
/company
/presentation
cannot simultaneously exist as:
- Administrator URL
- Administrator Landing Page
- User URL
- User Landing Page
The registry is enforced during:
- Creation
- Updates
- Import
- Restore
- Migration
- Startup validation
This guarantees deterministic routing.
Registry Validator
The Registry Validator introduced in v0.5.3 is responsible for maintaining namespace integrity.
It validates:
- Missing URLs
- Missing Landing Pages
- Missing Databases
- Invalid Owners
- Orphaned Registry Entries
- Stale Reservations
- Misplaced Administrator Content
Every validation produces structured results used by multiple platform components.
Registry Repair Framework
The Registry Repair Framework provides explicit repair operations.
Workflow:
Scan
↓
Validate
↓
Preview
↓
Transaction
↓
Repair
↓
Verify
Supported commands:
bzod repair registry --dry-run
bzod repair registry --force
bzod repair registry --slug my-page --dry-run
bzod repair registry --slug my-page --force
Characteristics:
- Transaction-safe
- Atomic
- Idempotent
- Fully logged
- Read-only preview
- Explicit administrator confirmation
Health Diagnostics
The Doctor subsystem continuously validates platform health.
Checks include:
Database Health
- SQLite Integrity
- WAL Mode
- Foreign Keys
- Schema Version
Namespace Health
- Registry Consistency
- Ownership Validation
- Missing Records
- Duplicate Entries
Operational Health
- Tenant Databases
- Administrator Databases
- Registry References
- Restore Compatibility
Run:
bzod doctor
Security Model
BZOD follows a defense-in-depth approach.
Authentication
- Username & Password
- Argon2 Password Hashing
- Secure Cookies
- API Tokens
Authorization
- Role-Based Access Control
- Administrator Privileges
- Tenant Isolation
Validation
- Namespace Validation
- Ownership Validation
- Restore Validation
- Registry Validation
Database
- SQLite Foreign Keys
- WAL Mode
- Atomic Transactions
Operations
- Audit Logging
- Registry Repair
- Backup Verification
Role-Based Access Control (RBAC)
Two primary account types exist.
Administrator
Capabilities:
- Platform Management
- User Management
- Global Analytics
- Moderation
- Registry Repair
- Backups
- Restore
- Audit Logs
- System Statistics
Standard User
Capabilities:
- Personal URLs
- Personal Landing Pages
- Personal Analytics
- QR Downloads
- Profile Management
Users cannot access platform-wide administrative data.
REST API
BZOD includes a REST API suitable for automation.
Current capabilities include:
- URL Management
- Landing Pages
- Analytics
- QR Codes
- Authentication
- Administration
Future API expansions are planned for:
- Webhooks
- Batch Operations
- Tenant Statistics
- OpenAPI Documentation
Backup & Restore
Backups are first-class features.
Platform Backup
bzod backup
Platform Restore
bzod restore backup.tar.gz
User Backup
bzod backup-user alice
User Restore
bzod restore-user alice-backup.tar.zst
Features:
- Backup Manifest
- Validation
- Integrity Checks
- Restore Verification
- Automatic Database Migration
- WAL Compatibility
Testing
BZOD includes extensive automated testing.
Validation is performed using:
cargo fmt --check
cargo clippy --all-targets -- -D warnings
cargo test --all-targets -- --nocapture
cargo build --release
Test coverage includes:
- Authentication
- Authorization
- Routing
- Namespace Integrity
- Registry Validation
- Registry Repair
- Backup & Restore
- User Isolation
- Concurrency
- QR Endpoints
- Analytics
- Moderation
- Business Workflows
- Database Integrity
- Transactions
Project Structure
src/
├── auth/
├── cli/
├── db/
├── jobs/
├── middleware/
├── services/
├── templates/
├── utils/
├── web/
templates/
tests/
docs/
www/
The codebase is organized by responsibility, making it straightforward to extend without introducing unnecessary complexity.
Documentation
The project includes comprehensive documentation.
| Document | Description |
|---|---|
| ADMIN_GUIDE.md | Administrator Guide |
| ARCHITECTURE.md | Internal Architecture |
| BACKUP_RESTORE.md | Backup & Recovery |
| CHANGELOG.md | Project History |
| CLI.md | Command Reference |
| COMPARISON.md | Feature Comparison |
| DATABASES.md | Database Layout |
| INSTALL.md | Installation Guide |
| MULTI_USER.md | Multi-User Architecture |
| RELEASE-NOTES.md | Release History |
| SECURITY.md | Security Model |
| TESTING.md | Testing Guide |
| UPGRADE.md | Upgrade Instructions |
Performance
Typical production deployment:
| Metric | Value |
|---|---|
| Binary Size | ~11 MB |
| Memory Usage | ~12 MB RSS |
| Database | SQLite (WAL) |
| External Dependencies | None |
BZOD scales efficiently for:
- Personal deployments
- Small businesses
- Enterprise internal services
- Educational institutions
- Government organizations
Comparison
| Feature | BZOD | Traditional URL Shorteners |
|---|---|---|
| Rust | ✅ | Rare |
| SQLite Only | ✅ | ❌ |
| Single Binary | ✅ | ❌ |
| Multi-User | ✅ | Limited |
| Landing Pages | ✅ | Limited |
| QR PNG/SVG | ✅ | Limited |
| Analytics | ✅ | Basic |
| Global Namespace | ✅ | Rare |
| Registry Validator | ✅ | ❌ |
| Registry Repair | ✅ | ❌ |
| Health Diagnostics | ✅ | ❌ |
| Backup & Restore | ✅ | Limited |
| User Backup | ✅ | ❌ |
| Transaction-safe Repairs | ✅ | ❌ |
| Self Hosted | ✅ | Mixed |
| Zero External Services | ✅ | Rare |
Production Ready
BZOD has been designed for production deployments with emphasis on:
- Operational simplicity
- Reliability
- Maintainability
- Recoverability
- Security
- Performance
It provides enterprise-grade operational tooling while remaining lightweight enough for homelab deployments.
Roadmap
BZOD follows a pragmatic roadmap focused on operational reliability, maintainability, and long-term ownership.
Rather than chasing feature count, development emphasizes quality, stability, and self-hosting excellence.
Completed
v0.1
- Basic URL Shortener
- SQLite Storage
- Web Interface
v0.2
- QR Code Generation
- Password Protected URLs
- Link Expiration
- Preview Pages
- Bulk Operations
- Audit Events
v0.3
- Landing Pages
- Analytics
- User Dashboard
- Administrator Dashboard
- QR Downloads
v0.4
- Multi-User Platform
- Tenant Isolation
- REST API
- User Administration
- Backup & Restore
- Moderation
- User Quotas
v0.5
Major operational improvements.
Highlights include:
- Global Namespace Registry
- Routing Integrity
- Dashboard Parity
- Administrator Content Consistency
- Registry Validator
- Registry Repair Framework
- RBAC
- Health Diagnostics
- Disaster Recovery
- Upgrade Validation
- Backup Manifest
- Transaction-safe Maintenance
Future Roadmap
v0.6
Planned features include:
- Webhooks
- OpenAPI Documentation
- API Versioning
- Personal Statistics API
- Improved Search
- Bulk Import
- Bulk Export
- Custom Domains
- Better QR Styling
v0.7
Planned improvements:
- Email Notifications
- Team Workspaces
- Shared Projects
- Administrator Notifications
- Enhanced Moderation
- Scheduled Jobs
Long-Term Vision
Potential future capabilities:
- SSO / OpenID Connect
- LDAP Integration
- High Availability
- Read-only Replicas
- Plugin System
- Metrics Export (Prometheus)
- Event Streaming
- Federation
- Object Storage Support
Development priorities will continue to favor reliability over unnecessary complexity.
Why Rust?
Rust provides several advantages for long-running infrastructure services.
- Memory Safety
- Zero-Cost Abstractions
- Excellent Performance
- Strong Concurrency
- Predictable Resource Usage
- Single Binary Deployment
- Cross-Platform Support
These characteristics make Rust particularly well suited for self-hosted infrastructure software.
Why SQLite?
BZOD intentionally uses SQLite as its primary database.
Benefits include:
- Embedded Database
- Zero Configuration
- ACID Transactions
- WAL Support
- Excellent Performance
- Easy Backups
- Simple Disaster Recovery
- Proven Reliability
For the majority of deployments, SQLite offers an excellent balance between performance and operational simplicity.
Contributing
Contributions are welcome.
Areas where contributions are particularly valuable include:
- Bug Reports
- Feature Requests
- Documentation
- Performance Improvements
- Security Reviews
- Testing
- Translations
Before submitting large changes, please open an issue to discuss the proposed implementation.
Reporting Issues
Please include as much information as possible.
Useful details include:
- BZOD Version
- Operating System
- Deployment Method
- Browser
- Logs
- Reproduction Steps
This helps reproduce and resolve issues efficiently.
License
Licensed under either of the following, at your option:
- MIT License
- Apache License 2.0
See the LICENSE files for full details.
Repository
GitHub
https://github.com/thakares/bzod
Codeberg
https://codeberg.org/thakares/bzod
Documentation
Complete documentation is available in the docs/ directory.
- ADMIN_GUIDE.md
- ARCHITECTURE.md
- BACKUP_RESTORE.md
- CHANGELOG.md
- CLI.md
- COMPARISON.md
- DATABASES.md
- INSTALL.md
- MULTI_USER.md
- RELEASE-NOTES.md
- SECURITY.md
- TESTING.md
- UPGRADE.md
Support
If you find BZOD useful:
- ⭐ Star the project
- 🐞 Report issues
- 💡 Suggest improvements
- 📖 Improve documentation
- 🚀 Share the project
Community feedback helps guide future development.
Project Status
Current Version
v0.5.3
Production Ready
Highlights
- ✅ Single Rust Binary
- ✅ SQLite + WAL
- ✅ Multi-User Architecture
- ✅ Global Namespace Registry
- ✅ Landing Pages
- ✅ QR Code Generation
- ✅ PNG & SVG Downloads
- ✅ Analytics
- ✅ REST API
- ✅ Role-Based Access Control
- ✅ Registry Validator
- ✅ Registry Repair Framework
- ✅ Health Diagnostics
- ✅ Backup & Restore
- ✅ Disaster Recovery
- ✅ Upgrade Validation
- ✅ Extensive Automated Test Suite
Project Philosophy
BZOD is more than a URL shortener.
It is a lightweight, self-hosted URL Management Platform designed around ownership, reliability, and operational excellence.
Every feature is guided by a few core principles:
- Own your infrastructure.
- Own your data.
- Keep deployments simple.
- Prefer reliability over complexity.
- Build tools that administrators can trust.
The goal is not to become the largest URL management platform, but to become one of the most dependable, maintainable, and resource-efficient self-hosted solutions available.
Acknowledgements
BZOD is built using outstanding open-source software, including:
- Rust
- Axum
- Tokio
- SQLite
- Askama
- Argon2
- QRCode
- Image
- Chrono
- Serde
Many thanks to the Rust and open-source communities whose work makes projects like BZOD possible.
Author
Sunil Thakare
GitHub: https://github.com/thakares
Codeberg: https://codeberg.org/thakares
BZOD
Own your links.
Own your analytics.
Own your infrastructure.