Skip to content

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.

  • .NET 10 SDK, for the backend in src/
  • Node 24, for the frontend in frontend/

Start the backend. It serves the API on port 8990:

Terminal window
dotnet run --project src/Maki.Api

In a second terminal, start the frontend dev server on port 5173. It proxies /api and /signalr to the backend:

Terminal window
npm --prefix frontend run dev

Open 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:

Terminal window
MAKI_CONFIG_DIR="$PWD/.devconfig" dotnet run --project src/Maki.Api

Migrations apply on startup, as in the container.

Terminal window
dotnet test
dotnet publish src/Maki.Api -c Release

To build the Docker image yourself, run docker build -f distribution/docker/Dockerfile -t maki:local . from the repository root.

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.