Install on Gentoo

Install doona with Portage from the repository's ebuild in a local ebuild repository, and honk-core from the same release. Then continue with Minimal configuration.

Note

Download the beta.19 assets from the release page.

Before you start

• Linux 6.12 or later and the kernel options listed in Requirements. Check the kernel with uname -r.
• A user account with sudo, or a root shell. Commands that need root have a sudo tab and a root tab; pick the one that matches your shell.
• net-misc/curl and app-misc/ca-certificates. honk uses the system CA certificates to verify HTTPS downloads.
• Access to github.com.
• Run every step in the same terminal: later steps use the REPO, VERSION, PV, BASE and TARGET variables that earlier steps set.

For lite, ensure curl and CA certificates are installed, then go directly to 5. Install doona and select the doona lite tab. Skip the standard edition’s package, repository, download and verification steps before it.

1. Create a local repository

Set REPO to the repository path. If you already have a local ebuild repository, set REPO to its path and skip the rest of this step.

REPO=/var/db/repos/local

Create the repository and register it with Portage:

sudo mkdir -p "$REPO/metadata" "$REPO/profiles" /etc/portage/repos.conf
echo local | sudo tee "$REPO/profiles/repo_name"
printf 'masters = gentoo\nauto-sync = false\n' | sudo tee "$REPO/metadata/layout.conf"
printf '[local]\nlocation = %s\n' "$REPO" | sudo tee /etc/portage/repos.conf/local.conf
portageq get_repos /

mkdir -p "$REPO/metadata" "$REPO/profiles" /etc/portage/repos.conf
echo local > "$REPO/profiles/repo_name"
printf 'masters = gentoo\nauto-sync = false\n' > "$REPO/metadata/layout.conf"
printf '[local]\nlocation = %s\n' "$REPO" > /etc/portage/repos.conf/local.conf
portageq get_repos /

The last command lists local next to gentoo.

2. Add the doona ebuild

Set the release version and its Gentoo form. The ebuild is fetched from the v0.1.0-beta.19 tag commit, and its download URLs follow PV.

VERSION=0.1.0-beta.19
PV=0.1.0_beta19
RAW=https://raw.githubusercontent.com/Zakkaus/doona/v${VERSION}/install/gentoo/net-proxy/doona
sudo mkdir -p "$REPO/net-proxy/doona"
cd "$REPO/net-proxy/doona"
sudo curl -fL -o "doona-$PV.ebuild" "$RAW/doona-$PV.ebuild" -O "$RAW/metadata.xml"
cd -

VERSION=0.1.0-beta.19
PV=0.1.0_beta19
RAW=https://raw.githubusercontent.com/Zakkaus/doona/v${VERSION}/install/gentoo/net-proxy/doona
mkdir -p "$REPO/net-proxy/doona"
cd "$REPO/net-proxy/doona"
curl -fL -o "doona-$PV.ebuild" "$RAW/doona-$PV.ebuild" -O "$RAW/metadata.xml"
cd -

3. Download and verify the doona archives

The ebuild installs the release’s program archive and, with the default fonts USE flag, its font archive. Download both with SHA256SUMS and check them.

BASE=https://github.com/Zakkaus/doona/releases/download/v$VERSION
curl -fL -O "$BASE/doona-${VERSION}.tar.gz" -O "$BASE/doona-fonts-${VERSION}.tar.gz" -O "$BASE/SHA256SUMS"
grep -E " doona(-fonts)?-${VERSION}\.tar\.gz\$" SHA256SUMS | sha256sum -c -

You should see:

doona-0.1.0-beta.19.tar.gz: OK
doona-fonts-0.1.0-beta.19.tar.gz: OK

4. Hand the archives to Portage

Copy the checked archives into the distfiles directory under the names the ebuild expects, then write the repository’s Manifest from them.

DISTDIR=$(portageq distdir)
sudo cp "doona-${VERSION}.tar.gz" "$DISTDIR/doona-$PV.tar.gz"
sudo cp "doona-fonts-${VERSION}.tar.gz" "$DISTDIR/doona-$PV-fonts.tar.gz"
sudo ebuild "$REPO/net-proxy/doona/doona-$PV.ebuild" manifest

DISTDIR=$(portageq distdir)
cp "doona-${VERSION}.tar.gz" "$DISTDIR/doona-$PV.tar.gz"
cp "doona-fonts-${VERSION}.tar.gz" "$DISTDIR/doona-$PV-fonts.tar.gz"
ebuild "$REPO/net-proxy/doona/doona-$PV.ebuild" manifest

The last command prints >>> Creating Manifest for and the package directory, /var/db/repos/local/net-proxy/doona by default.

