shlink

By

Brian Johnson

A self-hosted URL shortener.

Run docker instance - primary instructions

The main instructions will have you run something like this:

docker run \
    --name my_shlink \
    -p 8080:8080 \
    -e DEFAULT_DOMAIN=s.test \
    -e IS_HTTPS_ENABLED=true \
    -e GEOLITE_LICENSE_KEY=xyz123 \
    shlinkio/shlink:stable

• --name - can be whatever
• DEFAULT_DOMAIN - set to yourdomain.com
• IS_HTTPS_ENABLED - enable for HTTPS support (automatic via LetsEncrypt)
• GEOLITE_LICENSE_KEY - optional - read about it here. You can exclude this setting if you don't want to geolocate where your link clicks are coming from.

Run docker instance - secondary instructions

I had problems with my shlink docker instance pooping out randomly for no apparent reason. Claude had me run this alternative setup and it has been solid:

sudo docker pull shlinkio/shlink:stable && \
sudo docker rm -f my_shlink; \
sudo docker run -d \
    --name my_shlink \
    --restart unless-stopped \
    -p 8080:8080 \
    -v shlink_data:/etc/shlink/data \
    -e DEFAULT_DOMAIN=my.domain.com \
    -e IS_HTTPS_ENABLED=true \
    --log-opt max-size=10m \
    --log-opt max-file=5 \
    shlinkio/shlink:stable

Enable HTTPS using Caddy

Use a Caddyfile such as:

yourdomain.com {
    reverse_proxy http://127.0.0.1:8080
}

Then run it:

./caddy run --config ./Caddyfile

Generate an API key via docker

sudo docker exec -it my_shlink shlink api-key:generate

Write it down!

Install Web client to interact with shlink

• Download from here
• Unzip the zip

Run the Shlink Web portal to manage your instance

Using something like Caddy where /home/www/ is where the shlink Web interface is unzipped:

sudo caddy file-server \
  --root /home/www \
  --listen :8888

Enable HTTPS in the Web management portal

Per this discussion on GitHub, you'll have problems copying links to clipboard in the browser if you're not in a secure context while doing so. So once I get the Caddy file server going (see previous section) I setup another tmux session and run something like:

sudomain-I-setup-for-shlink-admin.mydomain.com {
    reverse_proxy http://127.0.0.1:8888
}

Stop/restart the instance

You can press Ctrl+C to stop the instance, but next time you start it docker will complain that the container name is in use, so you can just do:

sudo docker start my_shlink

Stop it again:

sudo docker stop my_shlink

Review shlink logs

Review the logs with:

sudo docker logs -f my_shlink