How to Install Shlink URL Shortener on Ubuntu 18.04 Server

Shlink is an open-source self-hosted URL shortener, which allows you to shorten URLs and serve them under your own short domain. Using your own URL shortner service instead of third-party service like bit.ly can increase brand awareness. This tutorial will be showing you how to install Shlink on Ubuntu 18.04 with Apache or Nginx web server.

install shlink on ubuntu_ self hosted url shortener

Shlink Features

  • Visit stats: Track all the visits to your short URLs, including stats like location, browser or referrer.
  • Email tracking: Generate a 1px transparent image that can be used to track emails.
  • Third party integrations: Easily make third party tools use shlink to shorten URLs by using a single-request API endpoint.
  • Custom Slugs: Make your shortened URLs use a custom slug to easily identify campaigns.
  • QR codes: Generate QR codes on the fly pointing to your short URLs
  • Previews: Get previews in image format for any short URL
  • Tags: Tag your short URLs and classify them for later analytics
  • Limited access: Limit access to short URLs, by date range and/or maximum number of visits.

Prerequisites of installing Shlink on Ubuntu 18.04 Server

Shlink is written in PHP and relies on MySQL/MariaDB or PostgreSQL database server, so you need to set up a LAMP stack or LEMP stack. If you prefer Apache web server, then set up LAMP stack.

If you prefer Nginx web server, then set up LEMP stack.

You also need a domain name. I registered my domain name from NameCheap because the price is low and they give whois privacy protection for free. In this tutorial, I use my lnux.be domain name as an example. Without further ado, let’s install Shlink on Ubuntu 18.04 server.

Step 1: Download Shlink onto Your Ubuntu 18.04 Server

Go to the Shlink Github page to see the latest stable version. You can download the latest stable version (2.1.3) by executing the following command on your server.

wget https://github.com/shlinkio/shlink/releases/download/v2.1.3/shlink_2.1.3_dist.zip

Note: If a new version comes out, simply replace 2.1.3 with the new version number.

The file will be saved as shlink_2.1.3_dist.zip. Use unzip command to unzip it to /var/www/ directory.

sudo apt install unzip

sudo unzip shlink_2.1.3_dist.zip -d /var/www/

Now the files are stored under /var/www/shlink_2.1.3_dist/, we rename it.

sudo mv /var/www/shlink_2.1.3_dist /var/www/shlink

Then make the web server user (www-data) as the owner of this directory.

sudo chown -R www-data:www-data /var/www/shlink/

Step 2: Create a MariaDB Database and User for Shlink

Now we need to log in to MariaDB console and create a database and user for Shlink. By default, the MaraiDB package on Ubuntu uses unix_socket to authenticate user login, which basically means you can use username and password of the OS to log into MariaDB console. So you can run the following command to login without providing MariaDB root password.

sudo mysql -u root

Next,create a new database for Shlink using the following command. This tutorial names it shlink, you can use whatever name you like for the database.

CREATE DATABASE shlink;

The following command will create a database user and password, and at the same time grant all permission of the new database to the new user so later on Shlink can write to the database. Replace red texts with your preferred database name, username and password.

GRANT ALL ON shlink.* TO 'shlink'@'localhost' IDENTIFIED BY 'password';

Flush privileges table and exit MariaDB console.

FLUSH PRIVILEGES;

EXIT;

Step 3: Install PHP7.4 and Some Extensions

Shlink requires PHP7.4 to run. Ubuntu 18.04 repository includes PHP7.2. To install PHP7.4 on Ubuntu 18.04, we need to add a PPA.

sudo apt install software-properties-common

sudo add-apt-repository ppa:ondrej/php

Then install PHP7.4 and the extensions required by Shlink.

sudo apt install php-apcu php7.4 php7.4-fpm php7.4-mysql php7.4-json php7.4-gd php7.4-common php7.4-curl php7.4-intl

Then restart Apache. (If you use Nginx, you don’t need to restart Nginx.)

sudo systemctl restart apache2

Step 4: Run the Shlink Install Script

Go to the /var/www/shlink/bin/ directory.

cd /var/www/shlink/bin/

There’s a PHP script named install, we run the script as the www-data user.

sudo -u www-data php7.4 ./install

Then the setup wizard will ask you to enter database details. So I choose MariaDB as the database type, then enter database name, user and password. The host is localhost and port is 3306.

shlink-install-script-wizard-command-line

Next, enter the default domain for your URL shortner and select the scheme type (https)

