From 32796a5a182fe5fa39c46ccb2e0ee07902b762cf Mon Sep 17 00:00:00 2001 From: Abhilash Raj Date: Fri, 7 Apr 2017 15:47:36 -0700 Subject: [PATCH] Add separate Readme for each image. --- README.md | 114 +++++++++++++++++++------------------------------ core/README.md | 89 ++++++++++++++++++++++++++++++++++++++ web/README.md | 63 +++++++++++++++++++++++++++ 3 files changed, 195 insertions(+), 71 deletions(-) create mode 100644 web/README.md diff --git a/README.md b/README.md index ec19159..8cc07d5 100644 --- a/README.md +++ b/README.md @@ -11,6 +11,12 @@ run multi-container applications. This repository consists of a [`docker-compose.yaml`](docker-compose.yaml) file which is a set of configurations that can be used to deploy the [Mailman 3 Suite][4]. +While is not _official_ way to deploy Mailman 3, I will try my best to help if +you encounter problems. + +For now, both `mailman-core` and `mailman-web` images are built from latest git +branches for all the proejcts, but in future when Mailman 3.1 is released, I +will have seperate images for latest and stable versions of the containers. Dependencies ============ @@ -22,12 +28,49 @@ are using. You can find documentation about [how to install][5]. It is recomended to use these instead of the one from your package managers. After you have downloaded and installed docker, install docker-compose from [here][6]. + + +Configuration +============= + +Most of the configuraiton is supposed to be handled through environment +variables in the `docker-compose.yaml`. + +### Mailman-web +These are the settings that you MUST change before deploying: + +- `SERVE_FROM_DOMAIN`: The domain name from which Django will be served. To be + added to `ALLOWED_HOSTS` in django settings. Default value is not set. + +- `HYPERKITT_API_KEY`: Hyperkitty's API Key, should be set to the same value as + set for the mailman-core. + +For more detauls on how to configura this image, please look at [Mailman-web's +Readme](web/README.md) + +### Mailman-Core + +These are the variables that you MUST change before deploying: + +- `HYPERKITT_API_KEY`: Hyperkitty's API Key, should be set to the same value as + set for the mailman-core. + +- `DATABASE_CLASS`: Default value is `mailman.database.sqlite.SQLiteDatabase`. + +For more details on how to configure this image, please look [Mailman-core's +Readme](core/README.md) + Running ======= To run the containers, simply run: ```bash +$ mkdir -p /opt/mailman/core +$ mkdir -p /opt/mailman/web +$ git clone https://github.com/maxking/docker-mailman +$ cd docker-mailman +# Change some configuration variables as mentioned below. $ docker-compose up ``` @@ -188,77 +231,6 @@ exit 0 Please do not forget to make the script executable (chmod +x certbot-renew.sh). -Configuration -============= - -Most of the configuraiton is supposed to be handled through environment -variables in the `docker-compose.yaml`. - -### Mailman-web -These are the settings that you MUST change before deploying: - -- `SERVE_FROM_DOMAIN`: The domain name from which Django will be served. To be - added to `ALLOWED_HOSTS` in django settings. Default value is not set. - -- `HYPERKITT_API_KEY`: Hyperkitty's API Key, should be set to the same value as - set for the mailman-core. - -These are the settings that are set to sane default and you do not need to -change them unless you know what you want. - -- `DATABASE_URL`: URL of the type - `driver://user:password@hostname:port/databasename` for the django to use. If - not set, the default is set to - `sqlite:///opt/mailman-web-data/mailmanweb.db`. The standard - docker-compose.yaml comes with it set to a postgres database. It is not must - to change this if you are happy with postgresql. - -- `MAILMAN_REST_URL`: The URL to the Mailman core's REST API server. Defaut - value is `http://mailman-core:8001`. - -- `MAILMAN_REST_USER`: Mailman's REST API username. Default value is `restadmin` - -- `MAILMAN_REST_PASSWORD`: Mailman's REST API user's password. Default value is - `restpass` - -- `DJANGO_HOST_IP`: IP of the container from which the django will be - served. Default value is `172.19.199.3`. - -- `SMTP_HOST`: IP Address/hostname from which you will be sending - emails. Default value is `172.19.199.1`, which is the address of the Host OS. - -- `SMTP_PORT`: Port used for SMTP. Default is `25`. - - -### Mailman-Core - -These are the variables that you MUST change before deploying: - -- `HYPERKITT_API_KEY`: Hyperkitty's API Key, should be set to the same value as - set for the mailman-core. - -- `DATABASE_CLASS`: Default value is `mailman.database.sqlite.SQLiteDatabase`. - -These are the variables that you don't need to change if you are using a -standard version of docker-compose.yaml from this repository. - -- `MM_HOSTNAME`: Default value is `mailman-core` - -- `SMTP_HOST`: IP Address/hostname from which you will be sending - emails. Default value is `172.19.199.1`, which is the address of the Host OS. - -- `SMTP_PORT`: Port used for SMTP. Default is `25`. - -- `HYPERKITTY_API_URL`: Default value is `http://mailman-web:8000/hyperkitty` - -- `DATABASE_URL`: URL of the type - `driver://user:password@hostname:port/databasename` for the django to use. If - not set, the default is set to - `sqlite:///opt/mailman-web-data/mailmanweb.db`. The standard - docker-compose.yaml comes with it set to a postgres database. It is not must - to change this if you are happy with postgresql. - - LICENSE ======= diff --git a/core/README.md b/core/README.md index 25a9146..4f8a1cb 100644 --- a/core/README.md +++ b/core/README.md @@ -8,3 +8,92 @@ be stored here so that it can persist across different sessions and containers. It is not advised to run multiple mailman processes on the same host sharing the same `/opt/mailman` directory as this will almost certainly be dangerous. + + +Configuration +============= + +These are the variables that you MUST change before deploying: + +- `HYPERKITT_API_KEY`: Hyperkitty's API Key, should be set to the same value as + set for the mailman-core. + +- `DATABASE_CLASS`: Default value is `mailman.database.sqlite.SQLiteDatabase`. + +These are the variables that you don't need to change if you are using a +standard version of docker-compose.yaml from this repository. + +- `MM_HOSTNAME`: Default value is `mailman-core` + +- `SMTP_HOST`: IP Address/hostname from which you will be sending + emails. Default value is `172.19.199.1`, which is the address of the Host OS. + +- `SMTP_PORT`: Port used for SMTP. Default is `25`. + +- `HYPERKITTY_API_URL`: Default value is `http://mailman-web:8000/hyperkitty` + +- `DATABASE_URL`: URL of the type + `driver://user:password@hostname:port/databasename` for the django to use. If + not set, the default is set to + `sqlite:///opt/mailman-web-data/mailmanweb.db`. The standard + docker-compose.yaml comes with it set to a postgres database. It is not must + to change this if you are happy with postgresql. + +Running Mailman-Core +==================== + +It is highly recomended that you run this image along with the +docker-compose.yaml file provided at the [github repo][1] of this +image. However, it is possibel to run this image as a standalone container if +you want just a mailman-core. + +```bash +$ mkdir -p /opt/mailman/core +$ docker run -it -e "HYPERKITTY_API_KEY=changeme" -h mailman-core -v /opt/mailman/core:/opt/mailman mailman-core +``` + +However, if you don't provide the environment `DATABASE_URL`, the database _may_ +not be persistant. All the configuration options are explained in more detail. + +If you need mode advanced configuration for mailman, you can create +`/opt/mailman/mailman.cfg` and it be added to the configuration inside the +container. Note that, anything inside this configuration will override the +settings provided via the environment variables and their default values. + +By default, the following settings are generated: + +``` +# mailman.cfg +[mta] +incoming: mailman.mta.exim4.LMTP +outgoing: mailman.mta.deliver.deliver +lmtp_host: $MM_HOSTNAME +lmtp_port: 8024 +smtp_host: $SMTP_HOST +smtp_port: $SMTP_PORT +configuration: python:mailman.config.exim4 + +[runner.retry] +sleep_time: 10s + +[webservice] +hostname: $MM_HOSTNAME + +[archiver.hyperkitty] +class: mailman_hyperkitty.Archiver +enable: yes +configuration: /config/mailman-hyperkitty.cfg + +[database] +class: $DATABASE_CLASS +url: $DATABASE_URL +``` + +``` +# mailman-hyperkitty.cfg +[general] +base_url: $HYPERKITTY_URL +api_key: $HYPERKITTY_API_KEY +``` + +[1]: https://github.com/maxking/docker-mailman.git diff --git a/web/README.md b/web/README.md new file mode 100644 index 0000000..e228deb --- /dev/null +++ b/web/README.md @@ -0,0 +1,63 @@ +Mailman 3 Web UI +================ + +This image consists of Mailman3's Web UI(Postorius) and Archiver +(Hyperkitty). This image is built from latest sources on [gitlab][1]. In future, +latest and stable releases will be seperate. I am looking forward to the release +of Mailman Suite 3.1 before that. + +Configuration +============= + +These are the settings that you MUST change before deploying: + +- `SERVE_FROM_DOMAIN`: The domain name from which Django will be served. To be + added to `ALLOWED_HOSTS` in django settings. Default value is not set. + +- `HYPERKITT_API_KEY`: Hyperkitty's API Key, should be set to the same value as + set for the mailman-core. + +These are the settings that are set to sane default and you do not need to +change them unless you know what you want. + +- `DATABASE_URL`: URL of the type + `driver://user:password@hostname:port/databasename` for the django to use. If + not set, the default is set to + `sqlite:///opt/mailman-web-data/mailmanweb.db`. The standard + docker-compose.yaml comes with it set to a postgres database. It is not must + to change this if you are happy with postgresql. + +- `MAILMAN_REST_URL`: The URL to the Mailman core's REST API server. Defaut + value is `http://mailman-core:8001`. + +- `MAILMAN_REST_USER`: Mailman's REST API username. Default value is `restadmin` + +- `MAILMAN_REST_PASSWORD`: Mailman's REST API user's password. Default value is + `restpass` + +- `DJANGO_HOST_IP`: IP of the container from which the django will be + served. Default value is `172.19.199.3`. + +- `SMTP_HOST`: IP Address/hostname from which you will be sending + emails. Default value is `172.19.199.1`, which is the address of the Host OS. + +- `SMTP_PORT`: Port used for SMTP. Default is `25`. + +Running +======= + +It is highly recommended that you run this using the [docker-compose.yaml][2] +provided in the [github repo][3] of this project. You will need to proxy the +requests the container that you create with this image using an actual web +server like Nginx. The [github repo][3] provides the setup instructions for +Nginx. + +Since the setup has `USE_SSL` set to `True` in django's `settings.py`, you may +also want to get a SSL certificate if you don't already have one. [Lets +Encrypt][4] provides free SSL certiticates for everyone and there are _some_ +instructions about that also. + +[1]: https://gitlab.com/mailman +[3]: https://github.com/maxking/docker-mailman/ +[2]: https://github.com/maxking/docker-mailman/blob/master/docker-compose.yaml +[4]: https://letsencrypt.org