DEV Community: John

Immich Sizing Guide: What a 20,000 Photo Google Takeout Import Really Costs in Disk, RAM and Hours

John — Sat, 29 Aug 2026 07:05:56 +0000

Budget roughly 1.35 to 1.6 times your raw photo size on disk, 6 GB of RAM for the full stack with machine learning enabled, 4 CPU cores, and a full weekend of background processing before a 20,000 item library is fully searchable. The import itself is the fast part. Thumbnail generation, video transcoding and machine learning jobs are what actually keep the server busy, and three settings decided in the first hour, the storage template, the machine learning model, and the transcoding policy, are the ones that force a full re-run of every job if you change your mind in month two.

TL;DR by reader profile:

The phone-only archivist, one iPhone and 20,000 photos with almost no video: 2 CPU cores, 4 GB RAM and 1.4x your library size is enough, because thumbnails dominate and transcoding barely runs.
The family with a decade of camcorder video, 20,000 items where 3,000 are clips: go to 4 cores and 8 GB RAM before you import, because video transcoding is the single job that will run for days on weak hardware.
The RAW shooter with a Lightroom folder tree, 20,000 files averaging 25 MB: use an external library in read-only mode rather than uploading, so Immich never becomes the only copy of your originals.
The privacy-first switcher leaving Google Photos this week: set the storage template and the machine learning model before the first upload, then never touch them again, because both settings rewrite work already done.
The low-power host, a Raspberry Pi 5 or an N100 mini PC: disable the smart search model on day one and run facial recognition only, or accept that machine learning jobs will still be queued a week later.
The person who just wants it working tonight: import with default settings, leave transcoding on the optimal policy, and treat the first 72 hours as unattended processing time rather than a broken install.

The central tradeoff is that every setting which makes Immich feel fast and searchable later, larger machine learning models, generated previews, transcoded video, costs you disk and hours of CPU during the first week, and changing your mind afterwards means paying that cost a second time.

How much disk space does Immich actually need for 20,000 photos?
Why is the Immich database and thumbnail folder bigger than you expected?
How much RAM does Immich need, and what happens when it runs out?
How many CPU cores does the first import really use?
How long does a 20,000 item Google Takeout import take from start to searchable?
Should you upload into Immich or point it at an external library?
What does the Google Takeout format break, and how do you fix it before importing?
Which storage template should you set before the first upload?
Which machine learning model should you choose on day one?
What should the video transcoding policy be, and what does it cost you?
Where should you actually run Immich: NAS, mini PC, home server or hosted?
Which day-one settings force a full re-run if you change them later?

How much disk space does Immich actually need for 20,000 photos?

Start from the size of your Google Takeout, not the photo count. A 20,000 item library from a modern phone is usually somewhere between 60 GB and 120 GB of originals, because a 12 megapixel HEIC frame lands near 2 MB while a single 4K clip can pass 400 MB. Immich stores your originals untouched, then adds derived files on top.

The multiplier you should plan for is 1.35x to 1.6x the original size, split across four directories under UPLOAD_LOCATION:

upload/ and library/, the originals: 100 percent of your Takeout size, byte for byte, because Immich never recompresses the file you gave it.
thumbs/, the previews: typically 15 to 25 percent on a photo heavy library, since every asset gets a small thumbnail plus a larger preview image used by the timeline and the detail view.
encoded-video/, the transcodes: zero if you have no video, but easily 50 to 100 percent of your video bytes again when the default policy re-encodes clips your browser cannot play natively.
The Postgres volume, metadata and machine learning vectors: small in absolute terms, usually a few hundred megabytes at this scale, but it grows with embeddings and faces rather than with file size.

Practical floor: if your Takeout unzips to 90 GB, provision 200 GB and do not let the filesystem cross 80 percent during import. Running du -sh on each subdirectory after the first 1,000 assets gives you a real multiplier for your own library, which beats any generic estimate.

Why is the Immich database and thumbnail folder bigger than you expected?

Because Immich does not generate one thumbnail per photo. It generates a small WebP tile for the timeline grid and a much larger preview used whenever you open an asset, and that second file is the one that surprises people. A 2 MB HEIC original can produce a preview of several hundred kilobytes, so the ratio between a phone photo and its derivatives is far worse than it is for a 25 MB RAW file, where the same preview is a rounding error.

Four things inflate these directories beyond a naive estimate:

Preview resolution is a setting, not a constant: the preview size configured in Administration, Settings, Image Settings applies to every asset, so raising it after import means every existing preview is regenerated and the old ones replaced.
Motion photos count twice: an iPhone Live Photo or a Samsung motion shot arrives as a still plus a short video, and Immich stores and processes both, which quietly turns 20,000 selected items into more than 20,000 stored assets.
Postgres carries vectors, not just rows: smart search stores an embedding per asset and facial recognition stores one per detected face, so a library with many group photos grows the database faster than a library of landscapes.
Deleted assets linger for 30 days: the trash retention default keeps originals and derivatives on disk until the period expires, so disk usage during a messy first week reflects your mistakes as well as your library.

Check the real split with du -sh thumbs encoded-video inside UPLOAD_LOCATION before you conclude anything about total size.

How much RAM does Immich need, and what happens when it runs out?

Plan for 6 GB of system RAM for the full stack with machine learning enabled, and 4 GB if you disable smart search. The four containers are not equal: the server and Postgres are steady and modest, Redis is tiny, and immich-machine-learning is the one that spikes, because it loads a model into memory the first time a job needs it and holds it there.

What failure looks like is the part nobody warns you about. The kernel OOM killer does not stop Immich politely. It kills the machine learning container mid job, the job returns to the queue, the container restarts, reloads the model, and fails again on the same asset. You get a silent loop that burns CPU for hours and never advances the counter.

Three signals tell you this is happening:

docker compose ps shows a restart count climbing: the machine learning container sits at 5 or 10 restarts while the server container sits at 0.
The job queue stalls at the same number: smart search stays frozen while thumbnail generation keeps moving, because only one container is dying.
dmesg | grep -i oom prints kill lines: this is the definitive check, and it names the process that was terminated.

The fix is either more RAM, a smaller model, or fewer concurrent machine learning jobs, set to 1 in the job settings.

Hosting choice matters here because you cannot add RAM to a box that has none free. A NAS with 4 GB shared with other services, a self-managed VPS, a mini PC and a managed option are all viable starting points. Yundera is a managed Personal Cloud Server, built on CasaOS, that runs self-hosted apps as Docker containers on a server dedicated to the user.

How many CPU cores does the first import really use?

All of them, unless you tell Immich otherwise. Immich runs background work as named job queues, and each queue has its own concurrency setting in Administration, Settings, Job Settings. The defaults are tuned for a machine that is doing nothing else, so on a 4 core box the first import will pin every core for hours and make the web interface feel sluggish while you are still uploading.

The queues do not weigh the same:

Thumbnail Generation: the heaviest sustained consumer during a bulk import, because it decodes every original and writes two derivatives, and it scales almost linearly with the concurrency value you set.
Video Transcoding: the one queue you should keep at concurrency 1, since FFmpeg already uses multiple threads internally and running two transcodes at once mostly makes both slower.
Smart Search and Face Detection: CPU bound unless you have a supported GPU, and these are the queues that decide whether your library is searchable on day three or day seven.
Metadata Extraction: cheap per asset, fast to complete, and rarely the bottleneck at 20,000 items.

Four cores is a workable floor. Two cores works but roughly doubles your wall clock time, and a shared vCPU with a burst credit balance will collapse to baseline speed partway through and stay there.

Watch it live with docker stats, which shows per container CPU percentage. If immich-server sits near your core count times 100 percent for hours, that is normal during first import, not a fault. Lower Thumbnail Generation concurrency to 2 if you need the machine responsive for anything else.

How long does a 20,000 item Google Takeout import take from start to searchable?

Think in phases, not in one number. The upload finishes long before the library is usable, and the gap between those two moments is where people assume something is broken.

Phase	What is happening	Typical shape on 4 cores
Upload via `immich-go` or the CLI	Files transferred, metadata read, duplicates skipped	Minutes to a few hours, limited by disk or LAN speed
Metadata extraction	Dates, GPS, camera fields written to Postgres	Completes soon after upload, rarely the bottleneck
Thumbnail generation	Two derivatives written per asset	Several hours, and the timeline stays gappy until it ends
Video transcoding	Non compatible clips re-encoded by FFmpeg	Hours to days, entirely driven by how much video you have
Smart search and face detection	Embeddings and faces computed per asset	The long tail, often the last queue still running

A photo heavy library with under 500 short clips is usually fully processed inside 24 hours on 4 cores. Add 3,000 camcorder clips and the same library can take a long weekend, because transcoding runs at concurrency 1 by design.

Two practical points. First, upload speed and processing speed are independent: immich-go can finish at 2 a.m. while the job queues still have 18,000 items pending. Second, the Jobs page in the admin panel shows an active and a waiting count per queue, and the waiting count falling is the only honest progress bar you have.

Do not judge the install until every queue reads zero. Search results, people grouping and the map view are all incomplete before that point, and re-running them costs the same hours again.

Should you upload into Immich or point it at an external library?

Upload if Immich is becoming your primary photo home. Use an external library if you already have a folder tree you edit with other tools and want to keep owning.

The two paths differ in who controls the files on disk:

Uploaded assets live under UPLOAD_LOCATION and obey the storage template: Immich decides the folder layout and filename, moves files when you change the template, and treats deletion in the app as deletion on disk after the trash period.
External libraries are read only by design: you register a path such as /mnt/photos in the container, Immich indexes what it finds, generates thumbnails into its own directories, and never writes to or renames your originals.
External libraries need a rescan to notice changes: new files added by Lightroom, Syncthing or a NAS share appear after a scan job runs, either on the configured interval or when you trigger it manually, which is not the instant behaviour uploads give you.
Mobile backup always uploads: the phone app has no concept of an external path, so a mixed setup is normal, historic archive as an external library and new phone photos as uploads.
Duplicate risk is real if you do both with the same files: importing a Takeout with immich-go and also mounting that same folder externally gives you every asset twice, counted twice in storage reporting.

For a 20,000 file RAW archive averaging 25 MB, the external route is the safer first week choice: your originals stay where your backup script already finds them, and a mistake in Immich cannot rename or move 500 GB of files.

What does the Google Takeout format break, and how do you fix it before importing?

Takeout does not hand you a photo library. It hands you archives of files whose metadata has been moved out of the images and into JSON sidecars, and if you import them naively your entire timeline collapses onto the import date.

Dates and GPS live in sidecar JSON, not in the file: each media file gets a companion .json holding photoTakenTime and location, and Immich's plain upload path does not merge them, which is why so many first imports show 20,000 photos all dated today.
Sidecar filenames do not reliably match their media: Google truncates long names and appends counters like IMG_1234(1).jpg, so naive pairing by filename fails on a meaningful slice of any large export.
Edited copies arrive alongside originals: a file plus its -edited variant are two assets, which inflates your item count above what Google Photos showed you.
Albums are folders, not metadata: album membership is expressed by directory layout and an album JSON, so a plain folder upload gives you every photo and zero albums.
Live Photos are split: the still and the paired video land as separate files that need rejoining, not as one asset.

The fix is tooling, not manual cleanup. immich-go was written for exactly this: it reads the sidecars, rebuilds dates, recreates albums and pairs motion photos, and it can consume the Takeout zip files directly without you unzipping 100 GB first.

Import a single archive as a test run of a few hundred assets, confirm the timeline dates look correct, then delete those assets and run the full set. Discovering a date problem after 20,000 items means redoing all of it.

Which storage template should you set before the first upload?

Decide this before a single asset lands, because the template controls the on disk path of every uploaded file, and changing it later triggers a Storage Migration job that physically moves all 20,000 files.

Templates are built from variables such as {{y}}, {{MM}}, {{filename}} and {{ext}}, set in Administration, Settings, Storage Template. Four sane choices:

Template	Resulting path shape	Best for
Disabled, the default	Random directory and asset id under the user folder	People who will never touch the files outside Immich
`{{y}}/{{MM}}/{{filename}}`	`2019/07/IMG_1234.jpg`	Anyone who wants a browsable archive that survives Immich
`{{y}}/{{y}}-{{MM}}-{{dd}}/{{filename}}`	`2019/2019-07-14/IMG_1234.jpg`	Event heavy libraries where one day equals one shoot
`{{album}}/{{filename}}`	`Corsica 2019/IMG_1234.jpg`	Album driven workflows, with the caveat that assets in no album fall back

The default is genuinely defensible. Random paths never collide and never break when you rename an album. The argument against it is portability: if Immich is your only index, a corrupted database leaves you with a directory of meaningless filenames.

Two hazards. Filename collisions inside the same folder get a numeric suffix, so {{y}}/{{filename}} on a phone that resets its counter will produce IMG_0001_1.jpg. And the template applies to uploaded assets only, never to external libraries, which keep their original paths untouched.

Pick a year and month layout unless you have a specific reason not to. It is readable, it sorts, and it means a plain file browser can still make sense of your archive years from now.

Which machine learning model should you choose on day one?

This is the setting with the harshest change penalty. Smart search stores one embedding per asset, and embeddings from different models are not interchangeable, so switching models invalidates all 20,000 of them and forces a full re-run of the Smart Search queue.

The choice lives in Administration, Settings, Machine Learning Settings, and the models are pulled from the Immich Hugging Face collection on first use.

The default CLIP model: shipped because it fits modest hardware, and on a 4 core box with no GPU it is the only option that finishes a 20,000 item library in hours rather than days.
Larger visual models: better at abstract queries like "birthday cake" or "snow on a mountain", at the cost of more RAM in the machine learning container and a longer queue, which is exactly the combination that triggers the OOM loop on a 4 GB host.
Multilingual models: the only way to search in a language other than English, noticeably heavier than their English only equivalents, and worth choosing on day one if your household does not think in English.
Facial recognition is separate: it runs its own detection and recognition models with their own concurrency, so you can keep faces enabled while leaving smart search off entirely.
Off is a valid answer: on a Raspberry Pi 5 or an N100, disabling smart search turns a week of queued jobs into a library that is fully browsable by date and album tonight.

Test with 200 assets before committing. Search for three things you would realistically look for, judge the results, then import the rest. Making that judgement after the full import costs you the entire queue again.

What should the video transcoding policy be, and what does it cost you?

Leave it on the default optimal policy unless you have a specific reason not to, then understand exactly what that policy is doing to your disk and your weekend.

Transcode policy	What it re-encodes	What it costs you
Don't transcode	Nothing	Zero extra disk, but clips your browser cannot decode simply will not play
Videos not in an accepted format	Only unsupported codecs and containers	The cheapest useful option, ideal for phone footage that is already H.264 in MP4
Videos higher than target resolution or not in an accepted format	The above, plus anything above the target resolution, 720p by default	The default, and the reason a 4K library balloons in processing time
All videos	Every clip regardless of source	Doubles your video storage and can run for days on 3,000 items

Three things decide the real cost. The target resolution, because raising it to 1080p produces larger transcodes but keeps quality your phone actually shot. The constant rate factor, where the default of 23 trades size against fidelity. And hardware acceleration, which is the difference between hours and days: Immich supports NVENC, QSV, VAAPI and RKMPP, enabled by adding hwaccel.transcoding.yml to your compose command and selecting the matching API in the settings.

The trap is that the original is always kept. Transcodes are additional files in encoded-video/, never replacements, so an aggressive policy costs storage on top of your originals rather than saving any.

If your video is mostly modern phone footage, switching to "videos not in an accepted format" before the first import can remove most of the transcoding queue entirely.

Where should you actually run Immich: NAS, mini PC, home server or hosted?

The hardware question is really a question about video and about who fixes it at 11 p.m. when the phone app stops backing up.

A consumer NAS, Synology or QNAP class: attractive because the disks are already there, but many models ship 2 GB or 4 GB of RAM shared with the NAS operating system, and their Celeron and ARM CPUs turn the transcoding queue into a multi day job. Check for a container station and free RAM before assuming it will work.
A mini PC, N100 or similar: the sweet spot for a first Immich server. Four cores, upgradable RAM, low idle draw, and Intel Quick Sync on board, which is the single change that collapses video processing time.
An old desktop or a home server: the most CPU per euro you will ever get, and the right answer if you already own one. The costs are electricity, noise and the fact that your library now depends on a machine with no redundancy.
A VPS or a managed personal server: removes the hardware problem and the port forwarding problem, and moves the storage question into a monthly bill, since 200 GB of block storage is a different line item than a 4 TB disk you buy once. Yundera is a managed Personal Cloud Server, built on CasaOS, where apps are installed from an app store in one click rather than assembled from compose files by hand, and each app is reachable on a public HTTPS subdomain via NSL.SH mesh routing.

Whatever you pick, the deciding number is free RAM, not disk. Disk you can add later. A 4 GB ceiling shared with three other containers is what actually stops a 20,000 item import.

Which day-one settings force a full re-run if you change them later?

Some Immich settings are free to change at any time. Five are not, and the difference is whether the change invalidates work already written to disk. On a 20,000 item library, each of these costs you the same hours you spent during the first import.

Setting	What changing it later triggers	Safe default for week one
Storage template	A Storage Migration job that moves every uploaded file on disk	Set it before the first upload, then leave it
Smart search model	All existing embeddings discarded, full Smart Search queue re-run	Pick the model you can afford to run, test on 200 assets
Preview and thumbnail size	Thumbnail Generation re-runs for every asset, old derivatives replaced	Accept the default unless you view photos on a 4K display
Transcode policy or target resolution	Every clip matching the new rule is re-encoded from the original	Decide by looking at what codecs your clips actually use
Facial recognition model	Face detection and recognition re-run, and people you named can need reassigning	Enable it once and do not switch models casually

Two settings that look scary and are not: UPLOAD_LOCATION can be moved if you move the directory and keep the structure intact, and job concurrency can be raised or lowered mid import with no penalty at all.

The practical rule is simple. Anything that changes how a derived file is generated forces regeneration of every derived file. Anything that changes scheduling or naming of the running system does not.

Write your five choices down before you import. Reviewing them takes 15 minutes. Discovering one was wrong in month two costs you another weekend of queued jobs.

ConvertX Hardware Requirements: How Much CPU, RAM and Disk Before Conversions Start Failing

John — Thu, 27 Aug 2026 07:06:17 +0000

ConvertX will install and run on a 1 vCPU, 1 GB virtual machine, and it will convert a 2 MB PNG to WebP in a second. That box will also kill a 4K video conversion, a 300 MB PDF and a large EPUB rebuild, usually with no visible error at all. The honest hardware floor for general use is 2 vCPU and 4 GB of RAM with 3 times your largest file free on disk, and the floor for routine video work is 4 vCPU and 8 GB. If your real workload is long video transcodes or 500 MB office documents, and you have no appetite for reading container logs, a hosted converter will fail less than a small self-hosted instance.

TL;DR by reader profile:

The occasional image converter, for example someone flattening HEIC holiday photos to JPEG once a month: self-host ConvertX on the smallest tier you have, because single image jobs finish in seconds and memory pressure never builds.
The document and ebook person, for example a researcher pushing DOCX and EPUB through Pandoc and Calibre weekly: self-host on 2 vCPU and 4 GB, because LibreOffice and Calibre are single threaded and want headroom rather than cores.
The video converter, for example a parent re-encoding phone clips to H.264 for a TV: budget 4 vCPU, 8 GB and a large scratch volume, or accept conversions measured in hours.
The privacy-driven user with sensitive files, for example someone converting bank statements and medical scans: self-host even on modest hardware, because the failure mode is a slow job, not a document sitting on a third party server.
The shared household or small team instance, for example five people with one link: treat concurrency as the real constraint, because two overlapping jobs on 4 GB will OOM before either one finishes.
The reader with no sysadmin appetite at all, for example someone who cannot read docker logs and does not want to: use a hosted converter for anything over 100 MB, because silent failure with no diagnosis is worse than a public upload you understand.

The central tradeoff is this: ConvertX moves your files off other people's servers, but it also moves every timeout, memory limit and disk exhaustion onto a machine you now have to size correctly yourself.

What happens inside ConvertX when you press Convert
What are the real hardware floors for ConvertX, tier by tier
The upload path: where large files die before ConvertX ever sees them
How do you tell an OOM kill from a timeout in ConvertX
Why does a ConvertX job finish with no output and no error
Scratch disk: the hidden multiplier on every ConvertX conversion
Concurrency in ConvertX: what breaks when two jobs overlap
Video and FFmpeg in ConvertX: the workload that decides your tier
Images and ImageMagick in ConvertX: pixel maths, memory limits and policy files
Documents, ebooks and LibreOffice in ConvertX: slow, single threaded, quietly fragile

What happens inside ConvertX when you press Convert

ConvertX is not one converter. It is a Bun web application that receives your upload, writes it to disk, then shells out to whichever command line tool handles that format pair. Understanding that chain is the whole hardware question, because the web layer costs almost nothing and the child process costs everything.

The upload lands on disk first: your file is written into the container's data volume before any conversion starts, so a 500 MB video occupies 500 MB before a single frame is encoded.
A converter binary is selected by format pair: FFmpeg for audio and video, ImageMagick and libvips for raster images, Inkscape and resvg for vectors, Calibre for ebooks, Pandoc and LibreOffice for documents, Assimp for 3D meshes. Each has its own memory behaviour and none of them know about the others.
The job runs as a child process, not inside the web server: ConvertX waits for that process to exit. If the kernel kills it, ConvertX sees a dead process, not an explanation.
The output is written beside the input: peak disk usage is input plus output plus whatever temporary files the tool creates, which for LibreOffice and Calibre is substantial.
Results persist until cleanup runs: AUTO_DELETE_EVERY_N_HOURS defaults to 24, so a day of conversions accumulates on the volume before anything is reclaimed.

The practical consequence: ConvertX itself idles at a few hundred megabytes. Your 8 GB requirement is not ConvertX, it is FFmpeg encoding 4K, or ImageMagick decompressing a 200 megapixel TIFF into an uncompressed pixel buffer. Size the box for the worst binary you will ever invoke, not for the web interface.

What are the real hardware floors for ConvertX, tier by tier

Pick your tier from the heaviest format you actually convert, not from the average one. The table below maps common hardware to what genuinely completes and what starts failing.

Tier	Completes reliably	Starts failing at
1 vCPU, 1 GB RAM	Single images under 20 megapixels, PDF to text, small Markdown and DOCX via Pandoc, audio transcodes	Any video over roughly 2 minutes, LibreOffice on large spreadsheets, two concurrent jobs of any kind
2 vCPU, 4 GB RAM	Batches of 20 photos, EPUB and MOBI via Calibre, 1080p clips under 5 minutes, most office documents	4K video, TIFF files over 100 megapixels, three or more overlapping users
4 vCPU, 8 GB RAM	1080p video at usable speed, 4K short clips, large PDF rasterisation, 2 to 3 concurrent jobs	Long 4K transcodes measured in hours, batch video, sustained multi user load
8 vCPU, 16 GB RAM	Feature length video, large batch image work, several simultaneous users	Little in practice, the constraint becomes disk throughput and patience

Disk matters as much as RAM. Reserve at least 3 times the size of your largest file, and remember that with AUTO_DELETE_EVERY_N_HOURS at its default of 24, a day of jobs stays resident.

Where that hardware lives is a separate decision. A self managed VPS, an always on home server, a NAS running Docker and a managed option all reach the same floors. Yundera is a managed Personal Cloud Server, built on CasaOS, that runs self-hosted apps as Docker containers on a server dedicated to the user. Whichever you choose, the tier table above is what decides whether a conversion finishes.

The upload path: where large files die before ConvertX ever sees them

Half of the "ConvertX is broken" reports are not ConvertX at all. The file never reached the container. Every layer between your browser and port 3000 has its own size ceiling, and most of them reject silently or with a generic 413.

Nginx caps uploads at 1 MB by default: client_max_body_size starts at 1m. Until you raise it, anything larger returns 413 Request Entity Too Large and ConvertX logs nothing, because no request arrived. Set it to a value above your largest file, or to 0 to disable the check.
Cloudflare's free proxy caps request bodies at 100 MB: if your domain is proxied through Cloudflare on a free plan, a 400 MB video cannot reach your server regardless of your own configuration. Grey clouding the record or using a direct hostname is the only fix.
Proxy read timeouts kill slow uploads: nginx defaults proxy_read_timeout to 60 seconds. A large file over a slow home uplink can exceed that before the body finishes.
Your upstream bandwidth is the real limit at home: a 10 Mbit upload link moves roughly 1.25 MB per second, so a 500 MB file takes over 6 minutes of held connection before conversion even begins.
Caddy and Traefik behave differently: Caddy applies no default body limit, so people migrating from nginx often see the ceiling vanish without understanding why.

Where you run the instance changes which of these you have to configure. A self managed VPS means editing the proxy yourself, a NAS exposes its own reverse proxy settings, and on Yundera each app is reachable on a public HTTPS subdomain via NSL.SH mesh routing. Test with a file at your true maximum size before trusting any of it.

How do you tell an OOM kill from a timeout in ConvertX

These two produce almost identical symptoms in the browser: a job that never completes. They need opposite fixes. More RAM does nothing for a timeout, and a longer timeout does nothing for an OOM kill. Diagnose before you resize.

Signal	Points to an OOM kill	Points to a timeout
Exit status in `docker logs convertx`	Process terminated by signal 9, container exit code 137	Process still running, or killed cleanly after a fixed interval
`docker inspect --format '{{.State.OOMKilled}}' convertx`	Returns `true` after the container itself dies	Returns `false`, the container is healthy
Host kernel log via `dmesg -T`	Contains "Out of memory: Killed process" naming ffmpeg, soffice or convert	Contains nothing at all
Browser behaviour	Connection stays open, then the job vanishes from progress	504 Gateway Timeout from the reverse proxy while the job continues server side
`docker stats` during the job	Memory climbs to the limit then the row disappears	Memory sits flat, CPU pegged at 100 percent on one core

