Further revisions and updates

Author: JeffSchering

source/install/config-mattermost.rst

@@ -1,3 +1,5 @@
+.. _config-mattermost:
+
 ======================
 Configuring Mattermost
 ======================
@@ -10,4 +12,5 @@ After installing the Mattermost components, you must create the first user and f
 
 .. include:: config-mattermost-server.rst
 .. include:: config-tls-mattermost.rst
+.. include:: config-proxy-nginx.rst
 .. include:: config-ssl-http2-nginx.rst

source/install/config-proxy-nginx.rst

@@ -0,0 +1,85 @@
+.. _config-proxy-nginx:
+
+Configuring NGINX as a proxy for Mattermost Server
+==================================================
+
+**To configure NGINX as a proxy**
+
+1. Log into the server that hosts NGINX and open a terminal window.
+2. Create a configuration file for Mattermost.
+
+  ``sudo touch /etc/nginx/sites-available/mattermost``
+
+2. Open the file ``/etc/nginx/sites-available/mattermost`` as root in a text editor and replace its contents, if any, with the following lines. Make sure that you use your own values for the Mattermost server IP address and FQDN for *server_name*.
+  
+  .. code-block:: none
+  
+    upstream backend {
+       server 10.10.10.2:8065;
+    }
+
+    proxy_cache_path /var/cache/nginx levels=1:2 keys_zone=mattermost_cache:10m max_size=3g inactive=120m use_temp_path=off;
+
+    server {
+       listen 80;
+       server_name    mattermost.example.com;
+
+       location /api/v3/users/websocket {
+           proxy_set_header Upgrade $http_upgrade;
+           proxy_set_header Connection "upgrade";
+           client_max_body_size 50M;
+           proxy_set_header Host $http_host;
+           proxy_set_header X-Real-IP $remote_addr;
+           proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+           proxy_set_header X-Forwarded-Proto $scheme;
+           proxy_set_header X-Frame-Options SAMEORIGIN;
+           proxy_buffers 256 16k;
+           proxy_buffer_size 16k;
+           proxy_read_timeout 600s;
+           proxy_pass http://backend;
+       }
+
+       location / {
+           client_max_body_size 50M;
+           proxy_set_header Connection "";
+           proxy_set_header Host $http_host;
+           proxy_set_header X-Real-IP $remote_addr;
+           proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+           proxy_set_header X-Forwarded-Proto $scheme;
+           proxy_set_header X-Frame-Options SAMEORIGIN;
+           proxy_buffers 256 16k;
+           proxy_buffer_size 16k;
+           proxy_read_timeout 600s;
+           proxy_cache mattermost_cache;
+           proxy_cache_revalidate on;
+           proxy_cache_min_uses 2;
+           proxy_cache_use_stale timeout;
+           proxy_cache_lock on;
+           proxy_pass http://backend;
+       }
+    }
+
+3. Remove the existing default sites-enabled file.
+
+  ``sudo rm /etc/nginx/sites-enabled/default``
+
+4. Enable the mattermost configuration.
+
+  ``sudo ln -s /etc/nginx/sites-available/mattermost /etc/nginx/sites-enabled/mattermost``
+
+5. Restart NGINX.
+
+  ``sudo service nginx restart``
+
+6. Verify you can see Mattermost thru the proxy.
+
+  ``curl http://localhost``
+  
+  If everything is working, you will see the HTML for the Mattermost signup page.
+
+**What to do next**
+
+You can configure NGINX to use SSL. This will allow you to use HTTPS connections and the HTTP/2 protocol.
+
+**Related links**
+  - :ref:`config-ssl-http2-nginx`

source/install/config-ssl-http2-nginx.rst

@@ -1,26 +1,44 @@
+.. _config-ssl-http2-nginx:
+
 Configuring NGINX with SSL and HTTP/2
 =====================================
 
-1. You can use a free and an open certificate security like let's
-   encrypt, this is how to proceed
+Using SSL gives greater security by ensuring that communications between Mattermost clients and the Mattermost server are encrypted. It also allows you to configure NGINX to use the HTTP/2 protocol.
+
+Although you can configure HTTP/2 without SSL, both Firefox and Chrome browsers support HTTP/2 on secure connections only.
+
+You can use any certificate that you want, but these instructions show you how to download and install certificates from *Let's Encrypt*.
+
+1. Log into the server that hosts NGINX and open a terminal window.
+2. Install git.
+
+  ``sudo apt-get install git``
+
+3. Clone the Let's Encrypt repository on GitHub.
+
+  ``git clone https://github.com/letsencrypt/letsencrypt``
+
+4. Change to the ``letsencrypt`` directory.
 
