doona
Development
Demo
English
Development

Development

Read CONTRIBUTING.md before opening a pull request. Its Translations section covers correcting a translation and proposing a language.

This documentation and the site built from it are in Zakkaus/doona-docs.

Commands

Run these from the repository root:

pnpm install --frozen-lockfile
pnpm build                       # writes dist/
pnpm check                       # types, lint, translations, formatting, unit tests, generated API types
pnpm check:size                  # gzip budgets for the dist/ build
pnpm e2e:install --with-deps     # once, for the browser tests
pnpm e2e                         # rebuild, then test against the mock at the root and under /ui/
pnpm package                     # release/doona-<version>.tar.gz, doona-fonts-<version>.tar.gz, SHA256SUMS

pnpm dev serves the mock on Vite's dev server. pnpm package uses the version in package.json; pnpm package --git-version uses git describe --tags --always without its leading v. Timestamps use SOURCE_DATE_EPOCH or the HEAD commit time.

Test against a live backend

For a read-only pass against a live backend, run DOONA_API=http://router:9527 DOONA_TOKEN=… pnpm e2e:live from the repository root. DOONA_API is required; omit DOONA_TOKEN when authentication is not required. The command runs accessibility, mobile-navigation and keyboard specs, rejects backend overrides in fixture storage, and aborts control requests, including DNS queries. Ordinary pnpm e2e runs reject DOONA_API unless DOONA_LIVE_OBSERVE=1 is explicitly set.

Screenshots

node tools/screenshots.mjs <url> docs/screenshots captures mock-backed pages in each language, the palette sheet, the English theme gallery, phone strips, page-tour stills and the routing animation as WebP. It requires cwebp, img2webp and Playwright's Chromium.

Source layout

Path Purpose
src/features/ Pages, their hooks and messages, one folder each
src/shell/ Application shell, navigation and search
src/ui/ Shared components, theme and icons
src/api/ Client, backend profiles, engine adapters and generated types
mock/ Mock backend for the demo, previews and tests
src/store/ Resource watching, cached reads and action hooks
src/i18n/ Translations and locale helpers
contract/ The vendored OpenAPI contract and its pin
public/ Static icons, manifest and service worker
e2e/ Browser tests
tools/ Build, packaging, conformance and screenshot tools
install/ nfpm configs, OpenWrt, Alpine, Gentoo and Nix recipes
docs/ Country-flag and font documentation
node_modules/@fontsource-variable/ Noto Sans TC/SC font sources bundled by Vite

The screenshot tool creates docs/screenshots/ when run; screenshots are not part of the source tree.

Contract

SOURCE.md records the pin of openapi.yaml. After moving the pin, run pnpm gen:api to regenerate src/api/types.ts. node tools/conformance.mjs http://router:9527 --token … checks a live backend's discovery, capabilities and read-only responses against the contract without sending a mutation.

See CHANGELOG.md for release notes.

doona lite

The doona lite source is in apps/lite, with its own lockfile. Install both sets of dependencies from the doona repository root, then build lite:

pnpm install --frozen-lockfile
pnpm --dir apps/lite install --frozen-lockfile
pnpm --dir apps/lite build

The output is apps/lite/dist. Use pnpm --dir apps/lite dev for the development server. lite has its own UI and state, and reuses the standard edition’s API client and generated types; see backend requirements.

doona

doona documentation

English
doona documentationFor a direct-only first run, follow Quick start. Quick startStart the standard edition of doona with a direct-only honk configuration, sign in, and verify traffic from the gateway itself. Standard edition and doona liteThe standard edition manages configuration and observes traffic. Requirements Install on Debian or UbuntuInstall doona from the doona-web .deb package and honk-core from the same release on Debian, Ubuntu or another APT-based system. Install on Fedora or RHELInstall doona from its .rpm package and honk-core from the same release on Fedora, RHEL or another DNF-based system. Install on Arch LinuxInstall doona from its .pkg.tar.zst package and honk-core from the same release on Arch Linux or another pacman-based system. Install on GentooInstall doona with Portage from the repository's ebuild in a local ebuild repository, and honk-core from the same release. Install on OpenWrtInstall doona from a release package or archive and honk-core from the same release on OpenWrt 25.12. Install on other systemsInstall doona and honk-core from release archives on an x86_64 or aarch64 Linux system that meets the kernel requirements below. Installation detailsInstall honk, write its configuration, then install doona and start honk. Minimal configurationThis page writes the smallest honk configuration that starts honk and serves doona, then checks it by starting honk by hand. Service managementThis page runs honk as a systemd or OpenWrt procd service: it creates the service once, then lists the commands that start, stop, restart and reload honk and read its log. Route your first connectionContinue from Quick start, with honk running and your administrator signed in. First sign-inThis page opens doona in a browser, creates the administrator account and checks that doona shows the running honk. Interface tourUse the navigation to open a page, the top bar to search or refresh, and the page tabs to change views. Watching trafficUse Activity and System status to read engine health, and Connections, Routing log and DNS to inspect traffic. Routing, nodes and rulesPolicies manages group selection and membership. Config and settingsConfiguration reads, validates and applies honk's configuration files. Common tasksThis page covers the standard edition; for doona lite, see doona lite. FeaturesFor each feature’s prerequisites and disabled-action explanations, see Feature requirements. doona litedoona lite edits honk configuration through a smaller interface for beginners. Connect doona liteConnect doona lite to the honk native API, or open the demo without a backend. Common tasks in doona liteUse doona lite to import resources and edit honk configuration. ConfigurationUse this reference for honk's DAE settings exposed by doona, their defaults, and their application paths. What doona can changedoona changes configuration sources, runtime state, persistent geodata settings, and browser preferences through different controls. Feature requirementsFind your standard-edition feature in the table, then use its section to check prerequisites and enable it. Troubleshooting DevelopmentRead CONTRIBUTING.md before opening a pull request.