389 lines
6.8 KiB
Markdown
389 lines
6.8 KiB
Markdown
# BZOD
|
|
|
|
> Self-hosted Multi-User URL Management Platform written in Rust.
|
|
|
|
BZOD combines URL shortening, landing pages, QR codes, analytics, moderation, audit logging, backup & restore workflows, and tenant isolation into a single deployable binary powered entirely by SQLite.
|
|
|
|
Designed for homelabs, organizations, businesses, educational institutions, and government agencies that require complete ownership of their links, analytics, and operational data.
|
|
|
|
---
|
|
|
|
## Why BZOD?
|
|
|
|
Most URL shorteners focus only on redirects and click tracking.
|
|
|
|
BZOD is designed as a complete self-hosted platform with:
|
|
|
|
* Multi-user architecture
|
|
* Tenant isolation
|
|
* Landing pages
|
|
* QR code generation
|
|
* Analytics
|
|
* Audit logging
|
|
* Moderation
|
|
* Backup & restore
|
|
* Disaster recovery
|
|
* Administrative tooling
|
|
* REST API
|
|
* Web UI
|
|
* CLI management
|
|
|
|
All without requiring PostgreSQL, Redis, Elasticsearch, Kubernetes, or external SaaS services.
|
|
|
|
---
|
|
|
|
## Key Features
|
|
|
|
### URL Management
|
|
|
|
* Short URLs
|
|
* Custom slugs
|
|
* Bulk operations
|
|
* Password-protected links
|
|
* Expiring links
|
|
* Smart preview pages
|
|
* QR code generation
|
|
|
|
### Landing Pages
|
|
|
|
* Hosted landing pages
|
|
* Custom slugs
|
|
* Analytics
|
|
* QR code support
|
|
|
|
### Analytics
|
|
|
|
* Visitor tracking
|
|
* QR scan analytics
|
|
* Browser detection
|
|
* Referrer analysis
|
|
* Daily and monthly statistics
|
|
* CSV export
|
|
* JSON export
|
|
* Raw visitor logs
|
|
|
|
### Multi-User Platform
|
|
|
|
* User accounts
|
|
* User quotas
|
|
* Session management
|
|
* API tokens
|
|
* Tenant isolation
|
|
* Administrative controls
|
|
|
|
### Administration
|
|
|
|
* User management
|
|
* Moderation
|
|
* Audit logs
|
|
* Session administration
|
|
* Quota management
|
|
* Backup management
|
|
* Health dashboard
|
|
|
|
### Operations
|
|
|
|
* Backup & restore
|
|
* Disaster recovery
|
|
* Health monitoring
|
|
* Upgrade migrations
|
|
* WAL-enabled SQLite databases
|
|
|
|
---
|
|
|
|
## Architecture
|
|
|
|
```text
|
|
┌─────────────┐
|
|
│ Browser │
|
|
└──────┬──────┘
|
|
│
|
|
┌───────▼───────┐
|
|
│ Axum Server │
|
|
└───────┬───────┘
|
|
│
|
|
┌────────────────────┼────────────────────┐
|
|
│ │ │
|
|
▼ ▼ ▼
|
|
users.db system.db User Databases
|
|
accounts global_slugs content.db
|
|
sessions moderation analytics.db
|
|
quotas audit logs tenant data
|
|
api tokens settings
|
|
```
|
|
|
|
### Data Layout
|
|
|
|
```text
|
|
data/
|
|
├── system.db
|
|
├── users.db
|
|
│
|
|
├── admin/
|
|
│ ├── content.db
|
|
│ └── analytics.db
|
|
│
|
|
└── users/
|
|
├── 2/
|
|
│ ├── content.db
|
|
│ └── analytics.db
|
|
│
|
|
├── 3/
|
|
│ ├── content.db
|
|
│ └── analytics.db
|
|
│
|
|
└── ...
|
|
```
|
|
|
|
### Core Databases
|
|
|
|
#### users.db
|
|
|
|
Stores:
|
|
|
|
* Users
|
|
* Password hashes
|
|
* Sessions
|
|
* API tokens
|
|
* Quotas
|
|
|
|
#### system.db
|
|
|
|
Stores:
|
|
|
|
* Global slug namespace
|
|
* Moderation events
|
|
* Audit events
|
|
* Reserved slugs
|
|
* Settings
|
|
|
|
#### Tenant Databases
|
|
|
|
Each user receives isolated databases:
|
|
|
|
##### content.db
|
|
|
|
* URLs
|
|
* Landing pages
|
|
* Metadata
|
|
|
|
##### analytics.db
|
|
|
|
* Visits
|
|
* QR scans
|
|
* Referrers
|
|
* User agents
|
|
* Aggregated statistics
|
|
|
|
---
|
|
|
|
## Feature Matrix
|
|
|
|
| Feature | Status |
|
|
| ------------------- | ------ |
|
|
| URL Shortening | ✅ |
|
|
| Custom Slugs | ✅ |
|
|
| Landing Pages | ✅ |
|
|
| QR Codes | ✅ |
|
|
| QR Analytics | ✅ |
|
|
| Password Protection | ✅ |
|
|
| Link Expiration | ✅ |
|
|
| Analytics Dashboard | ✅ |
|
|
| CSV Export | ✅ |
|
|
| JSON Export | ✅ |
|
|
| REST API | ✅ |
|
|
| Web UI | ✅ |
|
|
| CLI | ✅ |
|
|
| Multi-User Support | ✅ |
|
|
| User Quotas | ✅ |
|
|
| Session Management | ✅ |
|
|
| API Tokens | ✅ |
|
|
| Moderation | ✅ |
|
|
| Audit Logging | ✅ |
|
|
| Backup & Restore | ✅ |
|
|
| Disaster Recovery | ✅ |
|
|
| Health Monitoring | ✅ |
|
|
| Upgrade Migrations | ✅ |
|
|
|
|
---
|
|
|
|
## Screenshots
|
|
|
|
### Dashboard
|
|
|
|
|
|
|
|
### URL Management
|
|
|
|
|
|
|
|
### Landing Pages
|
|
|
|
|
|
|
|
### Settings
|
|
|
|
|
|
|
|
### Health Dashboard
|
|
|
|
|
|
|
|
---
|
|
|
|
## Installation
|
|
|
|
### Docker
|
|
|
|
```bash
|
|
docker compose up -d
|
|
```
|
|
|
|
### Native
|
|
|
|
```bash
|
|
cargo build --release
|
|
./target/release/bzod serve
|
|
```
|
|
|
|
---
|
|
|
|
## CLI
|
|
|
|
### Administration
|
|
|
|
```bash
|
|
bzod create-admin
|
|
bzod create-user
|
|
bzod delete-user
|
|
bzod disable-user
|
|
bzod enable-user
|
|
bzod reset-password
|
|
bzod list-users
|
|
```
|
|
|
|
### Backup & Recovery
|
|
|
|
```bash
|
|
bzod backup
|
|
bzod restore
|
|
```
|
|
|
|
### Maintenance
|
|
|
|
```bash
|
|
bzod doctor
|
|
bzod migrate
|
|
bzod validate
|
|
bzod stats
|
|
```
|
|
|
|
---
|
|
|
|
## Testing
|
|
|
|
BZOD v0.5.0 includes a comprehensive automated validation suite.
|
|
|
|
### Validation Coverage
|
|
|
|
* Unit tests
|
|
* Integration tests
|
|
* HTTP E2E tests
|
|
* Authentication tests
|
|
* Migration tests
|
|
* Upgrade validation tests
|
|
* User isolation tests
|
|
* Security tests
|
|
* Backup/restore tests
|
|
* Disaster recovery tests
|
|
* Concurrency tests
|
|
* Business workflow tests
|
|
* WAL recovery tests
|
|
|
|
### Execute
|
|
|
|
```bash
|
|
cargo test
|
|
```
|
|
|
|
### Quality Gates
|
|
|
|
```bash
|
|
cargo fmt --check
|
|
cargo clippy --all-targets -- -D warnings
|
|
cargo test
|
|
cargo build --release
|
|
cargo audit
|
|
```
|
|
|
|
---
|
|
|
|
## Documentation
|
|
|
|
Additional documentation is available in `docs/`.
|
|
|
|
| Document | Description |
|
|
| ---------------- | ---------------------------- |
|
|
| API.md | REST API reference |
|
|
| CHANGELOG.md | Version history |
|
|
| COMPARISON.md | Comparison with alternatives |
|
|
| DOCKER-Deploy.md | Docker deployment guide |
|
|
| RELEASE-NOTES.md | Release information |
|
|
| TESTING.md | Validation and testing |
|
|
|
|
---
|
|
|
|
## Release Status
|
|
|
|
### v0.5.0
|
|
|
|
General Availability (GA)
|
|
|
|
Validation completed:
|
|
|
|
* Formatting
|
|
* Linting
|
|
* Build verification
|
|
* Unit tests
|
|
* Integration tests
|
|
* HTTP E2E tests
|
|
* Business workflow tests
|
|
* Upgrade validation tests
|
|
|
|
---
|
|
|
|
## Roadmap
|
|
|
|
Planned future enhancements:
|
|
|
|
* Geographic analytics
|
|
* SSO integration
|
|
* OpenAPI specification
|
|
* Multi-organization support
|
|
* Advanced analytics dashboards
|
|
* Background scheduler UI
|
|
|
|
---
|
|
|
|
## License
|
|
|
|
Dual licensed under:
|
|
|
|
* Apache License 2.0
|
|
* MIT License
|
|
|
|
at your option.
|
|
|
|
See:
|
|
|
|
* LICENSE-APACHE
|
|
* LICENSE-MIT
|
|
|
|
---
|
|
|
|
## Author
|
|
|
|
Sunil Purushottam Thakare
|
|
|
|
Built with Rust, SQLite, Axum, Askama, and a preference for simple, maintainable, self-hosted software.
|