Self-hosted service
shaarli/Shaarli avatar
shaarli/Shaarli

Shaarli: flat files, four-stage Docker builds, and a proxy pinned to Traefik 1.7

The personal, minimalist, super-fast, database free, bookmarking service - community repo

3,922 stars320 forksPHPNOASSERTION

At a glance

What is it?
A single-user bookmarking service written in PHP with no database, distributed as a JAR-equivalent release twice a month. Its compose example still targets Traefik 1.7 label syntax, and its frontend pins several transitive dependencies by hand.
Who is it for?
Take Shaarli if you want a bookmarking service you host yourself as one user, and if having no database is a feature rather than a limitation, since your links live in flat files you can read and back up directly. Check three things first.
Can I use it commercially?
Check first. The repository uses a licence we do not classify automatically, so read its LICENSE file before any commercial use.
Is it still maintained?
Yes. The repository last received commits 7 days ago.
What is it written in?
Mainly PHP, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • shaarli/Shaarli3,922 ★ · +25
Star history
Repository2026-09-112026-11-15
shaarli/Shaarli3.9k3.9k

25 Stars in the last 65 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

No database means your links are files you can read

The defining constraint is in the first line of the project description and repeated in the readme: a database-free bookmarking service. Everything else follows from it. The readme states the design intent plainly, that it is a minimalist link sharing service you install on your own server, designed to be personal, meaning single-user, fast, and handy. There is no server to administer beyond the web server and PHP, and nothing to migrate when you move it. The compose configuration shows where the state actually lives, mounting a named volume at the data directory and a second one at the cache directory, so what you back up is files under those two paths. The tree agrees: there is a `data/` directory and a `cache/` directory, alongside a `pagecache/` directory, and no database schema, migration, or connection configuration anywhere in the root.

The demo instance resets daily and its credentials are printed

There is a public demo, and the readme is unusually explicit about how it behaves, which is the right way to present it. It runs the latest development version rather than a release, and it is updated and reset daily. The login and password are both the word `demo`, printed in the readme. So the demo is a preview of unreleased work rather than a stable instance, and anything you save there should be assumed disposable. That distinction matters more than it sounds, because the development version is where behaviour can change between releases, and the releases themselves move fast: v0.16.9 was published on 2026-10-04, v0.16.8 on 2026-09-29, and v0.16.7 on 2026-09-19. That is a patch release roughly every week to ten days, and the tag for the newest release is the same commit the default branch last moved on.

Four build stages, and the docs are built in the first one

The container image is built in four stages and the first one surprises people, because it has nothing to do with the runtime. Stage one starts from a Python image on Alpine, adds the sources, installs build tooling, and runs the documentation target. The reason is that the documentation has to exist before the packaging step. Stage two then resolves the PHP dependencies with Composer, using the prefer-dist flag and the no-dev flag so only runtime dependencies land. Stage three brings in a Node image, enables corepack, activates the pinned Yarn version, installs the frontend dependencies, runs the build, and deletes `node_modules` entirely so the build artefacts are all that survives. Stage four is the runtime: Alpine with nginx, PHP-FPM, a list of PHP extensions covering things like ctype, curl, gd, gettext, intl, ldap, mbstring, openssl, session, xml, and zlib, and s6 for process supervision. Two details are worth copying: the ICU English data package is removed and the full package installed, and both upload and POST size limits are rewritten to ten megabytes in the image.

The compose example targets Traefik 1.7, not current Traefik

The compose file is two services: Shaarli itself, from the project's container image with the tag taken from an environment variable, and a reverse proxy in front of it. The proxy is pinned to version 1.7 of the Alpine image, and its configuration is written the way that major version was configured: entry points passed as long command-line flags, plus the older dot-separated labels on the Shaarli service such as the domain and the frontend rule. Later major versions of that proxy dropped that label syntax in favour of a different router configuration, so this example is coherent with the version it pins and will not transfer to a current one unchanged. What it does show well is the intended shape: the proxy terminates TLS with a Let's Encrypt certificate obtained over an HTTP challenge, stores the account key on a mounted volume, mounts the Docker socket read-only so it can discover containers, and publishes only ports 80 and 443. Three environment variables drive it, the hostname, the certificate contact email, and the image tag.

