mailcow/README.adoc

= 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
----