Install Polr with Apache and MySQL or MariaDB on Ubuntu 20.04

Author: Francis Ndungu

Last Updated: Tue, May 11, 2021
Business Ubuntu Web Servers


Polr is a quick modern URL shortener with a simple interface for creating and managing personal domain-branded links. It has a robust API (Application Programming Interface) that allows you to create links programmatically.

Polr is open-source software released under the GNU General Public License v2.0, and it comes with a wide range of features that allow you to customize permissions, URL forwarding, and themes. Its codebase is written in PHP on top of a powerful Lumen micro-framework.

Polr assists you in promoting your online brand since it is more convenient to share short links and gain better insights by tracking clicks to each individual link. This leads to stronger engagement and professionalism without relying on third-party websites. Potential clients are more likely to click on the short, clean links instead of long links with lots of URL parameters.

You'll install the Polr URL shortener with Apache and MySQL/MariaDB on your Ubuntu 20.04 server in this guide.


To follow along with this tutorial, make sure you have the following:

  • An Ubuntu 20.04 server.
  • A domain name(e.g. For testing purposes, you can use the public IP address of your server.
  • A non-root sudo user.
  • A LAMP Stack. Choose either a MySQL or a MariaDB database server.

1. Install PHP Extensions and Apache mod_rewrite Module

SSH to your server and update the package information index.

$ sudo apt update

Next, install all the PHP extensions required to run the Polr package and the PHP Composer tool.

 $ sudo apt -y install php php-pdo php-mysql php-mbstring php-tokenizer php-json php-curl

Enable the Apache mod_rewrite module. Polr requires it to craft user-friendly URLs.

$ sudo a2enmod rewrite

Restart the Apache webserver to reload the new changes.

$ sudo systemctl restart apache2

With the PHP extensions and mod_rewrite installed, you'll download and configure the PHP dependency management tool next.

2. Set Up PHP Dependency Management Tool

Install PHP Composer to easily manage dependencies required by the Polr URL shortener. First, install the unzip tool.

$ sudo apt install -y unzip

Then, download and run the Composer installer.

$ cd ~
$ sudo curl -sS | php

Move the composer.phar executable to /usr/local/bin/ so that you can run it without typing its full file path.

$ sudo mv composer.phar /usr/local/bin/composer

The PHP Composer tool is now in place, but before installing Polr, you'll create a database and a user account next.

3. Create a Polr Database and User

Polr requires a database to work. Log in to your MySQL server as root.

$ sudo mysql -u root -p

When prompted, enter the root password for your MySQL server and press ENTER to proceed. Then, run the command below to create a polr database.

mysql> CREATE DATABASE polr;

Next, create a user account for connecting to the polr database and log out from the database server.

mysql> CREATE USER 'polr_user'@'localhost' IDENTIFIED WITH mysql_native_password BY 'EXAMPLE_PASSWORD';
       GRANT ALL PRIVILEGES ON polr.* TO 'polr_user'@'localhost';

If you prefer to use MariaDB, create the user account by running the commands below.

MariaDB> GRANT ALL PRIVILEGES on polr.* TO 'polr_user'@'localhost' identified by 'EXAMPLE_PASSWORD';

The database schema is ready. Next, you'll pull the Polr installation package from GitHub.

4. Clone the Polr Package from GitHub

Create a separate sub-directory for your Polr site under the Apache root directory /var/www. Replace with your correct domain name or public IP address of your server.

$ sudo mkdir -p /var/www/

Change the ownership of the directory to the current logged-in user.

$ sudo chown -R $USER:$USER /var/www/

Next, use git to clone the Polr installation package from GitHub.

$ sudo git clone --depth=1 /var/www/

Use Linux cd command to navigate to the /var/www/ directory.

$ cd /var/www/

Then, run the composer command below to install Polr.

$ sudo composer install --no-dev -o

Create a new configuration file by copying the default .env.setup file that ships with Polr to .env.

$ sudo cp .env.setup .env

Assign the appropriate ownership and permissions to the Polr files and directories.

$ sudo chown -R www-data:www-data /var/www/
$ sudo chmod -R 755 /var/www/

Your package is now installed. But before you run it, create a virtual host configuration file for your Polr application.

5. Create a Virtual Host File

Remove and disable the default Apache virtual host configuration file.

$ sudo rm -r /etc/apache2/sites-available/000-default.conf
$ sudo a2dissite 000-default.conf

Then, create a new virtual host file for your Polr site under the /etc/apache2/sites-available/ directory.

$ sudo nano /etc/apache2/sites-available/

Then, add the information below into the file. Replace with the correct domain name or public IP address of your server.

<VirtualHost *:80>
    DocumentRoot "/var/www/"
    <Directory "/var/www/">
        Require all granted
        Options Indexes FollowSymLinks
        AllowOverride All
        Order allow,deny
        Allow from all
   ErrorLog ${APACHE_LOG_DIR}/error.log
   CustomLog ${APACHE_LOG_DIR}/access.log combined

Save and close the file. Then, enable the configuration file you've just created using the a2ensite command.

$ sudo a2ensite

Then, restart the Apache webserver to load the new settings.

$ sudo systemctl restart apache2

Apache can now server your Polr website from the newly created virtual host file. You'll test this in the next step.

6. Complete and Test the Installation

Complete the Installation by opening the URL below on a web browser.

You should see a web page for finalizing the setup, as shown below.

Polr Setup Page

In case you experience a problem when running the setup script, run the command below to initialize the database structure manually.

$ sudo php artisan migrate

Visit your Polr site and begin shortening URLs. Your home page should be similar to the below screenshot.

Polr Home Page


In this guide, you've installed the Polr URL shortener with Apache and MySQL/MariaDB on your Ubuntu 20.04 server. Use your Polr website to create personal domain-branded short links.

Want to contribute?

You could earn up to $300 by adding new articles