Open Short URL

A powerful, self-hosted URL shortener with advanced analytics and privacy-first design

Transform long, unwieldy URLs into short, memorable links while maintaining complete control over your data. Perfect for businesses, marketers, and privacy-conscious users who need more than basic link shortening.

English | 繁體中文

---

Why Open Short URL?

🔐 Your Data, Your Control

Unlike commercial URL shorteners, your data stays on your server. No third-party tracking, no data selling, complete privacy.

💰 Cost-Effective

Free yourself from expensive SaaS subscriptions:

• No monthly or annual fees
• No link/click limits or quotas
• One-time infrastructure investment
• Scale without increasing costs
• Predictable operational expenses

📊 Comprehensive Analytics

Track every click with detailed insights:

• Real-time click tracking
• Geographic location data
• Device and browser analytics
• Referrer tracking
• UTM campaign monitoring

🎨 White-Label Ready

Fully customizable branding:

• Custom domain support
• Branded password pages
• Personalized logos and colors
• Your brand, your way

🔒 Advanced Security

• Password-protected URLs
• Expiration dates for temporary links
• Rate limiting to prevent abuse
• Cloudflare Turnstile integration
• Role-based access control (ADMIN/USER)

🚀 Enterprise Features

• RESTful API with comprehensive documentation
• API key management for integrations
• Two-factor authentication (2FA)
• Bulk URL management
• QR code generation
• Multi-language support (English, Traditional Chinese)

---

Key Features

✨ Smart Link Management

• Custom slugs or auto-generated short codes
• Dynamic slug length based on usage
• Link expiration and scheduling
• Status control (ACTIVE/INACTIVE)

📈 Powerful Analytics

• Click statistics dashboard
• Time-series analysis
• Geographic distribution
• Device and platform breakdown
• UTM parameter tracking

🔑 Flexible Authentication

• JWT-based user authentication
• API key support for server integrations
• Two-factor authentication
• Session management

🎯 Marketing Tools

• Password protection for sensitive links
• UTM parameter builder
• QR code generation
• Brand customization

⚡ High Performance

• Optional Redis caching for fast redirects
• PostgreSQL for reliable data storage
• Optimized for scale

---

Deployment

One-Click Deploy to Railway

The fastest way to get started is deploying to Railway with a single click:

This will automatically:

• ✅ Deploy frontend and backend services
• ✅ Provision PostgreSQL and Redis databases
• ✅ Configure environment variables

Important:

• ⚠️ Custom domains must be configured manually in Railway settings
• 🔐 Change the default admin password immediately after deployment

---

Redis Usage Guidelines

Redis is completely optional with automatic graceful degradation. The system works perfectly without Redis.

🎯 What Uses Redis?

When Redis is available, these features use it for better performance:

1. URL Query Cache - Faster redirects (300ms → 10-20ms)
2. Token Blacklist - Shared across multiple instances (logout sync)
3. Rate Limiting - Accurate throttling across instances

🔄 Automatic Fallback (No Redis Configuration)

If REDIS_HOST is not set, the system automatically uses fallback mechanisms:

Feature	Without Redis	Impact
URL Cache	Disabled (direct DB queries)	Slower redirects, higher DB load
Token Blacklist	In-memory Map	Works in single instance only
Rate Limiting	In-memory Map	Works in single instance only

System Status: Fully functional, just slower for high traffic.

❌ Skip Redis (< 10K daily clicks)

Perfect for:

• Personal use or small team tools
• Development/testing environments
• Budget-constrained early stage
• Single-instance deployments

Metrics:

• Traffic: < 10,000 clicks/day (~0.12 QPS)
• Peak concurrency: < 10 requests/second

Benefits:

• ✅ Lower infrastructure costs (~$5-10/month)
• ✅ Simpler maintenance (one less service)
• ✅ No Redis configuration needed

✅ Use Redis (> 50K daily clicks)