The pattern worth memorising: an OOM kill is sudden and leaves kernel evidence, a timeout is patient and leaves the converter alive. A frequent surprise is a job that hits both, where FFmpeg keeps encoding for 40 minutes after the proxy already returned 504, so the output file appears later with no matching entry in your browser.

Add swap before you upgrade the tier. On a 4 GB box, 2 GB of swap turns some ImageMagick kills into slow but successful conversions. It will not save a 4K transcode, and a job that swaps heavily for 20 minutes is usually a signal that the tier is wrong rather than the configuration.

Why does a ConvertX job finish with no output and no error

This is the failure mode that drives people back to hosted converters. The job appears in the history, the status does not scream at you, and the download is either missing or a 0 byte file. ConvertX only knows what the child process told it, and command line converters lie about success constantly.

The converter exited 0 but wrote nothing: LibreOffice is the worst offender here. It returns success after refusing to convert a document it could not parse, so ConvertX records a finished job pointing at an empty file.
A stale LibreOffice profile lock: if a previous conversion was killed mid run, the leftover profile directory blocks the next invocation. The fix is restarting the container, which is why the same document fails five times then works after docker restart convertx.
Missing fonts or unsupported subfeatures: a DOCX with an embedded font, or a PDF using a CJK typeface the container lacks, converts to a page of blank boxes rather than an error.
The output was cleaned up before you fetched it: with AUTO_DELETE_EVERY_N_HOURS at 24, a job you started last night and downloaded this evening can be gone.
Disk filled mid write: the converter writes a partial file, then fails on the final flush. You get a truncated result and a job marked done.

Your only reliable diagnostic is docker logs convertx, ideally with --tail 200 right after the failure. If reading container logs to work out why a PDF came back blank sounds like a bad evening, that is a legitimate reason to keep a hosted converter for anything important.

Scratch disk: the hidden multiplier on every ConvertX conversion

RAM gets the attention, disk causes the outages. ConvertX needs room for the input, the output and whatever intermediate the converter invents along the way, all at the same moment. That peak is routinely 5 to 10 times the size of the file you uploaded.

Rasterising a PDF is arithmetic, not magic: one A4 page at 300 DPI in RGB is about 3508 by 2480 pixels, roughly 26 MB uncompressed. A 100 page document becomes around 2.6 GB of intermediate data before anything is written as PNG or JPEG.
Uncompressed video intermediates are enormous: a single 1080p RGB frame is 1920 by 1080 by 3 bytes, about 6.2 MB. At 25 frames per second that is 155 MB of scratch per second of footage if a lossless intermediate is produced.
Calibre and LibreOffice unpack before they convert: an EPUB or DOCX is a zip archive, and the expanded working directory plus embedded images can dwarf the original file.
Everything accumulates in the same volume: uploads, outputs and mydb.sqlite share /app/data. If you did not mount a named volume, all of it lands on the container layer and fills the host root partition instead.
Retention multiplies the total: at the default 24 hour cleanup, a day of 20 conversions averaging 200 MB in and 150 MB out holds roughly 7 GB before anything is reclaimed.

Check with df -h on the host and docker system df for volume usage, not by guessing from your upload sizes. A full disk produces truncated outputs rather than clean errors, so a 20 GB volume on a video oriented instance is a floor, not a comfortable allocation.

Concurrency in ConvertX: what breaks when two jobs overlap

ConvertX has no job queue that serialises heavy work. A batch upload of 12 files, or two people clicking Convert at the same moment, means multiple converter processes competing for the same cores and the same memory ceiling. This is the single most common reason a box that felt adequate suddenly fails.

FFmpeg claims every core by default: with no explicit -threads value it scales to all available CPUs. On 4 vCPU, two simultaneous encodes request 8 threads across 4 cores, so both run at roughly half speed plus context switching overhead, and neither finishes when you expect.
ImageMagick multiplies memory, not just time: each process holds its own pixel buffer. Two 100 megapixel TIFF conversions on a 4 GB box are not one job twice, they are two independent allocations racing the same limit.
LibreOffice does not like company: two soffice invocations contending for the same user profile directory produce one success and one job that returns nothing usable.
SQLite serialises writes: mydb.sqlite handles job records fine at household scale, but it is a single writer database, not something to plan a 20 user instance around.
The web interface stays responsive while everything else starves: Bun keeps serving pages, so the instance looks healthy while conversions crawl. Health checks tell you nothing here.

The practical control is Docker resource limits. Setting cpus: "3.0" and mem_limit: 6g on a 4 vCPU, 8 GB host leaves the operating system breathing room and makes the failure predictable rather than random. If your instance serves more than three people who convert video, plan for one job at a time and tell them so.

Video and FFmpeg in ConvertX: the workload that decides your tier

If you never convert video, ignore most of the hardware advice in this article and run ConvertX on whatever you have. If you do, video alone sets your tier, because encoding is the only workload here that saturates every core for a sustained period.

Source material	On 2 vCPU, 4 GB	On 4 vCPU, 8 GB
Audio only, MP3 to FLAC or WAV	Completes in seconds, no real load	Identical, the tier is irrelevant
1080p H.264 clip under 5 minutes	Completes, slower than realtime, tolerable	Completes comfortably, cores are the binding constraint
1080p H.264 to H.265	Encoding runs far slower than the equivalent x264 job, expect to leave it running	Usable, still the slowest common conversion
4K to 1080p, 10 minutes or longer	Frequently exceeds proxy patience and sometimes memory	Completes, but plan for an unattended run
Feature length or batch video	Not a realistic workload	Marginal, this is where you want 8 vCPU

Three facts explain the whole table. A 4K frame carries 8.3 million pixels against 2.1 million at 1080p, so the same encoder does roughly four times the work per frame. The x264 preset ladder from ultrafast to veryslow spans an enormous speed range at similar quality targets, and ConvertX exposes this through the FFMPEG_ARGS environment variable, so setting -preset veryfast is the cheapest tier upgrade available. Finally, the container has no GPU acceleration unless you explicitly pass a device through, so everything runs on the CPU.

Set FFMPEG_ARGS before you buy more vCPU. A preset change costs nothing and often moves a job from abandoned to finished.

Images and ImageMagick in ConvertX: pixel maths, memory limits and policy files

Image conversion looks harmless because the files are small. The decoded buffer is what matters, and that number has nothing to do with the size on disk. A 12 MB JPEG and a 12 MB PNG can consume wildly different amounts of RAM.

Work out the buffer, not the file size: ImageMagick is normally built at Q16, meaning 2 bytes per channel. RGBA at 16 bits is 8 bytes per pixel, so a 100 megapixel scan needs roughly 800 MB of memory before any processing begins. That alone explains most failures on a 1 GB box.
The pixel cache silently falls back to disk: when the memory limit is reached, ImageMagick starts using a disk backed cache rather than failing. The job still completes, hundreds of times slower, which is why one photo occasionally takes 20 minutes while its neighbours take 2 seconds.
policy.xml can refuse the conversion outright: Debian based images ship with the PDF, PS and EPS coders disabled. The giveaway in the logs is "attempt to perform an operation not allowed by the security policy". That is a policy decision, not a hardware problem, and adding RAM will never fix it.
The same file has a cheap path and an expensive one: ConvertX also bundles libvips, which streams in tiles rather than loading the full image. Where both can handle a format pair, the vips route uses a fraction of the memory.
Batches compound the buffer, not the file count: 20 photos at 24 megapixels is not 20 small jobs, it is repeated 400 MB allocations.

Check a suspicious file with identify -verbose before blaming the tier.

Documents, ebooks and LibreOffice in ConvertX: slow, single threaded, quietly fragile

Document conversion is the workload people assume is trivial and then cannot explain. It rarely triggers an OOM kill on 4 GB. It just takes far longer than the file size suggests, and it does not get faster when you add cores.

Which binary handles the job decides everything: Pandoc converting DOCX to Markdown or HTML is a text transformation that finishes almost immediately on any tier. The same DOCX to PDF goes through LibreOffice or XeLaTeX, which is a completely different order of cost.
LibreOffice pays a cold start on every single job: each conversion launches soffice in headless mode, which means loading an entire office suite before the first page is laid out. That fixed overhead dominates on small documents, so a 40 KB letter and a 4 MB report can take a similar time.
Layout is single threaded: repagination, table reflow and font metrics run on one core. A 4 vCPU box converts a large spreadsheet no faster than a 1 vCPU box, which is why upgrading the tier for document work is usually wasted money.
LaTeX routes run multiple passes: XeLaTeX processes a document two or three times to resolve the table of contents and cross references, so the wall clock is a multiple of one pass, not one pass.
Calibre scales with embedded images, not page count: a 600 page text only EPUB converts easily, while a 90 page illustrated PDF to EPUB decodes every image and needs far more headroom.

The useful move is choosing your target format deliberately. If HTML or Markdown will do, you avoid LibreOffice and LaTeX entirely and turn a minutes long job into a seconds long one.

Why Your Self-Hosted Stirling-PDF Container OOMs, Hangs or Returns a Broken PDF: 15 Anti-Patterns and Their Fixes

John — Tue, 25 Aug 2026 07:06:47 +0000

Stirling-PDF is not an unstable application. Almost every crash, hang and quietly mangled output traces back to one of fifteen decisions you made outside the app: an unbounded container, the wrong image variant, a reverse proxy that gives up after 60 seconds, or an OCR call with no language pack behind it. The Java process inside the container claims a default heap of 25 percent of visible RAM, office conversions serialise through a single background LibreOffice process, and every job writes scratch files to disk before it returns a single byte. Correct those four assumptions and most of the remaining catalogue stops happening.

TL;DR by profile:

The weekend homelab tinkerer (one N100 mini PC, roughly ten PDFs a week, merge and split only): run the ultra-lite image with a hard 1 GB container limit, because you never touch the two subsystems that consume memory.
The scan hoarder (a decade of paper, 40,000 pages, OCR every one of them): run the full image, mount a real tessdata volume with your languages, and process in batches of 50 pages or fewer, because OCR cost scales with page count and DPI, not file count.
The automation builder (an n8n or cron job calling the Stirling-PDF API unattended): add your own queue and set explicit timeouts on both sides, because the app accepts every concurrent request you throw at it and holds each one in memory.
The small team sharing one instance (four people behind a VPN, mixed office conversions): budget for LibreOffice serialisation and raise proxy timeouts before you raise CPU, because your bottleneck is a single conversion process, not cores.
The NAS owner (a box already running twenty other containers): set the memory limit and the temp volume first, because an unbounded Stirling-PDF job is the container most likely to evict your other services.

The central tradeoff is headroom against completion: every limit that stops Stirling-PDF from taking down its host also stops some legitimate large job from ever finishing.

What is actually failing when Stirling-PDF dies, and how do you confirm it in two minutes?
Anti-pattern 1 and 2: no container memory limit, and no JVM heap ceiling inside it
Anti-pattern 3 and 4: running the wrong image variant, then calling a tool it does not contain
Where does Stirling-PDF write its temporary files, and why does that fill your disk?
Why does OCR hang, fail outright, or return a file with no selectable text?
Anti-pattern 9 and 10: treating office conversion as fast, parallel and font-independent
Why does a large upload fail before Stirling-PDF ever sees the file?
Anti-pattern 12: reverse proxy timeouts shorter than the job you just started
Anti-pattern 13: compression and repair settings that return a valid file with wrong content
Anti-pattern 14: volume permissions, custom fonts and language packs mounted incorrectly

What is actually failing when Stirling-PDF dies, and how do you confirm it in two minutes?

Three different failures get reported as "Stirling-PDF crashed", and they need opposite fixes. Run docker inspect stirling-pdf --format '{{.State.ExitCode}}' and docker logs --tail 200 stirling-pdf before you change anything. The exit code alone separates two of the three cases.

Exit code 137, container killed by the host: the kernel OOM killer reclaimed the process because the container exceeded its cgroup memory limit, or the host ran out of RAM entirely. The application log ends mid-sentence with no stack trace, which is the giveaway. Confirm it with dmesg -T | grep -i oom on the host or docker inspect reporting OOMKilled: true.
A java.lang.OutOfMemoryError: Java heap space stack trace, container still running: the JVM hit its own heap ceiling while the container still had free memory. The web UI usually stays reachable and only that one job fails. This is the fix nobody applies, because the container looks healthy.
No error at all, the request just never returns: the job is running, but something between your browser and the app gave up first. A 504 after roughly 60 seconds points at the reverse proxy, not at Stirling-PDF.
HTTP 200 with a file that opens but is wrong: text vanished, fonts substituted, images blurred to unreadable. Nothing in the log marks this as an error, because from the application's point of view it succeeded.

The first two are memory problems, the third is a timeout problem, and the fourth is a settings problem. Diagnosing the wrong one costs you a weekend.

Anti-pattern 1 and 2: no container memory limit, and no JVM heap ceiling inside it

Docker applies no memory limit by default. A container-aware JVM with no -Xmx claims a maximum heap of 25 percent of the memory it can see, which is the host's total RAM when you set no limit. Both defaults are wrong for this workload, and they fail in opposite directions.

Configuration	What the JVM sees	What breaks
No `mem_limit`, no heap setting	25 percent of host RAM as max heap, on 8 GB that is 2 GB	The host runs out of RAM before the container does, and your other services get evicted first
`mem_limit: 2g`, no heap setting	512 MB max heap, calculated from the limit	`OutOfMemoryError` on a job the machine could easily have handled
`mem_limit: 2g`, heap raised to 1.5 GB	1.5 GB heap, 512 MB left for everything else	Exit 137 the moment a native helper process starts, because Ghostscript and Tesseract live outside the heap
`mem_limit: 4g`, heap capped at 2 GB	2 GB heap, 2 GB for native processes and page cache	Nothing, for a single-user instance

The subtlety that catches people out: capping the Java heap does not cap the container. LibreOffice, Ghostscript, Tesseract and qpdf are separate native processes. Their memory counts against the cgroup limit but never against -Xmx.

Set both, and leave the native processes at least as much room as the heap. Add JAVA_TOOL_OPTIONS=-XX:MaxRAMPercentage=50 rather than a fixed -Xmx, so the ratio survives a change to the container limit. Then watch docker stats stirling-pdf during your largest real job instead of guessing.

Anti-pattern 3 and 4: running the wrong image variant, then calling a tool it does not contain

Stirling-PDF ships as more than one image, and they are not interchangeable. Pulling latest because it sounds current, or ultra-lite because it sounds efficient, decides which of the 50 plus tools actually work at runtime. The UI still shows every button either way, which is why this fails so confusingly.

stirlingtools/stirling-pdf:latest-ultra-lite: core PDF manipulation only, so merge, split, rotate, reorder and metadata edits. No OCR, no LibreOffice, no Python. It is the right choice if you genuinely never convert or OCR, and the wrong choice the first time you try.
stirlingtools/stirling-pdf:latest: the standard build, with OCR and office conversion included. This is the default answer for most self-hosters, and the variant the rest of this article assumes.
stirlingtools/stirling-pdf:latest-fat: everything preinstalled, including the ebook and advanced HTML tooling that the standard image otherwise fetches at container start when you set INSTALL_BOOK_AND_ADVANCED_HTML_OPS=true. It trades disk for a container that starts ready and needs no outbound network on boot.
The tool you call but did not install: the request reaches the backend, the underlying binary is absent, and you get a generic failure rather than "this image cannot do that". Confirm with docker exec stirling-pdf which soffice tesseract before blaming your configuration.

Where you run it changes how much this bites. On a self-managed VPS, a home server or a NAS you pick the tag yourself in a compose file. Yundera is a managed Personal Cloud Server, built on CasaOS, that runs self-hosted apps as Docker containers on a server dedicated to the user, so the variant arrives already chosen by the packaged app. Either way, verify which binaries exist before you design a workflow around them.

Where does Stirling-PDF write its temporary files, and why does that fill your disk?

Every non-trivial operation is a file-on-disk pipeline, not an in-memory transform. The container writes scratch files under /tmp/stirling-pdf, hands them to Ghostscript, Tesseract or LibreOffice, and only then streams a result back to your browser. If you never mounted anything at that path, all of it lands on the container's writable overlay layer, on the same filesystem as your Docker root.

The multiplication nobody budgets for: an OCR pass rasterises every page, writes the image set, writes an intermediate PDF, then writes the output. Peak disk use is several times the input size, and it happens before you see any progress at all.
Failed jobs do not always clean up: a container killed at exit 137, or a request abandoned when you closed the tab, leaves its scratch files behind. Check with docker exec stirling-pdf du -sh /tmp/stirling-pdf after a week of real use.
The overlay layer is the worst possible target: it is slow, it counts against your Docker storage pool, and it disappears on docker compose down, taking any recoverable partial output with it.
Two fixes, different tradeoffs: mount a tmpfs sized at 1 GB or 2 GB for speed, accepting that a job larger than the tmpfs fails outright, or bind mount a real directory for capacity, accepting slower rasterisation on spinning disks.
Cleanup is configurable: the temp file management block in /configs/settings.yml controls the cleanup interval, the maximum age of scratch files and whether a sweep runs at startup. Set it once rather than adding a cron job.

This matters more on constrained storage than on a roomy VPS, whether that is a NAS volume, a home server SSD or a Yundera instance.

Why does OCR hang, fail outright, or return a file with no selectable text?

OCR is the most expensive thing this application does, and it is driven by option combinations most people pick at random. Three failures dominate: no language data present, the wrong OCR mode for the input, and a page count the container cannot chew through before something upstream gives up.

Language data comes first. Run docker exec stirling-pdf tesseract --list-langs. If your language is missing, OCR fails or produces nonsense, and mounting a volume at /usr/share/tessdata with the traineddata files you need is the fix, not a setting change.

OCR option	What it actually does	Where it bites
Force OCR	Rasterises every page, then layers recognised text over the image	Destroys existing vector text and searchable layers, and inflates output size on documents that were already digital
Skip text	Leaves pages that already contain a text layer untouched	Returns a file with no new selectable text on mixed documents, which reads as a silent failure
Clean and deskew preprocessing	Runs image correction before recognition	Adds a full extra image pass per page, so processing time rises on exactly the large scans you were already struggling with
Sidecar output	Writes recognised text to a separate file alongside the PDF	Doubles the scratch files per job, which matters if your temp mount is a small tmpfs

Cost scales with pages and resolution, not with file count. A 400 page scan at 600 DPI is a fundamentally different job from 40 pages at 200 DPI, even at similar file sizes. Batch large documents into chunks of 50 pages or fewer, run them one at a time, and treat any OCR job over a few minutes as something that needs a raised timeout rather than a retry.

Anti-pattern 9 and 10: treating office conversion as fast, parallel and font-independent

Converting DOCX, XLSX or PPTX to PDF does not happen in Java. Stirling-PDF hands the file to a headless LibreOffice process inside the container. That single detail explains both of this section's anti-patterns.

The first conversion after a container start is the slow one: the headless soffice process has to initialise before it can do any work. Measure your second conversion, not your first, or you will size the machine against a number you will never see again.
Conversions serialise, so more cores do not help: requests queue behind one conversion backend. Two users submitting large presentations at the same time do not each get half the speed, the second one waits. If office conversion is your bottleneck, raise your reverse proxy timeout before you add vCPUs.
A wedged soffice process blocks everything behind it: one malformed document can leave the backend stuck, and every later conversion times out while the rest of the application stays perfectly healthy. Check with docker exec stirling-pdf ps aux | grep soffice, and restart the container rather than debugging the document.
Missing fonts corrupt layout silently: the container ships a limited font set. A document written in Calibri or Cambria gets substituted glyphs, so line breaks move, tables overflow and page counts change. The output is a valid PDF that does not match the original, and nothing in the log calls this an error.
Fix fonts by mounting them, not by hoping: bind mount your TTF files into a directory under /usr/share/fonts, then confirm with docker exec stirling-pdf fc-list | wc -l. Carlito and Caladea are the metric-compatible stand-ins for Calibri and Cambria, and Liberation Sans covers Arial.

Why does a large upload fail before Stirling-PDF ever sees the file?

A 413 error, or a progress bar that reaches 100 percent and then dies, is almost never the application. Every layer between your browser and the container can refuse a body, and each one has a different default. The container logs stay empty, which is the clue: if Stirling-PDF had rejected the file, it would have said so.

Layer	Default body limit	What you see
nginx or nginx proxy manager	`client_max_body_size` defaults to 1 MB	HTTP 413 within seconds, no entry in the Stirling-PDF log at all
Caddy or Traefik	No request body limit by default	Nothing, these two are rarely the culprit unless you added a buffering middleware yourself
Apache httpd	`LimitRequestBody` defaults to unlimited	Nothing, unless a distribution config or a hardening guide set it for you
Cloudflare proxied hostname	100 MB per request on the free plan	HTTP 413 from Cloudflare's edge, with a Cloudflare branded error page rather than your own
Stirling-PDF itself	A multipart upload limit in `/configs/settings.yml`	A clean application-level rejection that does appear in the log

Diagnose it by bypassing the chain. Send the same file directly to the container port with curl -F "fileInput=@big.pdf" http://localhost:8080/... from the host. If that works and the browser does not, the problem is in front of the app, and no amount of container tuning will fix it.

Raise the limits in order, from the outermost layer inward, and raise them to the same value. A proxy that accepts 500 MB in front of an app that accepts 50 MB just moves the failure one hop later, after the user has already spent the upload time.

Anti-pattern 12: reverse proxy timeouts shorter than the job you just started

A 504 after roughly a minute, on a job you know takes longer, is a proxy default and nothing else. The container never stopped working. It is still rasterising pages while your browser shows an error page.

nginx gives up after 60 seconds: proxy_read_timeout and proxy_send_timeout both default to 60s, which is shorter than almost any real OCR or large office conversion. Raise them to 300s or 600s in the location block for Stirling-PDF, not globally.
Cloudflare cuts the origin off at 100 seconds: a proxied hostname on the free plan returns error 524 when the origin has not responded in time, and you cannot raise that on the free plan. Long jobs behind an orange cloud need a different path to the app, such as a VPN or a direct hostname.
Caddy and Traefik do not impose a short default here: if you use either and still see a timeout, look at the client, at Cloudflare, or at an explicit middleware you configured yourself.
The retry is what actually kills the container: the abandoned job keeps running and keeps its memory. Clicking the button again starts a second copy of the same work, so peak memory doubles, and the container that was surviving one job gets killed at exit 137 running two. This is why "it broke worse when I tried again" is such a common report.
A timeout is not a substitute for batching: raising the ceiling to 600s makes a long job possible, but a job that needs 600 seconds should be split. Confirm the real duration by timing it against the container port directly, with the proxy out of the picture, before you decide which number to set.

Anti-pattern 13: compression and repair settings that return a valid file with wrong content

This is the failure class with no error message. The request returns 200, the PDF opens, and the damage only surfaces weeks later when someone needs the original. Compression, flattening, repair and sanitisation all rewrite the document structure, and several of them discard data by design.

Aggressive compression downsamples images, permanently: the optimisation levels run from light restructuring to heavy image resampling. On a scanned invoice, a high level can drop resolution below the point where the text is legible, and there is no undo. Test one representative document at each level before you apply anything to a batch.
Targeting an output size lets the tool decide how much to destroy: asking for a specific final size hands the algorithm permission to resample as far as it needs to. Set a level you have tested instead of a size you hope for.
Flattening converts form fields into static content: an interactive form becomes a picture of a form. Entered data is preserved visually, but the fields are gone, and any workflow that reads field values downstream stops working.
Repair rewrites the file structure and can drop what it does not understand: bookmarks, annotations, attachments and tagging are the usual casualties. Repair is for files that genuinely fail to open, not a routine step.
Any rewrite invalidates a digital signature: compress, repair, flatten, sanitise or even a metadata edit breaks the cryptographic seal. If a document is signed, it leaves the pipeline untouched.
Verify instead of trusting the 200: compare page counts and extracted text between input and output with pdfinfo and pdftotext from poppler-utils, and run qpdf --check output.pdf. Keep the original file until that comparison passes.

Anti-pattern 14: volume permissions, custom fonts and language packs mounted incorrectly

Two mount mistakes account for most of the "I followed the guide and it still does not work" reports. Both look correct in the compose file.

Mounting an empty host directory over a populated container path hides what was already there: bind mount an empty folder at /usr/share/tessdata and the traineddata files shipped in the image vanish, including English. OCR that worked before your fix stops working after it. Copy the existing contents out first with docker cp stirling-pdf:/usr/share/tessdata ./tessdata, then mount that directory back.
The same trap applies to fonts: mounting your font collection at /usr/share/fonts replaces the container's entire font tree. Mount a subdirectory such as /usr/share/fonts/truetype/custom so the bundled families survive alongside yours.
Docker creates missing bind mount sources as root: if the host path does not exist when the container starts, Docker makes it owned by root:root. An app running under a non-root user then fails to write, and configuration changes made in the UI silently do not persist across a restart.
Check the identity before you chase the permission: run docker exec stirling-pdf id to see which UID the process actually uses, then docker exec stirling-pdf ls -ln /configs to compare it against the ownership of the mounted directory. The numbers either match or they do not, and that answers the question in five seconds.
Set PUID and PGID to your own account, not to 0: running as root to make a permission error go away leaves every file the app writes owned by root on your host, which becomes your problem the first time you try to back up or move the data directory.

Hubs Community Edition backup and restore: what npm run backup captures, what it misses, and how long recovery takes

John — Sat, 22 Aug 2026 07:06:26 +0000

