From 58c0af651057760911fe158e74148b37ff6873a8 Mon Sep 17 00:00:00 2001 From: Sunil Thakare Date: Mon, 29 Jun 2026 17:12:43 +0530 Subject: [PATCH] docs: refresh README for v0.5.3 - 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 --- README.md | 2043 ++++++++++++++++++++++++++++++----------------------- 1 file changed, 1143 insertions(+), 900 deletions(-) diff --git a/README.md b/README.md index 8dfba25..19ba080 100644 --- a/README.md +++ b/README.md @@ -1,359 +1,608 @@ # BZOD -> Self-hosted Multi-User URL Management, Landing Page and QR Analytics Platform written in Rust. +> **Self-hosted Multi-User URL Management Platform with Landing Pages, QR Analytics, Global Namespace Integrity, and Operational Tooling — written in Rust.** ![Rust](https://img.shields.io/badge/Rust-Stable-orange) ![SQLite](https://img.shields.io/badge/SQLite-Embedded-blue) -![License](https://img.shields.io/badge/License-MIT%20%2F%20Apache--2.0-green) -![Version](https://img.shields.io/badge/Version-v0.5.1-purple) +![Platform](https://img.shields.io/badge/Platform-Linux-lightgrey) +![License](https://img.shields.io/badge/License-MIT%20OR%20Apache--2.0-green) +![Version](https://img.shields.io/badge/Version-v0.5.3-purple) -BZOD combines URL shortening, landing pages, QR code generation, analytics, moderation, audit logging, backup & restore workflows, tenant isolation, and administrative tooling into a single deployable binary powered entirely by SQLite. +[![GitHub](https://img.shields.io/badge/GitHub-thakares%2Fbzod-181717?logo=github)](https://github.com/thakares/bzod) +[![Codeberg](https://img.shields.io/badge/Codeberg-thakares%2Fbzod-2185D0?logo=codeberg)](https://codeberg.org/thakares/bzod) -Designed for: +BZOD is a modern, lightweight, self-hosted platform for managing short URLs, landing pages, QR codes, analytics, and multi-user deployments. -* Homelabs -* Small Businesses -* Enterprises -* Educational Institutions -* Government Agencies -* Internal IT Platforms -* Self-Hosted Enthusiasts +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. -BZOD enables complete ownership of: - -* Links -* Analytics -* Users -* QR Codes -* Landing Pages -* Operational Data - -without requiring PostgreSQL, Redis, Elasticsearch, Kubernetes, or external SaaS services. +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? +## Why BZOD? -Most URL shorteners focus only on redirects and click tracking. +Most URL shorteners focus solely on redirects. -BZOD is designed as a complete self-hosted platform that combines: +BZOD takes a broader approach by combining URL management with operational tooling required for real-world production deployments. -* URL Management -* Landing Pages -* QR Codes -* Analytics -* User Management -* Audit Logging -* Moderation -* Backup & Restore -* Disaster Recovery -* Administrative Tooling +Core capabilities include: -within a single deployable application. +- 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 goal is operational simplicity without sacrificing reliability, security, or ownership. - ---- -## Runtime Efficiency (v0.5.1) - -| Metric | Value | -|---------------------|------------| -| Binary Size | 11 MB | -| RSS Memory | 11.8 MB | -| Peak RSS | 11.8 MB | -| CPU Idle | 0.02% | -| Swap Usage | 0 KB | -| PIDs | 7 | - -**On a typical 32 GB server:** -- Memory usage: ~0.04% -- No swapping -- Plenty of headroom - -BZOD runs closer to a lightweight infrastructure service than a typical web application. - -# Design Philosophy - -BZOD is built around five principles: - -## 1. Single Binary Deployment - -A production deployment should not require: - -* Kubernetes -* Elasticsearch -* Redis -* Multiple microservices - -A single binary should be capable of serving the entire platform. +The result is a platform that is easy to deploy, lightweight to operate, and entirely controlled by its owner. --- -## 2. SQLite First +## Designed For -SQLite offers: +BZOD is suitable for: -* Simplicity -* Reliability -* Easy Backups -* Easy Recovery -* Minimal Operational Overhead - -BZOD embraces SQLite instead of treating it as a development-only database. +- 🏠 Homelabs +- 🚀 Startups +- 🏢 Small & Medium Businesses +- 🏭 Enterprise Deployments +- 🎓 Educational Institutions +- 🏛 Government Organizations +- 🌐 Internal Corporate Platforms +- ❤️ Self-hosting Enthusiasts --- -## 3. Self-Hosted Ownership +## Complete Ownership -All data belongs to the operator. +With BZOD, you own everything: -This includes: +- URLs +- Landing Pages +- QR Codes +- Analytics +- Users +- Sessions +- API Tokens +- Audit Logs +- System Configuration +- Backups -* URLs -* Analytics -* User Accounts -* QR Codes -* Landing Pages -* Audit Logs +No mandatory cloud services. -No telemetry is required. +No telemetry. + +No vendor lock-in. + +No recurring subscription fees. --- -## 4. Multi-Tenant Isolation +## Runtime Efficiency (v0.5.3) -Each tenant receives isolated storage and analytics. +| 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) | -The failure or compromise of one tenant must not affect another tenant. +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) | --- -## 5. Recoverability +# Deployment Options -A platform that cannot be restored is not production ready. +BZOD supports multiple deployment methods. -BZOD includes: +- Docker +- Docker Compose +- Native Linux Binary +- Systemd Service +- Reverse Proxy (Nginx, Caddy, Traefik, NPM) -* Backup Workflows -* Restore Workflows -* Disaster Recovery Procedures -* Upgrade Validation -* Integrity Checks - -as first-class features. +No Kubernetes is required. --- -# Key Features - -## URL Management - -* Short URLs -* Custom Slugs -* Bulk Operations -* Password-Protected Links -* Expiring Links -* Smart Preview Pages -* QR Code Generation -* QR Downloads (PNG) -* QR Downloads (SVG) - ---- - -## Landing Pages - -* Hosted Landing Pages -* Custom Slugs -* QR Support -* Analytics Integration -* Shareable Campaign Pages - ---- - -## Analytics - -* Visitor Tracking -* QR Scan Analytics -* Browser Detection -* Referrer Analysis -* Daily Statistics -* Monthly Statistics -* CSV Export -* JSON Export -* Raw Visitor Logs - ---- - -## Multi-User Platform - -* User Accounts -* User Quotas -* Session Management -* API Tokens -* Tenant Isolation -* Ownership Validation -* Administrative Controls - ---- - -## Administration - -* User Management -* Moderation -* Audit Logs -* Session Administration -* Quota Management -* Backup Management -* Health Dashboard -* Namespace Diagnostics - ---- - -## Operations - -* Backup & Restore -* Disaster Recovery -* Health Monitoring -* Upgrade Validation -* Migration Framework -* WAL-Enabled SQLite Databases -* Registry Integrity Validation - ---- - -# Global Namespace Integrity - -BZOD enforces a platform-wide slug namespace. - -The following resources cannot share the same slug: - -* Administrator URLs -* Administrator Landing Pages -* User URLs -* User Landing Pages +# Docker Example: -Valid: +```yaml +services: + bzod: + image: ghcr.io/thakares/bzod:latest + container_name: bzod -```text -/company -/docs -/about + restart: unless-stopped + + ports: + - "8654:8654" + + volumes: + - ./data:/app/data + + environment: + - RUST_LOG=info ``` -Invalid: +Start: -```text -Admin URL: -/docs - -User Landing Page: -/docs -``` - -Namespace conflicts are automatically detected during: - -* Creation -* Startup -* Restore -* Upgrade -* Validation - -This guarantees predictable routing behavior across the platform. - ---- - -# Global Slug Registry - -BZOD uses a centralized registry to manage all public routes. - -Stored in: - -```text -system.db -``` - -Registry table: - -```text -global_slugs -``` - -Tracks: - -* slug -* owner_user_id -* target_type -* target_id -* status - -The registry acts as the authoritative source of truth for: - -* Redirect Resolution -* Landing Page Routing -* QR Generation -* Ownership Validation -* Namespace Enforcement - ---- - -# Architecture - -```text - Browser - │ - ▼ - ┌──────────────────┐ - │ Axum Server │ - └────────┬─────────┘ - │ - ┌──────────────────┼──────────────────┐ - │ │ │ - ▼ ▼ ▼ - - users.db system.db User Databases - - Accounts Global Slugs content.db - Sessions Moderation analytics.db - API Tokens Audit Events - Quotas Settings +```bash +docker compose up -d ``` --- -# High-Level Request Flow +# Native Installation -```text -Client Request - │ - ▼ -Axum Router - │ - ▼ -Global Slug Registry Lookup - │ - ▼ -Ownership Resolution - │ - ▼ -Tenant Database - │ - ▼ -Response +Download the latest release. + +```bash +chmod +x bzod + +sudo mv bzod /usr/local/bin/ +``` + +Verify: + +```bash +bzod --help ``` --- -# Data Layout +# Initialize + +Create the administrator. + +```bash +bzod create-admin +``` + +Start the server. + +```bash +bzod serve +``` + +Default server: + +``` +http://localhost:8654 +``` + +--- + +# Systemd Service + +Example: + +```ini +[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: + +```bash +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 ```text +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. + +```bash +bzod doctor +``` + +Checks include: + +- SQLite Integrity +- WAL Status +- Foreign Keys +- Registry Integrity +- Namespace Consistency +- Missing Databases +- Missing Records +- Ownership Validation + +--- + +# Registry Repair + +Preview repairs. + +```bash +bzod repair registry --dry-run +``` + +Repair all orphaned entries. + +```bash +bzod repair registry --force +``` + +Repair a single slug. + +```bash +bzod repair registry \ + --slug my-page \ + --force +``` + +Repairs are: + +- Transaction Safe +- Atomic +- Non-destructive +- Fully Logged + +--- + +# Backup + +Platform Backup + +```bash +bzod backup +``` + +Restore + +```bash +bzod restore backup.tar.gz +``` + +--- + +# User Backup + +Backup a single tenant. + +```bash +bzod backup-user \ + user@example.com +``` + +Restore. + +```bash +bzod restore-user \ + backup.tar.zst +``` + +--- + +# Statistics + +View platform statistics. + +```bash +bzod stats +``` + +Displays: + +- Users +- URLs +- Landing Pages +- QR Codes +- Analytics +- Databases +- Storage Usage + +--- + +# URL Management + +Create a short URL. + +```bash +bzod shorten \ + https://example.com +``` + +Expand a short code. + +```bash +bzod expand abc123 +``` + +--- + +# Administrator Commands + +Create Administrator + +```bash +bzod create-admin +``` + +List Users + +```bash +bzod list-users +``` + +Disable User + +```bash +bzod disable-user alice +``` + +Enable User + +```bash +bzod enable-user alice +``` + +Delete User + +```bash +bzod delete-user alice +``` + +Reset Password + +```bash +bzod reset-password alice +``` + +--- + +# Admin Migration + +Preview migration. + +```bash +bzod admin-migrate 2 --dry-run +``` + +Execute migration. + +```bash +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. + +```text + Browser / API Client + │ + ▼ + ┌────────────────────┐ + │ Axum Router │ + └─────────┬──────────┘ + │ + ┌───────────────────┼───────────────────┐ + ▼ ▼ ▼ + + Authentication Business Logic REST API + + │ │ │ + └──────────────┬────┴───────────────────┘ + ▼ + + Global Slug Registry + + │ + ▼ + + Tenant Resolution Layer + + │ + ┌──────────────┴───────────────┐ + ▼ ▼ + + Administrator Standard Users + + │ │ + + ▼ ▼ + + admin/*.db users//*.db +``` + +--- + +# Multi-Tenant Architecture + +BZOD is designed around complete tenant isolation. + +Each user owns independent databases. + +``` data/ + ├── admin/ -│ ├── users.db -│ ├── system.db │ ├── admin.db -│ └── admin.db-wal +│ ├── users.db +│ └── system.db │ └── users/ ├── 1/ @@ -369,551 +618,288 @@ data/ └── ... ``` ---- +Benefits include: -# Core Databases - -## users.db - -Stores: - -* Users -* Password Hashes -* Sessions -* API Tokens -* Quotas -* User Status +- Complete tenant isolation +- Independent backups +- Faster restores +- Simplified migrations +- Better security +- Reduced blast radius --- -## system.db +# Global Namespace Registry -Stores: +Unlike many URL shorteners, BZOD guarantees that every public slug is globally unique. -* Global Slug Registry -* Moderation Events -* Audit Events -* Reserved Slugs -* Settings -* System Metadata +Examples: ---- - -## Tenant Databases - -Every user receives isolated databases. - -### content.db - -Stores: - -* URLs -* Landing Pages -* Metadata -* QR Relationships -* Preview Data - -### analytics.db - -Stores: - -* Visits -* QR Scans -* Referrers -* User Agents -* Aggregated Statistics - -### profile.db - -Stores: - -* User Preferences -* Tenant Metadata -* Account Configuration - ---- - -# Feature Matrix - -| Feature | Status | -| --------------------------- | ------ | -| URL Shortening | ✅ | -| Custom Slugs | ✅ | -| Landing Pages | ✅ | -| QR Codes | ✅ | -| QR Analytics | ✅ | -| PNG Downloads | ✅ | -| SVG Downloads | ✅ | -| Password Protection | ✅ | -| Link Expiration | ✅ | -| Analytics Dashboard | ✅ | -| CSV Export | ✅ | -| JSON Export | ✅ | -| REST API | ✅ | -| Web UI | ✅ | -| CLI | ✅ | -| Multi-User Support | ✅ | -| User Quotas | ✅ | -| Session Management | ✅ | -| API Tokens | ✅ | -| Audit Logging | ✅ | -| Moderation | ✅ | -| Global Namespace Integrity | ✅ | -| Ownership Isolation | ✅ | -| Dashboard Parity | ✅ | -| Backup & Restore | ✅ | -| Disaster Recovery | ✅ | -| Health Monitoring | ✅ | -| Upgrade Validation | ✅ | -| Restore Collision Detection | ✅ | -| Stale Reservation Recovery | ✅ | - ---- -# Screenshots - -## Administrator Dashboard - -Features: - -* Platform Statistics -* User Management -* Health Monitoring -* Moderation -* Audit Events -* Namespace Diagnostics - -```text -screenshots/dashboard.png +``` +/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. + --- -## URL Management +# Registry Validator -Features: +The Registry Validator introduced in v0.5.3 is responsible for maintaining namespace integrity. -* URL Creation -* QR Preview -* PNG Download -* SVG Download -* Analytics -* Export Functions +It validates: -```text -screenshots/short-url-panel.png +- 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 ``` ---- - -## Landing Pages - -Features: - -* Landing Page Creation -* Slug Management -* QR Support -* Analytics -* Public Publishing - -```text -screenshots/landing-page-panel.png -``` - ---- - -## Settings - -Features: - -* Password Management -* Session Control -* API Tokens -* User Preferences - -```text -screenshots/settings.png -``` - ---- - -## Health Dashboard - -Features: - -* Database Health -* Namespace Validation -* Storage Information -* System Diagnostics - -```text -screenshots/server-status.png -``` - ---- - -# Installation - -BZOD can be deployed using: - -* Docker -* Docker Compose -* Native Binary -* Systemd Service - -Supported Platforms: - -* Linux -* Debian -* Ubuntu -* Arch Linux -* Rocky Linux -* Alma Linux -* Fedora - ---- - -# Docker Deployment - -Build: +Supported commands: ```bash -docker compose build +bzod repair registry --dry-run + +bzod repair registry --force + +bzod repair registry --slug my-page --dry-run + +bzod repair registry --slug my-page --force ``` -Start: +Characteristics: -```bash -docker compose up -d -``` - -Check status: - -```bash -docker compose ps -``` - -View logs: - -```bash -docker compose logs -f -``` - -Stop: - -```bash -docker compose down -``` +- Transaction-safe +- Atomic +- Idempotent +- Fully logged +- Read-only preview +- Explicit administrator confirmation --- -# Docker Compose Example +# Health Diagnostics -```yaml -services: - bzod: - build: . - container_name: bzod - restart: unless-stopped +The Doctor subsystem continuously validates platform health. - ports: - - "8654:8654" +Checks include: - volumes: - - ./data:/app/data +## Database Health - environment: - - BZOD_BASE_URL=https://bzo.in -``` +- SQLite Integrity +- WAL Mode +- Foreign Keys +- Schema Version --- -# Native Installation +## Namespace Health -Clone repository: +- Registry Consistency +- Ownership Validation +- Missing Records +- Duplicate Entries -```bash -git clone https://github.com/thakares/nx9-url-shortener.git -cd nx9-url-shortener -``` +--- -Build: +## Operational Health -```bash -cargo build --release -``` - -Binary: - -```text -target/release/bzod -``` +- Tenant Databases +- Administrator Databases +- Registry References +- Restore Compatibility Run: -```bash -./target/release/bzod serve -``` - ---- - -# Systemd Service - -Example: - -```ini -[Unit] -Description=BZOD URL Management Platform -After=network.target - -[Service] -User=bzod -Group=bzod - -WorkingDirectory=/opt/bzod - -ExecStart=/opt/bzod/bzod serve - -Restart=always - -[Install] -WantedBy=multi-user.target -``` - -Enable: - -```bash -sudo systemctl enable bzod -sudo systemctl start bzod -``` - -Status: - -```bash -sudo systemctl status bzod -``` - ---- - -# Command Line Interface - -BZOD includes an extensive command-line interface. - -Display help: - -```bash -bzod --help -``` - -Available commands: - -```text -serve -backup -restore -migrate -stats -validate -doctor - -shorten -expand - -create-admin - -create-user -delete-user -disable-user -enable-user -reset-password -list-users - -backup-user -restore-user -``` - ---- - -# Example Commands - -Create administrator: - -```bash -bzod create-admin -``` - -Create user: - -```bash -bzod create-user -``` - -List users: - -```bash -bzod list-users -``` - -Disable user: - -```bash -bzod disable-user -``` - -Backup system: - -```bash -bzod backup -``` - -Restore system: - -```bash -bzod restore backup.tar.gz -``` - -Health diagnostics: - ```bash bzod doctor ``` -Statistics: +--- -```bash -bzod stats -``` +# Security Model -Shorten URL: +BZOD follows a defense-in-depth approach. -```bash -bzod shorten https://example.com -``` +Authentication -Expand URL: +- Username & Password +- Argon2 Password Hashing +- Secure Cookies +- API Tokens -```bash -bzod expand abc123 -``` +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 provides a RESTful JSON API. +BZOD includes a REST API suitable for automation. -Typical operations: +Current capabilities include: -* Create URLs -* Update URLs -* Delete URLs -* Retrieve Analytics -* Export Data -* Manage Landing Pages +- URL Management +- Landing Pages +- Analytics +- QR Codes +- Authentication +- Administration -Example: +Future API expansions are planned for: -```http -POST /api/urls -``` - -```json -{ - "destination": "https://example.com", - "code": "example" -} -``` - -Response: - -```json -{ - "success": true, - "code": "example" -} -``` - -See: - -```text -docs/API.md -``` - -for full API documentation. +- Webhooks +- Batch Operations +- Tenant Statistics +- OpenAPI Documentation --- -# Security +# Backup & Restore -Security features include: +Backups are first-class features. -* Argon2 Password Hashing -* Session Management -* CSRF Protection -* Ownership Validation -* Tenant Isolation -* Namespace Integrity -* Audit Logging +Platform Backup -Users cannot: - -* Access other user resources -* Access other user analytics -* Export other user data -* Modify other user records - -For details see: - -```text -docs/SECURITY.md +```bash +bzod backup ``` ---- +Platform Restore -# Backup & Recovery - -BZOD treats recoverability as a core feature. - -Supported: - -* Full System Backup -* Full System Restore -* Per User Backup -* Per User Restore -* Disaster Recovery -* Upgrade Validation -* Collision Detection - -See: - -```text -docs/BACKUP_RESTORE.md +```bash +bzod restore backup.tar.gz ``` +User Backup + +```bash +bzod backup-user alice +``` + +User Restore + +```bash +bzod restore-user alice-backup.tar.zst +``` + +Features: + +- Backup Manifest +- Validation +- Integrity Checks +- Restore Verification +- Automatic Database Migration +- WAL Compatibility + --- # Testing -BZOD includes an extensive automated validation suite. +BZOD includes extensive automated testing. -Validation Categories: - -* Unit Tests -* Integration Tests -* HTTP E2E Tests -* Security Tests -* Business Workflow Tests -* Backup Tests -* Restore Tests -* Disaster Recovery Tests -* Upgrade Validation Tests -* Namespace Integrity Tests -* Ownership Isolation Tests -* Dashboard Parity Tests -* QR Endpoint Tests -* Concurrency Tests -* WAL Recovery Tests - -Run validation: +Validation is performed using: ```bash cargo fmt --check @@ -921,181 +907,450 @@ cargo fmt --check cargo clippy --all-targets -- -D warnings cargo test --all-targets -- --nocapture -``` -Build production release: - -```bash cargo build --release ``` -See: +Test coverage includes: -```text -docs/TESTING.md -``` - ---- - -# Documentation - -| Document | Description | -| ----------------- | ---------------------------- | -| ADMIN_GUIDE.md | Administrator Operations | -| API.md | REST API Reference | -| ARCHITECTURE.md | System Architecture | -| BACKUP_RESTORE.md | Backup & Recovery | -| CHANGELOG.md | Version History | -| CLI.md | Command Reference | -| COMPARISON.md | Comparison With Alternatives | -| DATABASES.md | Database Architecture | -| DOCKER-Deploy.md | Docker Deployment | -| INSTALL.md | Installation Guide | -| MULTI_USER.md | Multi-Tenant Architecture | -| RELEASE-NOTES.md | Release Notes | -| SECURITY.md | Security Model | -| TESTING.md | Testing Guide | -| UPGRADE.md | Upgrade Procedures | +- 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 -```text +``` src/ -├── analytics/ + ├── auth/ -├── charts/ ├── cli/ ├── db/ ├── jobs/ -├── models/ +├── middleware/ ├── services/ ├── templates/ ├── utils/ -└── web/ +├── web/ templates/ + tests/ + docs/ + www/ ``` -Current codebase: +The codebase is organized by responsibility, making it straightforward to extend without introducing unnecessary complexity. -```text -~200 files -Rust -SQLite -Axum -Askama -``` +--- + +# 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 Shortener | -| ------------------------ | ---- | ------------------------- | -| URL Shortening | ✅ | ✅ | -| Landing Pages | ✅ | ❌ | -| QR Analytics | ✅ | Limited | -| Multi-User Support | ✅ | Limited | -| Audit Trail | ✅ | Rare | -| Backup & Restore | ✅ | Rare | -| Ownership Isolation | ✅ | Rare | -| Namespace Integrity | ✅ | Rare | -| Health Diagnostics | ✅ | Rare | -| Single Binary Deployment | ✅ | Varies | - -For detailed comparisons: - -```text -docs/COMPARISON.md -``` +| 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 | --- -# Release Status +# Production Ready -## v0.5.1 +BZOD has been designed for production deployments with emphasis on: -Namespace Integrity & Multi-User Hardening Release +- Operational simplicity +- Reliability +- Maintainability +- Recoverability +- Security +- Performance -Status: - -```text -Production Ready -``` - -Validated: - -* Formatting -* Static Analysis -* Release Builds -* Namespace Integrity -* Ownership Isolation -* Dashboard Parity -* QR Endpoints -* Routing -* Upgrade Validation -* Backup & Restore -* Disaster Recovery -* Security Validation +It provides enterprise-grade operational tooling while remaining lightweight enough for homelab deployments. --- - # Roadmap -Future areas of exploration: +BZOD follows a pragmatic roadmap focused on operational reliability, maintainability, and long-term ownership. -* SSO Integration -* OIDC Authentication -* LDAP Integration -* Enhanced API Tokens -* Scheduled Reporting -* Additional Export Formats -* Enhanced Moderation Tools -* Advanced Analytics +Rather than chasing feature count, development emphasizes quality, stability, and self-hosting excellence. -Roadmap priorities remain guided by: +--- -* Operational Simplicity -* Reliability -* Recoverability -* Self-Hosting +## 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 -Dual Licensed: +Licensed under either of the following, at your option: -* MIT License -* Apache License 2.0 +- MIT License +- Apache License 2.0 -See: - -```text -LICENSE-MIT -LICENSE-APACHE -``` +See the LICENSE files for full details. --- # Repository -GitHub: +GitHub -```text -https://github.com/thakares/nx9-url-shortener -``` +https://github.com/thakares/bzod -Codeberg: +Codeberg -```text -https://codeberg.org/thakares/nx9-url-shortener -``` +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. --- @@ -1103,26 +1358,14 @@ https://codeberg.org/thakares/nx9-url-shortener **Sunil Thakare** -BZOD is developed as a practical, self-hosted URL management platform focused on simplicity, ownership, and recoverability. +GitHub: https://github.com/thakares + +Codeberg: https://codeberg.org/thakares --- -# Final Thoughts +# BZOD -BZOD is not merely a URL shortener. - -It is a self-hosted platform for: - -* URL Management -* Landing Pages -* QR Analytics -* Multi-Tenant Operations -* Administrative Control -* Data Ownership -* Backup & Recovery - -while remaining deployable as a single Rust application backed by SQLite. - -The goal is simple: - -> Own your links. Own your analytics. Own your data. +**Own your links. +Own your analytics. +Own your infrastructure.** \ No newline at end of file