# Shlink URL Shortener

> Self-hosted URL shortener with analytics and API.

- Category: Productivity & Collaboration
- Difficulty: beginner
- Components: shlink, shlink-web-client, postgresql, redis
- Tags: url-shortener, shlink, analytics, links, tracking
- Source: https://docker.recipes/productivity/shlink-url-shortener

## Overview

Shlink is a powerful, open-source URL shortener developed by Alejandro Celaya that provides comprehensive link management with detailed analytics, QR code generation, and a robust REST API. Unlike simple URL shorteners, Shlink offers enterprise-grade features including geolocation tracking, visit analytics, custom domains, and extensive customization options while maintaining complete control over your data through self-hosting.

This deployment creates a complete Shlink ecosystem using four specialized containers: the main Shlink API server for URL processing and analytics, a dedicated web client for user interface management, PostgreSQL for reliable data persistence, and Redis for high-performance caching and session management. The PostgreSQL database ensures ACID compliance and complex query capabilities for analytics, while Redis provides sub-millisecond response times for frequently accessed short URLs and caching layer optimization.

This stack is ideal for organizations requiring branded short URLs with detailed analytics, marketing teams needing campaign tracking, developers building applications with URL shortening APIs, and privacy-conscious users who want full control over their link data. The combination of Shlink's feature-rich API with PostgreSQL's analytical capabilities and Redis's performance optimization creates a production-ready URL shortening service that scales from personal use to enterprise deployments.

## Features

- Custom domain support with SSL/HTTPS configuration for branded short URLs
- Comprehensive visit analytics including geolocation, referrer tracking, and device detection
- QR code generation with customizable size and format options for each shortened URL
- REST API with authentication for programmatic URL creation and management
- Real-time visit tracking with Redis-powered caching for instant response times
- PostgreSQL-backed analytics with complex query capabilities for detailed reporting
- Multi-user support with API key management and access control
- URL validation, expiration dates, and maximum visit limits for enhanced control

## Use cases

- Marketing campaigns requiring detailed click tracking and geographic analytics
- SaaS applications needing embedded URL shortening with white-label branding
- Enterprise organizations wanting self-hosted alternatives to bit.ly or tinyurl
- Social media management tools requiring bulk URL shortening with analytics
- E-commerce platforms tracking affiliate and referral link performance
- Event management systems generating trackable registration and promotion links
- Content creators and bloggers analyzing audience engagement across platforms

## Prerequisites

- Docker and Docker Compose installed with at least 2GB available RAM
- Environment variables configured: SHORT_DOMAIN, DB_PASSWORD, API_KEY, GEOLITE_KEY
- GeoLite2 license key from MaxMind for geolocation analytics features
- Ports 8080 and 8081 available for Shlink API and web client access
- Basic understanding of PostgreSQL for database maintenance and backups
- Domain name configured if using custom short domains with DNS records

## docker-compose.yml

```yaml
services:
  shlink:
    image: shlinkio/shlink:stable
    container_name: shlink
    environment:
      - DEFAULT_DOMAIN=${SHORT_DOMAIN}
      - IS_HTTPS_ENABLED=false
      - GEOLITE_LICENSE_KEY=${GEOLITE_KEY}
      - DB_DRIVER=postgres
      - DB_HOST=db
      - DB_NAME=shlink
      - DB_USER=shlink
      - DB_PASSWORD=${DB_PASSWORD}
      - REDIS_SERVERS=redis:6379
    ports:
      - "8080:8080"
    depends_on:
      - db
      - redis
    networks:
      - shlink-network
    restart: unless-stopped

  shlink-web-client:
    image: shlinkio/shlink-web-client:stable
    container_name: shlink-web-client
    environment:
      - SHLINK_SERVER_URL=http://localhost:8080
      - SHLINK_SERVER_API_KEY=${API_KEY}
    ports:
      - "8081:80"
    depends_on:
      - shlink
    networks:
      - shlink-network
    restart: unless-stopped

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

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

volumes:
  postgres-data:
  redis-data:

networks:
  shlink-network:
    driver: bridge
```

## .env

```bash
# Shlink
SHORT_DOMAIN=short.example.com
DB_PASSWORD=secure_shlink_password

# Get from maxmind.com for geolocation
GEOLITE_KEY=your_geolite_license_key

# Generate API key: docker exec shlink shlink api-key:generate
API_KEY=your_api_key
```

## Usage notes

- Shlink API at http://localhost:8080
- Web client at http://localhost:8081
- Generate API key via CLI
- QR codes and visit tracking
- REST API available

## Troubleshooting

- Shlink container fails to connect to database: Verify DB_PASSWORD matches between shlink and db services, ensure PostgreSQL is fully initialized before Shlink starts
- Web client shows 'Server not accessible': Check SHLINK_SERVER_URL environment variable and ensure shlink container is running on port 8080
- Geolocation data not appearing in analytics: Verify GEOLITE_LICENSE_KEY is valid and MaxMind database downloads are not blocked by firewall
- Redis connection errors in Shlink logs: Confirm redis container is running and accessible on port 6379, check network connectivity within shlink-network
- API key authentication fails: Generate new API key using Shlink CLI command 'bin/cli api-key:generate' inside the shlink container
- Short URLs returning 404 errors: Verify DEFAULT_DOMAIN environment variable matches your intended domain and DNS configuration

