Platform guides

Getting Docker running, wherever you are.

You don't need a Linux machine to start. Windows and macOS both run this perfectly well for a first server, with two trade-offs worth knowing about before you begin rather than after. Pick your system below.

The one thing that's true on Windows and macOS

On both, Docker runs inside a hidden Linux virtual machine. That means hardware transcoding isn't available — Jellyfin will transcode using your CPU, which realistically means one stream at a time — and files stored on the Windows or Mac side are reached over a slow network filesystem. Both have workarounds below. Neither stops you getting started today.

Windows 10 & 11

Windows

Docker Desktop with the WSL2 backend gives you a real Linux environment underneath a normal Windows app. Once it's installed, everything else in these guides works exactly as written.

  1. Turn on WSL2

    Open PowerShell as Administrator and run:

    wsl --install

    That enables the features, installs Ubuntu and sets WSL2 as the default. Restart when it asks. On first launch Ubuntu asks you to create a username and password — this is your Linux account, separate from your Windows one.

    If WSL was already installed some time ago, make sure it's version 2:

    wsl --set-default-version 2
wsl --status

  2. Install Docker Desktop

    Download it from docker.com and install as normal. During setup, leave "Use WSL 2 instead of Hyper-V" ticked.

    Once running, open Settings and check two things:

    • General → "Start Docker Desktop when you log in" should be on, or your server won't come back after a reboot.
    • Resources → WSL Integration → enable it for your Ubuntu distribution.

    Then open Ubuntu from the Start menu and confirm:

    docker run hello-world

  3. Decide where your files live

    This is the decision that matters most on Windows, and it's easy to get wrong.

    Don't put your library on /mnt/c/. Paths like /mnt/c/Users/You/Videos cross from Linux to Windows through a translation layer. Library scans crawl, file moves copy instead of rename, and Linux file permissions don't survive the trip. It works, but badly.

    Keep everything on the Linux side instead — inside your WSL home folder:

    # Good: native Linux filesystem, fast
/home/you/media
/home/you/downloads

    You can still reach these from Windows Explorer. Type \\wsl$ in the address bar, or just explorer.exe . from inside Ubuntu.

    Have a big drive full of media already? If it's a separate physical disk, you can mount it into WSL directly with wsl --mount, which is much faster than going through /mnt/. If your media is on your Windows C: drive and you'd rather not move it, it will still work — just expect slower scanning.

  4. Carry on with the normal guide

    From here, you're using Linux. Everything in the setup guide applies as written — run it inside your Ubuntu terminal, not PowerShell.

    Continue with Arcane   Or use the script

  5. Stop Windows going to sleep

    A server that sleeps isn't a server. Under Settings → System → Power, set sleep to Never when plugged in. On a laptop, also set the lid-close action to do nothing.

    Windows Update will still reboot the machine occasionally. As long as Docker Desktop starts on login and your containers use restart: unless-stopped, everything comes back on its own.

Worth knowing

Memory creepWSL2 can hold onto a lot of RAM. Cap it by creating .wslconfig in your Windows user folder with [wsl2] and memory=8GB.
Firewall promptsWindows will ask about network access the first time. Allow it on private networks so other devices can reach Jellyfin.
Reaching it from your TVWSL2 sits behind its own network. Docker Desktop forwards published ports to Windows automatically, so other devices use your Windows machine's IP address.
AntivirusReal-time scanning of the Docker data folder slows things noticeably. Consider an exclusion if scans feel sluggish.
Alternative: skip Docker Desktop entirely. If you'd rather not run it, you can install Docker Engine directly inside Ubuntu on WSL2 using the standard Linux instructions. Slightly more setup, no licensing considerations for commercial use, and one less background application.
Intel & Apple Silicon

macOS

Docker on a Mac also runs in a Linux virtual machine, so the same two trade-offs apply. Setup is quick, and Apple Silicon handles this comfortably as long as you're aware of a couple of images that expect Intel.

  1. Install Docker

    Download Docker Desktop and pick the build matching your Mac — Apple Silicon or Intel. Drag it to Applications and launch it.

    In Settings, enable "Start Docker Desktop when you sign in", and under Resources, give it at least 4 GB of memory — 8 GB if you're running Immich.

    Check it works in Terminal:

    docker run hello-world
    Lighter alternatives exist. OrbStack is noticeably faster and gentler on battery, and Colima is free and open source. Both provide the same docker command, so every instruction here works unchanged.

  2. Share your folders

    Docker Desktop can only mount folders you've allowed. Under Settings → Resources → File sharing, add the folder holding your media if it isn't already covered.

    Your home folder is usually shared by default, so this is simplest:

    /Users/you/media
