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:trixiecontainer (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 withpackaging/install-check-container.sh(needs Docker; not part ofmake ci).
| 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-libraryGetting 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-devand 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-devOn a headless server — no display libraries, no Allegro — build just what a server needs:
make server tools # darkchan-server + admin/cli/keygenOn a machine that will also run the GUI client, plain
make builds everything (and then needs the desktop packages
below):
make # client + server + toolsThat 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 ./dataFor 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-serverNo 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.)
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,BypassIt 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").
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 commandBefore publishing artifacts, two commands:
make docker-build # build the release artifacts (tagged with the codename)
make ci-packaging # then check them: ~10 minutes, needs dockermake 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 targetmake 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.
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 itselfThat 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,BypassIt 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 aloneDARKCHAN_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.
make client # or just `make`
./bin/darkchanThe 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.
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).
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.
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 + toolsDrop 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:
SIGHUP. Windows has no such signal,
so the server cannot be told to reload with kill -HUP. Use
darkchan-admin emoji-reload instead, which needs no signal
(it leaves a marker the server picks up within a second), or the in-app
admin screen's ADMIN_EMOJI_RELOAD (§11.6).
Ctrl+C still shuts down gracefully.SIGPIPE, which is simply one less
thing to handle: a write to a dead peer returns an error on Windows
rather than killing the process.darkchan_fchmod is a no-op — NTFS uses ACLs, not POSIX
modes, so the 0600 on key material is not enforced by the
filesystem. The at-rest encryption is what protects those files (§7.2);
restrict the data directory yourself if the machine has other
users.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.exeThese 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.
make installer-windows needs
makensis, packaged for both hosts:
pacman -S mingw-w64-x86_64-nsis # msys2
apt-get install nsis # Debian/UbuntuThe target refuses with that hint if makensis is
missing. It is not in make ci, like every
other windows* target.
What the installer does:
C:\Program Files\DarkChan (changeable on
the Directory page), which needs elevation;uninstall.exe;$INSTDIR as its
working directory. That is load-bearing, not tidiness:
the client resolves its fonts as DATA/fonts/<face>
relative to the working directory, so a shortcut started anywhere else
would launch a client with no font.What it deliberately does not do:
%APPDATA%\DarkChan. The client
creates its own store there on first run, as the logged-in user;%APPDATA%\DarkChan
alone. That directory holds the encrypted local store and the
device keys (§7.2 of CRYPTO.md); removing it would cost the
message history and, on a multi-device account, force the device to be
re-provisioned. Delete it by hand if you actually want it gone. The
uninstaller also removes only the files it installed, so anything you
put in the install directory survives — and so does the directory, which
is what tells you why;NiloreaStudio.cer into the install directory and the
uninstaller deletes that file; trusting it is a separate act (README,
"Windows: the signature");uninstall.exe it installs is signed
the same way.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.
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.
key.pem and cert.pem from the
machine that has them into its ~/.config/nilorea/signing —
in the MinGW64 shell that is
/home/<you>/.config/nilorea/signing — over a channel
you trust, and keep key.pem readable by you alone
(chmod 600).Makefile.windows carries WIN_SIGN_FINGERPRINT,
the SHA-256 the README publishes, and every signing step refuses a
certificate that is not that one: a file signed by a second
"NiloreaStudio" is worse than an unsigned file.
make WIN_SIGN_FINGERPRINT= ... (empty) signs with whatever
key is there.sh packaging/windows-sign.sh new-key makes a pair and
prints its fingerprint. It refuses when the directory already holds one.
Then build with your own
WIN_SIGN_FINGERPRINT=<that value>, or empty, and
publish your fingerprint instead of the README's.sha256sum build_windows/DarkChan/NiloreaStudio.cer (the
same value certutil -hashfile NiloreaStudio.cer SHA256
prints on Windows).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.exemake android # signed debug APK -> build_android/DarkChan-debug.apk
make android-release # signed release APK
make android-aab # Play Store bundlemake 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.apkThe 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/.
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/portalmake 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).
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.
The Markdown docs convert to a self-contained HTML set with an index:
make docs-html # -> dist/docs-html/index.html (needs pandoc)