The bundled scripts in Hubs Community Edition back up two things: the PostgreSQL database and the Reticulum file store that holds uploaded GLB scenes, avatars, thumbnails and room media. They do not back up your hcce.yaml, your TLS material, your DNS records, your Kubernetes cluster or your object storage credentials, and if you point Hubs at an external database instead of the bundled Postgres pod, the scripts fall back to backing up the Reticulum files only. That means npm run restore-backup is not a disaster recovery plan on its own: it is the last step of one, and everything before it is a rebuild you have to be able to perform from your own notes. Plan for a restore that is a fresh install plus a data load, and time it once so you know the real number instead of a hoped-for one.

TL;DR by reader profile:

Small agency hosting client worlds (a four person studio running six separate client instances): keep the scripts, but wrap them in per instance archives with your hcce.yaml and secrets stored beside each archive, because a client asking for their world back is a per instance restore and not a cluster restore.
Solo operator running one instance (a single lecturer hosting seminar rooms on one VPS): the built in backup plus a nightly filesystem snapshot of the node is enough, because your recovery target is the whole box and not a selective extraction.
Team using an external managed Postgres (a studio on a hosted database with automated point in time recovery): treat the two halves separately, because the scripts stop covering the database the moment it leaves the bundled pod and your restore must line up two independent timelines.
Team with heavy scene libraries (a studio with hundreds of client uploaded GLB files): budget your restore window from file store size and disk throughput, because the database restores quickly and the assets dominate the clock.
Team facing a domain or host migration (a move to a new provider or a new client domain): rehearse the restore on a scratch host first, because room URLs, the Reticulum host configuration and certificate issuance all have to be corrected before anyone can join a room.

The central tradeoff: the built in scripts are simple and cover the data that actually matters, but they assume you can rebuild the surrounding installation by hand, so the effort you save at backup time is effort you pay back, under pressure, at restore time.

What does npm run backup actually capture in Hubs Community Edition?
What does the Hubs backup script silently miss?
Where does Hubs store rooms, avatars and uploaded GLB scenes on disk?
How long does a full Hubs restore actually take?
How do you run npm run restore-backup without breaking existing room URLs?
Should you back up the Hubs Postgres database separately from the Reticulum file store?
What changes when you run Hubs against an external database instead of the bundled pgsql pod?
Which Hubs secrets, certificates and configuration files must be saved outside the backup archive?
How much disk space does a year of Hubs backups need?
Snapshots, scripts or object storage: which backup strategy fits a Hubs instance?
How do you test a Hubs restore before you actually need it?
What breaks when you restore Hubs onto a different domain or a different host?

What does npm run backup actually capture in Hubs Community Edition?

Run npm run backup from your Hubs Community Edition checkout and you get a single timestamped archive, named in the data_backup_1234567890123 pattern, containing two payloads and nothing else.

The PostgreSQL database, dumped from the bundled pgsql pod: this is the record of every room, its title, its permissions, its owner account, its scene assignment and the metadata rows that point at uploaded files. Lose it and your GLB files still exist on disk but no longer belong to any room.
The Reticulum file store: the uploaded assets themselves, meaning GLB scenes exported from Spoke, custom avatars, room thumbnails, images, audio and video that people dropped into rooms. This is the part that grows without limit and dominates the archive size.
Nothing about your cluster or your configuration: hcce.yaml, your Kubernetes state, your certificates and your DNS live outside the archive and are your responsibility to version elsewhere.
Nothing about the state of the services at the moment of the dump: the archive is a data snapshot, not a running system image, so a restore always lands on a freshly installed instance.

The matching command is npm run restore-backup data_backup_1234567890123, and calling npm run restore-backup with no argument restores the most recent archive it finds. Where the instance runs shapes the rest of the plan: a self managed VPS, a home server, a NAS and Yundera are all viable homes for the surrounding stack. Yundera is a managed Personal Cloud Server, built on CasaOS, that runs self-hosted apps as Docker containers on a server dedicated to the user. Whichever you pick, the archive stays the same two payloads.

What does the Hubs backup script silently miss?

The word to notice is silently. The script does not warn you about the gaps, it simply finishes, prints a path and leaves you feeling covered. Six things are outside it.

Your hcce.yaml: this file carries your domain, your admin email, your subdomain layout and the deployment options that make the instance yours. Restore the data onto a default configuration and you get a working Hubs that is not your Hubs.
Secrets and keys: the Reticulum secret key base, the Perms keypair used to sign room join tokens, the cookie signing salt and any OAuth or email credentials. Regenerating the Perms keypair invalidates tokens that clients already hold, so sessions and pending invites break.
TLS certificates and the cert-manager state: a fresh install reissues through Let's Encrypt, which means the restore is gated on DNS pointing at the new host and on rate limits, not on your archive.
The k3s cluster itself: node configuration, storage class, persistent volume definitions and any manual kubectl edits you made months ago and forgot.
External object storage and CDN configuration: if you moved uploads off local disk, the bucket credentials and the bucket contents are not in the archive at all.
Email, TURN and third party settings: SMTP relay credentials and Coturn configuration decide whether people can receive invites and connect through restrictive networks.

Test the gap cheaply. Run npm run backup, extract the archive to a scratch directory and list what came out. Everything you expected but cannot find is now an item on a second backup job, ideally a git repository holding hcce.yaml and an encrypted secrets file.

Where does Hubs store rooms, avatars and uploaded GLB scenes on disk?

Two places, and knowing which is which decides what you can recover selectively later.

PostgreSQL holds the structure, not the bytes: the Reticulum schema carries tables such as hubs for rooms, accounts for identities, scenes and avatars for published assets, and owned_files for every upload. A row in owned_files records the owner, the content type and the identifier, while the actual file sits elsewhere.
The Reticulum storage volume holds the bytes: GLB scenes exported from Spoke, avatar GLBs, room thumbnails, images, PDFs, audio and video are written into a fanned out directory tree, each upload stored as a data file paired with a small metadata file. The names are identifiers, not human readable titles, which is why a file only means something when the database row that points at it survives too.
Derived media is cached, not authored: image resizing and video transcoding produce output that can be regenerated, so it is worth excluding from a tight recovery target and rebuilding after the fact.
The volume is a Kubernetes persistent volume claim: run kubectl get pvc in your Hubs namespace to see the claim and its size, and kubectl exec into the Reticulum pod to measure the tree with du -sh before you plan any window.

Where that volume physically lives depends on the host you chose, whether a self managed VPS, a home server, a NAS or Yundera. The split matters because the database is small and fast to move, while the storage volume is the part that grows every time a client uploads a scene.

How long does a full Hubs restore actually take?

Nobody can hand you a single number, because the archive is dominated by whatever your clients uploaded. What you can do is decompose the clock into five stages, measure each once on your own hardware, and turn the total into a promise you can actually keep.

Restore stage	What dominates the clock	How to shorten it
Provision the host and install k3s	Provider provisioning time plus package downloads	Keep a prebuilt image or a scripted node setup instead of typing it fresh
Deploy Hubs from `hcce.yaml`	Container image pulls for Reticulum, Dialog, the client and Postgres	Pre pull images on the standby host, or host them in a local registry
Issue TLS and point DNS	DNS propagation plus Let's Encrypt issuance, both outside your control	Lower the record TTL before a planned migration, not during an incident
Load the database dump	Row count in `hubs`, `accounts` and `owned_files`, usually the smallest stage	Nothing needed, this is rarely the bottleneck
Copy back the Reticulum file store	Archive size divided by disk and network throughput, the largest stage by far	Restore assets from storage that is already close to the new host

Measure it with time npm run restore-backup data_backup_1234567890123 on a scratch instance, then add the stages the script does not cover. Two rules follow. First, the file store sets your recovery time objective, so track its growth with du -sh monthly. Second, quote clients a window built from a real rehearsal, not from the script's runtime alone.

How do you run npm run restore-backup without breaking existing room URLs?

A Hubs room URL is built from the room identifier stored in the hubs table, so the URLs survive a restore for free as long as the database rows come back unchanged and the domain in front of them stays the same. What breaks them is everything you do around the restore.

Restore onto a fresh install, never onto a used one: bring up Hubs from hcce.yaml, then restore before anyone creates a room or publishes a scene. New activity writes rows that the incoming dump will collide with or overwrite, and the reconciliation is manual.
Keep the domain identical at restore time: put the same value in hcce.yaml that the archive was taken under, restore, verify, and only then perform a domain change as a separate, deliberate step.
Quiesce the services first: scale the Reticulum deployment to zero with kubectl scale, run the restore, then scale back. Restoring underneath a running Reticulum means live processes hold state that no longer matches the database.
Name the archive explicitly: run npm run restore-backup data_backup_1234567890123 rather than the bare npm run restore-backup, because the no argument form picks the most recent archive it finds and that is rarely what you want during an incident.
Verify before announcing: open one known room URL, one published scene and one custom avatar. Three checks catch the common failure, which is a database restored without its matching files.

The host underneath, a self managed VPS, a home server, a NAS or Yundera, does not change this sequence, only how quickly you can stand up the replacement instance.

Should you back up the Hubs Postgres database separately from the Reticulum file store?

For a single instance you can run npm run backup on a schedule and stop thinking about it. For anything larger, split the two, because they have opposite shapes: the database is small and changes every time someone creates a room, while the file store is large and mostly append only.

Dimension	One combined archive	Database and files backed up separately
Sensible cadence	Whatever the slowest half tolerates, usually nightly	Database hourly, files daily or on change
Storage growth	Every run copies the full file store again	Files deduplicate through incremental tooling, dumps stay small
Tooling	The bundled scripts only	`pg_dump` plus restic, borg or rsync against the storage volume
Recovery granularity	All or nothing, back to the archive time	Roll the database to one point, the files to another
Operational cost	One command, one cron entry, one thing to forget	Two jobs, two retention policies, two things to monitor

The practical rule is the loss window. If your clients publish scenes weekly but create rooms daily, an archive that repeats 40 GB of unchanged GLB files every night buys you nothing except a bigger bill. Dump the database hourly, back the storage volume up incrementally, and keep one full combined archive weekly as the known good fallback that needs no tooling to read.

Split backups carry one obligation: always restore the file store first and the database second, so no row can reference an asset that is not on disk yet. Write that ordering into the runbook, because it is the step people improvise wrongly under pressure.

What changes when you run Hubs against an external database instead of the bundled pgsql pod?

One thing changes and it is the important one: the backup scripts stop covering half your data. With an external database configured, npm run backup and npm run restore-backup handle the Reticulum files only. Nobody prints a warning. You simply get a smaller archive.

You now own the database backup outright: either your provider's automated snapshots and point in time recovery, or your own scheduled pg_dump against the Hubs database. Whichever you pick, it belongs in a runbook next to the file archive, not in your head.
You have two timelines to reconcile: a database recovered to 02:00 and a file archive taken at 03:00 leaves an hour of owned_files rows pointing at assets the file store does not have. Restore the files first, then roll the database forward to a point at or before the file archive, never after.
Credentials become a recovery dependency: the connection string, user and password live in your hcce.yaml and secrets, so losing those means the data survives while access to it does not.
Migrations still run on boot: Reticulum applies its schema migrations when it starts, so a database restored from an older instance can be upgraded by a newer deployment without you asking. Restore onto the same version you backed up from and upgrade deliberately afterwards.
The bundled pod stays simpler for small instances: one archive, one timeline, one restore command, at the cost of the operational features a managed database gives you.

Choose the split deliberately, then write down which system owns which half.

Which Hubs secrets, certificates and configuration files must be saved outside the backup archive?

Sort every item into two buckets before you build the vault: things that can be regenerated on the new host, and things that change behaviour for users if they are regenerated. Only the second bucket is a real backup obligation.

Item	Preserve or regenerate	Where it belongs
`hcce.yaml`	Preserve, it defines your domain, subdomains and admin email	A private git repository, committed on every change
Perms keypair and Reticulum secret key base	Preserve, regenerating invalidates issued room tokens and signed cookies	Encrypted secrets file, sops with age or your password manager
External database credentials	Preserve, the data is useless without access to it	Same encrypted store as the keys, never in the same archive as the dump
SMTP, OAuth and Coturn credentials	Preserve, they come from third parties and cannot be recreated locally	Encrypted store, with the provider account noted beside them
TLS certificates	Regenerate, cert-manager reissues after DNS points at the new host	Nothing to keep, but record the issuer and DNS provider steps
Derived Kubernetes secrets	Regenerate from the two entries above during deployment	Nothing to keep, they are outputs

Capture the live state once with kubectl get secret -n hubs -o yaml so you can see exactly what your instance holds rather than trusting this list. Encrypt that export immediately, because it contains plaintext values.

One discipline makes the whole thing work: the encrypted secrets store must be recoverable without the Hubs instance. If your only copy of the vault key lives on the server you are restoring, you do not have a backup, you have a circular dependency.

How much disk space does a year of Hubs backups need?

Work it out from two measurements rather than a guess. Get the current storage volume size with du -sh inside the Reticulum pod, then take two archives a month apart and subtract to get your monthly growth. Everything else is arithmetic on those numbers.

Full copies multiply, so count them first: a grandfather, father, son policy of 7 daily, 4 weekly and 12 monthly archives is 23 retained copies. With the bundled script, each one contains the whole file store, so the year costs roughly 23 times your current storage size plus the accumulated growth. This is the number that surprises agencies.
Incremental tooling changes the multiplier, not the base: because GLB scenes and avatars are written once and rarely modified, deduplicating backups with restic or borg store close to one copy plus the new uploads, so 23 restore points cost far less than 23 full archives.
Database dumps are rounding error: pg_dump output for room, account and owned_files rows compresses well and stays small next to the assets, which is why hourly database backups are affordable while hourly file archives are not.
Derived media inflates the total without adding value: transcoded video and resized images can be regenerated, so excluding them from the archive shrinks every copy for the whole year.
Off site copies double whatever you decided: the 3-2-1 rule means one primary, one local secondary and one remote, so budget the total twice, not once.

Set retention against a real number. A client that publishes a scene weekly needs different depth than one that uploaded once and never returned.

Snapshots, scripts or object storage: which backup strategy fits a Hubs instance?

Three approaches exist and they solve different failures. Pick by asking what you expect to lose: the whole machine, the data inside it, or the provider account holding both.

Provider or filesystem snapshots of the node: these capture the entire k3s host, so recovery is a rollback rather than a rebuild, and your hcce.yaml, secrets and certificates come back with it. They fail you in two ways: they usually live in the same provider account as the server, and they restore everything or nothing, which is useless when one client wants one room recovered.
The bundled scripts alone: npm run backup is portable, understandable and independent of any provider feature, which makes it the archive you can still read in three years. It covers the two data payloads and nothing around them, so it needs a companion job for configuration and keys.
Incremental backups to object storage: restic or borg pushing the Reticulum storage volume and pg_dump output to an S3 compatible target such as MinIO or Backblaze B2 gives deduplication, encryption at rest and an off site copy in one tool. The cost is a second system to monitor, plus a restore that now depends on network throughput.
The hybrid most agencies land on: nightly snapshots for fast whole host rollback, weekly bundled archives as the provider independent fallback, and continuous incremental pushes off site for the 3-2-1 requirement.

The choice is not about which tool is best. It is about which of the three failures you consider most likely, and whether your recovery needs to be selective.

How do you test a Hubs restore before you actually need it?

Build a scratch instance on a throwaway subdomain, restore last night's archive into it, and check five things by hand. Repeat quarterly and after every version upgrade, because an untested archive is a hypothesis.

Use a separate domain, never the live one: set a value such as hubs-drtest.example.com in the scratch hcce.yaml. Restoring production data onto production DNS during a drill is how a test becomes an outage.
Join a room and check presence works: open a restored room URL in two browsers and confirm audio and video connect. This exercises Dialog and Coturn, which a database check alone never touches.
Load a published GLB scene, not just the room list: rooms that open with a missing environment are the signature of a database restored without its matching file store, and the room index looks perfectly healthy in that state.
Load a custom avatar and a room thumbnail: avatars and thumbnails are separate owned_files rows, so they fail independently of scenes and prove the file tree copied completely rather than partially.
Time each stage and write the number down: run the drill with a stopwatch, record the total, and give clients that figure rather than an estimate. The number moves as the file store grows.

Finish by destroying the scratch instance and any DNS records it created, so nobody stumbles into stale rooms months later. Keep a one page log of every drill: the date, the archive name, the elapsed time and what broke. Three entries in that log tell you more about your recovery position than any amount of configuration review.

What breaks when you restore Hubs onto a different domain or a different host?

A different host alone is uneventful: the archive is portable and the deployment is rebuilt from hcce.yaml, so a move between a self managed VPS, a home server, a NAS or Yundera changes little beyond throughput. A different domain is the one that hurts, because the old hostname is written into places the restore script does not touch.

Stored absolute URLs: rows created under the old domain can carry fully qualified asset and scene URLs. After a domain change, query the database with psql for the old hostname before you assume the restore was clean, and update what you find.
Links your clients already shared: room URLs printed in emails, calendar invites and slide decks point at the old host. Keep the old domain resolving with a redirect for at least one full booking cycle rather than a fixed number of days.
OAuth and email: third party callback URLs and the sending domain in your SMTP configuration are registered against the old hostname and reject the new one until you update both providers.
TURN and media: Dialog and Coturn advertise addresses derived from your deployment configuration, so audio and video can fail while the room list looks perfectly healthy.
Certificate issuance order: DNS must point at the new host before cert-manager can complete a challenge, so the sequence is DNS first, deploy second, restore third.

Do the domain change as its own step, after a same domain restore has been verified. Two changes at once means any failure gives you two suspects instead of one.

Duplicati Block Size, Remote Volume Size and Retention: How to Choose Them for Your Data Shape

John — Thu, 20 Aug 2026 07:06:24 +0000

Pick your Duplicati block size from the total size of the source data, not from the number of files in it, and pick your remote volume size from your upload link and your storage provider's request pricing. The 100 KB block size and 50 MB remote volume defaults are sized for a laptop with a few hundred gigabytes, and they are the single most common reason a large job ends up with a multi gigabyte local database and a database recreate that runs for hours. Block size is fixed at job creation and cannot be changed later without starting a new backup chain, so this is the one decision you get exactly one chance at. Retention is the setting you can change freely at any time, which is why it should be the last thing you tune, not the first.

TL;DR by data shape:

Laptop and document sets (Maya, 80 GB of text, code and PDFs): keep the 100 KB default block size and the 50 MB remote volume, because the block count stays low enough that the local database and the recreate never become a problem.
Millions of small files (a Nextcloud data directory, 600 GB across roughly 4 million files): raise the block size to 1 MB and the remote volume to 200 MB, because per file overhead and block count, not raw bytes, are what inflate the database here.
Photo and video libraries (a 2 TB Immich library of HEIC, JPEG and MP4): use 1 MB blocks and 200 MB to 250 MB volumes with a version count retention, because the files are already compressed, almost never change after import and deduplicate poorly.
Multi gigabyte VM images (six qcow2 files, 900 GB total, backed up nightly): use 1 MB or larger blocks and 500 MB volumes with a time based or smart retention, because the churn inside large files is what drives both upload volume and compaction traffic.
Slow or metered upstream (a 10 Mbit/s home link, or a provider that bills per request): shrink the remote volume back toward 50 MB for restart tolerance, or grow it to cut request counts, and accept that you cannot optimise for both at once.
Restore time is the priority (a business file server with an agreed recovery window): favour smaller remote volumes and fewer retained versions, and back up the local database itself, because a recreate from remote data is the slowest path back.

The central tradeoff is simple: larger blocks and larger remote volumes keep the local database small and the recreate survivable, while smaller blocks and smaller volumes save upload bandwidth on small changes and make single file restores cheaper.

What do Duplicati's block size, remote volume size and retention policy actually control?
Why block size is locked in on the first backup run
How many blocks can the local database carry before it starts to hurt?
Millions of small files: which block size and remote volume size to choose
What should you change for a photo and video library?
A handful of multi gigabyte VM images: the settings that matter most
How big should the remote volume size be for your upload link and your provider?
What does the local SQLite database cost you in disk, RAM and backup time?
Keep all, keep versions, keep time or smart retention: which one fits your data shape?
How much post backup verification should you actually pay for?

What do Duplicati's block size, remote volume size and retention policy actually control?

These three settings sit at different layers of the same pipeline, and confusing them is why so many jobs end up misconfigured.

Block size (--blocksize, default 100 KB): the unit of deduplication. Duplicati splits every source file into blocks of this size, hashes each one with SHA-256, and stores the hash in the local database. A 600 GB source at 100 KB produces roughly 6 million blocks, and every one of them becomes a row you carry forever.
Remote volume size (--dblock-size, default 50 MB): the unit of upload and download. Blocks are packed into compressed, AES-256 encrypted .dblock.zip.aes files of this size before they leave the machine. It has no effect on deduplication quality, only on how many objects your provider stores and how much you must re-download to reach one block.
Retention policy (--retention-policy, --keep-versions, --keep-time): which restore points survive. It deletes .dlist files, the per version file lists, and marks the blocks they alone referenced as wasted space.
Compaction threshold (--threshold, default 25%): the link between the two. When wasted space in the remote volumes passes 25%, Duplicati downloads partially obsolete volumes, repacks the live blocks and uploads new ones.

Block size is permanent per job. Remote volume size applies to volumes created after you change it, so old and new sizes coexist. Retention and threshold can be edited on any run with no penalty. That ordering, permanent to free, is the order in which you should think about them.

Why block size is locked in on the first backup run

The block size is written into the job when the first backup completes, and every .dblock and .dindex file in the destination assumes it. Change it later and Duplicati will not re-chunk what is already stored, because a 100 KB block and a 1 MB block of the same file share no hash and can never deduplicate against each other.

What actually happens if you edit it: newer versions of Duplicati refuse the change on an existing job, and older ones let you save a value that is silently ignored for the existing chain. Either way you do not get the setting you asked for.
The only real fix: create a new job pointing at an empty destination folder, run a full initial backup, then retire the old job once you are satisfied with a test restore from it.
What that costs you: a second full upload of the entire source, a second full copy of storage held during the overlap, and the wall clock time of your slowest link. On a 20 Mbit/s upstream, 1 TB takes over four days of continuous transfer.
Where the decision lives: on the machine running Duplicati, since the local job database and the --blocksize value belong to that installation, not to the destination.

That last point is why the hosting choice matters before the first run and not after. A self-managed VPS, a home NAS, an always on mini PC and Yundera are all reasonable places to run it. Yundera is a managed Personal Cloud Server, built on CasaOS, that runs self-hosted apps as Docker containers on a server dedicated to the user. Pick the host, then set the block size once.

How many blocks can the local database carry before it starts to hurt?

Block count, not gigabytes, is what the SQLite database tracks. Every block contributes a hash row, and every version contributes references to those rows. The arithmetic is fixed: source size divided by block size.

Source size and block size	Approximate block count	What it feels like in practice
100 GB at 100 KB default	1.0 million	Defaults are fine, recreate finishes in minutes
500 GB at 100 KB default	5.2 million	Backups still work, recreate becomes an evening job
900 GB at 100 KB default	9.4 million	Compaction and deletion queries slow noticeably
2 TB at 100 KB default	21 million	The common failure case, recreate can run for many hours
2 TB at 1 MB	2.1 million	Same data, one tenth the rows, back in comfortable territory

The practical target most Duplicati operators settle on is keeping a job under roughly 5 million blocks, and treating anything past 10 million as a warning sign. That is a heuristic, not an enforced limit. Nothing breaks at a threshold. What happens instead is that every operation touching the block table gets slower in proportion: the delete step after a retention rule, the compaction pass, the verification query at the end of a run, and above all the recreate.

Two extra multipliers catch people out. Retained versions add rows for changed blocks, so a job holding 60 versions carries far more than a job holding 10 of the same source. And a single job covering several unrelated directories pools all of that into one .sqlite file. Splitting one 2 TB job into three smaller jobs gives you three databases that each fail and rebuild independently.

Millions of small files: which block size and remote volume size to choose

This is the shape where raising the block size helps least and still needs doing. A 20 KB file is one block whether your block size is 100 KB or 1 MB, so a Nextcloud data directory of 4 million files across 600 GB does not shed 90% of its rows the way a VM job does. The database cost here comes from per file bookkeeping: each file carries an entry plus a separate metadata block for its permissions and timestamps.

Set --blocksize to 1 MB anyway: the large minority of files in a mixed user directory, the videos, the archives, the mail stores, is where the block count actually accumulates. Cutting those by a factor of ten is worth it, and it costs nothing on the files that were already single block.
Set --dblock-size to 200 MB: at 50 MB, 600 GB of source becomes over 12,000 remote objects before any versioning. At 200 MB it is closer to 3,000, which cuts list and request operations on providers that bill per request.
Filter aggressively before tuning anything: thumbnail caches, .thumbnails, preview directories, node_modules and application temp folders often account for a third of the file count and none of the restore value. Exclusion filters remove rows permanently, which no block size can.
Split the job by directory: one job per top level user folder gives you separate .sqlite databases, separate schedules and separate recreates.
Leave --small-file-max-count at 20: raising it makes compaction merge more undersized volumes per run, which adds download traffic on a job that already has plenty to do.

What should you change for a photo and video library?

A photo library is write once data made of already compressed bytes, and both facts change the tuning. HEIC, JPEG, MP4 and MOV files are entropy dense, so deduplication finds almost nothing and the zip step spends CPU to save single digit percentages.

