diff --git a/README.md b/README.md index ce5c244..82a3e85 100644 --- a/README.md +++ b/README.md @@ -1,613 +1,209 @@ -# nx9-url-shortener (the BZOD daemon) +# BZOD -**A lightweight, self-hosted URL management platform written in Rust.** +> Self-hosted Multi-User URL Management Platform written in Rust. -BZOD combines URL shortening, landing pages, QR code generation, password-protected links, smart preview pages, analytics, audit logging, lifecycle management, backup/restore, and API automation into a single self-hosted application with zero external service dependencies. +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. -Built with Rust, SQLite, Axum, and Askama, BZOD is designed for individuals, organizations, homelab operators, government agencies, and businesses that want complete ownership of their links, analytics, and branding. +Designed for homelabs, organizations, businesses, educational institutions, and government agencies that require complete ownership of their links, analytics, and operational data. --- -## License -Licensed under either of +## Why BZOD? -- Apache License, Version 2.0 - ([LICENSE](LICENSE-APACHE)) - Default -- MIT License - ([LICENSE-MIT](LICENSE-MIT)) +Most URL shorteners focus only on redirects and click tracking. -at your option. +BZOD is designed as a complete self-hosted platform with: -### Contribution - -Unless you explicitly state otherwise, any contribution intentionally -submitted for inclusion in this project shall be dual licensed under -the terms above without any additional terms or conditions. - -[![License: MIT OR Apache-2.0](https://img.shields.io/badge/license-MIT%20OR%20Apache--2.0-blue.svg)](#license) ---- -## Highlights - -### v0.4.0 - -* Raw visitor activity logs -* Analytics drill-down pages -* Visitor pagination -* Advanced sliding-window pagination -* CSV analytics export -* JSON analytics export -* Date-filtered analytics -* Landing page analytics -* Human-readable custom slugs -* Root landing page support -* UTM campaign builder -* Built-in backup and restore -* CLI shorten command -* CLI expand command +* Multi-user architecture +* Tenant isolation +* Landing pages * QR code generation -* Password-protected links -* Smart preview pages -* Analytics dashboard +* Analytics * Audit logging -* Health monitoring -* Human-readable custom slugs -* Root landing page support -* Landing page custom slugs -* UTM campaign builder -* Built-in backup and restore -* CLI shorten command -* CLI expand command -* QR code generation (PNG/SVG) +* 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 -* Analytics dashboard -* Audit logging -* Health monitoring +* QR code generation -## Added in v0.5.0 - -- Single binary deployment -- Multi-user platform -- Per-user database isolation -- Global slug namespace -- URL Shortener -- Landing Pages -- QR Codes (PNG + SVG) -- Analytics -- User Management -- Moderation -- Session Management -- Backup & Restore -- Audit Logging -- Quotas -- WAL Enabled SQLite -- CSRF Protection -- RBAC Authorization -- Migration Framework - ---- - -## Feature Matrix v0.5.0 - -| Feature | Status | -|---------------------------|--------| -| URL Shortening | ✅ | -| Custom Slugs | ✅ | -| Landing Pages | ✅ | -| Landing Page Custom Slugs | ✅ | -| QR Code Generation | ✅ | -| QR Analytics | ✅ | -| Password-Protected Links | ✅ | -| Smart Preview Pages | ✅ | -| Link Expiration | ✅ | -| One/Multi-Time Links | ✅ | -| Audit Trail | ✅ | -| Analytics Dashboard | ✅ | -| Health Monitoring | ✅ | -| REST API | ✅ | -| Backup & Restore | ✅ | -| UTM Campaign Builder | ✅ | -| CLI Automation | ✅ | -| Raw Visitor Logs | ✅ | -| Analytics Export (CSV) | ✅ | -| Analytics Export (JSON) | ✅ | -| Analytics Drill-Down | ✅ | -| Date Range Analytics | ✅ | -| Advanced Pagination | ✅ | - Multi-User Administration | ✅ | -| Geo Analytics | 🚧 | -| SSO | 🚧 | - ---- -## One-Command Installation (Recommended) - -```bash -curl -fsSL https://bzo.in/deploy.sh | sudo bash -``` ---- -## Features - -### URL Shortening - -Create compact short URLs using automatically generated hexadecimal identifiers. - -Example: - -```text -https://your-domain/1bb170 -``` - ---- -## Design Principles - -BZOD is intentionally designed around a few principles: - -- Self-hosted first -- SQLite-first architecture -- Minimal operational complexity -- Recovery over convenience -- Human-readable administration -- No external service dependencies -- No vendor lock-in - -Features are added only when they improve usability without increasing architectural complexity. -### Custom Slugs - -Create memorable human-readable links. - -Examples: - -```text -https://your-domain/!office -https://your-domain/!home -https://your-domain/!site -https://your-domain/!project-alpha -``` - -Features: - -* Case-insensitive uniqueness -* Lowercase normalization -* Human-readable URLs -* No database schema changes -* Fully compatible with existing short codes - -Examples: - -```text -!office -!home -!warehouse -!meeting-room -!client_a -``` -## Practical Examples - -Generated URL -``` -https://bzo.in/1b926e -``` -Custom Slug -``` -https://bzo.in/!myoffice -``` -Landing Page -``` -https://bzo.in/p/!company-profile -``` ---- -## CLI -``` -bzod shorten https://example.com -bzod shorten https://example.com --slug !office -bzod expand !office -``` ---- ### Landing Pages -Create standalone landing pages hosted directly by BZOD. +* Hosted landing pages +* Custom slugs +* Analytics +* QR code support -Generated page: - -```text -https://your-domain/p/1a2b -``` - -Custom slug page: - -```text -https://your-domain/p/!company-profile -https://your-domain/p/!product-launch -``` - -Features: - -* Raw HTML support -* SEO slug support -* Published / Draft states -* Custom paths -* Open Graph metadata - ---- -### CLI Commands - -Core commands -```bash -bzod serve -bzod create-admin -bzod doctor -bzod stats -``` -URL management -```bash -bzod shorten https://example.com -bzod shorten https://example.com --slug !campaign -bzod expand 1bb170 -bzod expand !campaign -``` -Maintenance -```bash -bzod backup -bzod restore --file backup_20250614.tar.gz -bzod migrate -``` -### QR Code Generation - -Generate QR codes for every short URL. - -Supported formats: - -* PNG -* SVG - -Features: - -* Downloadable QR assets -* QR scan analytics -* Bulk QR export -* Print-friendly SVG output - ---- - -### Password-Protected Links - -Protect sensitive links using Argon2id password hashing. - -Features: - -* Password gate -* Secure session handling -* Access restrictions -* Audit logging - ---- - -### Smart Preview Pages - -Display branded preview pages before redirecting visitors. - -Features: - -* Custom title -* Description -* Logo support -* Open Graph metadata -* Social sharing previews - ---- - -### Link Lifecycle Management - -Control link validity. - -Features: - -* Expiration dates -* One-time links -* Access limits -* Administrative disable -* Automated expiry jobs - ---- - -### UTM Campaign Builder - -Append campaign tracking parameters when creating links. - -Supported parameters: - -```text -utm_source -utm_medium -utm_campaign -``` - -Example output: - -```text -https://example.com/page?utm_source=email&utm_medium=newsletter&utm_campaign=launch -``` - -No additional database schema changes are required. - ---- ### Analytics -Track: - -* Total visits -* Unique visitors -* QR scans -* Countries -* Referrers -* User agents -* Daily statistics -* Monthly statistics -* Yearly statistics - -Analytics drill-down includes: - -* Raw visitor activity logs -* Visitor IP addresses -* Country information -* Referrer tracking +* Visitor tracking +* QR scan analytics * Browser detection -* Raw User-Agent display -* Date range filtering +* Referrer analysis +* Daily and monthly statistics * CSV export * JSON export -* Paginated visitor logs +* Raw visitor logs -Analytics Export +### Multi-User Platform -Export analytics data directly from the administration interface. - -Supported formats: - -* CSV -* JSON - -Features: - -* Memory-safe export handling -* Date-range filtering -* Downloadable files -* Compatible with spreadsheets and BI tools - ---- -## Stability - -BZOD v0.5.0 has passed: - -- Unit Tests -- Integration Tests -- HTTP E2E Tests -- Authentication Migration Tests -- Upgrade Validation Tests -- Backup/Restore Tests -- Disaster Recovery Tests -- Security Tests -- Concurrency Tests -- Business Workflow Tests -- WAL Recovery Tests - -Total automated coverage exceeds 90 tests. - -### Audit Trail - -Track administrative activity. - -Recorded events include: - -* Login -* Logout -* URL creation -* URL updates -* URL deletion -* Backup creation -* Restore operations -* QR exports -* Configuration changes - ---- - -### Administrative Dashboard - -Web-based management interface. - -Features: - -* URL registry -* Landing pages -* QR management -* Analytics -* API token management -* Audit logs -* Backup utilities -* Restore utilities -* Health monitoring -* Server diagnostics - ---- - -### REST API - -REST API support for automation and integrations. - -Endpoint prefix: - -```text -/api/v1/* -``` - -Supports: - -* URL creation -* URL management -* Landing pages -* QR generation -* Analytics access - ---- - -### CLI Automation - -Create and manage links directly from the command line. - -Examples: - -Create automatic code: - -```bash -bzod shorten https://example.com -``` - -Create custom slug: - -```bash -bzod shorten https://example.com --slug !office -``` - -Expand code: - -```bash -bzod expand 1bb170 -``` - -Expand custom slug: - -```bash -bzod expand !office -``` - ---- - -### Backup & Restore - -BZOD includes integrated backup and restore functionality through both the CLI and Web UI. - -CLI: - -```bash -bzod backup -bzod restore --file backup.tar.gz -``` - -Web UI: - -```text -Settings → Maintenance & DB Utilities -``` - -Features: - -* Compressed tar.gz backups -* Full database restoration -* Backup validation -* Disaster recovery support -* No external tools required - -Protected databases: - -* admin.db -* content.db -* analytics.db -* system.db - ---- - -### Security - -* Password-protected administration -* Password-protected links -* Argon2id password hashing -* CSRF protection +* User accounts +* User quotas * Session management -* API token authentication -* Audit logging -* Access controls +* API tokens +* Tenant isolation +* Administrative controls ---- +### Administration -### Self-Hosted +* User management +* Moderation +* Audit logs +* Session administration +* Quota management +* Backup management +* Health dashboard -No external services required. +### Operations -Dependencies: - -* Rust -* SQLite -* Docker (optional) - -No: - -* React -* Node.js -* Redis -* PostgreSQL -* MongoDB -* Kubernetes -* SaaS dependencies +* Backup & restore +* Disaster recovery +* Health monitoring +* Upgrade migrations +* WAL-enabled SQLite databases --- ## Architecture -### Databases - -BZOD uses four SQLite databases. - -| Database | Purpose | -| ------------ | ------------------------------ | -| admin.db | Users, sessions, API keys | -| content.db | URLs, landing pages, metadata | -| analytics.db | Visits, QR scans, statistics | -| system.db | Audit events, jobs, monitoring | - ---- - -## Initial Setup - -### Native Installation - -```bash -cargo run -- create-admin +```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 ``` -### Docker +### Data Layout -```bash -docker exec -it bzod bzod create-admin +```text +data/ +├── system.db +├── users.db +│ +├── admin/ +│ ├── content.db +│ └── analytics.db +│ +└── users/ + ├── 2/ + │ ├── content.db + │ └── analytics.db + │ + ├── 3/ + │ ├── content.db + │ └── analytics.db + │ + └── ... ``` ---- +### Core Databases -## Disaster Recovery Validation +#### users.db -The backup and restore system has been validated through a complete recovery workflow. +Stores: -Validation procedure: - -1. Create backup archive -2. Stop application -3. Restore backup -4. Restart application -5. Verify application integrity - -Verified components: - -* URL registry -* Landing pages -* Analytics -* Audit logs +* Users +* Password hashes +* Sessions * API tokens -* QR assets +* Quotas + +#### system.db + +Stores: + +* Global slug namespace +* Moderation events +* Audit events +* Reserved slugs * Settings -* Health monitoring -Expected outcome: +#### Tenant Databases -The application returns to a fully operational state without data loss. +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 | ✅ | --- @@ -629,159 +225,159 @@ The application returns to a fully operational state without data loss. ![Settings](screenshots/settings.png) -### Server Status +### Health Dashboard -![Server Status](screenshots/server-status.png) +![Health Dashboard](screenshots/server-status.png) --- -## Docker Deployment +## Installation -Build: - -```bash -docker compose build -``` - -Start: +### Docker ```bash docker compose up -d ``` -Logs: +### Native ```bash -docker logs -f bzod +cargo build --release +./target/release/bzod serve ``` --- -## Docker Compose Example +## CLI -```yaml -services: - bzod: - build: . - container_name: bzod - restart: unless-stopped +### Administration - ports: - - "8654:8654" +```bash +bzod create-admin +bzod create-user +bzod delete-user +bzod disable-user +bzod enable-user +bzod reset-password +bzod list-users +``` - volumes: - - ./data:/app/data - - ./config:/app/config +### Backup & Recovery - environment: - HOST: 0.0.0.0 - PORT: 8654 - DATA_DIR: /app/data +```bash +bzod backup +bzod restore +``` + +### Maintenance + +```bash +bzod doctor +bzod migrate +bzod validate +bzod stats ``` --- -## Development +## Testing -Build: +BZOD v0.5.0 includes a comprehensive automated validation suite. -```bash -cargo build -``` +### Validation Coverage -Run: +* 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 -```bash -cargo run -- serve -``` - -Create administrator: - -```bash -cargo run -- create-admin -``` - -Run tests: +### Execute ```bash cargo test ``` ---- +### Quality Gates -## Development & Testing - -See: - -```text -docs/TESTING.md +```bash +cargo fmt --check +cargo clippy --all-targets -- -D warnings +cargo test +cargo build --release +cargo audit ``` -for testing, validation, backup, restore, disaster recovery, and release procedures. - --- -## Project Structure +## Documentation -```text -src/ -├── analytics/ -├── auth/ -├── charts/ -├── cli/ -├── db/ -├── jobs/ -├── models/ -├── services/ -├── templates/ -├── utils/ -└── web/ -``` +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 features: +Planned future enhancements: -* Geo analytics -* Multi-user administration +* Geographic analytics * SSO integration -* Signed temporary links -* OpenAPI documentation - ---- - -## Production Deployment - -Recommended architecture: - -```text -Internet - │ - ▼ -Nginx Proxy Manager - │ - ▼ -BZOD - │ - ▼ -SQLite -``` - -HTTPS is strongly recommended. - ---- -## Documentation - -- [Testing Guide](docs/TESTING.md) -- [Docker Deployment Guide](docs/DOCKER-Deploy.md) +* OpenAPI specification +* Multi-organization support +* Advanced analytics dashboards +* Background scheduler UI --- ## License -Apache License 2.0 +Dual licensed under: + +* Apache License 2.0 +* MIT License + +at your option. + +See: + +* LICENSE-APACHE +* LICENSE-MIT --- @@ -789,4 +385,4 @@ Apache License 2.0 Sunil Purushottam Thakare -Built with Rust, SQLite, Axum, Askama, and a preference for simple, maintainable software. +Built with Rust, SQLite, Axum, Askama, and a preference for simple, maintainable, self-hosted software. diff --git a/docs/ADMIN_GUIDE.md b/docs/ADMIN_GUIDE.md new file mode 100644 index 0000000..22564d7 --- /dev/null +++ b/docs/ADMIN_GUIDE.md @@ -0,0 +1,888 @@ +# BZOD Administrator Guide + +Version: v0.5.0 + +--- + +# Introduction + +This guide is intended for BZOD administrators responsible for operating, maintaining, and managing a BZOD instance. + +It covers: + +* Administrator authentication +* User management +* Quotas +* Sessions +* Moderation +* Slug ownership +* Analytics +* Audit logs +* Backup and recovery +* Health monitoring +* Operational best practices + +--- + +# Administrator Role + +Administrators have full platform control. + +Administrative capabilities include: + +* Create users +* Modify users +* Disable users +* Delete users +* Reset passwords +* Manage quotas +* Review analytics +* Moderate content +* Transfer slug ownership +* Manage backups +* Review audit logs +* Monitor system health + +Administrators cannot bypass audit logging. + +All administrative actions are recorded. + +--- + +# Login + +Administrative login is available at: + +```text +/login +``` + +Successful login redirects to: + +```text +/admin +``` + +Authentication uses: + +```text +users.db +``` + +Sessions are stored in: + +```text +users.db.sessions +``` + +Cookie name: + +```text +bzod_session +``` + +--- + +# Administrative Dashboard + +Route: + +```text +/admin +``` + +The dashboard provides a high-level overview of platform activity. + +Metrics include: + +* Total Users +* Active Users +* Total URLs +* Total Landing Pages +* Active Sessions +* API Tokens +* Storage Usage +* Moderation Events +* Recent Audit Events + +Quick actions include: + +* Create User +* View Sessions +* View Audit Logs +* Create Backup +* Review Health Status + +--- + +# User Management + +## Users List + +Route: + +```text +/admin/users +``` + +Displays: + +* User ID +* Username +* Status +* Account Type +* Creation Date + +Available actions: + +* View +* Edit +* Disable +* Enable +* Reset Password +* Delete + +--- + +## Create User + +Route: + +```text +/admin/users/new +``` + +Fields: + +* Username +* Password +* Account Type +* Quota Limits + +Supported account types: + +```text +admin +standard +``` + +Reserved usernames cannot be used. + +Examples: + +```text +admin +legacy_admin +system +root +administrator +``` + +--- + +## User Detail Page + +Route: + +```text +/admin/users/{id} +``` + +Displays: + +### Profile + +* User ID +* Username +* Status +* Account Type +* Created Date + +### Usage Statistics + +* URL Count +* Landing Page Count +* Visit Count +* Storage Usage +* API Token Count +* Active Sessions + +### Quotas + +* Maximum URLs +* Maximum Pages +* Maximum Storage +* Maximum Tokens + +### Sessions + +List of active sessions. + +### API Tokens + +List of active tokens. + +--- + +## Edit User + +Route: + +```text +/admin/users/{id}/edit +``` + +Administrators may: + +* Change status +* Change account type +* Modify quotas + +--- + +## Reset Password + +Route: + +```text +/admin/users/{id}/password +``` + +Creates a new password hash and invalidates existing sessions. + +Audit event generated: + +```text +password_reset +``` + +--- + +## Disable User + +Route: + +```text +/admin/users/{id}/disable +``` + +Effects: + +* User login disabled +* Existing sessions revoked +* API access denied + +Audit event generated: + +```text +user_disabled +``` + +--- + +## Enable User + +Route: + +```text +/admin/users/{id}/enable +``` + +Restores account access. + +Audit event generated: + +```text +user_enabled +``` + +--- + +## Delete User + +Route: + +```text +/admin/users/{id}/delete +``` + +Deletion performs: + +1. Session revocation +2. API token removal +3. Content removal +4. Analytics removal +5. Slug release +6. User database deletion + +Audit event generated: + +```text +user_deleted +``` + +--- + +# Session Management + +Route: + +```text +/admin/sessions +``` + +Displays all active platform sessions. + +Information displayed: + +* User ID +* Username +* Session Identifier +* Created Time +* Expiry Time +* IP Address +* User Agent + +--- + +## Revoke Session + +Individual sessions can be revoked. + +Effects: + +* Session removed immediately +* User forced to reauthenticate + +--- + +## Revoke All Sessions + +Administrators may invalidate all active sessions. + +Useful after: + +* Password compromise +* Security incidents +* Large configuration changes + +--- + +# Quota Management + +Route: + +```text +/admin/quotas +``` + +Quotas limit user resource consumption. + +Available limits: + +```text +max_urls +max_pages +max_storage_mb +max_api_tokens +``` + +--- + +## Quota Reconciliation + +Administrators can execute: + +```text +quota_reconcile +``` + +Purpose: + +* Detect counter drift +* Recount resources +* Repair quota usage + +Common causes: + +* Manual database modifications +* Failed migrations +* Interrupted operations + +--- + +# Moderation + +Route: + +```text +/admin/moderation +``` + +Moderation allows administrators to manage abuse and policy violations. + +--- + +## Flag Content + +Marks content for review. + +Audit event: + +```text +content_flagged +``` + +--- + +## Disable Content + +Disabled content returns: + +```http +410 Gone +``` + +Affected endpoints: + +```text +/{slug} +/p/{slug} +/api/qr/{slug}.png +/api/qr/{slug}.svg +``` + +Audit event: + +```text +content_disabled +``` + +--- + +## Enable Content + +Restores functionality. + +Audit event: + +```text +content_enabled +``` + +--- + +## Delete Content + +Permanently removes content. + +Audit event: + +```text +content_deleted +``` + +--- + +# Slug Management + +Route: + +```text +/admin/slugs +``` + +Displays platform-wide slug ownership. + +Information includes: + +* Slug +* Owner +* Type +* Status +* Creation Date + +--- + +## Slug Types + +Supported types: + +```text +url +page +``` + +--- + +## Transfer Ownership + +Administrators may transfer ownership. + +Workflow: + +1. Validate recipient quota. +2. Copy content. +3. Update ownership. +4. Update global slug registry. +5. Write audit record. + +Audit event: + +```text +slug_transfer +``` + +Analytics are preserved. + +--- + +# Analytics + +Administrators can access analytics for any managed resource. + +--- + +## URL Analytics + +Route: + +```text +/admin/analytics/url/{id} +``` + +Displays: + +* Total Visits +* Unique Visitors +* Referrers +* Browsers +* Countries +* Visit Timeline + +--- + +## Page Analytics + +Route: + +```text +/admin/analytics/page/{id} +``` + +Displays identical metrics for landing pages. + +--- + +## User Analytics + +Administrators can review user-level analytics. + +Route: + +```text +/analytics +``` + +Includes: + +* Top Links +* Top Pages +* Referrers +* Browsers +* Countries +* Recent Visits + +--- + +# Audit Logs + +Route: + +```text +/admin/audit +``` + +All administrative actions are recorded. + +Searchable event types include: + +```text +login +logout +failed_login +user_created +user_deleted +user_disabled +user_enabled +password_reset +quota_updated +slug_transfer +content_flagged +content_disabled +backup_created +restore_executed +``` + +Audit logs should be reviewed regularly. + +--- + +# Backup Management + +Route: + +```text +/admin/backups +``` + +Provides web-based backup operations. + +--- + +## Create Backup + +Creates a platform snapshot. + +Includes: + +```text +users.db +system.db +tenant databases +``` + +Audit event: + +```text +backup_created +``` + +--- + +## Download Backup + +Allows local storage of backup archives. + +Recommended frequency: + +```text +Daily +``` + +--- + +## Restore Backup + +Restores a selected backup archive. + +Audit event: + +```text +restore_executed +``` + +Always test restores before production use. + +--- + +## Delete Backup + +Removes backup archives from storage. + +--- + +# Health Dashboard + +Route: + +```text +/admin/health +``` + +Provides operational diagnostics. + +Displays: + +* Database Status +* WAL Status +* Storage Utilization +* Backup Status +* Health Check Results +* Quota Reconciliation Results + +--- + +## Database Health + +Checks: + +```text +users.db +system.db +content.db +analytics.db +``` + +Reports: + +```text +healthy +warning +error +``` + +--- + +## Storage Monitoring + +Shows: + +* Total Storage +* Free Storage +* Database Sizes +* Backup Sizes + +--- + +# Security Administration + +## Password Policies + +Recommendations: + +* Minimum 12 characters +* Unique passwords +* Password manager usage + +--- + +## Session Management + +Recommended actions: + +* Revoke old sessions +* Review active sessions +* Remove inactive users + +--- + +## CSRF Protection + +All administrative forms require valid CSRF tokens. + +Invalid requests return: + +```http +403 Forbidden +``` + +--- + +## Audit Reviews + +Recommended review schedule: + +| Event Type | Frequency | +| ----------------- | --------- | +| Failed Logins | Daily | +| User Creation | Weekly | +| Slug Transfers | Weekly | +| Backup Events | Daily | +| Moderation Events | Weekly | + +--- + +# Disaster Recovery + +Recommended workflow: + +1. Stop BZOD. +2. Create backup copy. +3. Restore archive. +4. Verify databases. +5. Run integrity checks. +6. Restart service. + +--- + +# Operational Best Practices + +Recommended: + +* Enable HTTPS +* Run daily backups +* Monitor disk usage +* Review audit logs +* Keep binaries updated +* Test restore procedures regularly + +Avoid: + +* Manual database modifications +* Direct deletion of tenant databases +* Disabling audit logging + +--- + +# Troubleshooting + +## User Cannot Login + +Check: + +* User status +* Session validity +* Password reset history + +--- + +## Slug Already Exists + +Check: + +```text +/admin/slugs +``` + +for ownership conflicts. + +--- + +## Analytics Missing + +Verify: + +* Analytics worker running +* Analytics database present +* Event queue processing + +--- + +## Backup Failure + +Check: + +* Free disk space +* File permissions +* Backup destination path + +--- + +# Summary + +The BZOD administration system provides: + +* Centralized user management +* Quotas and session controls +* Moderation and slug ownership management +* Analytics visibility +* Audit logging +* Backup and restore capabilities +* Health monitoring + +while maintaining strong tenant isolation and a SQLite-native operational model. + +--- + +End of Document. diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md new file mode 100644 index 0000000..233e045 --- /dev/null +++ b/docs/ARCHITECTURE.md @@ -0,0 +1,650 @@ +# BZOD Architecture Guide + +Version: v0.5.0 + +--- + +# Overview + +BZOD is a self-hosted multi-user URL management platform written in Rust. + +The platform combines: + +* URL shortening +* Landing pages +* QR code generation +* Analytics +* User management +* Moderation +* Audit logging +* Backup & restore +* Disaster recovery + +into a single deployable binary powered entirely by SQLite. + +BZOD is designed around operational simplicity, tenant isolation, and long-term maintainability. + +--- + +# Architectural Goals + +The primary design goals are: + +1. Self-hosted first +2. SQLite-first architecture +3. Multi-user operation +4. Tenant isolation +5. Simple deployment +6. Minimal dependencies +7. Easy backup and recovery +8. No vendor lock-in + +--- + +# High-Level Architecture + +```text + ┌─────────────┐ + │ Browser │ + └──────┬──────┘ + │ + ▼ + ┌────────────────────┐ + │ Axum Router │ + └─────────┬──────────┘ + │ + ┌────────────────────┼────────────────────┐ + │ │ │ + ▼ ▼ ▼ + + users.db system.db User Databases + + Users Global Slugs content.db + Sessions Audit Events analytics.db + Quotas Moderation + API Tokens Settings +``` + +--- + +# Runtime Components + +## Web Layer + +Location: + +```text +src/web/ +``` + +Responsible for: + +* HTTP routing +* Dashboard rendering +* Form handling +* Authentication checks +* Redirect handling +* REST API endpoints + +Major modules: + +```text +admin.rs +api.rs +pages.rs +redirect.rs +qr.rs +system.rs +multi_user.rs +routes.rs +``` + +--- + +## Authentication Layer + +Location: + +```text +src/auth/ +``` + +Responsible for: + +* Password hashing +* Session validation +* Cookie management +* CSRF protection +* Authorization + +Modules: + +```text +csrf.rs +middleware.rs +password.rs +session.rs +``` + +Authentication technologies: + +* Argon2id password hashing +* Session cookies +* CSRF tokens +* RBAC checks + +--- + +## Database Layer + +Location: + +```text +src/db/ +``` + +Responsible for: + +* Schema creation +* Migrations +* Database access +* Analytics storage +* User management + +Modules: + +```text +admin.rs +analytics.rs +audit_events.rs +content.rs +migrations.rs +sqlite.rs +users.rs +``` + +--- + +# Database Architecture + +BZOD uses multiple SQLite databases rather than a single monolithic database. + +This approach provides: + +* Better isolation +* Easier backup +* Simpler disaster recovery +* Reduced risk of cross-user data leakage + +--- + +## users.db + +Purpose: + +Central identity and account database. + +Contains: + +```text +users +sessions +api_tokens +quotas +``` + +Stores: + +* User accounts +* Password hashes +* Session records +* API tokens +* Quota information + +--- + +## system.db + +Purpose: + +Global platform metadata. + +Contains: + +```text +global_slugs +audit_events +moderation_events +reserved_slugs +settings +slug_history +``` + +Stores: + +* Global slug ownership +* Audit records +* Moderation actions +* Platform settings +* Slug transfers + +--- + +## Tenant Databases + +Each user receives isolated databases. + +Directory structure: + +```text +users/ +└── / + ├── content.db + └── analytics.db +``` + +--- + +### content.db + +Stores: + +* URLs +* Landing pages +* Metadata + +--- + +### analytics.db + +Stores: + +* Visits +* Referrers +* QR scans +* Browser information +* Analytics aggregates + +--- + +# Multi-User Architecture + +BZOD v0.5.0 introduced complete tenant isolation. + +Each user owns: + +```text +content.db +analytics.db +``` + +Users cannot directly access: + +* Other users' URLs +* Other users' landing pages +* Other users' analytics + +The administrator accesses all tenants through controlled administrative interfaces. + +--- + +# Global Slug Namespace + +All public URLs are tracked in: + +```text +system.db -> global_slugs +``` + +Purpose: + +Prevent collisions across users. + +Example: + +```text +User A owns: + +https://bzo.in/!office + +User B cannot create: + +https://bzo.in/!office +``` + +This guarantees global uniqueness. + +--- + +# Request Lifecycle + +## URL Redirect + +Request: + +```text +GET /abc123 +``` + +Flow: + +```text +Browser + ↓ +Axum Router + ↓ +global_slugs lookup + ↓ +Locate owner database + ↓ +Resolve URL + ↓ +Record analytics + ↓ +302 Redirect +``` + +--- + +## Landing Page + +Request: + +```text +GET /p/demo +``` + +Flow: + +```text +Browser + ↓ +Router + ↓ +global_slugs lookup + ↓ +Tenant content.db lookup + ↓ +Render page +``` + +--- + +## QR Generation + +Request: + +```text +GET /api/qr/demo.svg +``` + +Flow: + +```text +Router + ↓ +global_slugs lookup + ↓ +Generate QR + ↓ +Return SVG +``` + +--- + +# Analytics Pipeline + +Location: + +```text +src/analytics/ +``` + +Components: + +```text +events.rs +queue.rs +worker.rs +aggregate.rs +location.rs +``` + +Responsibilities: + +* Visit tracking +* QR tracking +* Browser detection +* Referrer parsing +* Aggregation + +--- + +# Background Jobs + +Location: + +```text +src/jobs/ +``` + +Jobs: + +## aggregate.rs + +Analytics aggregation. + +## backup.rs + +Automated backups. + +## expiry.rs + +Expired content cleanup. + +## retention.rs + +Retention policy enforcement. + +## healthcheck.rs + +System health validation. + +## quota_reconcile.rs + +Quota consistency verification. + +--- + +# Services Layer + +Location: + +```text +src/services/ +``` + +Purpose: + +Business logic abstraction. + +Modules: + +```text +api_keys.rs +audit.rs +bulk.rs +landing_pages.rs +qr.rs +shortener.rs +``` + +This layer separates business rules from HTTP handlers. + +--- + +# CLI Architecture + +Location: + +```text +src/cli/ +``` + +The CLI and Web UI share the same internal services. + +Examples: + +```bash +bzod create-admin +bzod create-user +bzod backup +bzod restore +bzod doctor +bzod migrate +``` + +This avoids duplicate logic between administration methods. + +--- + +# Security Model + +Security mechanisms: + +## Authentication + +* Argon2id password hashes +* Session cookies + +## Authorization + +* RBAC +* Administrative permission checks + +## CSRF Protection + +* Form tokens +* Request validation + +## Tenant Isolation + +* Separate databases +* Controlled access paths + +## Audit Logging + +All critical operations are recorded. + +Examples: + +* Login attempts +* User creation +* Password resets +* Slug transfers +* Moderation actions + +--- + +# Backup & Recovery + +BZOD is designed for SQLite-first recovery. + +Backup targets: + +```text +users.db +system.db +admin/ +users/* +``` + +Capabilities: + +* Full backups +* Restore operations +* Upgrade migrations +* Disaster recovery validation + +--- + +# Testing Architecture + +Location: + +```text +tests/ +``` + +Coverage includes: + +* Authentication +* Authorization +* User management +* Analytics +* Backups +* Disaster recovery +* Routing +* Security +* Concurrency +* Upgrade validation +* Multi-user isolation + +v0.5.0 includes more than 90 automated tests. + +--- + +# Deployment Models + +Supported deployments: + +## Native + +```bash +cargo build --release +./bzod serve +``` + +## Systemd + +```text +bzod.service +``` + +## Docker + +```text +Dockerfile +docker-compose.yml +``` + +--- + +# Future Architecture Direction + +Planned for future releases: + +* Geo analytics +* OpenAPI generation +* SSO integration +* Multi-organization support +* Advanced reporting +* Distributed analytics aggregation + +--- + +# Summary + +BZOD v0.5.0 is built around a simple principle: + +> Keep deployment simple, keep data local, keep users isolated, and keep recovery easy. + +The platform achieves this through: + +* Rust +* Axum +* SQLite +* Tenant isolation +* Multi-database architecture +* Strong automated validation +* Operational simplicity diff --git a/docs/BACKUP_RESTORE.md b/docs/BACKUP_RESTORE.md new file mode 100644 index 0000000..6d2259e --- /dev/null +++ b/docs/BACKUP_RESTORE.md @@ -0,0 +1,584 @@ +# Backup & Restore Guide + +Version: v0.5.0 +Applies To: BZOD Multi-User Platform + +--- + +# Overview + +BZOD provides built-in backup and recovery functionality for both single-user and multi-user deployments. + +The backup architecture is designed to support: + +* Full platform backups +* Individual tenant backups +* Disaster recovery +* Upgrade safety +* Migration validation +* Data integrity verification + +All production deployments should maintain regular backups before performing upgrades, maintenance, or administrative operations. + +--- + +# Database Architecture + +BZOD stores data across multiple SQLite databases. + +## Core Databases + +```text +data/ +├── users.db +├── system.db +└── users/ +``` + +### users.db + +Stores: + +* User accounts +* Password hashes +* Account status +* Roles +* Sessions +* Quotas +* API tokens + +### system.db + +Stores: + +* Global slug registry +* Reserved slugs +* Slug ownership history +* Audit events +* Moderation events +* System settings + +--- + +## Tenant Databases + +Each tenant owns isolated content and analytics databases. + +```text +data/users/{user_id}/ +├── content.db +└── analytics.db +``` + +### content.db + +Stores: + +* Short URLs +* Landing pages +* Metadata +* Tags +* QR code configuration + +### analytics.db + +Stores: + +* Visit events +* Referrers +* Browser information +* Country information +* Aggregated statistics + +--- + +# Backup Types + +## Full Platform Backup + +Creates a complete snapshot of the entire BZOD installation. + +Includes: + +```text +users.db +system.db +all tenant content.db files +all tenant analytics.db files +``` + +Recommended for: + +* Daily scheduled backups +* Upgrades +* Server migration +* Disaster recovery + +--- + +## User Backup + +Creates a backup of a single tenant. + +Includes: + +```text +content.db +analytics.db +``` + +Recommended for: + +* User export +* User migration +* User recovery + +--- + +# CLI Backup Commands + +## Create Full Backup + +```bash +bzod backup +``` + +Output: + +```text +backups/ +└── backup-YYYYMMDD-HHMMSS.zip +``` + +--- + +## Create User Backup + +```bash +bzod backup-user 42 +``` + +Output: + +```text +backups/ +└── user-42-YYYYMMDD-HHMMSS.zip +``` + +--- + +# CLI Restore Commands + +## Restore Full Backup + +```bash +bzod restore backup-20260619-020000.zip +``` + +Restores: + +* users.db +* system.db +* all tenant databases + +--- + +## Restore Single User + +```bash +bzod restore-user user-42-20260619.zip +``` + +Restores only: + +```text +users/42/content.db +users/42/analytics.db +``` + +without affecting any other tenant. + +--- + +# Web-Based Backup Management + +Administrative users can manage backups through: + +```text +/admin/backups +``` + +Features: + +* Create backup +* Download backup +* Upload backup +* Restore backup +* Delete backup + +Only authenticated administrators may access backup operations. + +--- + +# Backup Strategy + +## Recommended Schedule + +### Daily + +```text +02:00 AM +``` + +Create a full platform backup. + +--- + +### Weekly + +```text +Sunday 03:00 AM +``` + +Create a full backup and copy it to: + +* NAS +* Secondary server +* External storage + +--- + +### Monthly + +Archive a backup for long-term retention. + +Recommended retention: + +```text +12 months +``` + +--- + +# Retention Policy + +Recommended policy: + +```text +Daily Backups: +30 days + +Weekly Backups: +12 weeks + +Monthly Backups: +12 months +``` + +Adjust retention according to compliance requirements. + +--- + +# Upgrade Procedure + +Always create a backup before upgrading. + +## Step 1 + +Create backup: + +```bash +bzod backup +``` + +## Step 2 + +Upgrade BZOD binary. + +## Step 3 + +Start BZOD. + +```bash +bzod serve +``` + +## Step 4 + +Allow database migrations to complete. + +## Step 5 + +Verify: + +* Login +* URLs +* Landing pages +* Analytics +* Administration panels + +--- + +# Restore Validation + +After every restore operation verify: + +## Authentication + +* Administrator login works +* Standard user login works + +## Content + +* URLs are visible +* Landing pages render correctly + +## Routing + +* Slug redirects work +* Landing page routes resolve + +## Analytics + +* Visit counts exist +* Analytics dashboards load + +## System + +* Audit events visible +* Moderation records preserved +* System settings preserved + +## Multi-User + +* Tenant isolation maintained +* Ownership mappings preserved + +--- + +# Disaster Recovery Scenarios + +## Scenario 1: Deleted User + +Problem: + +```text +User account accidentally deleted. +``` + +Recovery: + +```bash +bzod restore-user user-42.zip +``` + +Verify: + +* URLs restored +* Pages restored +* Analytics restored + +--- + +## Scenario 2: Corrupted Tenant Database + +Problem: + +```text +content.db corruption +``` + +Recovery: + +```bash +bzod restore-user user-42.zip +``` + +or + +```bash +bzod restore full-backup.zip +``` + +--- + +## Scenario 3: Corrupted users.db + +Problem: + +```text +Unable to login +Missing users +Session failures +``` + +Recovery: + +```bash +bzod restore full-backup.zip +``` + +--- + +## Scenario 4: Corrupted system.db + +Problem: + +```text +Slug resolution failures +Moderation data missing +Settings lost +``` + +Recovery: + +```bash +bzod restore full-backup.zip +``` + +--- + +## Scenario 5: Complete Server Failure + +Problem: + +```text +Disk failure +Server loss +Hardware replacement +``` + +Recovery: + +1. Reinstall operating system +2. Install BZOD +3. Restore backup + +```bash +bzod restore backup.zip +``` + +4. Start BZOD + +```bash +bzod serve +``` + +--- + +# WAL Mode + +BZOD uses SQLite Write-Ahead Logging (WAL). + +Examples: + +```text +users.db +users.db-wal +users.db-shm + +system.db +system.db-wal +system.db-shm + +content.db +content.db-wal +content.db-shm + +analytics.db +analytics.db-wal +analytics.db-shm +``` + +Benefits: + +* Improved concurrency +* Better crash recovery +* Faster write operations + +--- + +# Backup Safety + +Do not manually copy live SQLite databases while the server is actively writing. + +Always use: + +```bash +bzod backup +``` + +or the Backup Management UI. + +This ensures consistent snapshots. + +--- + +# Security Considerations + +Backups may contain: + +* User accounts +* Password hashes +* Session metadata +* Analytics data +* Audit records +* API token hashes + +Even though passwords and tokens are stored as hashes, backup archives should be treated as sensitive information. + +Recommended practices: + +* Encrypt backup storage +* Restrict filesystem permissions +* Maintain offsite copies +* Transfer backups over secure channels +* Test restores periodically + +--- + +# Backup Testing + +A backup is only useful if it can be restored. + +Quarterly validation is recommended. + +Example: + +```bash +mkdir restore-test + +bzod restore backup.zip \ + --data-dir restore-test +``` + +Verify: + +* Login works +* URLs resolve +* Landing pages load +* Analytics display +* Administration dashboard functions + +--- + +# Production Recommendation + +Minimum production policy: + +```text +Daily Full Backup +Weekly Offsite Backup +Monthly Archive Backup +Quarterly Restore Validation +``` + +Following this policy protects against: + +* User mistakes +* Database corruption +* Upgrade failures +* Hardware failures +* Site disasters + +and provides a reliable recovery path for BZOD deployments. diff --git a/docs/CLI.md b/docs/CLI.md new file mode 100644 index 0000000..9a2d357 --- /dev/null +++ b/docs/CLI.md @@ -0,0 +1,271 @@ +# BZOD Command Line Interface (CLI) + +BZOD includes a comprehensive command-line interface for server administration, backups, migrations, diagnostics, validation, and multi-user management. + +The current command list for BZOD v0.5.0 is: + +```text +$ bzod --help + +BZOD - Personal Redirector & Landing Page Platform + +Usage: bzod + +Commands: + serve Start the BZOD web server + backup Create a tar.gz backup of all databases + restore Restore databases from a tar.gz backup file + migrate Apply pending database schema migrations + stats Print database statistics and record counts in the terminal + validate Perform a one-shot validation of all registered short link destinations + create-admin Create a new administrator user in the database + doctor Run database diagnostics and health checks + shorten Shorten a URL (Feature 3) + expand Expand a shortened code or custom slug to its destination URL (Feature 4) + create-user Create a new standard user in the database + delete-user Delete a standard user and all their databases/slugs + disable-user Disable a standard user + enable-user Enable a standard user + reset-password Reset standard user's password + list-users List all standard/system users + backup-user Backup a standard user's databases to a .tar.zst package + restore-user Restore a standard user's databases from a .tar.zst package + help Print this message or the help of the given subcommand(s) + +Options: + -h, --help Print help +``` + +--- + +# Server Operations + +## Start Web Server + +```bash +bzod serve +``` + +--- + +# Backup & Recovery + +## Full Backup + +```bash +bzod backup +``` + +Creates a compressed backup archive containing: + +* users.db +* system.db +* content databases +* analytics databases +* user directories + +## Full Restore + +```bash +bzod restore backup.tar.gz +``` + +Restores an entire BZOD installation from a backup archive. + +--- + +# Database Operations + +## Apply Migrations + +```bash +bzod migrate +``` + +Applies any pending database migrations. + +Safe to execute multiple times. + +## Database Statistics + +```bash +bzod stats +``` + +Displays database statistics, record counts, storage usage, and operational metrics. + +--- + +# Validation & Diagnostics + +## Validate Links + +```bash +bzod validate +``` + +Checks all registered URLs and reports invalid destinations. + +## Health Diagnostics + +```bash +bzod doctor +``` + +Performs: + +* SQLite integrity checks +* WAL validation +* Database availability checks +* Storage verification +* System health diagnostics + +--- + +# URL Management + +## Create Short URL + +```bash +bzod shorten https://example.com +``` + +## Expand Existing URL + +```bash +bzod expand abc123 +``` + +Returns the destination URL associated with the slug. + +--- + +# Administrator Management + +## Create Administrator + +```bash +bzod create-admin admin +``` + +Creates a new administrator account. + +--- + +# User Management + +## List Users + +```bash +bzod list-users +``` + +Displays all users in the platform. + +## Create User + +```bash +bzod create-user alice +``` + +Creates a new standard user. + +## Disable User + +```bash +bzod disable-user alice +``` + +Blocks login and invalidates sessions. + +## Enable User + +```bash +bzod enable-user alice +``` + +Re-enables a disabled user. + +## Reset Password + +```bash +bzod reset-password alice +``` + +Resets a user's password. + +## Delete User + +```bash +bzod delete-user alice +``` + +Deletes: + +* User account +* User databases +* Sessions +* API tokens +* Slug ownership + +--- + +# User Backup Operations + +## Backup User + +```bash +bzod backup-user alice +``` + +Creates a portable `.tar.zst` archive containing all user-owned data. + +## Restore User + +```bash +bzod restore-user alice.tar.zst +``` + +Restores a user from a previously generated archive. + +--- + +# Recommended Maintenance + +Daily: + +```bash +bzod doctor +``` + +Weekly: + +```bash +bzod backup +``` + +Before Upgrades: + +```bash +bzod backup +bzod validate +``` + +After Upgrades: + +```bash +bzod migrate +bzod doctor +``` + +--- + +# Related Documentation + +* INSTALL.md +* MULTI_USER.md +* ADMIN_GUIDE.md +* BACKUP_RESTORE.md +* SECURITY.md +* API.md +* ARCHITECTURE.md diff --git a/docs/COMPARISON.md b/docs/COMPARISON.md index 3e9e1db..1f18fb0 100644 --- a/docs/COMPARISON.md +++ b/docs/COMPARISON.md @@ -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. diff --git a/docs/DATABASES.md b/docs/DATABASES.md new file mode 100644 index 0000000..0bdef19 --- /dev/null +++ b/docs/DATABASES.md @@ -0,0 +1,503 @@ +# DATABASES.md + +# BZOD Database Architecture + +BZOD v0.5.0 uses SQLite exclusively. + +Rather than using a single monolithic database, BZOD separates data into administrative and tenant-specific databases. This architecture improves security, isolation, backup flexibility, disaster recovery, and scalability. + +--- + +# Overview + +BZOD stores data in the following structure: + +```text +data/ +├── admin/ +│ ├── admin.db +│ ├── system.db +│ └── users.db +│ +└── users/ + ├── 1/ + │ ├── analytics.db + │ ├── content.db + │ └── profile.db + │ + ├── 2/ + │ ├── analytics.db + │ ├── content.db + │ └── profile.db + │ + └── N/ + ├── analytics.db + ├── content.db + └── profile.db +``` + +Each user receives isolated databases. + +No user content or analytics are stored in the central administrative databases. + +--- + +# Administrative Databases + +Administrative databases are located under: + +```text +data/admin/ +``` + +--- + +# users.db + +Primary authentication and user management database. + +Purpose: + +* User accounts +* Password hashes +* Sessions +* Quotas +* API tokens +* User status tracking + +Typical tables: + +```text +users +sessions +quotas +api_tokens +``` + +Responsibilities: + +* Authentication +* Authorization +* Session management +* Account status +* Quota enforcement + +This is the primary identity database of the platform. + +--- + +# system.db + +Global platform database. + +Purpose: + +* Global slug namespace +* Moderation +* Auditing +* System configuration + +Typical tables: + +```text +global_slugs +slug_history +moderation_events +audit_events +reserved_slugs +settings +``` + +Responsibilities: + +* Global slug uniqueness +* Slug ownership +* Moderation actions +* Audit logging +* System settings + +Every redirect ultimately resolves through records stored in this database. + +--- + +# admin.db + +Administrative application database. + +Purpose: + +* Administrative metadata +* Administrative API key records +* Legacy compatibility structures +* Internal management data + +Typical tables: + +```text +api_keys +audit_events +``` + +This database is reserved for administrative functions and does not store tenant content. + +--- + +# Tenant Databases + +Tenant databases are located under: + +```text +data/users/{user_id}/ +``` + +Each user owns a completely isolated set of databases. + +Example: + +```text +data/users/2/ +├── analytics.db +├── content.db +└── profile.db +``` + +--- + +# content.db + +Stores user-owned content. + +Purpose: + +* Short URLs +* Landing pages +* QR metadata +* Preview metadata + +Typical tables: + +```text +urls +pages +qr_codes +previews +``` + +Responsibilities: + +* URL management +* Landing page management +* Content ownership + +This database contains the actual resources owned by a user. + +--- + +# analytics.db + +Stores traffic and visitor information. + +Purpose: + +* Visit recording +* Referrer tracking +* Browser tracking +* Country statistics +* Aggregated analytics + +Typical tables: + +```text +visits +referrers +browsers +countries +daily_stats +``` + +Responsibilities: + +* Analytics collection +* Reporting +* Dashboard statistics + +Analytics are fully isolated per user. + +Administrators access aggregated analytics by querying each user's analytics database. + +--- + +# profile.db + +Stores user-specific profile information. + +Purpose: + +* User preferences +* Profile settings +* Future extensible metadata + +Typical tables: + +```text +profile +preferences +``` + +Responsibilities: + +* User profile management +* Dashboard preferences +* Future personalization features + +--- + +# Database Isolation Model + +BZOD follows a strict tenant isolation model. + +```text +User A + ├── content.db + ├── analytics.db + └── profile.db + +User B + ├── content.db + ├── analytics.db + └── profile.db +``` + +User databases never share tables. + +Cross-user content access is prevented by design. + +Benefits: + +* Security +* Easier backups +* Easier deletion +* Reduced corruption impact + +--- + +# Global Slug Registry + +The system maintains a single namespace. + +Stored in: + +```text +system.db +``` + +Table: + +```text +global_slugs +``` + +Example: + +```text +abc123 → User 2 URL +docs → User 5 Page +demo → User 1 URL +``` + +This guarantees: + +* Global uniqueness +* Ownership tracking +* Moderation support +* Slug transfer support + +--- + +# Write Flow + +Creating a URL: + +```text +1. Validate quota +2. Register slug in system.db +3. Create URL in content.db +4. Update quota counters +5. Write audit event +``` + +Creating a landing page: + +```text +1. Validate quota +2. Register slug in system.db +3. Create page in content.db +4. Update quota counters +5. Write audit event +``` + +--- + +# Analytics Flow + +Visitor request: + +```text +GET /abc123 +``` + +Process: + +```text +global_slugs + ↓ +content.db lookup + ↓ +redirect + ↓ +analytics.db visit record +``` + +Analytics writes never modify content records. + +--- + +# WAL Mode + +All databases operate in SQLite WAL mode. + +Verify: + +```sql +PRAGMA journal_mode; +``` + +Expected: + +```text +wal +``` + +Benefits: + +* Improved concurrency +* Reduced write contention +* Crash recovery + +Associated files: + +```text +*.db +*.db-shm +*.db-wal +``` + +--- + +# WAL Checkpointing + +Large WAL files are normal during heavy traffic. + +Example: + +```text +analytics.db-wal +content.db-wal +``` + +To manually checkpoint: + +```sql +PRAGMA wal_checkpoint(TRUNCATE); +``` + +The healthcheck and backup jobs may trigger checkpoints automatically. + +--- + +# Backups + +Recommended: + +```bash +bzod backup +``` + +This creates a consistent archive of: + +```text +admin/ +users/ +``` + +Never manually copy live databases while the application is running. + +--- + +# Integrity Verification + +Run: + +```bash +bzod doctor +``` + +Or: + +```sql +PRAGMA integrity_check; +``` + +Expected: + +```text +ok +``` + +--- + +# Migration System + +BZOD maintains schema versions using: + +```sql +PRAGMA user_version; +``` + +Startup automatically executes: + +```text +Db::init() +``` + +which: + +1. Creates missing databases +2. Applies migrations +3. Validates schemas +4. Repairs legacy installations when required + +--- + +# Design Principles + +BZOD database architecture prioritizes: + +* SQLite-only deployment +* Multi-user isolation +* Operational simplicity +* Backup friendliness +* Easy disaster recovery +* Minimal dependencies +* Single-binary deployment + +--- + +# Related Documentation + +* ARCHITECTURE.md +* MULTI_USER.md +* BACKUP_RESTORE.md +* INSTALL.md +* UPGRADE.md +* SECURITY.md diff --git a/docs/INSTALL.md b/docs/INSTALL.md new file mode 100644 index 0000000..ecf3eee --- /dev/null +++ b/docs/INSTALL.md @@ -0,0 +1,604 @@ +# BZOD Installation Guide + +Version: v0.5.0 + +--- + +# Introduction + +BZOD is a self-hosted multi-user URL management platform written in Rust. + +Features include: + +* URL shortening +* Landing pages +* QR code generation +* Analytics +* User management +* Audit logging +* Moderation +* Backup & restore +* Disaster recovery + +BZOD is distributed as a single executable and uses SQLite databases for storage. + +No PostgreSQL, MySQL, Redis, Elasticsearch, or external services are required. + +--- + +# Installation Methods + +BZOD supports three deployment methods: + +| Method | Recommended For | +| -------------- | ---------------- | +| Docker Compose | Most deployments | +| Native Binary | Linux servers | +| Source Build | Development | + +--- + +# System Requirements + +## Minimum + +| Component | Requirement | +| --------- | ------------ | +| CPU | 1 Core | +| Memory | 512 MB | +| Storage | 1 GB | +| OS | Linux x86_64 | + +## Recommended + +| Component | Requirement | +| --------- | ------------------------ | +| CPU | 2+ Cores | +| Memory | 2 GB | +| Storage | 10+ GB SSD | +| OS | Debian 12 / Ubuntu 24.04 | + +## Tested Platforms + +* Debian 12 Bookworm +* Ubuntu 22.04 +* Ubuntu 24.04 +* Arch Linux +* Docker +* CasaOS + +--- + +# Installation Using Docker + +## Prerequisites + +Install: + +```bash +docker +docker compose +``` + +Verify: + +```bash +docker --version +docker compose version +``` + +--- + +## Create Directory + +```bash +mkdir -p /opt/bzod +cd /opt/bzod +``` + +--- + +## Copy Files + +Required: + +```text +docker-compose.yml +Dockerfile +``` + +Optional: + +```text +bzod.service +``` + +--- + +## Start Container + +```bash +docker compose up -d +``` + +Verify: + +```bash +docker compose ps +``` + +View logs: + +```bash +docker compose logs -f +``` + +--- + +## Stop Container + +```bash +docker compose down +``` + +--- + +## Restart Container + +```bash +docker compose restart +``` + +--- + +# Native Installation + +## Install Dependencies + +### Debian / Ubuntu + +```bash +sudo apt update + +sudo apt install -y \ + build-essential \ + pkg-config \ + libssl-dev \ + sqlite3 +``` + +### Arch Linux + +```bash +sudo pacman -S \ + base-devel \ + openssl \ + sqlite +``` + +--- + +## Download Release Binary + +Example: + +```bash +wget https://example.com/bzod-v0.5.0-linux-amd64.tar.gz +``` + +Extract: + +```bash +tar -xzf bzod-v0.5.0-linux-amd64.tar.gz +``` + +Install: + +```bash +sudo install -m755 bzod /usr/local/bin/bzod +``` + +Verify: + +```bash +bzod --help +``` + +--- + +# Build From Source + +## Install Rust + +```bash +curl https://sh.rustup.rs -sSf | sh +``` + +Verify: + +```bash +cargo --version +rustc --version +``` + +--- + +## Clone Repository + +```bash +git clone https://github.com/thakares/nx9-url-shortener.git + +cd nx9-url-shortener +``` + +--- + +## Build + +Development: + +```bash +cargo build +``` + +Release: + +```bash +cargo build --release +``` + +Binary: + +```bash +target/release/bzod +``` + +--- + +# Data Directory + +BZOD automatically creates its databases on first startup. + +Default structure: + +```text +data/ +├── users.db +├── system.db +│ +├── admin/ +│ ├── content.db +│ └── analytics.db +│ +└── users/ + └── ... +``` + +Do not manually modify database files while BZOD is running. + +--- + +# First Startup + +Run: + +```bash +bzod serve +``` + +By default: + +```text +http://localhost:8080 +``` + +Open: + +```text +http://localhost:8080 +``` + +--- + +# Bootstrap Administrator + +On a fresh installation: + +1. Open Login page +2. Use bootstrap credentials +3. Create the first administrator account +4. Save the credentials securely + +After bootstrap: + +* Bootstrap mode is disabled +* Normal authentication is enforced + +--- + +# Create Administrator Using CLI + +Alternative method: + +```bash +bzod create-admin +``` + +Follow prompts: + +```text +Username: +Password: +``` + +The administrator account is stored in: + +```text +users.db +``` + +--- + +# Reverse Proxy Configuration + +Using Nginx is recommended. + +Example: + +```nginx +server { + server_name bzod.example.com; + + location / { + proxy_pass http://127.0.0.1:8080; + + proxy_set_header Host $host; + proxy_set_header X-Real-IP $remote_addr; + + proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; + + proxy_set_header X-Forwarded-Proto $scheme; + } +} +``` + +Reload: + +```bash +sudo nginx -t +sudo systemctl reload nginx +``` + +--- + +# HTTPS + +Recommended options: + +* Let's Encrypt +* Nginx Proxy Manager +* Caddy +* Traefik + +Always use HTTPS in production. + +--- + +# Running as Systemd Service + +Install binary: + +```bash +sudo install -m755 bzod /usr/local/bin/bzod +``` + +Copy service: + +```bash +sudo cp bzod.service /etc/systemd/system/ +``` + +Reload: + +```bash +sudo systemctl daemon-reload +``` + +Enable: + +```bash +sudo systemctl enable bzod +``` + +Start: + +```bash +sudo systemctl start bzod +``` + +Status: + +```bash +sudo systemctl status bzod +``` + +Logs: + +```bash +journalctl -u bzod -f +``` + +--- + +# Firewall + +Open HTTP: + +```bash +sudo ufw allow 8080/tcp +``` + +HTTPS: + +```bash +sudo ufw allow 443/tcp +``` + +HTTP: + +```bash +sudo ufw allow 80/tcp +``` + +--- + +# Health Verification + +Open: + +```text +http://localhost:8080 +``` + +Login as administrator. + +Verify: + +* Dashboard loads +* User list loads +* URL creation works +* Landing pages work +* QR generation works +* Analytics record visits + +--- + +# Upgrade Procedure + +Always backup before upgrading. + +Create backup: + +```bash +bzod backup +``` + +Stop service: + +```bash +sudo systemctl stop bzod +``` + +Replace binary. + +Run migrations: + +```bash +bzod migrate +``` + +Start service: + +```bash +sudo systemctl start bzod +``` + +Verify logs. + +See: + +```text +docs/UPGRADE.md +``` + +--- + +# Troubleshooting + +## Port Already In Use + +Check: + +```bash +ss -tulpn | grep 8080 +``` + +Change port or stop conflicting service. + +--- + +## Database Locked + +Verify only one BZOD instance is running: + +```bash +ps aux | grep bzod +``` + +--- + +## Permission Errors + +Verify ownership: + +```bash +chown -R bzod:bzod data/ +``` + +--- + +## Login Problems + +Verify: + +* Administrator account exists +* Session cookies enabled +* System clock is correct + +--- + +## View Logs + +Systemd: + +```bash +journalctl -u bzod -f +``` + +Docker: + +```bash +docker compose logs -f +``` + +--- + +# Next Steps + +After installation: + +1. Read `MULTI_USER.md` +2. Read `ADMIN_GUIDE.md` +3. Configure backups +4. Configure HTTPS +5. Create additional users +6. Verify restore procedures + +--- + +# Additional Documentation + +| File | Purpose | +| ----------------- | ------------------------ | +| ARCHITECTURE.md | System architecture | +| MULTI_USER.md | Multi-user design | +| ADMIN_GUIDE.md | Administrative workflows | +| BACKUP_RESTORE.md | Backup procedures | +| SECURITY.md | Security model | +| CLI.md | Command reference | +| API.md | REST API reference | +| UPGRADE.md | Upgrade instructions | + +--- + +End of Document. diff --git a/docs/MULTI_USER.md b/docs/MULTI_USER.md new file mode 100644 index 0000000..0eb894e --- /dev/null +++ b/docs/MULTI_USER.md @@ -0,0 +1,732 @@ +# BZOD Multi-User Architecture Guide + +Version: v0.5.0 + +--- + +# Introduction + +BZOD v0.5.0 introduces a complete multi-user architecture that transforms BZOD from a single-tenant URL shortener into a secure, isolated, self-hosted multi-user platform. + +Each user receives logically isolated content and analytics storage while sharing a common authentication, administration, moderation, and routing infrastructure. + +This document explains the architecture, database layout, ownership model, security boundaries, quotas, slug management, and administrative workflows. + +--- + +# Design Goals + +The multi-user architecture was designed around the following principles: + +* Strong tenant isolation +* Single binary deployment +* SQLite-only operation +* Minimal operational complexity +* No external services required +* Global slug namespace +* Centralized administration +* Disaster recovery support +* Simple backup and restore workflows + +--- + +# User Types + +BZOD supports the following account types. + +## Administrator + +Administrators can: + +* Access the administrative dashboard +* Create users +* Delete users +* Reset passwords +* Manage quotas +* Transfer ownership +* Moderate content +* Manage backups +* Access health dashboards +* Access audit logs + +Administrators cannot bypass database isolation. + +--- + +## Standard User + +Standard users can: + +* Create short URLs +* Create landing pages +* View analytics +* Generate QR codes +* Manage API tokens +* Update passwords + +Standard users cannot: + +* Access other user content +* Access administrative functions +* Access system settings + +--- + +## System Accounts + +System accounts are reserved for internal operations. + +They cannot authenticate into the dashboard. + +--- + +# Database Architecture + +BZOD uses multiple SQLite databases. + +## users.db + +Central identity store. + +Contains: + +```text +users +sessions +quotas +api_tokens +``` + +Responsibilities: + +* Authentication +* Session management +* Password verification +* User status management +* Quota tracking + +--- + +## system.db + +Global platform database. + +Contains: + +```text +global_slugs +slug_history +moderation_events +audit_events +settings +reserved_slugs +``` + +Responsibilities: + +* Slug ownership +* Moderation +* Audit logging +* Global settings +* System metadata + +--- + +## Tenant Databases + +Every tenant owns independent databases. + +Example: + +```text +users/ +└── 15/ + ├── content.db + └── analytics.db +``` + +Responsibilities: + +### content.db + +Stores: + +```text +urls +pages +qr_metadata +previews +``` + +### analytics.db + +Stores: + +```text +visits +aggregates +referrers +browsers +countries +``` + +--- + +# Directory Structure + +Example installation: + +```text +data/ +├── users.db +├── system.db +│ +├── admin/ +│ ├── content.db +│ └── analytics.db +│ +└── users/ + ├── 2/ + │ ├── content.db + │ └── analytics.db + │ + ├── 3/ + │ ├── content.db + │ └── analytics.db + │ + └── 4/ + ├── content.db + └── analytics.db +``` + +--- + +# Global Slug Namespace + +BZOD uses a platform-wide namespace. + +A slug can only exist once. + +Examples: + +```text +/company +/about +/docs +``` + +If User A owns: + +```text +/company +``` + +User B cannot create: + +```text +/company +``` + +The operation is rejected. + +--- + +# Slug Registration Flow + +When a URL or page is created: + +1. Validate quota. +2. Validate slug. +3. Register slug in system.db. +4. Create record in tenant content.db. +5. Increment quota counters. +6. Write audit log. + +If any step fails: + +* Changes are rolled back. +* Partial records are removed. + +--- + +# Global Slug Table + +Conceptually: + +```text +global_slugs +``` + +Contains: + +```text +slug +owner_user_id +target_type +target_id +status +created_at +``` + +Example: + +| slug | owner | type | +| ---- | ----- | ---- | +| docs | 3 | page | +| api | 8 | page | +| home | 2 | url | + +--- + +# Slug Ownership Transfer + +Administrators may transfer ownership. + +Process: + +1. Validate destination quotas. +2. Copy content. +3. Move ownership. +4. Update global slug registry. +5. Record history. +6. Write audit event. + +Analytics remain preserved. + +URLs remain functional. + +--- + +# Tenant Isolation + +Each user owns independent databases. + +Example: + +```text +User A +└── users/2/ + +User B +└── users/3/ +``` + +User A never accesses: + +```text +users/3/content.db +users/3/analytics.db +``` + +User B never accesses: + +```text +users/2/content.db +users/2/analytics.db +``` + +All access is enforced by application logic. + +--- + +# Authentication Architecture + +Authentication is centralized. + +Stored in: + +```text +users.db +``` + +Tables: + +```text +users +sessions +``` + +All dashboard sessions use: + +```text +bzod_session +``` + +Sessions are validated against: + +```text +users.db.sessions +``` + +--- + +# Session Lifecycle + +Login: + +```text +User Login + ↓ +Create Session + ↓ +Store in users.db + ↓ +Set bzod_session cookie +``` + +Logout: + +```text +Delete session row + ↓ +Expire cookie +``` + +Disabled users immediately lose access. + +--- + +# Quota System + +Every user has quotas. + +Examples: + +```text +max_urls +max_pages +max_storage_mb +max_api_tokens +``` + +Current utilization is tracked separately. + +Administrators may: + +* Increase limits +* Reduce limits +* Trigger reconciliation + +--- + +# Quota Reconciliation + +Background job: + +```text +quota_reconcile +``` + +Purpose: + +* Detect drift +* Recount resources +* Repair counters + +Example: + +```text +Stored URLs = 50 +Actual URLs = 47 +``` + +Counter automatically corrected. + +--- + +# Analytics Isolation + +Each tenant stores analytics independently. + +Example: + +```text +users/10/analytics.db +``` + +Contains only User 10 traffic. + +Administrators can: + +* View aggregated analytics +* Access user analytics + +Users cannot view analytics from other tenants. + +--- + +# QR Code System + +QR codes are generated dynamically. + +Endpoints: + +```text +/api/qr/{slug}.png +/api/qr/{slug}.svg +``` + +Slug ownership is resolved through: + +```text +system.db.global_slugs +``` + +No content database scan is required. + +--- + +# Moderation Architecture + +Administrators can: + +* Flag content +* Disable content +* Delete content +* Transfer ownership + +Disabled content returns: + +```http +410 Gone +``` + +For: + +```text +/slug +/p/slug +/api/qr/slug.png +/api/qr/slug.svg +``` + +--- + +# Audit Logging + +All administrative actions are recorded. + +Examples: + +```text +login +logout +user_create +user_delete +password_reset +quota_update +slug_transfer +backup_create +restore_execute +``` + +Stored in: + +```text +system.db +``` + +--- + +# Backup Architecture + +Supported levels: + +## Full Platform Backup + +Includes: + +```text +users.db +system.db +all tenant databases +``` + +--- + +## User Backup + +Includes: + +```text +content.db +analytics.db +``` + +For a specific user. + +--- + +# Disaster Recovery + +Supported operations: + +```bash +bzod backup +bzod restore +bzod backup-user +bzod restore-user +``` + +Recovery preserves: + +* URLs +* Pages +* Analytics +* Users +* Slugs +* Settings + +--- + +# Upgrade Path + +BZOD automatically migrates: + +```text +v0.4.x +``` + +to + +```text +v0.5.x +``` + +Migration process: + +1. Create users.db. +2. Create system.db. +3. Create admin tenant. +4. Migrate content. +5. Migrate analytics. +6. Populate global_slugs. +7. Create legacy_admin. +8. Validate integrity. + +No manual database migration is normally required. + +--- + +# Security Model + +Security boundaries: + +## Authentication + +Centralized. + +```text +users.db +``` + +--- + +## Authorization + +Role-based. + +```text +admin +standard +system +``` + +--- + +## CSRF Protection + +All forms protected. + +Invalid tokens: + +```http +403 Forbidden +``` + +--- + +## Session Security + +* Secure session IDs +* Session invalidation +* Expiration support +* Replay protection + +--- + +## Tenant Isolation + +Per-user databases. + +No shared content tables. + +--- + +# Operational Recommendations + +Recommended deployment: + +```text +Nginx + ↓ +BZOD + ↓ +SQLite WAL +``` + +Enable: + +* HTTPS +* Daily backups +* Log rotation +* Health monitoring + +--- + +# Limitations + +Current v0.5.0 limitations: + +* SQLite backend only +* Single server deployment +* No clustering +* No federation +* No organization account hierarchy + +These may be addressed in future releases. + +--- + +# Future Expansion + +Potential v0.6.x features: + +* Organization accounts +* Service accounts +* SSO integration +* Multi-node replication +* Advanced analytics dashboards +* Scheduled tasks UI + +--- + +# Summary + +BZOD v0.5.0 provides: + +* Centralized authentication +* Multi-user isolation +* Global slug namespace +* Per-user analytics +* Administrative moderation +* Quotas +* Audit logging +* Backup & disaster recovery +* Single-binary deployment + +while remaining lightweight, SQLite-native, and operationally simple. + +--- + +End of Document. diff --git a/docs/SECURITY.md b/docs/SECURITY.md new file mode 100644 index 0000000..16979e5 --- /dev/null +++ b/docs/SECURITY.md @@ -0,0 +1,662 @@ +# BZOD Security Guide + +Version: v0.5.0 + +--- + +# Security Overview + +BZOD is designed as a self-hosted URL shortener and landing page platform with a strong emphasis on: + +* Multi-user isolation +* Secure authentication +* Role-based access control +* Auditability +* Data ownership +* Disaster recovery +* Operational simplicity + +This document describes the security architecture, threat model, authentication mechanisms, authorization controls, and operational security recommendations for BZOD v0.5.0. + +--- + +# Security Principles + +BZOD follows several core principles: + +1. Least Privilege +2. Tenant Isolation +3. Defense in Depth +4. Auditability +5. Secure Defaults +6. Explicit Ownership +7. Fail Secure + +--- + +# Threat Model + +BZOD is designed to protect against: + +* Unauthorized dashboard access +* Credential theft +* Session hijacking +* Cross-user data access +* Slug takeover attempts +* Privilege escalation +* CSRF attacks +* XSS injection attempts +* Unauthorized API access +* Malicious content modification +* Accidental administrative mistakes + +BZOD is not intended to defend against: + +* Physical server compromise +* Root-level operating system compromise +* Malware running as the BZOD service user +* Full database theft by a privileged host administrator + +--- + +# Authentication + +Authentication is centralized in: + +```text +users.db +``` + +Tables: + +```text +users +sessions +api_tokens +``` + +All users authenticate through the same identity system. + +--- + +# Password Security + +Passwords are never stored in plaintext. + +Stored values: + +```text +password_hash +``` + +Passwords are hashed before storage. + +Administrative password resets generate entirely new hashes. + +Existing passwords cannot be recovered. + +--- + +# Session Security + +All dashboard authentication uses: + +```text +bzod_session +``` + +cookie. + +Sessions are stored in: + +```text +users.db.sessions +``` + +Each session contains: + +```text +session_id +user_id +created_at +expires_at +``` + +--- + +## Session Validation + +Each authenticated request verifies: + +1. Session exists +2. Session has not expired +3. User exists +4. User status is active +5. User has required permissions + +Failure at any step immediately invalidates access. + +--- + +## Session Revocation + +Sessions are revoked when: + +* User logs out +* User is disabled +* User is deleted +* Password is reset +* Administrator revokes sessions + +--- + +## Session Fixation Protection + +BZOD generates new session identifiers after successful authentication. + +Previously issued identifiers are not reused. + +--- + +# Authorization Model + +BZOD implements Role-Based Access Control (RBAC). + +Supported roles: + +```text +admin +standard +system +``` + +--- + +## Administrator + +Administrators can: + +* Manage users +* Reset passwords +* Transfer ownership +* Manage quotas +* Access audit logs +* Review analytics +* Create backups +* Restore backups +* Moderate content + +Administrators cannot bypass audit logging. + +--- + +## Standard User + +Standard users can: + +* Manage owned URLs +* Manage owned landing pages +* View owned analytics +* Generate API tokens +* Manage owned content + +Standard users cannot: + +* Access other users' content +* Access administrative endpoints +* Access system settings + +--- + +## System Accounts + +System accounts are internal accounts. + +They cannot authenticate into: + +* Dashboard +* REST API + +--- + +# Multi-User Isolation + +Multi-user isolation is one of the primary security features of BZOD. + +Each tenant receives independent databases. + +Example: + +```text +users/ +├── 2/ +│ ├── content.db +│ └── analytics.db +│ +├── 3/ +│ ├── content.db +│ └── analytics.db +``` + +User 2 never accesses: + +```text +users/3/content.db +users/3/analytics.db +``` + +User 3 never accesses: + +```text +users/2/content.db +users/2/analytics.db +``` + +--- + +# Global Slug Security + +All public slugs are stored in: + +```text +system.db.global_slugs +``` + +Each slug is globally unique. + +Example: + +```text +/company +``` + +may belong to only one owner. + +Duplicate registrations are rejected. + +--- + +## Slug Ownership + +Every slug contains: + +```text +owner_user_id +target_id +target_type +status +``` + +Ownership must match before modification is permitted. + +--- + +## Slug Transfer Protection + +Only administrators may transfer ownership. + +Transfer operations: + +1. Validate destination quotas +2. Validate destination user +3. Copy content +4. Update ownership +5. Record history +6. Write audit event + +--- + +# API Security + +REST API authentication uses API tokens. + +Tokens are stored as hashes. + +Plaintext tokens are shown only once during creation. + +--- + +## API Token Security + +Stored values: + +```text +token_hash +``` + +Never: + +```text +plaintext_token +``` + +If a token is lost: + +1. Revoke it +2. Generate a new token + +--- + +## API Permissions + +Admin tokens: + +```text +Full administrative access +``` + +Standard user tokens: + +```text +Owned resources only +``` + +System accounts: + +```text +API access denied +``` + +--- + +# CSRF Protection + +All dashboard forms require valid CSRF tokens. + +Protected actions include: + +* Login +* User creation +* Password reset +* Content modification +* Moderation actions +* Quota updates +* Backup operations + +--- + +## Invalid CSRF Requests + +Invalid requests return: + +```http +403 Forbidden +``` + +and are rejected before processing. + +--- + +# XSS Protection + +User-supplied content is validated before rendering. + +Templates use: + +```text +Askama +``` + +which escapes output by default. + +Recommended: + +* Do not allow arbitrary JavaScript +* Validate HTML content +* Restrict trusted editors + +--- + +# Content Moderation + +Administrators may: + +* Flag content +* Disable content +* Delete content + +Disabled content returns: + +```http +410 Gone +``` + +for: + +```text +/{slug} +/p/{slug} +/api/qr/{slug}.png +/api/qr/{slug}.svg +``` + +--- + +# Audit Logging + +Security-sensitive actions are logged. + +Examples: + +```text +login +logout +failed_login +user_created +user_deleted +password_reset +slug_transfer +quota_update +backup_created +restore_executed +``` + +Stored in: + +```text +system.db +``` + +Audit logs should be reviewed regularly. + +--- + +# Backup Security + +Backups may contain: + +* User records +* Session records +* URLs +* Pages +* Analytics +* API token hashes + +Backups should be treated as sensitive data. + +--- + +## Recommendations + +Store backups: + +* Offsite +* Encrypted +* Access-controlled + +Never expose backup archives publicly. + +--- + +# Database Security + +SQLite databases should be accessible only to the BZOD service account. + +Recommended permissions: + +```bash +chmod 700 data +chmod 600 *.db +``` + +--- + +# HTTPS Requirements + +Production deployments should always use HTTPS. + +Recommended reverse proxies: + +* Nginx +* Caddy +* Traefik + +Never expose login pages over plaintext HTTP. + +--- + +# Security Headers + +Recommended reverse proxy headers: + +```http +X-Frame-Options: DENY +X-Content-Type-Options: nosniff +Referrer-Policy: strict-origin-when-cross-origin +Content-Security-Policy: default-src 'self' +``` + +--- + +# Password Policy Recommendations + +Recommended minimum: + +```text +12 characters +``` + +Encourage: + +* Password managers +* Unique passwords +* Randomly generated credentials + +Avoid: + +* Reused passwords +* Dictionary words +* Predictable patterns + +--- + +# Brute Force Protection + +Recommended deployment protections: + +* Reverse proxy rate limiting +* Fail2Ban +* Firewall rules + +Example: + +```text +5 login attempts +within 5 minutes +``` + +before temporary blocking. + +--- + +# Administrative Security Checklist + +Before production deployment: + +* Enable HTTPS +* Configure backups +* Review file permissions +* Remove default credentials +* Verify audit logging +* Test restore procedures +* Review active sessions + +--- + +# Incident Response + +If compromise is suspected: + +1. Disable affected accounts. +2. Revoke active sessions. +3. Revoke API tokens. +4. Create forensic backup. +5. Review audit logs. +6. Restore from trusted backups if necessary. +7. Rotate credentials. + +--- + +# Security Testing + +BZOD v0.5.0 includes tests covering: + +* Authentication +* Authorization +* Session validation +* CSRF enforcement +* Slug ownership +* User isolation +* Upgrade migrations +* Backup integrity +* Disaster recovery + +These tests are executed during CI and release validation. + +--- + +# Responsible Disclosure + +If a security vulnerability is discovered: + +1. Do not publish exploit details immediately. +2. Report the issue privately. +3. Allow time for remediation. +4. Coordinate disclosure after a fix is available. + +--- + +# Known Limitations + +Current limitations include: + +* No MFA support +* No SSO integration +* No hardware security key support +* No built-in rate limiter +* No WebAuthn support + +These may be addressed in future releases. + +--- + +# Summary + +BZOD v0.5.0 provides: + +* Centralized authentication +* Secure session management +* RBAC authorization +* Multi-user isolation +* Global slug ownership controls +* CSRF protection +* API token hashing +* Audit logging +* Backup security +* Operational security guidance + +while maintaining a lightweight, SQLite-native, self-hosted architecture. + +--- + +End of Document. diff --git a/docs/UPGRADE.md b/docs/UPGRADE.md new file mode 100644 index 0000000..6ed8e86 --- /dev/null +++ b/docs/UPGRADE.md @@ -0,0 +1,473 @@ +# Upgrade Guide + +Version: v0.5.0 + +This document describes the upgrade process from previous BZOD releases to BZOD v0.5.0. + +--- + +# Overview + +BZOD v0.5.0 introduces the largest architectural change in project history: + +* Multi-user architecture +* Tenant isolation +* Global slug namespace +* Centralized authentication +* User quotas +* User-specific analytics +* Administrative user management +* Backup and restore framework + +Existing v0.4.x deployments can be upgraded without data loss. + +--- + +# Supported Upgrade Paths + +Supported: + +```text +v0.4.0 → v0.5.0 +v0.4.x → v0.5.0 +``` + +Unsupported: + +```text +v0.3.x → v0.5.0 +``` + +Older installations should first upgrade to v0.4.x. + +--- + +# Breaking Changes + +## Database Layout + +### v0.4.x + +```text +data/ +├── admin.db +├── content.db +└── analytics.db +``` + +### v0.5.0 + +```text +data/ +├── users.db +├── system.db +└── users/ + └── 1/ + ├── content.db + └── analytics.db +``` + +--- + +## Authentication + +Authentication is now centralized. + +Old: + +```text +admin.db +``` + +New: + +```text +users.db +``` + +Sessions are managed globally. + +--- + +## Global Slug Namespace + +Slugs are now unique platform-wide. + +Examples: + +```text +/example +/company +/docs +``` + +cannot exist twice. + +--- + +# Pre-Upgrade Checklist + +Before upgrading: + +* Verify current version +* Stop active traffic +* Create backup +* Verify backup integrity + +--- + +## Step 1: Create Backup + +CLI: + +```bash +bzod backup +``` + +or manually archive: + +```bash +tar czf bzod-backup.tar.gz data/ +``` + +--- + +## Step 2: Verify Backup + +Confirm archive contains: + +```text +admin.db +content.db +analytics.db +``` + +--- + +## Step 3: Stop Service + +Systemd: + +```bash +sudo systemctl stop bzod +``` + +Docker: + +```bash +docker compose down +``` + +--- + +# Upgrade Procedure + +## Replace Binary + +Install new release: + +```bash +cargo build --release +``` + +or download release binary. + +--- + +## Start BZOD + +```bash +bzod serve +``` + +On first startup BZOD automatically: + +1. Detects legacy databases. +2. Creates users.db. +3. Creates system.db. +4. Creates administrator tenant. +5. Moves content.db. +6. Moves analytics.db. +7. Creates global slug registry. +8. Runs migrations. + +--- + +# Automatic Migration + +Migration performs: + +## Administrator Creation + +Legacy administrator becomes: + +```text +User ID: 1 +Type: admin +``` + +--- + +## Content Migration + +All URLs migrate into: + +```text +users/1/content.db +``` + +--- + +## Analytics Migration + +All analytics migrate into: + +```text +users/1/analytics.db +``` + +--- + +## Global Slug Registration + +All existing slugs are inserted into: + +```text +system.db.global_slugs +``` + +--- + +# Post-Upgrade Validation + +## Login + +Verify: + +```text +Admin login succeeds +``` + +--- + +## URLs + +Verify: + +```text +Short URLs redirect +``` + +Example: + +```text +https://example.com/abc123 +``` + +--- + +## Landing Pages + +Verify: + +```text +https://example.com/p/demo +``` + +renders correctly. + +--- + +## Analytics + +Verify: + +* Visits visible +* Reports load +* Charts render + +--- + +## User Management + +Verify: + +```text +Admin → Users +``` + +loads correctly. + +--- + +# Upgrade Validation Tests + +BZOD v0.5.0 includes automated migration tests. + +Validated: + +* Legacy admin migration +* Legacy content migration +* Legacy analytics migration +* Slug registration +* Redirect preservation +* Analytics preservation + +Test suite: + +```bash +cargo test --test upgrade_validation_tests +``` + +--- + +# Rollback Procedure + +If upgrade validation fails: + +## Stop Server + +```bash +sudo systemctl stop bzod +``` + +or + +```bash +docker compose down +``` + +--- + +## Restore Backup + +```bash +bzod restore backup.zip +``` + +or restore archived data directory. + +--- + +## Reinstall Previous Release + +Deploy previous v0.4.x binary. + +--- + +# Docker Upgrade + +Pull new image: + +```bash +docker compose pull +``` + +Restart: + +```bash +docker compose up -d +``` + +Monitor logs: + +```bash +docker compose logs -f +``` + +Verify migrations complete successfully. + +--- + +# Systemd Upgrade + +Replace binary: + +```bash +sudo cp bzod /usr/local/bin/ +``` + +Restart: + +```bash +sudo systemctl restart bzod +``` + +Verify: + +```bash +sudo systemctl status bzod +``` + +--- + +# Recommended Upgrade Workflow + +```text +1. Create backup +2. Stop service +3. Install v0.5.0 +4. Start service +5. Run migrations +6. Validate login +7. Validate URLs +8. Validate analytics +9. Validate admin dashboard +10. Return to production +``` + +--- + +# Troubleshooting + +## Login Fails + +Check: + +```text +users.db +``` + +Verify administrator account exists. + +--- + +## URLs Missing + +Verify: + +```text +users/1/content.db +``` + +contains migrated records. + +--- + +## Analytics Missing + +Verify: + +```text +users/1/analytics.db +``` + +contains visit data. + +--- + +## Slug Resolution Fails + +Verify: + +```sql +SELECT * FROM global_slugs; +``` + +returns expected entries. + +--- + +# Upgrade Status + +BZOD v0.5.0 upgrade path has been validated through automated migration and integration testing and is considered production-ready for upgrades from v0.4.x deployments.