nx9-url-shortener/docs/INSTALL.md

BZOD Installation Guide

Version: v0.7.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:

docker
docker compose

Verify:

docker --version
docker compose version

---

Create Directory

mkdir -p /opt/bzod
cd /opt/bzod

---

Copy Files

Required:

docker-compose.yml
Dockerfile

Optional:

bzod.service

---

Start Container

docker compose up -d

Verify:

docker compose ps

View logs:

docker compose logs -f

---

Stop Container

docker compose down

---

Restart Container

docker compose restart

---

Native Installation

Install Dependencies

Debian / Ubuntu

sudo apt update

sudo apt install -y \
    build-essential \
    pkg-config \
    libssl-dev \
    sqlite3

Arch Linux

sudo pacman -S \
    base-devel \
    openssl \
    sqlite

---

Download Release Binary

Example:

wget https://example.com/bzod-v0.7.0-linux-amd64.tar.gz

Extract:

tar -xzf bzod-v0.7.0-linux-amd64.tar.gz

Install:

sudo install -m755 bzod /usr/local/bin/bzod

Verify:

bzod --help

---

Build From Source

Install Rust

curl https://sh.rustup.rs -sSf | sh

Verify:

cargo --version
rustc --version

---

Clone Repository

git clone https://github.com/thakares/nx9-url-shortener.git

cd nx9-url-shortener

---

Build

Development:

cargo build

Release:

cargo build --release

Binary:

target/release/bzod

---

Data Directory

BZOD automatically creates its databases on first startup.

Default structure:

data/
├── users.db
├── system.db
│
├── admin/
│   ├── content.db
│   └── analytics.db
│
└── users/
    └── ...

Do not manually modify database files while BZOD is running.

---

First Startup

Run:

bzod serve

By default:

http://localhost:8080

Open:

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:

bzod create-admin

Follow prompts:

Username:
Password:

The administrator account is stored in:

users.db

---

Reverse Proxy Configuration

Using Nginx is recommended.

Example:

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:

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:

sudo install -m755 bzod /usr/local/bin/bzod

Copy service:

sudo cp bzod.service /etc/systemd/system/

Reload:

sudo systemctl daemon-reload

Enable:

sudo systemctl enable bzod

Start:

sudo systemctl start bzod

Status:

sudo systemctl status bzod

Logs:

journalctl -u bzod -f

---

Firewall

Open HTTP:

sudo ufw allow 8080/tcp

HTTPS:

sudo ufw allow 443/tcp

HTTP:

sudo ufw allow 80/tcp

---

Health Verification

Open:

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:

bzod backup

Stop service:

sudo systemctl stop bzod

Replace binary.

Run migrations:

bzod migrate

Start service:

sudo systemctl start bzod

Verify logs.

See:

docs/UPGRADE.md

---

Troubleshooting

Port Already In Use

Check:

ss -tulpn | grep 8080

Change port or stop conflicting service.

---

Database Locked

Verify only one BZOD instance is running:

ps aux | grep bzod

---

Permission Errors

Verify ownership:

chown -R bzod:bzod data/

---

Login Problems

Verify:

• Administrator account exists
• Session cookies enabled
• System clock is correct

---

View Logs

Systemd:

journalctl -u bzod -f

Docker:

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.