4.8 KiB
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:
v0.4.0 → v0.5.0
v0.4.x → v0.5.0
Unsupported:
v0.3.x → v0.5.0
Older installations should first upgrade to v0.4.x.
Breaking Changes
Database Layout
v0.4.x
data/
├── admin.db
├── content.db
└── analytics.db
v0.5.0
data/
├── users.db
├── system.db
└── users/
└── 1/
├── content.db
└── analytics.db
Authentication
Authentication is now centralized.
Old:
admin.db
New:
users.db
Sessions are managed globally.
Global Slug Namespace
Slugs are now unique platform-wide.
Examples:
/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:
bzod backup
or manually archive:
tar czf bzod-backup.tar.gz data/
Step 2: Verify Backup
Confirm archive contains:
admin.db
content.db
analytics.db
Step 3: Stop Service
Systemd:
sudo systemctl stop bzod
Docker:
docker compose down
Upgrade Procedure
Replace Binary
Install new release:
cargo build --release
or download release binary.
Start BZOD
bzod serve
On first startup BZOD automatically:
- Detects legacy databases.
- Creates users.db.
- Creates system.db.
- Creates administrator tenant.
- Moves content.db.
- Moves analytics.db.
- Creates global slug registry.
- Runs migrations.
Automatic Migration
Migration performs:
Administrator Creation
Legacy administrator becomes:
User ID: 1
Type: admin
Content Migration
All URLs migrate into:
users/1/content.db
Analytics Migration
All analytics migrate into:
users/1/analytics.db
Global Slug Registration
All existing slugs are inserted into:
system.db.global_slugs
Post-Upgrade Validation
Login
Verify:
Admin login succeeds
URLs
Verify:
Short URLs redirect
Example:
https://example.com/abc123
Landing Pages
Verify:
https://example.com/p/demo
renders correctly.
Analytics
Verify:
- Visits visible
- Reports load
- Charts render
User Management
Verify:
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:
cargo test --test upgrade_validation_tests
Rollback Procedure
If upgrade validation fails:
Stop Server
sudo systemctl stop bzod
or
docker compose down
Restore Backup
bzod restore backup.zip
or restore archived data directory.
Reinstall Previous Release
Deploy previous v0.4.x binary.
Docker Upgrade
Pull new image:
docker compose pull
Restart:
docker compose up -d
Monitor logs:
docker compose logs -f
Verify migrations complete successfully.
Systemd Upgrade
Replace binary:
sudo cp bzod /usr/local/bin/
Restart:
sudo systemctl restart bzod
Verify:
sudo systemctl status bzod
Recommended Upgrade Workflow
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:
users.db
Verify administrator account exists.
URLs Missing
Verify:
users/1/content.db
contains migrated records.
Analytics Missing
Verify:
users/1/analytics.db
contains visit data.
Slug Resolution Fails
Verify:
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.