FreeIPA server container: running a systemd identity stack in OCI

A build recipe set, not an application

The freeipa-container repository is easier to understand once you drop the expectation of an application. What it contains are Dockerfiles and additional files for creating FreeIPA server container images from the official yum and dnf repositories of multiple Linux distributions. There is no server code here. The images are built automatically and pushed to quay.io and Docker Hub, and the full canonical pull path is either `quay.io/freeipa/freeipa-server:<tag>` or `docker.io/freeipa/freeipa-server:<tag>`. The tag matches the Dockerfile suffix, so it tells you the operating system the image is based on. The choice of OS and version is left to you, and the README makes the argument that newer versions are typically better and are useful for testing interoperability with the latest FreeIPA, while for long term production setups Fedora might be updating too quickly and sometimes be too new compared to the other systems.

Why the tag suffix decides your upgrade path

The version tags carry a maintenance decision that the README spells out. The images get rebuilt regularly with the latest version of both FreeIPA and its dependent packages in the given operating system version, for security and bug fixes. That means a tag is not a frozen artefact. The registry also carries more specific tags that identify the FreeIPA version inside the image, and the README notes that the underlying dependency packages could have been updated many times even if the FreeIPA packages stayed the same. If you need stricter control over which builds enter your deployments, the documented path is to tag the images into your own namespace or push them to your own registry and run a testing, stage and production regression process. The README also issues a blunt warning: establish an upgrade plan before putting these containers into production, or you will find yourself with an end-of-life FreeIPA cluster with known security issues three years later.

Systemd inside the container changes the runtime requirements

This is where the project parts ways with the usual container story. The FreeIPA container runs systemd to manage all the necessary services within a single container, and the README warns that running a systemd based container may require special handling or parameters passed to the runtime. Its advice for debugging is to simplify: retry with plain podman or docker instead of continuing with more complex orchestration like docker-compose or Kubernetes, and get plain systemd running in the container properly first. One boundary is drawn explicitly, that privileged setup is not supported and will not work, since the goal is to keep the FreeIPA server container reasonably isolated from the host and the host from the container. With podman, a normal `podman run` is typically enough and works for rootless setups as well. The repository supports that with a set of host-side files, among them a hostname helper, a hostnamectl wrapper, an exit-with-status script, a container-ipa.target and systemd service units for configuring the first boot and for the self upgrade.

Building an image for one distribution locally

For development or debugging, the README describes using the `-f` option of `podman build` or `docker build` to pick the Dockerfile for a specific operating system and version. Two examples are given, one for AlmaLinux 10 packages with podman and one for Fedora rawhide with docker:

    podman build -t localhost/freeipa-server -f Dockerfile.almalinux-10 .

    docker build -t localhost/freeipa-server -f Dockerfile.fedora-rawhide .

You should see the image tagged `localhost/freeipa-server` in your local store, with a Dockerfile suffix matching the distribution you named. The note about the docker daemon matters if you use the moby engine, because the daemon needs to be running. The available Dockerfiles cover AlmaLinux 8, 9 and 10, CentOS Stream 9 and 10, Fedora 43, 44 and rawhide, RHEL 8, 9 and 10, and Rocky 8 and 9, and the top level of the repository also carries a `ci/` directory, a `tests/` directory and platform specific configuration files such as ipaplatform-fedora.conf and ipaplatform-rhel.conf.

cgroups, userns and the SELinux boolean

The runtime requirements are the part of the documentation most likely to cost you an afternoon. Rootless docker is supported only on systems with cgroups v2, determined by the existence of `/sys/fs/cgroup/cgroup.controllers`, and it may then be necessary to use the `docker run` option `--cgroupns=host -v /sys/fs/cgroup:/sys/fs/cgroup:rw`. With a rootful docker daemon, user namespace remapping may be needed so the container cgroup is created and mounted read-write as systemd expects, with the `userns-remap` set to `default` in `/etc/docker/daemon.json` and a restart of the docker service afterwards. The README notes that this isolates the container root from the host root, which is good in general, but that it is a global daemon configuration affecting other containers too. On systems with cgroups v1, a hybrid setup is often present with cgroups v2 at `/sys/fs/cgroup/unified`, and the option `-v /sys/fs/cgroup/unified:/sys/fs/cgroup:rw` should work. On SELinux enabled systems, the boolean `container_manage_cgroup` may need to be enabled with `setsebool -P container_manage_cgroup 1`.