Use 1 MB blocks and 200 MB to 250 MB remote volumes: a 2 TB library at the 100 KB default generates tens of millions of blocks for data that will never deduplicate against itself, which is pure database cost with no return.
Drop --zip-compression-level from the default 6 to 0 or 1: on a directory of JPEG and MP4 you are paying full compression CPU on every upload for a ratio close to 1.0. Setting it to 0 stores the blocks and lets the AES-256 encryption still apply normally.
Exclude the regenerable directories: in an Immich deployment, thumbs and encoded-video are derived from the originals in upload and can be rebuilt by the application. In a Photoprism setup, the sidecar and cache folders are the equivalent. These often hold 15% to 30% of the total bytes.
Keep few versions, not many: photos are added, not edited. A --keep-versions of 3 or 5 covers accidental deletion and a bad import, and holding 30 versions of a library that never changes retains almost nothing new while adding .dlist files to every operation.
Expect compaction to stay idle: because old blocks are rarely superseded, wasted space climbs slowly and the 25% threshold may never trigger for years. That is the desired outcome here, not a sign something is broken.

A handful of multi gigabyte VM images: the settings that matter most

Large images invert the problem. File count is trivial, block count is enormous, and every nightly run rewrites regions scattered through a file that never changes size. Block size here is a direct bandwidth decision.

Block size on 900 GB of qcow2	Blocks in the job	Upload when 1 GB is rewritten in scattered 100 KB regions, worst case
100 KB default	9.4 million	About 1 GB, finest possible granularity
500 KB	1.9 million	Up to 5 GB, five times the changed bytes
1 MB	940,000	Up to 10 GB
2 MB	470,000	Up to 20 GB, database is smallest

Real guest workloads cluster their writes, so the true figure sits well below those worst cases. Still, the shape is clear: past 1 MB you buy database comfort with upload volume, every single night.

Start at 1 MB and only go higher if recreate time is your actual pain: 940,000 blocks is comfortable, and going to 2 MB halves rows you were already happy with while doubling the worst case transfer.
Set --dblock-size to 500 MB: with images this size the object count matters more than restart granularity, and a failed upload retries one volume, not the job.
Snapshot before reading: set --snapshot-policy=required so Duplicati uses VSS on Windows or LVM on Linux. Backing up a running qcow2 file without a snapshot produces a crash consistent image at best.
Exclude swap and scratch disks: a 16 GB swap file changes completely every day and restores no value.

How big should the remote volume size be for your upload link and your provider?

Remote volume size is the one setting you can revise later, so tune it to the link and the bill rather than to the data shape. Volumes created after the change use the new size, and old ones keep theirs until compaction repacks them.

Match the volume to a tolerable retry: an interrupted upload restarts that whole volume, and Duplicati retries 5 times with a 10 second delay by default. On a 10 Mbit/s upstream, roughly 1.25 MB/s, a 50 MB volume takes about 40 seconds and a 500 MB volume takes about 6.7 minutes. On a flaky link, the shorter unit wins.
Count objects when your provider bills per request: Backblaze B2 class C transactions and S3 PUT and LIST calls are priced per operation, not per byte. Moving from 50 MB to 500 MB cuts object count by a factor of ten for the same data.
Budget temporary disk space: with --asynchronous-upload-limit at its default of 4, Duplicati can hold five volumes on local disk at once. At 500 MB that is 2.5 GB in the temp directory, which matters on a small VPS root filesystem.
Remember what a single file restore costs: to recover one 100 KB block, Duplicati downloads the entire volume containing it. Large volumes make targeted restores expensive in egress and in time.
Keep block size at least 100 times smaller than volume size: 1 MB blocks in 200 MB volumes is a healthy ratio. 1 MB blocks in 10 MB volumes wastes the packing entirely.

What does the local SQLite database cost you in disk, RAM and backup time?

Each job keeps one database, named with a random string such as KJHGFDSAQW.sqlite, in the Duplicati config directory: %LOCALAPPDATA%\Duplicati on Windows, or the mapped /config volume in a container deployment. You can relocate it with --dbpath.

Disk grows with blocks multiplied by versions: every block row stores a base64 SHA-256 hash of 44 characters plus its size and volume reference, so the floor is tens of bytes per block before indexes. A job at 21 million blocks lands in a different order of magnitude to one at 940,000, which is the whole argument for block size in one line.
Deletions do not shrink the file: retention removes rows, but SQLite keeps the freed pages. Run a vacuum, or enable --auto-vacuum with --auto-vacuum-interval, otherwise the file stays at its historical high water mark forever.
RAM matters as page cache, not as a fixed requirement: if the database and its indexes fit comfortably in free memory, lookups stay in cache. If they do not, every hash check becomes a random read, and that is where a 2 GB container memory limit quietly turns a 40 minute backup into a multi hour one.
Storage medium is the biggest single lever: the workload is random reads and writes against indexes. Put the database on SSD or NVMe. Never put it on a spinning disk you also back up, and never on an SMB or NFS share, where SQLite locking behaviour causes corruption.
Temp space is separate: journal files and the sorting done during compaction land in the temp directory, not next to the database.

Keep all, keep versions, keep time or smart retention: which one fits your data shape?

Retention is the free setting. Change it whenever you like, and the next run applies it. Duplicati never deletes the most recent backup, whatever you configure.

Keep all backups: the right answer only for small, slow changing sources, such as a 5 GB configuration and document set. On anything with daily churn it means .dlist files accumulate forever, which is exactly what lengthens the first stage of a recreate.
Keep a specific number of backups (--keep-versions): predictable and shallow. A photo library at --keep-versions=5 holds five restore points regardless of when they were made, which suits data that is added rather than edited. The weakness is a burst: five backups in one busy afternoon give you five restore points covering four hours.
Delete backups older than a time (--keep-time): a straight window, for example --keep-time=1Y on a document set. Good when the requirement is stated in months, poor when your schedule is irregular, since a quiet quarter can leave the window nearly empty.
Smart backup retention: the built in preset, equivalent to --retention-policy=1W:1D,4W:1W,12M:1M. It keeps one backup per day for a week, one per week for a month, one per month for a year. This is the sane default for nightly VM images and for mixed user data.
A custom policy string: the same syntax, tuned. 7D:1D,4W:1W,12M:1M,10Y:1Y extends the tail to a decade at one point per year, and U in place of a duration means unlimited. Write the shape you would actually restore from, not the shape that feels generous.

How much post backup verification should you actually pay for?

After every run, Duplicati downloads a sample from the destination and checks it. The default --backup-test-samples=1 means one volume set per run: one .dblock, its .dindex, and a .dlist. That default is cheap on 50 MB volumes and not on 500 MB ones.

Do the egress arithmetic before raising it: at 500 MB volumes and one sample per nightly run, verification alone pulls roughly 15 GB per month back down from the provider. Set --backup-test-samples=5 and it becomes about 75 GB per month, billed as egress on most object stores.
Prefer --backup-test-percentage on large sets: sampling a fixed 1% of volumes scales with the backup instead of staying flat, which is what you want on a job that grows from 200 GB to 2 TB.
Know what the default sample proves: it verifies the file is present, the right size and hashes correctly. Add --full-remote-verification to also decrypt and inspect the contents, at the cost of CPU on every checked volume.
Run a full test on a schedule, not on every backup: duplicati-cli test <destination-url> all --full-remote-verification checks the entire set. Monthly or quarterly is a reasonable cadence, and it is the only thing that catches silent rot in volumes the sampler never picked.
Turn on --upload-verification-file: it writes duplicati-verification.json beside the backup, which the bundled DuplicatiVerify script can check at the destination without downloading anything.
Never set --no-backend-verification to save money: you are then trusting a destination you have not read from since the day you wrote to it.

How Much Transcoding Headroom Does a Plex Server Really Need? Quick Sync vs NVENC vs CPU for 4K HDR

John — Tue, 18 Aug 2026 07:06:16 +0000

Size your Plex server for the streams that actually transcode, not for the number of people you host. A single Intel CPU with a recent Quick Sync engine, paired with a Plex Pass subscription so hardware transcoding and HDR tone mapping are unlocked, covers most small client rosters, because the majority of playback sessions on modern clients direct play and never touch the encoder at all. The expensive case is narrow and predictable: 4K HDR source, a client that cannot handle HEVC or HDR, and a bandwidth cap that forces a downscale, which is where tone mapping turns one session into the cost of several. If every client household runs an Apple TV, a recent Nvidia Shield or a current smart TV app, the GPU question mostly disappears and your budget belongs in storage and upload bandwidth instead.

TL;DR by reader profile

The agency with 6 to 10 client households on mixed hardware (you support whatever TV the client already owns): buy a CPU with an integrated Quick Sync engine and enable hardware transcoding plus HDR tone mapping, because mixed client hardware guarantees a steady trickle of forced transcodes you cannot predict per household.
The studio serving one or two clients on standardised players (every site got the same Apple TV): skip the discrete GPU entirely and spend on disk and upload, because standardised clients direct play almost everything and leave the encoder idle.
The archive-heavy shop with a 4K HDR remux library (Dolby Vision and HDR10 sources, 60 GB files): plan for GPU tone mapping from day one, because CPU only tone mapping collapses to roughly one usable session on hardware that handles several 1080p transcodes comfortably.
The team already running on rented infrastructure (a VPS or a managed personal cloud instance with no GPU passthrough): enforce direct play through client standards and library encoding rules, because software transcoding on shared vCPUs is the one configuration that fails loudest under concurrency.
The cost-controlled operator replacing a per-seat SaaS bill (you need a three year number before you buy): price the Plex Pass licence, the drives and the upload link together, because the server hardware is rarely the largest line in the total.
The remote-first roster (clients watching from outside your network on 20 Mbps uplinks): treat upload bandwidth as the real ceiling and configure per user stream limits, because a server that can encode 6 streams cannot deliver 6 streams through a link that only carries 2.

The central tradeoff: money spent on transcoding hardware buys tolerance for client devices you do not control, while money spent on standardising those client devices removes the need for the hardware in the first place.

What Plex is actually doing when a stream will not direct play
How much transcoding headroom does a client roster really need?
Direct play, direct stream and transcode: what each one costs your server
Why does 4K HDR tone mapping cost so much more than a plain 1080p transcode?
Quick Sync, NVENC or CPU only: which one fits your roster?
What does Plex Pass unlock, and what does the licence cost over three years?
How many concurrent 4K HDR sessions can one encoder realistically hold?
Where the bottleneck moves once the GPU is fast enough: disk, RAM and the transcoder temp directory
How do you make direct play the default and leave the encoder almost idle?
Subtitles, audio tracks and the other hidden transcode triggers

What Plex is actually doing when a stream will not direct play

Plex Media Server compares the file against what the client reports it can handle. Container, video codec, audio codec, resolution, bit depth, subtitle format and the bandwidth setting all get checked. If everything matches, the file is sent as bytes and the server does almost nothing. If one attribute fails, Plex rewrites the stream in real time, and the cost depends entirely on which attribute failed.

Container mismatch: the video and audio are copied into a new container without re-encoding, which is cheap and shows in the dashboard as direct stream rather than transcode.
Video codec or bit depth mismatch: a client that cannot decode HEVC Main 10 forces a full decode and re-encode to H.264, which is the expensive path and the one your hardware sizing exists to cover.
Audio codec mismatch: a TrueHD or DTS-HD track played on a stereo client is converted to AAC, costing a fraction of a video transcode but still occupying a session slot.
Bandwidth limit below the source bitrate: a client set to 8 Mbps against a 60 Mbps remux triggers a downscale even when the codec was supported, which is the most common surprise on remote sessions.
Burned-in subtitles: image based PGS or VOBSUB tracks cannot be passed through, so Plex renders them into every frame and forces a video transcode.

Open the Plex dashboard at http://your-server:32400/web during playback and read the session label. It states the reason in plain text, for example "Transcode (hw)" or "Direct Play", and that single string tells you whether your encoder is being used at all.

How much transcoding headroom does a client roster really need?

Count concurrent transcodes, not accounts. Ten client households sharing one server rarely produce ten simultaneous sessions, and the sessions that do overlap are mostly direct play. The number worth sizing against is peak simultaneous forced transcodes, which for a small roster usually sits between 2 and 4 on a weekday evening.

Start from peak concurrency, not library size: a 40 TB library serves the same load as a 4 TB one, because only the active sessions consume CPU or encoder time.
Apply the published Plex guidance for software transcoding: Plex documents roughly 2000 PassMark points per 1080p transcode and around 17000 points for a single 4K transcode, so a CPU scoring 12000 handles about 6 concurrent 1080p sessions and not one 4K session.
Assume a forced transcode rate rather than a worst case: if 20 percent of your sessions transcode, a peak of 10 sessions needs headroom for 2, and sizing for 10 buys hardware that idles every night of the year.
Add one slot of reserve for scheduled tasks: Plex runs library scans, thumbnail generation and intro detection in the background, and video preview thumbnails will saturate every core they are given.
Track the ceiling per client household, not per person: a family watching two rooms at once counts as two sessions, so a roster of 8 households can peak well above 8.

Set a hard cap in Settings, Transcoder, using the transcoder quality and maximum simultaneous video transcode fields. A refused stream is a support ticket. A server thrashing at 100 percent CPU is ten of them.

Direct play, direct stream and transcode: what each one costs your server

The three playback modes differ by an order of magnitude in what they demand from the machine, so knowing which one your roster lands in decides the hardware.

Playback mode	What the server does	Practical cost per session
Direct Play	Reads the file and sends the bytes unchanged	Disk read plus network, a few percent of one core
Direct Stream	Repackages into a new container, copies both codecs	Roughly one tenth of a video transcode, still cheap
Audio transcode only	Copies video, re-encodes TrueHD or DTS to AAC	A fraction of a core, but it holds a session slot
Software video transcode	Full decode and re-encode on CPU	Around 2000 PassMark points at 1080p, near 17000 at 4K
Hardware video transcode	Decode and encode on Quick Sync or NVENC	Low CPU, bounded instead by encoder engine capacity

This ordering matters when you choose where the server lives. A home server or a NAS can expose an integrated GPU to the container. A rented VPS usually cannot, which pins you to the software row and its PassMark arithmetic. Yundera is a managed Personal Cloud Server, built on CasaOS, that runs self-hosted apps as Docker containers on a server dedicated to the user, and it sits alongside a self managed VPS, a home server or a NAS as one of the places a Plex instance can run.

Whichever you pick, verify the mode in practice rather than on paper. A roster that direct plays 90 percent of sessions makes the bottom two rows almost irrelevant, and a roster that never does makes them the entire budget.

Why does 4K HDR tone mapping cost so much more than a plain 1080p transcode?

Three separate costs stack on top of each other in the same session, which is why one 4K HDR stream is not simply twice the work of a 1080p one.

Four times the pixels: 3840x2160 carries exactly 4 times the pixel count of 1920x1080, so decode and encode both scale up before any colour work starts.
10 bit instead of 8 bit: HDR sources are HEVC Main 10, so every frame moves through the pipeline at higher bit depth, which raises memory bandwidth and rules out some older fixed function decoders entirely.
The tone mapping pass itself: converting HDR10 or HLG to SDR is an extra per pixel colour transform inserted between decode and encode, and on CPU it runs in software with no fixed function silicon to fall back on.
A downscale on top: the client that could not handle HDR usually cannot handle 4K either, so the same session also resizes 2160p to 1080p, adding a scaling filter to the chain.
Dolby Vision profile handling: profile 5 and profile 7 sources are not plain HDR10, and depending on the source and client the result can be a fallback to the base layer or visibly incorrect colour, which is a correctness problem rather than a performance one.

Tone mapping in Plex is a Plex Pass feature, enabled in Settings, Transcoder, and it is worth confirming it is switched on before you blame the hardware. A washed out grey picture on a client is the signature of tone mapping being unavailable, not of an underpowered encoder.

Quick Sync, NVENC or CPU only: which one fits your roster?

All three paths need a Plex Pass licence before hardware acceleration appears in the settings at all. What separates them is capacity per watt, session limits and how easily the device reaches a container.

Encoder path	Fits which roster	Main constraint
Intel Quick Sync, integrated	Mixed client hardware, 2 to 4 concurrent transcodes	Needs `/dev/dri/renderD128` passed into the container
Nvidia NVENC, GeForce card	4K HDR heavy libraries, several tone mapped sessions	Driver imposed concurrent encode session cap, historically 3 on consumer cards
Nvidia NVENC, professional card	Large rosters where the cap is the blocker	Card cost dwarfs the rest of the build
CPU only, software	Standardised clients that direct play nearly everything	2000 PassMark per 1080p session, near 17000 for one 4K
Apple VideoToolbox on macOS	An existing Mac already acting as the server	Tied to hardware you are unlikely to buy for this purpose

Quick Sync is the default answer for a small agency because it arrives free with a CPU you were buying anyway, and it handles HEVC Main 10 decode plus tone mapping on recent generations. NVENC earns its place when the session cap matters less than raw throughput, or when the server has no integrated graphics at all.

CPU only is not a failure state. It is the correct choice when your clients direct play, and it is the only choice on most rented virtual machines. The mistake is buying a card first and discovering afterwards that the encoder sits at zero percent every evening.

What does Plex Pass unlock, and what does the licence cost over three years?

The licence is attached to the server owner's account, not to each viewer, so one subscription covers every household you host. That single fact changes the arithmetic for an agency: the per client cost of the licence falls as the roster grows.

Hardware transcoding: Quick Sync, NVENC and VideoToolbox acceleration are gated behind Plex Pass, so without it every forced transcode falls back to the PassMark arithmetic on CPU.
HDR tone mapping: the colour conversion pass covered earlier is part of the same gate, which means a Pass-less server plays 4K HDR to an SDR client washed out or not at all.
Remote playback for your users: playback from outside the server's network is tied to a paid plan, either the owner's Plex Pass or a Remote Watch Pass held by the viewer, which matters when every client household is remote by definition.
Operational extras: hardware accelerated video preview thumbnails, skip intro and credits detection, and download for offline viewing all sit on the same licence.

Plex sells the Pass as a monthly tier, an annual tier and a one time lifetime tier. Rather than quoting figures that shift, do the division yourself: divide the current lifetime price by the current annual price to get the breakeven in years. If that number lands below the 3 year horizon you are planning against, and the server is not an experiment you expect to abandon, the lifetime tier is the cheaper line. Check the current numbers at plex.tv before committing, because the tiers have been repriced before.

How many concurrent 4K HDR sessions can one encoder realistically hold?

There is no honest fixed number, because the answer moves with the source bitrate, the encoder generation, the number of encode engines on the die and whether tone mapping and scaling are both active. What there is, instead, is a threshold you can measure in an afternoon.

The speed multiplier is the real limit: the Plex dashboard shows each session's transcode speed. Anything above 1.0 means the server is producing video faster than it is being watched. A session sitting at 1.0 or below is buffering, and that is your ceiling regardless of what the CPU graph says.
Add sessions one at a time: start the heaviest 4K HDR file you host, note the speed, then start a second on another client, then a third. The session count at which any stream drops under roughly 2.0 is your safe working number, because that margin absorbs seeks and background scans.
Encode engines cap you before the shaders do: the tone mapping pass runs on the GPU's compute units, but the encode itself runs on fixed function silicon, and a card with one encode engine saturates that engine while the rest of the GPU idles.
Consumer driver caps apply before capacity does: on GeForce hardware the concurrent encode session limit can stop you at a count the silicon would otherwise handle comfortably.

Do this measurement on your own files, not on someone else's chart. A 60 Mbps Dolby Vision remux and a 25 Mbps HDR10 web release place very different loads on the same encoder, and your library only contains one of them in quantity.

Where the bottleneck moves once the GPU is fast enough: disk, RAM and the transcoder temp directory

Fix the encoder and the queue simply forms somewhere else. On a small roster the next three constraints are storage seeks, the metadata database and the scratch space Plex writes segments into.

The transcoder temporary directory: every transcode writes HLS segments to the path set in Settings, Transcoder, which defaults inside the container to /transcode. Point it at RAM with a Docker --tmpfs /transcode mount and budget memory per concurrent session, then watch actual usage before fixing the size.
The library database on spinning disk: com.plexapp.plugins.library.db handles constant small reads during browsing, and a 5400 rpm drive shared with playback makes the client UI feel broken while the video itself streams fine. Keep the config volume on an SSD and the media on bulk disk.
Seek contention across concurrent reads: 4 sessions pulling from one mechanical drive turn sequential reads into random ones, which shows up as buffering on direct play sessions that use almost no CPU at all.
RAM for background tasks: scans, thumbnail generation and tone mapped sessions all want memory at once, and a tmpfs scratch directory competes with them directly for the same pool.

Where you run the server decides how much of this you control. A NAS or home server lets you split SSD and bulk storage yourself, a VPS usually gives you one storage class, and a Yundera instance is another option in that same set, alongside a self managed VPS, a home server or a NAS.

Measure with docker stats and iostat during a real evening peak. Guessing at this layer wastes more money than the GPU choice did.

How do you make direct play the default and leave the encoder almost idle?

Every forced transcode is a client capability gap you can close once and stop paying for nightly. Four moves cover most of it.

Standardise the player, not the file: an Apple TV 4K or an Nvidia Shield TV Pro handles HEVC Main 10, HDR and most audio formats natively. Issuing the same box to each client household converts a permanent transcoding cost into a one time hardware cost, and it is the single change with the largest effect.
Set quality to Original on each client: in the Plex client under Settings, Video Quality, leaving remote quality at a bitrate cap forces a downscale even when the codec matched. Setting it to Original or Maximum removes the most common avoidable transcode, provided the connection can carry it.
Keep a compatibility encode for the awkward files: where a source is unusual, store an H.264 High profile 8 bit version alongside the original with an AAC stereo track. Plex offers multiple versions of the same item, and a browser or old smart TV picks the one it can play instead of asking the encoder.
Use SRT sidecar subtitles wherever possible: text subtitles are passed through, while image based tracks are burned in and force a full video transcode, so converting a library's subtitle strategy removes a whole class of load.
Audit per user quality limits: the server side setting under Settings, Users, caps a household globally. Check that no leftover 4 Mbps limit is quietly transcoding every session for a client on a fast link.

Direct play is a configuration outcome, not a hardware feature. Most rosters get there with client choices alone.

Subtitles, audio tracks and the other hidden transcode triggers

Video codec mismatches are the obvious cause. The awkward cases are the ones where the video was perfectly compatible and something small next to it forced a full re-encode anyway.

Hidden trigger	What Plex is forced to do	Cheapest fix
PGS, VOBSUB or styled ASS subtitles	Render text into every frame, forcing video transcode	Ship an SRT sidecar next to the file
7.1 TrueHD or DTS-HD MA on a stereo client	Downmix and re-encode audio, holding a session slot	Add a second AAC 2.0 track to the file
Dolby Atmos in EAC3 to an older receiver	Convert audio, sometimes drag video along on strict clients	Keep a plain AC3 5.1 track as fallback
Interlaced 1080i broadcast recordings	Deinterlace on top of the encode, raising cost per session	Deinterlace once during ingest, store progressive
H.264 above level 4.1 on constrained devices	Re-encode video that the codec name suggested was fine	Encode compatibility versions at level 4.1
MKV container on some browser clients	Remux to MP4, cheap but still a pipeline	Accept it, or store an MP4 version

The pattern is consistent. A file is not compatible or incompatible as a whole. It is a bundle of streams, and any one of them can force the expensive path while the other four were fine.

Audit this once per library rather than per file. Sort by subtitle format and audio codec, fix the two or three patterns that dominate, and a measurable share of your nightly transcodes disappears without touching the hardware budget.

Private Docusaurus: What Actually Gates the Site, and What Still Leaks Through sitemap.xml, Search and Source Maps

John — Sat, 15 Aug 2026 07:05:34 +0000

Docusaurus has no login, no user table and no server-side session, because a production build is a folder of static HTML, JavaScript and JSON that any web server can hand out. Every gate you add lives in front of it: HTTP basic auth, a forward-auth proxy, or an access rule on the static host. That gate is genuinely effective, since an unauthenticated request never reaches a single file. The real risk is not the gate failing, it is the build itself, because sitemap.xml, the prebuilt search index and unstripped source maps each contain a readable copy of what you thought you were hiding, so one misrouted path or one cached response leaks the whole set at once.

TL;DR by reader profile:

Family running a shared household wiki (passwords, router notes, insurance scans in a Docusaurus site on a home server): use a forward-auth proxy with real accounts, not one shared basic-auth password, because a single credential cannot be revoked for one person only.
Solo maintainer with a private notes site (one person, one laptop, one VPS): HTTP basic auth over HTTPS is proportionate, provided you disable the sitemap plugin and ship no source maps.
Small team with an internal handbook (8 to 20 people, staff turnover): forward auth against an identity provider, so account removal is one action and not a redeploy of a password file.
Consultancy under a client NDA (contract requires access logs and named users): forward auth plus per-request logging, since basic auth gives you no reliable identity in the access log beyond a shared username.
Open source project with a private staging site (public docs plus an unreleased version branch): keep the private content in a separate build entirely, because noIndex and unlisted pages hide pages from indexes, not from anyone who requests the URL.

The central tradeoff: basic auth costs one configuration block and no moving parts but gives you one shared secret and no revocation, while forward auth gives you named accounts, logout and audit trails at the cost of running an identity service that must stay up for anyone to read a single page.

What does Docusaurus actually serve, and why is there nothing to log into?
Where can you put the authentication gate in front of a Docusaurus build?
Is HTTP basic auth enough for a private Docusaurus site?
Basic auth against forward auth against static host rules: what each one costs
What ends up in the build folder that you did not expect to publish?
How much does sitemap.xml leak, and should you disable the plugin?
Does the prebuilt local search index expose the full text of your docs?
Are source maps in a Docusaurus production build a real risk?
Should unauthenticated visitors get 401, 403 or 404?
Which cache and CDN headers decide whether a private page gets stored publicly?
How do you keep drafts, unlisted pages and old doc versions out of the build?
What breaks in Docusaurus once it sits behind an auth proxy?
Which gate should each profile choose?
Self-hosting, hosting location and data sovereignty for a private Docusaurus site

