Build and run from source
For a normal install, use Docker Compose, Unraid, the Windows app or the Linux tarball. Run from source to change Maki or test a branch.
Prerequisites
Section titled “Prerequisites”- .NET 10 SDK, for the backend in
src/ - Node 24, for the frontend in
frontend/
Run it
Section titled “Run it”Start the backend. It serves the API on port 8990:
dotnet run --project src/Maki.ApiIn a second terminal, start the frontend dev server on port 5173. It proxies /api and /signalr
to the backend:
npm --prefix frontend run devOpen http://localhost:5173 for the app with hot reload, or http://localhost:8990 for the backend
with the frontend built into it.
Point MAKI_CONFIG_DIR at a throwaway folder so you do not touch a real library or database:
MAKI_CONFIG_DIR="$PWD/.devconfig" dotnet run --project src/Maki.ApiMigrations apply on startup, as in the container.
Tests and a release build
Section titled “Tests and a release build”dotnet testdotnet publish src/Maki.Api -c ReleaseTo build the Docker image yourself, run docker build -f distribution/docker/Dockerfile -t maki:local . from the repository root.
JPEG XL
Section titled “JPEG XL”Server upscaling and page conversion write JPEG XL through libjxl, which is not part of .NET. A Windows build downloads the pinned libjxl DLLs on its own (pass -p:SkipLibJxl=true to skip that). On Linux, build them with distribution/libjxl/build.sh, which needs git, cmake, ninja and a C++17 compiler. Without libjxl Maki still runs: upscaled colour pages are saved as WebP, and page conversion refuses a JPEG XL target.
The contribution guide covers the full setup and project layout.