From a1a77c2c1a5087f63376d5d4c7572c188dfaad4e Mon Sep 17 00:00:00 2001 From: Jeff Schering Date: Mon, 28 Nov 2016 15:39:09 -0800 Subject: [PATCH] Added a couple more files and started revising the content --- source/guides/administrator.rst | 6 ++-- source/install/config-mattermost-server.rst | 4 +-- source/install/config-mattermost.rst | 13 +++++++ source/install/config-ssl-http2-nginx.rst | 4 +-- source/install/config-tls-mattermost.rst | 8 ++--- source/install/install-common-intro.rst | 5 +++ source/install/install-nginx.rst | 32 +++++++++-------- .../install-ubuntu-1404-mattermost.rst | 30 +++++++++------- source/install/install-ubuntu-1404-mysql.rst | 36 ++++++++++--------- .../install/install-ubuntu-1404-overview.rst | 7 ++-- .../install-ubuntu-1404-postgresql.rst | 36 ++++++++++--------- source/install/install-ubuntu-1404.rst | 19 +++++----- 12 files changed, 117 insertions(+), 83 deletions(-) create mode 100644 source/install/config-mattermost.rst create mode 100644 source/install/install-common-intro.rst diff --git a/source/guides/administrator.rst b/source/guides/administrator.rst index cd2b13681ae..0bb795050cf 100644 --- a/source/guides/administrator.rst +++ b/source/guides/administrator.rst @@ -27,11 +27,9 @@ Configuring Mattermost ---------------------- .. toctree:: - :maxdepth: 1 + :maxdepth: 2 - /install/config-mattermost-server.rst - /install/config-tls-mattermost.rst - /install/config-ssl-http2-nginx.rst + /install/config-mattermost.rst Deployment ---------- diff --git a/source/install/config-mattermost-server.rst b/source/install/config-mattermost-server.rst index 8353c623070..19157ba4b33 100644 --- a/source/install/config-mattermost-server.rst +++ b/source/install/config-mattermost-server.rst @@ -1,5 +1,5 @@ -Test setup and configure Mattermost Server -========================================== +Configuring Mattermost Server +============================= 1. Navigate to ``https://mattermost.example.com`` and create a team and user. diff --git a/source/install/config-mattermost.rst b/source/install/config-mattermost.rst new file mode 100644 index 00000000000..8b706eabee9 --- /dev/null +++ b/source/install/config-mattermost.rst @@ -0,0 +1,13 @@ +====================== +Configuring Mattermost +====================== + +After installing the Mattermost components, you must create the first user and first team. You can also configure the system to enhance performance and security. + +.. contents:: + :backlinks: top + :local: + +.. include:: config-mattermost-server.rst +.. include:: config-tls-mattermost.rst +.. include:: config-ssl-http2-nginx.rst diff --git a/source/install/config-ssl-http2-nginx.rst b/source/install/config-ssl-http2-nginx.rst index 033ec2b051d..6404043c2aa 100644 --- a/source/install/config-ssl-http2-nginx.rst +++ b/source/install/config-ssl-http2-nginx.rst @@ -1,5 +1,5 @@ -Set up NGINX with SSL (Recommended) -=================================== +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 diff --git a/source/install/config-tls-mattermost.rst b/source/install/config-tls-mattermost.rst index 10d4face173..30b767ac870 100644 --- a/source/install/config-tls-mattermost.rst +++ b/source/install/config-tls-mattermost.rst @@ -1,6 +1,4 @@ -.. _setup-tls: - -TLS Setup on Mattermost Server +Configuring TLS on the Mattermost Server ======================================== 1. Go to the **General** > **Configuration** section of the System Console. @@ -12,7 +10,7 @@ TLS Setup on Mattermost Server At this point you have two options: automatic certificate retrieval though Let's Encrypt or manually specifying a certificate. Automatic Certificate Retrieval -------------------------------------------- +------------------------------- In this mode a certificate will be automatically retrieved the first time a client tries to connect to the Mattermost server. Certificates will be retrieved for any hostname a client tries to reach the server at. Setting this up is only one step: @@ -21,7 +19,7 @@ In this mode a certificate will be automatically retrieved the first time a clie Manual Certificate Specification ----------------------------------------------- +-------------------------------- 1. Change the **Use Let's Encrypt** setting to ``false``. 2. Change the **TLS Certificate File** setting to the location of the certificate file. diff --git a/source/install/install-common-intro.rst b/source/install/install-common-intro.rst new file mode 100644 index 00000000000..0f2dd1d7208 --- /dev/null +++ b/source/install/install-common-intro.rst @@ -0,0 +1,5 @@ +A complete Mattermost installation consists of 3 major components: a proxy server, a database server, and the Mattermost server. You can install all components on 1 machine, or you can install each component on its own machine. If you have only 2 machines, then install the proxy and the Mattermost server on one machine, and install the database on the other machine. + +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 diff --git a/source/install/install-nginx.rst b/source/install/install-nginx.rst index 7c7d850d212..38b146a56b1 100644 --- a/source/install/install-nginx.rst +++ b/source/install/install-nginx.rst @@ -1,35 +1,37 @@ -Set up NGINX Server -=================== +Installing NGINX Server +======================= -1. For the purposes of this guide we will assume this server has an IP - address of ``10.10.10.3`` -2. We use NGINX for proxying request to the Mattermost Server. The main - benefits are: +In a production setting, use a proxy server for greater security and performance of Mattermost. - - SSL termination - - http to https redirect - - Port mapping ``:80`` to ``:8065`` - - Standard request logs +The main benefits of using a proxy are as follows: + - SSL termination + - HTTP to HTTPS redirect + - Port mapping ``:80`` to ``:8065`` + - Standard request logs -3. Install NGINX on Ubuntu with +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`` -4. Verify NGINX is running +2. Verify NGINX is running - ``curl http://10.10.10.3`` - You should see a *Welcome to NGINX!* page -5. You can manage NGINX with the following commands +3. You can manage NGINX with the following commands - ``sudo service nginx stop`` - ``sudo service nginx start`` - ``sudo service nginx restart`` -6. Map a FQDN (fully qualified domain name) like +4. Map a FQDN (fully qualified domain name) like ``mattermost.example.com`` to point to the NGINX server. -7. Configure NGINX to proxy connections from the internet to the +5. Configure NGINX to proxy connections from the internet to the Mattermost Server - Create a configuration for Mattermost diff --git a/source/install/install-ubuntu-1404-mattermost.rst b/source/install/install-ubuntu-1404-mattermost.rst index 4b14cc95339..c59f837485f 100644 --- a/source/install/install-ubuntu-1404-mattermost.rst +++ b/source/install/install-ubuntu-1404-mattermost.rst @@ -1,30 +1,36 @@ -Set up Mattermost Server -======================== +Installing Mattermost Server +================================ -For the purposes of this guide we will assume this server has an IP address of ``10.10.10.2`` +Install Mattermost Server on a 64-bit machine. -1. Create a mattermost user and group +Assume that the IP address of this server is 10.10.10.2 + +**To install Mattermost Server on Ubuntu** + +1. Log into the server that will host Mattermost Server and open a terminal window. + +2. Create a mattermost user and group - ``sudo adduser --system --group mattermost`` -2. Change to the mattermost home directory. +3. Change to the mattermost home directory. ``cd /home/mattermost`` -3. Download `the latest version of the Mattermost Server `_ by typing: +4. Download `the latest version of the Mattermost Server `_ by typing: - ``wget https://releases.mattermost.com/X.X.X/mattermost-X.X.X-linux-amd64.tar.gz`` - Where ``vX.X.X`` is the latest version. -4. Extract the Mattermost Server files by typing: +5. Extract the Mattermost Server files by typing: - ``sudo tar -xvzf *.gz`` -5. Change the user and group of the extracted files to mattermost +6. Change the user and group of the extracted files to mattermost - ``sudo chown -R mattermost:mattermost mattermost/`` -6. Create the storage directory for files. We assume you will have +7. Create the storage directory for files. We assume you will have attached a large drive for storage of images and files. For this setup we will assume the directory is located at ``/mattermost/data``. @@ -34,7 +40,7 @@ For the purposes of this guide we will assume this server has an IP address of ` - Set the mattermost account as the directory owner by typing: - ``sudo chown -R mattermost:mattermost /mattermost`` -7. Configure Mattermost Server by editing the config.json file at +8. Configure Mattermost Server by editing the config.json file at ``/home/mattermost/config`` - ``cd /home/mattermost/mattermost/config`` @@ -50,7 +56,7 @@ For the purposes of this guide we will assume this server has an IP address of ` ``config.json`` or use the System Console described in a later section to finish the configuration. -8. Test the Mattermost Server +9. Test the Mattermost Server - ``cd ~/mattermost/bin`` - Run the Mattermost Server by typing: @@ -59,7 +65,7 @@ For the purposes of this guide we will assume this server has an IP address of ` letting you know the service is running. - Stop the server for now by typing ``ctrl-c`` -9. Setup Mattermost to use the Upstart daemon which handles supervision +10. Setup Mattermost to use the Upstart daemon which handles supervision of the Mattermost process. - ``sudo touch /etc/init/mattermost.conf`` diff --git a/source/install/install-ubuntu-1404-mysql.rst b/source/install/install-ubuntu-1404-mysql.rst index b4f76cf6a8b..0add5ae21c5 100644 --- a/source/install/install-ubuntu-1404-mysql.rst +++ b/source/install/install-ubuntu-1404-mysql.rst @@ -1,31 +1,35 @@ -Set up MySQL Database Server -============================ +Installing MySQL Database Server +================================ -1. Install MySQL 5.6. +Mattermost supports either MySQL or PostgreSQL. - - ``sudo apt-get install mysql-server-5.6`` +**To install MySQL 5.6 on Ubuntu Server:** +1. Log into the server that will host the database and issue the following command: + + ``sudo apt-get install mysql-server-5.6`` + 2. Log in to MySQL as root. + + ``mysql -u root -p`` + + When prompted, enter the root password that you created when installing MySQL. - - ``mysql -u root -p`` +3. Create the Mattermost user 'mmuser'. - When prompted, enter the root password that you created when installing MySQL. + ``mysql> create user 'mmuser'@'%' identified by 'mmuser-password';`` -3. Create the Mattermost user, 'mmuser'. + **Notes**: - - ``mysql> create user 'mmuser'@'%' identified by 'mmuser-password';`` + 1. Use a password that is more secure than 'mmuser-password' + 2. The '%' means that mmuser can connect from any machine on the network. However, it's more secure to use the IP address of the machine that hosts Mattermost. For example, if you install Mattermost on the machine with IP address 10.10.10.2, then use the following command: - **Notes**: - - 1. Use a password that is more secure than 'mmuser-password' - 2. The '%' means that mmuser can connect from any machine on the network. However, it's more secure to use the IP address of the machine that hosts Mattermost. For example, if you install Mattermost on the machine with IP address 10.10.10.2, then use the following command: - - - ``mysql> create user 'mmuser'@'10.10.10.2' identified by 'mmuser-password';`` + ``mysql> create user 'mmuser'@'10.10.10.2' identified by 'mmuser-password';`` 4. Create the Mattermost database. - - ``mysql> create database mattermost;`` + ``mysql> create database mattermost;`` 5. Grant access privileges to the user 'mmuser' - - ``mysql> grant all privileges on mattermost.* to 'mmuser'@'%';`` + ``mysql> grant all privileges on mattermost.* to 'mmuser'@'%';`` diff --git a/source/install/install-ubuntu-1404-overview.rst b/source/install/install-ubuntu-1404-overview.rst index 41c02df38a6..b8c26c7bc6b 100644 --- a/source/install/install-ubuntu-1404-overview.rst +++ b/source/install/install-ubuntu-1404-overview.rst @@ -2,17 +2,18 @@ Installing Mattermost on Ubuntu 14.04 LTS ========================================= +Install a production-ready Mattermost system on 1 to 3 machines. -Install Mattermost in production mode on one, two or three machines, using the following steps: +.. include:: install-common-intro.rst -.. contents:: +.. contents:: Install the components in the following order: :backlinks: top :local: .. include:: install-ubuntu-1404.rst .. include:: install-ubuntu-1404-mysql.rst .. include:: install-ubuntu-1404-postgresql.rst -.. include:: install-ubuntu_1404-mattermost.rst +.. include:: install-ubuntu-1404-mattermost.rst .. include:: install-nginx.rst .. diff --git a/source/install/install-ubuntu-1404-postgresql.rst b/source/install/install-ubuntu-1404-postgresql.rst index 126b4b74a90..077bea23540 100644 --- a/source/install/install-ubuntu-1404-postgresql.rst +++ b/source/install/install-ubuntu-1404-postgresql.rst @@ -1,54 +1,58 @@ -Set up PostreSQL -================ +Installing PostreSQL Database Server +==================================== -1. For the purposes of this guide we will assume this server has an IP - address of 10.10.10.1 -2. Install PostgreSQL 9.3+ +Mattermost supports either PostgreSQL or MySQL. + +Assume that the IP address of this server is 10.10.10.1 + +**To install PostgreSQL on Ubuntu Server:** + +1. Log into the server that will host the database and issue the following command: - ``sudo apt-get install postgresql postgresql-contrib`` -3. PostgreSQL created a user account called ``postgres``. You will need +2. PostgreSQL created a user account called ``postgres``. You will need to log into that account with: - ``sudo -i -u postgres`` -4. You can get a PostgreSQL prompt by typing: +3. You can get a PostgreSQL prompt by typing: - ``psql`` -5. Create the Mattermost database by typing: +4. Create the Mattermost database by typing: - ``postgres=# CREATE DATABASE mattermost;`` -6. Create the Mattermost user by typing: +5. Create the Mattermost user by typing: - ``postgres=# CREATE USER mmuser WITH PASSWORD 'mmuser_password';`` -7. Grant the user access to the Mattermost database by typing: +6. Grant the user access to the Mattermost database by typing: - ``postgres=# GRANT ALL PRIVILEGES ON DATABASE mattermost to mmuser;`` -8. You can exit out of PostgreSQL by typing: +7. You can exit out of PostgreSQL by typing: - ``postgre=# \q`` -9. You can exit the postgres account by typing: +8. You can exit the postgres account by typing: - ``exit`` -10. Allow Postgres to listen on all assigned IP Addresses +9. Allow Postgres to listen on all assigned IP Addresses - ``sudo vi /etc/postgresql/9.3/main/postgresql.conf`` - Uncomment ``listen_addresses`` and change ``localhost`` to ``*`` -11. Alter pg\_hba.conf to allow the mattermost server to talk to the +10. Alter pg\_hba.conf to allow the mattermost server to talk to the postgres database - ``sudo vi /etc/postgresql/9.3/main/pg_hba.conf`` - Add the following line to the ``IPv4 local connections`` - ``host all all 10.10.10.2/32 md5`` -12. Reload Postgres database +11. Reload Postgres database - ``sudo /etc/init.d/postgresql reload`` @@ -60,7 +64,7 @@ Set up PostreSQL - ``sudo service postgresql restart`` -13. Attempt to connect with the new created user to verify everything +12. Attempt to connect with the new created user to verify everything looks good - ``psql --host=10.10.10.1 --dbname=mattermost --username=mmuser --password`` diff --git a/source/install/install-ubuntu-1404.rst b/source/install/install-ubuntu-1404.rst index cd80513ae92..ce406c6e7e6 100644 --- a/source/install/install-ubuntu-1404.rst +++ b/source/install/install-ubuntu-1404.rst @@ -1,14 +1,17 @@ -Install Ubuntu Server (x64) 14.04 LTS -===================================== +Installing Ubuntu Server 14.04 LTS +================================== -1. Set up 3 machines with Ubuntu 14.04 with 2GB of RAM or more. The - servers will be used for the Proxy, Mattermost (must be - x64), and Database. +Install Ubuntu Server on each machine that hosts one or more of the components. In most cases you need the 64-bit version. - - **Optional:** You can also use a **1 machine setup** (Proxy, Mattermost and Database on one machine) or a **2 machine setup** (Proxy and Mattermost on one machine, Database on another) depending on your data center standards. +You can use the 32-bit version on a machine that hosts the database and proxy server, but the Mattermost server requires 64-bit. -2. Make sure the system is up to date with the most recent security - patches. +**To install Ubuntu Server:** + +1. Download the appropriate ISO image from http://releases.ubuntu.com/14.04.5/ and burn it to a CD-ROM. + +2. Boot the system from the CD-ROM drive and follow the on-screen prompts. + +3. After the system is installed, make sure that it's up to date with the most recent security patches. Open a terminal window and issue the following commands: - ``sudo apt-get update`` - ``sudo apt-get upgrade``