Add NEWS for upgrade instructions (#499)

* Add NEWS for new release

* Use material theme

NEWS.md

@@ -1,11 +1,101 @@
 # NEWS
 
-## Outdated
+## Upgrading to 0.4.0 Release
 
-Please see [release page](https://github.com/maxking/docker-mailman/releases)
-for the latest releases and change log.
+Some configurations in the release are backwards incompatible with
+what was working before. 
 
+### Web server configuration
 
+With 0.4.0 version, we added Port mapping from host's Port 8000/8080
+to mailman-web container's port 8000/8080. Make sure you have this
+in your docker-compose.yaml
+
+```yaml
+  mailman-web:
+    ports:
+    - "127.0.0.1:8000:8000" # HTTP
+    - "127.0.0.1:8080:8080" # uwsgi
+```
+
+You should update your web server to proxy 127.0.0.1:8000.
+
+#### Nginx
+
+Update the Nginx configuration to look like this, notice the
+actual **URL for `proxy_pass` is the only thing that has changed**
+along with some options like `uwsgi_read_timeout` and `include uwsgi_params`
+that have been removed from the previous version.
+
+```
+    location / {
+		  proxy_pass http://127.0.0.1:8000;
+		  proxy_set_header Host $host;
+		  proxy_set_header X-Forwarded-For $remote_addr;
+    }
+```
+
+For other web servers like Apache2, update the URL accordingly.
+
+**Note** that if you are using `uwsgi_pass` instead of `proxy_pass`
+then you should update the URL accordingly to `https://127.0.0.1:8080`.
+
+### MTA configuration
+
+MTA configuration needs updating to ensure that all IPs from the 
+`172.19.199.0/24` subnet is added to `mynetworks` in Postfix configs.
+
+Please verify that the network configuration generated by the containers
+look like this:
+
+```bash
+$ docker exec mailman-core cat /etc/mailman.cfg
+# This file is autogenerated at container startup.
+[database]
+class: mailman.database.postgresql.PostgreSQLDatabase
+url: postgres://mailman:mailmanpass@database/mailmandb
+[runner.retry]
+sleep_time: 10s
+
+[webservice]
+hostname: 172.19.199.3
+port: 8001
+admin_user: restadmin
+admin_pass: restpass
+configuration: /etc/gunicorn.cfg
+
+[mta]
+incoming: mailman.mta.postfix.LMTP
+outgoing: mailman.mta.deliver.deliver
+lmtp_host: 172.19.199.3
+lmtp_port: 8024
+smtp_host: 172.19.199.1
+smtp_port: 25
+configuration: /etc/postfix-mailman.cfg
+
+[archiver.hyperkitty]
+class: mailman_hyperkitty.Archiver
+enable: yes
+configuration: /etc/mailman-hyperkitty.cfg
+```
+
+**Note that lmtp_host can be different than before since new
+containers don't have static IP addresses. They are automatically
+parsed from the output of "ip route" command from inside mailman-core
+container.**
+
+You can verify that the IP address of the containers by running the
+following commands, note that the **output can be different** and it is
+fine if that is the case.
+
+```bash
+$ docker inspect -f '{{range.NetworkSettings.Networks}}{{.IPAddress}}{{end}}' mailman-core
+172.19.199.3
+$ docker inspect -f '{{range.NetworkSettings.Networks}}{{.IPAddress}}{{end}}' mailman-web
+172.19.199.4
+```
+
+----
 ## Mailman Core
 
 ### v1.1.1 (released Aug 9 2017)

docs/news.md

@@ -0,0 +1 @@
+../NEWS.md

mkdocs.yml

@@ -11,6 +11,7 @@ nav:
   - Home: "index.md"
   - Mailman Core: "core.md"
   - Mailman Web: "web.md"
+  - News: "news.md"
 
 markdown_extensions:
   - toc: