diff options
Diffstat (limited to 'doc/install')
| -rw-r--r-- | doc/install/Administration.md | 19 | ||||
| -rw-r--r-- | doc/install/Amazon-Elastic-Beanstalk.md | 45 | ||||
| -rw-r--r-- | doc/install/Production-Debian.md | 302 | ||||
| -rw-r--r-- | doc/install/Production-Ubuntu.md | 11 | ||||
| -rw-r--r-- | doc/install/Requirements.md | 21 | ||||
| -rw-r--r-- | doc/install/SMTP-Email-Setup.md | 12 | ||||
| -rw-r--r-- | doc/install/Troubleshooting.md | 19 | ||||
| -rw-r--r-- | doc/install/Upgrade-Guide.md | 21 |
8 files changed, 414 insertions, 36 deletions
diff --git a/doc/install/Administration.md b/doc/install/Administration.md new file mode 100644 index 000000000..ee996088c --- /dev/null +++ b/doc/install/Administration.md @@ -0,0 +1,19 @@ +# Administration + +This document provides instructions for common administrator tasks + +#### Important notes + +##### **DO NOT manipulate the Mattermost database** + - In particular, DO NOT delete data from the database, as Mattermost is designed to stop working if data integrity has been compromised. The system is designed to archive content continously and generally assumes data is never deleted. + +### Common Tasks + +##### Creating System Administrator account from commandline + - If the System Administrator account becomes unavailable, a person leaving the organization for example, you can set a new system admin from the commandline using `./platform -assign_role -team_name="yourteam" -email="you@example.com" -role="system_admin"`. + - After assigning the role the user needs to log out and log back in before the System Administrator role is applied. + +##### Deactivating a user + + - Team Admin or System Admin can go to **Main Menu** > **Manage Members** > **Make Inactive** to deactivate a user, which removes them from the team. + - To preserve audit history, users are never deleted from the system. It is highly recommended that System Administrators do not attempt to delete users manually from the database, as this may compromise system integrity and ability to upgrade in future. diff --git a/doc/install/Amazon-Elastic-Beanstalk.md b/doc/install/Amazon-Elastic-Beanstalk.md index 0416b67ea..8738ab3ac 100644 --- a/doc/install/Amazon-Elastic-Beanstalk.md +++ b/doc/install/Amazon-Elastic-Beanstalk.md @@ -1,27 +1,26 @@ ## AWS Elastic Beanstalk Setup (Docker) +These instructions will guide you through the process of setting up Mattermost for product evaluation using an EBS Docker single-container application using [Dockerrun.aws.zip](https://github.com/mattermost/platform/raw/master/docker/1.1/Dockerrun.aws.zip). -1. Create a new Elastic Beanstalk Docker application using the [Dockerrun.aws.zip](https://github.com/mattermost/platform/raw/master/docker/1.0/Dockerrun.aws.zip) file provided. - 1. From the AWS console select Elastic Beanstalk. - 2. Select "Create New Application" from the top right. - 3. Name the application and press next. - 4. Select "Create a web server" environment. - 5. If asked, select create an IAM role and instance profile and press next. - 6. For predefined configuration select under Generic: Docker. For environment type select single instance. - 7. For application source, select upload your own and upload Dockerrun.aws.zip from [Dockerrun.aws.zip](https://github.com/mattermost/platform/raw/master/docker/1.0/Dockerrun.aws.zip). Everything else may be left at default. - 8. Select an environment name, this is how you will refer to your environment. Make sure the URL is available then press next. - 9. The options on the additional resources page may be left at default unless you wish to change them. Press Next. - 10. On the configuration details place. Select an instance type of t2.small or larger. - 11. You can set the configuration details as you please but they may be left at their defaults. When you are done press next. - 12. Environment tags my be left blank. Press next. - 13. You will be asked to review your information. Press Launch. - -4. Try it out! - 14. Wait for beanstalk to update the environment. - 15. Try it out by entering the domain of the form \*.elasticbeanstalk.com found at the top of the dashboard into your browser. You can also map your own domain if you wish. - - - ### (Recommended) Enable Email - The default single-container Docker instance for Mattermost is designed for product evaluation, and sets `ByPassEmail=true` so the product can run without enabling email, when doing so maybe difficult. +1. From your [AWS console]( https://console.aws.amazon.com/console/home) select **Elastic Beanstalk** under the Compute section. +2. Select **Create New Application** from the top right. +3. Name your Elastic Beanstalk application and click **Next**, +4. Select **Create web server** on the New Enviroment page. +5. If asked, select **Create an IAM role and instance profile**, then click **Next**. +6. On the Enviroment Type page, + 1. Set Predefined Configuration to **Docker** under the generic heading in the drop-down list. + 2. Set Environment Type to **Single instance** in the drop-down list. + 3. Click **Next**. +7. For Application Source, select **Upload your own** and upload the [Dockerrun.aws.zip](https://github.com/mattermost/platform/raw/master/docker/1.1/Dockerrun.aws.zip) file, then click **Next**. +8. Type an Environment Name and URL. Make sure the URL is available by clicking **Check availability**, then click **Next**. +9. The options on the Additional Resources page may be left at default unless you wish to change them. Click **Next**. +10. On the Configuration Details page, + 1. Select an Instance Type of **t2.small** or larger. + 2. The remaining options may be left at their default values unless you wish to change them. Click **Next**. +11. Environment tags may be left blank. Click **Next**. +12. You will be asked to review your information, then click **Launch**. +14. It may take a few minutes for beanstalk to launch your environment. If the launch is successful, you will see a see a large green checkmark and the Health status should change to “Green”. +15. Test your environment by clicking the domain link next to your application name at the top of the dashboard. Alternatively, enter the domain into your browser in the form `http://<your-ebs-application-url>.elasticbeanstalk.com`. You can also map your own domain if you wish. If everything is working correctly, the domain should navigate you to the Mattermost signup page. Enjoy exploring Mattermost! - To see the product's full functionality, [enabling SMTP email is recommended](SMTP-Email-Setup.md). +### (Recommended) Enable Email +The default single-container Docker instance for Mattermost is designed for product evaluation, and sets `SendEmailNotifications=false` so the product can function without enabling email. To see the product's full functionality, [enabling SMTP email is recommended](SMTP-Email-Setup.md). diff --git a/doc/install/Production-Debian.md b/doc/install/Production-Debian.md new file mode 100644 index 000000000..e97f3188b --- /dev/null +++ b/doc/install/Production-Debian.md @@ -0,0 +1,302 @@ +# (Community Guide) Production Installation on Debian Jessie (x64) + +Note: This install guide has been generously contributed by the Mattermost community. It has not yet been tested by the core. We have [an open ticket](https://github.com/mattermost/platform/issues/1185) requesting community help testing and improving this guide. Once the community has confirmed we have multiple deployments on these instructions, we can update the text here. If you're installing on Debian anyway, please let us know any issues or instruciton improvements? https://github.com/mattermost/platform/issues/1185 + + +## Install Debian Jessie (x64) +1. Set up 3 machines with Debian Jessie with 2GB of RAM or more. The servers will be used for the Load Balancer, Mattermost (this must be x64 to use pre-built binaries), and Database. +1. This can also be set up all on a single server for small teams: + * I have a Mattermost instance running on a single Debian Jessie server with 1GB of ram and 30 GB SSD + * This has been working in production for ~20 users without issue. + * The only difference in the below instructions for this method is to do everything on the same server +1. Make sure the system is up to date with the most recent security patches. + * ``` sudo apt-get update``` + * ``` sudo apt-get upgrade``` + +## Set up Database Server +1. For the purposes of this guide we will assume this server has an IP address of 10.10.10.1 +1. Install PostgreSQL 9.3+ (or MySQL 5.6+) + * ``` sudo apt-get install postgresql postgresql-contrib``` +1. PostgreSQL created a user account called `postgres`. You will need to log into that account with: + * ``` sudo -i -u postgres``` +1. You can get a PostgreSQL prompt by typing: + * ``` psql``` +1. Create the Mattermost database by typing: + * ```postgres=# CREATE DATABASE mattermost;``` +1. Create the Mattermost user by typing: + * ```postgres=# CREATE USER mmuser WITH PASSWORD 'mmuser_password';``` +1. Grant the user access to the Mattermost database by typing: + * ```postgres=# GRANT ALL PRIVILEGES ON DATABASE mattermost to mmuser;``` +1. You can exit out of PostgreSQL by typing: + * ```postgre=# \q``` +1. You can exit the postgres account by typing: + * ``` exit``` + +## Set up Mattermost Server +1. For the purposes of this guide we will assume this server has an IP address of 10.10.10.2 +1. Download the latest Mattermost Server by typing: + * ``` wget https://github.com/mattermost/platform/releases/download/v1.1.0/mattermost.tar.gz``` +1. Install Mattermost under /opt + * ``` cd /opt``` + * Unzip the Mattermost Server by typing: + * ``` tar -xvzf mattermost.tar.gz``` +1. 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`. + * Create the directory by typing: + * ``` sudo mkdir -p /opt/mattermost/data``` +1. Create a system user and group called mattermost that will run this service + * ``` useradd -r mattermost -U``` + * Set the mattermost account as the directory owner by typing: + * ``` sudo chown -R mattermost:mattermost /opt/mattermost``` + * Add yourself to the mattermost group to ensure you can edit these files: + * ``` sudo usermod -aG mattermost USERNAME``` +1. Configure Mattermost Server by editing the config.json file at /opt/mattermost/config + * ``` cd /opt/mattermost/config``` + * Edit the file by typing: + * ``` vi config.json``` + * replace `DriverName": "mysql"` with `DriverName": "postgres"` + * replace `"DataSource": "mmuser:mostest@tcp(dockerhost:3306)/mattermost_test?charset=utf8mb4,utf8"` with `"DataSource": "postgres://mmuser:mmuser_password@10.10.10.1:5432/mattermost?sslmode=disable&connect_timeout=10"` + * Optionally you may continue to edit configuration settings in `config.json` or use the System Console described in a later section to finish the configuration. +1. Test the Mattermost Server + * ``` cd /opt/mattermost/bin``` + * Run the Mattermost Server by typing: + * ``` ./platform``` + * You should see a console log like `Server is listening on :8065` letting you know the service is running. + * Stop the server for now by typing `ctrl-c` +1. Setup Mattermost to use the systemd init daemon which handles supervision of the Mattermost process + * ``` sudo touch /etc/init.d/mattermost``` + * ``` sudo vi /etc/init.d/mattermost``` + * Copy the following lines into `/etc/init.d/mattermost` +``` +#! /bin/sh +### BEGIN INIT INFO +# Provides: mattermost +# Required-Start: $network $syslog +# Required-Stop: $network $syslog +# Default-Start: 2 3 4 5 +# Default-Stop: 0 1 6 +# Short-Description: Mattermost Group Chat +# Description: Mattermost: An open-source Slack +### END INIT INFO + +PATH=/sbin:/usr/sbin:/bin:/usr/bin +DESC="Mattermost" +NAME=mattermost +MATTERMOST_ROOT=/opt/mattermost +MATTERMOST_GROUP=mattermost +MATTERMOST_USER=mattermost +DAEMON="$MATTERMOST_ROOT/bin/platform" +PIDFILE=/var/run/$NAME.pid +SCRIPTNAME=/etc/init.d/$NAME + +. /lib/lsb/init-functions + +do_start() { + # Return + # 0 if daemon has been started + # 1 if daemon was already running + # 2 if daemon could not be started + start-stop-daemon --start --quiet \ + --chuid $MATTERMOST_USER:$MATTERMOST_GROUP --chdir $MATTERMOST_ROOT --background \ + --pidfile $PIDFILE --exec $DAEMON --test > /dev/null \ + || return 1 + start-stop-daemon --start --quiet \ + --chuid $MATTERMOST_USER:$MATTERMOST_GROUP --chdir $MATTERMOST_ROOT --background \ + --make-pidfile --pidfile $PIDFILE --exec $DAEMON \ + || return 2 +} + +# +# Function that stops the daemon/service +# +do_stop() { + # Return + # 0 if daemon has been stopped + # 1 if daemon was already stopped + # 2 if daemon could not be stopped + # other if a failure occurred + start-stop-daemon --stop --quiet --retry=TERM/30/KILL/5 \ + --pidfile $PIDFILE --exec $DAEMON + RETVAL="$?" + [ "$RETVAL" = 2 ] && return 2 + # Wait for children to finish too if this is a daemon that forks + # and if the daemon is only ever run from this initscript. + # If the above conditions are not satisfied then add some other code + # that waits for the process to drop all resources that could be + # needed by services started subsequently. A last resort is to + # sleep for some time. + start-stop-daemon --stop --quiet --oknodo --retry=0/30/KILL/5 \ + --exec $DAEMON + [ "$?" = 2 ] && return 2 + # Many daemons don't delete their pidfiles when they exit. + rm -f $PIDFILE + return "$RETVAL" +} + +case "$1" in +start) + [ "$VERBOSE" != no ] && log_daemon_msg "Starting $DESC" "$NAME" + do_start + case "$?" in + 0|1) [ "$VERBOSE" != no ] && log_end_msg 0 ;; + 2) [ "$VERBOSE" != no ] && log_end_msg 1 ;; + esac + ;; +stop) + [ "$VERBOSE" != no ] && log_daemon_msg "Stopping $DESC" "$NAME" + do_stop + case "$?" in + 0|1) [ "$VERBOSE" != no ] && log_end_msg 0 ;; + 2) [ "$VERBOSE" != no ] && log_end_msg 1 ;; + esac + ;; +status) + status_of_proc "$DAEMON" "$NAME" && exit 0 || exit $? + ;; +restart|force-reload) + # + # If the "reload" option is implemented then remove the + # 'force-reload' alias + # + log_daemon_msg "Restarting $DESC" "$NAME" + do_stop + case "$?" in + 0|1) + do_start + case "$?" in + 0) log_end_msg 0 ;; + 1) log_end_msg 1 ;; # Old process is still running + *) log_end_msg 1 ;; # Failed to start + esac + ;; + *) + # Failed to stop + log_end_msg 1 + ;; + esac + ;; +*) + echo "Usage: $SCRIPTNAME {start|stop|status|restart|force-reload}" >&2 + exit 3 + ;; +esac + +exit 0 +``` + * Make sure that /etc/init.d/mattermost is executable + * ``` chmod +x /etc/init.d/mattermost``` +1. On reboot, systemd will generate a unit file from the headers in this init script and install it in `/run/systemd/generator.late/` + +## Set up Nginx Server +1. For the purposes of this guide we will assume this server has an IP address of 10.10.10.3 +1. We use Nginx for proxying request to the Mattermost Server. The main benefits are: + * SSL termination + * http to https redirect + * Port mapping :80 to :8065 + * Standard request logs +1. Install Nginx on Debian with + * ``` sudo apt-get install nginx``` +1. Verify Nginx is running + * ``` curl http://10.10.10.3``` + * You should see a *Welcome to nginx!* page +1. You can manage Nginx with the following commands + * ``` sudo service nginx stop``` + * ``` sudo service nginx start``` + * ``` sudo service nginx restart``` +1. Map a FQDN (fully qualified domain name) like **mattermost.example.com** to point to the Nginx server. +1. 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 configuration with the minimum settings required to configure Mattermost + ``` + server { + server_name mattermost.example.com; + location / { + client_max_body_size 50M; + proxy_set_header Upgrade $http_upgrade; + proxy_set_header Connection "upgrade"; + 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_pass http://localhost:8065; + } + } +``` + * 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* + +## Set up Nginx with SSL (Recommended) +1. You will need a SSL cert from a certificate authority. +1. For simplicity we will generate a test certificate. + * ``` mkdir ~/cert``` + * ``` cd ~/cert``` + * ``` sudo openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout mattermost.key -out mattermost.crt``` + * Input the following info +``` + Country Name (2 letter code) [AU]:US + State or Province Name (full name) [Some-State]:California + Locality Name (eg, city) []:Palo Alto + Organization Name (eg, company) [Internet Widgits Pty Ltd]:Example LLC + Organizational Unit Name (eg, section) []: + Common Name (e.g. server FQDN or YOUR name) []:mattermost.example.com + Email Address []:admin@mattermost.example.com +``` +1. Modify the file at `/etc/nginx/sites-available/mattermost` and add the following lines + * +``` + server { + listen 80; + server_name mattermost.example.com; + return 301 https://$server_name$request_uri; + } + + server { + listen 443 ssl; + server_name mattermost.example.com; + + ssl on; + ssl_certificate /home/mattermost/cert/mattermost.crt; + ssl_certificate_key /home/mattermost/cert/mattermost.key; + ssl_session_timeout 5m; + ssl_protocols SSLv3 TLSv1 TLSv1.1 TLSv1.2; + ssl_ciphers "HIGH:!aNULL:!MD5 or HIGH:!aNULL:!MD5:!3DES"; + ssl_prefer_server_ciphers on; + + # add to location / above + location / { + gzip off; + proxy_set_header X-Forwarded-Ssl on; +``` +## Finish Mattermost Server setup +1. Navigate to https://mattermost.example.com and create a team and user. +1. The first user in the system is automatically granted the `system_admin` role, which gives you access to the System Console. +1. From the `town-square` channel click the dropdown and choose the `System Console` option +1. Update Email Settings. We recommend using an email sending service. The example below assumes AmazonSES. + * Set *Send Email Notifications* to true + * Set *Require Email Verification* to true + * Set *Feedback Name* to `No-Reply` + * Set *Feedback Email* to `mattermost@example.com` + * Set *SMTP Username* to `AFIADTOVDKDLGERR` + * Set *SMTP Password* to `DFKJoiweklsjdflkjOIGHLSDFJewiskdjf` + * Set *SMTP Server* to `email-smtp.us-east-1.amazonaws.com` + * Set *SMTP Port* to `465` + * Set *Connection Security* to `TLS` + * Save the Settings +1. Update File Settings + * Change *Local Directory Location* from `./data/` to `/mattermost/data` +1. Update Log Settings. + * Set *Log to The Console* to false +1. Update Rate Limit Settings. + * Set *Vary By Remote Address* to false + * Set *Vary By HTTP Header* to X-Real-IP +1. Feel free to modify other settings. +1. Restart the Mattermost Service by typing: + * ``` sudo restart mattermost``` diff --git a/doc/install/Production-Ubuntu.md b/doc/install/Production-Ubuntu.md index 836af3995..2e02cca38 100644 --- a/doc/install/Production-Ubuntu.md +++ b/doc/install/Production-Ubuntu.md @@ -119,7 +119,7 @@ exec bin/platform ## Set up Nginx with SSL (Recommended) 1. You will need a SSL cert from a certificate authority. -1. For simplicity we will generate a test certificate. +2. For simplicity we will generate a test certificate. * ``` mkdir ~/cert``` * ``` cd ~/cert``` * ``` sudo openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout mattermost.key -out mattermost.crt``` @@ -133,8 +133,8 @@ exec bin/platform Common Name (e.g. server FQDN or YOUR name) []:mattermost.example.com Email Address []:admin@mattermost.example.com ``` -1. Modify the file at `/etc/nginx/sites-available/mattermost` and add the following lines - * +3. Run `openssl dhparam -out dhparam.pem 4096` (it will take some time). +4. Modify the file at `/etc/nginx/sites-available/mattermost` and add the following lines: ``` server { listen 80; @@ -149,9 +149,10 @@ exec bin/platform ssl on; ssl_certificate /home/ubuntu/cert/mattermost.crt; ssl_certificate_key /home/ubuntu/cert/mattermost.key; + ssl_dhparam /home/ubuntu/cert/dhparam.pem; ssl_session_timeout 5m; - ssl_protocols SSLv3 TLSv1 TLSv1.1 TLSv1.2; - ssl_ciphers "HIGH:!aNULL:!MD5 or HIGH:!aNULL:!MD5:!3DES"; + ssl_protocols TLSv1 TLSv1.1 TLSv1.2; + ssl_ciphers 'EECDH+AESGCM:EDH+AESGCM:AES256+EECDH:AES256+EDH'; ssl_prefer_server_ciphers on; # add to location / above diff --git a/doc/install/Requirements.md b/doc/install/Requirements.md index 1e0a12fb9..61fa8e7be 100644 --- a/doc/install/Requirements.md +++ b/doc/install/Requirements.md @@ -10,6 +10,27 @@ Supported Operating Systems and Browsers for the Mattermost Web Client include: - iPhone 4s and higher (Safari on iOS 8.3+, Chrome 43+) - Android 5 and higher (Chrome 43+) +### Email Client + +Supported Email Clients for rendering Mattermost email notifications include: + +Web based clients: +- Gmail +- Office 365 +- Outlook +- Yahoo +- AOL + +Desktop Clients: +- Apple Mail version 7+ +- Outlook 2016+ +- Thunderbird 38.2+ + +Mobile Clients: +- Gmail Mobile App (Android, iOS) +- iOS Mail App (iOS 7+) +- Blackberry Mail App (OS version 4+) + ### Server Supported Operating Systems for the Mattermost Server include: diff --git a/doc/install/SMTP-Email-Setup.md b/doc/install/SMTP-Email-Setup.md index bb57d95ba..7d9beae89 100644 --- a/doc/install/SMTP-Email-Setup.md +++ b/doc/install/SMTP-Email-Setup.md @@ -52,10 +52,18 @@ To enable email, configure an SMTP email service as follows: * Set **Connection Security** to **(empty)** ##### Gmail -* Information needed +* Set **SMTP Username** to **your_email@gmail.com** +* Set **SMTP Password** to **your_password** +* Set **SMTP Server** to **smtp.gmail.com** +* Set **SMTP Port** to **587** +* Set **Connection Security** to **TLS** ##### Office 365 -* Information needed +* Set **SMTP Username** to **Office 365 username** +* Set **SMTP Password** to **Office 365 password** +* Set **SMTP Server** to **smtp.office365.com** +* Set **SMTP Port** to **587** +* Set **Connection Security** to **TLS** ##### Hotmail * Set **SMTP Username** to **your_email@hotmail.com** diff --git a/doc/install/Troubleshooting.md b/doc/install/Troubleshooting.md index 46efc61fa..7166f9978 100644 --- a/doc/install/Troubleshooting.md +++ b/doc/install/Troubleshooting.md @@ -8,10 +8,23 @@ #### Common Issues -##### Error message in logs when attempting to sign-up: `x509: certificate signed by unknown authority` - - This error may appear when attempt to use a self-signed certificate to setup SSL, which is not yet supported by Mattermost. You can resolve this issue by setting up a load balancer like Ngnix. A ticket exists to [add support for self-signed certificates in future](x509: certificate signed by unknown authority). - ##### Lost System Administrator account - If the System Administrator account becomes unavailable, a person leaving the organization for example, you can set a new system admin from the commandline using `./platform -assign_role -team_name="yourteam" -email="you@example.com" -role="system_admin"`. - After assigning the role the user needs to log out and log back in before the System Administrator role is applied. +#### Error Messages + +The following is a list of common error messages and solutions: + +###### `Please check connection, Mattermost unreachable. If issue persists, ask administrator to check WebSocket port.` +- Message appears in blue bar on team site. +- **Solution:** Check that [your websocket port is properly configured](https://github.com/mattermost/platform/blob/master/doc/install/Production-Ubuntu.md#set-up-nginx-server). + + +###### `x509: certificate signed by unknown authority` in server logs when attempting to sign-up + - This error may appear when attempt to use a self-signed certificate to setup SSL, which is not yet supported by Mattermost. You + - **Solution:** Set up a load balancer like Ngnix [per production install guide](https://github.com/mattermost/platform/blob/master/doc/install/Production-Ubuntu.md#set-up-nginx-with-ssl-recommended). A ticket exists to [add support for self-signed certificates in future](x509: certificate signed by unknown authority). + +###### `panic: runtime error: invalid memory address or nil pointer dereference` + - This error can occur if you have manually manipulated the Mattermost database, typically with deletions. Mattermost is designed to serve as a searchable archive, and manual manipulation of the database elements compromises integrity and may prevent upgrade. + - **Solution:** Restore from database backup created prior to manual database updates, or reinstall the system. diff --git a/doc/install/Upgrade-Guide.md b/doc/install/Upgrade-Guide.md index cecd45353..fc3a0711f 100644 --- a/doc/install/Upgrade-Guide.md +++ b/doc/install/Upgrade-Guide.md @@ -1,10 +1,23 @@ # Mattermost Upgrade Guide -### Upgrading Mattermost v0.7 to v1.1.1 +### Upgrading Mattermost in GitLab 8.0 to GitLab 8.1 with omnibus -_Note: [Mattermost v1.1.1](https://github.com/mattermost/platform/releases/tag/v1.1.1) is a special release of Mattermost v1.1 that upgrades the database to Mattermost v1.1 from EITHER Mattermost v0.7 or Mattermost v1.0. The following instructions are for upgrading from Mattermost v0.7 to v1.1.1 and skipping the upgrade to Mattermost v1.0._ +Mattermost 0.7.1-beta in GitLab 8.0 was a pre-release of Mattermost and Mattermost v1.1.1 in GitLab 8.1 was [updated significantly](https://github.com/mattermost/platform/blob/master/CHANGELOG.md#configjson-changes-from-v07-to-v10) to get to a stable, forwards-compatible platform for Mattermost. -If you've manually changed Mattermost v0.7 configuration by updating the `config.json` file, you'll need to port those changes to Mattermost v1.1.1: +The Mattermost team didn't think it made sense for GitLab omnibus to attempt an automated re-configuration of Mattermost (since 0.7.1-beta was a pre-release) given the scale of change, so we're providing instructions for GitLab users who have customized their Mattermost deployments in 8.0 to move to 8.1: + +1. Follow the [Upgrading Mattermost v0.7.1-beta to v1.1.1 instructions](https://github.com/mattermost/platform/blob/master/doc/install/Upgrade-Guide.md#upgrading-mattermost-v071-beta-to-v111) below to identify the settings in Mattermost's `config.json` file that differ from defaults and need to be updated from GitLab 8.0 to 8.1. +2. Upgrade to GitLab 8.1 using omnibus, and allowing it overwrite `config.json` to the new Mattermost v1.1.1 format +3. Manually update `config.json` to new settings identified in Step 1. + +Optionally, you can use the new [System Console user interface](https://github.com/mattermost/platform/blob/master/doc/install/Configuration-Settings.md) to make changes to your new `config.json` file. + + +### Upgrading Mattermost v0.7.1-beta to v1.1.1 + +_Note: [Mattermost v1.1.1](https://github.com/mattermost/platform/releases/tag/v1.1.1) is a special release of Mattermost v1.1 that upgrades the database to Mattermost v1.1 from EITHER Mattermost v0.7 or Mattermost v1.0. The following instructions are for upgrading from Mattermost v0.7.1-beta to v1.1.1 and skipping the upgrade to Mattermost v1.0._ + +If you've manually changed Mattermost v0.7.1-beta configuration by updating the `config.json` file, you'll need to port those changes to Mattermost v1.1.1: 1. Go to the `config.json` file that you manually updated and note any differences from the [default `config.json` file in Mattermost 0.7](https://github.com/mattermost/platform/blob/v0.7.0/config/config.json). @@ -16,3 +29,5 @@ Optionally, you can use the new [System Console user interface](https://github.c + + |