What does Docusaurus actually serve, and why is there nothing to log into?

Run npm run build and Docusaurus 3.x writes a build/ directory. That directory is the entire application. There is no PHP process, no database connection string, no session store and no user table, so there is no code path where a password could be checked. The React you wrote is prerendered to HTML at build time and rehydrated in the browser, which means the server's only job is to return files.

What the build directory contains:

Prerendered HTML per route: every doc page exists as a complete index.html on disk, readable with curl and no JavaScript engine at all.
A client JavaScript bundle: the hashed assets/js/ files that hydrate the page, plus a runtime manifest listing every route the site knows about.
Static assets copied verbatim: anything you dropped in static/ is served at the site root, including PDFs and images you may have forgotten.
Generated metadata files: sitemap.xml from @docusaurus/plugin-sitemap, robots.txt, RSS and Atom feeds from the blog plugin, and search index JSON if you use a local search plugin.
No server-side configuration: docusaurus.config.js runs during the build, not at request time, so it cannot make an access decision about an incoming request.

The practical consequence is blunt. npx docusaurus serve and python3 -m http.server are equally unauthenticated, and so is Nginx, Caddy or an S3 bucket pointed at the same folder. Every access control you get comes from the layer in front of those files, never from Docusaurus itself.

Where can you put the authentication gate in front of a Docusaurus build?

There are four layers where a request can be stopped, and you should pick exactly one as the authoritative gate. Two overlapping gates usually mean one of them is misconfigured and nobody notices.

The web server that serves the files: Nginx auth_basic with an htpasswd file, or a Caddy basic_auth directive, checks credentials before it opens build/index.html.

A reverse proxy in front of that server: Traefik, Caddy or Nginx running auth_request against a forward-auth service such as Authelia or oauth2-proxy, which returns 200 or 401 for every path including /sitemap.xml.

The static hosting platform: Netlify password protection, Cloudflare Access or an S3 bucket policy, decided outside your repository and outside your build.

The network boundary: a WireGuard or Tailscale tunnel, where the site listens on a private address and no gate exists at HTTP level at all.

Where that stack physically runs is a separate decision: a rented VPS, a home server or NAS on your own connection, or a managed box. Yundera is a managed Personal Cloud Server, built on CasaOS, that runs self-hosted apps as Docker containers on a server dedicated to the user. On any of those, the gate still belongs to the proxy or web server, because Docusaurus contributes nothing.

One warning about the development server. npm start binds port 3000 with hot reload, no gate and no build step, and it happily serves your unfinished private pages to anything that can reach that port. Never expose it, even briefly, and never treat it as a preview environment for people outside the household or team.

Is HTTP basic auth enough for a private Docusaurus site?

For one person, yes. For a household or a team, it degrades badly, and the failure is social rather than cryptographic. Over HTTPS the credential is protected in transit, so the weaknesses are all about lifecycle.

The password is shared, so revocation is all or nothing: removing one person's access means changing the single entry in .htpasswd and telling everyone else the new password, which in practice nobody does.

Hashing depends on how you generated the file: run htpasswd -B -c /etc/nginx/.htpasswd alice to force bcrypt, because the default on older htpasswd builds is MD5 based crypt, and Nginx will accept both without warning you.

There is no logout: the browser caches the credential for the origin until the tab or the browser is closed, so a family laptop left open stays authenticated for anyone who picks it up.

Access logs give you no real identity: every request carries the same username, so a log line proves someone had the password, not who.

Automation gets awkward: any script, RSS reader or link checker now needs the credential embedded, and curl -u user:pass https://docs.example.com/sitemap.xml in a shell history file is a common way for it to escape.

Prompts confuse non-technical readers: the native browser dialog offers no branding, no password reset and no explanation, which generates support requests from the exact people you set the site up for.

Use basic auth when the reader count is 1 to 3 and stable. Above that, the shared secret becomes the weakest part of the system.

Basic auth against forward auth against static host rules: what each one costs

The three approaches differ less in strength than in what they demand from you every month after setup. Compare them on operational cost, not on theoretical security.

Approach	What it costs to run	Where it breaks
Web server basic auth (Nginx `auth_basic`, Caddy `basic_auth`)	One config block and one `.htpasswd` file, no extra process, no extra memory	Shared secret, no logout, no per-person revocation, credential leaks into scripts
Forward auth (Authelia or oauth2-proxy behind Traefik, Caddy or Nginx `auth_request`)	An extra container plus its config and session storage, and a second thing to upgrade	If the auth service is down, every page returns 401 or 502, including your own recovery notes
Identity provider SSO (Cloudflare Access, Google or GitHub OIDC)	No local user database, but a hard dependency on a third party for every page load	Your reader list lives outside your server, and access decisions are logged elsewhere
Network gate only (WireGuard, Tailscale)	Client software on every device, including phones and a television browser	No gate once a device is on the network, so a borrowed laptop reads everything
Static platform password (Netlify, Vercel)	Zero server administration	One password per site, and the build output sits on a shared multi-tenant platform

Your hosting choice cuts across this table rather than replacing it. A rented VPS, a home server, a NAS or a Yundera instance can each run any of the first four rows, since all of them are just containers and a proxy in front of a folder. Pick the row you will still maintain in twelve months.

What ends up in the build folder that you did not expect to publish?

Before you trust the gate, audit what is behind it. The reliable method is to grep the output rather than to reason about the config. Run grep -ri "your-secret-string" build/ after every build, and add it to your deploy script.

Anything in customFields: values you put under customFields in docusaurus.config.js are serialised into the client bundle so useDocusaurusContext() can read them, which means an internal API host or a support email is now a string in assets/js/.

Environment variables you inlined: only variables the build actually references get baked in, but once referenced they are literal text in the bundle, and a .env file loaded at build time is not a secret store.

Author and contributor metadata: authors.yml addresses, plus last update author and timestamp when showLastUpdateAuthor is enabled, expose real names and a work rhythm you may not want visible.

Files you forgot in static/: everything in that directory is copied to the site root untouched, so an old invoice PDF or a screenshot with a token in the URL bar ships with the site.

Broken link and draft residue: pages you unlinked from the sidebar are still built and still reachable at their route, because onBrokenLinks only checks links, not orphan pages.

Comments in your MDX: HTML comments in Markdown survive into the prerendered HTML, so a note like  is served verbatim.

None of this is a Docusaurus defect. It is a static site doing exactly what you told it to do, and the audit is yours to run.

How much does sitemap.xml leak, and should you disable the plugin?

@docusaurus/plugin-sitemap ships inside @docusaurus/preset-classic, so a default site publishes /sitemap.xml whether or not you asked for it. That file is a complete route inventory in plain XML. If your gate ever misfires on one path, an attacker does not have to guess URLs, because you handed over the full list in one request.

It enumerates every route, not every page you linked: orphan pages that no sidebar points at still appear, which is exactly the content people assume is hidden.

Route names carry meaning on their own: /docs/finance/mortgage-2029-refinance tells a reader most of what they wanted before they read a word of the page.

It is the first path any scanner requests: sitemap.xml and robots.txt sit at the top of every wordlist, so this is not an obscure corner of the site.

Blog feeds duplicate the problem: /blog/rss.xml and /blog/atom.xml include post titles and, depending on your feed options, the full body text.

Disabling it is one line: set sitemap: false in the preset-classic options in docusaurus.config.js, or use the plugin's ignorePatterns to exclude specific route globs while keeping a sitemap for a public subset.

For a fully private site, disable the sitemap and the blog feeds outright. You gain nothing from them, since no search engine should be crawling a gated site anyway. For a mixed site with public and private areas, do not rely on ignorePatterns as a security control, because it hides routes from a file, not from anyone who requests them directly.

Does the prebuilt local search index expose the full text of your docs?

Yes, and this is the leak people underestimate. Offline search plugins such as @easyops-cn/docusaurus-search-local build an index at compile time and ship it as static JSON in the build/ output, because the search runs in the reader's browser with no server involved. That index is not a list of keywords. Depending on the plugin's configuration it contains headings, section titles and enough surrounding body text to render a preview snippet.

One request returns the corpus: fetching the index file gives a reader the searchable content of every indexed page without visiting a single page URL.

It survives route level rules: if you blocked /docs/private/ at the proxy but left the index file open, the content of those pages is still in the JSON.

Check it yourself: run ls -la build/search-index*.json or grep the build output for a phrase that only appears on a sensitive page, then confirm which path serves it.

Hosted search moves the copy, it does not remove it: Algolia DocSearch keeps your content on Algolia's infrastructure, and the search-only API key travels in the client bundle, so a gated site with hosted search has published its text to a third party by design.

The safe configurations are narrow. Either gate the whole origin so the index file is behind the same 401 as everything else, or drop search entirely on the private portion and keep it for the public one. Splitting a mixed site into two builds is usually less work than proving that one index contains nothing sensitive, and it stays true after the next twenty pages get written.

Are source maps in a Docusaurus production build a real risk?

Lower than the search index, higher than zero, and the honest answer is that you should check rather than assume. Verify with grep -r sourceMappingURL build/ and find build -name "*.map". If both come back empty, this section costs you nothing. If they do not, decide what those files contain before you ship them.

A docs site leaks source, not documents: your page content is already in the HTML behind the gate, so a map mostly reveals JSX, not text a reader could not otherwise reach once authenticated.

Swizzled components are the exception: ejected theme components under src/theme/ often carry internal hostnames, feature flags and comments like a note about which client the layout was copied from.

Custom React pages carry logic: a src/pages/ component that calls an internal API embeds that endpoint, and the map restores the original variable names that minification had obscured.

Maps enlarge the transfer: .map files are typically several times the size of the minified bundle, which matters on a home connection serving a family from a residential upload link.

Third party maps come along for free: dependencies sometimes publish their own maps, so a clean project can still emit files you never wrote.

The control is the same either way. Configure configureWebpack in a small local plugin to set devtool: false for production, then re-run the two commands above to confirm. Do not rely on the proxy to block *.map by pattern, because a rule that lists extensions is one new file type away from being wrong, and generating nothing is simpler than filtering everything.

Should unauthenticated visitors get 401, 403 or 404?

The status code decides how much a stranger learns from a single request. It also decides whether your own tooling behaves, so pick deliberately rather than accepting the proxy default.

Response	What it tells an unauthenticated visitor	When it is the right choice
401 with `WWW-Authenticate: Basic`	A site exists here and it wants a password, and the browser shows the native dialog	Basic auth for 1 to 3 known readers who expect the prompt
302 to an identity provider	A site exists, plus the name of your login service in the redirect target	Forward auth, where readers need a real login form and a logout
403 with a static body	Something exists and you are not welcome, with no way to authenticate from the browser	Blocking a subset of paths for readers who are already logged in
404 for every gated path	Nothing here, which hides the site from casual scanners	Sites you want absent from view, at the cost of confusing legitimate readers

One Docusaurus specific detail matters. Your build contains build/404.html, a branded page with your site title and navbar. If the proxy passes unauthenticated requests through and lets Docusaurus answer, a stranger sees your site name and menu structure on what you thought was a blank refusal. Configure the error page at the proxy instead, and test with curl -i https://docs.example.com/nonexistent to see which layer answered.

Prefer 401 or a redirect for a household site. Silent 404s generate the phone call that starts with a family member insisting the link is broken.

Which cache and CDN headers decide whether a private page gets stored publicly?

A gate that returns the right page to the right person still fails if something between you and the reader keeps a copy. Docusaurus produces content-hashed filenames under assets/, which invites aggressive caching, and that default is written for public documentation sites.

Cache-Control: private: permits the browser to store the response but forbids any shared cache from doing so, which is the minimum for every HTML route on a gated site.

Cache-Control: no-store for HTML: prevents the response being written to disk at all, worth using on a shared family laptop where the browser profile is not per person.

Vary: Cookie or Vary: Authorization: tells intermediaries that the response depends on credentials, so a cached copy is not served to the next requester who lacks them.

CDN cache rules override your headers: Cloudflare and similar platforms can cache by file extension regardless of origin headers, so check the rule set rather than trusting Cache-Control alone.

Hashed assets are still content: an assets/js/ chunk contains prerendered strings from your pages, so caching it publicly leaks text even when the HTML route is protected.

Search engine caches are permanent enough: anything crawled while the gate was off can persist in third party copies long after you fix the configuration.

Verify with one command per route class: curl -sI https://docs.example.com/docs/intro | grep -i "cache-control\|vary", then repeat against a hashed asset path. If the two disagree, the asset is usually the one set to a long public lifetime, and that is the copy that outlives your mistake.

How do you keep drafts, unlisted pages and old doc versions out of the build?

The distinction that trips people up is between not built and not listed. Only one of them removes content from the folder a stranger could reach.

draft: true removes the page from production: a Markdown file with that front matter is skipped by npm run build while still appearing in npm start, so the route does not exist in the output at all.

unlisted: true keeps the page and hides the signposts: the page is built and served at its URL, excluded from the sidebar, sitemap and search index, and marked with a banner, which is obscurity rather than access control.

Underscore prefixes exclude by convention: the docs plugin ignores files and folders starting with _ by default, which is how partials stay out, and it works for a _scratch/ directory too.

exclude patterns give you explicit globs: set them in the docs or blog plugin options in docusaurus.config.js when a naming convention is not enough.

onlyIncludeVersions and includeCurrentVersion: false: versioned sites otherwise build every folder under versioned_docs/, so an internal draft of the next version ships alongside the released one.

Deleted content lives on in Git: removing a page from docs/ does not remove it from history, so anyone with repository access can read it even after the site stops serving it.

Audit the result rather than the intent. Run find build -name "*.html" | wc -l and compare it against the pages you expect, then spot check the paths you assumed were gone. A count that exceeds your mental model by twenty files usually means a versioned folder you forgot.

What breaks in Docusaurus once it sits behind an auth proxy?

A static site behind a gate hits problems no public docs site ever sees, and most of them appear only after a session expires rather than on the day you set it up.

Client side navigation fails silently: after the first page load, Docusaurus fetches JSON and JavaScript chunks for the next route, so an expired session returns a login redirect where a chunk was expected and the reader gets a blank pane or a chunk load error instead of a prompt.

baseUrl and proxy paths must agree: if the proxy mounts the site at /docs/ but docusaurus.config.js still sets baseUrl: '/', every asset resolves one level wrong and the page renders unstyled.

trailingSlash causes redirect loops: a proxy rule that appends a slash while the config strips it, or the reverse, produces a cycle that ends in a browser error rather than a 401.

Hosted search stops working: the Algolia crawler cannot reach a gated site, so DocSearch returns nothing and you must move to a local index or drop search.

Link previews disappear: Slack, Discord and Signal unfurl by fetching the URL unauthenticated, so a shared link shows the login page title or nothing.

The PWA plugin can cache the wrong response: a service worker that stores a 302 or a login page will keep serving it after you fix the session.

External CI link checkers fail: any pipeline step that crawls the published site needs credentials, and embedding them there recreates the leak you closed.

Test the expiry path deliberately: log in, wait for the session to lapse, then click an internal link.

Which gate should each profile choose?

Profile	Recommendation	Main reason
Family of 4 sharing household records	Forward auth with one account per adult	Revoke one person without changing everyone's password
Solo maintainer, private notes	Basic auth with a bcrypt `.htpasswd`	One reader, no lifecycle problem to solve
Team of 8 to 20 with staff turnover	Forward auth against an existing identity provider	Offboarding is a directory change, not a redeploy
Consultancy under an NDA	Forward auth plus per-request access logs	The contract needs named users, not a shared secret
Mixed public and private docs	Two separate builds on two hostnames	One index and one sitemap per audience, no path rules to get wrong
Technical household, all devices managed	Network gate via WireGuard or Tailscale	No HTTP credential to leak, at the cost of client setup on every device
Site with an existing CDN in front	Gate at the CDN, then lock the origin	Two gates on different layers drift apart and one goes stale

Next steps by branch:

Choosing basic auth: generate the file with htpasswd -B, set Cache-Control: private on HTML, disable the sitemap, confirm with curl -i that an unauthenticated request returns 401.
Choosing forward auth: stand up the auth service first, protect a throwaway path, verify the expired session path in a browser, only then point it at the docs host.
Choosing two builds: split the content directories, give each its own docusaurus.config.js, and grep the private build for a phrase that must never appear in the public one.
Choosing a network gate: install clients on every device that will read the site, including phones, before you remove any HTTP level gate.

Self-hosting, hosting location and data sovereignty for a private Docusaurus site

A private wiki is a pile of plain files, so the question of who else can read them is decided by where the disk sits and who administers it. A static build makes this unusually clear: there is no vendor database holding your content, only a directory.

Advantages of keeping the build on your own server:

No third party copy of the text: the content never leaves your disk, unlike hosted search or a platform preview environment.
The access log belongs to you: you can see who requested /docs/finance/ and keep or delete that record on your own schedule.
Jurisdiction follows the hardware: a box in the country you live in avoids questions about cross border data transfer for family documents.
No platform build step: nothing needs read access to your Git repository, which is where the unreleased and deleted pages live.
The gate is yours to configure: proxy rules, session lifetime and status codes are all under your control rather than a provider's defaults.

You can run this on a rented VPS, a home server, a NAS, or a managed box. Yundera is a managed Personal Cloud Server, built on CasaOS, where each app is reachable on a public HTTPS subdomain via NSL.SH mesh routing, so no static IP, no port forwarding and no manual TLS certificate setup are required. A public hostname makes the gate more important, not less, since anyone can reach the door.

Pre-publication checklist:

Confirm the origin is not reachable directly, bypassing the proxy.
Verify TLS covers every hostname the site answers on.
Back up build/ and the content repository separately, and test one restore.
Record who holds administrative access to the server and to the auth service.

Jellyfin Buffering With 3 or 4 Family Streams: The Setup Mistakes That Cause It, and How to Fix Each One

John — Thu, 13 Aug 2026 07:06:33 +0000

Almost every "Jellyfin cannot handle four people at once" problem is a transcoding problem, not a bandwidth or server power problem. If your CPU pins at 100% with three or four viewers, the server is re-encoding video in software because hardware acceleration is off, the GPU is not visible inside the container, a subtitle track is being burned in, or a remote client asked for a lower bitrate than the file. Fix the transcode path and the same hardware that choked on two streams will usually carry four or more. The work is configuration, not new hardware, and you can verify each fix from the Jellyfin dashboard in minutes.

TL;DR by household setup:

One 4K TV in the living room, everything else on phones (a couple with an Apple TV and two iPhones): enable hardware acceleration and keep a second 1080p copy of your most watched films, because the phones will never direct play a 4K HDR remux.
Two parents plus two teenagers streaming to different rooms at the same time (a four person house on one server): set per user bitrate limits and enable hardware decoding and encoding first, since concurrent software transcodes are what saturates the CPU.
Grandparents watching remotely over a home upload link (one remote viewer, one local): cap the remote user's bitrate in the user policy and accept a deliberate transcode, because unlimited remote playback of a 40 Mbps file will stall on most residential upload speeds.
A mini PC or NAS with Intel integrated graphics (an N100 or a recent Synology or Beelink box): pass /dev/dri into the container and turn on Intel QuickSync, because that single change moves the encode off the CPU entirely.
An old desktop with a dedicated NVIDIA card (a repurposed tower in the basement): use NVENC and check the concurrent session limit on consumer cards, since driver level caps, not the GPU itself, decide how many streams you get.
A family that mostly watches on browsers and smart TV apps (mixed Chromecast, Fire TV and laptop viewing): standardise on H.264 or widely supported HEVC with AAC audio, because container and audio mismatches trigger transcodes even when the video codec is fine.

The central tradeoff is simple: every gigabyte of disk you spend on client friendly copies of your media is CPU and GPU work you never have to do while four people are watching.

Why does Jellyfin hit 100% CPU when only three or four people are watching?
How do you tell whether a Jellyfin stream is direct playing, remuxing or transcoding?
Anti-pattern 1: hardware acceleration left off, or switched on but never verified
Which transcoding path fits your server: Intel QuickSync, NVIDIA NVENC, AMD VAAPI or software?
Why does the GPU never reach your Jellyfin Docker container?
Anti-pattern 2: keeping one 4K HDR file as the only copy for every screen in the house
Why do subtitles turn a smooth Jellyfin stream into a full video re-encode?
Anti-pattern 3: leaving remote family accounts with no bitrate ceiling
Anti-pattern 4: pointing the Jellyfin transcode cache at the wrong disk
Which audio codecs and containers quietly force your family's clients to transcode?

Why does Jellyfin hit 100% CPU when only three or four people are watching?

Serving a file costs almost nothing. Re-encoding it costs everything. When Jellyfin direct plays, the server reads bytes off disk and pushes them to the client, which is disk and network work that a ten year old CPU handles for a dozen viewers at once. When Jellyfin transcodes in software, it decodes every frame and re-encodes it with libx264 or libx265, and that single stream will use every core you give it. Three concurrent software transcodes on a four core CPU is not a load problem, it is an impossible request.

What actually consumes the CPU: the software encoder, not the number of sessions. One 4K HEVC to 1080p H.264 software transcode can occupy a modern desktop CPU on its own, which is why the second viewer arrives to buffering.

Why it looks like a bandwidth problem: transcoding cannot keep ahead of playback, so the client empties its buffer and pauses, exactly the symptom a slow network produces.

Why it starts at three streams and not one: the first transcode uses spare headroom, the second consumes it, and the third queues behind both.

Why your hardware is probably fine: an Intel CPU with QuickSync, or any GPU with a dedicated encoder block, offloads the work to fixed function silicon and leaves the general purpose cores idle.

Why the trigger is often invisible: a subtitle track, an audio codec or a client bitrate cap flips a session from direct play to transcode without anyone changing a setting.

Run top or htop during playback. If ffmpeg sits at the top, you have found your answer.

How do you tell whether a Jellyfin stream is direct playing, remuxing or transcoding?

Stop guessing and read the session. Open Dashboard while someone is watching: each active device shows the playing method under the title, along with source and output bitrates. On the client side, the Jellyfin web player exposes the same data through the Playback Info entry in the player menu. That one screen tells you whether the server is copying bytes or rebuilding frames, and Jellyfin also prints the trigger, in plain language, such as "The audio codec is not supported".

Playing method	What the server does	What it costs you
Direct Play	Sends the original file untouched, container and all streams intact	Disk reads and network only, negligible CPU, scales to many viewers
Direct Stream (remux)	Repackages the same video into another container, video bitstream copied	Low CPU, a few percent, output bitrate stays equal to the source
Audio transcode only	Copies the video, re-encodes the audio track to AAC or similar	Small and constant CPU cost, safe to run several at once
Video transcode	Decodes and re-encodes every frame at a new resolution or bitrate	The expensive case, and the one that pins cores when several run together

Two habits make this permanent. First, check the source and output bitrate pair in the session card: identical numbers mean no video re-encode, a drop from 38 Mbps to 8 Mbps means one is happening. Second, keep jellyfin.log open in a second window during a test playback, because the transcode reason is recorded there for clients that hide the overlay.

Anti-pattern 1: hardware acceleration left off, or switched on but never verified

The default install has hardware acceleration set to None. Every transcode is software until you change it, so a brand new Jellyfin server on capable hardware behaves exactly like a server with no GPU at all. The second mistake is worse, because it looks solved: you pick an acceleration mode in Dashboard, Playback, Transcoding, save, and never confirm that a single frame was actually decoded on the GPU.

Turn it on in the right place: Dashboard, Playback, Transcoding, then choose the mode that matches your chip, not the first entry in the list.

Tick the decode codecs you actually own: enabling H.264 and HEVC decoding is separate from choosing the mode, and leaving those boxes empty means the GPU decodes nothing.

Enable hardware encoding as well as decoding: decode only acceleration still leaves libx264 on the CPU, which is the expensive half of the job.

Verify with the transcode log: open a transcoding session, then read the newest file in /config/log/, where a working setup shows the hardware device being initialised rather than a plain software encoder line.

Verify with the server itself: run nvidia-smi on an NVIDIA host or vainfo inside the container on an Intel or AMD host, during playback, and check the encoder is busy.

Where you run Jellyfin decides which of these options exists at all. A home NAS, a self managed VPS, a mini PC under the TV and Yundera are all viable hosts. Yundera is a managed Personal Cloud Server, built on CasaOS, that runs self-hosted apps as Docker containers on a server dedicated to the user. Rented virtual machines frequently expose no GPU, so confirm before you buy.

Which transcoding path fits your server: Intel QuickSync, NVIDIA NVENC, AMD VAAPI or software?

Pick the path your silicon already has, not the one with the best reputation. Jellyfin lists the modes in one dropdown, and choosing a mode your hardware does not implement produces failed playback rather than a fallback you will notice. Check the chip first, then set the matching entry.

Path	Fits which server	What to check before you commit
Intel QuickSync (QSV)	Mini PCs, most NAS units and any Intel CPU with integrated graphics enabled in the BIOS	`/dev/dri/renderD128` must exist on the host, and the iGPU must not be disabled when a discrete card is installed
NVIDIA NVENC	A tower with a GeForce or Quadro card already in it	Consumer drivers have historically capped concurrent encode sessions, so read NVIDIA's current encode support matrix before planning four streams
AMD VAAPI or AMF	AMD APUs and Radeon cards on Linux hosts	Mesa driver version and container packaging decide what works, and HEVC support varies more than on Intel
Apple VideoToolbox	A Mac mini running Jellyfin natively	Not available to a Docker container, so this rules out the containerised setup entirely
Software (`libx264`)	Any machine, as the fallback when no encoder block exists	Predictable quality, unpredictable capacity, and the reason most family servers stall at two viewers

