Published

Linkwarden

Collaborative bookmark manager that keeps a copy of every saved page: a screenshot, a PDF, a self-contained HTML file and a readable text view, with collections, tags, highlights and full-text search. The self-hosted stack is the app (web, background worker and a headless Chromium in one container), PostgreSQL and Meilisearch.

Resources by load level

What the app itself needs at each level, next to what we recommend for a server that runs only this app.

Level	What it means	App requirements	Recommended
LightEstimate	Up to 3 users, ~2,000 saved links with the default formats, ~20 new links a day; preservation at the default 5 links per batch, full-text search on.	2.25 vCPU · 3 GiB RAM · 17.75 GiB disk	2.82 vCPU · 5.1 GiB RAM · 29.958 GiB disk
MediumEstimate	Up to 10 users, ~10,000 saved links, ~100 new links a day and occasional imports of a few thousand bookmarks; full-text search over all of them.	3 vCPU · 4.5 GiB RAM · 52.5 GiB disk	3.72 vCPU · 6.9 GiB RAM · 69.92 GiB disk
HeavyEstimate	Up to 30 users, ~25,000 saved links, ~300 new links a day with regular imports and RSS feeds; the worker keeps 5 pages preserving at once.	4 vCPU · 7.5 GiB RAM · 118.5 GiB disk	4.92 vCPU · 10.5 GiB RAM · 145.82 GiB disk

Recommended = app requirements + system baseline + safety headroom, under sizing policy 2026.10.0. Options stay at their defaults. “Estimate” means the sources give no number for that case, so it is worked out from them by the method stated under Components. How the numbers are built

Size it in the Stack Sizer

Ready-to-run files

Support level Supported

Compose template from the official sources; not yet verified by a run.

Create docker-compose

Components

What each component needs at each load level, before baseline and headroom.

vCPU / GiB RAM / GiB disk
Component	Light	Medium	Heavy	Sources
Linkwarden (web, worker and headless Chromium) (app)	1 / 1.5 / 10	1.5 / 2 / 41	2 / 2.5 / 100	[11][12][13][19][29]
PostgreSQL (database)	1 / 1 / 6.5	1 / 1 / 6.5	1 / 1 / 6.5	[13][23][33][39][40][41][42][43][44][45]
Meilisearch (full-text search) (other)	0.25 / 0.5 / 1.25	0.5 / 1.5 / 5	1 / 4 / 12	[12][22][34][36]

How the estimates are worked out

