# YOURLS URL Shortener

> Your Own URL Shortener - simple PHP-based URL shortening.

- Category: Productivity & Collaboration
- Difficulty: beginner
- Components: yourls, mysql
- Tags: url-shortener, yourls, php, simple
- Source: https://docker.recipes/productivity/yourls-shortener

## Overview

YOURLS (Your Own URL Shortener) is a powerful, self-hosted PHP-based URL shortening service that gives you complete control over your shortened links. Created as an open-source alternative to services like bit.ly and tinyurl, YOURLS allows organizations and individuals to create custom short URLs using their own domain, maintain link analytics, and retain full ownership of their data. The platform supports custom keywords, provides detailed statistics, and offers extensive customization through its plugin architecture.

This deployment consists of two core services: the YOURLS application container running on Apache with PHP support, and a MySQL 8.0 database container for storing URLs, statistics, and user data. The YOURLS service connects to the dedicated MySQL database instance, creating a robust and scalable URL shortening solution. The configuration includes plugin support through persistent volumes and exposes the web interface on port 8080 for easy access.

This stack is ideal for businesses wanting branded short URLs, marketing teams requiring detailed link analytics, developers building applications that need URL shortening capabilities, and privacy-conscious users who prefer self-hosted solutions over third-party services. The combination provides enterprise-grade reliability while maintaining the simplicity that makes YOURLS accessible to users of all technical levels.

## Features

- Custom keyword support for branded and memorable short URLs
- Comprehensive click analytics with geographic and referrer tracking
- RESTful API for programmatic URL shortening and management
- Plugin ecosystem with persistent storage for extensions and customizations
- Bookmarklet integration for one-click URL shortening from any browser
- MySQL 8.0 with InnoDB storage engine for ACID compliance and data integrity
- Multi-user support with role-based access control and private/public URLs
- Custom domain support with full DNS integration capabilities

## Use cases

- Corporate marketing campaigns requiring branded short URLs with detailed analytics
- Social media management where link tracking and performance metrics are essential
- Email marketing campaigns needing click-through rate analysis and user engagement data
- Internal company tools for sharing resources while maintaining usage statistics
- Developer projects requiring URL shortening API integration for applications
- Privacy-focused organizations wanting complete control over link data and user information
- Educational institutions creating trackable links for course materials and resources

## Prerequisites

- Docker and Docker Compose installed with at least 1GB available RAM for MySQL
- Available port 8080 for web interface access (configurable)
- Domain name or subdomain configured if using custom branding features
- Environment variables configured: DB_PASSWORD, DB_ROOT_PASSWORD, YOURLS_SITE, YOURLS_USER, YOURLS_PASS
- Basic understanding of PHP web applications and MySQL database concepts
- SSL certificate setup recommended for production deployments handling sensitive URLs

## docker-compose.yml

```yaml
services:
  yourls:
    image: yourls:latest
    container_name: yourls
    environment:
      - YOURLS_DB_HOST=db
      - YOURLS_DB_USER=yourls
      - YOURLS_DB_PASS=${DB_PASSWORD}
      - YOURLS_DB_NAME=yourls
      - YOURLS_SITE=${YOURLS_SITE}
      - YOURLS_USER=${YOURLS_USER}
      - YOURLS_PASS=${YOURLS_PASS}
    volumes:
      - yourls-data:/var/www/html/user/plugins
    ports:
      - "8080:80"
    depends_on:
      - db
    networks:
      - yourls-network
    restart: unless-stopped

  db:
    image: mysql:8.0
    container_name: yourls-db
    environment:
      - MYSQL_ROOT_PASSWORD=${DB_ROOT_PASSWORD}
      - MYSQL_DATABASE=yourls
      - MYSQL_USER=yourls
      - MYSQL_PASSWORD=${DB_PASSWORD}
    volumes:
      - mysql-data:/var/lib/mysql
    networks:
      - yourls-network
    restart: unless-stopped

volumes:
  yourls-data:
  mysql-data:

networks:
  yourls-network:
    driver: bridge
```

## .env

```bash
# YOURLS
YOURLS_SITE=http://localhost:8080
YOURLS_USER=admin
YOURLS_PASS=secure_admin_password
DB_PASSWORD=secure_yourls_password
DB_ROOT_PASSWORD=secure_root_password
```

## Usage notes

- Admin at http://localhost:8080/admin/
- Install via /admin/install.php first
- Bookmarklet for quick shortening
- Plugin ecosystem
- API available

## Troubleshooting

- YOURLS shows database connection error: Verify DB_PASSWORD matches MYSQL_PASSWORD and ensure db container is running
- Cannot access admin interface at /admin/: Complete initial setup by visiting /admin/install.php first
- Bookmarklet not working with shortened URLs: Check YOURLS_SITE environment variable matches your actual domain
- MySQL container fails to start with authentication errors: Ensure MYSQL_ROOT_PASSWORD is set and volumes are properly mounted
- Plugin installation fails or plugins disappear: Verify yourls-data volume is mounted to /var/www/html/user/plugins
- API requests return authentication errors: Confirm YOURLS_USER and YOURLS_PASS are properly configured in environment variables

