blob: 1c6a0eccb49de398e65402f04c05a9453eb4a96b [file] [log] [blame]
= Mailcow on Kubernetes
Matthias Andreas Benkard
:experimental:
:data-uri:
:sectnums:
:toc:
:stem:
:toclevels: 2
:icons: font
:source-highlighter: prettify
== Description
This directory contains a distribution of https://mailcow.github.io/mailcow-dockerized-docs/[*Mailcow*]
that you can run in a https://matthias.benkard.de/posts/814[*Kata container*] as part of a *Kubernetes cluster*.
The main artifact provided is a Docker image, meant to run in a Kata container, which embeds its own
https://www.docker.com[Docker daemon] and copies of https://docs.docker.com/compose/[docker-compose] and a very slightly patched
https://github.com/mailcow/mailcow-dockerized/[mailcow-dockerized].
== Usage
=== Building the Docker image
The main Docker image that you can run in the cluster is defined in link:default.nix[].
To build it, you can either go through the regular procedure of
https://nixos.org/guides/building-and-running-docker-images.html[building Docker images with Nix]
or make use of the top-level link:../Makefile[Makefile]:
[source,shell script]
----
make mailcow.load
----
After building and loading the image, push it to the registry of your choice.
=== Deploying to Kubernetes
First, create a *configuration file* as explained in the https://mailcow.github.io/mailcow-dockerized-docs/i_u_m_install/[Mailcow installation howto] and deploy the configuration as a *Kubernetes secret*:
[source,shell script]
----
kubectl create secret generic mailcow-secrets \
--from-file=mailcow.conf=src/mailcow-dockerized/mailcow.conf
----
You can then use the provided link:mailcow.yaml[] file to perform the *deployment*.
Be sure to change the *image name* to the image you built above.
You probably also want to adjust the *namespace* unless a namespace named `mulk` makes sense to you.
=== Updating Mailcow
Updating should usually be as easy as *synchronizing* the link:src/mailcow-dockerized/[] subtree with *upstream* and then <<Building the Docker image,rebuilding the image>>.
To synchronize the subtree, use `git subtree`:
[source,shell script]
----
git subtree pull \
--prefix=mailcow/src/mailcow-dockerized \
https://github.com/mailcow/mailcow-dockerized.git \
master
----