Linkwarden (web, worker and headless Chromium) · Light: RAM: ~350 MB idle (docs) plus a headless Chromium rendering up to 5 pages per batch and two Node processes (web, worker); 1.5 GiB. vCPU: one core for page rendering, PDF and HTML capture. Disk: image 1,713,869,312 B unpacked (1.596 GiB) rounded up to 1.75 GiB + 2,000 links × an assumed 4 MiB of preserved files (7.8 GiB), rounded up to 10 GiB.
Linkwarden (web, worker and headless Chromium) · Medium: Imports keep the worker at its default 5 links per batch for hours, so more than light: 2 GiB RAM and 1.5 vCPU, within the docs' 4 GB / 2-core machine for the whole stack. Disk: 1.75 GiB image + 10,000 links × an assumed 4 MiB of preserved files (39.1 GiB), rounded up to 41 GiB.
Linkwarden (web, worker and headless Chromium) · Heavy: The docs' 4 GB / 2-core machine minus PostgreSQL (1 GiB) and a small Meilisearch (0.5 GiB) leaves ~2.5 GiB for Linkwarden at its defaults, which this level uses all the time: 2 vCPU / 2.5 GiB. Disk: 1.75 GiB image + 25,000 links × an assumed 4 MiB of preserved files (97.7 GiB), rounded up to 100 GiB.
PostgreSQL · Light: Embedded metadata DB with the image's default config: equals the PostgreSQL profile's light preset (≤ 5 GB data, ≤ 20 concurrent connections) at every load level. Light preset method: shared_buffers 25% of RAM, worst-case work_mem/maintenance_work_mem budget, 0.5 GiB image + 5 GiB data + 1 GiB WAL.
PostgreSQL · Medium: Readable text is stored per link in PostgreSQL (the main database growth, per the docs): 10,000 links × an assumed 50 KB = 0.5 GB, inside the sidecar's 5 GB. Prisma 6 opens physical CPUs × 2 + 1 connections per process (web, worker): 18 on a 4-core host, inside 20. Light preset method: shared_buffers 25% of RAM, 0.5 GiB image + 5 GiB data + 1 GiB WAL.
PostgreSQL · Heavy: 25,000 links × an assumed 50 KB of readable text and rows = 1.25 GB, still inside the sidecar's 5 GB; set TEXT_CONTENT_LIMIT to cap it. Two Prisma pools (web, worker) of physical CPUs × 2 + 1 stay within 20 connections up to 4 cores. Light preset method: shared_buffers 25% of RAM, 0.5 GiB image + 5 GiB data + 1 GiB WAL.
Meilisearch (full-text search) · Light: Each link is indexed as a document with its readable text (assumed ~20 KB): 2,000 × 20 KB = 40 MB raw. Meilisearch's measured example grew 9.1 MB of JSON to 224 MB on disk (~25×), so ~1 GB index. RAM: 0.5 GiB, above the ~305 MB of that example. Disk: 91.3 MiB compressed image × 3 (0.27 GiB) + 0.92 GiB index, rounded up to 1.25 GiB.
Meilisearch (full-text search) · Medium: 10,000 links × ~20 KB = 200 MB raw, ~25× on disk as in Meilisearch's measured example: 4.6 GiB index. RAM: 1.5 GiB, about a third of the index, the ratio the docs say does not materially hurt performance. Disk: 0.27 GiB image + 4.6 GiB index, rounded up to 5 GiB.
Meilisearch (full-text search) · Heavy: 25,000 links × ~20 KB = 500 MB raw, ~25× on disk as in Meilisearch's measured example: 11.4 GiB index. RAM: 4 GiB, about a third of the index (the docs' ratio). vCPU: one core for steady indexing in batches of 50 links. Disk: 0.27 GiB image + 11.4 GiB index, rounded up to 12 GiB.

Ports

Public ports are meant to be reached from outside the stack, usually through a reverse proxy; internal ones stay on the stack's own network.

Component	Port	Exposure	Purpose	Sources
Linkwarden (web, worker and headless Chromium)	3000/tcp	Public, through a proxy	Web UI, REST API, browser extension and mobile app (HTTP; put behind TLS)	[2][4]
PostgreSQL	5432/tcp	Internal only	PostgreSQL connections from the web and worker processes	[2][44]
Meilisearch (full-text search)	7700/tcp	Internal only	Meilisearch API (indexing by the worker, searches by the web app)	[6][7]

Every port in the catalog, with conflicts between apps

User and permissions (UID/GID)

The user each container's process runs as, and the paths it writes to. A bind mount for one of these paths must be writable by that UID:GID.

Component	UID:GID	User	Starts as root	Writes to	Sources
Linkwarden (web, worker and headless Chromium)Derived	0:0	`root`	No	`/data/data/data/apps/web/.next/cache`	[4][5][14]
PostgreSQL	999:999	`postgres`	Yes, prepares its directories, then drops to this user	`/var/lib/postgresql/var/run/postgresql`	[37][38][44]
Meilisearch (full-text search)Derived	0:0	`root`	No	`/meili_data`	[7][8]

Linkwarden (web, worker and headless Chromium): The Dockerfile sets no USER, so web, worker and Chromium run as root and never drop privileges; the docs confirm this and show user: 1000:1000 with pre-owned folders as the alternative. Preserved files go to /data/data; the Next.js image cache is pre-created world-writable.
Meilisearch (full-text search): The Meilisearch Dockerfile sets no USER and starts /bin/meilisearch under tini, so it runs as root; its database lives in /meili_data/data.ms.

Storage growth

How much each component's data grows per month at each load level, on top of the disk in the profile. A value marked Assumption is ANAROQ's stated assumption, not a figure from the sources; the notes say what it rests on.

GiB per month
Component	Light	Medium	Heavy	Sources
Linkwarden (web, worker and headless Chromium)Assumption	2.344	11.719	35.156	[12][19]
PostgreSQLAssumption	0.03	0.14	0.42	[13]
Meilisearch (full-text search)Assumption	0.28	1.4	4.2	[22][34]

