willluck/waymark repository overview

⁠Waymark

A self-hosted, read-only page that shows every project on your Gitea, Forgejo and GitHub accounts: what is active, what is deployed, and what waits on you.

⁠Try it in one command

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

Open http://127.0.0.1:8080⁠ to see an invented team's projects from a built-in fake forge: no token, no config, no network, and every page says it is demo data.

⁠A quick tour

The header has four tabs: Overview, Ideas, Ship log and Map.

⁠Overview

Every project at a glance: count tiles, a year of commits, what changed since you last looked, and every project grouped by state.

The six states are Active, Live, On hold, Quiet, Dormant and Archived. The page updates itself, and the header says Live or names a failing source.

Further down the Overview, every project is grouped by state, starting with Active:

⁠Needs you

What is waiting on you: things to Fix, Deploy, Review, Confirm or Decide, each naming its project and where it came from.

Cards come from your forges, Docker, probes, F-Droid, the projects file and notes. On a forge, "you" is the token's user: to add a card, label an issue needs-you or assign it to yourself.

⁠Project page

Everything about one project: is it deployed, is it healthy, what is left. You can tell without opening the forge.

The top: its state and why, then chips for versions, CI, issues, PRs and plan progress.

Further down: where it runs, and its versions with the running one marked.

⁠Ideas

Feature ideas from issues labelled idea or enhancement, and from an optional ideas file. Filter them by kind and size, or press Surprise me.

An idea that is not an issue yet has a File as issue button. With no ideas set up, the page stays hidden.

⁠Ship log

A year of commits per day, your busiest day and current streak, then every release of the last 18 months, by month.

⁠Map

Every project as a star, grouped by category. Colour shows the state, size shows the last 12 weeks of commits, and lines join related projects.

⁠Search

Press Ctrl K (Cmd K on a Mac, or /) and type a few letters to jump to any project, idea or issue.

It also runs commands: Refresh now, Toggle theme and Surprise me.

⁠Dark mode and phone

Light or dark: it follows your system until you press the sun or moon button. Every page also fits a phone.

Dark theme	On a phone

⁠What it reads

Nothing on the page is typed in by hand: every state comes from these sources. Waymark needs no LLM and no database, and it only reads: it never writes to a forge and never shows your token.

You need at least one forge. Without a projects file, each repo is a project. Repo homepages are probed by default.

Every setting is in the Configuration Reference⁠.

⁠Install

Each command publishes the port on 127.0.0.1 only. Read the no-login note above before you open it up.

GitHub only: give it a read-only token and the owners to track, and each of their public repos becomes a project.

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

Gitea or Forgejo only: give it your forge's address, a read-only token and the owners to track.

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

Both: set both sets of variables or write a config file, and a repo with the same name on both forges becomes one project.

# 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

Token scopes, private repos, Docker options, images and binaries are in the install guide⁠.

⁠Documentation

⁠About

Waymark started as a status page I built for my own homelab, to see all of my projects in one place. I adapted it so anyone with Gitea, Forgejo or GitHub can run it, in case others find it useful too.

⁠Licence

MIT. Made by Will Luck. See LICENSE⁠.