--  ``sudo apt-get install git``
--  ``git clone https://github.com/letsencrypt/letsencrypt``
--  ``cd letsencrypt``
+  ``cd letsencrypt``
 
-2. Be sure that the port 80 is not use by stopping NGINX
+5. Stop NGINX.
 
--  ``sudo service nginx stop``
--  ``netstat -na | grep ':80.*LISTEN'``
--  ``./letsencrypt-auto certonly --standalone``
+  ``sudo service nginx stop``
 
-3. This command will download packages and run the instance, after that
-   you will have to give your domain name
-4. You can find your certificate in ``/etc/letsencrypt/live``
-5. Modify the file at ``/etc/nginx/sites-available/mattermost`` and add
-   the following lines:
+6. Run ``netstat`` to make sure that nothing is listening on port 80.
 
-  ::
+  ``netstat -na | grep ':80.*LISTEN'``
+
+7. Run the Let's Encrypt installer.
+
+  ``./letsencrypt-auto certonly --standalone``
+
+  When prompted, enter your domain name. The certificate is located in  ``/etc/letsencrypt/live``
+
+8. Open the file ``/etc/nginx/sites-available/mattermost`` as root and update it to incorporate the following lines. Make sure that you use your own values for the Mattermost server IP address and FQDN for *server_name*.
+
+  .. code-block:: none
 
     upstream backend {
         server 10.10.10.2:8065;
@@ -35,7 +53,7 @@ Configuring NGINX with SSL and HTTP/2
     proxy_cache_path /var/cache/nginx levels=1:2 keys_zone=mattermost_cache:10m max_size=3g inactive=120m use_temp_path=off;
 
     server {
-       listen 443 ssl;
+       listen 443 ssl http2;
        server_name mattermost.example.com;
 
        ssl on;
@@ -85,23 +103,19 @@ Configuring NGINX with SSL and HTTP/2
     }
 
 
-6. Be sure to restart NGINX
-  * ``\ sudo service nginx start``
-7. Add the following line to cron so the cert will renew every month
-  * ``crontab -e``
-  * ``@monthly /home/ubuntu/letsencrypt/letsencrypt-auto certonly --reinstall --nginx -d yourdomainname && sudo service nginx reload``
-8. Check that your SSL certificate is set up correctly
-  * Test the SSL certificate by visiting a site such as `https://www.ssllabs.com/ssltest/index.html <https://www.ssllabs.com/ssltest/index.html>`_
-  * If there’s an error about the missing chain or certificate path, there is likely an intermediate certificate missing that needs to be included
+9. Restart NGINX
+
+  ``sudo service nginx start``
 
-Setup HTTP2
-------------
+10. Check that your SSL certificate is set up correctly.
 
-It is recommended to enable HTTP2 for enhanced performance. 
+  * Test the SSL certificate by visiting a site such as https://www.ssllabs.com/ssltest/index.html
+  * If there’s an error about the missing chain or certificate path, there is likely an intermediate certificate missing that needs to be included.
 
-1. Modify your NGINX configuration as above. Then,
+11. Configure ``cron`` so that the certificate will automatically renew every month.
 
-  - Change the line ``listen 443 ssl;`` to ``listen 443 ssl http2;``
-  - Change the line ``proxy_pass http://10.10.10.2:8065;`` to ``proxy_pass https://10.10.10.2:8065;``
+  ``crontab -e``
+  
+  In the following line, use your domain name in place of *<domain-name>*
 
-2. Restart NGINX
+  ``@monthly /home/ubuntu/letsencrypt/letsencrypt-auto certonly --reinstall --nginx -d <domain-name> && sudo service nginx reload``

source/install/install-common-intro.rst

@@ -2,4 +2,4 @@ A complete Mattermost installation consists of 3 major components: a proxy serve
 
 The Mattermost server must be installed on a 64-bit machine, but the database and proxy can be on 32-bit machines. For the database, you can install either MySQL or ProstgreSQL. The proxy is NGINX.
 
-After all the components are installed, some configuration is required. You can set up email notifications, SSL, TSL, and HTTP/2. For more information about configuring, see   
+After all the components are installed, some configuration is required. You can set up email notifications, SSL, TSL, and HTTP/2. For more information about configuring, see :ref:`config-mattermost`.

source/install/install-nginx.rst

@@ -1,3 +1,5 @@
+.. _install-nginx:
+
 Installing NGINX Server
 =======================
 
@@ -10,88 +12,50 @@ The main benefits of using a proxy are as follows:
   -  Port mapping ``:80`` to ``:8065``
   -  Standard request logs
 
-Assume that the IP address of the proxy server is 10.10.10.3.
-
 **To install NGINX on Ubuntu Server:**
 
-1.  Log into the server that will host the proxy and issue the following command:
-
-   -  ``sudo apt-get install nginx``
-
-2. Verify NGINX is running
-
-   -  ``curl http://10.10.10.3``
-   -  You should see a *Welcome to NGINX!* page
-
-3. You can manage NGINX with the following commands
-
-   -  ``sudo service nginx stop``
-   -  ``sudo service nginx start``
-   -  ``sudo service nginx restart``
-
-4. Map a FQDN (fully qualified domain name) like
-   ``mattermost.example.com`` to point to the NGINX server.
-5. Configure NGINX to proxy connections from the internet to the
-   Mattermost Server
-
-   -  Create a configuration for Mattermost
-   -  ``sudo touch /etc/nginx/sites-available/mattermost``
-   -  Below is a sample nginx configuration optimized for performance:
-
-    ::
-    
-        upstream backend {
-            server 10.10.10.2:8065;
-        }
-
-        proxy_cache_path /var/cache/nginx levels=1:2 keys_zone=mattermost_cache:10m max_size=3g inactive=120m use_temp_path=off;
-
-        server {
-            listen 80;
-            server_name    mattermost.example.com;
-
-            location /api/v3/users/websocket {
-                proxy_set_header Upgrade $http_upgrade;
-                proxy_set_header Connection "upgrade";
-                client_max_body_size 50M;
-                proxy_set_header Host $http_host;
-                proxy_set_header X-Real-IP $remote_addr;
-                proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
-                proxy_set_header X-Forwarded-Proto $scheme;
-                proxy_set_header X-Frame-Options SAMEORIGIN;
-                proxy_buffers 256 16k;
-                proxy_buffer_size 16k;
-                proxy_read_timeout 600s;
-                proxy_pass http://backend;
-            }
-
-            location / {
-                client_max_body_size 50M;
-                proxy_set_header Connection "";
-                proxy_set_header Host $http_host;
-                proxy_set_header X-Real-IP $remote_addr;
-                proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
-                proxy_set_header X-Forwarded-Proto $scheme;
-                proxy_set_header X-Frame-Options SAMEORIGIN;
-                proxy_buffers 256 16k;
-                proxy_buffer_size 16k;
-                proxy_read_timeout 600s;
-                proxy_cache mattermost_cache;
-                proxy_cache_revalidate on;
-                proxy_cache_min_uses 2;
-                proxy_cache_use_stale timeout;
-                proxy_cache_lock on;
-                proxy_pass http://backend;
-            }
-        }
-
-
-   * Remove the existing file with
-   * ``` sudo rm /etc/nginx/sites-enabled/default```
-   * Link the mattermost config by typing:
-   * ```sudo ln -s /etc/nginx/sites-available/mattermost /etc/nginx/sites-enabled/mattermost```
-   * Restart NGINX by typing:
-   * ``` sudo service nginx restart```
-   * Verify you can see Mattermost thru the proxy by typing:
-   * ``` curl http://localhost```
-   * You should see a page titles *Mattermost - Signup*
+1. Log into the server that will host the proxy and open a terminal window.
+2. Make sure that your package index is up to date. 
+
+  ``sudo apt-get update``
+
+3. Install NGINX.
+
+  ``sudo apt-get install nginx``
+
+4. After the installation is complete, verify that NGINX is running.
+
+  ``curl http://localhost``
+  
+  If NGINX is running, you see the following output:
+  
+  .. code-block:: html
+  
+    <!DOCTYPE html>
+    <html>
+    <head>
+    <title>Welcome to nginx!</title>
+    .
+    .
+    .
+    <p><em>Thank you for using nginx.</em></p>
+    </body>
+    </html>
+
+.. Note::
+  
+  You can stop, start, and restart NGINX with the following commands:
+  
+  .. code-block:: none
+  
+    sudo service nginx stop
+    sudo service nginx start
+    sudo service nginx restart
+
+**What to do next**
+
+1. Map a fully qualified domain name (FQDN) such as ``mattermost.example.com`` to point to the NGINX server.
+2. Configure NGINX to proxy connections from the internet to the Mattermost Server.
+
+**Related links**
+  - :ref:`config-proxy-nginx` 

source/install/install-ubuntu-1404-mattermost.rst

@@ -1,5 +1,7 @@
+.. _install-ubuntu-1404-mattermost:
+
 Installing Mattermost Server
-================================
+============================
 
 Install Mattermost Server on a 64-bit machine.