thakares/nx9-url-shortener
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
pre-refactor-stable
nx9-url-shortener/README.md
T

6.4 KiB
Raw Permalink Blame History

nx9-url-shortener

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.

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.

Highlights

v0.2.0

  • QR code generation (PNG and SVG)
  • QR scan analytics
  • Password-protected links
  • Smart preview pages
  • Link expiration
  • Audit trail
  • Bulk operations
  • Expanded test coverage
  • Improved health monitoring

Feature Matrix

Feature Status
URL Shortening ✅
Landing Pages ✅
QR Code Generation ✅
QR Analytics ✅
Password-Protected Links ✅
Smart Preview Pages ✅
Link Expiration ✅
One-Time Links ✅
Audit Trail ✅
Bulk Operations ✅
Analytics Dashboard ✅
Health Monitoring ✅
REST API ✅
CSV Import/Export 🚧
Geo Analytics 🚧
Multi-User Administration 🚧
SSO 🚧

Features

URL Shortening

Create short links using compact hexadecimal identifiers.

Example:

https://your-short-domain/1bb170

Redirects to:

https://very-long-domain-name.com

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-hashed passwords.

Features:

  • Password gate
  • Secure session handling
  • Configurable protection
  • Audit logging

Smart Preview Pages

Display branded preview pages before redirecting.

Features:

  • Custom title
  • Description
  • Logo support
  • Open Graph metadata
  • Social sharing previews

Landing Pages

Create standalone landing pages using dedicated page identifiers.

Example:

https://your-short-domain/p/1a2b

Link Lifecycle Management

Control link validity.

Features:

  • Expiration dates
  • Automatic expiry jobs
  • One-time links
  • Maximum access limits
  • Administrative disabling

Analytics

Track:

  • Total visits
  • QR scans
  • Country statistics
  • Referrers
  • User agents
  • Daily statistics
  • Monthly statistics
  • Yearly statistics

Audit Trail

Track administrative actions including:

  • Login
  • Logout
  • URL creation
  • URL updates
  • URL deletion
  • QR operations
  • Configuration changes

Administrative Dashboard

Web-based administration interface featuring:

  • URL management
  • QR code management
  • Landing page management
  • Preview page management
  • API token management
  • Audit logs
  • Link expiration controls
  • Health monitoring
  • Analytics dashboard
  • SVG charts
  • Bulk operations

API Support

REST API endpoints for automation and integration.

/api/v1/*

Supports:

  • URL creation
  • URL management
  • QR generation
  • Analytics access
  • Bulk operations

Security

  • Password-protected administration interface
  • Password-protected links
  • Argon2id password hashing
  • Session management
  • CSRF protection
  • API token authentication
  • Audit logging
  • Link access controls

Self-Hosted

No external services required.

Dependencies:

  • Rust
  • SQLite
  • Docker (optional)

No:

  • React
  • Node.js
  • Redis
  • PostgreSQL
  • MongoDB
  • Kubernetes
  • External SaaS

Architecture

Databases

nx9-url-shortener 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

Initial Setup

Create an administrator account:

Native Installation

cargo run -- create-admin

Docker

docker exec -it nx9-url-shortener nx9-url-shortener create-admin

Screenshots

Dashboard

Dashboard

URL Management

URL Management

Landing Pages

Landing Pages

Settings

Settings

Server Status

Server Status

Docker Deployment

Build

docker compose build

Start

docker compose up -d

Logs

docker logs -f nx9-url-shortener

Docker Compose Example

services:
  nx9-url-shortener:
    build: .
    container_name: nx9-url-shortener
    restart: unless-stopped

    ports:
      - "8654:8654"

    volumes:
      - ./data:/app/data
      - ./config:/app/config

    environment:
      HOST: 0.0.0.0
      PORT: 8654
      DATA_DIR: /app/data

Development

Build

cargo build

Run

cargo run -- serve

Create Administrator

cargo run -- create-admin

Run Tests

cargo test

Project Structure

src/
├── analytics/
├── auth/
├── charts/
├── cli/
├── db/
├── jobs/
├── models/
├── services/
├── templates/
├── utils/
└── web/

Roadmap

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:

Internet
    │
    ▼
Nginx Proxy Manager
    │
    ▼
nx9-url-shortener
    │
    ▼
SQLite

HTTPS is strongly recommended.

License

Apache License 2.0

Author

Sunil Purushottam Thakare

Built with Rust, SQLite, Axum, Askama, and a preference for simple, maintainable software.

Reference in new issue View Git Blame Copy Permalink