Requirements

The target

Local Drive is built to run comfortably on a 1 GB RAM machine. That target shapes real decisions:

• SQLite rather than Postgres, so there is no second process to run and tune.
• No Redis. The Linux page cache already keeps recently read files in RAM, using whatever memory is actually free, and evicting under real pressure rather than on a TTL.
• Two background workers by default.
• Files are streamed with a fixed 32 KB copy buffer. The server never buffers a whole file in memory, in either direction.
• mem_limit: 512m on the server container, leaving room for the OS, the proxy, the two tiny helpers, and the filesystem cache, which is where SQLite's page cache benefit actually comes from.

Minimum

Releases carry a binary for Linux on x86-64 and ARM64, and for Windows on x86-64. There is no published macOS build. The server compiles and runs on macOS, so it is supported, but a published build would be unsigned, and macOS quarantines an unsigned download so that the first run fails in a way that looks like broken software rather than like a missing signature. Building it yourself avoids that entirely:

cd server
go build ./cmd/localdrive

Recommended

Optional tools

ffmpeg and pdftoppm give video and PDF thumbnails. Both ship in the container image. If either is absent the server looks for it once at startup, logs what it found, and skips those jobs cleanly: the file keeps its type badge, and nothing is treated as an error.

Two places are searched, in this order:

1. Anywhere on PATH.
2. The directory holding the Local Drive binary.

The second exists because a self hosted server is often a binary dropped in a folder rather than something a package manager installed. Putting ffmpeg next to localdrive is easier than editing the system PATH, and it travels with the folder if it moves.

Fetching ffmpeg automatically

When ffmpeg is missing on Windows or Linux, the server downloads a build for its own platform and puts it beside the binary. The download is verified by running it, so a truncated file or the wrong architecture is caught before anything depends on it.

localdrive setup does this while you are still sitting in front of it, which is the one moment a download is not a surprise. A server that reaches serve without one fetches in the background instead, so it answers requests immediately rather than making a first run wait.

If that download fails it is tried again, with the gap growing each time, starting at fifteen seconds and ending at three hours. Each gap is scattered by up to a third of itself, so a room full of servers that all came back after a power cut do not knock on the same door at the same second.

Set LOCALDRIVE_FETCH_FFMPEG=false to switch this off. Fetching an executable at runtime is something some operators will forbid outright, and that should be one variable rather than an argument with the software.

macOS is deliberately not fetched. The published builds are unsigned, so Gatekeeper quarantines them and the first run fails in a way that looks like a broken app rather than a missing tool. Install it with Homebrew there:

brew install ffmpeg

Thumbnails are made when a file is uploaded, so a video that arrives while ffmpeg is still downloading has no preview at that moment. It does not stay that way: when ffmpeg becomes usable the server goes back for everything that was skipped, and a sweep every thirty minutes picks up anything else that has no preview, in small batches so a large library heals over hours instead of pinning the machine for one of them.

Nothing has to be re-uploaded, and nothing has to be restarted.