Commands

The Docker image and the standalone binary drive the same build. This page is the reference for both: what you can run, what you can pass it, and what it reads from the environment.

The working directory

Wikven works out of a single directory, and everything else is derived from it:

<workdir>/src: Your wikitext, images and .wikven.yaml. Read, never written, except by the translation helpers.
<workdir>/dist: The built site. Emptied at the start of each build.
<workdir>/.cache: The throwaway database and MediaWiki's scratch space. Nothing here is part of your site, and it can be deleted between builds.

The Docker image has the working directory at /workspace, which is why builds mount src and dist under it. The binary uses the current directory. Either way, WIKVEN_WORKDIR overrides it.

`build`

Builds src/ into dist/. This is the image's default command, so the Docker form needs no argument:

wikven build

docker run --rm \
  -v "$(pwd)/src:/workspace/src" \
  -v "$(pwd)/dist:/workspace/dist" \
  ghcr.io/chaotic-ground/wikven

It takes no options; everything a build can be told is in your .wikven.yaml file. A failed build exits non-zero and says which page or step failed.

`serve`

Serves an already-built dist/ for local preview, on port 8080. It builds nothing: run build first.

This is for looking at a build on your own machine, and it is not a way to publish one. Both products listen on every interface by default, and one of them is PHP's own web server, whose manual says it "should not be used on a public network" and is "not intended for production usage". To put a site in front of readers, publish dist/ on a host instead.

wikven serve
wikven serve --listen 127.0.0.1:3000

docker run --rm -p 8080:8080 \
  -v "$(pwd)/dist:/workspace/dist" \
  ghcr.io/chaotic-ground/wikven serve

Only the binary takes --listen; the container always listens on 8080 inside, and you choose the outside port with Docker's own -p.

Each product serves with the server it already has, and those are not the same server. The image is a PHP runtime with no HTTP server in it, which is the choice that makes it 873MB rather than 1.5GB, so it serves with the one PHP itself carries. The binary is FrankenPHP, a web server with PHP inside, so it serves with the server it is built out of.

Both answer the same addresses, and both serve the files the export contains and nothing else. What each says about a file keeps to the standard, and a standard leaves room for two servers to say the same thing differently, so a preview from either shows you the site you are about to publish.

A stylesheet arrives as text/css; charset=UTF-8 from one and text/css; charset=utf-8 from the other. HTTP reads a charset without regard to case, so both name the same encoding.

`translate`

The four helpers behind Translating. They work on your source tree and exit without building anything.

Both products have these. The image runs them against the mounted source tree; the binary runs them against the working directory, which is the only difference between the two forms below.

translate mark: Inserts  markers into the still-unmarked units of a source page. Keeps the numbers already there, so it is safe to re-run.
translate scaffold <language>: Writes an empty marker per source unit into <Page>/<language>.wikitext, as a skeleton to translate into. Keeps what is already translated.
translate stamp: Records, for one translation you have read, the source version its units were written against.
translate check: Reports broken source pages, and translations that are out of date or missing. Writes nothing.

mark and scaffold take a single file, or --all for every page under the source directory: what they write is worked out from the source, so sweeping the tree says nothing that naming a file would not. stamp takes one file and has no --all, because what it writes is your reading rather than anything the tool can derive, and nobody reads a whole tree at once. check takes neither; it always reads every page it can find. mark, scaffold and stamp write into your source: mount it writable under Docker, where the binary edits it in place. check only reads.

wikven translate mark --all

wikven translate scaffold ko "Getting Started.wikitext"

wikven translate check --gate

docker run --rm -v "$(pwd)/src:/workspace/src" \
  ghcr.io/chaotic-ground/wikven translate mark --all

docker run --rm -v "$(pwd)/src:/workspace/src" \
  ghcr.io/chaotic-ground/wikven translate scaffold ko "Getting Started.wikitext"

docker run --rm -v "$(pwd)/src:/workspace/src:ro" \
  ghcr.io/chaotic-ground/wikven translate check --gate

check takes two more:

--gate: Exit non-zero when a source page is broken. A translation that is stale or missing is reported either way and never fails the run, because translating is not the job of whoever edited the English page.
--path-prefix <prefix>: Prepend a prefix to reported file names, so they read as repository paths rather than paths inside the container.

Environment variables

WIKVEN_WORKDIR: The working directory described above. Defaults to /workspace in the image and to the current directory for the binary.
SOURCE_DATE_EPOCH: The Unix time the build should claim its content was written, as in the reproducible-builds convention. The build runs with the clock frozen at it, so every timestamp in the output is stable. Unset, a fixed date is used — a wrong but unmoving one being easier to live with than one that moves each bake. The bake action sets it to the commit being built.
WIKVEN_FETCH_DIR: Where to keep the extensions and skins WikvenRepositories pins. A container is thrown away with the copies it fetched, so the next build asks the same hosts for the same tags again; name a directory that outlives the run — a mount, under Docker — and a build reuses what is there, fetching only where a pin has moved. The bake action does this for you.
WIKVEN_BUILD_JOBS: How many skin render passes may run beside each other. Unset, the build uses one per processor it is allowed — the container's allowance, not the host's. Only a site built with more than one skin has passes to run in parallel; set it to 1 to make a bake sequential, for a machine short of memory or a log you want in order.

There are three more, none of them useful to set by hand. The build sets two on itself to run one skin's render pass: WIKVEN_BUILD_SKIN names the skin, and WIKVEN_BUILD_DB_DIR names the copy of the database that pass writes to, since the passes run beside each other and SQLite takes one writer at a time. WIKVEN_BUILD_DB_DIR is read only when WIKVEN_BUILD_SKIN is set, and setting that one turns the build into a render pass over a wiki nothing has filled, so it writes a site of nothing. The third is WIKVEN_RUNTIME, which the standalone binary sets on every command it runs: it names the server the binary was compiled from, and the build puts that on the licenses page it writes.

GitHub Actions

Two composite actions run the image on a GitHub Actions runner, so a workflow needs no docker command of its own. The bake action bakes a source tree, which is how a site is published from a workflow: Deploying shows a complete one. The check-translations action runs translate check on a pull request and reports what it finds, which Translating describes. Each input an action takes, and its default, is described in the action's own action.yml, which the links above open.

← Standalone binary

Writing an extension →