Frontend dependencies are pinned twice over

The frontend manifest is small and its resolutions block is the interesting part. Six runtime dependencies: an autocomplete library, a lazy-loading image script, an icon font, an HTML entity decoder, and PureCSS with its extras module. The rest is build tooling, so webpack with Babel and Sass loaders, terser, and stylelint with both standard and standard-scss configurations. What is unusual is the resolutions block, which pins seven transitive packages to exact versions: a string width package, two minimatch entries, an ajv keywords package, two brace expansion entries, and the terser plugin. Nobody writes those resolutions because they are the dependencies they use; they are written because something upstream broke. That is dependency pinning as a maintenance practice rather than as an initial choice, and it means the frontend build is reproducible at the cost of carrying overrides you now have to revisit on every upgrade.

The default make target checks file permissions before running tests

The Makefile is for a PHP project, so its vocabulary is the PHP toolchain rather than a build system. The default target runs a permission check and then the test suite. The permission check is unusual enough to be worth reading: it walks the files git tracks, excludes anything under docker, and fails if any tracked file is executable, on the reasoning that a source tree full of executable files means somebody's permissions leaked into a commit. There are four code sniffer targets, the default one, one that reports errors by git author, one that reports everything with a full report at a width of 200, and one that groups errors by source. The test target depends on both the development Composer dependencies and a translate step, creates a sandbox directory and a coverage directory, and runs PHPUnit with coverage enabled, which means the run needs an extension present to produce that report.

There is a docker make adapter so tests can run unprivileged

One Makefile pattern deserves its own mention because it answers a problem specific to containerised PHP development. Any target can be invoked through a docker-prefixed variant, which copies the sources and the vendored libraries out of a shared volume into a user-owned directory with rsync, changes into that copy, and then runs the requested target there. The comment above it explains why: the sources and vendored libraries are copied from a shared volume to a user-owned directory to enable running tests as a non-root user. So the suite can run as an ordinary user rather than as root inside the container, which matters for a project whose own test suite creates sandbox and coverage directories and whose permission check cares about how files are owned. Related files at the root support the same concern, including a PHP CodeSniffer configuration, a PHPUnit configuration, a phpdoc configuration, and an `.htaccess` for the Apache deployment route that predates the container.

Editorial conclusion

Take Shaarli if you want a bookmarking service you host yourself as one user, and if having no database is a feature rather than a limitation, since your links live in flat files you can read and back up directly. Check three things first. It is single-user by design, so a shared instance is outside what it is built for. The compose example ships a reverse proxy pinned to an old major version with the older label syntax, so copy it as a starting point rather than as a current recipe. And the licence is per component rather than one file, with the project pointing at a copying file for the details of each, so check that file rather than assuming a single standard licence.

Frequently asked questions

What is Shaarli used for?

It is a personal, minimalist bookmarking and link sharing service you install on your own server. It is designed for a single user, and because it has no database, the links are stored in flat files rather than in a database server.

Is Shaarli single-user or multi-user?

Single-user. The readme states it is designed to be personal, meaning a single user, fast and handy, so a shared or team instance is outside what the project is built for.

How do I run Shaarli with Docker?

The repository ships a compose example with two services, Shaarli from the project's container image with the tag set by an environment variable, and a reverse proxy terminating TLS. Three variables drive it: the virtual host, the certificate contact email, and the image tag.

What licence is Shaarli under?

It is described as free software, and the readme points to a copying file in the repository for the detail of the contributors and the licence of each individual component, so the terms are per component rather than one identifier.

Official sources

  1. Issues
  2. Project website
  3. README
  4. Releases
  5. shaarli/Shaarli on GitHub
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/shaarli-shaarli.svg)](https://hysenlabs.com/projects/shaarli-shaarli)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/shaarli-shaarli.svg)](https://hysenlabs.com/projects/shaarli-shaarli)

Was this useful?