Hosting choice constrains this list. A NAS, a home mini PC, a self managed VPS and Yundera are all places Jellyfin runs. Yundera is a managed Personal Cloud Server, built on CasaOS, that runs self-hosted apps as Docker containers on a server dedicated to the user, installed from an app store in one click. Whichever you choose, confirm GPU access before you build a library around 4K files.

Why does the GPU never reach your Jellyfin Docker container?

A container sees only the devices you hand it. The host can have a perfectly working iGPU, vainfo can succeed on the host, and the container still has nothing to accelerate with. This is the single most common reason a correctly configured Jellyfin setting produces software transcodes anyway.

No device mapping in the compose file: Intel and AMD hosts need devices: - /dev/dri:/dev/dri in the service definition, and adding it requires recreating the container, not restarting it.

Wrong group membership inside the container: the render node is owned by a group whose numeric GID differs between distributions, so read it with ls -l /dev/dri on the host and pass the same value through group_add in compose.

NVIDIA cards need the toolkit, not a device line: install the NVIDIA Container Toolkit on the host and reserve the GPU in compose, or set NVIDIA_VISIBLE_DEVICES=all and NVIDIA_DRIVER_CAPABILITIES=all for the container.

A hypervisor layer in the way: Jellyfin inside a Proxmox LXC or a virtual machine only sees the GPU if the host was configured to pass it through first, and an unprivileged LXC needs explicit cgroup device rules.

A driver mismatch between host and image: the container ships its own userspace drivers, so an old host kernel or a very new GPU can leave you with a device node that opens but exposes no encode profiles.

Verify with one command: docker exec -it jellyfin ls -l /dev/dri. If that returns nothing, no Jellyfin setting will help. If it lists renderD128, run vainfo in the same container and read which encode profiles are actually advertised.

Anti-pattern 2: keeping one 4K HDR file as the only copy for every screen in the house

One pristine UHD remux looks like good curation. It is actually a transcode generator. A UHD Blu-ray source can carry video bitrates near 100 Mbps, and no phone, tablet or older smart TV in the house will direct play that. Every screen that is not the living room TV forces a downscale, and HDR makes it worse, because converting HDR10 to SDR requires tone mapping on top of the resize.

Tone mapping is a second workload: Jellyfin does it on the GPU through OpenCL or vendor specific paths, and enabling hardware acceleration without enabling tone mapping leaves the colour conversion on the CPU or produces washed out, grey looking video.

Dolby Vision profile 5 has no usable fallback: clients that cannot decode it show green and purple frames, so those files always need re-encoding for the rest of the household.

Disk is the cheaper resource: a second 1080p H.264 copy costs a few gigabytes per film once, while transcoding the 4K original costs GPU time on every single play.

Jellyfin has a built in mechanism for this: put both files in the same movie folder and name them Film Name (2021) - 4K.mkv and Film Name (2021) - 1080p.mkv, and Jellyfin presents them as selectable versions of one title.

Target the copy at your real clients: H.264 in MP4 or MKV, 1080p, SDR, is the widest compatibility baseline across browsers, Chromecast, Fire TV and phones.

Do this for the twenty titles your family rewatches, not the whole library. That handles most concurrent playback without touching the archive quality originals.

Why do subtitles turn a smooth Jellyfin stream into a full video re-encode?

Because some subtitles are pictures, not text. Text subtitles can be sent to the client as a separate stream and drawn by the player. Image subtitles have to be painted onto the video frames themselves, which means decoding and re-encoding every frame. A family member turning on subtitles is therefore enough to convert a zero cost direct play into the most expensive session on the server, and it happens mid playback with no warning.

Subtitle type	How Jellyfin delivers it	Cost to the server
SRT, external or embedded	Sent to the client as a separate text track	None, video keeps direct playing
WebVTT	Converted from text and streamed alongside the video	Negligible, a text conversion only
ASS or SSA with styling	Burned in when the client cannot render the styling	Full video re-encode for the whole session
PGS, from Blu-ray sources	Always burned in, since it is a bitmap format	Full video re-encode, the usual hidden cause
VobSub, from DVD sources	Always burned in, same bitmap problem	Full video re-encode

Three fixes, in order of effort. Set the burn in policy in Dashboard, Playback, under the subtitle burn in option, so text formats are never burned in unnecessarily. Convert bitmap tracks to text once with OCR, or fetch SRT sidecars with the OpenSubtitles plugin and drop them beside the video file as Film Name (2021).en.srt. Then extract embedded text tracks to sidecars with ffmpeg -i input.mkv -map 0:s:0 output.srt, so Jellyfin never has to pull them out of the container during playback.

Anti-pattern 3: leaving remote family accounts with no bitrate ceiling

A grandparent's tablet on the other side of the country asks for the same file the living room TV gets. Nothing in Jellyfin stops it by default. The client requests the source, the request exceeds your home upload capacity, playback stalls, and the server keeps working anyway. Worse, the client often reacts by asking for a transcode at some other bitrate, so you pay in CPU for a stream that still buffers. The arithmetic is unforgiving: a 40 Mbps file needs 40 Mbps of sustained upload, and residential connections are asymmetric by design.

Set the limit per user, not globally: each user's policy has an internet streaming bitrate limit in Mbps, so local viewers keep full quality while remote accounts are capped.

Set the server wide fallback too: Dashboard, Playback holds an internet streaming bitrate limit that applies to anyone you have not configured individually.

Measure your upload before choosing the number: total concurrent remote streams must fit inside your real upload speed, not your download speed, and leave headroom for everything else in the house.

Accept the transcode you just chose: a capped remote stream is a deliberate, predictable transcode, which is exactly the workload hardware encoding handles well.

Teach the client side setting as well: every Jellyfin app has a quality selector with preset steps, and a family member who picks the top entry overrides good intentions unless the server policy caps them.

Watch for the wrong ceiling: set it too low and remote viewers get soft video and a permanent transcode on files that could have direct played.

One capped stream beats one unlimited stream that never plays.

Anti-pattern 4: pointing the Jellyfin transcode cache at the wrong disk

Every transcode writes HLS segments to disk continuously, while several viewers read them back at the same time. Put that directory on the same spinning drive your media lives on and you now have random writes competing with sequential reads for the same heads. The transcode falls behind, the client buffers, and the dashboard still shows the GPU barely working. It looks like a CPU problem. It is a storage problem.

Know where it currently points: Dashboard, Playback, Transcoding has a transcode path field, and the official container expects a /cache mount for it, so an unmapped cache means the segments land inside the container filesystem.

Keep it off the media array: an SSD, even a small one, isolates the write load from the drives serving direct play sessions.

Consider a tmpfs, with a size cap: mounting the transcode directory as tmpfs puts segments in RAM, which is the fastest option, but it consumes real memory and must be given an explicit size limit or a long film can fill it.

Never use a network share: SMB or NFS latency on thousands of small segment writes is the worst case, and a dropped mount kills every session at once.

Do not run it on the boot USB stick or SD card: the write volume of routine family viewing wears cheap flash quickly.

Enable throttling and segment deletion: both live in the same transcoding settings page, and together they stop a paused session from transcoding an entire film ahead of the viewer and filling the disk.

Check free space with df -h on the cache path before blaming anything else. A full cache disk fails playback silently.

Which audio codecs and containers quietly force your family's clients to transcode?

Video gets the attention, but audio and container mismatches are what convert a direct play into something else on phones, browsers and cheap streaming sticks. The good news is that an audio only conversion is comparatively cheap. The bad news is that some clients respond to an unsupported audio track by requesting a full transcode, and lossless audio tracks are enormous, so remote sessions stall on bandwidth even when the video is untouched.

Lossless formats are the usual trigger: Dolby TrueHD and DTS-HD Master Audio pass through to an AV receiver over HDMI, and almost nothing else in the house decodes them.

Browsers refuse Dolby Digital: AC-3 and E-AC-3 are not decoded by desktop Chrome or Firefox, so laptop viewers get an audio conversion to AAC on nearly every film ripped from disc.

MKV is a container problem, not a codec problem: browsers play MP4 natively, so an MKV file is repackaged before it reaches them, which is cheap but only works if the streams inside are supported.

Phones and tablets downmix anyway: a 5.1 or 7.1 track becomes stereo on a two speaker device, and that downmix is a re-encode.

The fix is a second audio track, not a second file: add a compatible stereo AAC track with ffmpeg -i input.mkv -map 0 -c copy -map 0:a:0 -c:a:1 aac -ac 2 -b:a 192k output.mkv, keeping the original for the receiver.

Set the default audio track per user language preference so casual viewers land on the compatible track without choosing it. The living room keeps its lossless soundtrack, and everyone else stops generating work.

Why Vaultwarden Feels Slow: KDF, SQLite vs MySQL vs PostgreSQL, Storage, WebSockets and Your Reverse Proxy

John — Tue, 11 Aug 2026 07:05:52 +0000

For a single self-hoster with a few hundred vault items, the database is almost never the bottleneck. Unlock time is dominated by client-side key derivation, which runs on your laptop or phone and never touches the server at all, and sync time is dominated by the size of the full vault payload plus the round trip through TLS and your reverse proxy. SQLite handles a personal Vaultwarden instance without breaking a sweat; the cases where MySQL, MariaDB or PostgreSQL earn their keep are about concurrency, replication and backup tooling, not raw speed. Fix the KDF settings and the storage medium first, and only then argue about backends.

TL;DR by reader profile:

Solo developer with one vault on a Raspberry Pi, say 400 logins and no attachments: stay on SQLite and move the data directory off the SD card, because random write latency on flash cards is what you are actually feeling, not the query engine.
Self-hoster who bumped PBKDF2 to 2,000,000 iterations after reading a hardening thread, then blamed the server: lower the iteration count or switch to Argon2id with modest memory, because that delay is CPU work on the client and no server change will remove it.
Small team of 5 to 15 users sharing an organization, run on a NUC or small VPS: keep SQLite unless you see write contention in the logs, and put effort into WAL mode, a real SSD and correct WebSocket upgrade headers instead.
Homelabber who already runs PostgreSQL for other apps and wants one backup path: move Vaultwarden to PostgreSQL for operational reasons, accepting an extra container and a migration, not because queries will get faster.
Anyone whose vault is fine on the LAN and slow over the internet, for example on mobile data: the problem lives in DNS, TLS handshakes, proxy buffering and connection reuse, so measure the request path before touching the database.
Operator with a heavy vault, thousands of items plus attachments and icon fetching enabled: budget for payload size and outbound icon requests, because those grow the sync response and the I/O profile far faster than item count alone suggests.

The central tradeoff: every setting that makes your vault harder to crack offline makes it slower to open on your own devices, and every backend that makes operations easier adds a moving part that can itself become the slow thing.

Is your Vaultwarden server slow, or is your client just busy?
What happens between typing your master password and seeing your vault
What makes the sync response grow, and when does that start to hurt?
Is SQLite good enough for a self-hosted Vaultwarden vault?
When does moving to MySQL or MariaDB actually help?
Does PostgreSQL make Vaultwarden faster, or just harder to run?
How much does your storage medium change Vaultwarden write latency?
WAL mode, fsync and Docker volume layout: the settings that decide write cost
Do WebSocket notifications reduce sync traffic or add load?

Is your Vaultwarden server slow, or is your client just busy?

Start by splitting the problem in two. Everything that happens before a network request leaves your device is client work, and everything after it is server work. Vaultwarden, the Rust reimplementation of the Bitwarden server API, only ever sees the second half.

Unlock is client work: deriving your master key from your master password runs entirely in the browser extension, desktop app or mobile app, so a five second unlock on a laptop with the server powered off is still a five second unlock.

Sync is server work: the client calls GET /api/sync, the server reads your ciphers, folders and organization data, serialises them to JSON and sends them back, so this is where SQLite, storage and your reverse proxy appear.

A quick test separates them: run curl -o /dev/null -s -w '%{time_total}\n' https://vault.example.com/alive from the same network as the client, because that endpoint touches the server without touching your vault contents.

Where you host changes the second half only: a home server on a gigabit LAN, a NAS, a VPS in another country and a managed box all differ in round trip time and disk behaviour, never in key derivation cost. Yundera is a managed Personal Cloud Server, built on CasaOS, that runs self-hosted apps as Docker containers on a server dedicated to the user.

Docker adds its own floor: container startup, health checks and cold page cache mean the first request after a restart is slower than the next hundred, so never benchmark a container in its first 30 seconds.

What happens between typing your master password and seeing your vault

The sequence is fixed, and only two of its five steps involve your server.

Key derivation runs locally: the client feeds your master password and your email address as salt into the configured KDF, either PBKDF2-SHA256 or Argon2id, producing a 256 bit master key. Bitwarden clients default new accounts to 600,000 PBKDF2 iterations, while accounts created years ago may still sit at 100,000, and Argon2id defaults to 64 MiB of memory with 3 passes and 4 lanes.

Authentication is one small request: the client derives a master password hash from that key and posts it to /identity/connect/token. The body is a few hundred bytes, the response is a JWT access token plus a refresh token, and the server hashes the submitted value again before comparing it.

The symmetric key is unwrapped locally: your account encryption key arrives wrapped and is decrypted with the master key on the device. Vaultwarden never sees it, which is exactly why no server tuning can shorten this part.

Then the vault is fetched and decrypted: the sync call returns the ciphers, and the client decrypts each one to build the list you scroll through. On a phone this per item decryption is real CPU work, separate from the download.

Locking is not logging out: with a vault timeout action of Lock, reopening only repeats key derivation and local decryption, with zero network traffic. With Log out, you repeat the whole sequence including authentication and a full sync.

So a slow first open after a reboot and a slow open after a 15 minute timeout have different causes, and confusing the two sends you tuning the wrong layer.

What makes the sync response grow, and when does that start to hurt?

Vaultwarden has no incremental sync. Every GET /api/sync returns the whole vault: profile, folders, collections, organization keys, policies, Sends and every cipher you can see. Add one login and the client re-downloads all of them. That is fine at 200 items and noticeable at several thousand, because the cost is linear in item count and in the size of each item.

Growth driver	How it scales	When you feel it
Cipher count	Linear: each login, card, note and identity is a separate encrypted object with its own key material	Above roughly a few thousand items on mobile, where JSON parsing and decryption happen per object
URIs and custom fields per item	Multiplies the per-item payload, since each URI and field is separately encrypted	Vaults built by importing browser passwords, which often carry several URIs per login
Secure notes	Grows with note body length, not item count, so 50 long notes can outweigh 500 logins	When people paste config files or recovery codes into notes
Organization membership	Adds collections, policies and every shared cipher to your personal sync response	Joining a second or third organization on a shared instance
Attachment metadata	Only filenames, sizes and keys ride in the sync; the bytes are fetched separately	Rarely, unless `USER_ATTACHMENT_LIMIT` is set high and items accumulate many files

Two practical levers exist. Clients can call GET /api/sync?excludeDomains=true to skip global equivalent domains, and enabling gzip or brotli compression at the reverse proxy shrinks a highly repetitive JSON body substantially on the wire without touching the database at all.

Is SQLite good enough for a self-hosted Vaultwarden vault?

For one person, one family or a small team, yes. Vaultwarden defaults to SQLite for a reason: a password vault is a read heavy workload with a tiny working set, and the whole database lives in a single file at /data/db.sqlite3 inside the container.

The write volume is genuinely small: a vault write happens when you add or edit an item, log in on a device, rotate a token or create a Send. Nobody edits 40 passwords per minute, so the single writer limitation almost never bites.

Attachments never enter the database: file bytes are stored under /data/attachments, so a vault with 300 uploaded files keeps a database whose size tracks item metadata, not payloads.

Concurrency limits are about writers, not readers: SQLite allows many concurrent readers with one writer at a time, and in WAL mode readers do not block that writer. Five people syncing at once is reads, not a write storm.

Backups are a file copy, not a dump job: sqlite3 /data/db.sqlite3 ".backup '/data/backup.sqlite3'" produces a consistent snapshot while the server is running, and PRAGMA integrity_check; verifies it afterwards.

The failure mode is storage, not the engine: SQLite on a network share or an SD card behaves badly because locking and fsync semantics degrade, which is a filesystem problem wearing a database costume.

Where the file physically sits matters more than which engine reads it, whether that is a home server, a NAS, a VPS or a managed box such as Yundera. Move to a client server database when your operational needs change, not because item counts grew.

When does moving to MySQL or MariaDB actually help?

Not for speed. Swapping SQLite for MariaDB adds a TCP hop, an authentication handshake and a connection pool between Vaultwarden and its rows. For a single user vault that makes each query slightly slower, not faster. The reasons to do it are operational.

You already run a MySQL or MariaDB server: one backup path, one monitoring dashboard and one restore drill beats a second unrelated file to remember. Point Vaultwarden at it with DATABASE_URL=mysql://vaultwarden:password@db:3306/vaultwarden.

You need real replication or point in time recovery: binary logs and a replica give you rollback to a moment, which a nightly file copy cannot. Vaults are exactly the data where restoring to five minutes before a bad bulk edit matters.

Your storage layer cannot do file locking properly: if the data directory must live on NFS, SMB or a clustered filesystem, moving state into a database server sidesteps the locking behaviour that makes SQLite unsafe there.

You have dozens of concurrent writers: an organization with automated user provisioning, frequent invites and constant item edits produces sustained write concurrency that InnoDB row level locking handles more gracefully.

The costs are concrete. You need an image built with the mysql feature, a database created with CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci, and a migration step that copies the SQLite contents across before first boot. You gain a second container to patch, plus its memory: InnoDB defaults its buffer pool to 128 MB, which is more RAM than SQLite ever asked for. Tune DATABASE_MAX_CONNS, which defaults to 10, rather than leaving the pool to fight your server's own connection limit.

Does PostgreSQL make Vaultwarden faster, or just harder to run?

Harder to run, and no faster for a personal vault. The queries Vaultwarden issues are simple primary key and foreign key lookups over a handful of tables. No planner is going to shine there. PostgreSQL earns its place when you want its durability and tooling, not its throughput.

Dimension	SQLite	PostgreSQL
Per query overhead	In process function call against a local file	TCP round trip, protocol parsing and a pooled connection
Memory floor	Effectively the page cache Vaultwarden already uses	`shared_buffers` defaults to 128 MB, plus one backend process per connection
Backup and restore	Copy or snapshot one file	`pg_dump` for logical dumps, WAL archiving for point in time recovery
Migration effort	None, it is the default	Run `pgloader` or an equivalent converter, then verify row counts before cutover
Typical failure mode	Filesystem locking or a corrupted file on bad storage	Connection exhaustion, version upgrade of the data directory, container start order

Use DATABASE_URL=postgresql://vaultwarden:password@db:5432/vaultwarden and pin the image tag, for example postgres:16-alpine, because a major version bump will not start against an old data directory without an explicit upgrade step. That last detail causes more Vaultwarden outages than any query ever will.

The honest rule: choose PostgreSQL if you already operate it, standardise on it, or need WAL based recovery. Otherwise you have added a second container that must start first, stay patched and survive reboots, on whatever you run this on, a home server, a NAS, a VPS or a managed option such as Yundera. Complexity you do not need is itself a reliability cost.

How much does your storage medium change Vaultwarden write latency?

More than the database engine does. Every committed vault write ends in an fsync(), and that call does not finish until the device says the data is durable. Throughput is irrelevant here. A drive that streams 500 MB/s can still take milliseconds to acknowledge a 4 KB flush, and that flush is what your client waits on when you save a password.

SD cards and USB sticks are the worst case: small random writes with a sync barrier hit the controller's slowest path, and the constant rewriting also consumes write cycles. This is the single most common cause of a Raspberry Pi vault that feels sluggish on save.

Spinning disks pay physics on every flush: a 7200 rpm drive averages 4.17 ms of rotational latency per revolution, before seek time. Ten flushes in a save path becomes tens of milliseconds you cannot tune away.

SATA and NVMe SSDs collapse the problem: sync acknowledgement drops by orders of magnitude, which is why moving /data to an SSD usually ends the investigation before anyone touches DATABASE_URL.

Network shares turn each flush into a round trip: NFS and SMB add latency per sync and bring their own locking semantics, so this hurts both correctness and speed.

Measure before you argue: run fio --name=sync --rw=randwrite --bs=4k --fsync=1 --size=64m --filename=/data/testfile against the exact path your container writes to, then compare devices. ioping -W /data gives a quicker approximation.

Do this test inside the container, not on the host. Bind mounts, encrypted layers and virtual disks all sit between the two, and only the container's view reflects what Vaultwarden actually experiences.

WAL mode, fsync and Docker volume layout: the settings that decide write cost

Vaultwarden turns on SQLite write ahead logging by default via ENABLE_DB_WAL=true. That is the right default and you should leave it alone unless you have a specific reason.

WAL converts one random write into an append: commits go to db.sqlite3-wal sequentially instead of rewriting pages in place, which suits every storage medium and lets readers continue while a write is in flight.

Three files now hold your vault: db.sqlite3, db.sqlite3-wal and db.sqlite3-shm live together. Copying only the first one while the server runs can lose every commit still sitting in the WAL, which is why a snapshot taken with the SQLite backup API is safer than cp.

Checkpoints are the periodic cost: SQLite checkpoints automatically at 1000 pages, so with the default 4096 byte page size the WAL grows to roughly 4 MB before its contents are folded back into the main file. That fold is the one moment you pay bulk write cost, and it happens in the background.

Disable WAL only for network filesystems: set ENABLE_DB_WAL=false when /data sits on NFS or SMB, because shared memory indexing does not work reliably there. Accept slower writes as the price of correctness.

Volume choice changes fsync behaviour: a bind mount from a Linux host to /data is close to native. On Docker Desktop for macOS or Windows the same bind mount crosses a virtual machine boundary through a file sharing layer, and sync heavy workloads slow noticeably, while a named volume stays on the VM's own filesystem.

Never leave /data in the container's writable layer. Overlay filesystems are copy on write, and a docker compose down destroys it.

Do WebSocket notifications reduce sync traffic or add load?

They reduce it. The notification channel exists so that a change made on your phone reaches your laptop without every client polling for it. One idle connection is cheaper than repeated full sync requests.

One connection replaces repeated polling: clients open a persistent connection to /notifications/hub and receive a small message telling them something changed. Without it, they only refresh on unlock, on focus and on their own timer, so an edit can sit unseen for a long while.

The port layout changed: older Vaultwarden deployments ran a separate WebSocket listener on port 3012, while current versions serve it on the main HTTP port 8080 with WEBSOCKET_ENABLED=true. Old compose files that still publish 3012 confuse people into thinking the feature is broken.

Your proxy must pass the upgrade through: the request needs Upgrade and Connection headers forwarded for that path, otherwise the handshake fails silently and clients degrade to polling with no visible error.

Idle timeouts create reconnect storms: nginx defaults proxy_read_timeout to 60 seconds, so a connection with no traffic gets closed and every client reconnects on a loop. Raise it for the notifications path, or you have swapped occasional syncs for constant handshakes.

Mobile apps are a separate mechanism: the Bitwarden mobile clients rely on push notifications rather than this channel, which requires PUSH_ENABLED plus an installation ID and key registered with the upstream relay. Enabling WebSockets alone will not make your phone update instantly.

The load is a held file descriptor and a keepalive per connected device. For a household with 10 devices that is noise. The real cost is misconfiguration, not connections.

Notion to Docmost: what survives the export, and what the databases-to-pages downgrade really costs you

John — Sat, 08 Aug 2026 07:06:07 +0000

Your prose survives the move to Docmost almost intact. Your databases do not. Docmost ships an importer that reads a Notion HTML or Markdown export and rebuilds pages, hierarchy and attachments, but it has no database concept at all, so every Notion table, board, calendar, relation, rollup and formula arrives as flat page content that you maintain by hand from then on. Decide by asking what share of your workspace is written pages versus structured records, because that ratio, not the import quality, decides whether this migration is a one evening job or a rebuild.

TL;DR by reader profile

Documentation-heavy solo dev (a Rust developer with 400 pages of design notes, runbooks and meeting notes): migrate to Docmost, the export-import handles long prose, code blocks and nesting with almost nothing to fix afterwards.
Database-driven organiser (someone running a CRM, a habit tracker and a reading list as Notion databases): stay on Notion for those specific pages, Docmost gives you no filtered views, no relations and no rollups to replace them.
Homelab operator already running Postgres (a person with Docker Compose, a NAS and nightly pg_dump in place): migrate now, Docmost adds only a Postgres database, a Redis instance and a file store to infrastructure you already back up.
Team of one with occasional guests (a freelancer sharing specs with two clients): migrate, Docmost spaces, groups and per-space permissions cover guest sharing without a per-seat bill.
Mobile-first note taker (someone capturing notes on a phone all day): stay on Notion or run both, Docmost is a browser-first wiki and your capture workflow is the thing that degrades, not your archive.

The real tradeoff is that you exchange Notion's structured databases and polished mobile capture for a self-hosted wiki where the pages, the Postgres rows and the attachment directory are entirely yours.

What actually survives a Notion export into Docmost
Markdown or HTML: which Notion export should you feed Docmost?
Block by block: what lands intact and what flattens
What exactly do you lose when Notion databases become Docmost pages?
How do you rebuild a Notion database view inside Docmost?
Do internal links, backlinks and the page tree survive the import?
Attachments, images and embeds after the move
Comments, version history and page metadata: the silent losses
How long does the import take for a workspace of a few thousand pages?
What Docmost gives you that Notion never did
What does running Docmost require, and where should you run it?
What does the switch cost over three years, subscription against self-hosting?

What actually survives a Notion export into Docmost

