How to Install Mattermost on Heroku: A Comprehensive Guide for Seamless Deployment

What is Mattermost?

Mattermost is an open-source messaging platform, providing real-time team communication and collaboration features similar to Slack. While Mattermost is traditionally deployed on dedicated servers, it is possible to deploy it on Heroku, a cloud platform that supports multiple programming languages and frameworks. Deploying Mattermost on Heroku requires a few specific steps, including handling file storage, database setup, and build configuration.

What is Heroku?

Heroku is a cloud platform that enables developers to build, deploy, and manage applications without worrying about the underlying infrastructure. It is a Platform-as-a-Service (PaaS), meaning it abstracts away the complexity of managing servers, networks, storage, and other infrastructure tasks, allowing developers to focus purely on writing code.

Heroku is designed to make the process of deploying applications simple and efficient. It supports several programming languages and frameworks, including Node.js, Python, Ruby, Java, PHP, Go, and more.

This guide will walk you through the entire process of installing and configuring Mattermost on Heroku.

Prerequisites:

Before we begin, make sure you have the following:

• A Heroku account (Sign up here).

• Heroku CLI installed on your local machine (Installation guide).

• Git installed on your local machine (Installation guide).

• Basic understanding of Heroku's platform and command-line tools.

Step 1: Create a New Heroku App

First, log in to Heroku using the CLI. Open a terminal and execute the following command:

heroku login

You will be prompted to enter your credentials. After that, create a new Heroku app by running:

heroku create your-app-name

Replace your-app-name with the name you want for your Heroku application.

Step 2: Add PostgreSQL Database

Mattermost requires a database to function, and we'll use Heroku Postgres. Add the PostgreSQL add-on to your Heroku app with the following command:

heroku addons:create heroku-postgresql:hobby-dev --app your-app-name

This will add a free hobby-dev PostgreSQL instance to your app.

If you're unable to add the free hobby-dev PostgreSQL instance to your Heroku app (due to availability, plan changes, or other issues), you can try the following alternatives:

Check for Available PostgreSQL Plans

Heroku's free-tier services sometimes change, or specific regions might not support certain plans. To see which PostgreSQL plans are available for your account, run the following command:

heroku addons:plans heroku-postgresql

This will list all available PostgreSQL plans. If the hobby-dev plan is not available, look for an alternative (e.g., standard-0, basic, etc.) and use that instead.

Example:

heroku addons:create heroku-postgresql:standard-0 --app your-app-name

Replace standard-0 with the plan that’s available to you.

Step 3: Set Up External File Storage

Since Heroku does not support persistent file storage, you'll need to use an external service like Amazon S3 for storing files (e.g., images, documents). Follow these steps to configure S3 for Mattermost:

1. Create an S3 Bucket: Sign in to your AWS account, navigate to the S3 service, and create a new bucket.

2. Configure Environment Variables: Add the necessary S3 credentials to your Heroku environment:

   heroku config:set MM_FILESETTINGS_DRIVERNAME=amazons3 heroku config:set MM_FILESETTINGS_AMAZONS3_BUCKET=your-s3-bucket-name 
   heroku config:set MM_FILESETTINGS_AMAZONS3_ACCESSKEYID=your-access-key heroku config:set MM_FILESETTINGS_AMAZONS3_SECRETACCESSKEY=your-secret-key

Replace your-s3-bucket-name, your-access-key, and your-secret-key with your actual AWS S3 credentials.

Step 4: Clone the Mattermost Repository

Clone the Mattermost server source code to your local machine using Git:

git clone https://github.com/mattermost/mattermost-server.git cd mattermost-server

Step 5: Add a Procfile

Heroku uses a Procfile to determine how to run your application. Create a Procfile in the root of your Mattermost repository and add the following line:

web: ./bin/mattermost

This tells Heroku to start Mattermost using the ./bin/mattermost command.

Step 6: Set Up Buildpacks for Go and Node.js

Mattermost is a Go application, and it also has a Node.js frontend. To ensure that both the backend and frontend build properly, you'll need to configure Heroku to use both Go and Node.js buildpacks.

First, clear any existing buildpacks:

heroku buildpacks:clear --app your-app-name

Then, add the Go and Node.js buildpacks:

heroku buildpacks:add heroku/go --app your-app-name heroku buildpacks:add heroku/nodejs --app your-app-name

This ensures that both Go and Node.js dependencies are handled during the build process.

Step 7: Configure Environment Variables

Mattermost requires a number of environment variables to connect to the database and external services. Set the necessary configuration variables for your PostgreSQL database:

heroku config:set MM_SQLSETTINGS_DRIVERNAME=postgres --app your-app-name 
heroku config:set MM_SQLSETTINGS_DATASOURCE=$(heroku config:get DATABASE_URL) --app your-app-name

The second command uses the DATABASE_URL environment variable, which is automatically set when the PostgreSQL add-on was created earlier.

Step 8: Push Code to Heroku

Now, push the Mattermost code to Heroku to deploy it. If you're working from the master branch, simply run:

git push heroku master

If you're working on a different branch, specify it like this:

git push heroku your-branch-name:main

This command will trigger the build and deployment process on Heroku.

Step 9: Run Database Migrations

After deploying, you’ll need to run the initial database migrations for Mattermost. This can be done via the Heroku CLI:

heroku run ./bin/mattermost db migrate --app your-app-name

This ensures that your database is properly initialized with the necessary tables and data for Mattermost to function.

Step 10: Access Your Mattermost Application

Once the deployment is complete, you can access your Mattermost instance by visiting the Heroku URL provided for your app:

https://your-app-name.herokuapp.com/

This will open the Mattermost login page, and you can start using the platform.

Optional: Set Up a Custom Domain

If you'd like to use a custom domain for your Mattermost instance, you can configure this via the Heroku dashboard or CLI. Add your custom domain like this:

heroku domains:add www.yourdomain.com --app your-app-name

Then, configure your DNS to point to the Heroku app’s DNS target.

Step 11: Monitor and Scale Your Application

You can monitor the performance and logs of your Heroku app using the Heroku dashboard or CLI. View your app's logs with:

heroku logs --tail --app your-app-name

If needed, you can scale your app to handle more traffic by adding more dynos:

heroku ps:scale web=1 --app your-app-name

For higher traffic, you may want to scale up the number of dynos or consider upgrading to paid Heroku plans for better performance.

Conclusion

Deploying Mattermost on Heroku involves several steps, including setting up external file storage, configuring the database, and using multi-buildpacks for Go and Node.js. While the setup is more complex than a typical web app, following this guide ensures that Mattermost will run smoothly on the Heroku platform.

With Mattermost successfully deployed, you can now enjoy a fully open-source messaging platform for your team collaboration needs. Don't forget to keep an eye on logs and performance to ensure smooth operation, and scale up when necessary!