Skip to content
Serverküche
Search

Loading search …

Applications Difficulty: Intermediate

linkding: Self-Host Your Bookmarks

All your bookmarks in one place, across devices and without browser lock-in: linkding as a lean bookmark manager behind Traefik – with tags and API.

· Last updated: · 11 min read ·Duration: approx. 40 minutes
Table of contents

Browser bookmarks are tied to one device, chaotically organized and gone the moment the profile breaks. linkding collects your links centrally on your own server: via the browser, an extension, the API – searchable, tagged and cross-device.

What are we building?

A lean, self-hosted bookmark manager with linkding (v1.47.0) behind Traefik. By the end you save links in one click, tag them, find them again via full-text search – and linkding fetches title and description from the linked page automatically. On top of that we set up the REST API so you can create bookmarks from scripts, and walk through the settings that decide what data your server hands out.

linkding is deliberately minimalist: a single container, SQLite instead of a separate database, no cache, no search index service. The entire state of a fresh instance with its first bookmarks takes up just under 1 MB on disk.

Prerequisites

🍳 Recommendation Ad

VPS 1000 G12.5

4 vCores · 8 GB RAM · 128 GB SSD

from €14.50/month

linkding is tiny – even the smallest VPS is bored by it.

Go to netcup →

💶 1 month free:

Single use, valid for VPS 1000 G12.5. Redeem in the cart →

💶 €5.95 voucher for new netcup customers: always valid · not for domains or VPS Lite

All netcup vouchers →

Step by step

Step 1: Project and Compose file

linkding stores everything (database, settings, favicons) in a data folder. Create the project:

Terminal
mkdir -p /opt/linkding/data && cd /opt/linkding

The compose.yaml – replace YOUR_DOMAIN. linkding creates the admin account on first start from the environment variables:

YAML
services:
  linkding:
    image: sissbruecker/linkding:1.47.0
    restart: unless-stopped
    volumes:
      - ./data:/etc/linkding/data
    environment:
      LD_SUPERUSER_NAME: cook
      LD_SUPERUSER_PASSWORD: YOUR_STRONG_PASSWORD
      LD_CSRF_TRUSTED_ORIGINS: https://YOUR_DOMAIN
    networks: [proxy]
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.linkding.rule=Host(`YOUR_DOMAIN`)"
      - "traefik.http.routers.linkding.entrypoints=websecure"
      - "traefik.http.routers.linkding.tls.certresolver=le"
      - "traefik.http.services.linkding.loadbalancer.server.port=9090"

networks:
  proxy:
    external: true

The image tag is deliberately pinned to 1.47.0 instead of latest: that way you decide when an update happens, and a docker compose pull won’t silently drag in a new major version. Port 9090 belongs in the loadbalancer.server.port label because linkding doesn’t listen on 80 – without that label Traefik guesses wrong.

LD_CSRF_TRUSTED_ORIGINS is insurance: Django checks on every POST whether the origin of the request matches the host name. Directly behind Traefik that works without the entry, because Traefik passes the Host header through unchanged. But if another proxy in front rewrites the host, or linkding runs under a sub-path, login fails with a CSRF error (see “When things go wrong”) – the entry costs nothing and prevents that.

Step 2: Start and log in

Terminal
docker compose up -d

The image ships its own health check, and Traefik only routes once the container reports healthy. Until then, for about half a minute, you get a 404 from Traefik on your domain – not a fault, the container just isn’t in the routing table yet. You can watch the status directly:

Terminal
docker compose ps
Ausgabe
NAME                  IMAGE                          COMMAND            SERVICE    STATUS
linkding-linkding-1   sissbruecker/linkding:1.47.0   "./bootstrap.sh"   linkding   Up 39 seconds (healthy)

Once it says (healthy), the domain answers too. The /health endpoint works without a login and reports the running version – handy for updates and monitoring:

Terminal
curl https://YOUR_DOMAIN/health
Ausgabe
{"version": "1.47.0", "status": "healthy"}

Then open https://YOUR_DOMAIN/ and log in with the account from the Compose file:

The linkding login page under your own HTTPS domain
The linkding login – the credentials come from the Compose file

Get the password out of the Compose file

LD_SUPERUSER_PASSWORD sits in plain text in your compose.yaml and only takes effect on the very first start. Change the password afterwards in the interface under Settings → Change password and remove both LD_SUPERUSER_* lines from the Compose file – they aren’t needed any more.

Step 3: Save your first bookmark

