This is a guide on upgrading and/or migrating Mattermost 5.6 (from 4.x) in a deploy that used docker-compose.

It's been a year, and I want to freshen up my Mattermost install, get some of the new features. I also want a bit more elbow-room in my Mattermost installation. My installation (~20 active users at any given time) was running absolutely fine at Digital Ocean's cheapest ($5 a month) plan, but I also wanted to to future-proof my installation a little bit, so I'm upgrading to their $15 a month plan.

Interested in installing Mattermost quickly using Digital Ocean and their provided Docker images? Read my tutorial here, which has been tested with versions 4.2.3 and 5.6.

Tutorial

This is a followup from my previous blog post, and assumes you launched Mattermost using their provided Docker images. This also assumes you have made no major changes to Mattermost, such as installing plug-ins. If you did install plug-ins, you probably want to temporarily disable them while you do the upgrade.

1. Back everything up, and alert your users.

To be extra careful, I made back-ups at two levels:

1. The droplet / image level (within Digital Ocean this can be done by either creating a snapshot, or enabling regular backups)

2. Simply by copying the volumes. If you are using their docker-compose file of Mattermost, then anything important should be in the volumes directory. I just did a cp -r of this to a new location on the same machine. This took less than a thirty seconds for 1.8 GB on a DO droplet.

cd mattermost-docker  
docker-compose down # shut down  
cp -r volumes ../volumes-backup  

This is just common admin sense, but if there are active users, you'll want to ensure they don't try to access the site while the site is down, or for example add a post after. I also added a temporary re-direct with CloudFlare to a "Schedule maintenance post" on a separate server.

2. Checkout the newest version

In this case, I had originally installed 4.2.3, and I wanted to upgrade directly to 5.6.2. This was simply a matter of doing a git checkout of the necessary tag.

cd mattermost-docker  
git pull  
git checkout 5.6.2  

3. Re-build

This and all subsequent commands assumes you are in the mattermost-docker location:

docker-compose down  
docker-compose build  

4. Upgrading from 4.x: Change permissions

If you decided to use an older version (e.g. 4.x) you are done. Otherwise, you may have to run the following command to create relevant volume directories, and change permissions:

mkdir -pv ./volumes/app/mattermost/{data,logs,config,plugins}  
chown -R 2000:2000 ./volumes/app/mattermost/  

5. Upgrading from 4.x: Change port number

The config.json had some essential changes since the 4.x versions. This means that the port number must be changed from 80 to 8000.

1. You can open up the config.json file using nano as such: nano ./volumes/app/mattermost/config/config.json

2. Change the property that looks like "ListenAddress": ":8000", to "ListenAddress": ":80",

NOTE: You do NOT need to change the "WebsocketPort": 80, -- this should be left at 80 otherwise it won't work.

6. Start server again

docker-compose up -d  

For me, everything just worked at this point, with the latest version of Mattermost happily humming along.

7. (Optional) Resize and/or migrate

At this point, you can safely shutdown the droplet, then move or resize the droplet safely from Digital Ocean's interface.

If you are not using Digital Ocean, to migrate to a new machine should be as simple as copying over the volumes directory -- although I have not actually tested this.

All-in-all, an extremely painless process. Let me know in the comments if it works for your, or it required any other changes.