Installing DarkChan

Installing DarkChan

DarkChan is self-hosted. One person runs the server; everyone else runs a client — a native app on Linux, Windows or Android, or the web portal in a browser. This page covers building and installing each of those.

Everything is built from source with make. There is no installer to download and no package repository — that is deliberate for a self-hosted messenger you are meant to be able to audit.

The Linux instructions below are executed as written in a clean debian:trixie container (nothing preinstalled), so the package lists are what a fresh machine actually needs rather than what happened to be on the author's. Re-check them yourself with packaging/install-check-container.sh (needs Docker; not part of make ci).


1. What you need

To build You need
Server + tools OpenSSL 3.0+ (libssl-dev), zlib (zlib1g-dev), a C99 compiler, make
Contributing clang-format 20 or newer for ./format-code.sh (older majors reformat files you did not touch; the script picks the newest it finds and refuses anything below 20) and cppcheck for make check
Desktop client the above plus Allegro 5 (liballegro5-dev + its addons)
darkchan-emoji Allegro too — it composes atlas pages with headless memory bitmaps, so a server that rebuilds the emoji pack needs the desktop packages (or build the pack elsewhere and copy data/emoji/ across)
Windows client, cross-built mingw-w64 on a Linux host (the build fetches and cross-builds OpenSSL and Allegro itself); nsis as well for make installer-windows; osslsigncode to sign what is staged (optional, §4.3)
Windows, built natively MSYS2 with its MinGW64 toolchain and packages, see §4.2
Android app Android SDK build-tools + NDK, a JDK
Web portal the Emscripten SDK; Node.js only to run its tests

Everything also needs nilorea-library checked out locally — it is compiled from source into the build, not linked from the system. Both repositories live on git.nilorea.net and are private: cloning needs an account with access, or a deploy key.

Tell the build where it is. The default is ../../nilorea-library, which suits a tree where DarkChan sits one level deeper than nilorea. If you clone the two side by side, pass the path instead:

git clone git@git.nilorea.net:private/nilorea-library.git
git clone git@git.nilorea.net:UTILS/DarkChan.git
cd DarkChan
make NILOREA=../nilorea-library

Getting this wrong produces No rule to make target 'bin/nil/n_common.o', which does not obviously mean "nilorea is not where I expected".

On Debian/Ubuntu the server-side prerequisites are:

sudo apt install build-essential pkg-config libssl-dev zlib1g-dev

and for the desktop client additionally:

sudo apt install liballegro5-dev liballegro-image5-dev liballegro-ttf5-dev \
                 liballegro-audio5-dev liballegro-acodec5-dev \
                 liballegro-dialog5-dev liballegro-physfs5-dev libx11-dev

2. Server (Linux)

On a headless server — no display libraries, no Allegro — build just what a server needs:

make server tools    # darkchan-server + admin/cli/keygen

On a machine that will also run the GUI client, plain make builds everything (and then needs the desktop packages below):

make                 # client + server + tools

That produces, under bin/:

Binary Purpose
darkchan-server the server
darkchan-admin approve users, manage roles, instances (operator CLI)
darkchan-emoji build / sign / inspect the emoji pack (needs Allegro, make emoji-tool)
darkchan-keygen generate key material
darkchan-cli headless client, useful for testing and scripting (login, send, sendfile, recv, mkchannel, push-register, delete-account, and bot, which stays online answering every incoming text — the Play review account's partner, see store/LISTING.md). --pass-file F reads the password from a file, for a service that must not carry it on its command line
darkchan the desktop GUI client

Run it straight away — with no arguments it uses ./data and port 7420 and generates a self-signed development certificate:

./bin/darkchan-server --data ./data

For anything long-lived, install it as a service instead:

sudo useradd --system --home /var/lib/darkchan --shell /usr/sbin/nologin darkchan
sudo install -m755 bin/darkchan-server bin/darkchan-admin bin/darkchan-emoji \
     /usr/local/bin/
sudo install -m644 packaging/darkchan-server.service /etc/systemd/system/
sudo install -m644 packaging/darkchan-server.default /etc/default/darkchan-server
sudo install -m755 packaging/darkchan-adm /usr/local/sbin/
sudo systemctl daemon-reload && sudo systemctl enable --now darkchan-server

No certificate step, and that is a fix rather than an omission. The unit used to pass --cert /etc/darkchan/cert.pem while also mounting that directory read-only, so a first start with nothing in it could not generate the self-signed fallback either and the server exited dev certificate generation failed into a restart loop. It now passes no certificate at all and self-signs into its data directory. Point it at a real one by setting DARKCHAN_EXTRA_ARGS in /etc/default/darkchan-server — native clients pin the server identity key rather than the chain (§7.2) and do not care either way, but browsers using the web portal warn until you do.

The unit runs as an unprivileged darkchan user, keeps state in /var/lib/darkchan (mode 0700), and is sandboxed (ProtectSystem=strict, NoNewPrivileges, restricted address families). Edit its flags in /etc/default/darkchan-server, not in the unit — see CONFIGURATION.md §1.1. On the packaged route the unit lives under /usr and dpkg replaces it on upgrade without asking, so an edit there would silently disappear; the /etc/default file is a conffile and survives.

darkchan-adm is the wrapper you should use for darkchan-admin afterwards: it runs it as the service user and stops the service around any command that writes. Both of those failure modes are silent — see OPERATIONS.md §3.

Then create the first admin, because a fresh server approves nobody:

darkchan-admin --data /var/lib/darkchan make-admin <username>

(Register that username from a client first; make-admin both promotes and activates it. Everyone else stays PENDING until an admin approves them.)

Deploying to a VPS in one command

packaging/deploy-vps.sh does everything above on a fresh Debian/Ubuntu host and is re-runnable — a second run pulls both repositories, rebuilds and restarts:

sudo packaging/deploy-vps.sh --instances Family,Bypass

It compiles on the server and needs both repositories there. The alternative is the package: install darkchan-server (below), and update it from your own machine with packaging/deploy-deb.sh, which builds the package in a container and installs it over SSH (OPERATIONS.md §10.1). A host this script installed moves to the package with packaging/migrate-to-deb.sh (OPERATIONS.md §10.2).

It creates the darkchan system user, lays the deployment out under one prefix (/opt/darkchan by default: the two clones under nilorea-library/ and Utils/DarkChan/, the built binaries in bin/, the data directory in data/), builds make server tools, writes a systemd unit pointed at that prefix, and installs darkchan-adm — a wrapper that runs darkchan-admin as the service user and stops the service around the commands that write to the store, which are the two ways a CLI edit gets silently lost (OPERATIONS.md §3). The prefix is root:darkchan 0750 and the binaries are root-owned, so the service can read its program and write only its data.

Useful flags: --identity-key <path> installs an existing server_identity.key before the first start so clients keep their TOFU pin; --cert/--key point at a real certificate; --clone-as <user> borrows another login's access to the private repositories on git.nilorea.net (its git runs in a staging copy outside the prefix, which that login cannot enter) — the alternative is a key in /opt/darkchan/.ssh/ added as a read-only deploy key on both repositories; --instances A,B renames the auto-created default instance to A and creates the rest, all closed. --help lists them all.

Note what it deliberately does not do: create accounts or mint invites. Neither is possible from the CLI — registration happens in a client, approval is darkchan-adm approve <user>, and an invite token is minted over the wire from a signed-in client (USER_GUIDE.md, "Instances").

Packaged builds

make install           # FHS install; honours PREFIX (default /usr/local) and DESTDIR
make deb               # all four Debian packages
make deb-server        # the server package alone — needs no Allegro toolchain
make appimage          # portable AppImage of the desktop client
make appimage-check    # RUN that AppImage in a container that has no Allegro
make docker-build      # reproducible release artifacts in a container
make deb-systemd-check # install the server .deb in a systemd container and RUN it
make ci-packaging      # ALL of the packaging checks, in one command

Before publishing artifacts, two commands:

make docker-build      # build the release artifacts (tagged with the codename)
make ci-packaging      # then check them: ~10 minutes, needs docker

make ci-packaging runs the deploy tooling suite with its real in-container deploy, executes INSTALL.md in a clean container, installs and drives all three .debs under systemd, and runs the AppImage where no Allegro exists. It builds nothing — it checks the newest release artifacts in dist/, preferring a codename-tagged one over a local build, and says plainly when one is missing. A check that cannot run here (no docker, no artifact) is reported as a skip rather than a pass, and the closing line always names the counts.

It is deliberately outside make ci, which must stay runnable anywhere: this needs a docker daemon, binds a fixed port and takes minutes.

make appimage-check is the only thing that ever runs the AppImage anywhere but the machine that built it. It starts a container with an X server and a GL driver and nothing else — no Allegro, no GTK, no DejaVu — and drives three pre-login screens through the client's own --screenshot hook, asserting that each one drew something and that all three differ. It is negative-controlled by deleting the bundled Allegro from a copy of the extracted AppImage, which must then fail to render.

It checks against Debian 13 (trixie) by default, because that is what make docker-build builds release artifacts on. glibc is backward-compatible only, so an AppImage from a plain make appimage on a rolling distribution runs on that glibc and newer — the check says so by name when it happens. Check a release artifact by passing it:

packaging/appimage-check.sh dist/DarkChan-<ver>-trixie-x86_64.AppImage
APPIMAGE_CHECK_IMAGE=debian:bookworm-slim packaging/appimage-check.sh   # older target

make install rewrites the systemd unit's ExecStart to $PREFIX/bin as it installs it, so the unit matches wherever the binaries actually landed. The copy in packaging/ names /usr/local/bin, which is what the manual route in §2 installs into; make install-check (in make ci) stages both prefixes and fails if the unit ever names a binary the install did not put down.

It is built from three components, which the Debian packaging installs one at a time and you can too:

make install-server    # darkchan-server, -admin, -keygen, -cli, the unit,
                       #   backup.sh / restore.sh, the portal assets if built
make install-client    # darkchan, desktop entry, icon, fonts, the bundled
                       #   starter emoji pack
make install-emoji     # darkchan-emoji, the pack-authoring tool, alone
make install-doc       # README, LICENCE, THIRD_PARTY_LICENSES, docs/*.md
                       #   into share/doc/$DOC_NAME (default: darkchan)

Both program components install man pages: darkchan-server, darkchan-admin, darkchan-adm and darkchan-server-setup in section 8, darkchan, darkchan-emoji, darkchan-keygen and darkchan-cli in section 1. The .debs also carry a copyright and a changelog, and their binaries are stripped — all three are lintian-clean, which deb-systemd-check asserts before it starts a container.

install-server installs nothing that links Allegro or X11 — that is what lets a headless host take the server without the GUI's dependency set, and install-check asserts it against the installed binaries rather than against this paragraph. darkchan-emoji is its own component because it sits between the two: composing atlas pages needs Allegro (§11.6), but the host that wants it is the server (§17's "drop a PNG on the server, run one command"), not the desktop.

Four packages, and which one you want

make deb builds four:

package what it is dependencies
darkchan-server server, darkchan-admin, darkchan-keygen, darkchan-cli, the systemd unit, backup.sh / restore.sh, the web portal assets if built nothing graphical — libc, OpenSSL, zlib
darkchan-client the desktop client, desktop entry, icon, fonts, bundled starter emoji pack Allegro 5 + X11 + the UI font
darkchan-emoji the sprite-pack authoring tool alone Allegro core + image, no GTK
darkchan metapackage pulling the other three, so the old single name still installs everything it used to the three above

On a server, install darkchan-server alone. Measured in a clean debian:trixie-slim: the server package pulls 1 package where the old single package pulled 150 — GTK3, X11, Wayland, Cairo and Pango, onto a machine with no display. (liballegro-dialog5.2 depends on libgtk-3-0, which is where most of them come from.) darkchan-server recommends the client rather than depending on it, so --no-install-recommends keeps the VPS lean.

If that server also hosts a sprite pack, add darkchan-emoji. Same image, measured the same way: 51 packages for the tool against 148 for the desktop client, and none of them GTK3 — the tool needs Allegro's core and its image addon and nothing else. It used to live in darkchan-client, which meant §17's "drop a PNG on the server, run one command" asked a headless VPS for the whole desktop set (D-036). It is suggested by darkchan-server and recommended by darkchan-client, so neither pulls it by surprise.