The /data volume holds everything the server writes

All configuration, data and logs live on the volume mounted to `/data` inside the container, and the README shows creating a directory on the host to hold that server data:

    mkdir ipa-data

The container is then started with that directory mounted, and the same shape is given for podman and for docker, with `--read-only` on the container root and a `:Z` relabel on the volume:

    podman run --name freeipa-server-container -ti \
        -h ipa.example.test --read-only \
        -v $(pwd)/ipa-data:/data:Z <image> [ ... ]

    docker run --name freeipa-server-container -ti \
        -h ipa.example.test --read-only \
        -v $(pwd)/ipa-data:/data:Z <image> [ ... ]

When running in rootless mode, the volume directory on the host has to be owned by the uid that becomes uid 0 in the container. You can also let the container system manage the volume with `podman volume create freeipa-data` and then mount it the same way. The repository carries volume related helpers such as volume-data-autoupdate, volume-data-list and volume-tmp-list, plus ipa-volume-upgrade-1.0-1.1 and ipa-volume-upgrade-1.1-2.0 for moving stored data between format versions.

First start turns the container into a master

The first invocation against an empty `/data` is the moment the server is actually created. The container runs `ipa-server-install` or `ipa-replica-install` to configure a FreeIPA master or a replica, and the README gives the interactive form for podman:

    podman run -ti -h ipa.example.test --read-only \
        -v /var/lib/ipa-data:/data:Z \
        <image> ipa-server-install -r EXAMPLE.TEST --no-ntp

The trailing arguments after the image name are passed to the install command, which is how the EXAMPLE.TEST domain name and the no-ntp choice are supplied. The hostname flag matters because FreeIPA binds certificates and DNS to the server name, and the documentation is careful to point out that prior experience with FreeIPA is definitely useful, because in an ideal case the container simplifies setup but in practice it can be more challenging than other typical containerized workloads. The general FreeIPA documentation is the reference for everything that is not specific to running it containerized. The host entry point, `ipa-server-configure-first` with its systemd service unit, is what performs this first boot sequence.

Where the container route stops being the right route

Three limits are clear from the documentation. First, this is a deployment of a stateful, systemd based, certificate issuing identity provider, and the container image does not change that. The images are rebuilt regularly, so the artefact you test is not necessarily the artefact you run, which is exactly the risk the README's own warning about an end-of-life cluster three years out is pointing at. Second, the CPU microarchitecture requirement bites at the edges: processes in containers run natively on the machine CPU, so the image has to be compiled for a level the CPU supports, and the `:almalinux-10` tag fails on x86_64 CPUs that are not of `x86-64-v3` level with a fatal glibc error. Third, the isolation story is deliberately partial. The container wants to be reasonably isolated from the host, privileged setup does not work, and the userns-remap route is a global daemon setting that changes behaviour for every other container on that host. If your requirement is a lightweight directory service for a handful of users, a full FreeIPA with its own CA, DNS and replication concepts is a heavy answer regardless of the packaging.

Editorial conclusion

The FreeIPA server container is the right choice for lab work, interoperability testing and short lived deployments where you want a real FreeIPA master or replica that you can throw away, and the wrong choice for a long lived production cluster unless you build the upgrade and regression process the README warns about. Before you deploy, pick the distribution and version deliberately from the available Dockerfile suffixes, confirm your host runs cgroups v2 and that the CPU supports the microarchitecture level the image was compiled for, and set up the /data volume with the right ownership. The last push was on 2026-10-04, the images are rebuilt regularly, and the code is Apache-2.0 licensed with a separate LICENSE-2.0 file in the repository.

Frequently asked questions

Official sources

1. freeipa/freeipa-container on GitHub
2. Issues
3. License: Apache-2.0
4. Project website
5. README