Getting Started (for Developers)


See the designs folder, and compile the private documentation locally:

cargo doc --document-private-items --open --no-deps

Rust Documentation

A list of links to the library documentation is at

Minimum Supported Rust Version

The MSRV is specified in the package Cargo.toml files.

Build Profiles

Setting different developer profiles while building is done by setting the environment variable KANIDM_BUILD_PROFILE to one of the bare filename of the TOML files in /profiles.

For example, this will set the CPU flags to "none" and the location for the Web UI files to /usr/share/kanidm/ui/pkg:

KANIDM_BUILD_PROFILE=release_suse_generic cargo build --release --bin kanidmd



You will need rustup to install a Rust toolchain.


You will need rustup to install a Rust toolchain. If you're using the Tumbleweed release, it's packaged in zypper.

You will also need some system libraries to build this:

libudev-devel sqlite3-devel libopenssl-devel


You need to install the Rust toolchain packages:

rust cargo

You will also need some system libraries to build this:

systemd-devel sqlite-devel openssl-devel pam-devel

Building the Web UI requires additional packages:

perl-FindBin perl-File-Compare rust-std-static-wasm32-unknown-unknown


You need rustup to install a Rust toolchain.

You will also need some system libraries to build this, which can be installed by running:

sudo apt-get install libsqlite3-dev libudev-dev libssl-dev pkg-config libpam0g-dev

Tested with Ubuntu 20.04 and 22.04.


You need rustup to install a Rust toolchain.

An easy way to grab the dependencies is to install vcpkg.

This is how it works in the automated build:

  1. Enable use of installed packages for the user system-wide:
vcpkg integrate install
  1. Install the openssl dependency, which compiles it from source. This downloads all sorts of dependencies, including perl for the build.
vcpkg install openssl:x64-windows-static-md

There's a powershell script in the root directory of the repository which, in concert with openssl will generate a config file and certs for testing.

Get Involved

To get started, you'll need to fork or branch, and we'll merge based on pull requests.

If you are a contributor to the project, simply clone:

git clone

If you are forking, then fork in GitHub and clone with:

git clone
cd kanidm
git remote add myfork<YOUR USERNAME>/kanidm.git

Select an issue (always feel free to reach out to us for advice!), and create a branch to start working:

git branch <feature-branch-name>
git checkout <feature-branch-name>
cargo test

