Skip to content

Installation

Jump to bottom
Will Luck edited this page Nov 1, 2026 · 1 revision

Installation

This page covers every way to run Waymark: the demo, GitHub, Gitea or Forgejo, both, the tokens it needs and the Docker details. Back to the README.

There is no login. Read Privacy first. Publish the port on loopback (-p 127.0.0.1:8080:8080) unless something in front of it guards it.

Contents

Try the demo

An invented team's projects from a built-in fake forge: no token, no config, no network.

docker run --rm -p 127.0.0.1:8080:8080 ghcr.io/will-luck/waymark -demo

Open http://127.0.0.1:8080. Every page says it is demo data.

GitHub only

docker run -d --name waymark --restart unless-stopped \
  -p 127.0.0.1:8080:8080 \
  -e GITHUB_TOKEN=github_pat_... \
  -e GITHUB_OWNERS=your-user,your-org \
  -e TZ=Europe/Paris \
  -v waymark-data:/data \
  ghcr.io/will-luck/waymark:latest
  • Each public repo of the listed owners becomes a project.
  • Leave GITHUB_OWNERS out to track only the token user's own repos; list orgs or other users to track theirs.
  • Private repos stay off. To show them, add -e WAYMARK_INCLUDE_PRIVATE=true: their names, issues, commits and CI then show to anyone who can reach the page, so put a login in front of it first (privacy).

Gitea or Forgejo only

docker run -d --name waymark --restart unless-stopped \
  -p 127.0.0.1:8080:8080 \
  -e GITEA_URL=https://git.example.com \
  -e GITEA_TOKEN=... \
  -e GITEA_OWNERS=your-user,your-org \
  -v waymark-data:/data \
  ghcr.io/will-luck/waymark:latest
  • The same rule: leave GITEA_OWNERS out to track only the token user's own repos (not repos you collaborate on, nor your orgs' repos); list orgs or other users to track theirs.
  • The token is required. Gitea and Forgejo need it; without one their API refuses the list.
  • Private repos stay off here too: -e WAYMARK_INCLUDE_PRIVATE=true shows them, behind a login.

Both forges

Set both sets of variables, or write a config file. A repo with the same name on both forges becomes one project: the first forge holds the primary (tags, releases, CI, plans), the second is a mirror (stars, its issues, its latest release).

# config/waymark.yml
site:
  title: Team status
  timezone: Europe/Paris
include_private: false   # true shows private repos: only behind a login
forges:
  - id: gitea
    type: gitea          # or forgejo
    url: https://git.example.com
    token: ${GITEA_TOKEN}
    owners: [acme]
  - id: github
    type: github
    token: ${GITHUB_TOKEN}
    owners: [acme]
    heatmap: false       # the mirrored commits are already counted on Gitea
docker run -d --name waymark --restart unless-stopped \
  -p 127.0.0.1:8080:8080 \
  -e GITEA_TOKEN=... -e GITHUB_TOKEN=... \
  -v "$PWD/config:/config:ro" \
  -v waymark-data:/data \
  ghcr.io/will-luck/waymark:latest

Images and binaries

What Where
Images ghcr.io/will-luck/waymark and willluck/waymark on Docker Hub, for amd64 and arm64
Binaries Linux (amd64, arm64, armv7) and macOS (amd64, arm64), on the releases page

Run the binary as waymark with the same variables and DATA_DIR set to a folder it can write, or waymark -demo.

Tokens and scopes

Waymark only reads. Give it a token that can only read.

Gitea and Forgejo

An access token (Settings, Applications) with read:repository, read:issue, read:user and read:organization. A token is required: without one the API answers 401 and the forge's source shows as failing.

GitHub

A fine-grained token with read-only Metadata, Contents, Issues, Pull requests and Actions on the repos to track (choose "All repositories" to pick up new ones). Use a fine-grained token where you can. A classic token with no scopes reads public repos only; for private repos it needs repo, which also allows writing. Waymark never writes, but that token could.

What needs a GitHub token:

  • listing an owner's repos (without one, only repos the projects file names are read);
  • full detail: tags, commits, PRs, CI runs, the changelog and plans;
  • the contribution calendar for the ship log, and the search that finds issues filed from ideas;
  • anything private.

Rate limits

  • Without a token GitHub allows 60 requests an hour, so a tokenless forge reads each named repo lightly: the repo, its open issues and its latest release, every 30 minutes.
  • With a token the limit is 5,000 an hour, and every read is conditional (ETags), so unchanged data costs little.
  • A spent limit is named in the forge's status with the time it resets, and the forge is asked nothing until then.

Docker

  • Image: Alpine, runs as uid 1000, listens on 8080, no HEALTHCHECK (GET /healthz answers with each source's state if you want one).
  • /data is a volume: state.json (events for 90 days, probe history) and the last good projects and ideas files. Use a named volume, or a directory uid 1000 can write.
  • /config is where waymark.yml is read from. Bind-mount the directory, read-only.
  • Tokens come in as -e variables and are named in the file as ${GITHUB_TOKEN}.
  • Notes: mount the notes folder read-only. See Notes.

Containers on the page

Containers are optional. With docker.feed or docker.host set, "Where it runs" shows each project's containers (see Where it runs).

Setting How Notes
none Nothing about containers is shown
docker.feed A host cron runs scripts/docker-feed.sh every minute; mount its directory read-only at /feed No Docker socket in the container. The safe default
docker.host The Engine API: tcp://socket-proxy:2375 or unix:///var/run/docker.sock Prefer a socket proxy that allows only container listing. A mounted socket gives control of Docker even with :ro, and needs --group-add with the socket's group

Configure it further

One YAML file, /config/waymark.yml (WAYMARK_CONFIG names another path), with ${VAR} expansion so tokens stay in the environment. Every key, its default and an example are in docs/configuration.md; waymark.example.yml is a complete file to copy.

Section What it sets
site Page title, time zone, the names notes use for you
include_private Whether private repos show at all (off by default)
forges Each Gitea, Forgejo or GitHub account: URL, token, owners, heatmap
projects An optional projects file: names, categories, grouped repos, containers, URLs to probe, holds, relations
ideas Idea labels, an optional ideas file, the filed-idea marker
needs_you Which labels, assignments and review requests wait on you
notes An optional notes folder
plans Where plan files live in each repo
docker A feed file or the Docker Engine API
probes Whether repo homepages are probed
listen, data_dir Address and state directory

Without a file, the environment variables above make an env-only setup.

Home

Getting started

Using Waymark

Reference

Clone this wiki locally