Run with Docker

The Docker image contains everything YAPCO needs: Node.js, Chromium, Caddy, the app, this documentation and the PDF export service. Your system only needs Docker, and nothing is installed on it besides the image.

What you need

• Windows 10 or 11: Docker Desktop with the WSL 2 back end (the installer sets it up; start Docker Desktop before the commands below).
• macOS: Docker Desktop (Apple silicon or Intel).
• Linux: Docker Engine with the Compose plugin (docker compose version prints a version). Add your user to the docker group, or put sudo before the commands below.
• To build it yourself: Git, and about 5 GB of free disk space for the build.

Quickest: the ready-made image

No clone and no build: Docker downloads the published image (about 600 MB) and starts it. It works on Intel/AMD and ARM machines, including Apple silicon Macs.

docker run -d --name yapco --restart unless-stopped -p 127.0.0.1:8080:8080 --shm-size 1g --read-only --tmpfs /tmp --security-opt no-new-privileges ghcr.io/mdyzma/yapco:latest

Then open http://localhost:8080. The same command works in PowerShell, Terminal (macOS) and any Linux shell. (In Git Bash on Windows, put MSYS_NO_PATHCONV=1 before it, or Git Bash turns /tmp into a Windows path.)

To…	Run
Allow another address for PDF export	add -e YAPCO_ORIGIN=http://192.168.1.20:8080 before the image name
Open it from other devices	use -p 8080:8080 instead of -p 127.0.0.1:8080:8080
Update	docker pull ghcr.io/mdyzma/yapco:latest, docker rm -f yapco, then the docker run command again
Stop and remove	docker rm -f yapco
See the logs	docker logs -f yapco

latest follows the main branch; released versions have their own tags, such as :0.10.0.

Build it yourself

To build the image from the source, for example to try your own changes, use Compose:

git clone https://github.com/mdyzma/yapco.git
cd yapco
docker compose -f deploy/docker/compose.yaml up -d --build

The same commands work in PowerShell, Terminal (macOS) and any Linux shell: Docker accepts the forward slashes in deploy/docker/compose.yaml on Windows too.

The first build takes a few minutes: it installs the dependencies and builds the site inside the image. Then open http://localhost:8080. This documentation is at http://localhost:8080/docs/.

Check that it is running:

docker compose -f deploy/docker/compose.yaml ps

The status should say healthy.

Settings

Copy deploy/docker/.env.example to deploy/docker/.env and open it in a text editor:

Windows

Copy-Item deploy/docker/.env.example deploy/docker/.env
notepad deploy/docker/.env

Linux

cp deploy/docker/.env.example deploy/docker/.env
nano deploy/docker/.env

macOS

cp deploy/docker/.env.example deploy/docker/.env
open -e deploy/docker/.env

Every line is optional:

Variable	Default	Meaning
YAPCO_PORT	8080	The port on your computer
YAPCO_BIND	127.0.0.1	127.0.0.1: only this computer can open it; 0.0.0.0: other devices in your network too
YAPCO_ORIGIN	none	More addresses people open the site with, comma-separated
BUILD_SHA	docker	The version shown in the dashboard’s footer

After a change, run the up -d command again.

To show the exact commit in the footer instead of docker, set BUILD_SHA when building:

Windows

$env:BUILD_SHA = git rev-parse --short HEAD
docker compose -f deploy/docker/compose.yaml up -d --build

Linux

BUILD_SHA=$(git rev-parse --short HEAD) docker compose -f deploy/docker/compose.yaml up -d --build

macOS

BUILD_SHA=$(git rev-parse --short HEAD) docker compose -f deploy/docker/compose.yaml up -d --build

PDF export and addresses

The export service answers only pages opened from an address it knows: localhost and the addresses in YAPCO_ORIGIN. If you open the site from another device as http://192.168.1.20:8080, or through a tunnel as https://planner.example.com, add that address to YAPCO_ORIGIN, or Create PDF will fail there.

Update

git pull
docker compose -f deploy/docker/compose.yaml up -d --build

Stop and remove

docker compose -f deploy/docker/compose.yaml down

The container keeps no data, so stopping or removing it loses nothing: planners stay in your browser. Keep JSON backups of them as usual.

To free the disk space as well, remove the image: docker image rm yapco:local.

Logs

docker compose -f deploy/docker/compose.yaml logs -f

How it is built

• deploy/docker/Dockerfile: a build stage installs the workspace and builds the app and the documentation; the final image has only Node.js, Chromium, fonts, Caddy, the static files and the export service. It is about 1.5 GB, mostly Chromium.
• deploy/docker/entrypoint.sh starts the export service and Caddy; if either stops, Docker restarts the container.
• The container runs as an unprivileged user with a read-only file system.
• deploy/Caddyfile is the same as on Proxmox.

Next (optional): publish it with a Cloudflare Tunnel.