5. Install doona

With ui: embedded, the honk debug.2026.10.9.native-api.2 assets for doona beta.19 (commit eac5e0c5fba5078a7ff4517a3e3851e7fa0f4f8e) serve bundled doona 0.1.0-beta.19 without a separate UI package. You can also serve the beta.19 package installed here with ui: /usr/share/doona; see Minimal configuration.

The ebuild is keyworded testing (~amd64, ~arm64 and others), so accept it for this package first. Replace ~amd64 with your architecture’s keyword.

For doona lite, use the archive; there are no lite distribution packages yet. Follow Install doona lite, set ui: /usr/share/doona-lite, then continue with the honk steps on this page. Choose the tab for your edition and shell.

sudo mkdir -p /etc/portage/package.accept_keywords
echo 'net-proxy/doona ~amd64' | sudo tee /etc/portage/package.accept_keywords/doona
sudo emerge --ask net-proxy/doona
ls -l /usr/share/doona/index.html

mkdir -p /etc/portage/package.accept_keywords
echo 'net-proxy/doona ~amd64' > /etc/portage/package.accept_keywords/doona
emerge --ask net-proxy/doona
ls -l /usr/share/doona/index.html

VERSION=0.1.0-beta.19
BASE=https://github.com/Zakkaus/doona/releases/download/v$VERSION
curl -fL -O "$BASE/doona-lite-${VERSION}.tar.gz" -O "$BASE/SHA256SUMS"
grep " doona-lite-${VERSION}.tar.gz\$" SHA256SUMS | sha256sum -c -
sudo mkdir -p /usr/share/doona-lite
sudo tar -xzf "doona-lite-${VERSION}.tar.gz" -C /usr/share/doona-lite
ls -l /usr/share/doona-lite/index.html

VERSION=0.1.0-beta.19
BASE=https://github.com/Zakkaus/doona/releases/download/v$VERSION
curl -fL -O "$BASE/doona-lite-${VERSION}.tar.gz" -O "$BASE/SHA256SUMS"
grep " doona-lite-${VERSION}.tar.gz\$" SHA256SUMS | sha256sum -c -
mkdir -p /usr/share/doona-lite
tar -xzf "doona-lite-${VERSION}.tar.gz" -C /usr/share/doona-lite
ls -l /usr/share/doona-lite/index.html

For lite, ls must list /usr/share/doona-lite/index.html. Continue at 6. Choose the honk-core build; skip the standard edition results and optional packages below. In Minimal configuration, set ui to /usr/share/doona-lite.

For the standard edition:

Portage ends with Point the engine's ui setting at /usr/share/doona, or serve that directory with any web server., and ls prints a line ending in /usr/share/doona/index.html. The package holds doona’s web files and documentation; it installs no service. Set USE=-fonts for net-proxy/doona to leave out the Noto Sans TC and SC fonts.

6. Choose the honk-core build

uname -m

The release carries eight honk-core archives, named honk-core-debug-<target>.tar.gz. Build the target from the machine type and the C library:

For example, x86_64-unknown-linux-musl, aarch64-unknown-linux-gnu or x86_64-unknown-linux-musl-stock.

7. Download and verify honk-core

Set TARGET to the build you chose, then download it from the same release and check it against the same SHA256SUMS.

TARGET=x86_64-unknown-linux-musl
curl -fL -O "$BASE/honk-core-debug-$TARGET.tar.gz"
grep " honk-core-debug-$TARGET.tar.gz\$" SHA256SUMS | sha256sum -c -

You should see:

honk-core-debug-x86_64-unknown-linux-musl.tar.gz: OK

8. Install honk-core

The archive holds one directory with the honk-core binary. Install it as /usr/local/bin/honk-core, the path the service in Service management starts.

tar -xzf honk-core-debug-$TARGET.tar.gz
sudo install -m 0755 honk-core-debug-$TARGET/honk-core /usr/local/bin/honk-core
/usr/local/bin/honk-core --version

tar -xzf honk-core-debug-$TARGET.tar.gz
install -m 0755 honk-core-debug-$TARGET/honk-core /usr/local/bin/honk-core
/usr/local/bin/honk-core --version

The last command prints the honk build, for example:

honk-core debug.2026.10.9.native-api.2

HONK-SOURCE.txt in the same release records the honk build and links both its source and the matching doona source.

Before starting honk, follow Directories and geodata to install geosite.dat and geoip.dat.

Next: Minimal configuration. The service steps cover systemd and OpenWrt’s procd only; doona and honk ship no OpenRC script. With OpenRC, Service management gives the foreground command that runs honk for the first sign-in.

If it doesn’t work

For problems after installation, see Troubleshooting.