Installation guide for Shlink as a Docker Container

Introduction

This tutorial is about the installation of the selfhosted URL shortener Shlink as a Docker Container

More Information about Shlink can be found in the Shlink documentation

Prerequisites

• (Cloud-)Server with Debian
  • Hetzner Cloud
  • Hetzner Cloud Docs
  • Tutorial Debian
• Docker already installed
  • Tutorial Docker
• Docker Compose installed at /usr/local/bin/docker-compose
  • Tutorial Docker Compose
• if required, a reverse proxy can be used to e.g. use multiple domains and encrypt the requests (the service does not provide encryption by itself)
  • Tutorial Caddy Reverse Proxy
  • Tutorial Nginx Reverse Proxy
  • Tutorial Apache Reverse Proxy
• if a publicly accessible (sub-)domain is to be used, the DNS settings must be adjusted accordingly
  • Hetzner DNS Docs

Step 1 - Create directory structure

First we create the directories for the configuration and database files

mkdir -p /opt/shlink/db_data/

Step 2 - Create docker-compose.yml

In the docker-compose.yml we define all settings for our Docker containers

nano /opt/shlink/docker-compose.yml

We have to consider a few variables that we still have to adjust:

• DEFAULT_DOMAIN: Here we have to specify the domain through which the Shlink instance will be accessible
• IS_HTTPS_ENABLED: If a reverse proxy with TLS termination is installed (technology to be able to use https), true must be entered here, otherwise false
• GEOLITE_LICENSE_KEY: The Geolite license key must be entered here, which we will receive in the next step
• DB_PASSWORD: A secure password, preferably randomly generated, must be entered here
• MARIADB_ROOT_PASSWORD: A secure password, preferably randomly generated, must be entered here

The following applies to the variables under Ports:

• 127.0.0.1: the bind address is entered here, i.e. the address via which the service should be accessible
  • 127.0.0.1 means that the service can only be reached locally, this would be used if a reverse proxy is connected
  • 0.0.0.0 means that the service can be accessed globally as long as the corresponding port is opened
• 8080: the bind port is entered here, i.e. the port via which the service should be accessible
  • 80 would be used if you want to reach the service directly via http
  • 8080 or some other non-standard port would be used for a reverse proxy configuration

Shlink offers some more variables, which you can find in the Shlink documentation

docker-compose.yml:

version: "3"

services:
  shlink:
    image: shlinkio/shlink:stable
    restart: always
    environment:
      - TZ="Europe/Berlin"
      - DEFAULT_DOMAIN=<DEFAULT_DOMAIN>
      - IS_HTTPS_ENABLED=<true/false>
      - GEOLITE_LICENSE_KEY=<GEOLITE_LICENSE_KEY>
      - DB_DRIVER=maria
      - DB_USER=shlink
      - DB_NAME=shlink
      - DB_PASSWORD=<DB_PASSWORD>
      - DB_HOST=database
    depends_on:
      - database
    ports:
      - <127.0.0.1>:<8080>:8080

  database:
    image: mariadb:10.8
    restart: always
    environment:
      - MARIADB_ROOT_PASSWORD=<MARIADB_ROOT_PASSWORD>
      - MARIADB_DATABASE=shlink
      - MARIADB_USER=shlink
      - MARIADB_PASSWORD=<DB_PASSWORD>
    volumes:
      - /opt/shlink/db_data:/var/lib/mysql

Step 3 - Apply for a GeoLite2 license key

• To assign a real address to the IP addresses, we need a corresponding database
• The provider MAXMIND provides the database GeoLite2 free in addition to commercial services
• To use this service we need a license key

You can get this by following these steps:

1. Create an Account for GeoLite2
2. Generate a license key

Don't forget to put this key in the variable as well!

Step 4 - Start service

To start the Docker container we use:

docker-compose up -d

To stop the Docker container we use:

docker-compose down

We can see the status of the containers with the following command:

docker-compose ps

• Everything should be Up in Status!

To get a deeper insight, you can see the logs with the following command:

docker-compose logs

Note

You should now be able to access your Shlink instance

If you go to your URL and don't have a redirect specified by the DEFAULT_BASE_URL_REDIRECT variable, a 404 page should appear

Now you can use the CLI (console command), Rest API or web client to create and manage new short codes, i.e. URL abbreviations, and view their statistics

Step 5 - CLI commands (Optional)

This console command allows you to interact directly with your instance

docker-compose exec shlink shlink <arguments>

By omitting arguments you get a help with all available commands

Step 6 - Rest API (Optional)

Shlink provides a rest API through which you can control your instance alongside the CLI. This requires an API key, which you can generate with a console command:

docker-compose exec shlink shlink api-key:generate

You can find a list of API endpoints here

Step 7 - Shlink Web Client (Optional)

• You've probably asked yourself whether you always have to control everything via the CLI (console command) or the Rest API
  • Again, Shlink offers a clever help
  • You can use the Shlink web client to create and manage 'short codes', i.e. URL abbreviations, and view their statistics
• To use it, you can just use the official WebApp
• Even if your data is safe because it is only processed in the browser, you can also host it yourself
  • You can simply add the following part to your docker-compose.yml
  • Make sure that you set the bind address and the bind port again so that you can reach the web client either directly or via reverse proxy

  shlink-web-client:
    image: shlinkio/shlink-web-client
    restart: always
    volumes:
      - /opt/shlink/servers.json:/usr/share/nginx/html/servers.json
    ports:
      - <127.0.0.1>:<8081>:80

Note

If you want to use the official WebApp and/or want to secure your own web client through https, you also have to connect a reverse proxy with TLS termination to your Shlink instance, because you cannot access http pages via https pages for security reasons.

More information is available here

Summary

You now have a fully functional Shlink instance that you can use to create shortcuts for your URLs. Shlink also offers many other practical features. Just have a look at the Shlink documentation or try the CLI, Rest API or web client.

For more help you can

• use the Shlink Troubleshooting Guide
• use the Discussions page of the project

License: MIT