What the growth figures rest on

Linkwarden (web, worker and headless Chromium): New links × 30 days × an assumed 4 MiB of preserved files per link (screenshot, PDF, HTML and readable text, all on by default): 20, 100 and 300 links a day. Nothing expires: files are removed only with their link. Each format is capped at 100 MB (*_MAX_BUFFER).
PostgreSQL: New links × 30 days × an assumed 50 KB of readable text and rows per link; the docs name stored readable text as the main database growth, which TEXT_CONTENT_LIMIT caps (unlimited by default).
Meilisearch (full-text search): New links × 30 days × ~20 KB per indexed link × ~25 (the on-disk growth in Meilisearch's measured example). LMDB never returns freed space to the system, so the index does not shrink when links are deleted.

Upgrade and rollback

How to move to a new version safely, and how to go back if it fails.

Back up first

Migrations cannot be undone: first take a pg_dump of the linkwarden database and an archive of the data volume (preserved files) and the .env. [17]

Upgrade steps

Read the release notes of every version between yours and the new one: breaking changes are called out there. [17]
Change the pinned linkwarden tag, then run docker compose pull and docker compose up -d. Migrations run on their own before the app listens; follow docker compose logs -f linkwarden until it is ready. [4][17]
Change the Meilisearch tag only to the one the new release's docker-compose.yml pins, and migrate its database with a dump or a dumpless upgrade: a Meilisearch database only works with the version that created it. [24][25][35]DerivedLinkwarden's guide covers its own image only; the Meilisearch step follows from upstream's compose bumping Meilisearch inside 2.16.x and from the Meilisearch upgrade guide.

Roll back

Restore the database dump from before the upgrade and pin the image back to the previous tag. Both are needed: an older release cannot read a schema a newer migration has changed. [17]

Known breaking changes

In 2.16.1: The official compose moved Meilisearch from v1.12.8 to v1.13.3. A Meilisearch database only opens in the version that created it, so an existing index needs a dump or a dumpless upgrade. [24][25][35]
In 2.15.0: DISABLE_PRESERVATION was renamed DISABLE_BROWSER; an old .env silently keeps preservation on. The image was rewritten (about 1.5 GB instead of 3 GB, ~350 MB idle). [13][17][26][27]
In 2.0.0: NEXTAUTH_URL must end in /api/v1/auth, and instances coming from v1 run a one-time migration script. [18]

Limits

Preservation runs a headless Chromium inside the app container, 5 links per batch with up to 5 minutes per page. On a small server set ARCHIVE_TAKE_COUNT=1, turn off the PDF and Webpage formats, or set DISABLE_BROWSER=true for bookmarks only. [12][13]
The server visits pages as an anonymous visitor: logins, paywalls and bot blocks end up in the copy, and private-network addresses are refused by default. Capture such pages from your own browser with the extension or SingleFile. [12][19]
Each collection owner can store up to 30,000 links (MAX_LINKS_PER_USER), uploads are capped at 10 MB and each generated format at 100 MB. Files stay on the server's disk; S3-compatible storage needs SPACES_* settings the template doesn't write. [12][19]

Security

Serve Linkwarden over HTTPS from a reverse proxy and set NEXTAUTH_URL to https://<domain>/api/v1/auth; sign-in and OAuth callbacks are built from it. [12][15]
Registration is open by default and the first account becomes the administrator. Create it right after the first start, then set NEXT_PUBLIC_DISABLE_REGISTRATION=true; the administrator can still add users. [12][20]
The archiving Chromium opens untrusted pages without its own sandbox (Playwright's default) as root, so the container is the only boundary. The template grants no extra capabilities; the docs show how to run as user 1000:1000. [14][21][32]
Preserved HTML is served from the app's own origin unless NEXT_PUBLIC_USER_CONTENT_DOMAIN points at a second domain. For untrusted pages, add that domain at the proxy as the docs describe. [16]

Backup

Back up three things together: a pg_dump of the database, the data volume with the preserved files, and the .env (NEXTAUTH_SECRET and the passwords). [17]
Keep the Meilisearch volume too: PostgreSQL records which links are already indexed, so an empty index is not refilled on its own and full-text search would miss older links. [8][22]