51 is better than 148 and it is not 2: Allegro's core links X11 whatever you do. An X11-free server host would need the tool to stop using Allegro altogether, which is written down and not done (DECISIONS D-036).

A package built elsewhere may not run. darkchan-emoji and the client link Allegro, and al_install_system refuses a binary built against a different Allegro major.minor.release — the same portability rule as glibc (D-034). Install the package built for your distribution; make docker-build produces codename-tagged ones for exactly this reason. The tool now says so by name when it happens.

Installing the server package gives you a running server. It creates the darkchan system user its unit runs as, creates /var/lib/darkchan (0700), and enables and starts the service:

sudo apt install ./darkchan-server_<version>_amd64.deb   # resolves deps itself

That is all. The server self-signs a certificate into its data directory on first boot, so there is nothing to place first, and new accounts land PENDING, so an open port is not an open door — nobody can log in until you approve them.

darkchan-server-setup does the rest, and it is everything deploy-vps.sh does after the build — the same code, shared through packaging/deploy-lib.sh, rather than the same intent written twice:

sudo darkchan-server-setup --instances Family,Bypass

It names the instances (the first renames the one the server creates on its first boot, the rest are created beside it, all closed), and prints the runbook for the parts no program can do: registering your own account, promoting it, and minting invites. Other options:

Option What it does
--identity-key PATH install an existing server_identity.key, so clients that already pinned it keep their pin (§7.2)
--replace-identity allow replacing one that is already there, keeping the old as .bak. Restoring onto a packaged install always needs this — installing the package starts the server, which generates a key immediately
--port N set DARKCHAN_PORT in /etc/default/darkchan-server and restart
--cert PATH --key PATH set the certificate in DARKCHAN_EXTRA_ARGS; make the key readable by the service user, and for a certbot path install the renewal hook that does so again at every renewal

Installing without a certificate prints the recipe for getting one — certbot, and the one command to point the server at it. The two steps that are skipped most and fail hardest are that command's job rather than the reader's: the key permissions (the server cannot start on a key it may not read, and certbot leaves it root-only) and the renewal hook (certbot writes a new root-only key at every renewal, so applying the permissions once is not enough). It stops printing once a certificate is configured, and an upgrade keeps that configuration — /etc/default/darkchan-server is a conffile.

With no options it prints the runbook and changes nothing.

Settings live in /etc/default/darkchan-server (a conffile: your edits survive upgrades). A real certificate goes in DARKCHAN_EXTRA_ARGS there, not in the unit — CONFIGURATION.md §1.1.

If you are upgrading from a package whose unit passed --cert /etc/darkchan/..., the postinst carries that certificate over into a systemd drop-in and says so on the console, rather than silently demoting a working TLS setup to a self-signed one. systemctl cat darkchan-server shows what is in effect.

Administer the server as the darkchan user, not as root — darkchan-admin run by root leaves records the service cannot read (OPERATIONS.md §3; the tool refuses and tells you the command to re-run).

