Please note that this is work in progress.

Run kolab with all components on a single host.

This deployment consists of a single vm, and all workloads are executed in k3s.

This is the simplest deployment mode and suitable if the workload load fits on a single system,
and downtime for maintenance or failure is acceptable.

Setup Instructions

Please also see About Kolab on Kubernetes Deployments

Executed from the control host.

Create a directory where you intend to manage the kolab installation from
Download the latest release here: https://mirror.apheleia-it.ch/pub/kolab-kubernetes-latest.tar.gz
Extract the tarball: tar xf kolab-kubernetes-latest.tar.gz
Copy deployments/k3s-single-node/inventory.example.yaml to inventory.yaml
Adjust the new inventory.yaml, by default it will deploy everything on localhost
Run the ansible provisioning process: ansible-playbook -v -i inventory.yaml -D deployments/k3s-single-node/ansible/playbook.yaml
Navigate to the configured url (if dns is not already prepared, via /etc/hosts entry)
Login with the admin@YOURDOMAIN user
Future changes can be applied via: ./kolabctl apply

Installing on a pre-existing vm (bypass vm provisioning)

It is possible to either manually provision a Virtual Machine or connect to an existing system to install Kolab. Please note that the ansible scripts assume the environment as prepared by the kvm ansible role (as part of https://mirror.apheleia-it.ch/pub/kolab-kubernetes-latest.tar.gz).

As the base image for manual installation, the following image is recommended: https://mirror.apheleia-it.ch/pub/kolab-minimal-0.1.qcow2 (default login root/kolab)

Once the VM is available, follow the above instructions with the following adjustments:

When adjusting the new inventory.yaml:
- Disable vm provisioning by setting provision_vm: false
- Set the ip to connect to your vm (only necessary if the hostname is not resolved to the correct ip on the control host):
  - Set ansible_host: ip of your vm

Updating

To update the VM image run the same ansible script as for installing Kolab:

ansible-playbook -v -i inventory.yaml -D deployments/k3s-single-node/ansible/playbook.yaml

Please note that this will still respect pinned image versions in values.yaml, so you will have to update those manually.

Backup & Restore

11 Comments

Peter · March 19, 2025 at 4:32 pm

I downloaded the kolab-minimal-0.1.qcow2 image and have it running, but I can’t login because I can’t find a login user and password. Can someone help me with this?

Christian Mollekopf · April 11, 2025 at 2:58 am

Hi,

You should be able to login with user root and password kolab.

Christian Mollekopf · April 11, 2025 at 3:45 am

The login is root/kolab, which would then be updated by the ansible based deployment process.

Oliver · May 5, 2025 at 7:30 pm

Hi Christian, thanks for the information provided. I wish there was an easy way (and therefore step-by-step instructions) for Kubernetes noobs like me to test Kolab. Sorry, for asking very basic questions, but where do I even start for single machine installation ? Do I use a vanilla AlmaLinux9 image or kolab-minimal-0.1.qcow2 as starting point ? I couldn’t find any information in this image: kolabvm.qcow2. What is good for ? Sorry, for asking beginner questions, but as stated more beginner friendly information would be really appreciated, if not asked too much. Thanks

Christian Mollekopf · July 3, 2025 at 2:14 pm

Hi,
The ansible provision scripts create the VM’s via libvirt, so that’s where the VM image to use is configured.
If you want to bypass the VM provisioning process, then yes, the kolab-minimal vm image is a good starting point, and the ansbible scripts now also support installing from a vanilla almalinux 9 image.
I’m afraid we’ll have to keep the documentation to a necessary minimum, but I hope that then ansible scripts can serve as a form of executable documentation at least for those familiar with ansible, and we can of course improve the documentation where we can.

Alex · May 29, 2025 at 11:35 am

I want to implement kolab in k3s cluster of 5 nodes. The README and NOTES do not have enough details in regards to that configuration. mainly which other CSI based operators does it support ? longhorn ? what about extending cluster to 7 nodes ? what are time lines for extending db ?

Christian Mollekopf · July 3, 2025 at 2:27 pm

Hi,

I don’t expect that we will have documentation how to run large-scale deployments of Kolab here.
We typically use either local storage or Ceph, but I see no reason why longhorn wouldn’t work.
You are welcome to contribute notes for your deployments if you decide to work on that and I’m happy to answer questions at mollekopf@apheleia-it.ch or devel@lists.kolab.org (CC me to make sure I don’t miss the mail).

Lennart Ackermans · August 19, 2025 at 7:00 pm

Thanks for providing this script!

Some annoyances I had:

1. I didn’t want to use KVM since k3s runs fine in an LXC container. It would be nicer if the script for VM provision and kolab installation were separate, and if the latter didn’t depend on the former.

2. Seems I had to add a few settings to my inventory.yaml to avoid Ansible errors:
disable_cert_manager: false
local_registry: false
disable_ingress: false
skip_reconfigure: false

3. It seems that there is only one “domain” setting, which is both the main email domain and the web host for accessing kolab. It would be nice if these were separate settings.

4. Despite using the Alma Linux image provided there were quite some packages I needed to install on the k3s host, including one that was not available in the repository (yq).

5. The ansible script gave me some errors that I had to fix by tinkering with the playbook. Maybe it’s my fault, can’t remember what the problems were.

6. The kolab pod was OOMKilled quickly after starting, with the standard 1G memory limit. I had to increase it to 3G. It’s strange that it uses so much memory.

Christian Mollekopf · August 28, 2025 at 7:32 am

Thanks for the feedback!

1. The ansible script basically has 3 layers (provided in 3 ansible roles):
* The kvm role which provisions the VM
* The kolab-single-node script which sets-up k3s (and is specific to the almalinux vm that we use)
* The kolab role which deploys the kolab via the helm chart in the provided cluster

While it’s likely that modifications are required (because not tested), the idea would be that you could choose to omit a layer:
* Provide a pre-provisioned VM (skipping the kvm role)
* Provide a pre-provisioned k3s cluster (skipping both kvm and kolab-node)

4. That is because the idea is to maintain the system from a control host, and not the deployed vm itself.
I understand that it can make sense for your usecase to do everything directly from the deployed vm, and there’s nothing wrong with that approach per se. The benefit from doing from “outside”, is that you can loose the vm, and recreate it to the same state as before (or recreate it in another place if you bring the storage volumes along).

It probably make sense to install all dependencies anyways, it’s not like there’s much harm to it.

6. That is odd indeed. I’ve only seen it use more than 1GB on large deployments, for small ones ~400MB should be normal.

Lennart Ackermans · August 30, 2025 at 11:06 pm

Hi Christian, thanks for the reply. I actually ran the ansible script from a control host. But it still complained about some packages not being installed on the k3s host, including (I believe) yq.

About the memory, does the kolab pod perhaps run two workers for every cpu core? I have 48 cores and I see about 100 processes.

Christian Mollekopf · September 1, 2025 at 9:48 am

It’s possible that you’re still on a version that autoscales with the number of cpu-cores, there’s a recent fix for that. I’ll try to push the sources for the helm chart to git.kolab.org this week and make sure all containers are up-to-date so we have a good base going forward.

Deploy Kolab on a single host

Published by Christian Mollekopf on February 14, 2025February 14, 2025

Setup Instructions

Installing on a pre-existing vm (bypass vm provisioning)

Updating