YOURLS URL Shortener

beginner

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

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.

Key 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

Common Use Cases

1Corporate marketing campaigns requiring branded short URLs with detailed analytics
2Social media management where link tracking and performance metrics are essential
3Email marketing campaigns needing click-through rate analysis and user engagement data
4Internal company tools for sharing resources while maintaining usage statistics
5Developer projects requiring URL shortening API integration for applications
6Privacy-focused organizations wanting complete control over link data and user information
7Educational 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

For development & testing. Review security settings, change default credentials, and test thoroughly before production use. See Terms

docker-compose.yml

1services: 
2  yourls: 
3    image: yourls:latest
4    container_name: yourls
5    environment: 
6      - YOURLS_DB_HOST=db
7      - YOURLS_DB_USER=yourls
8      - YOURLS_DB_PASS=${DB_PASSWORD}
9      - YOURLS_DB_NAME=yourls
10      - YOURLS_SITE=${YOURLS_SITE}
11      - YOURLS_USER=${YOURLS_USER}
12      - YOURLS_PASS=${YOURLS_PASS}
13    volumes: 
14      - yourls-data:/var/www/html/user/plugins
15    ports: 
16      - "8080:80"
17    depends_on: 
18      - db
19    networks: 
20      - yourls-network
21    restart: unless-stopped
22
23  db: 
24    image: mysql:8.0
25    container_name: yourls-db
26    environment: 
27      - MYSQL_ROOT_PASSWORD=${DB_ROOT_PASSWORD}
28      - MYSQL_DATABASE=yourls
29      - MYSQL_USER=yourls
30      - MYSQL_PASSWORD=${DB_PASSWORD}
31    volumes: 
32      - mysql-data:/var/lib/mysql
33    networks: 
34      - yourls-network
35    restart: unless-stopped
36
37volumes: 
38  yourls-data: 
39  mysql-data: 
40
41networks: 
42  yourls-network: 
43    driver: bridge

.env Template

.env

1# YOURLS
2YOURLS_SITE=http://localhost:8080
3YOURLS_USER=admin
4YOURLS_PASS=secure_admin_password
5DB_PASSWORD=secure_yourls_password
6DB_ROOT_PASSWORD=secure_root_password

Usage Notes

1Admin at http://localhost:8080/admin/
2Install via /admin/install.php first
3Bookmarklet for quick shortening
4Plugin ecosystem
5API available

Individual Services(2 services)

Copy individual services to mix and match with your existing compose files.

yourls

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

Quick Start

terminal

1# 1. Create the compose file
2cat > docker-compose.yml << 'EOF'
3services:
4  yourls:
5    image: yourls:latest
6    container_name: yourls
7    environment:
8      - YOURLS_DB_HOST=db
9      - YOURLS_DB_USER=yourls
10      - YOURLS_DB_PASS=${DB_PASSWORD}
11      - YOURLS_DB_NAME=yourls
12      - YOURLS_SITE=${YOURLS_SITE}
13      - YOURLS_USER=${YOURLS_USER}
14      - YOURLS_PASS=${YOURLS_PASS}
15    volumes:
16      - yourls-data:/var/www/html/user/plugins
17    ports:
18      - "8080:80"
19    depends_on:
20      - db
21    networks:
22      - yourls-network
23    restart: unless-stopped
24
25  db:
26    image: mysql:8.0
27    container_name: yourls-db
28    environment:
29      - MYSQL_ROOT_PASSWORD=${DB_ROOT_PASSWORD}
30      - MYSQL_DATABASE=yourls
31      - MYSQL_USER=yourls
32      - MYSQL_PASSWORD=${DB_PASSWORD}
33    volumes:
34      - mysql-data:/var/lib/mysql
35    networks:
36      - yourls-network
37    restart: unless-stopped
38
39volumes:
40  yourls-data:
41  mysql-data:
42
43networks:
44  yourls-network:
45    driver: bridge
46EOF
47
48# 2. Create the .env file
49cat > .env << 'EOF'
50# YOURLS
51YOURLS_SITE=http://localhost:8080
52YOURLS_USER=admin
53YOURLS_PASS=secure_admin_password
54DB_PASSWORD=secure_yourls_password
55DB_ROOT_PASSWORD=secure_root_password
56EOF
57
58# 3. Start the services
59docker compose up -d
60
61# 4. View logs
62docker compose logs -f

One-Liner

Run this command to download and set up the recipe in one step:

terminal

1curl -fsSL https://docker.recipes/api/recipes/yourls-shortener/run | bash

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

Community Notes

Loading notes...

Download Recipe Kit

Get all files in a ready-to-deploy package

Includes docker-compose.yml, .env template, README, and license

Components

yourlsmysql

Related Recipes

Ad Space

Shortcuts: C CopyF FavoriteD Download