# Kutt URL Shortener

> Modern URL shortener with custom domains and analytics.

- Category: Productivity & Collaboration
- Difficulty: beginner
- Components: kutt, postgresql, redis
- Tags: url-shortener, kutt, analytics, custom-domains
- Source: https://docker.recipes/productivity/kutt-url-shortener

## Overview

Kutt is a modern, open-source URL shortener that prioritizes user privacy and customization. Built with Node.js and React, it offers a clean alternative to services like bit.ly or TinyURL, allowing organizations to maintain control over their shortened URLs with custom domains, detailed analytics, and comprehensive API access. Unlike cloud-based services, Kutt can be self-hosted to ensure complete data ownership and privacy compliance.

This deployment orchestrates three specialized services: the main Kutt application server handling the web interface and API, a PostgreSQL database for storing URLs and user data with full ACID compliance, and Redis for high-performance caching and session management. The PostgreSQL database ensures data integrity for user accounts, shortened URLs, and click analytics, while Redis accelerates response times by caching frequently accessed links and managing user sessions.

This stack is ideal for organizations requiring branded URL shortening with complete data control, marketing teams needing detailed link analytics, and developers building applications that integrate URL shortening functionality. The combination of PostgreSQL's reliability and Redis's speed creates a robust foundation for high-traffic URL shortening workloads while maintaining the flexibility to customize domains, user limits, and administrative controls.

## Features

- Custom domain support for branded shortened URLs with full DNS configuration
- Comprehensive link analytics including click tracking, referrer data, and geographic statistics
- RESTful API for programmatic URL creation and management with authentication
- QR code generation for shortened URLs with customizable styling options
- User management system with registration controls and daily link limits
- Admin panel for user oversight, link moderation, and system configuration
- Anonymous link creation support with optional registration requirements
- PostgreSQL-backed data persistence ensuring ACID compliance for all URL and user data

## Use cases

- Corporate marketing campaigns requiring branded short URLs with detailed click analytics
- Social media management teams tracking engagement across multiple platforms
- Developer teams integrating URL shortening into applications via API
- Educational institutions sharing course materials with trackable links
- Event organizers distributing registration and information links with usage metrics
- Privacy-conscious organizations avoiding third-party URL shortening services
- SaaS companies providing URL shortening features to their customers

## Prerequisites

- Minimum 1.5GB RAM to support PostgreSQL database operations and Redis caching
- Port 3000 available for the Kutt web interface and API access
- Valid domain name configured for custom URL shortening (optional but recommended)
- Environment variables configured for database credentials, JWT secrets, and admin emails
- Basic understanding of PostgreSQL administration for database maintenance
- SMTP server details if email notifications and user registration features are enabled

## docker-compose.yml

```yaml
services:
  kutt:
    image: kutt/kutt:latest
    container_name: kutt
    environment:
      - DB_HOST=db
      - DB_PORT=5432
      - DB_NAME=kutt
      - DB_USER=kutt
      - DB_PASSWORD=${DB_PASSWORD}
      - REDIS_HOST=redis
      - REDIS_PORT=6379
      - SITE_NAME=Kutt
      - DEFAULT_DOMAIN=${DEFAULT_DOMAIN}
      - LINK_LENGTH=6
      - DISALLOW_REGISTRATION=false
      - DISALLOW_ANONYMOUS_LINKS=false
      - USER_LIMIT_PER_DAY=50
      - ADMIN_EMAILS=${ADMIN_EMAIL}
      - REPORT_EMAIL=${REPORT_EMAIL}
      - CONTACT_EMAIL=${CONTACT_EMAIL}
      - JWT_SECRET=${JWT_SECRET}
    ports:
      - "3000:3000"
    depends_on:
      - db
      - redis
    networks:
      - kutt-network
    restart: unless-stopped

  db:
    image: postgres:15-alpine
    container_name: kutt-db
    environment:
      - POSTGRES_USER=kutt
      - POSTGRES_PASSWORD=${DB_PASSWORD}
      - POSTGRES_DB=kutt
    volumes:
      - postgres-data:/var/lib/postgresql/data
    networks:
      - kutt-network
    restart: unless-stopped

  redis:
    image: redis:7-alpine
    container_name: kutt-redis
    volumes:
      - redis-data:/data
    networks:
      - kutt-network
    restart: unless-stopped

volumes:
  postgres-data:
  redis-data:

networks:
  kutt-network:
    driver: bridge
```

## .env

```bash
# Kutt
DEFAULT_DOMAIN=kutt.example.com
ADMIN_EMAIL=admin@example.com
REPORT_EMAIL=report@example.com
CONTACT_EMAIL=contact@example.com
DB_PASSWORD=secure_kutt_password

# Generate with: openssl rand -hex 32
JWT_SECRET=your_jwt_secret
```

## Usage notes

- Web UI at http://localhost:3000
- Register first account
- Custom domains support
- Link analytics and QR codes
- API available

## Troubleshooting

- Kutt container fails to start with database connection errors: Ensure DB_PASSWORD environment variable matches POSTGRES_PASSWORD and db service is fully initialized
- Short URLs return 404 errors: Verify DEFAULT_DOMAIN environment variable matches your actual domain and DNS is properly configured
- User registration fails silently: Check that ADMIN_EMAILS, REPORT_EMAIL, and CONTACT_EMAIL environment variables are set with valid email addresses
- Redis connection timeouts causing slow performance: Increase Redis memory limits or check redis container logs for memory pressure warnings
- JWT authentication errors on login: Regenerate JWT_SECRET environment variable and restart kutt container to refresh authentication tokens
- PostgreSQL data corruption after container restart: Ensure postgres-data volume has proper permissions and sufficient disk space for database growth

