docs: complete v0.5.0 administration, architecture and deployment guides
This commit is contained in:
thakares committed
1 parent
c7e851000f
commit
49acf76cf6
11 files changed
+5910
-998
No files matched your search
+280
-331
@@ -1,382 +1,331 @@
|
||||
# BZOD vs Other Self-Hosted URL Shorteners
|
||||
# BZOD v0.5.0 vs Self-Hosted URL Management Platforms
|
||||
|
||||
**BZOD (nx9-url-shortener)** is a modern, privacy-focused, self-hosted URL management platform built in Rust as part of the **NX9 Platform**.
|
||||
BZOD is a modern, privacy-focused, self-hosted URL Management Platform written in Rust and developed as part of the NX9 Platform.
|
||||
|
||||
Unlike many traditional URL shorteners that focus solely on redirects, BZOD combines:
|
||||
Unlike traditional URL shorteners that focus primarily on URL redirection, BZOD provides a complete platform for managing URLs, landing pages, analytics, users, permissions, backups, and operational workflows.
|
||||
|
||||
---
|
||||
|
||||
# Executive Summary
|
||||
|
||||
BZOD combines:
|
||||
|
||||
* URL shortening
|
||||
* Landing pages
|
||||
* QR code generation
|
||||
* QR analytics
|
||||
* Password protection
|
||||
* Link analytics
|
||||
* Password-protected links
|
||||
* Link expiration
|
||||
* REST API
|
||||
* CLI automation
|
||||
* Backup & restore
|
||||
* Administrative dashboard
|
||||
* Multi-user operation
|
||||
* User management
|
||||
* User quotas
|
||||
* Session management
|
||||
* Audit logging
|
||||
|
||||
into a single lightweight deployment.
|
||||
|
||||
**Philosophy:** *One binary. One command. Full ownership.*
|
||||
|
||||
---
|
||||
|
||||
## At a Glance
|
||||
|
||||
* Rust-based
|
||||
* Single ~18 MB binary
|
||||
* Embedded SQLite
|
||||
* No external services required
|
||||
* Landing pages
|
||||
* QR generation & analytics
|
||||
* Password-protected links
|
||||
* REST API
|
||||
* CLI automation
|
||||
* Moderation
|
||||
* Backup & restore
|
||||
* Audit trail
|
||||
* MIT OR Apache-2.0 licensed
|
||||
* One-command deployment
|
||||
* Disaster recovery tooling
|
||||
|
||||
into a single Rust binary deployment.
|
||||
|
||||
---
|
||||
|
||||
## Quick Comparison
|
||||
# At a Glance
|
||||
|
||||
| Feature | BZOD | Shlink | YOURLS | Chhoto URL |
|
||||
| --------------------- | ----------------- | -------- | -------- | ---------- |
|
||||
| Language | Rust | PHP | PHP | Rust |
|
||||
| Single Binary | ✅ | ❌ | ❌ | ✅ |
|
||||
| Landing Pages | ✅ | ❌ | Plugin | ❌ |
|
||||
| QR Code + Analytics | ✅ | Partial | Plugin | Partial |
|
||||
| Password Protection | ✅ | Limited | Plugin | ❌ |
|
||||
| Backup & Restore | ✅ | External | External | ❌ |
|
||||
| Audit Trail | ✅ | Limited | Plugin | ❌ |
|
||||
| CLI Tools | ✅ | Limited | Limited | Limited |
|
||||
| Dependencies | None | PHP + DB | PHP + DB | None |
|
||||
| Deployment Complexity | Low | Medium | High | Low |
|
||||
| License | MIT OR Apache-2.0 | MIT | MIT | MIT |
|
||||
| Feature | BZOD |
|
||||
| -------------------- | ----------------- |
|
||||
| Language | Rust |
|
||||
| License | MIT OR Apache-2.0 |
|
||||
| Deployment | Single Binary |
|
||||
| Runtime Dependencies | None |
|
||||
| Database | SQLite |
|
||||
| Multi-User | Yes |
|
||||
| Landing Pages | Yes |
|
||||
| QR Codes | Yes |
|
||||
| Analytics | Yes |
|
||||
| REST API | Yes |
|
||||
| CLI Tools | Yes |
|
||||
| Backups | Built-in |
|
||||
| Audit Logs | Built-in |
|
||||
| RBAC | Built-in |
|
||||
|
||||
---
|
||||
|
||||
## Design Philosophy
|
||||
# What Changed in v0.5.0
|
||||
|
||||
| Principle | BZOD |
|
||||
| -------------------------- | ----------------- |
|
||||
| Self-hosted | ✅ |
|
||||
| Privacy-first | ✅ |
|
||||
| Open Source | MIT OR Apache-2.0 |
|
||||
| Vendor Lock-in | None |
|
||||
| Telemetry | None |
|
||||
| External Services Required | None |
|
||||
| Database Server Required | No (SQLite) |
|
||||
| Runtime Dependencies | None |
|
||||
| Single Binary | Yes (~18 MB) |
|
||||
| Linux-first | Yes |
|
||||
BZOD v0.5.0 introduces a major architectural evolution.
|
||||
|
||||
## New Platform Capabilities
|
||||
|
||||
* Multi-user architecture
|
||||
* Tenant isolation
|
||||
* Global slug namespace
|
||||
* User management
|
||||
* User quotas
|
||||
* Session management
|
||||
* Administrative dashboards
|
||||
* User self-service dashboards
|
||||
* Audit event logging
|
||||
* Moderation workflows
|
||||
* Backup management
|
||||
* Health monitoring
|
||||
* Upgrade framework
|
||||
* Migration tooling
|
||||
|
||||
BZOD is no longer merely a URL shortener.
|
||||
|
||||
It is now a self-hosted URL Management Platform.
|
||||
|
||||
---
|
||||
|
||||
## The NX9 Philosophy
|
||||
# Traditional URL Shortener Comparison
|
||||
|
||||
BZOD is part of the **NX9 Platform**.
|
||||
|
||||
NX9 projects follow strict engineering principles:
|
||||
|
||||
* Linux-native first
|
||||
* Rust-first
|
||||
* Single binary deployments
|
||||
* No NodeJS
|
||||
* No React
|
||||
* No Python runtime dependencies
|
||||
* No vendor lock-in
|
||||
* No telemetry
|
||||
* Privacy-first by default
|
||||
* MIT OR Apache-2.0 licensed
|
||||
|
||||
GitHub and Codeberg are source-code repositories, not the projects themselves.
|
||||
|
||||
The software is the project.
|
||||
|
||||
The goal of NX9 is simple:
|
||||
|
||||
> Build technology that serves people, organizations, communities, and governments — not advertising networks, data brokers, or vendor ecosystems.
|
||||
| Capability | BZOD | Shlink | YOURLS | Chhoto URL |
|
||||
| ------------------- | ---- | -------- | -------- | ---------- |
|
||||
| URL Shortening | ✅ | ✅ | ✅ | ✅ |
|
||||
| Landing Pages | ✅ | ❌ | Plugin | ❌ |
|
||||
| QR Generation | ✅ | Partial | Plugin | Partial |
|
||||
| QR Analytics | ✅ | Partial | Plugin | ❌ |
|
||||
| Password Protection | ✅ | Limited | Plugin | ❌ |
|
||||
| Link Expiration | ✅ | ✅ | Plugin | Limited |
|
||||
| REST API | ✅ | ✅ | ✅ | JSON-RPC |
|
||||
| Backup & Restore | ✅ | External | External | ❌ |
|
||||
| Audit Logs | ✅ | Limited | Plugin | ❌ |
|
||||
| Multi User | ✅ | Partial | Plugin | ❌ |
|
||||
| User Quotas | ✅ | ❌ | ❌ | ❌ |
|
||||
| User Isolation | ✅ | ❌ | ❌ | ❌ |
|
||||
| User Dashboards | ✅ | ❌ | ❌ | ❌ |
|
||||
|
||||
---
|
||||
|
||||
## Why BZOD Exists
|
||||
# Multi-User Platform Comparison
|
||||
|
||||
Most self-hosted URL shorteners optimize for one of two extremes:
|
||||
BZOD v0.5.0 introduces first-class multi-user support.
|
||||
|
||||
### 1. Minimal Redirect Service
|
||||
| Capability | BZOD |
|
||||
| ---------------------- | ---- |
|
||||
| User Accounts | ✅ |
|
||||
| Administrator Accounts | ✅ |
|
||||
| User Isolation | ✅ |
|
||||
| User Quotas | ✅ |
|
||||
| Session Management | ✅ |
|
||||
| API Tokens | ✅ |
|
||||
| Audit Trail | ✅ |
|
||||
| Moderation | ✅ |
|
||||
| Tenant Analytics | ✅ |
|
||||
| Self-Service Portal | ✅ |
|
||||
|
||||
A tiny application that creates short links and redirects traffic.
|
||||
Most self-hosted URL shorteners are fundamentally single-user applications.
|
||||
|
||||
Advantages:
|
||||
BZOD is designed for:
|
||||
|
||||
* Extremely lightweight
|
||||
* Easy to understand
|
||||
* Easy to maintain
|
||||
|
||||
Disadvantages:
|
||||
|
||||
* Limited administration
|
||||
* Limited analytics
|
||||
* Limited security features
|
||||
* Often requires additional tools
|
||||
|
||||
### 2. Large Multi-Service Platform
|
||||
|
||||
Feature-rich systems with extensive integrations and dependencies.
|
||||
|
||||
Advantages:
|
||||
|
||||
* Powerful analytics
|
||||
* Advanced routing
|
||||
* Large ecosystems
|
||||
|
||||
Disadvantages:
|
||||
|
||||
* More infrastructure
|
||||
* More maintenance
|
||||
* Higher resource requirements
|
||||
|
||||
### BZOD's Approach
|
||||
|
||||
BZOD intentionally sits in the middle.
|
||||
|
||||
It is:
|
||||
|
||||
* Small enough for a Raspberry Pi
|
||||
* Powerful enough for organizations
|
||||
* Simple enough for homelabs
|
||||
* Complete enough for production use
|
||||
* Individuals
|
||||
* Teams
|
||||
* Organizations
|
||||
* Educational Institutions
|
||||
* Governments
|
||||
* Service Providers
|
||||
|
||||
---
|
||||
|
||||
# BZOD vs Go URL Shorteners
|
||||
# Security Comparison
|
||||
|
||||
Popular Go projects include:
|
||||
| Security Feature | BZOD | Typical URL Shortener |
|
||||
| ------------------------- | ---- | --------------------- |
|
||||
| Argon2id Password Hashing | ✅ | Varies |
|
||||
| Session Management | ✅ | Basic |
|
||||
| CSRF Protection | ✅ | Varies |
|
||||
| RBAC | ✅ | Rare |
|
||||
| Audit Logging | ✅ | Rare |
|
||||
| User Disablement | ✅ | Rare |
|
||||
| Moderation Controls | ✅ | Rare |
|
||||
| Tenant Isolation | ✅ | Rare |
|
||||
| API Token Security | ✅ | Varies |
|
||||
|
||||
---
|
||||
|
||||
# Operations Comparison
|
||||
|
||||
| Operational Feature | BZOD |
|
||||
| ------------------- | ---- |
|
||||
| Backup Creation | ✅ |
|
||||
| Backup Restore | ✅ |
|
||||
| User Backup | ✅ |
|
||||
| User Restore | ✅ |
|
||||
| Disaster Recovery | ✅ |
|
||||
| Upgrade Validation | ✅ |
|
||||
| Health Monitoring | ✅ |
|
||||
| WAL Recovery | ✅ |
|
||||
| Migration Framework | ✅ |
|
||||
|
||||
Most competing products rely on external tooling for these capabilities.
|
||||
|
||||
---
|
||||
|
||||
# Deployment Comparison
|
||||
|
||||
| Requirement | BZOD | Shlink | YOURLS |
|
||||
| -------------------------- | ---- | -------- | -------- |
|
||||
| Single Binary | ✅ | ❌ | ❌ |
|
||||
| SQLite Only | ✅ | Optional | Optional |
|
||||
| External Database Required | ❌ | Usually | Usually |
|
||||
| Docker Support | ✅ | ✅ | ✅ |
|
||||
| Systemd Support | ✅ | Manual | Manual |
|
||||
| Backup Framework | ✅ | ❌ | ❌ |
|
||||
| Upgrade Framework | ✅ | ❌ | ❌ |
|
||||
|
||||
---
|
||||
|
||||
# BZOD vs Go-Based URL Shorteners
|
||||
|
||||
Popular Go alternatives include:
|
||||
|
||||
* Krtk
|
||||
* Slash
|
||||
* Goshorly
|
||||
* Slash
|
||||
* Shortr
|
||||
* Custom Gin/Echo implementations
|
||||
|
||||
## Detailed Comparison
|
||||
### Strengths of Go Projects
|
||||
|
||||
| Aspect | BZOD (Rust) | Typical Go Projects |
|
||||
| ------------------- | -------------------- | ------------------- |
|
||||
| Binary | Single ~18 MB binary | Usually 10–20 MB |
|
||||
| Runtime | None | None |
|
||||
| Database | Embedded SQLite | SQLite / PostgreSQL |
|
||||
| Landing Pages | ✅ Built-in | Rare |
|
||||
| QR Generation | ✅ | Sometimes |
|
||||
| QR Analytics | ✅ | Rare |
|
||||
| Password Protection | ✅ | Varies |
|
||||
| Link Expiry | ✅ | Often |
|
||||
| One-Time Links | ✅ | Rare |
|
||||
| UTM Builder | ✅ | Rare |
|
||||
| REST API | ✅ | Usually |
|
||||
| CLI | ✅ Extensive | Usually limited |
|
||||
| Backup & Restore | ✅ Built-in | Rare |
|
||||
| Audit Logs | ✅ | Rare |
|
||||
| Admin Dashboard | ✅ | Varies |
|
||||
* Small binaries
|
||||
* Excellent performance
|
||||
* Simple codebases
|
||||
|
||||
### Summary
|
||||
### Strengths of BZOD
|
||||
|
||||
Go shorteners are often:
|
||||
|
||||
* Extremely simple
|
||||
* Fast
|
||||
* Easy to extend
|
||||
|
||||
BZOD focuses on:
|
||||
|
||||
* Rich built-in functionality
|
||||
* Complete ownership
|
||||
* Minimal operations
|
||||
* Batteries-included deployment
|
||||
|
||||
---
|
||||
|
||||
# BZOD vs Python URL Shorteners
|
||||
|
||||
Popular Python projects include:
|
||||
|
||||
* Pygmy
|
||||
* ReducePy
|
||||
* Schort
|
||||
* Flask/FastAPI examples
|
||||
|
||||
## Detailed Comparison
|
||||
|
||||
| Aspect | BZOD (Rust) | Python Solutions |
|
||||
| ---------------- | --------------------- | ----------------- |
|
||||
| Runtime | None | Python required |
|
||||
| Deploy Size | ~18 MB | Often 100+ MB |
|
||||
| Memory Usage | Very Low | Moderate |
|
||||
| Landing Pages | ✅ | Rare |
|
||||
| QR Analytics | ✅ | Rare |
|
||||
| Backup & Restore | ✅ | Rare |
|
||||
| CLI Tools | ✅ | Limited |
|
||||
| Dashboard | ✅ | Varies |
|
||||
| Security | Argon2id + Audit Logs | Project dependent |
|
||||
| Performance | Excellent | Good |
|
||||
|
||||
### Summary
|
||||
|
||||
Python solutions are ideal when:
|
||||
|
||||
* Already using Python
|
||||
* Rapid prototyping
|
||||
* Easy customization
|
||||
|
||||
BZOD is ideal when:
|
||||
|
||||
* Long-term deployment matters
|
||||
* Resource efficiency matters
|
||||
* Minimal maintenance is desired
|
||||
|
||||
---
|
||||
|
||||
# BZOD vs Shlink
|
||||
|
||||
Shlink is one of the most mature self-hosted URL shorteners available.
|
||||
|
||||
## Detailed Comparison
|
||||
|
||||
| Aspect | BZOD | Shlink |
|
||||
| ------------------------ | ------------- | ---------------- |
|
||||
| Language | Rust | PHP |
|
||||
| Deployment | Single binary | PHP stack |
|
||||
| External DB | No | Usually yes |
|
||||
| Landing Pages | ✅ | ❌ |
|
||||
| Password Protected Links | ✅ | Limited |
|
||||
| QR Analytics | ✅ | Partial |
|
||||
| UTM Builder | ✅ | ❌ |
|
||||
| Backup & Restore | ✅ | External tooling |
|
||||
| Audit Trail | ✅ | Limited |
|
||||
| Dynamic Redirect Rules | ❌ | ✅ |
|
||||
| Multi-domain | Planned | ✅ |
|
||||
| Ecosystem | Growing | Mature |
|
||||
|
||||
### Summary
|
||||
|
||||
Choose Shlink when:
|
||||
|
||||
* Multi-domain management is critical
|
||||
* Dynamic redirect rules are required
|
||||
* Enterprise-scale analytics matter
|
||||
|
||||
Choose BZOD when:
|
||||
|
||||
* Simplicity matters
|
||||
* Privacy matters
|
||||
* Minimal infrastructure matters
|
||||
* Landing pages are important
|
||||
|
||||
---
|
||||
|
||||
# BZOD vs YOURLS
|
||||
|
||||
YOURLS is the classic self-hosted URL shortener.
|
||||
|
||||
## Detailed Comparison
|
||||
|
||||
| Aspect | BZOD | YOURLS |
|
||||
| ------------- | ------------- | ---------- |
|
||||
| Language | Rust | PHP |
|
||||
| Architecture | Single binary | LAMP stack |
|
||||
| Plugins | Not required | Extensive |
|
||||
| Landing Pages | ✅ | Plugin |
|
||||
| QR Analytics | ✅ | Plugin |
|
||||
| Audit Logs | ✅ | Plugin |
|
||||
| Backup Tools | ✅ | External |
|
||||
| API | ✅ | ✅ |
|
||||
| Maintenance | Minimal | Moderate |
|
||||
|
||||
### Summary
|
||||
|
||||
YOURLS wins on:
|
||||
|
||||
* Age
|
||||
* Community
|
||||
* Plugin ecosystem
|
||||
|
||||
BZOD wins on:
|
||||
|
||||
* Simplicity
|
||||
* Deployment
|
||||
* Modern architecture
|
||||
* Integrated features
|
||||
|
||||
---
|
||||
|
||||
# BZOD vs Chhoto URL
|
||||
|
||||
Chhoto URL is the closest Rust-based competitor.
|
||||
|
||||
## Detailed Comparison
|
||||
|
||||
| Aspect | BZOD | Chhoto URL |
|
||||
| ---------------- | ------ | ---------- |
|
||||
| Language | Rust | Rust |
|
||||
| Landing Pages | ✅ | ❌ |
|
||||
| QR Codes | ✅ | ✅ |
|
||||
| QR Analytics | ✅ | ❌ |
|
||||
| Password Links | ✅ | ❌ |
|
||||
| Backup & Restore | ✅ | ❌ |
|
||||
| REST API | ✅ | JSON-RPC |
|
||||
| Audit Logs | ✅ | ❌ |
|
||||
| Analytics | Rich | Basic |
|
||||
| Binary Size | ~18 MB | Smaller |
|
||||
|
||||
### Summary
|
||||
|
||||
Choose Chhoto URL for:
|
||||
|
||||
* Maximum simplicity
|
||||
* Minimal footprint
|
||||
|
||||
Choose BZOD for:
|
||||
|
||||
* Feature completeness
|
||||
* Better administration
|
||||
* Better analytics
|
||||
|
||||
---
|
||||
|
||||
## Future Comparisons
|
||||
|
||||
Additional comparison sections may be added in the future for:
|
||||
|
||||
* Bitly
|
||||
* Dub
|
||||
* Pygmy
|
||||
* Krtk
|
||||
* Other self-hosted URL management platforms
|
||||
|
||||
---
|
||||
|
||||
## Conclusion
|
||||
|
||||
**BZOD is not merely a URL shortener.**
|
||||
|
||||
It is a lightweight URL management platform that combines:
|
||||
|
||||
* Link shortening
|
||||
* Multi-user support
|
||||
* Landing pages
|
||||
* QR services
|
||||
* User management
|
||||
* Built-in analytics
|
||||
* Backup framework
|
||||
* Audit logging
|
||||
* Moderation
|
||||
* Administrative dashboards
|
||||
|
||||
---
|
||||
|
||||
# BZOD vs Python-Based Solutions
|
||||
|
||||
Examples:
|
||||
|
||||
* Pygmy
|
||||
* Schort
|
||||
* ReducePy
|
||||
* Flask-based projects
|
||||
* FastAPI-based projects
|
||||
|
||||
### Python Advantages
|
||||
|
||||
* Rapid development
|
||||
* Familiar ecosystem
|
||||
|
||||
### BZOD Advantages
|
||||
|
||||
* No runtime dependency
|
||||
* Lower memory consumption
|
||||
* Single binary deployment
|
||||
* Operational tooling included
|
||||
* Better long-term maintenance characteristics
|
||||
|
||||
---
|
||||
|
||||
# Reliability & Testing
|
||||
|
||||
BZOD v0.5.0 includes a comprehensive automated validation suite.
|
||||
|
||||
Coverage includes:
|
||||
|
||||
* Unit tests
|
||||
* Integration tests
|
||||
* HTTP E2E tests
|
||||
* Business workflow tests
|
||||
* Upgrade validation tests
|
||||
* Backup/restore tests
|
||||
* Disaster recovery tests
|
||||
* Security tests
|
||||
* Concurrency tests
|
||||
* WAL recovery tests
|
||||
|
||||
The platform is validated using more than 90 automated tests.
|
||||
|
||||
---
|
||||
|
||||
# NX9 Platform Philosophy
|
||||
|
||||
BZOD follows the NX9 engineering philosophy:
|
||||
|
||||
* Linux-first
|
||||
* Rust-first
|
||||
* Self-hosted
|
||||
* Privacy-first
|
||||
* No telemetry
|
||||
* No vendor lock-in
|
||||
* No external dependencies
|
||||
* Single binary deployment
|
||||
|
||||
The goal is simple:
|
||||
|
||||
> Build software that remains useful, understandable, maintainable, and deployable decades into the future.
|
||||
|
||||
---
|
||||
|
||||
# Who Should Use BZOD?
|
||||
|
||||
BZOD is suitable for:
|
||||
|
||||
### Individuals
|
||||
|
||||
* Personal URL management
|
||||
* Homelabs
|
||||
* Self-hosted services
|
||||
|
||||
### Organizations
|
||||
|
||||
* Marketing campaigns
|
||||
* Internal redirects
|
||||
* Landing page hosting
|
||||
|
||||
### Governments
|
||||
|
||||
* Public service redirects
|
||||
* Long-term link preservation
|
||||
* Controlled infrastructure
|
||||
|
||||
### Service Providers
|
||||
|
||||
* Multi-tenant URL management
|
||||
* Managed short-link services
|
||||
* White-label deployments
|
||||
|
||||
---
|
||||
|
||||
# Conclusion
|
||||
|
||||
BZOD v0.5.0 is not simply a URL shortener.
|
||||
|
||||
It is a self-hosted URL Management Platform providing:
|
||||
|
||||
* Multi-user operation
|
||||
* Tenant isolation
|
||||
* URL shortening
|
||||
* Landing pages
|
||||
* QR generation
|
||||
* Analytics
|
||||
* Automation
|
||||
* Security
|
||||
* Backups
|
||||
* Audit logging
|
||||
* Moderation
|
||||
* User administration
|
||||
* Backup & restore
|
||||
* Health monitoring
|
||||
|
||||
into a single deployable Rust binary.
|
||||
within a single Rust binary deployment.
|
||||
|
||||
As part of the NX9 Platform, BZOD follows a simple principle:
|
||||
BZOD is designed for individuals, organizations, governments, educational institutions, and service providers that require full ownership of their links, analytics, and infrastructure.
|
||||
|
||||
> Own your links. Own your data. Own your infrastructure.
|
||||
> Own your links.
|
||||
> Own your data.
|
||||
> Own your infrastructure.
|
||||
|
||||
No telemetry. No vendor lock-in. No unnecessary complexity.
|
||||
|
||||
For users seeking privacy, simplicity, ownership, and long-term sustainability, BZOD offers a compelling alternative to both cloud SaaS platforms and traditional self-hosted URL shorteners.
|
||||
Reference in new issue
Block a user