Click Add bookmark at the top and paste a URL. linkding fetches the page and fills in title and description automatically – you only add tags (separated by spaces, without #):

The form for creating a bookmark with automatically filled title and description
\"Add bookmark\": linkding fetches title and description from the page itself; you add tags

That fetch happens on your server, not in the browser – so the target site sees your VPS’s IP, not yours. Since version 1.47.0 linkding protects these server-side requests against SSRF, so it no longer calls internal addresses on your network just because somebody entered one as a bookmark.

Optionally you can mark a bookmark as unread (“Mark as unread”) – handy as a read-later list. Under Notes there’s room for your own note, separate from the target page’s description.

Step 4: Search and filter the collection

The overview shows your bookmarks chronologically, with a clickable tag cloud on the right. The search finds links by words or #tags:

The linkding overview with several bookmarks, tags and a search box
The bookmark list: title, tags and auto description, with tag navigation on the right

Clicking a tag filters instantly; multiple tags combine the filters – without any folder hierarchy. Since version 1.44 the search understands logical expressions: #docker and not #reference finds everything tagged docker that isn’t also tagged reference. By default tag search runs in strict mode, so tags must be written with # – otherwise they’d be indistinguishable from plain search terms. You can change that under Settings → General → Tag search.

Step 5: Save quickly from the browser

For everyday use you don’t want to open the web interface every time. Under Settings → Integrations you’ll find both convenient routes plus API access:

The linkding integrations page with browser extension, bookmarklet and REST API
Settings → Integrations: extension, bookmarklet, API token and RSS feeds in one place

  • Browser extension: there’s an official linkding extension for Firefox and Chrome. In its settings you enter https://YOUR_DOMAIN and an API token. After that you save the current page with one click.
  • Bookmarklet: a bookmark in your browser bar that sends the current page straight to linkding. Works without an extension, on mobile too. You can choose whether title and description are detected on the server or in the browser (“Detect title and description in the browser”) – the browser variant helps with pages that are only readable while logged in or block automated access.

You create the token in the REST API section via Create API token, with a descriptive name per application.

The token is shown exactly once

After creating it, the token appears once (“Copy this token now, it will only be shown once”); after that the list only shows the name. A token with full access to all your bookmarks belongs in your password manager, not in a script in plain text – and use a separate one per application so you can revoke a single token without breaking all the others.

Step 6: Manage bookmarks via the API

With the token linkding becomes scriptable. Put it into an environment variable so it doesn’t end up in your shell history:

Terminal
read -rs LINKDING_TOKEN && export LINKDING_TOKEN

Authentication goes through an Authorization header. First test – list your own bookmarks:

Terminal
curl -H "Authorization: Token $LINKDING_TOKEN" \
  "https://YOUR_DOMAIN/api/bookmarks/?limit=1"
Ausgabe
{
    "count": 4,
    "next": "https://YOUR_DOMAIN/api/bookmarks/?limit=1&offset=1",
    "previous": null,
    "results": [
        {
            "id": 4,
            "url": "https://serverkueche.de/",
            "title": "Serverküche – Selfhosting-Tutorials, frisch serviert",
            "description": "Praxisnahe Schritt-für-Schritt-Anleitungen fürs Selfhosting …",
            "notes": "",
            "is_archived": false,
            "unread": false,
            "shared": false,
            "tag_names": [
                "docker",
                "selfhosting",
                "serverkueche"
            ],
            "date_added": "2026-09-27T23:54:21.396342Z",
            "date_modified": "2026-09-27T23:54:21.396350Z"
        }
    ]
}

Creating a bookmark is a POST with JSON. You may leave out title and description – linkding fetches them from the page here too:

Terminal
curl -X POST \
  -H "Authorization: Token $LINKDING_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://www.debian.org/releases/trixie/","tag_names":["debian","release"],"unread":true}' \
  "https://YOUR_DOMAIN/api/bookmarks/"
Ausgabe
{
  "id": 5,
  "url": "https://www.debian.org/releases/trixie/",
  "title": "Debian -- Debian “trixie” Release Information",
  "tag_names": [
    "debian",
    "release"
  ],
  "unread": true
}

The field is called tag_names, not tags: if you send "tags": [...], the bookmark is created without an error, but with "tag_names": []. So check the response of your first call before you run an import loop over it.

