How to Install YOURLS on Ubuntu with Nginx and Let’s Encrypt

In this tutorial, we’re going to show you how to install YOURLS on an Ubuntu 20.04 server with Nginx, MariaDB, PHP, and Let’s Encrypt.


This is what you’ll need to follow this tutorial and set up YOURLS:

  • An Ubuntu server. You can get the $2.50 per month server from Vultr, it’s more than enough to handle YOURLS (which is pretty lightweight)
  • Experience in managing a server. You need to know how to ssh into your server. This tutorial assumes you’ve already taken care of maintaining and securing the server. What you’ll learn here is how to install and configure YOURLS.
  • Root access to the server. We’ll be using the root user for everything below. If you’re using a non-root user, use “sudo” where appropriate.

Step 1: Update the server

Before you do anything, update your Ubuntu server:

apt-get update && apt-get upgrade -y

Step 2: Install a few needed packages

For the purposes of this tutorial, we’ll need some basic packages like git and nano. Your server may already have them installed, but if you don’t, you can install them by running:

apt-get install git nano -y

You can also use other text editors, it doesn’t have to be nano.

Step 3: Install Nginx

The next step in installing the LEMP stack is to install the nginx server:

apt-get install nginx -y

Then start the server and enable it to start on boot:

systemctl start nginx
systemctl enable nginx

Step 4: Install MariaDB

You can either use MySQL or MariaDB. In this tutorial, we’ll be using MariaDB. To install it, run:

apt-get install nginx mariadb-server -y

Then, start MariaDB and enable it on boot:

systemctl start mariadb
systemctl enable mariadb

Step 5: Install PHP and a few PHP modules

The final part of the LEMP stack is to install PHP and a few needed PHP modules. Run the following command:

apt-get install php php-fpm php-xml php-pear php-cli php-zip php-json php-mysql  php-gd php-mbstring php-curl php-bcmath -y

And with that, we’re done installing the LEMP stack. Now it’s time to configure everything.

Step 6: Set up MariaDB and create a database

Next, run the following script and follow the easy-to-understand prompts to get a more secure MariaDB:


Next, log into MariaDB by running the following command:

mysql -u root -p

Note: the command may be different if you’re not using the root user or if you didn’t set up a password.

And run the following commands to create the database and a user, grant privileges, and exit out of MariaDB:

CREATE USER 'yourlsuser'@'localhost' IDENTIFIED BY 'StrongPassword';
GRANT ALL PRIVILEGES ON yourlsdb.* TO 'yourlsuser'@'localhost' IDENTIFIED BY 'StrongPassword' WITH GRANT OPTION;

Step 7: Download YOURLS

The next step is to download YOURLS. There are a few ways of doing this. You can download YOURLS into your root folder (meaning you’ll use your domain for YOURLS), or you can download it into a folder (meaning you’ll use for YOURLS). For this tutorial, we’ll be using our root domain.

So, navigate to:

cd /var/www/html

And download YOURLS. You can download the latest stable release from their GitHub releases, or download the latest code that’s on their GitHub repo. We’ll be using the latter option. If you’re going to download a release, you’ll need to unpack the archive after you download it.

git clone .

This command will extract their GitHub repo into whatever directory you’re currently in. In our case, it’s /var/www/html. If the directory is not empty, this command won’t run. In some cases, there may be the default index.html files already in that directory, so you can remove them by running the following commands:

rm index.html
rm index.nginx-debian.html

And then run the git command again. The dot at the end of the command means that it will clone the git repo in the current directory, as opposed to in a new YOURLS directory if the command was run without the dot.

Step 8: Create and edit config.php

The next step is to create a config.php file and edit it with our database and domain info.

Use the sample config.php file to create a new copy:

cp user/config-sample.php user/config.php

And open the file with whatever text editor you’re using to edit it:

nano user/config.php

Find and edit the following lines:

define( 'YOURLS_DB_USER', 'your db user name' );

define( 'YOURLS_DB_PASS', 'your db password' );

define( 'YOURLS_DB_NAME', 'yourlsdb' );

define( 'YOURLS_SITE', '' );

