ZipURL

A modern, self-hosted URL shortener built with Rust and Leptos, featuring UTM parameter tracking, Open Graph metadata support, and OIDC authentication.

Features

• URL Shortening - Create short, memorable links with custom codes
• UTM Tracking - Automatically append UTM parameters to track campaigns
• Open Graph Metadata - Auto-fetch and customize social media preview cards
• Multi-Domain Support - Manage multiple short link domains
• API Key Management - Secure API access with SHA-256 hashed keys
• Tag System - Organize links with tags for better management
• OIDC Authentication - Integrate with Keycloak or any OIDC provider
• Analytics - Track click counts and link performance
• Bot Detection - Identify and filter bot traffic
• QR Code Generation - Generate QR codes for short links
• Prometheus Metrics - Monitor your instance with built-in metrics

Technology Stack

• Backend: Rust with Axum web framework
• Frontend: Leptos (full-stack SSR framework)
• Database: redb (embedded key-value store)
• Styling: Tailwind CSS v4
• Build: cargo-leptos with WASM compilation

Quick Start

See QUICKSTART.md for detailed setup instructions.

# Enter development environment (requires Nix)
nix develop

# Copy example config
cp config.toml.example config.toml

# Start development server
just dev

# Access at http://localhost:1337

Architecture

ZipURL is organized as a Rust workspace with four crates:

• zipurl-core - Shared data models and types
• zipurl-server - Backend API, database, and authentication
• zipurl-client - Browser-side utilities (WASM)
• zipurl-app - Leptos full-stack application

The application uses server-side rendering (SSR) with client-side hydration for optimal performance and SEO.

Development

just dev          # Start dev server with hot reload
just test         # Run tests
just fmt          # Format code
just lint         # Run clippy linter
just build-release # Production build

See CLAUDE.md for comprehensive development documentation.

Configuration

Configuration is managed via config.toml (see config.toml.example):

• Database path and server settings
• Authentication provider (none/mock/OIDC/Keycloak)
• Environment variables override file settings

API

ZipURL provides a RESTful API for programmatic access:

• /api/domains - Domain management
• /api/urls - URL shortening and retrieval
• /api/tags - Tag management
• /api/metadata - Open Graph metadata
• /:code - Redirect endpoint

Authentication via Authorization: Bearer <API_KEY> header.

Deployment

Docker

just docker-build
just docker-run

Manual

just build-release
# Binary: target/release/zipurl-app
# Static assets: target/site/

License

This project is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0). See LICENSE.md for details.

The AGPL-3.0 requires that if you modify this software and provide it as a service over a network, you must make the modified source code available to users of that service.

Contributing

Contributions are welcome! Please ensure:

• Code is formatted with rustfmt and passes clippy
• Tests pass with just test
• Frontend compiles for wasm32 target
• Commit messages follow conventional commits format

Support

For issues, questions, or feature requests, please open an issue on GitHub.

Acknowledgments

Built with:

• Leptos - Full-stack Rust web framework
• Axum - Web application framework
• redb - Embedded database
• Tailwind CSS - Utility-first CSS framework