make deb-systemd-check is the check behind all of this. Hand it a path to choose which package it examines — packaging/deb-systemd-check.sh dist/darkchan-client_*.deb asks the questions a desktop package raises (does every library its binaries need resolve from the declared Depends; does darkchan-emoji run; does it bring no service or system account; does the desktop entry point at things that exist; do the two packages coexist). With no argument it takes the newest server .deb and installs it in a real systemd container, starts the service, drives register → approve → systemctl reload → login → DM through it, puts a certbot-shaped certificate through a renewal (a new root-only key, the deploy hook, and the assertion that the renewed certificate reaches the wire in the same server process), drives a real UnifiedPush wake-up to an HTTP sink in the container for an offline recipient — once with ordinary files name resolution and once with nss-resolve, which is an AF_UNIX connect the unit's sandbox has to allow — and asserts that removing the package stops the service while purging it keeps /var/lib/darkchan. It also asserts the install pulled no Allegro/GTK/X11 — the property the split exists for, asked of dpkg rather than of a file list. It needs a Docker daemon and is outside make ci.

That gate is what caught the one real defect the split exposed: the unit's ExecReload ran /bin/kill, which lives in procps and is not installed on a minimal Debian host. systemctl reload darkchan-server had therefore never worked on a lean server — it only looked like it did, because the old package's 150 dependencies dragged procps in. It now goes through /bin/sh, whose kill is a builtin.

Removing the package stops the service; purging it keeps the darkchan user and /var/lib/darkchan, which hold the account database and the server identity key.

make docker-build needs Docker, and it builds inside a Debian container so the artifacts link that release's glibc rather than the host's. It mounts both source trees — DarkChan and nilorea-library — so the container needs to be told where nilorea is the same way the Makefile does, except that the variable is NILOREA_DIR (a script environment variable) rather than NILOREA:

make docker-build                                    # nilorea at ../../nilorea-library
NILOREA_DIR=../nilorea-library make docker-build     # side-by-side checkouts
BASE_IMAGE=debian:bookworm-slim make docker-build    # target an older release
DARKCHAN_DOCKER_WHAT=server packaging/docker-build.sh   # the server package alone

DARKCHAN_DOCKER_WHAT=server is the short build — no Allegro, no AppImage — and what packaging/deploy-deb.sh runs.

The web portal goes into the server package when the checkout has the WASM crypto module (make portal-wasm, §6): the portal is rebuilt on the host first (make portal-assets, which needs emscripten) and copied into the container, which needs none. The script says whether the package has a portal. DARKCHAN_PORTAL_PREBUILT=1 packages the module as already built instead of rebuilding it, and refuses when any of its sources is newer than it. Each package's changelog names the commit it was built from (-dirty when the tree had uncommitted changes).

The artifacts are tagged with the container's Debian codename (darkchan-server_<version>-trixie_amd64.deb, and likewise for the client and metapackage) to tell them apart from the generically versioned make deb / make appimage testing builds.


3. Desktop client (Linux)

make client           # or just `make`
./bin/darkchan

The client asks for a server address, a username and a password on first run. Nothing else needs configuring; its encrypted store is created under $XDG_DATA_HOME/darkchan (falling back to ~/.local/share/darkchan).

make install puts it in $PREFIX/bin/darkchan with its fonts and bundled emoji pack under $PREFIX/share/darkchan — the client resolves both relative to its own executable, so an installed binary finds them from any working directory. The AppImage is self-contained and needs no install at all.


4. Windows

There is no MSVC project. Two routes that build different things (§4.1, §4.2), and one set of packaging targets that works from either (§4.3).

4.1 Cross-compiled from Linux — the shippable client

make openssl-mingw       # once: cross-builds and pins OpenSSL for mingw64
make windows             # the full Allegro GUI client -> build_windows/

The result is a single statically linked .exe — no DLLs to ship alongside. Its store lives in %APPDATA%\DarkChan.

make windows-core builds only the Allegro-free client core (network, crypto, store); useful to verify the port compiles without building the GUI.

To hand the result to somebody, package it with §4.3.

4.2 Natively, inside MSYS2 / MinGW64

