<commit_before>---
permalink: /
---


# GNU Mailman 3 Deployment with Docker



[![CircleCI](https://circleci.com/gh/maxking/docker-mailman/tree/main.svg?style=svg)](https://circleci.com/gh/maxking/docker-mailman/tree/main)

This repository hosts code for two docker images `maxking/mailman-core` and
`maxking/mailman-web` both of which are meant to deploy [GNU Mailman 3][1] in
a production environment.

[Docker][2] is a container ecosystem which can run containers on several
platforms. It consists of a tool called [docker-compose][3] which can be used to
run multi-container applications. This repository consists of a
[`docker-compose.yaml`][1] file which is a set of
configurations that can be used to deploy the [Mailman 3 Suite][4].

[1]: https://github.com/maxking/docker-mailman/blob/master/docker-compose.yaml

Please see [release page](https://github.com/maxking/docker-mailman/releases)
for the releases and change log.

## Release


The tags for the images are assumed to be release versions for images. This is
going to be a somewhat common philosophy of distributing Container images where
the images with same tags are usually updated with the new functionality.

Releases will follow the following rules:

* Images tagged like A.B.C will never change. If you want to pin down versions
  of Images, use these tags.

* Images tagged with A.B will correspond to the latest A.B.C version
  released. Releases in A.B series are supposed to be backwards compatible,
  i.e., any existing installation should not break when upgrading between
  subversions of A.B.C. So, if you want the latest updates and want to
  frequently update your installation without having to change the version
  numbers, you can use this.

* Any changes in the minor version of Mailman components of the images will
  cause a bump in the minor version, e.g., A.(B+1) can have one or more
  updated Mailman components from A.B. Also, significant change in functionality,
  that might change how Images work or how people interact with the containers
  can also cause a bump in the minor version.

* Major versions will change either when there are backwards incompatible
  changes or when the releases reach a certain set milestone or when there are
  bugfix releases for the internal components or both.


## Container Registries


The container images are available from multiple container registries:

### Mailman Core

- `ghcr.io/maxking/mailman-core`
- `quay.io/maxking/mailman-core`
- `docker.io/maxking/mailman-core`

### Mailman Web

- `ghcr.io/maxking/mailman-web`
- `quay.io/maxking/mailman-web`
- `docker.io/maxking/mailman-web`

### Postorius

- `ghcr.io/maxking/postorius`
- `quay.io/maxking/postorius`
- `docker.io/maxking/postorius`

## Rolling Releases

Rolling releases are made up of Mailman Components installed from [git
source](https://gitlab.com/mailman). **Note that these releases are made up of
un-released software and should be assumed to be beta quality.**

Every commit is tested with Mailman's CI infrastructure and is included in
rolling releases only if they have passed the complete test suite.

```bash
$ docker pull docker.io/maxking/mailman-web:rolling
$ docker pull docker.io/maxking/mailman-core:rolling
```

Rolling releases are built with every commit and also re-generated weekly. You
can inspect the images to get which commit it was built using:

```bash
$ docker inspect --format '{{json .Config.Labels }}' mailman-core | python -m json.tool
{
    "version.core": "31f434d0",
    "version.git_commit": "45a4d7805b2b3d0e7c51679f59682d64ba02f05f",
    "version.mm3-hk": "c625bfd2"
}

$ docker inspect --format '{{json .Config.Labels }}' mailman-web | python -m json.tool
{
    "version.client": "d9e9cb73",
    "version.dj-mm3": "72a7d6c4",
    "version.git_commit": "<PASSWORD>",
    "version.hyperkitty": "b67ca8a8",
    "version.postorius": "73328ad4"
}

```

- `version.git_commit` : This is the commit hash of the Dockerfile in the
  [Github repo](https://github.com/maxking/docker-mailman)
- `version.core`: The commit hash of Mailman Core
- `version.mm3-hk`: The commit hash of Mailman3-hyperkitty plugin.
- `version.client`: The commit hash of Mailman Client.
- `version.hyperkitty`: The commit hash of Hyperkitty.
- `version.postorius`: The commit hash of Postorius.
- `version.dj-mm3`: The commit hash of Django-Mailman3 project.

## Dependencies

- Docker
- Docker-compose

To install these on Ubuntu/Debian:

```
$ sudo apt install docker.io docker-compose
```

For other systems, you can read the official Docker documentation to install
the dependencies from [here][5] and [here][6].


## Configuration

Most of the common configuration is handled through environment variables in the
`docker-compose.yaml`. However, there is need for some extra configuration that
interacts directly with the application. There are two configuration files on
the host that interact directly with Mailman's settings. These files exist on
the host running the containers and are imported at runtime in the containers.

* `/opt/mailman/core/mailman-extra.cfg` : This is the configuration for Mailman
  Core and anything that you add here will be added to Core's configuration. You
  need to restart your mailman-core container for the changes in this file to
  take effect.

* `/opt/mailman/web/settings_local.py` : This is the Django configuration that
  is imported by the [existing configuration][2]
  provided by the mailman-web container. **This file is referred to as
  `settings.py` in most of the Postorius and Django documentation.** To change
  or override any settings in Django/Postorius, you need to create/edit this file.
  A useful configuration for troubleshooting is `DEBUG = True`.

[2]: https://github.com/maxking/docker-mailman/blob/master/web/mailman-web/settings.py<commit_msg>Some small changes in the REDAME urls. (#503)<commit_after>---
permalink: /
---


# GNU Mailman 3 Deployment with Docker



[![CircleCI](https://circleci.com/gh/maxking/docker-mailman/tree/main.svg?style=svg)](https://circleci.com/gh/maxking/docker-mailman/tree/main)

This repository hosts code for two docker images `maxking/mailman-core` and
`maxking/mailman-web` both of which are meant to deploy [GNU Mailman 3][1] in
a production environment.

[Docker][2] is a container ecosystem which can run containers on several
platforms. It consists of a tool called [docker-compose][3] which can be used to
run multi-container applications. This repository consists of a
[`docker-compose.yaml`][1] file which is a set of
configurations that can be used to deploy the [Mailman 3 Suite][4].

[1]: https://github.com/maxking/docker-mailman/blob/master/docker-compose.yaml

Please see [release page](https://github.com/maxking/docker-mailman/releases)
for the releases and change log.

## Release


The tags for the images are assumed to be release versions for images. This is
going to be a somewhat common philosophy of distributing Container images where
the images with same tags are usually updated with the new functionality.

Releases will follow the following rules:

* Images tagged like A.B.C will never change. If you want to pin down versions
  of Images, use these tags.

* Images tagged with A.B will correspond to the latest A.B.C version
  released. Releases in A.B series are supposed to be backwards compatible,
  i.e., any existing installation should not break when upgrading between
  subversions of A.B.C. So, if you want the latest updates and want to
  frequently update your installation without having to change the version
  numbers, you can use this.

* Any changes in the minor version of Mailman components of the images will
  cause a bump in the minor version, e.g., A.(B+1) can have one or more
  updated Mailman components from A.B. Also, significant change in functionality,
  that might change how Images work or how people interact with the containers
  can also cause a bump in the minor version.

* Major versions will change either when there are backwards incompatible
  changes or when the releases reach a certain set milestone or when there are
  bugfix releases for the internal components or both.


## Container Registries


The container images are available from multiple container registries:

### Mailman Core

- `ghcr.io/maxking/mailman-core`
- `quay.io/maxking/mailman-core`
- `docker.io/maxking/mailman-core`

### Mailman Web

- `ghcr.io/maxking/mailman-web`
- `quay.io/maxking/mailman-web`
- `docker.io/maxking/mailman-web`

### Postorius

- `ghcr.io/maxking/postorius`
- `quay.io/maxking/postorius`
- `docker.io/maxking/postorius`

## Rolling Releases

Rolling releases are made up of Mailman Components installed from [git
source](https://gitlab.com/mailman). **Note that these releases are made up of
un-released software and should be assumed to be beta quality.**

Every commit is tested with Mailman's CI infrastructure and is included in
rolling releases only if they have passed the complete test suite.

```bash
$ docker pull docker.io/maxking/mailman-web:rolling
$ docker pull docker.io/maxking/mailman-core:rolling
```

Rolling releases are built with every commit and also re-generated weekly. You
can inspect the images to get which commit it was built using:

```bash
$ docker inspect --format '{{json .Config.Labels }}' mailman-core | python -m json.tool
{
    "version.core": "31f434d0",
    "version.git_commit": "<PASSWORD>",
    "version.mm3-hk": "c625bfd2"
}

$ docker inspect --format '{{json .Config.Labels }}' mailman-web | python -m json.tool
{
    "version.client": "d9e9cb73",
    "version.dj-mm3": "72a7d6c4",
    "version.git_commit": "<KEY>f",
    "version.hyperkitty": "b67ca8a8",
    "version.postorius": "73328ad4"
}

```

- `version.git_commit` : This is the commit hash of the Dockerfile in the
  [Github repo](https://github.com/maxking/docker-mailman)
- `version.core`: The commit hash of Mailman Core
- `version.mm3-hk`: The commit hash of Mailman3-hyperkitty plugin.
- `version.client`: The commit hash of Mailman Client.
- `version.hyperkitty`: The commit hash of Hyperkitty.
- `version.postorius`: The commit hash of Postorius.
- `version.dj-mm3`: The commit hash of Django-Mailman3 project.

## Dependencies

- Docker
- Docker-compose

To install these on Ubuntu/Debian:

```
$ sudo apt install docker.io docker-compose
```

For other systems, you can read the official Docker documentation to install
[Docker from here][5] and [docker-compose from here][6].


## Configuration

Most of the common configuration is handled through environment variables in the
`docker-compose.yaml`. However, there is need for some extra configuration that
interacts directly with the application. There are two configuration files on
the host that interact directly with Mailman's settings. These files exist on
the host running the containers and are imported at runtime in the containers.

* `/opt/mailman/core/mailman-extra.cfg` : This is the configuration for Mailman
  Core and anything that you add here will be added to Core's configuration. You
  need to restart your mailman-core container for the changes in this file to
  take effect.

* `/opt/mailman/web/settings_local.py` : This is the Django configuration that
  is imported by the [existing configuration][2]
  provided by the mailman-web container. **This file is referred to as
  `settings.py` in most of the Postorius and Django documentation.** To change
  or override any settings in Django/Postorius, you need to create/edit this file.
  A useful configuration for troubleshooting is `DEBUG = True`.

[2]: https://github.com/maxking/docker-mailman/blob/master/web/mailman-web/settings.py
{'fraction_non_alphanumeric': 0.08965339739190116, 'fraction_numerical': 0.01098146877144818, 'mean_word_length': 4.215659955257271, 'pattern_counts': {'":': 16, '<': 6, '<?xml version=': 0, '>': 6, 'https://': 14, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '551897', 'n_tokens_mistral': 3553, 'n_tokens_neox': 3340, 'n_words': 1395}