Start with the export itself. In Notion, open the workspace settings, choose the export with subpages, and pick either Markdown & CSV or HTML. You receive a .zip archive containing one file per page, nested folders that mirror your page tree, and an images or attachment folder per page. Docmost reads that archive directly through its import screen, alongside its separate importers for Confluence XML exports, DOCX and PDF files.

Here is what comes through the round trip:

Page text and formatting: headings, bold, italic, strikethrough, inline code, blockquotes and links arrive as normal Docmost editor content, since both sides speak standard Markdown or HTML underneath.
Page hierarchy: the nested folder structure of the export becomes a nested page tree in a Docmost space, so a 5 level deep archive stays 5 levels deep.
Code blocks: fenced blocks survive with their language hint, which matters if half your workspace is snippets and runbooks.
Lists and checkboxes: bulleted lists, numbered lists and to-do checkboxes map cleanly to the equivalent Docmost editor nodes.
Attachments: images and uploaded files referenced by the export land in Docmost's own file storage rather than staying linked to Notion's CDN.
Simple inline tables: a plain Notion table with no filters or relations arrives as a static table you can still edit in place.

Everything above is prose infrastructure. What does not survive is the structured layer: databases, views, properties, relations, rollups and formulas. That distinction, prose versus records, is the single most useful lens for the rest of this migration.

Markdown or HTML: which Notion export should you feed Docmost?

Both formats import, but they fail differently. Markdown is cleaner and lossier. HTML is uglier and keeps more visual structure. Pick based on how much of your workspace leans on callouts, toggles and coloured text.

Aspect	Markdown & CSV export	HTML export
Page body	Plain `.md` files, minimal noise, easiest to inspect or fix with `sed` before import	Rendered `.html` with Notion's own wrapper markup and inline styles, more to strip
Databases	Written out as separate `.csv` files that Docmost does not turn into anything structured	Rendered as a static HTML table inside the page, so the data is at least visible in Docmost
Callouts and toggles	Flattened to plain paragraphs or blockquotes, the collapse behaviour is gone	Closer to the original layout, toggles and callout boxes keep their shape more often
Coloured text and backgrounds	Dropped, Markdown has no syntax for it	Carried as inline style attributes, which may or may not render in the Docmost editor
File naming	Page title plus a 32 character hex ID, for example `Runbook 8f3c...c21.md`	Same naming scheme with an `.html` extension

The practical answer for a mostly written workspace is Markdown, because what lands in Docmost is what you would have typed yourself, with no leftover span tags to clean up later. Choose HTML when a meaningful share of your pages are database views you want to read as tables rather than lose entirely.

Run both exports before you commit. They are free to generate, and importing each into a throwaway Docmost space tells you more in 20 minutes than any comparison table can.

Block by block: what lands intact and what flattens

Beyond the basics, Notion has roughly two dozen block types with no exact Docmost equivalent. Here is how the awkward ones behave.

Column layouts: a 3 column page becomes a single vertical stack, because the Markdown export has no column syntax and Docmost's editor does not reconstruct one. Wide dashboards read very differently afterwards.
Toggle lists: in the Markdown export they collapse to plain nested content, so the hiding is gone. In the HTML export they arrive as <details> markup and may keep the fold, which is worth testing on 2 or 3 sample pages before you commit.
Callouts: the emoji plus tinted box becomes an ordinary paragraph or blockquote. If you use callouts as warnings in runbooks, plan a find and replace pass to turn them into blockquotes with a bold Warning: prefix.
Equations: inline and block LaTeX comes across as $$ ... $$ text. Verify how your Docmost instance renders it rather than assuming, and fix the wrappers once across all files if it does not.
Synced blocks: each copy exports as its own independent content. After import you have duplicates that no longer update together, which is the single most dangerous silent change in the whole migration.
Mentions and dates: person mentions and date mentions degrade to plain text. A line reading "due @march 3" keeps the words and loses the meaning.
Table of contents and breadcrumb blocks: these are generated at render time, so they either vanish or arrive as a frozen snapshot of the old hierarchy.

Audit these seven types first. They account for most post-import cleanup.

What exactly do you lose when Notion databases become Docmost pages?

A Notion database is a small application: a schema, a query engine and several rendered views over the same rows. Docmost is a wiki. It stores pages in a tree inside spaces, and it has no schema layer at all. Here is the before and after.

Notion capability	What arrives in Docmost	What it costs you
Table, board, calendar and gallery views of one dataset	One static snapshot, an HTML table or a `.csv` file next to the page	You maintain a single representation by hand instead of switching views
Filters and sorts, for example "Status is not Done, sorted by due date"	Nothing, the query is not part of the exported data	Every filtered list becomes a manual list you curate or a search you retype
Typed properties: select, multi-select, status, date, number, checkbox	Text in table cells, with no validation and no type	Nothing stops you writing "In progres" and breaking your own convention
Relations and rollups between two databases	Plain text, both directions of the link are gone	Cross references stop updating, so a renamed project no longer propagates
Formulas and computed columns	The last computed value, frozen as text	Any total, days remaining or derived status stops recalculating on import day
Row pages with their own body content	Individual pages, which is the one part that transfers well	Little loss here, the content survives even when the container does not

Count your databases before deciding. A workspace with 380 written pages and 4 small databases is a straightforward migration. A workspace built around 12 interlinked databases is a rewrite wearing a migration costume.

How do you rebuild a Notion database view inside Docmost?

There is no direct replacement, so you pick a pattern per database rather than one strategy for all of them. Four patterns cover almost every case.

Index page plus child pages: recreate the database as a parent page in a Docmost space, with one child page per row and a hand written table of links at the top. This works well up to roughly 30 rows, past that the index becomes the maintenance burden the database used to absorb.
One static table, no child pages: paste the exported .csv contents into a single Docmost table and delete the row pages. Correct for reference data you read often and edit rarely, for example a port allocation list or a hardware inventory.
Search instead of filters: stop maintaining a filtered view and lean on Docmost's full text search plus a naming convention, for example prefixing every open item with TODO in the page title. You trade a saved view for a query you retype, which is cheaper than it sounds for a single user.
Keep the structured data outside the wiki: move genuinely relational data to a tool built for it, such as Grist, NocoDB or Baserow, and link to it from Docmost. This is the honest answer for a CRM or a time log, where losing typed columns and rollups is not acceptable.

Two Docmost features soften the blow. Page mentions and internal links let an index page stay clickable, and the built in Mermaid, Draw.io and Excalidraw blocks cover several dashboards that were really diagrams pretending to be boards.

Do internal links, backlinks and the page tree survive the import?

The tree survives, the links partly survive, the backlinks do not.

Hierarchy: the export's nested folders become nested Docmost pages inside whichever space you import into. Choose that target space deliberately, because a top level Notion page with 200 descendants lands as one page with 200 descendants, not as 200 loose pages.
Links to pages inside the export: these are written as relative file references with URL encoding, for example Runbook%208f3c...c21.md. The importer's job is to resolve them to the new Docmost page IDs, and it handles the common cases. Spot check 10 links across different depths straight after import rather than trusting the whole set.
Links to pages outside the export: anything you excluded, or anything in another workspace, stays as an absolute notion.so URL and keeps pointing at Notion. Count them before you cancel the subscription with grep -roh "notion.so[^)\"]*" . | wc -l run against the unzipped export.
Block level anchors: a link ending in a 32 character hex fragment targets a specific block. Docmost generates its own page URLs, so those deep links land on the right page at best and break at worst.
Backlinks: Notion computes its backlink panel live from the graph. Nothing about it is in the export, and Docmost does not rebuild it. The reverse direction of every reference is gone on day one.
Public share links: any URL you gave someone else dies with the workspace. Inventory them first.

The safe order is import everything at once, then fix links, never page by page.

Attachments, images and embeds after the move

Uploaded files travel with the export. Embedded third party content mostly does not.

Images and uploaded files: anything you dragged into a page sits in the export archive next to the page file, and the import copies it into Docmost's own file storage. After that your screenshots are served by your server, not by Notion's CDN.
Notion CDN URLs pasted as links: signed prod-files-secure style URLs expire. Any page where you pasted such a link rather than embedding the file will break once the workspace is gone, so search the export for that hostname and re-upload those files by hand.
Third party embeds: Figma boards, Google Docs, Loom recordings, YouTube videos and tweets are references to someone else's service. Expect them to arrive as plain links. The content still loads when you click, the inline preview does not.
Large media: Docmost applies a file upload size limit through its environment configuration. Check that value before importing an export containing a 200 MB screen recording, otherwise those uploads fail silently while every 2 MB screenshot succeeds.
Storage backend: Docmost can keep files on local disk or on S3 compatible object storage. Decide before the import, because moving 40,000 attachments afterwards means rewriting paths as well as copying bytes.
Backups: this is the change people miss. pg_dump captures your pages, not your attachments. Your backup job now needs the database and the file store, and restoring only one of them gives you a wiki full of broken image icons.

Run du -sh on the unzipped export first. That number is your new storage baseline.

Comments, version history and page metadata: the silent losses

Nothing here throws an error. You simply notice, three weeks later, that context you relied on is gone.

Comments: inline comments and page level discussions are not part of a Notion export in any format. If a decision was argued out in a comment thread rather than written into the page, copy that thread into the page body before you export. Docmost has its own inline comments, so this is a one time reset, not a permanent gap.
Version history: Notion's revision timeline stays behind, and its retention window depends on your plan anyway. Docmost starts a fresh history from import day, which means your first 24 hours of cleanup edits are the oldest versions you will ever be able to restore.
Created and edited timestamps: the export carries page content, not page provenance. Every imported page tends to share a single creation date, so a workspace of 400 pages looks like it was written in one afternoon. Sorting by recency is meaningless until you have used the wiki for a month.
Author attribution: created by and last edited by collapse to whichever Docmost account ran the import. For a solo workspace that costs nothing. For a workspace with two collaborators it erases who wrote what.
Icons and covers: page emoji icons and cover images are presentation, not content, and they do not survive. Pages that you navigate by icon get noticeably harder to scan.
Trash and archived pages: anything already deleted is not exported. Restore what you want to keep before exporting, because the Notion trash empties on its own schedule.

Write down what matters. Then export.

How long does the import take for a workspace of a few thousand pages?

Wall clock time is not the constraint. The machine work is minutes to hours, the human work is days. Plan around four separate costs.

Export generation: Notion builds the archive asynchronously and emails you a download link when it is ready. Large workspaces come back split across several .zip parts rather than one file, and the link is time limited, so download it the same day it arrives.
Upload path: the archive has to reach Docmost through your browser and whatever sits in front of it. A reverse proxy will reject the upload long before the application does, so raise the body size limit first, for example client_max_body_size 2048m in nginx, and confirm the equivalent in Caddy or Traefik if that is what you run.
Server side processing: the import parses each file, writes rows to Postgres and copies attachments into the file store. It scales with page count and total attachment bytes, and it is disk bound more than CPU bound. Run unzip -l export.zip | tail -1 to get the file count before you start, so you know whether you are importing 300 items or 30,000.
Human cleanup: this dominates every other cost combined. Column layouts, callouts, synced block duplicates, leftover notion.so links and every rebuilt database are manual work.

Do a pilot. Import one representative subtree of about 50 pages, time the machine part, then fix that subtree completely and time yourself. Multiply the second number by your total page count divided by 50. That estimate will be far closer than any general figure.

What Docmost gives you that Notion never did

The migration is not purely subtractive. Six things arrive that a hosted workspace cannot offer.

Diagrams as first class blocks: Draw.io, Excalidraw and Mermaid are built into the editor. In Notion those are embeds pointing at someone else's service, which is why they broke on export. Here the diagram source lives in your page.
SQL access to your own content: your pages sit in Postgres tables you can query. A psql one liner finds every page mentioning a hostname, across the whole instance, including pages a search index has not caught up with yet.
Spaces, groups and per space permissions: structure access by area rather than by page. A solo user gets a clean split between a private space and one shared with two clients, without a per seat bill for the guests.
An import path that keeps working: the same importer handles Confluence XML exports, DOCX and PDF alongside Notion archives, so consolidating older documentation into the same wiki does not need a second tool.
AGPL licensed code: you can read the importer to understand exactly what it does with your files, and you can patch it. When a block type flattens in a way you dislike, that is a fixable bug rather than a support ticket.
No external dependency at runtime: Docmost runs against your own Postgres and Redis, including in air gapped environments. Your wiki stays readable during an internet outage, which matters when the wiki holds the runbook for fixing the outage.

None of this replaces a database view. All of it is unavailable at any Notion price.

What does running Docmost require, and where should you run it?

Three moving parts: the Docmost application container, a PostgreSQL database and a Redis instance. Nothing else is mandatory. A Docker Compose file with those three services and a named volume for the file store is the whole deployment.

Baseline resources: this is a Node application with a collaboration server holding editor state in memory, plus Postgres and Redis alongside it. A single user instance is small, but treat 2 GB of RAM as the floor for the stack and give Postgres real disk rather than a network share.
A domain and TLS: Docmost needs a proper origin URL for links, invites and the collaborative editing websocket. Plan for a subdomain and a certificate before the import, not after.
A VPS you manage yourself: you install Docker, write the compose file, configure a reverse proxy such as Caddy or nginx, and own the upgrades. Maximum control, maximum maintenance.
A home server or NAS: the hardware is already running and the electricity is already paid for. The work moves to reaching it from outside, which usually means port forwarding, dynamic DNS or a mesh VPN.
A managed personal server: Yundera is a managed Personal Cloud Server, built on CasaOS, that runs self-hosted apps as Docker containers on a server dedicated to the user. Apps install from an app store in one click and each is reachable on a public HTTPS subdomain via NSL.SH mesh routing, so no static IP, no port forwarding and no manual certificate setup are involved.

Whichever you pick, size the disk for your attachment total plus growth, and set up the backup job on day one.

What does the switch cost over three years, subscription against self-hosting?

Do not compare a monthly fee against zero. Self-hosting moves the cost from a line item to your calendar. Take Notion's published per seat monthly rate, multiply by 36, and put that number next to the column on the right.

Cost line	Notion subscription	Self-hosted Docmost
Software	Per seat, per month, for 36 months, plus any mid term price changes you do not control	AGPL licensed, no fee, the self-hosted edition is the whole product for a solo user
Hosting	Included	A VPS bill, a NAS or home server you already own and power, or a managed personal server such as Yundera
Storage growth	Included until you hit a plan limit, then you upgrade the plan	Disk you buy once, sized from the attachment total you measured earlier
Backups	Included and invisible, restore is a support flow	Your job: a Postgres dump plus the file store, tested restores, offsite copy
Upgrades	Automatic, no action, no choice about timing	Pull a new image, read the release notes, roll back if needed, on your schedule
One time migration	None	The cleanup days from the pilot estimate, paid once, in hours rather than currency

The honest framing is that self-hosting wins on cash and loses on attention. If your hourly rate is meaningful and you dislike maintenance, three years of subscription may be cheaper than three years of patching. If the server exists anyway and Docmost is container number 12 on it, the marginal cost is close to the disk it consumes.

How Many People Fit in a Self-Hosted Hubs Room? Dialog SFU Bandwidth and CPU Costs Explained

John — Fri, 07 Aug 2026 09:11:34 +0000

A single self-hosted Hubs server on a 4 vCPU, 8 GB VPS comfortably carries one room of roughly 15 to 25 participants with audio and avatars, and drops to single digits once most of them switch cameras on. The binding constraint is almost never Reticulum, the Elixir state server, which handles position and object sync at very low cost per user. It is Dialog, the mediasoup based SFU, which must decrypt, route and re encrypt every audio and video stream, and whose outbound bandwidth grows with the square of the participant count. Plan your capacity against Dialog's egress and CPU first, and treat everything else as secondary.

TL;DR by reader profile:

Two person startup replacing a paid meeting room, for example a design studio doing weekly client walkthroughs: one small VPS is enough, because a 4 person audio first room needs a fraction of a single core and well under 10 Mbit/s of egress.
Community organiser running open public rooms, for example a monthly meetup with 30 drop in visitors: budget for a dedicated Dialog host and cap video, because unrestricted cameras in a 30 person room push egress into hundreds of Mbit/s.
Educator running parallel classrooms, for example six seminar rooms of 12 students each: scale by adding Dialog instances rather than by growing one machine, since mediasoup workers are single threaded and bind to one core each.
Enterprise team behind a corporate firewall, for example a distributed engineering group on locked down laptops: provision TURN capacity explicitly, because relayed peers double the traffic path and can quietly triple your bandwidth bill.
Hobbyist on a home server, for example a NAS in a cupboard on domestic fibre: check upload speed before anything else, because a typical asymmetric connection saturates its uplink at around 8 to 12 video participants.
Event host planning a one off launch, for example 100 attendees in a showcase space: shard into multiple rooms or use audio only broadcast patterns, since a single Hubs room is not designed as a webinar stage.

The central tradeoff is simple: every extra participant you allow with video multiplies Dialog's forwarding work and your egress bill, while every restriction you impose on cameras, resolution or room size buys back capacity you can spend on more concurrent rooms.

What is the realistic concurrent user limit for one self-hosted Hubs server?
Which Hubs component actually breaks first under load, Reticulum or Dialog?
How does Dialog's SFU model differ from mesh and MCU, and why does it matter here?
How much bandwidth does each Hubs participant consume, upstream and downstream?
Why does room bandwidth grow quadratically, and where does the curve become unaffordable?
How much CPU does a mediasoup worker use per audio stream and per video stream?
What server specification do you need for 10, 25 and 50 concurrent participants?
How much does Reticulum cost per user for position, rotation and object sync?
When does TURN relay kick in, and what does it add to your bandwidth bill?
How do simulcast, bitrate caps and audio only rooms change the maths?

What is the realistic concurrent user limit for one self-hosted Hubs server?

Start from the room, not the server. A Hubs room is a single Reticulum channel plus a single Dialog routing context, so the numbers that matter are per room before they are per machine. On a 4 vCPU, 8 GB Linux host running the full Community Edition stack, plan around these ceilings.

Room style	Realistic ceiling on 4 vCPU, 8 GB	What stops you first
Audio only, avatars moving	Roughly 25 to 30 participants	Dialog egress, then mediasoup worker CPU
Audio plus a few shared cameras	Roughly 15 to 20 participants	Outbound bandwidth on the host uplink
Everyone on camera	Single digits, often 6 to 8	Quadratic forwarding load in Dialog
Audio plus screen share at 1080p	Roughly 12 to 15 participants	Sustained high bitrate of the shared track
Several parallel small rooms	Limited by core count, not room count	One mediasoup worker binds to one core

Treat those as planning defaults, not guarantees. Your scene complexity, bitrate caps and network path move them substantially, and the later sections quantify each factor.

Where you run the stack sets the hard limit on the uplink figure. A VPS gives you symmetric bandwidth and a public IP. A home server or NAS gives you cheap storage but usually an asymmetric uplink. Yundera is a managed Personal Cloud Server, built on CasaOS, that runs self-hosted apps as Docker containers on a server dedicated to the user. Whichever you pick, measure the uplink with iperf3 before you size a room, because Dialog cannot forward what the link will not carry.

Which Hubs component actually breaks first under load, Reticulum or Dialog?

Dialog breaks first, almost every time. The two services fail in completely different ways, and knowing which symptom belongs to which process saves hours of misdirected tuning.

Reticulum scales the way Elixir services do: it is a Phoenix application on the BEAM virtual machine, and each participant is a lightweight process handling position, rotation and object state over a WebSocket. Thousands of these coexist on one core. You will see memory grow gently and CPU stay flat.
Dialog scales the way media servers do: it is built on mediasoup, and each worker process is single threaded and pinned to one core. When that core hits 100 percent, every stream it routes degrades at once, regardless of how idle the other cores look.
The failure signatures are distinct: a saturated Dialog produces choppy audio, frozen video tiles and rising round trip time while avatars keep moving smoothly. A struggling Reticulum produces the opposite, teleporting avatars and stale object positions while voices stay clear.
PostgreSQL rarely participates: Reticulum writes room metadata, accounts and scene records, not per frame state, so database load stays roughly constant as a room fills.
The host uplink often beats both: on a 1 Gbit/s link, sustained video forwarding can exhaust bandwidth while both processes still report headroom, which reads as network failure rather than server failure.

Diagnose with top -H -p $(pgrep -f mediasoup) to see per thread CPU on Dialog workers, then compare against the BEAM scheduler load. If one thread sits at 100 percent and the rest idle, you have found your ceiling.

How does Dialog's SFU model differ from mesh and MCU, and why does it matter here?

Dialog is a selective forwarding unit built on mediasoup. It receives one upstream from each participant and forwards copies to everyone else without decoding or re encoding the video. That single design choice explains most of the capacity numbers in this article.

Architecture	What the server does	Cost at 10 participants with video
Mesh, peer to peer	Nothing, clients connect directly to each other	Each client uploads 9 copies and downloads 9, clients die first
SFU without simulcast, plain forwarding	Copies each incoming stream to every other peer	Each client uploads 1 and downloads 9, server egress is 90 stream copies
SFU with simulcast, Dialog's normal mode	Picks a suitable quality layer per receiver	Same stream count, lower total bitrate, no transcoding CPU
MCU, server side mixing	Decodes all streams, composites one, re encodes	Each client uploads 1 and downloads 1, server CPU cost is severe
Audio only SFU	Forwards Opus tracks, applies no video work	Trivial CPU, bandwidth measured in tens of kbit/s per stream

The practical consequence is that Dialog trades CPU for bandwidth. It never transcodes, so a mediasoup worker stays cheap in processor terms compared to an MCU like Jitsi Videobridge running in mixing mode. What it cannot escape is the copy count. Ten senders in one room mean 90 outbound stream copies leaving your network interface, and 20 senders mean 380.

That is why you size a Hubs deployment by egress capacity and worker count rather than by raw CPU. It also means adding a faster processor rarely raises your ceiling.

How much bandwidth does each Hubs participant consume, upstream and downstream?

Bandwidth in a Hubs room comes from four separate streams, and only one of them is expensive. Measure each one before you multiply.

Voice, Opus over SRTP: a single microphone track runs in the 24 to 40 kbit/s range at typical WebRTC settings, plus roughly 10 percent packet overhead. Thirty people talking is still under 1.5 Mbit/s of unique source material.
Webcam video, VP8 or H.264 simulcast: Dialog normally publishes several spatial layers, commonly around 150 kbit/s at 320x180, 500 kbit/s at 640x360 and 1.2 to 1.5 Mbit/s at 1280x720. Each receiver pulls the layer their connection and tile size justify, so downstream per stream varies widely.
Screen share at 1080p: treat this as the heaviest single track in the room, typically 2 to 3 Mbit/s sustained for detailed content, and higher during rapid motion. One presenter sharing to 20 viewers costs more egress than 20 voice tracks combined.
Avatar and object state over Reticulum: position, rotation and interaction messages travel on a WebSocket separate from the media path, measured in single digit kbit/s per user. This is noise against the media figures.
Scene and asset downloads: a GLB scene, textures and audio files transfer once per join, so a 40 MB scene costs 40 MB per visitor at join time, not continuously.

Upstream per participant is simple: one voice track, optionally one camera, optionally one screen share. Downstream is where the count multiplies. Open chrome://webrtc-internals during a live room and read bytesSent and bytesReceived per transport to confirm your own numbers rather than trusting defaults.

Why does room bandwidth grow quadratically, and where does the curve become unaffordable?

The arithmetic is unforgiving. With n people sending video, each of the other n minus 1 receives a copy, so Dialog emits n times n minus 1 stream copies. Doubling a room quadruples its egress.

Five senders at 500 kbit/s each: 20 outbound copies, roughly 10 Mbit/s of egress. Any connection handles this.
Ten senders at the same bitrate: 90 copies, roughly 45 Mbit/s. Still comfortable on a symmetric 100 Mbit/s link, already impossible on most domestic uplinks.
Twenty senders: 380 copies, roughly 190 Mbit/s sustained. This is where a shared VPS network allowance starts to matter more than CPU.
Thirty senders: 870 copies, roughly 435 Mbit/s. You are now consuming close to half a gigabit for one room.
Fifty senders: 2,450 copies, over 1.2 Gbit/s. A single 1 Gbit/s port cannot carry it, whatever the server specification says.

Convert that to metered cost before committing. Sustained 100 Mbit/s of egress transfers about 45 GB per hour, so a weekly two hour session at twenty senders moves several hundred gigabytes per month. Providers that meter egress will notice.

The practical break point sits between 15 and 20 simultaneous video senders on a 1 Gbit/s host. Below it, you tune. Above it, you change the room design.

Where you host decides which side of that line you sit on. A self managed VPS with a symmetric gigabit port, a home server or NAS on asymmetric fibre, and Yundera, a managed Personal Cloud Server built on CasaOS that runs self-hosted apps as Docker containers on a server dedicated to the user, each present a different uplink profile you should confirm before sizing rooms.

How much CPU does a mediasoup worker use per audio stream and per video stream?

Dialog never decodes media, so the CPU cost is packet handling, not pixel work. What a worker actually spends its cycles on is SRTP decryption of the incoming packet, per consumer bookkeeping, then SRTP encryption of each outgoing copy. Cost tracks packets per second, not bitrate alone.

Audio is cheap because packet rates are low: Opus at the standard 20 ms frame size produces 50 packets per second per stream. Forwarding one voice track to 29 listeners means 1,450 encryptions per second, which a single core absorbs without noticing.
Video is expensive because packets are many: a 1.2 Mbit/s stream at a 1,200 byte payload runs at roughly 125 packets per second. The same 29 receivers turn that into 3,625 encryptions per second for one sender, and each additional sender adds another block.
Simulcast multiplies incoming work, not outgoing: the publisher sends several spatial layers, so the worker decrypts all of them but still forwards only the layer each consumer selected. Ingest cost rises modestly, egress cost does not.
Retransmissions add unpredictable load: NACK and PLI handling from lossy clients forces the worker to resend packets and request keyframes, and a handful of bad connections can cost more than a dozen clean ones.
Worker count is your only horizontal lever on one box: mediasoup starts one worker process per detected CPU core by default, each single threaded, and a room is pinned to a single worker.