The ordinary make works from the MinGW64 shell (not the MSYS or UCRT64 one, unless every package below comes from the matching repository). It detects the host from uname -s and links Winsock (ws2_32), the CryptoAPI root store (crypt32) and bcrypt, gives the GUI client -mwindows so it opens no console window, and names its output bin/*.exe.

pacman -S --needed mingw-w64-x86_64-toolchain mingw-w64-x86_64-openssl \
                   mingw-w64-x86_64-zlib mingw-w64-x86_64-allegro \
                   mingw-w64-x86_64-pkgconf make git
make NILOREA=/path/to/nilorea-library      # client + server + tools

Drop mingw-w64-x86_64-allegro and build make server tools if you only want the headless side. bin/darkchan.exe carries the app icon and a version resource (packaging/darkchan.rc, compiled by msys2's windres), so Explorer, the taskbar and its Properties tab all show DarkChan and the version from android/version_name.txt. To hand the result to somebody, package it with §4.3.

make test does not build on Windows yet and is not part of this. The unit suite still uses mkdtemp and the POSIX socket headers in about seventy places across four files; porting it is a separate piece of work. What is checked for Windows, from a Linux host with mingw-w64 and (optionally) wine, is:

make windows-tools      # cross-link server + keygen + admin + cli at -Werror
make windows-net-test   # run the socket shim's own suite under wine
make windows-e2e-test   # run the server + CLI under wine: login, DM, files
make windows-gui-shots  # render every GUI screen under wine (needs a DISPLAY)

The last two skip cleanly when wine is not installed. None of the three is in make ci.

What differs from the POSIX build at run time, rather than at compile time:


4.3 Packaging what you built — the zip and the installer

make windows-stage       # assemble the payload -> build_windows/DarkChan/
make windows-zip         # that, zipped -> build_windows/DarkChan-windows.zip
make installer-windows   # NSIS setup.exe -> dist/DarkChan-<version>-setup.exe

These work from either route above, which matters because DarkChan is developed on a native msys2 host and also cross-built from Linux. windows-stage picks the binary by host — bin/darkchan.exe from the native make client in msys2, build_windows/DarkChan.exe from the cross make windows on Linux — and stages it as DarkChan.exe either way, so the installed program reads the same whichever route produced it. Override WIN_CLIENT_EXE and WIN_CLIENT_DEP to stage a binary the makefile did not build.

Both artifacts carry the same payload, assembled once into build_windows/DarkChan/: the .exe, DATA/ (the UI fonts and the bundled starter emoji pack), README.md, LICENSE, THIRD_PARTY_LICENSES and docs/*.md, plus NiloreaStudio.cer when the build signed its files (see "Signing" below). docs/DECISIONS.md is the one doc left out: it is the maintainer log. The staged .exe is stripped; the one the build left in build_windows/ or bin/ keeps its symbols.

Plus the runtime DLLs, on the native route only. The cross-built client is one static Allegro monolith with nothing beside it; the native msys2 client links that toolchain's Allegro, OpenSSL, FreeType, zlib and libwinpthread through pkg-config, so windows-stage runs ldd over it and copies those DLLs — and only those, never the Windows system ones — next to the .exe. Without them the installed client starts nowhere but a MinGW64 shell, and the failure lands on the user's machine as a missing-DLL dialog rather than on yours. The staging line reports how many it took.

The licence files are not optional either way: the same libraries are linked, statically on one route and shipped as DLLs on the other, and DATA/fonts carries the DejaVu faces.

Which one to hand people. The zip needs no privileges and leaves nothing behind — it is still the artifact §16 calls shippable. The installer is for people who expect a Start-menu entry and an Add/Remove Programs row.

The installer

make installer-windows needs makensis, packaged for both hosts:

pacman -S mingw-w64-x86_64-nsis   # msys2
apt-get install nsis              # Debian/Ubuntu

The target refuses with that hint if makensis is missing. It is not in make ci, like every other windows* target.

What the installer does:

What it deliberately does not do:

The .exe itself carries the app icon and a version resource (packaging/darkchan.rc), so Explorer, the taskbar and the Properties tab all show DarkChan, the company NiloreaStudio and the version from android/version_name.txt. The server and the tools (make windows-tools, or make server tools in msys2) link the same version block under their own file name, without the icon. The icon is packaging/darkchan.ico, generated by tools/gen-app-icon.py from the same first-party art as the Android launcher icons and verified by make check — so building the installer needs no image tooling.

Signing

windows-stage strips the staged DarkChan.exe and every DLL staged beside it (the msys2 ones of a native build), then signs them all; installer-windows signs the uninstaller while makensis packs it, and then the setup program; windows-tools strips and signs the four programs it links. The signature is Authenticode, made by packaging/windows-sign.sh with osslsigncode:

apt-get install osslsigncode                 # Debian/Ubuntu
pacman -S mingw-w64-x86_64-osslsigncode      # msys2, MinGW64 shell (§4.2)
WIN_SIGN=
auto (default) sign when osslsigncode and the key are both on the machine; otherwise build unsigned and print NOTHING IS SIGNED
1 fail when either is missing — use this for anything you hand out
0 sign nothing

OSSLSIGNCODE=<path> names the tool when it is not on PATH.

The uninstaller is signed from inside makensis (!uninstfinalize), which needs NSIS 3.08 or later and sh on the PATH when makensis runs — true in the MinGW64 shell and on Linux. If that step fails on some machine, the installer is not written; WIN_SIGN=0 builds it unsigned.

The certificate is self-signed, named NiloreaStudio, and shared by the NiloreaStudio projects so that a machine trusts one publisher once. Nobody vouches for it: Windows reports the signature as untrusted until the certificate is installed by hand (the README has the commands and the fingerprint). What it buys without that is a publisher name a security product can read and an administrator can allow once, for every file and every later build (D-135).

The key is outside the tree: key.pem and cert.pem in ~/.config/nilorea/signing ($XDG_CONFIG_HOME/nilorea/signing, or WINSIGN_DIR). Whoever holds key.pem can sign as this publisher; it has no passphrase, is mode 0600 and must never be committed.

A build never creates the key. On a machine without one, auto builds unsigned and says so, and 1 fails; both tell you to copy the key over.

No timestamp is requested, since that is a call to somebody else's server on every build; the certificate lasts ten years instead. WINSIGN_TIMESTAMP=<RFC 3161 URL> adds one. Check a signature from Linux with:

osslsigncode verify -CAfile ~/.config/nilorea/signing/cert.pem \
    -in build_windows/DarkChan/DarkChan.exe

5. Android app

make android          # signed debug APK  -> build_android/DarkChan-debug.apk
make android-release  # signed release APK
make android-aab      # Play Store bundle

make android needs the SDK build-tools and an NDK; it cross-builds OpenSSL itself (make openssl-android) and reuses Allegro from a sibling checkout, or builds it with make android-deps. Install a debug build with:

adb install -r build_android/DarkChan-debug.apk

The debug package is org.niloreastudio.darkchan.dev, so it installs alongside a release build rather than replacing it.

Builds ship arm64-v8a and armeabi-v7a by default — 64-bit for current devices, 32-bit so older ones are still served. Testing on an emulator needs the emulator's own ABI:

make android ANDROID_ABIS="arm64-v8a x86_64"

An arm64-only APK installs and runs on an x86_64 emulator while silently keeping the previous native library, so a native change appears not to take effect. Always build the ABI you are about to test on.

The native compile is -Werror. It is one clang invocation over first-party code, nilorea and the NDK / Allegro / OpenSSL headers together, so unlike the desktop build it cannot hold those at different warning levels — it stays at clang's default level, where every ABI is currently silent. A new NDK or Allegro release can add a warning that has nothing to do with your change; drop the flag to get unblocked, and treat what it printed as a bug to fix rather than as noise:

make android ANDROID_WERROR=

Release and bundle builds need a signing key — see CONFIGURATION.md. make android-aab additionally needs bundletool, which is not part of the SDK.

For notifications that survive Doze and app standby, users also install a UnifiedPush distributor: NTFY_SETUP.md.

Google Play assets — make store regenerates store/ (512 px icon, feature graphics, phone screenshots captured from the real desktop client on a private Xvfb, and the listing length check). It needs Xvfb, xdotool, ImageMagick and Pillow plus a built bin/. The foreground-service demo video is packaging/store-fgs-video.sh (an emulator; set EMU_SERIAL to reuse a running one). What to paste where in the Play Console is store/LISTING.md.

Emoji picker check — make picker-check drives the native picker with injected clicks on a private Xvfb and compares before/after screenshots of its grid (Xvfb and Pillow, like make store). make ui-sweep shoots the roster, a scrolled chat, the member view and Settings at three sizes and in every theme into contact sheets under build/ui-sweep/.


6. Web portal (browser client)

The server serves the portal over its own TLS connection. There is no separate web server, no CDN and no third-party host: the browser gets the same end-to-end encryption as the native apps, because the crypto is darkchan_crypto.c compiled to WebAssembly.

The browser is the weakest DarkChan client. Its key storage is the least protected of any target and the portal says so on screen. Read the honest security statement in the README before offering it to people.

Build it (needs Emscripten; separate from make and not part of make ci):

make portal-assets    # cross-builds OpenSSL for wasm, compiles the crypto to
                      # WASM, assembles the servable files with SRI hashes
                      # -> build_wasm/portal/

make portal does the same and also runs the portal's test suite (needs Node.js).

make portal-browser-smoke is a separate, optional check that loads the assembled portal in a real headless Chrome and asserts the TLS handshake, the SRI-guarded scripts, the CSP's wasm-unsafe-eval and the in-page crypto self-test all work. It is outside both make ci and make portal because it needs google-chrome (not a build dependency) and Node >= 22 — it drives the page over CDP with the global WebSocket, which older Node lacks. Override with CHROME=, PORT=, CDP_PORT= or SMOKE_TIMEOUT_MS=.

make portal-browser-ui is optional in the same way and has the same needs, plus Python 3 with Pillow (it draws its test pictures). It signs in to the portal in a phone-width headless Chrome and checks the conversation view against a second account driven by darkchan-cli. It asserts that a conversation opens at its newest message, that the ↓ jump-to-latest button appears only while you are scrolled up, and that the full-size picture viewer opens and closes.

Serve it by pointing the server at that directory — omit the flag and the portal stays off and non-API GETs return 404:

darkchan-server --data /var/lib/darkchan --portal-dir /path/to/build_wasm/portal

make install (and the .deb) copy an already-built portal to $PREFIX/share/darkchan/portal, so on a packaged install that is the directory to point --portal-dir at. The portal is not built by make, so a package built by make deb without make portal-assets first simply has no such directory; make docker-build runs that step itself when the WASM module is there (§3).

Open it at https://<server-host>:7420/. Users create an account, an admin approves it, and they sign in. The portal pins the server's identity key on first sign-in and warns if it ever changes.

Certificates matter more here than for native clients. Native clients pin the application identity key (TOFU) and are unaffected by a self-signed TLS cert; browsers are not, and will show a full-page warning. For a LAN server clicking through is defensible; for anything else give the server a real CA certificate (--cert / --key).


7. Checking the build

make test             # unit tests; when they pass, removes their scratch (test-clean)
make test-clean       # remove leftover test scratch (dc_*_*/ dirs, dc_*_test.pem); make clean runs it too
make check            # static analysis + the project's invariant checks
make ci               # the full gate (build, tests, cppcheck, ASan, TSan, licences, format)

make ci is what must be green before a release. The Android emulator suite (make android-emu-smoke) and the portal tests (make portal) live outside it because they need an emulator and a browser toolchain respectively.


8. Documentation as HTML

The Markdown docs convert to a self-contained HTML set with an index:

make docs-html        # -> dist/docs-html/index.html   (needs pandoc)