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.
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.
- Third-party imports: Import your existing short URLs from third parties like bit.ly.
- Command-line and web interface.
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.6.2) by executing the following command on your server.
wget https://github.com/shlinkio/shlink/releases/download/v2.6.2/shlink2.6.2_php8.0_dist.zip
Note: If a new version comes out, simply replace 2.6.2 with the new version number.
The file will be saved as shlink2.6.2_php8.0_dist.zip. Use unzip command to unzip it to /var/www/ directory.
sudo apt install unzip
sudo mkdir -p /var/www/
sudo unzip shlink2.6.2_php8.0_dist.zip -d /var/www/
Now the files are stored under /var/www/shlink2.6.2_php8.0_dist/, we rename it to make it simpler.
sudo mv /var/www/shlink2.6.2_php8.0_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 the MariaDB console and create a database and user for Shlink. By default, the MariaDB package on Ubuntu uses unix_socket to authenticate user login, which basically means you can use the username and password of the OS to log into the 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 PHP8.0 and Some Extensions
Since we downloaded the PHP 8 version of Shlink, we need to install PHP8. Ubuntu 18.04 repository includes PHP7.2. To install PHP8.0 on Ubuntu 18.04, we need to add a PPA.
sudo apt install software-properties-common sudo add-apt-repository ppa:ondrej/php -y
Then install PHP8.0 and the extensions required by Shlink.
sudo apt install php-apcu php8.0 php8.0-fpm php8.0-mysql php8.0-gd php8.0-common php8.0-curl php8.0-intl php8.0-gmp php8.0-xml
If you use Apache web server, you need to run the following commands to make it use PHP8.0-FPM.
sudo a2dismod mpm_prefork sudo a2enmod mpm_event proxy_fcgi setenvif sudo a2enconf php8.0-fpm
Then restart Apache.
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 php8.0 ./install
Then the setup wizard will ask you to enter database details. So I choose MariaDB as the database type, then enter the database name, user and password. The host is localhost and the port is 3306.
Next, enter the default domain for your URL shortener and select the scheme type (https)
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.
Finally, configure the application. I simply press Enter to use the default settings.
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/php8.0-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 [email protected] -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 [email protected] -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.
Step 7: Creating Short Links
First, you need to create an API key with the following command.
sudo -u www-data php8.0 /var/www/shlink/bin/cli api-key:generate
Then go to https://app.shlink.io/ to add your server.
Once you add your server, you can create short links.
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.You may also want to learn how to use multiple versions of PHP on Ubuntu.
As always, if you found this post useful, then subscribe to our free newsletter to get more tips and tricks. Take care 🙂
Work for me.. Thank you!
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.
Ok, thank you so much!
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:
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:
Reload nginx:
Then rerun certbot with your additional domains:
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
Ni hao Xiao,
I follow your instruction and have the same error code as @carlos above:
Code:
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:
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…
You guessed right. When serving the app with swoole you should put an apache or nginx in front of it as a reverse proxy.
There are undocumented ways to change the port, and swoole supports SSL, but the process is more complex, so it’s not worth it.
Just use a well known web server as proxy 🙂
I’ll make sure to get the docs updated to notice this. It’s absolutely not clear enough and can be confusing.
Hi Guys, just in case some one needs to know the exact location of the clicks run:
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.
Thanks for that. I’m logged in as www-data so I had to use:
Thanks a lot for spreading the word. Really good tutorial 🙂
how do i update from shlink v2.6.0 to v6.0.1
i tried doing the way stated on the shlink website but after running the bin/update tool and restarting the VPS it just stops working when I visit the page it is just blank can anyone help
You can follow this guide
https://shlink.io/documentation/update-your-instance/
That is what i followed but after it was done my instance just showed a blank page
Have you added the errorlog line to your apache/nginx config? is yes, can you please post the logs from there?
can you try doing the permissions for www-data again?
are you using swoole OR webserver?
can you please check this and see if the solution here works for you?
https://github.com/shlinkio/shlink/issues/1056#issuecomment-804511307
Hi
i am using Nginx
therefore https://github.com/shlinkio/shlink/issues/1056#issuecomment-804511307, does not help me as it uses swoole
i have tried to
to www-data again but that seemed to do nothing
Saved as a favorite, I like your blog!