README fixes (#464)

* Fix typos and use consistent YAML data structures for env

* Add Debug flag and more structure to the README

* Clarify default value of MM_HOSTNAME

* Fix typo

* Fix typos

README.md

@@ -154,7 +154,8 @@ the host running the containers and are imported at runtime in the containers.
   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. 
+  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
 
@@ -190,7 +191,7 @@ environment variables mentioned above (`MAILMAN_ADMIN_USER` &
 password, plese follow the "Forgot Password" link on the "Sign In" page.
 
 To configure the mailman-web container to send emails, add this to your
-`settings_local.py`.:
+`settings_local.py`:
 
 ```
 EMAIL_BACKEND = 'django.core.mail.backends.smtp.EmailBackend'
@@ -333,11 +334,13 @@ The provided docker containers do not have an MTA in-built. You can either run
 your own MTA inside a container and have them relay emails to the mailman-core
 container or just install an MTA on the host and have them relay emails.
 
+### Exim4
+
 To use [Exim4][8], it should be setup to relay emails from mailman-core and
 mailman-web. The mailman specific configuration is provided in the
 repository at `core/assets/exim`. There are three files
 
-- [25_mm_macros](core/assets/exim/25_mm3_macros) to be placed at
+- [25_mm3_macros](core/assets/exim/25_mm3_macros) to be placed at
   `/etc/exim4/conf.d/main/25_mm3_macros` in a typical Debian install of
   exim4. Please change MY_DOMAIN_NAME to the domain name that will be used to
   serve mailman. Multi-domain setups will be added later.
@@ -364,6 +367,8 @@ smtp_port: $SMTP_PORT
 configuration: python:mailman.config.exim4
 ```
 
+### Postfix
+
 To use [Postfix][12], edit the `main.cf` configuration file, which is typically
 at `/etc/postfix/main.cf` on Debian-based operating systems.  Add
 mailman-core and mailman-web to `mynetworks` so it will relay emails from

core/README.md

@@ -5,7 +5,7 @@ When you spawn off this container, you must mount `/opt/mailman` to the
 container. Mailman's `var` directory will also be stored here so that it can
 persist across different sessions and containers. Any configuration at
 `/opt/mailman/core/mailman-extra.cfg` (on the host) will be added to the mailman's default
-generated confifguration (See below).
+generated confifguration (see below).
 
 It is not advised to run multiple mailman processes on the same host sharing the
 same `/opt/mailman` (`/opt/mailman/core` on the host) directory as this will
@@ -25,10 +25,10 @@ These are the variables that you MUST change before deploying:
   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.
+  to change this if you are happy with PostgreSQL.
 
-- `DATABASE_TYPE`: It's value can be one of `sqlite`, `postgres` or `mysql` as
+- `DATABASE_TYPE`: Its value can be one of `sqlite`, `postgres` or `mysql` as
-  these are the only three database types that Mailman 3 supports. It's defualt
+  these are the only three database types that Mailman 3 supports. Its default
   value is set to `sqlite` along with the default database class and default
   database url above.
 
@@ -41,7 +41,7 @@ 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`: Which hostname or IP should Core bind to for REST API and
-  LMTP. If not defined output from `hostname` command is used.
+  LMTP. If not defined output from the `hostname -i` command is used.
 
 - `MAILMAN_REST_PORT`: Which port should Core use for the REST API. If not defined
   the default is `8001`.
@@ -79,7 +79,7 @@ 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
+image. However, it is possible to run this image as a standalone container if
 you want just a mailman-core.
 
 ```bash
@@ -88,11 +88,11 @@ $ docker run -it -e "HYPERKITTY_API_KEY=changeme" -h mailman-core -v /opt/mailma
 ```
 
 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.
+not be persisted. 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
+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:
@@ -142,7 +142,7 @@ You can use Postfix or [Exim][2] with this image to send emails. Mailman Core
 can interact with any modern MTA which can deliver emails over LMTP. The
 documentation for Mailman Core has configuration settigs for using them.
 
-Only Exim and Postfix has been tested with these images and are supported as of
+Only Exim and Postfix have been tested with these images and are supported as of
 now. There _might_ be some limitations with using other MTAs in a containerized
 environments. Contributions are welcome for anything additional needed to
 support other MTAs.

docker-compose.yaml

@@ -46,9 +46,9 @@ services:
 
   database:
     environment:
-      POSTGRES_DB: mailmandb
+    - POSTGRES_DB=mailmandb
-      POSTGRES_USER: mailman
+    - POSTGRES_USER=mailman
-      POSTGRES_PASSWORD: mailmanpass
+    - POSTGRES_PASSWORD=mailmanpass
     image: postgres:9.6-alpine
     volumes:
     - /opt/mailman/database:/var/lib/postgresql/data

web/README.md

@@ -33,7 +33,7 @@ change them unless you know what you want.
   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.
+  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`.