Shaarli is a lightweight, self-hosted bookmarking service designed for simplicity, speed, and privacy. It allows you to save, organize, and share links effortlessly, offering full control over your data without relying on third-party platforms. This guide will take you through deploying, configuring, and managing Shaarli, covering installation, reverse proxy setup, logging, backups, updates, and leveraging its powerful features.
Installing Shaarli
📦 Docker/Docker Compose Setup
Using Docker is one of the easiest ways to deploy Shaarli. Below is a docker-compose.yml file tailored for running Shaarli with persistent storage and port forwarding:
version: '3.8'
services:
shaarli:
image: shaarli/shaarli:latest
container_name: shaarli
ports:
- "8080:80" # Maps Shaarli to port 8080 on your host
volumes:
- ./data:/var/www/shaarli/data # Persistent storage for user data
- ./config:/var/www/shaarli/config # Persistent storage for configuration files
environment:
- TZ=UTC
restart: unless-stopped
To deploy Shaarli, run the following commands in the directory containing docker-compose.yml:
docker-compose up -d
This will pull the Shaarli Docker image and start the container. Access Shaarli by navigating to http://<your-server-ip>:8080.
🚀 Manual Installation
To install Shaarli directly on a Linux server, follow these steps:
- Install required dependencies:
sudo apt update
sudo apt install -y apache2 php php-cli php-curl php-mbstring php-xml git unzip
- Clone the Shaarli repository:
git clone https://github.com/shaarli/Shaarli.git /var/www/shaarli
cd /var/www/shaarli
- Set permissions and configure Shaarli:
sudo chown -R www-data:www-data /var/www/shaarli
sudo chmod -R 775 /var/www/shaarli
- Configure Apache:
sudo nano /etc/apache2/sites-available/shaarli.conf
Add the following lines:
<VirtualHost *:80>
DocumentRoot /var/www/shaarli
<Directory /var/www/shaarli>
AllowOverride All
</Directory>
</VirtualHost>
Enable the site and reload Apache:
sudo a2ensite shaarli
sudo systemctl reload apache2
- Visit
http://<your-server-ip>to complete the setup.
Configuring Nginx as a Reverse Proxy
🌐 Nginx Configuration
If you're using Nginx as a reverse proxy in front of Shaarli, create a server block configuration file:
sudo nano /etc/nginx/sites-available/shaarli
Add the following configuration:
server {
listen 80;
server_name yourdomain.com;
location / {
proxy_pass http://127.0.0.1:8080; # Forward traffic to Shaarli
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
}
}
Enable the site and restart Nginx:
sudo ln -s /etc/nginx/sites-available/shaarli /etc/nginx/sites-enabled/
sudo systemctl restart nginx
🔒 SSL/TLS Setup
Secure your Shaarli instance with Let's Encrypt:
sudo apt install -y certbot python3-certbot-nginx
sudo certbot --nginx -d yourdomain.com
Automate certificate renewal:
sudo systemctl enable certbot.timer
🛠️ Testing and Reloading Nginx
Validate your Nginx configuration and reload the service:
sudo nginx -t
sudo systemctl reload nginx
Logging and Debugging Shaarli
🗃️ Enabling Debug Logs
To enable debug logs in Shaarli, edit the config.json.php file located in the data directory:
sudo nano /var/www/shaarli/data/config.json.php
Set the LOG_LEVEL parameter to DEBUG:
"LOG_LEVEL": "DEBUG",
Save the changes and restart Shaarli.
📄 Viewing Logs
For Docker deployments, access logs with:
docker logs shaarli
For manual installations, review your web server logs:
sudo tail -f /var/log/apache2/access.log /var/log/apache2/error.log
🛠️ Troubleshooting Common Issues
Check for common errors like incorrect file permissions:
sudo chown -R www-data:www-data /var/www/shaarli
sudo chmod -R 775 /var/www/shaarli
📤 Exporting Logs
To forward logs to an ELK stack, configure Filebeat or similar agents to monitor relevant log files.
Backup and Restore
🗂️ File-Based Backups
To back up Shaarli files and configurations:
tar -czvf shaarli-backup.tar.gz /var/www/shaarli
🔄 Database Backups
If using a database (e.g., SQLite), back it up as follows:
cp /var/www/shaarli/data/shaarli.sqlite /backup/location/shaarli.sqlite.bak
📅 Automated Backup Scripts
Create a cron job for periodic backups:
crontab -e
Add the following line to back up daily at midnight:
0 0 * * * tar -czvf /backup/shaarli-$(date +\%F).tar.gz /var/www/shaarli
Updating and Upgrading Shaarli
⬆️ Updating Docker Images
Pull the latest image and restart the container:
docker-compose pull
docker-compose up -d
🛠️ Manual Updates
For manual installations, pull the latest changes from the repository:
cd /var/www/shaarli
git pull origin master
🔍 Checking for Updates
Periodically check the Shaarli GitHub Releases for new versions.
Leveraging Shaarli’s Unique Features
🔧 Enabling APIs
To enable the API, edit the config.json.php file:
"ENABLE_API": true,
Test the API with curl:
curl -X GET http://<your-server-ip>:8080/api/v1/info
🌟 Advanced Configurations
Enable advanced filters or third-party integrations by modifying config.json.php. For example, to enable tagging:
"ENABLE_TAGS": true,
Restart Shaarli for changes to take effect.
Wrapping Up
Shaarli is a powerful, lightweight, and flexible tool for managing bookmarks while maintaining control of your data. By following the steps in this guide, you’ve successfully deployed and configured Shaarli, secured it with SSL, set up logging, created backups, and leveraged its unique features. Start organizing your links with confidence, knowing you have complete ownership and customization at your fingertips!