When you are ready for review (even if the feature isn't complete and you just want some advice):

  1. Run the test suite: cargo test --workspace
  2. Ensure rust formatting standards are followed: cargo fmt --check
  3. Try following the suggestions from clippy, after running cargo clippy. This is not a blocker on us accepting your code!
  4. Then commit your changes:
git commit -m 'Commit message' ...
git push <myfork/origin> <feature-branch-name>

If you receive advice or make further changes, just keep committing to the branch, and pushing to your branch. When we are happy with the code, we'll merge in GitHub, meaning you can now clean up your branch.

git checkout master
git pull
git branch -D <feature-branch-name>


If you are asked to rebase your change, follow these steps:

git checkout master
git pull
git checkout <feature-branch-name>
git rebase master

Then be sure to fix any merge issues or other comments as they arise. If you have issues, you can always stop and reset with:

git rebase --abort

Development Server Quickstart for Interactive Testing

After getting the code, you will need a rust environment. Please investigate rustup for your platform to establish this.

Once you have the source code, you need encryption certificates to use with the server, because without certificates, authentication will fail.

We recommend using Let's Encrypt, but if this is not possible, please use our insecure certificate tool (

NOTE: Windows developers can use insecure_generate_tls.ps1, which puts everything (including a templated confi gfile) in $TEMP\kanidm. Please adjust paths below to suit.

The insecure certificate tool creates /tmp/kanidm and puts some self-signed certificates there.

You can now build and run the server with the commands below. It will use a database in /tmp/kanidm.db.

Create the initial database and generate an admin username:

cargo run --bin kanidmd recover_account -c ./examples/insecure_server.toml admin
Success - password reset to -> Et8QRJgQkMJu3v1AQxcbxRWW44qRUZPpr6BJ9fCGapAB9cT4

Record the password above, then run the server start command:

cd kanidmd/daemon
cargo run --bin kanidmd server -c ../../examples/insecure_server.toml

(The server start command is also a script in kanidmd/daemon/

In a new terminal, you can now build and run the client tools with:

cargo run --bin kanidm -- --help
cargo run --bin kanidm -- login -H https://localhost:8443 -D anonymous -C /tmp/kanidm/ca.pem
cargo run --bin kanidm -- self whoami -H https://localhost:8443 -D anonymous -C /tmp/kanidm/ca.pem

cargo run --bin kanidm -- login -H https://localhost:8443 -D admin -C /tmp/kanidm/ca.pem
cargo run --bin kanidm -- self whoami -H https://localhost:8443 -D admin -C /tmp/kanidm/ca.pem

Raw actions

The server has a low-level stateful API you can use for more complex or advanced tasks on large numbers of entries at once. Some examples are below, but generally we advise you to use the APIs or CLI tools. These are very handy to "unbreak" something if you make a mistake however!

# Create from json (group or account)
kanidm raw create -H https://localhost:8443 -C ../insecure/ca.pem -D admin example.create.account.json
kanidm raw create  -H https://localhost:8443 -C ../insecure/ca.pem -D idm_admin

# Apply a json stateful modification to all entries matching a filter
kanidm raw modify -H https://localhost:8443 -C ../insecure/ca.pem -D admin '{"or": [ {"eq": ["name", "idm_person_account_create_priv"]}, {"eq": ["name", "idm_service_account_create_priv"]}, {"eq": ["name", "idm_account_write_priv"]}, {"eq": ["name", "idm_group_write_priv"]}, {"eq": ["name", "idm_people_write_priv"]}, {"eq": ["name", "idm_group_create_priv"]} ]}' example.modify.idm_admin.json
kanidm raw modify -H https://localhost:8443 -C ../insecure/ca.pem -D idm_admin '{"eq": ["name", "idm_admins"]}' example.modify.idm_admin.json

# Search and show the database representations
kanidm raw search -H https://localhost:8443 -C ../insecure/ca.pem -D admin '{"eq": ["name", "idm_admin"]}'

# Delete all entries matching a filter
kanidm raw delete -H https://localhost:8443 -C ../insecure/ca.pem -D idm_admin '{"eq": ["name", "test_account_delete_me"]}'

Building the Web UI

NOTE: There is a pre-packaged version of the Web UI at /kanidmd_web_ui/pkg/, which can be used directly. This means you don't need to build the Web UI yourself.

The Web UI uses Rust WebAssembly rather than Javascript. To build this you need to set up the environment:

cargo install wasm-pack

Then you are able to build the UI:

cd kanidmd_web_ui/

To build for release, run

The "developer" profile for kanidmd will automatically use the pkg output in this folder.

Build a Kanidm Container

Build a container with the current branch using:

make <TARGET>

Check make help for a list of valid targets.

The following environment variables control the build:

ENV variableDefinitionDefault
IMAGE_BASEBase location of the container image.kanidm
IMAGE_VERSIONDetermines the container's tag.None
CONTAINER_TOOL_ARGSSpecify extra options for the container build tool.None
IMAGE_ARCHPassed to --platforms when the container is built.linux/amd64,linux/arm64
CONTAINER_BUILD_ARGSOverride default ARG settings during the container build.None
CONTAINER_TOOLUse an alternative container build tool.docker
BOOK_VERSIONSets version used when building the documentation book.master

Container Build Examples

Build a kanidm container using podman:

CONTAINER_TOOL=podman make build/kanidmd

Build a kanidm container and use a redis build cache:

CONTAINER_BUILD_ARGS='--build-arg "SCCACHE_REDIS=redis://"' make build/kanidmd

Automatically Built Containers

To speed up testing across platforms, we're leveraging GitHub actions to build containers for test use.

Whenever code is merged with the master branch of Kanidm, containers are automatically built for kanidmd and radius. Sometimes they fail to build, but we'll try to keep them available.

To find information on the packages, visit the Kanidm packages page.

An example command for pulling and running the radius container is below. You'll need to authenticate with the GitHub container registry first.

docker pull
docker run --rm -it \
    -v $(pwd)/kanidm:/data/kanidm \

This assumes you have a kanidm client configuration file in the current working directory.

Building the Book

You'll need mdbook to build the book:

cargo install mdbook

To build it:

cd kanidm_book
mdbook build

Or to run a local webserver:

cd kanidm_book
mdbook serve