Recommended for:

• Marketing campaigns with traffic spikes
• Frequent analytics page views
• Popular URLs (20% URLs = 80% traffic)
• Multi-instance deployments

Metrics:

• Traffic: > 50,000 clicks/day (~0.6 QPS)
• Peak concurrency: > 20 requests/second

Performance boost:

• Redirect time: 300ms → 10-20ms
• Database load: -70% to -90%
• Can handle 10-100x traffic
• Logout syncs across all instances

Cost: ~$15-25/month (5-10x performance improvement)

⚠️ Redis Strongly Recommended (> 1M daily clicks)

Essential for:

• SaaS products or high-traffic services
• Multi-instance production deployments
• Services requiring guaranteed rate limiting

Metrics:

• Traffic: > 1,000,000 clicks/day (~12 QPS)
• Peak concurrency: > 100 requests/second

Risk without Redis:

• Database becomes bottleneck
• Degraded user experience
• Rate limiting per instance (not global)

📊 How to Decide

Monitor these metrics:

• DB query time > 200ms → Consider Redis
• Redirect response > 500ms → Need optimization
• Same URL queried > 10 times/hour → Cache helps
• Multiple instances → Need Redis for sync

🚀 Railway Deployment

Option A: Without Redis (Simple & Cheap)

1. Don't add Redis service
2. Don't set REDIS_HOST environment variable
3. System uses automatic fallback
4. Cost: ~$5-10/month

Option B: With Redis (Performance)

1. Add Redis service in Railway
2. Environment variables auto-configured:

   REDIS_HOST=${{Redis.RAILWAY_PRIVATE_DOMAIN}}
   REDIS_PORT=${{Redis.REDISPORT}}
   REDIS_PASSWORD=${{Redis.REDISPASSWORD}}
   

3. System automatically detects and uses Redis
4. Cost: ~$15-25/month

Switch anytime: Add or remove Redis without code changes. The system automatically adapts.

---

Quick Start

Prerequisites

• Node.js 18+
• PostgreSQL 14+
• Redis 6+ (optional, for caching)

Installation

1. Clone the repository

git clone https://github.com/supra126/open-short-url.git
cd open-short-url

2. Install dependencies

yarn install

3. Configure environment

# Backend
cp apps/backend/.env.example apps/backend/.env.local
# Edit apps/backend/.env.local with your database credentials

# Frontend
cp apps/frontend/.env.example apps/frontend/.env.local
# Edit apps/frontend/.env.local with your API URL
# Optional: Set NEXT_PUBLIC_LOCALE=zh-TW for Traditional Chinese (default: en)

4. Setup database

cd apps/backend
yarn prisma:migrate
yarn prisma:seed

5. Start development servers

# From project root
yarn dev

Visit:

• Frontend: http://localhost:4100
• Backend API: http://localhost:4101
• API Documentation: http://localhost:4101/api

Default credentials: admin@example.com / admin123

---

Use Cases

For Businesses

• Create branded short links for marketing campaigns
• Track campaign performance with detailed analytics
• Password-protect confidential links
• Maintain brand consistency across channels

For Developers

• Self-hosted solution with full API access
• Integrate with existing systems via REST API
• Customize and extend functionality
• No vendor lock-in

For Privacy Advocates

• Complete data ownership
• No third-party tracking
• GDPR compliant
• Open source transparency

---

Technology Stack

• Backend: NestJS, Prisma, PostgreSQL, Redis (optional)
• Frontend: Next.js 15, React 19, TypeScript, Tailwind CSS
• Security: JWT, bcrypt, Cloudflare Turnstile
• Analytics: Real-time click tracking with geographic data

---

Roadmap

• Webhook support for events
• Link bundles/collections
• Dark mode
• Audit logs

---

License

This project is licensed under the MIT License - see the LICENSE file for details.

---

Support

• 🐛 Issue Tracker
• 💬 Discussions