/Users/you/downloads

    Make sure VirtioFS is selected under Settings → General. It's substantially faster than the older options for the kind of file access these apps do.

    External drives are the awkward part. A USB drive at /Volumes/Media can be shared, but if macOS unmounts it — sleep, a loose cable — containers keep writing into an empty folder where the mount used to be. If your library lives on an external drive, set the Mac to never sleep and check the mount after any disconnection.

  3. Apple Silicon notes

    Most images here publish native arm64 builds and run at full speed. A few don't:

    ServiceOn Apple Silicon
    JellyfinNative — CPU transcoding only
    The *arr appsNative — no issues
    qBittorrent, GluetunNative
    ImmichNative — machine learning works well
    Uptime Kuma, ArchiveBoxNative
    Tube ArchivistMixed — its Elasticsearch has limited ARM support

    If an image has no ARM build, Docker will emulate it. That works but is slow and memory-hungry. You can force it per service if needed:

    services:
  something:
    platform: linux/amd64

  4. Carry on with the normal guide

    Everything else is identical. Run the commands in Terminal.

    Continue with Arcane   Or use the script

    The install script detects macOS and adjusts its default paths and permissions accordingly.

  5. Stop it sleeping

    Under System Settings → Displays → Advanced, enable "Prevent automatic sleeping when the display is off". On a laptop this only applies on mains power.

    For something more reliable, the built-in command works well:

    caffeinate -s

    Leave that running in a Terminal window and the Mac stays awake while it's open.

Docker Desktop licensing. It's free for personal use, education and small businesses, but larger companies need a paid subscription. If that applies to you, OrbStack or Colima avoid the question entirely.
Ubuntu, Debian, Fedora and friends

Linux

The best results, and the least in your way. Docker runs directly on the kernel with no virtual machine in between, which means full-speed disk access and hardware transcoding that actually works.

What you get here that you don't elsewhere
  • Hardware transcoding through /dev/dri — several simultaneous streams instead of one
  • Native filesystem speed, so large library scans finish in reasonable time
  • Instant file moves between downloads and library on the same filesystem
  • Lower idle memory use, since there's no VM to feed

  1. Install Docker

    The official convenience script handles every major distribution. Read it first — you're about to run it as root.

    curl -fsSL https://get.docker.com -o get-docker.sh
less get-docker.sh
sudo sh get-docker.sh

    Then let your user drive Docker without sudo:

    sudo usermod -aG docker $USER

    Log out and back in. Group membership doesn't apply to your current session, and this catches nearly everyone.

    docker run hello-world

  2. Set up hardware transcoding

    Only worth doing if you have an Intel CPU with integrated graphics, and only needed if Jellyfin will transcode. Check the device exists:

    ls -l /dev/dri

    If you see renderD128, add yourself to the render group and uncomment the devices: block in Jellyfin's service:

    sudo usermod -aG render $USER

    Then enable hardware acceleration in Jellyfin's dashboard under Playback.

  3. Carry on with the normal guide

    Continue with Arcane   Or use the script

  4. Make it survive reboots

    Ensure Docker starts at boot:

    sudo systemctl enable docker

    Combined with restart: unless-stopped on every service, your stack comes back by itself after a power cut. On a headless machine, also check that BIOS is set to power on after AC loss.

Synology, QNAP, unRAID, TrueNAS

NAS

A NAS is already a Linux machine built to stay on and hold drives, which makes it a natural fit. The main differences are that Docker is installed through a package manager, and that paths follow the NAS's own conventions.

Synology

Install Container Manager from Package Center (called Docker on older DSM versions). It includes Compose support under the Project tab, which is where you'll paste your generated file.

SettingValue
Config root/volume1/docker/modular-media-server
Media root/volume1/media
Downloads/volume1/downloads
PUID / PGIDRun id yourname over SSH to find them
Ports below 1024 and some others are reserved by DSM. If a container won't start because a port is taken, DSM is probably using it. Change the host side of the mapping — "8097:8096" rather than "8096:8096".

Transcoding depends on the model. Intel-based units with QuickSync can pass through /dev/dri; Realtek and older ARM models can't transcode meaningfully at all.

QNAP

Install Container Station from the App Center. It supports Compose under Applications. Paths generally start /share/ rather than /volume1/ — check yours in File Station.

unRAID

Docker is built in and unRAID's Community Applications catalogue already contains most of these services as one-click templates, which many people prefer to a Compose file. If you'd rather use Compose, install the Compose Manager plugin.

Mind the cache drive. Point downloads and appdata at your cache pool rather than the array, and keep your finished media on the array. Writing torrents directly to spinning disks in the array is slow and keeps them spun up constantly.

TrueNAS

Recent versions run Docker Compose directly. Older Kubernetes-based releases handle custom stacks differently, so check which version you're on before following a Compose-based guide.

Then carry on

Once Docker is available, the rest is the same. Arcane runs on a NAS perfectly well if you'd rather manage things in a browser than through the NAS's own interface.

Continue with Arcane   Or use the script

Side by side

What differs between them

WindowsmacOSLinuxNAS
Setup effortModerateEasyEasyEasy
Hardware transcodingNoNoYesModel-dependent
Disk speedGood in WSLGood with VirtioFSNativeNative
Idle memoryHigher (VM)Higher (VM)LowLow
Always-on suitabilityNeeds power tweaksNeeds power tweaksDesigned for itDesigned for it
Good for starting outYesYesYesYes
So should you switch to Linux?

Not to begin with. Use the computer you already own, get the stack running, and find out what you actually want from it. If you later hit CPU transcoding limits or slow library scans, that's the moment a dedicated Linux box earns its cost — and by then you'll know exactly which parts you need. Your Compose file and config folder move across in minutes.

Whatever you run it on, the rules don't change. Only obtain and share content you're legally entitled to. Downloaded files can carry malware regardless of operating system, and a VPN routes traffic without making any file safe. Keep everything updated, don't expose admin interfaces to the internet, and back up what you'd hate to lose.

Back to the setup guide   Hardware & hosting