Skip to content
Klutch.sh Docs

Deploying Shaarli

Introduction

Shaarli is a minimalist, database-free bookmark manager and link sharing platform. Often described as “your own personal, federated, Twitter-like platform,” Shaarli lets you save bookmarks, write notes, and share content through a simple web interface. Its file-based storage approach means no database setup is required, making it incredibly easy to deploy and maintain.

Built with PHP, Shaarli has been in active development since 2011 and has earned a devoted following among self-hosters who appreciate its simplicity and reliability. The application supports tags, full-text search, RSS feeds, and even a bookmarklet for quick saving from any webpage.

Key highlights of Shaarli:

  • No Database Required: Stores data in flat files for simplicity
  • Tag System: Organize links with flexible tagging
  • Full-Text Search: Fast search across all your links
  • RSS/Atom Feeds: Subscribe to your links or specific tags
  • Private/Public Links: Choose what to share publicly
  • Bookmarklet: Save links with one click from any page
  • Daily Digest: Automatically generated daily link collections
  • API: REST API for integrations and custom clients
  • Plugins: Extend functionality with plugins
  • 100% Open Source: Licensed under Zlib

This guide walks through deploying Shaarli on Klutch.sh using Docker, configuring your link collection, and setting up efficient bookmark management.

Why Deploy Shaarli on Klutch.sh

Deploying Shaarli on Klutch.sh provides several advantages:

Simplified Deployment: Klutch.sh handles PHP configuration automatically with no database setup needed.

Persistent Storage: Attach persistent volumes for your bookmark data that survives restarts.

HTTPS by Default: Klutch.sh provides automatic SSL certificates for secure access.

Lightweight: Minimal resource requirements due to file-based storage.

Custom Domains: Use your own domain for a personalized link sharing site.

Prerequisites

Before deploying Shaarli on Klutch.sh, ensure you have:

Preparing Your Repository

Create a GitHub repository with your Shaarli configuration.

Repository Structure

shaarli-deploy/
├── Dockerfile
└── .dockerignore

Creating the Dockerfile

Create a Dockerfile in the root of your repository:

FROM ghcr.io/shaarli/shaarli:latest


# Environment variables
ENV SHAARLI_TITLE=${SHAARLI_TITLE:-My Shaarli}
ENV SHAARLI_TIMEZONE=${SHAARLI_TIMEZONE:-UTC}


# Create data directory
RUN mkdir -p /var/www/shaarli/data


# Expose the web interface port
EXPOSE 80

Environment Variables Reference

VariableRequiredDefaultDescription
SHAARLI_TITLENoMy ShaarliTitle displayed on your Shaarli instance
SHAARLI_TIMEZONENoUTCTimezone for timestamps

Deploying Shaarli on Klutch.sh

    Push Your Repository to GitHub

    Initialize and push your repository:

    Terminal window
    git init
    git add Dockerfile .dockerignore
    git commit -m "Initial Shaarli deployment configuration"
    git remote add origin https://github.com/yourusername/shaarli-deploy.git
    git push -u origin main

    Create a New Project on Klutch.sh

    Navigate to the Klutch.sh dashboard and create a new project with a descriptive name like “shaarli” or “links”.

    Create a New App

    Within your project, create a new app. Connect your GitHub account and select your Shaarli repository.

    Configure HTTP Traffic

    In the deployment settings:

    • Select HTTP as the traffic type
    • Set the internal port to 80

    Set Environment Variables

    Add optional environment variables:

    VariableValue
    SHAARLI_TITLEYour custom title
    SHAARLI_TIMEZONEYour timezone

    Attach Persistent Volumes

    Add the following volume:

    Mount PathRecommended SizePurpose
    /var/www/shaarli/data5 GBLink database, cache, and configuration

    Deploy Your Application

    Click Deploy to start the build process.

    Complete Installation

    Access your Shaarli instance at https://your-app-name.klutch.sh and complete the setup:

    1. Create your admin username and password
    2. Configure basic settings
    3. Start adding links

Using Shaarli

  1. Click Shaare in the menu
  2. Enter the URL
  3. Add a title and description
  4. Add tags (space or comma separated)
  5. Choose public or private
  6. Click Save

Using the Bookmarklet

  1. Go to Tools in the menu
  2. Drag the bookmarklet to your bookmarks bar
  3. On any page, click the bookmarklet to save it to Shaarli

Organizing with Tags

  • Add tags when creating links
  • Click tags in the tag cloud to filter
  • Use tag operators:
    • tag1 tag2 - links with both tags
    • tag1+tag2 - links with either tag
    • -tag1 - exclude tag

Use the search box to find links by:

  • Title
  • Description
  • URL
  • Tags

RSS Feeds

Shaarli generates RSS feeds automatically:

  • All public links: /feed/atom
  • By tag: /feed/atom?searchtags=tagname
  • Daily: /daily

Configuration Options

Privacy Settings

  1. Go to Tools > Configure your Shaarli
  2. Set default visibility (public/private)
  3. Configure API access
  4. Enable/disable features

Themes

  1. Go to Tools > Configure your Shaarli
  2. Select a theme from the dropdown
  3. Custom themes can be added to the tpl/ directory

Plugins

Enable plugins in Tools > Configure your Shaarli:

  • Archive.org: Add Wayback Machine links
  • Default Colors: Customize link colors
  • Markdown: Format descriptions with Markdown
  • Playvideos: Inline video playback
  • QRcode: Generate QR codes for links

Troubleshooting

Cannot Log In

Symptoms: Login fails or page redirects.

Solutions:

  • Clear browser cookies for the site
  • Check that the data volume is mounted
  • Verify the installation completed properly

Symptoms: Added links disappear.

Solutions:

  • Verify persistent volume is mounted at /var/www/shaarli/data
  • Check file permissions in the data directory
  • Review PHP error logs

Search Not Working

Symptoms: Search returns no results.

Solutions:

  • Rebuild the search index in Tools
  • Check that links are public (if not logged in)
  • Verify the data files aren’t corrupted

Additional Resources

Conclusion

Deploying Shaarli on Klutch.sh gives you a lightweight, reliable bookmark manager that requires no database and minimal resources. With its tag system, RSS feeds, and bookmarklet, Shaarli provides everything needed to build your personal link collection while keeping full control of your data.