define( 'YOURLS_COOKIEKEY', 'modify this text with something random' );

$yourls_user_passwords = array(
'username' => 'password',

Following our tutorial, the edited lines should look like this:

define( 'YOURLS_DB_USER', 'yourlsuser' );

define( 'YOURLS_DB_PASS', 'StrongPassword' );

define( 'YOURLS_DB_NAME', 'yourlsdb' );

define( 'YOURLS_SITE', '' );

define( 'YOURLS_COOKIEKEY', 'WjwRx[H~(jdEw_z7whka[L#3Hj&NN1H(83ZW9fM(' );

$yourls_user_passwords = array(
'linuxstans' => 'AnotherStrongpassword',

The lines may be different depending on what kind of database setup you’re using and your domain. Pay extra attention to this step as it’s the one step where most people make an error. All the lines are well-commented with explanations. Double-check everything.

Once you’re done editing, save and close the file.

Step 9: Update permissions and your firewall

Next, update your directory permissions:

chown -R www-data:www-data /var/www/html
chmod -R 775 /var/www/html

And update your firewall (if any):

ufw allow http
ufw allow https

(this command can be done out of order, but we included it in Step 9). You don’t have to allow https traffic if you’re not planning on using an SSL.

Step 10: Configure Nginx

Next, you need to configure Nginx and set up a server block for your YOURLS.

Create a .conf file for your YOURLS:

nano /etc/nginx/sites-available/yourls.conf

And paste the configuration:

server {

listen 80;
listen [::]:80;


root /var/www/html;

location / {
try_files $uri $uri/ /yourls-loader.php$is_args$args;

location ~ \.php$ {
include fastcgi.conf;

fastcgi_index index.php;

fastcgi_pass unix:/var/run/php/php7.4-fpm.sock;


This is another step where people usually make a mistake. Make sure all the information is updated according to what you’re using. Pay extra attention to your domain, path to the root folder, and the PHP .sock file.

Once you’re done editing, save and close the file.

To make sure you didn’t make any error, run the following command:

nginx -t

Enable the conf by running:

ln -s /etc/nginx/sites-available/yourls.conf /etc/nginx/sites-enabled/

Then, restart Nginx for the changes to take effect:

systemctl restart nginx

If you don’t plan on using an SSL, you’re done here. You can navigate to to finish the installation process. However, in this tutorial, we’ll be using an SSL (Let’s Encrypt), so follow the next steps.

Step 11: Install Let’s Encrypt with Certbot

We’ll be using Certbot to manage our Let’s Encrypt SSL.

To install it, run:

apt-get install certbot python3-certbot-nginx -y

Then, run the following command to add an SSL for your domain:

certbot --nginx -d

Of course, update the command with the domain you’re using. There must be an A record pointing to your server’s IP for Certbot to work.

Follow the prompts after you run the command for Certbot to set up and configure Nginx for HTTPS.

Next, you need to update your config.php file now that you’re using an SSL. We could’ve done this previously, but if someone doesn’t plan on using an SSL the config.php file wouldn’t work.

So, open config.php

nano user/config.php

Update the following line and add https:

define( 'YOURLS_SITE', '' );

And add the following line:

define('YOURLS_ADMIN_SSL', true);

Save and close the file.

That’s it. Now navigate to and follow the steps to finish installing YOURLS. Use your admin username and password to log into the admin area via

Further steps and some notes

You can further extend YOURLS with plugins, themes, translations, or more. Check this page for more information and links. Read their wiki for detailed documentation.

Note that the root domain will return an error by design. You either need to set up an index page or redirect the root YOURLS domain to somewhere else.

The tutorial was tested multiple times and it works fine on Ubuntu 20.04. If you’re getting some kind of an error, check their documentation, their GitHub issues, or double-check all the steps from the tutorial.

We can install YOURLS for you for a one-time fee. If you need to extend YOURLS with plugins, themes, or translations, you can also contact us.

Leave a comment

Your email address will not be published. Required fields are marked *

5 thoughts on “How to Install YOURLS on Ubuntu with Nginx and Let’s Encrypt”