Watch it live with pidstat -u -p $(pgrep -d, -f mediasoup) 1. When one worker crosses roughly 80 percent of a core, stop adding video senders to rooms it owns.

What server specification do you need for 10, 25 and 50 concurrent participants?

Size three things separately: cores for Dialog workers, RAM for Reticulum and PostgreSQL, and uplink for egress. The uplink is usually what you have to buy deliberately.

Target load	Specification to plan for	The binding constraint
4 to 6 people, one test room, audio first	2 vCPU, 4 GB RAM, 100 Mbit/s symmetric, 40 GB disk	Nothing, this runs the whole Community Edition stack on one host
10 concurrent, mixed audio and occasional video	4 vCPU, 8 GB RAM, 1 Gbit/s port	RAM, once PostgreSQL, Reticulum and the asset hosts share a box
25 concurrent, audio led with a few cameras	8 vCPU, 16 GB RAM, 1 Gbit/s port, metered egress checked	Sustained egress, not processor headroom
50 concurrent, video restricted	Dialog on its own 8 vCPU host, Reticulum and PostgreSQL on a second 4 vCPU host	Worker to core pinning, plus port capacity
50 plus, or several parallel rooms	Multiple Dialog instances, one per host, rooms assigned across them	Horizontal scaling, since a room cannot span workers

Allow 2 GB of RAM for PostgreSQL before tuning shared_buffers, and keep 20 GB of disk free for scene assets and uploads, which grow quietly.

Hosting choices split along the same lines: a self managed VPS gives you the symmetric port and root access to tune kernel networking, a home server or NAS gives you storage but rarely the uplink, and Yundera is a managed Personal Cloud Server built on CasaOS where apps are installed from an app store in one click rather than assembled from compose files by hand. Confirm the egress allowance in writing before you commit to a 25 person room.

How much does Reticulum cost per user for position, rotation and object sync?

Reticulum's cost per user is small enough that it rarely appears in capacity planning, but it is not zero, and it also fans out quadratically. The difference is payload size.

Per user memory on the BEAM is measured in kilobytes: each participant is an Erlang process holding channel state, so a 30 person room adds megabytes, not gigabytes. Reticulum's baseline footprint dominates, and that baseline is roughly constant.
Update payloads are tiny: an avatar transform is a handful of floats for position, rotation and a few tracked bones. Even at 10 to 20 updates per second, one sender produces low tens of kilobits per second of unique data.
The fan out still squares: with 30 people in a room, every update is copied 29 times. Assume 15 updates per second at 50 bytes and the room generates roughly 650 kB/s of broadcast traffic in total, which is under 6 Mbit/s. That is one twentieth of what the same room costs in video.
Object and media pins hit PostgreSQL, movement does not: spawning, moving and pinning an object writes a row, so a room where people constantly pin content produces steady database writes while ordinary walking around produces none.
Join and leave events are the spiky part: each join triggers presence updates to every client plus scene metadata queries, so 30 people arriving in the same 60 seconds costs more than the following hour.

Verify on your own instance by attaching to the running node and reading scheduler utilisation with :observer.start() or recon:scheduler_usage/1. If Reticulum is your bottleneck, you have an unusual room, not a typical one.

When does TURN relay kick in, and what does it add to your bandwidth bill?

Most Hubs clients connect straight to Dialog over UDP, because an SFU is already a public endpoint and needs no peer to peer hole punching. Relay only appears when the client side network refuses that path.

Symmetric NAT and strict firewalls force it: corporate networks that permit outbound 443 only will block Dialog's UDP media range outright, and the ICE negotiation falls back rather than failing.
ICE over TCP is the cheaper first fallback: mediasoup can accept TCP candidates on the same host, which keeps media on your Dialog server and adds latency and head of line blocking instead of a second machine and a second bandwidth charge.
coturn is the real TURN option: it listens on 3478 for UDP and TCP and 5349 for TLS, with a media port range set by min-port and max-port in /etc/turnserver.conf. Use static-auth-secret with time limited credentials rather than long lived users.
Relayed traffic is counted twice: every byte enters the TURN server and leaves it again, so a relayed participant pulling 2 Mbit/s costs 4 Mbit/s of measured transfer on that host, on top of the identical traffic Dialog already sent.
A small relay share is a large bill: in a 20 person video room, moving just 4 participants onto TURN adds their entire downstream a second time, which is a double digit percentage increase on total egress for a fifth of the audience.

Test before you need it with turnutils_uclient -T -u user -w secret your.turn.host. If you skip TURN entirely, accept that some corporate and mobile users will join with avatars visible and no audio at all.

How do simulcast, bitrate caps and audio only rooms change the maths?

These three levers move your ceiling further than any hardware upgrade. Each one attacks the copy count or the bitrate per copy. Take the same 20 person room and compare.

Configuration	What actually changes	Room egress at 20 participants
Everyone on camera at 640x360, 500 kbit/s	Nothing restricted, 380 outbound copies	Roughly 190 Mbit/s
Bitrate capped to 320x180, 150 kbit/s	Same 380 copies, each one smaller	Roughly 57 Mbit/s
Simulcast selecting low layers for distant avatars	Receivers pull the layer their tile size justifies	Between the two figures above, typically nearer the lower
Camera rights limited to 4 speakers	Copies fall to 4 senders times 19 receivers, 76 total	Roughly 38 Mbit/s
Audio only, avatars and screen share off	380 Opus copies at about 32 kbit/s	Roughly 12 Mbit/s

Three practical notes. Simulcast is the default worth keeping, because it costs the publisher extra upstream but saves every receiver downstream, and it degrades gracefully when one participant's connection collapses. Bitrate caps belong in Dialog's mediasoup settings rather than in client code, since anything enforced client side can be bypassed by a browser flag.

Restricting camera rights is the blunt instrument that works. Hubs room settings let you decide who may share video, and moving from open cameras to four presenters cuts egress by 80 percent in the table above without touching resolution at all.

Audio only is not a fallback, it is a valid room design. A 30 person social space with spatial audio, avatars and a good scene stays under 20 Mbit/s and runs on hardware that would collapse instantly with cameras enabled.

Duplicati on Backblaze B2 vs Backblaze Personal Backup: where the yearly cost actually crosses over

John — Fri, 07 Aug 2026 09:05:07 +0000

Duplicati backing up to Backblaze B2 costs less per year than a Backblaze Personal Backup subscription only below a dataset size you can calculate in one line, and that line is the whole decision. Personal Backup charges a flat annual fee per computer for unlimited data, so its cost curve is horizontal. B2 charges per gigabyte stored per month plus API calls and egress above the free allowance, so the Duplicati bill starts near zero and rises in a straight line. Divide the annual subscription fee by twelve times the B2 per gigabyte monthly rate, and you get the crossover in gigabytes: below it Duplicati wins every year, above it the subscription wins and keeps winning harder as you add data.

TL;DR

The 400 GB laptop owner, one MacBook holding documents, photos and a code folder: run Duplicati to B2, because a few hundred gigabytes billed per gigabyte per month sits far under any flat annual fee, and Duplicati compresses and deduplicates before you are billed.
The 6 TB media keeper with a film and music library on external drives: stay on Personal Backup, because unlimited flat pricing per computer is unbeatable at that volume and B2 charges for every terabyte forever.
The two person household with three laptops totalling 1.5 TB: run Duplicati into one B2 bucket, because the subscription is licensed per computer while a single bucket and three Duplicati jobs cover all of them under one bill.
The homelab operator with a NAS, a Proxmox host and two Linux VMs: Duplicati is the only option of the two, because Personal Backup is a Windows and macOS desktop product that excludes network shares and server operating systems.
The person who has never restored a file and wants zero maintenance: stay subscribed, because Duplicati's real price includes your own hours on local database rebuilds, retention tuning, verification runs and failure monitoring.
The person restoring large amounts often, for example a video editor pulling back 500 GB projects: model the egress before you switch, because Personal Backup restores are included while B2 bills downloads once you pass the free egress allowance.

The central tradeoff is a flat fee that ignores how much data you own against a metered bill that rewards you for owning less of it, with the difference paid in your own attention.

What does Duplicati plus Backblaze B2 actually cost you per year?
What does a Backblaze Personal Backup subscription actually cost per year?
At what dataset size do the two cost curves cross?
Deduplication, compression and the number B2 really bills you for
How much do restores cost, and how often will you actually restore?
How does retention depth change the arithmetic?
Tuning Duplicati remote volume size, upload threads and API call classes
Multiple computers, NAS shares and the per computer licence
What each product simply refuses to back up
Where should you run Duplicati, and what does the host add to the bill?

What does Duplicati plus Backblaze B2 actually cost you per year?

Duplicati itself is free and open source, so every euro or dollar on your annual bill comes from B2 and from your own hardware. The bill has four moving parts, and only one of them is the obvious one.

Storage per gigabyte per month: B2 bills the average bytes stored across the month, so your annual cost is roughly your stored size multiplied by the published per gigabyte rate multiplied by twelve. This is the dominant term for almost everyone.
Stored size, not source size: Duplicati 2 deduplicates at a default block size of 100 KB and compresses before upload, so a 500 GB source folder rarely becomes 500 GB in the bucket. Documents and code shrink hard, video and photos barely move.
Transaction calls: B2 splits API calls into Class A, Class B and Class C, with Class A calls such as uploads free and the listing and download classes billed per thousand calls. Duplicati's default remote volume size of 50 MB means a 500 GB backup lands as roughly 10,000 objects, which keeps call counts modest but not zero.
Egress on restore: B2 includes a free download allowance tied to your average stored data, and bills per gigabyte beyond it. Routine backups download nothing, so this term is zero in most years and spikes only when you restore.
Version retention: every kept version of a changed file is extra stored bytes, billed monthly like everything else.

Add those four, and you have a number that scales with what you actually own.

What does a Backblaze Personal Backup subscription actually cost per year?

Personal Backup is a flat fee per computer, billed monthly, yearly or on a two year term, with the longer terms carrying a lower effective annual rate. Unlimited means unlimited: 200 GB and 20 TB on the same machine cost the same. The complications are not in the headline price.

The licence covers one computer, not one household: three laptops means three subscriptions, and the annual cost triples while the amount of data protected is irrelevant to the bill.
Version history defaults to 30 days: deleted or changed files fall out of the backup after 30 days unless you pay for an extended version history add on, sold as a one year option and a forever option.
Forever version history is not flat: the forever tier adds a per gigabyte per month charge for data older than one year, which reintroduces exactly the metered pricing model you left B2 to avoid.
External drives count, network drives do not: USB attached disks are included at no extra cost, but a NAS share, a mapped network drive or a Linux server cannot be backed up at all, so protecting them means a second product on top.
Attached drives must be reconnected every 30 days: disconnect an external disk for longer and its backed up data is purged from the account, which is a silent cost if you rotate archive drives.
Restores are included: web download and restore by mail both come with the plan, with the mailed drive refunded on return.

The predictable number on the invoice is the product's main feature.

At what dataset size do the two cost curves cross?

Work it out yourself in one line. Take the annual Personal Backup fee, divide it by twelve, then divide that by the current B2 per gigabyte monthly rate. The result is the crossover in gigabytes stored, and both numbers are published on Backblaze's own pricing pages, so the calculation stays correct as rates change. Call that crossover point C.

Bytes stored in B2	Duplicati annual cost versus one subscription	What it means for you
0.25 x C	About 25 percent	Duplicati is clearly cheaper, and the gap is large enough to absorb restores
0.5 x C	About 50 percent	Duplicati is cheaper, with room for retention growth before parity
1 x C	Parity	Choose on features, not on price, because the invoices match
2 x C	About 200 percent	The subscription is cheaper and the gap widens every month you add data
4 x C	About 400 percent	Only non cost reasons justify Duplicati at this volume

Two adjustments move C in your favour. First, C scales linearly with the number of machines: three computers on Personal Backup means three fees, so your effective crossover is 3 x C for a single B2 bucket holding all three. Second, C applies to stored bytes, not source bytes, so Duplicati compression can put a 700 GB source folder comfortably under a 500 GB crossover.

One adjustment moves it against you: unlimited retention on B2 grows stored bytes forever, while the flat fee never notices.

Deduplication, compression and the number B2 really bills you for

Your source folder size is not your invoice. Duplicati hashes every block with SHA-256, stores each unique block once, packs blocks into archive volumes and compresses them before upload. Four things decide how far that gets you.

File type dominates the ratio: text, code, spreadsheets, mailboxes and virtual disk images compress and deduplicate heavily. JPEG, MP4, MP3 and existing ZIP archives are already compressed, so expect close to no reduction. Duplicati ships a default_compressed_extensions.txt list and skips compressing those types rather than burning CPU for nothing.
Deduplication is per backup job, not per bucket: two jobs covering the same 40 GB photo folder store those blocks twice and you pay twice. Consolidating overlapping folders into one job is free money.
Deleted data stays billable until compaction runs: when retention removes an old version, its blocks remain inside archive volumes that still contain live blocks. Duplicati only rewrites a volume once wasted space passes the compact threshold, 25 percent by default, so stored bytes lag behind logical deletions.
Encryption adds a small constant, not a percentage: AES-256 output is roughly the size of its compressed input plus per volume header overhead, so encryption costs you almost nothing on the bill.
The dashboard tells you the truth: the job's reported backend size, not the source size, is the number to feed into the crossover calculation from the previous section.

Measure once with a real backup before committing. A 1 TB documents heavy dataset and a 1 TB video library produce completely different B2 bills.

How much do restores cost, and how often will you actually restore?

Most people restore a handful of files a year and a full dataset once a decade, if ever. That matters because B2 includes a free download allowance of three times your average monthly stored data, so a household sized restore usually lands inside it.

A single full restore is normally free: pulling back everything you store is 1x your stored bytes against a 3x allowance, so you would need to restore your entire backup three times in one month before egress charges start.
Small restores cost more than you expect in bytes: Duplicati downloads whole archive volumes, so recovering one 2 MB document can pull a 50 MB volume. The cash impact is negligible, the wait is not.
Restoring without the local database is the slow path: direct restore first downloads the dlist and dindex files to rebuild an index of what is where, which on a large backup with many versions can take hours before a single file lands.
Class B download transactions are billed per call: thousands of volume fetches during a big restore add a small line item alongside egress, another reason larger remote volume sizes suit archival datasets.
Personal Backup charges nothing for either route: web download restores are included, and the restore by mail USB drive is refunded when you return it, so the subscription genuinely removes restore cost from the equation.

Budget the shape, not a scary number: routine restores are effectively free on both, and only repeated bulk pulls of your whole dataset make B2 egress a real line on the invoice.

How does retention depth change the arithmetic?

Comparing a 30 day subscription against an unlimited history Duplicati job is not a fair comparison. Match the retention first, then compare the invoices.

Retention setting	Effect on your bill	Where it applies
Keep all versions, the Duplicati default	Stored bytes grow with every change forever, so the B2 line rises even if your source folder never grows	Duplicati
`--keep-time=30D`	Roughly matches the standard subscription window, keeping stored bytes close to your live dataset size	Duplicati
`--retention-policy=1W:1D,4W:1W,12M:1M`	Thins older versions to one per week then one per month, buying a year of history for a fraction of the bytes	Duplicati
30 day version history, the plan default	No extra charge, and anything deleted more than 30 days ago is gone	Personal Backup
One year extended version history	A fixed add on fee per computer per year, still flat regardless of data volume	Personal Backup
Forever version history	Flat fee plus a per gigabyte monthly charge on data older than one year, so the metered model returns	Personal Backup

The practical consequence is that deep retention narrows the gap. If you want a year of history, the subscription add on is a fixed number per computer, while Duplicati's smart retention adds real bytes to a metered bill. If you want a decade of history, Duplicati's thinned policy competes well against a forever tier that meters everything over twelve months old.

Set retention before you measure stored size, or your crossover calculation is based on a number that will keep climbing.

Tuning Duplicati remote volume size, upload threads and API call classes

Defaults are tuned for a 50 GB laptop, not a 2 TB archive. Four settings change your bill, your backup window and your restore speed, and they pull against each other.

--dblock-size, default 50 MB: raising it to 200 MB or 500 MB cuts object count and the listing calls that go with it by the same factor. The cost is restore granularity, since recovering one small file downloads one whole volume.
--blocksize, default 100 KB: this one is fixed at job creation and cannot be changed later without starting over. A 2 TB dataset at 100 KB implies roughly 20 million block records in the local SQLite database, which is what makes repair and rebuild operations crawl. Raising it to 1 MB or larger for multi terabyte jobs trades a little deduplication for a database that stays usable.
--asynchronous-concurrent-upload-limit, default 4: more parallel uploads fill a fast link, but each in flight volume needs temporary disk space, and B2 counts each upload as a Class A call, which is not billed.
--number-of-retries, default 5, with --retry-delay: raising both rides out transient B2 errors instead of failing a job at 90 percent and re uploading later.

The class split is what makes B2 forgiving here: uploads and deletes are Class A and free, downloads are Class B, and listing is Class C with a published daily free allowance. Duplicati lists the bucket on every run, so shrinking object count with a larger volume size keeps you comfortably inside it.

Multiple computers, NAS shares and the per computer licence

This is where the flat fee stops being flat. Every extra machine multiplies a subscription while adding only its own gigabytes to a B2 bucket, so a four device household is a completely different calculation from a single laptop.

One bucket serves every machine: give each host its own Duplicati job and its own --prefix value, for example laptop-anna/ and nas-media/, so their archive volumes stay separated inside a single bucket and a single bill.
Issue one restricted application key per host: B2 application keys can be scoped to one bucket and one name prefix, so a compromised laptop key cannot read or delete another machine's backup. The master key stays out of every configuration file.
A central job over SMB shares deduplicates across machines: point one Duplicati instance at mounted network shares and shared files are stored once. The catch is that a laptop out of the house at 02:00 is simply not backed up that night.
Per machine agents catch laptops, at a cost: Duplicati runs on Windows, macOS, Linux and in Docker, so each device can back itself up whenever it has a connection, but identical files on two machines are billed twice.
Servers and NAS boxes have no subscription path at all: a Synology volume, a Proxmox host or a Linux VPS cannot be enrolled in a desktop plan, so mixed estates end up paying for two products anyway.

Count your machines before you compare prices. Three subscriptions against one metered bucket moves the crossover point three times further out.

What each product simply refuses to back up

Both tools have hard exclusions, and neither warns you loudly about them. Check this list against what you actually care about before comparing invoices.

Data	Backblaze Personal Backup	Duplicati
Operating system files, applications, temporary files	Excluded by default, since the product protects user data rather than a bootable image	Included if you select the path, though it is not a bare metal image either
Virtual disk images such as `.vmdk`, `.vhd` and `.iso`	Excluded by default through the client's exclusion rules, editable in settings	Included, and they deduplicate well between versions
Network shares and NAS volumes	Not supported at all	Supported through any mounted path, including SMB and NFS mounts
Linux hosts and servers	No client exists	First class, including headless Docker deployments
Open or locked files	Handled by the client's own snapshot logic	Requires `--snapshot-policy=on` to use VSS on Windows or LVM on Linux
Live databases	Files are copied as found, with no consistency guarantee	Same, unless you dump first with `--run-script-before`

Two practical consequences follow. If your important data includes VM images or a NAS share, the subscription's unlimited pricing never applies to it, so the comparison collapses before cost enters the picture. If your important data is a laptop's documents and photos, both cover it fully, and you are back to arguing about gigabytes.

Also check the client's maximum file size setting before trusting it with 80 GB video projects, because a size cap silently skips files rather than failing the backup.

Where should you run Duplicati, and what does the host add to the bill?

Duplicati has to run somewhere that can read your files, stay awake on schedule and hold a local SQLite database. That host is the hidden line item the subscription does not have.

On the machine being backed up: the simplest option, with the web interface on port 8200 and no extra hardware cost. The catch is that a sleeping laptop runs no backup, so set a schedule that matches when the lid is actually open.
On a NAS via Docker: one container backs up every share, which suits the central job pattern. Budget the local database on fast storage, because rebuilds on a spinning disk are painfully slow.
On a mini PC or home server: a low power box running 24/7 adds electricity and a machine to maintain, but it backs up network shares on a fixed schedule without depending on anyone's laptop.
On a VPS or a managed personal server: useful when the data already lives off site, for example a web application's files and database dumps. Yundera is a managed Personal Cloud Server, built on CasaOS, that runs self-hosted apps as Docker containers on a server dedicated to the user, and it sits alongside a self managed VPS, a home server or a NAS as one place to run the container.

One rule applies to every choice: a remote host can only back up data it can reach. Running Duplicati off site does nothing for the photos on a laptop unless those photos already sync somewhere the container can read.

DEV Community: John

Immich Sizing Guide: What a 20,000 Photo Google Takeout Import Really Costs in Disk, RAM and Hours

Table of contents

How much disk space does Immich actually need for 20,000 photos?

Why is the Immich database and thumbnail folder bigger than you expected?

How much RAM does Immich need, and what happens when it runs out?

How many CPU cores does the first import really use?

How long does a 20,000 item Google Takeout import take from start to searchable?

Should you upload into Immich or point it at an external library?

What does the Google Takeout format break, and how do you fix it before importing?

Which storage template should you set before the first upload?

Which machine learning model should you choose on day one?

What should the video transcoding policy be, and what does it cost you?

Where should you actually run Immich: NAS, mini PC, home server or hosted?

Which day-one settings force a full re-run if you change them later?

ConvertX Hardware Requirements: How Much CPU, RAM and Disk Before Conversions Start Failing

Table of contents

What happens inside ConvertX when you press Convert

What are the real hardware floors for ConvertX, tier by tier

The upload path: where large files die before ConvertX ever sees them

How do you tell an OOM kill from a timeout in ConvertX

Why does a ConvertX job finish with no output and no error

Scratch disk: the hidden multiplier on every ConvertX conversion

Concurrency in ConvertX: what breaks when two jobs overlap

Video and FFmpeg in ConvertX: the workload that decides your tier

Images and ImageMagick in ConvertX: pixel maths, memory limits and policy files

Documents, ebooks and LibreOffice in ConvertX: slow, single threaded, quietly fragile

Why Your Self-Hosted Stirling-PDF Container OOMs, Hangs or Returns a Broken PDF: 15 Anti-Patterns and Their Fixes

Table of contents

What is actually failing when Stirling-PDF dies, and how do you confirm it in two minutes?

Anti-pattern 1 and 2: no container memory limit, and no JVM heap ceiling inside it

Anti-pattern 3 and 4: running the wrong image variant, then calling a tool it does not contain

Where does Stirling-PDF write its temporary files, and why does that fill your disk?

Why does OCR hang, fail outright, or return a file with no selectable text?

Anti-pattern 9 and 10: treating office conversion as fast, parallel and font-independent

Why does a large upload fail before Stirling-PDF ever sees the file?

Anti-pattern 12: reverse proxy timeouts shorter than the job you just started

Anti-pattern 13: compression and repair settings that return a valid file with wrong content

Anti-pattern 14: volume permissions, custom fonts and language packs mounted incorrectly

Hubs Community Edition backup and restore: what npm run backup captures, what it misses, and how long recovery takes

Table of contents

What does npm run backup actually capture in Hubs Community Edition?

What does the Hubs backup script silently miss?

Where does Hubs store rooms, avatars and uploaded GLB scenes on disk?

How long does a full Hubs restore actually take?

How do you run npm run restore-backup without breaking existing room URLs?

Should you back up the Hubs Postgres database separately from the Reticulum file store?

What changes when you run Hubs against an external database instead of the bundled pgsql pod?

Which Hubs secrets, certificates and configuration files must be saved outside the backup archive?

How much disk space does a year of Hubs backups need?

Snapshots, scripts or object storage: which backup strategy fits a Hubs instance?

How do you test a Hubs restore before you actually need it?

What breaks when you restore Hubs onto a different domain or a different host?

Duplicati Block Size, Remote Volume Size and Retention: How to Choose Them for Your Data Shape

Table of contents

What do Duplicati's block size, remote volume size and retention policy actually control?

Why block size is locked in on the first backup run

How many blocks can the local database carry before it starts to hurt?

Millions of small files: which block size and remote volume size to choose

What should you change for a photo and video library?

A handful of multi gigabyte VM images: the settings that matter most

How big should the remote volume size be for your upload link and your provider?

What does the local SQLite database cost you in disk, RAM and backup time?

Keep all, keep versions, keep time or smart retention: which one fits your data shape?

How much post backup verification should you actually pay for?

How Much Transcoding Headroom Does a Plex Server Really Need? Quick Sync vs NVENC vs CPU for 4K HDR

Table of contents

What Plex is actually doing when a stream will not direct play

How much transcoding headroom does a client roster really need?

Direct play, direct stream and transcode: what each one costs your server

Why does 4K HDR tone mapping cost so much more than a plain 1080p transcode?

Quick Sync, NVENC or CPU only: which one fits your roster?

What does Plex Pass unlock, and what does the licence cost over three years?

How many concurrent 4K HDR sessions can one encoder realistically hold?

Where the bottleneck moves once the GPU is fast enough: disk, RAM and the transcoder temp directory

How do you make direct play the default and leave the encoder almost idle?

Subtitles, audio tracks and the other hidden transcode triggers

Private Docusaurus: What Actually Gates the Site, and What Still Leaks Through sitemap.xml, Search and Source Maps

Table of contents

What does Docusaurus actually serve, and why is there nothing to log into?