474 lines
4.8 KiB
Markdown
474 lines
4.8 KiB
Markdown
# 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.
|