Searching works just like in the interface, via the q parameter (the # has to be URL-encoded as %23):

Terminal
curl -H "Authorization: Token $LINKDING_TOKEN" \
  "https://YOUR_DOMAIN/api/bookmarks/?q=%23docker"

Without a valid token every API endpoint answers with 401 – so the API isn’t accidentally open:

Ausgabe
{"detail":"Authentication credentials were not provided."}

Step 7: The settings that make the difference

Under Settings → General there are four options worth going through deliberately once.

Auto Tagging assigns tags based on the URL without you typing them. Each line is one rule made of a domain (or domain plus path) and the tags behind it:

Ausgabe
docs.docker.com doku docker
debian.org debian linux
reddit.com/r/selfhosted selfhosting reddit

The rules apply to bookmarks from the API and the extension as well: a POST to https://docs.docker.com/compose/ without tag_names comes back with ["docker", "doku"].

Enable Favicons is off by default. Turn it on and linkding downloads the icons via a Google service by default – an ugly back channel, because Google learns about every domain you save. The linkding docs name DuckDuckGo as an alternative; add one line to the Compose file:

YAML
      LD_FAVICON_PROVIDER: https://icons.duckduckgo.com/ip3/{domain}.ico

After docker compose up -d and enabling favicons, the icons land as .ico files under data/favicons/ – Google serves PNGs, which tells you which provider was used.

Internet Archive integration is off too, and should stay that way unless you explicitly want it: enabled, linkding reports every saved URL to the Wayback Machine – useful once the original disappears, but your reading list becomes visible to a third party.

Enable public bookmark sharing (off by default) makes bookmarks marked as shared reachable without a login – anyone who knows your instance’s address can see that list.

If you want an extra bolt in front of the login page, rate limiting and security headers belong in the proxy rather than the app – Hardening Traefik middlewares shows how.

When things go wrong

The page doesn’t load, Traefik answers with a 404, even though the container is running. The health check isn’t healthy yet (see step 2). Check with docker compose ps or docker inspect -f '{{.State.Health.Status}}' linkding-linkding-1; if it stays unhealthy, docker compose logs linkding tells you why.

The login form answers with Forbidden (403) CSRF verification failed. The login page itself loads normally, but Django didn’t consider the request’s origin trustworthy – typical when a proxy in front of Traefik rewrites the Host header or linkding runs under a sub-path. Add LD_CSRF_TRUSTED_ORIGINS: https://YOUR_DOMAIN (with https://, without a path and without a trailing slash) and run docker compose up -d.

Title and description aren’t fetched automatically. The target page blocks automated access or responds too slowly. Enter both by hand or switch the bookmarklet to detection in the browser (step 5).

The admin account wasn’t created. LD_SUPERUSER_NAME and LD_SUPERUSER_PASSWORD only take effect on the first start with an empty database. If data/db.sqlite3 already exists, a later change does nothing. Create the account afterwards: docker compose exec linkding python manage.py createsuperuser.

The API or the extension answers with 401. Either the token is missing or it’s wrong: {"detail":"Authentication credentials were not provided."} means the Authorization header never arrived, {"detail":"Invalid token."} means the token doesn’t match. Since a token is only shown once, creating a new one under Settings → Integrations is faster than hunting for the old one. Enter exactly https://YOUR_DOMAIN as the server, with no path after it.

Your problem is not listed? Search all error messages →

Maintenance & backups

  • Updates. Set the image tag (sissbruecker/linkding:1.47.0) to the current version and restart with docker compose up -d; the database migrates automatically at start. curl https://YOUR_DOMAIN/health shows whether the new version is running. The rest runs through your normal update process.

  • Backup: the data folder – but consistently, please. The entire state lives in data/. The catch: linkding runs SQLite in WAL mode, and on a fresh instance more than half the data can still sit in db.sqlite3-wal rather than db.sqlite3 – back up only the .sqlite3 file and you lose the larger part. Either you back up the complete folder including -wal and -shm, or you create a self-consistent snapshot first:

    Terminal
    docker compose exec -T linkding python -c \
      "import sqlite3; s=sqlite3.connect('data/db.sqlite3'); \
       d=sqlite3.connect('data/db-backup.sqlite3'); s.backup(d); d.close(); s.close()"

    That uses SQLite’s online backup interface and works while the service runs – the image doesn’t ship an sqlite3 command line tool. Take the resulting data/db-backup.sqlite3 along with the folder into your Restic backup.

  • Plus an HTML export. Under Settings → Export you download your collection as bookmarks_YEAR-MONTH-DAY_HH-MM-SS.html in the Netscape bookmark format – the same format every browser imports. That’s your service-independent emergency backup: even if linkding refuses to start, the links including tags and descriptions stay readable. The other direction (Settings → Import) brings existing bookmarks over from a browser or another service and turns folders into tags.

  • Near-zero effort. linkding is a “set it up and forget it” service: one container, no background services and around 240 MB of memory at idle.

You might also like