pms-wiki: the written blueprint for a self hosted open media server

A wiki that argues for one specific stack

pms-wiki is a documentation project, and the interesting thing about it is not that it explains how to run a media server. That is widely documented elsewhere. It is that it commits to a specific set of choices and defends them.

The readme states the primary technologies it recommends: Linux, containers via docker managed with docker-compose, Proxmox, mergerfs, SnapRAID and ZFS. That is a full opinionated stack, from the hypervisor down to the array driver, and the wiki format exists to explain why each piece is there and how the pieces fit.

The history explains the format. The project began as a series of blog posts on the LinuxServer.io blog, and those posts continue to be popular, but a blog post can only get you so far. The four editions are linked in the readme, from the original 2016 article through the 2017 extensive video guides, the 2019 edition with the subtitle Boring is reliable + adding ZFS, and the 2020 edition that launched the site. The 2019 title is a fair summary of the philosophy: boring, reliable choices over novelty.

So the repository holds the source of a reference design rather than a tool. The primary language is recorded as HTML, and the actual content lives in a docs directory that MkDocs turns into the site. For a reader deciding whether to build a media server, this is closer to a book than to a package.

Justfile, mkdocs serve and a live reload loop

Running the wiki locally is deliberately simple, and the readme gives two routes.

The shorter one is a Justfile task.

just serve

The Justfile is in the repository root alongside the mkdocs.yml, the Dockerfile and the compose file, so the task is a one line wrapper around the same toolchain.

The longer route installs the Python dependencies and runs mkdocs directly.

pip3 -U -r requirements.txt

mkdocs serve

In both cases the site is served at localhost:8000. The requirements file is short and tells you what the site is made of. It pins the default theme at 9.7.0 or newer with the imaging extra, adds the theme extensions package and a minify plugin, then lists the git revision date plugin and its localized variant, and finally an analytics plugin for privacy friendly usage tracking.

The minify plugin and the revision date plugins are the two entries that tell you most about how the project is operated. Minification means the published HTML is meant to be served to readers, not just read in a browser during development. The git revision date plugins mean the site shows when each page was last changed, which for a wiki of this kind is important information: you need to know whether the ZFS advice reflects a current recommendation or a page nobody has touched in years.

That analytics plugin is the notable choice, since the fact that it avoids Google tracking is a small signal about the values the project states. The site is built to be hosted, and the maintainer chose the free and open source stack for the server side too.

Two container images, one built site and an nginx front end

The Dockerfile is a three stage build that ends in a plain nginx container, and the compose file ties it together.

The base image is parameterised so the upstream theme image can be swapped, and the dev stage installs the requirements with pip using a no cache directory, exposing port 8000 and running the serve command against 0.0.0.0 so the container is reachable from the host.

WORKDIR /build
COPY requirements.txt .
RUN pip install --no-cache-dir -U -r requirements.txt

EXPOSE 8000
CMD ["serve", "--dev-addr=0.0.0.0:8000"]

The builder stage copies the repository in and runs mkdocs build, and the final stage is nginx:alpine with the built site copied to the nginx html directory and a custom nginx.conf mounted as the default server configuration. The result is a static site served by nginx, which is the same shape as the production deployment the wiki recommends for everything else in the stack.

The compose file is a short, single-service definition.

services:
  pms-wiki:
    build: .
    platform: linux/x86_64
    image: ghcr.io/ironicbadger/pms-wiki:latest
    ports:
      - 8000:80

Two details in it are worth noting. The service is pinned to the linux/x86_64 platform, so the container does not run on a Raspberry Pi or an ARM machine without a change. And the image is published to the GitHub Container Registry with a latest tag, which means you can pull the published wiki without building it, although the platform line suggests the published image is built for one architecture only.

The compose file also shows a docker compose up --build command in the readme as the way to run the production style nginx image locally, which is the third route offered alongside just serve and mkdocs serve.

Publishing is a push to main and a GitHub action

The deployment model is stated in one sentence: to deploy the site, push to main, and a GitHub action will do the rest.

That is a complete deployment story for a static documentation site, and it is worth noting what it implies. The site is built by CI rather than by a maintainer with a local machine, the output is a static bundle, and the hosting is whatever the workflow points at. The repository has a .github directory, and the Dockerfile builds an image that could be built and pushed from the same place.

For a contributor, the process is unusually informal. The readme says to open a pull request and that it will be reviewed, and it closes with the phrase Gratefully received. There is a markdownlint configuration in the repository root, so the prose style is checked by a linter in the same way code would be, and there is a docs directory with the markdown pages plus an overrides directory, which is where the theme customisations live.

The maintenance signal here is thin, and it should be read as thin rather than as an endorsement. The repository has no GitHub releases, and the last push was on 2026-07-09. A wiki with no tagged versions and no changelog means that the correct way to consume it is as a website, at perfectmediaserver.com, and that the git history is the only record of what changed when. If you are pinning a specific recommendation from a specific page, note the revision date that the git revision date plugin surfaces, because the page itself will not tell you how old the advice is.

Where a wiki is the wrong tool

The limits of pms-wiki are the limits of its format, and they are clear enough to state.

The first is that it is not automation. There is no script in this repository that creates a media server, no Ansible role and no compose file for the stack the wiki describes. The repository builds a website. Everything else is prose that tells you what to install and how to wire it together, which means the work of building the server is still yours, and the wiki is a specification rather than a tool. That is a feature for someone who wants to understand their system and a poor fit for someone who wants a running server on Sunday.

The second is the hardware and platform assumption. The recommended stack starts at Proxmox, which is a virtualisation platform, and the compose file for the wiki itself is pinned to linux/x86_64. A single board computer or an ARM server, which is a common home media server form factor, is not what this design targets, and the wiki is not going to be the place you find ARM instructions.

The third is that a wiki can go stale in a way a package cannot. The page might describe a ZFS pool layout that was correct when written, and the repository shows no release cadence and no per page version. The git revision date plugin mitigates this by showing when a page changed, but mitigation is not the same as a maintained guarantee.

The fourth is the licence. The repository is recorded as carrying a licence that GitHub cannot classify, and the pointer to the LICENSE file is the only way to know what it permits. That is a real consideration for a body of prose that people may want to reuse, quote or fork, and it is exactly the kind of question that needs reading the file rather than trusting a summary.

On the alternative, the honest comparison is not another wiki but a different shape of solution. A container image per service, with the compose file and the configuration checked into your own repository, gives you the same modular, self owned stack and adds reproducibility, since the exact image digests are recorded and a rebuild reproduces the system. The difference in approach is that the wiki gives you a reasoned design and a set of principles, while a version controlled compose stack gives you a mechanism that runs the same way every time. The wiki argues for the second and provides the first, and for a first build the argument is what saves you from assembling something that works until an update breaks it.

Editorial conclusion

pms-wiki suits a self hoster who has decided to run their own media stack and wants a defensible reference design rather than a shopping list of components, and it does not suit someone who wants a turnkey media server or expects a script to perform the setup, because the repository builds a documentation site and nothing else. Before you follow it, read the whole wiki rather than the abstract, because the value is in the individual pages, and note that the licence is a custom one that GitHub cannot classify, so read the LICENSE file yourself before redistributing any of the text.

Frequently asked questions

Official sources

1. ironicbadger/pms-wiki on GitHub
2. Issues
3. Project website
4. README