shlink-self-hosted-url-shortner-ubuntu-18.04

Then configure the redirects. When visitors hit my Shlink’s base URL (https://lnux.be), they will be redirected to my website. You can also create a custom URL for 404 not found page. In this tutorial, I simply press Enter to accept the default.

shlink redirects

Finally, configure the application. I simply press Enter to use the default settings.

install-shlink-on-ubuntu-18.04-server-apache-nginx

Step 5: Create Apache Virtual Host or Nginx Config File for Shlink

Apache

If you use Apache web server, create a virtual host for Shlink.

sudo nano /etc/apache2/sites-available/shlink.conf

Put the following text into the file. Replace lnux.be with your real domain name and don’t forget to set DNS A record for it.

<VirtualHost *:80>
  ServerName lnux.be
  DocumentRoot /var/www/shlink/public

  ErrorLog ${APACHE_LOG_DIR}/shlink_error.log
  CustomLog ${APACHE_LOG_DIR}/shlink_access.log combined

  <Directory /var/www/shlink/public>
    Options FollowSymLinks Includes ExecCGI
    AllowOverride All
    Order allow,deny
    allow from all
  </Directory>

</VirtualHost>

Save and close the file. Then enable this virtual host with:

sudo a2ensite shlink.conf

Reload Apache for the changes to take effect.

sudo systemctl reload apache2

Nginx

If you use Nginx web server, create a virtual host for Shlink.

sudo nano /etc/nginx/conf.d/shlink.conf

Put the following text into the file. Replace lnux.be with your real domain name and don’t forget to set DNS A record for it.

server {
   listen 80;
   listen [::]:80;
   server_name lnux.be;

   root /var/www/shlink/public;
   error_log /var/log/nginx/shlink.error;
   access_log /var/log/nginx/shlink.access;

   index index.php index.html index.htm index.nginx-debian.html;

   location / {
     # try to serve file directly, fallback to app.php
     try_files $uri /index.php$is_args$args;
   }

   # redirect some entire folders
     rewrite ^/(vendor|translations|build)/.* /index.php break;

   location ~ \.php$ {
     fastcgi_split_path_info ^(.+\.php)(/.+)$;
     fastcgi_pass unix:/var/run/php/php7.4-fpm.sock;
     fastcgi_index index.php;
     fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
     include fastcgi_params;
   }

}

Save and close the file. Then test Nginx configuration.

sudo nginx -t

If the test is successful, reload Nginx for the changes to take effect.

sudo systemctl reload nginx

Step 6: Enabling HTTPS

To encrypt the HTTP traffic, we can enable HTTPS by installing a free TLS certificate issued from Let’s Encrypt. Run the following command to install Let’s Encrypt client (certbot) on Ubuntu 18.04 server.

sudo apt install certbot

If you use Apache, install the Certbot Apache plugin.

sudo apt install python3-certbot-apache

And run this command to obtain and install TLS certificate.

sudo certbot --apache --agree-tos --redirect --hsts --staple-ocsp --email you@example.com -d lnux.be

If you use Nginx, then you also need to install the Certbot Nginx plugin.

sudo apt install python3-certbot-nginx

Next, run the following command to obtain and install TLS certificate.

sudo certbot --nginx --agree-tos --redirect --hsts --staple-ocsp --email you@example.com -d lnux.be

Where

  • --nginx: Use the nginx plugin.
  • --apache: Use the Apache plugin.
  • --agree-tos: Agree to terms of service.
  • --redirect: Force HTTPS by 301 redirect.
  • --hsts: Add the Strict-Transport-Security header to every HTTP response. Forcing browser to always use TLS for the domain. Defends against SSL/TLS Stripping.
  • --staple-ocsp: Enables OCSP Stapling. A valid OCSP response is stapled to the certificate that the server offers during TLS.

The certificate should now be obtained and automatically installed.

shlink https

Step 7: Creating Short Links

First, you need to create an API key with the following command.

sudo -u www-data php7.4 /var/www/shlink/bin/cli api-key:generate

Then go to https://app.shlink.io/ to add your server.

shlink create short link

Once you add your server, you can create short links.

shlink create short url

Note that this is just a web client. Short URLs are stored on your own server.

You can also generate short URLs from command line on your server.

sudo -u www-data /var/www/shlink/bin/cli short-url:generate

List short URLs.

sudo -u www-data /var/www/shlink/bin/cli short-url:list

Run the following command to see the help message.

sudo -u www-data php /var/www/shlink/bin/cli

Wrapping Up

I hope this tutorial helped you install Shlink on Ubuntu 18.04 server. As always, if you found this post useful, then subscribe to our free newsletter to get more tips and tricks. Take care 🙂

Rate this tutorial
[Total: 2 Average: 5]

11 Responses to “How to Install Shlink URL Shortener on Ubuntu 18.04 Server

  • vanhussen
    1 year ago

    Work for me.. Thank you!

  • vanhussen
    1 year ago

    What is different shlink-web-client v2.1.1 with shlink_1.18.1? Becouse when I access my server, 404
    Page not found.
    The page you requested could not be found.

    I see some people can make graphic pie on sites address.

    • Shlink is the server. Shlink-web-client is the client. You can self host the web client if you want to. You use the web-client or command line client to manage short links. The main domain name like lnux.be isn’t a short link.

  • After playing with your first url shortener url, you might enjoy and want to use other urls for marketing branding. You can enter more domains / sub domains you’ve pointed to the server ip

    For nginx – add multiple domains on:

    sudo nano /etc/nginx/conf.d/shlink.conf

    Edit server name line:

    server {
       listen 80;
       listen [::]:80;
       server_name example1.com example2.com link.example3.com go.yourdomain.com ;
    ...
    

    CTRL-X (to exit) and Y (to save)

    Then check to make sure it’s good:

    sudo nginx -t

    Reload nginx:

    sudo systemctl reload nginx

    Then rerun certbot with your additional domains:

    sudo certbot --nginx --agree-tos --redirect --hsts --staple-ocsp --email youremail@yourdomain.com -d example1.com -d example2.com -d link.example3.com -d go.yourdomain.com

    Thanks again for the tutorial LinuxBabe!

  • error for me:

    sudo -u www-data php ./install

    PHP Warning: require(/var/www/html/shlink/bin/../vendor/shlinkio/shlink-installer/bin/run.php): failed to open stream: No such file or directory in /var/www/html/shlink/bin/install on line 11

  • Quang Mai
    7 months ago

    Ni hao Xiao,

    I follow your instruction and have the same error code as @carlos above:

    Code:

    sudo -u www-data php ./install
    PHP Parse error:  syntax error, unexpected '$isUpdate' (T_VARIABLE), expecting ',' or ')' in /var/www/shlink/vendor/shlinkio/shlink-installer/bin/run.php on line 12
    

    Do you have any ideas? Thanks

    • The latest Shlink now requires PHP7.4. I just updated this article to include instructions to install PHP7.4.

      You need to run the install script with PHP7.4 like this:

      sudo -u www-data php7.4 ./install
  • Massimiliano
    6 months ago

    I followed the installation through the official documentation and I managed to have Shlink on my VPS.

    I have created a public folder that everyone can reach to manage the links and I can access it to see which links I have generated and to generate others.

    The problem is that the redirect system behind it does not work, for example I created “massifor.me/pc” which should redirect to my blog (pcgenius.org), in the command line I see the link and I also see it from webclient however when I click on it it says “Oops! We could not find requested route.”, I don’t know what it depends on.

    Php modules are all there, the wordpress sites that I have on the same machine work, do you have any ideas?
    I’m under Ubuntu, Apache, Php 7.4.5 and I’m using virtual hosts

  • Thank you for the tutorial! I’m trying to make it work with Swoole (as per their recommendation) but never managed to do so; it only listens to 8080 port, and I found no way to set up SSL without using a real webserver like apache or nginx, and the web client was never able to find the backend lol. Not sure if I should use a reverse proxy as a frontend (why Swoole if I’m using apache frontend anyways lol). Amazing script without doubt, but what a pity that it’s so insufficiently documented…

  • Hi Guys, just in case some one needs to know the exact location of the clicks run:

    sudo /var/www/shlink/bin/cli visit:locate 

    That after installing the new version which adds geo-location.

    You can make a cron job for that to be made automatically adding -q flag. That flag will avoid populating the cron logs.

Leave a Comment

  • Comments with links are moderated by admin before published.
  • Your email address will not be published.
  • Use <pre> ... </pre> HTML tag to quote the output from your terminal/console.
  • Please use the community (https://community.linuxbabe.com) for questions unrelated to this article.
  • I don't have time to answer every question. Making a donation would incentivize me to spend more time answering questions.


The maximum upload file size: 2 MB.
You can upload: image.