Polr is an open-source URL shortener and link management platform designed for self-hosting. It provides complete control over your data, customization options, and powerful APIs, making it a great choice for developers and system administrators who want a lightweight, privacy-focused solution. This guide will walk you through deploying, configuring, and managing Polr, covering everything from installation to leveraging its best features.
Installing Polr
📦 Docker/Docker Compose Setup
Using Docker Compose is the easiest way to deploy Polr with all dependencies. Create the docker-compose.yml file with the following configuration:
version: '3.8'
services:
polr:
image: cydrobolt/polr
container_name: polr
ports:
- "8080:80"
environment:
- APP_KEY=base64:your-generated-app-key-here
- DB_CONNECTION=mysql
- DB_HOST=db
- DB_PORT=3306
- DB_DATABASE=polr
- DB_USERNAME=polr_user
- DB_PASSWORD=secure_password
volumes:
- polr-data:/var/www/html
db:
image: mysql:5.7
container_name: polr_db
environment:
- MYSQL_DATABASE=polr
- MYSQL_USER=polr_user
- MYSQL_PASSWORD=secure_password
- MYSQL_ROOT_PASSWORD=root_password
volumes:
- db-data:/var/lib/mysql
volumes:
polr-data:
db-data:
Run the following commands to deploy Polr:
docker-compose up -d
This will start the Polr application and a MySQL database. Visit http://<your-server-ip>:8080 to complete the setup.
🚀 Manual Installation
For a manual setup, install Polr on a Linux server by following these steps:
- Install required dependencies:
sudo apt update
sudo apt install -y php php-mysql mysql-server apache2 unzip git curl
- Clone the Polr repository:
git clone https://github.com/cydrobolt/polr.git /var/www/polr
cd /var/www/polr
- Install PHP dependencies via Composer:
curl -sS https://getcomposer.org/installer | php
php composer.phar install --no-dev -o
- Set up the
.envconfiguration file:
cp .env.setup .env
nano .env
- Set permissions and initialize the database:
sudo chown -R www-data:www-data /var/www/polr
php artisan migrate --force
- Configure Apache as a web server:
sudo nano /etc/apache2/sites-available/polr.conf
Add the following content:
<VirtualHost *:80>
ServerName yourdomain.com
DocumentRoot /var/www/polr/public
<Directory /var/www/polr/public>
AllowOverride All
</Directory>
</VirtualHost>
Enable the configuration:
sudo a2ensite polr.conf
sudo systemctl restart apache2
Configuring Nginx as a Reverse Proxy
🌐 Nginx Configuration
If you're using Nginx as a reverse proxy, set up a server block:
server {
listen 80;
server_name yourdomain.com;
location / {
proxy_pass http://127.0.0.1:8080;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
}
}
Apply the configuration:
sudo nano /etc/nginx/sites-available/polr
sudo ln -s /etc/nginx/sites-available/polr /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx
🔒 SSL/TLS Setup
Secure your site with Let's Encrypt:
sudo apt install -y certbot python3-certbot-nginx
sudo certbot --nginx -d yourdomain.com
sudo systemctl reload nginx
🛠️ Testing and Reloading Nginx
Verify and reload Nginx to ensure the configuration works:
sudo nginx -t
sudo systemctl reload nginx
Logging and Debugging Polr
🗃️ Enabling Debug Logs
Enable debug logging in Polr by modifying the .env file:
nano /var/www/polr/.env
## Set APP_DEBUG to true
APP_DEBUG=true
📄 Viewing Logs
For Docker deployments, view logs using:
docker logs -f polr
For manual setups, check the log files in the Laravel framework:
tail -f /var/www/polr/storage/logs/laravel.log
🛠️ Troubleshooting Common Issues
Common issues like database connection errors are logged in laravel.log. Check for errors like:
SQLSTATE[HY000] [1045] Access denied for user 'polr_user'@'localhost'
Resolve this by verifying database credentials in .env.
📤 Exporting Logs
Export logs to a centralized system like ELK Stack using Filebeat:
sudo apt install filebeat
nano /etc/filebeat/filebeat.yml
## Add /var/www/polr/storage/logs/laravel.log to the filebeat.paths section
sudo systemctl start filebeat
Backup and Restore
🗂️ File-Based Backups
Create a snapshot of Polr’s configuration and data:
tar -czvf polr-backup.tar.gz /var/www/polr
🔄 Database Backups
Export the MySQL database:
mysqldump -u polr_user -p polr > polr-db-backup.sql
Restore the database:
mysql -u polr_user -p polr < polr-db-backup.sql
📅 Automated Backup Scripts
Set up a cron job to automate backups:
crontab -e
## Add the following:
0 2 * * * tar -czvf /backup/polr-$(date +\%F).tar.gz /var/www/polr
0 3 * * * mysqldump -u polr_user -p'password' polr > /backup/polr-db-$(date +\%F).sql
Updating and Upgrading Polr
⬆️ Updating Docker Images
Pull the latest Docker image and redeploy:
docker-compose down
docker-compose pull
docker-compose up -d
🛠️ Manual Updates
Update Polr manually by pulling the latest code and re-running migrations:
cd /var/www/polr
git pull origin master
php artisan migrate --force
🔍 Checking for Updates
Check for new releases on Polr's GitHub repository: Polr GitHub.
Leveraging Polr’s Unique Features
🔧 Enabling APIs
Enable the API in the .env file:
nano /var/www/polr/.env
## Set API_ENABLED to true
API_ENABLED=true
Test the API with curl:
curl -X POST -d "url=https://example.com" -H "Authorization: Bearer YOUR_API_KEY" http://yourdomain.com/api/v2/action/shorten
🌟 Advanced Configurations
Enable custom themes by modifying the theme setting in Polr’s admin panel, or adjust default URL shortening behavior in the .env file.
Wrapping Up
Self-hosting Polr provides unparalleled flexibility and control, making it an ideal choice for privacy-conscious developers and administrators. This guide walked you through deploying, configuring, and leveraging Polr’s features. With these steps, you can now confidently manage and customize Polr to suit your use case.
