Add custom slugs, restore UI, UTM builder, and CLI link tools
This commit is contained in:
thakares committed
1 parent
02a26cfd94
commit
c6486763e3
22 files changed
+999
-113
No files matched your search
@@ -1,26 +1,30 @@
|
||||
# nx9-url-shortener
|
||||
# BZOD
|
||||
|
||||
**A lightweight, self-hosted URL management platform written in Rust.**
|
||||
|
||||
nx9-url-shortener combines URL shortening, QR code generation, password-protected links, smart preview pages, analytics, audit logging, and lifecycle management into a single self-hosted application with zero external dependencies.
|
||||
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.
|
||||
|
||||
Built with Rust, SQLite, Axum, and Askama, nx9-url-shortener is designed for individuals, organizations, homelab operators, and businesses that want complete control over their links, analytics, and branding.
|
||||
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.
|
||||
|
||||
---
|
||||
|
||||
## Highlights
|
||||
|
||||
### v0.2.0
|
||||
### v0.3.0
|
||||
|
||||
* QR code generation (PNG and SVG)
|
||||
* QR scan analytics
|
||||
* 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)
|
||||
* Password-protected links
|
||||
* Smart preview pages
|
||||
* Link expiration
|
||||
* Audit trail
|
||||
* Bulk operations
|
||||
* Expanded test coverage
|
||||
* Improved health monitoring
|
||||
* Analytics dashboard
|
||||
* Audit logging
|
||||
* Health monitoring
|
||||
|
||||
---
|
||||
|
||||
@@ -29,7 +33,9 @@ Built with Rust, SQLite, Axum, and Askama, nx9-url-shortener is designed for ind
|
||||
| Feature | Status |
|
||||
| ------------------------- | ------ |
|
||||
| URL Shortening | ✅ |
|
||||
| Custom Slugs | ✅ |
|
||||
| Landing Pages | ✅ |
|
||||
| Landing Page Custom Slugs | ✅ |
|
||||
| QR Code Generation | ✅ |
|
||||
| QR Analytics | ✅ |
|
||||
| Password-Protected Links | ✅ |
|
||||
@@ -37,11 +43,12 @@ Built with Rust, SQLite, Axum, and Askama, nx9-url-shortener is designed for ind
|
||||
| Link Expiration | ✅ |
|
||||
| One-Time Links | ✅ |
|
||||
| Audit Trail | ✅ |
|
||||
| Bulk Operations | ✅ |
|
||||
| Analytics Dashboard | ✅ |
|
||||
| Health Monitoring | ✅ |
|
||||
| REST API | ✅ |
|
||||
| CSV Import/Export | 🚧 |
|
||||
| Backup & Restore | ✅ |
|
||||
| UTM Campaign Builder | ✅ |
|
||||
| CLI Automation | ✅ |
|
||||
| Geo Analytics | 🚧 |
|
||||
| Multi-User Administration | 🚧 |
|
||||
| SSO | 🚧 |
|
||||
@@ -52,20 +59,74 @@ Built with Rust, SQLite, Axum, and Askama, nx9-url-shortener is designed for ind
|
||||
|
||||
### URL Shortening
|
||||
|
||||
Create short links using compact hexadecimal identifiers.
|
||||
Create compact short URLs using automatically generated hexadecimal identifiers.
|
||||
|
||||
Example:
|
||||
|
||||
```text
|
||||
https://your-short-domain/1bb170
|
||||
https://your-domain/1bb170
|
||||
```
|
||||
|
||||
Redirects to:
|
||||
---
|
||||
|
||||
### Custom Slugs
|
||||
|
||||
Create memorable human-readable links.
|
||||
|
||||
Examples:
|
||||
|
||||
```text
|
||||
https://very-long-domain-name.com
|
||||
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
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Landing Pages
|
||||
|
||||
Create standalone landing pages hosted directly by BZOD.
|
||||
|
||||
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
|
||||
|
||||
---
|
||||
|
||||
### QR Code Generation
|
||||
@@ -88,20 +149,20 @@ Features:
|
||||
|
||||
### Password-Protected Links
|
||||
|
||||
Protect sensitive links using Argon2id-hashed passwords.
|
||||
Protect sensitive links using Argon2id password hashing.
|
||||
|
||||
Features:
|
||||
|
||||
* Password gate
|
||||
* Secure session handling
|
||||
* Configurable protection
|
||||
* Access restrictions
|
||||
* Audit logging
|
||||
|
||||
---
|
||||
|
||||
### Smart Preview Pages
|
||||
|
||||
Display branded preview pages before redirecting.
|
||||
Display branded preview pages before redirecting visitors.
|
||||
|
||||
Features:
|
||||
|
||||
@@ -113,18 +174,6 @@ Features:
|
||||
|
||||
---
|
||||
|
||||
### Landing Pages
|
||||
|
||||
Create standalone landing pages using dedicated page identifiers.
|
||||
|
||||
Example:
|
||||
|
||||
```text
|
||||
https://your-short-domain/p/1a2b
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Link Lifecycle Management
|
||||
|
||||
Control link validity.
|
||||
@@ -132,10 +181,32 @@ Control link validity.
|
||||
Features:
|
||||
|
||||
* Expiration dates
|
||||
* Automatic expiry jobs
|
||||
* One-time links
|
||||
* Maximum access limits
|
||||
* Administrative disabling
|
||||
* 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.
|
||||
|
||||
---
|
||||
|
||||
@@ -145,7 +216,7 @@ Track:
|
||||
|
||||
* Total visits
|
||||
* QR scans
|
||||
* Country statistics
|
||||
* Countries
|
||||
* Referrers
|
||||
* User agents
|
||||
* Daily statistics
|
||||
@@ -156,39 +227,46 @@ Track:
|
||||
|
||||
### Audit Trail
|
||||
|
||||
Track administrative actions including:
|
||||
Track administrative activity.
|
||||
|
||||
Recorded events include:
|
||||
|
||||
* Login
|
||||
* Logout
|
||||
* URL creation
|
||||
* URL updates
|
||||
* URL deletion
|
||||
* QR operations
|
||||
* Backup creation
|
||||
* Restore operations
|
||||
* QR exports
|
||||
* Configuration changes
|
||||
|
||||
---
|
||||
|
||||
### Administrative Dashboard
|
||||
|
||||
Web-based administration interface featuring:
|
||||
Web-based management interface.
|
||||
|
||||
* URL management
|
||||
* QR code management
|
||||
* Landing page management
|
||||
* Preview page management
|
||||
Features:
|
||||
|
||||
* URL registry
|
||||
* Landing pages
|
||||
* QR management
|
||||
* Analytics
|
||||
* API token management
|
||||
* Audit logs
|
||||
* Link expiration controls
|
||||
* Backup utilities
|
||||
* Restore utilities
|
||||
* Health monitoring
|
||||
* Analytics dashboard
|
||||
* SVG charts
|
||||
* Bulk operations
|
||||
* Server diagnostics
|
||||
|
||||
---
|
||||
|
||||
### API Support
|
||||
### REST API
|
||||
|
||||
REST API endpoints for automation and integration.
|
||||
REST API support for automation and integrations.
|
||||
|
||||
Endpoint prefix:
|
||||
|
||||
```text
|
||||
/api/v1/*
|
||||
@@ -198,22 +276,88 @@ Supports:
|
||||
|
||||
* URL creation
|
||||
* URL management
|
||||
* Landing pages
|
||||
* QR generation
|
||||
* Analytics access
|
||||
* Bulk operations
|
||||
|
||||
---
|
||||
|
||||
### 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 interface
|
||||
* Password-protected administration
|
||||
* Password-protected links
|
||||
* Argon2id password hashing
|
||||
* Session management
|
||||
* CSRF protection
|
||||
* Session management
|
||||
* API token authentication
|
||||
* Audit logging
|
||||
* Link access controls
|
||||
* Access controls
|
||||
|
||||
---
|
||||
|
||||
@@ -235,7 +379,7 @@ No:
|
||||
* PostgreSQL
|
||||
* MongoDB
|
||||
* Kubernetes
|
||||
* External SaaS
|
||||
* SaaS dependencies
|
||||
|
||||
---
|
||||
|
||||
@@ -243,21 +387,19 @@ No:
|
||||
|
||||
### Databases
|
||||
|
||||
nx9-url-shortener uses four SQLite databases.
|
||||
BZOD uses four SQLite databases.
|
||||
|
||||
| Database | Purpose |
|
||||
| ------------ | ------------------------------------------------- |
|
||||
| admin.db | Users, sessions, API keys |
|
||||
| content.db | URLs, landing pages, preview pages, tags |
|
||||
| analytics.db | Visits, QR scans, statistics |
|
||||
| system.db | Audit events, jobs, migrations, health monitoring |
|
||||
| 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
|
||||
|
||||
Create an administrator account:
|
||||
|
||||
### Native Installation
|
||||
|
||||
```bash
|
||||
@@ -267,11 +409,40 @@ cargo run -- create-admin
|
||||
### Docker
|
||||
|
||||
```bash
|
||||
docker exec -it nx9-url-shortener nx9-url-shortener create-admin
|
||||
docker exec -it bzod bzod create-admin
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Disaster Recovery Validation
|
||||
|
||||
The backup and restore system has been validated through a complete recovery workflow.
|
||||
|
||||
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
|
||||
* API tokens
|
||||
* QR assets
|
||||
* Settings
|
||||
* Health monitoring
|
||||
|
||||
Expected outcome:
|
||||
|
||||
The application returns to a fully operational state without data loss.
|
||||
|
||||
---
|
||||
|
||||
## Screenshots
|
||||
|
||||
### Dashboard
|
||||
@@ -298,22 +469,22 @@ docker exec -it nx9-url-shortener nx9-url-shortener create-admin
|
||||
|
||||
## Docker Deployment
|
||||
|
||||
### Build
|
||||
Build:
|
||||
|
||||
```bash
|
||||
docker compose build
|
||||
```
|
||||
|
||||
### Start
|
||||
Start:
|
||||
|
||||
```bash
|
||||
docker compose up -d
|
||||
```
|
||||
|
||||
### Logs
|
||||
Logs:
|
||||
|
||||
```bash
|
||||
docker logs -f nx9-url-shortener
|
||||
docker logs -f bzod
|
||||
```
|
||||
|
||||
---
|
||||
@@ -322,9 +493,9 @@ docker logs -f nx9-url-shortener
|
||||
|
||||
```yaml
|
||||
services:
|
||||
nx9-url-shortener:
|
||||
bzod:
|
||||
build: .
|
||||
container_name: nx9-url-shortener
|
||||
container_name: bzod
|
||||
restart: unless-stopped
|
||||
|
||||
ports:
|
||||
@@ -344,33 +515,44 @@ services:
|
||||
|
||||
## Development
|
||||
|
||||
### Build
|
||||
Build:
|
||||
|
||||
```bash
|
||||
cargo build
|
||||
```
|
||||
|
||||
### Run
|
||||
Run:
|
||||
|
||||
```bash
|
||||
cargo run -- serve
|
||||
```
|
||||
|
||||
### Create Administrator
|
||||
Create administrator:
|
||||
|
||||
```bash
|
||||
cargo run -- create-admin
|
||||
```
|
||||
|
||||
### Run Tests
|
||||
Run tests:
|
||||
|
||||
```bash
|
||||
cargo test
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Development & Testing
|
||||
|
||||
See [docs/TESTING.md](docs/TESTING.md) for comprehensive testing, validation, backup, restore, disaster recovery, and release procedures.
|
||||
See:
|
||||
|
||||
```text
|
||||
docs/TESTING.md
|
||||
```
|
||||
|
||||
for testing, validation, backup, restore, disaster recovery, and release procedures.
|
||||
|
||||
---
|
||||
|
||||
## Project Structure
|
||||
|
||||
```text
|
||||
@@ -394,20 +576,17 @@ src/
|
||||
|
||||
Planned features:
|
||||
|
||||
* Vanity URLs
|
||||
* CSV import/export
|
||||
* Geo analytics
|
||||
* Multi-user administration
|
||||
* SSO integration
|
||||
* Signed temporary links
|
||||
* OpenAPI documentation
|
||||
* Webhook support
|
||||
|
||||
---
|
||||
|
||||
## Production Deployment
|
||||
|
||||
Recommended stack:
|
||||
Recommended architecture:
|
||||
|
||||
```text
|
||||
Internet
|
||||
@@ -416,7 +595,7 @@ Internet
|
||||
Nginx Proxy Manager
|
||||
│
|
||||
▼
|
||||
nx9-url-shortener
|
||||
BZOD
|
||||
│
|
||||
▼
|
||||
SQLite
|
||||
@@ -437,4 +616,3 @@ Apache License 2.0
|
||||
Sunil Purushottam Thakare
|
||||
|
||||
Built with Rust, SQLite, Axum, Askama, and a preference for simple, maintainable software.
|
||||
|
||||
Reference in new issue
Block a user