This guide is for Server Admins only, for user guides please see this site

Mastodon Super-Tutorial!

This will be a VERY simple, easy to use tutorial. This will not cover customizing, however it does cover:

Installing Mastodon
Maintainence of Mastodon
Upgrades
SSL Certificates(Let's Encrypt)
Nginx configurations
Troubleshooting basic issues with Mastodon & Nginx services

This tutorial expects that you are running on Ubuntu 15.04+. However - This can be done with virtually any linux distrobution that can use Docker application. We also expect that your VPS/Dedicated machine has an external IP Address, that is properly routed and a domain name to go with it! (You need it for SSL cert!!)

Tutorial Menu

Mastodon Official Documentation (Should see first)
Warnings & Common Sense
Requirements
Installing Docker
Installing docker-compose
Download Mastodon
Building Mastodon & Installing Mastodon Dependencies
Install & proxy through nginx
Setup cron jobs for Mastodon cleaning
Maintainence & Troubleshooting of Mastodon
Maintainence & Troubleshooting of Nginx

Warnings & Common Sense

As with any tutorial where the user requires root permissions, you need to be aware of the following things:

Although tested, some commands, when ran as root(sudo), can break the system. It is unlikely - but I have to put in a warning for legal reasons here.
You are doing this of your own free will, you are aware that any commands here might break stuff, and you are doing this at your own risk!
Once the service is online - You cannot blame me or Mastodon's developers if a hacker DDoS's, gets into, or otherwise with your server.
Security is best practiced with you! This means keep strong passwords! Changing them every couple weeks to months. Never settle for weak security!
I have to say it because of certain services floating around the internet: Keep an eye on your server. Not my fault if someone uploads illegal stuff on it. (Really - Moderate it!)
FIREWALL!!! Using ufw or iptables on linux will keep the bad guys at bay (at least most of them, it is very unlikely they will care enough to get into your server.)

Requirements

A server (VPS, Dedicated, etc) running Ubuntu 16.04+ (Or Debian 8+)
Depending on the amount of users you expect, at least 4GB RAM or more. (Single user instances can be around 2GB)
I would recommend at least a 100mbit unmetered connection with the service provider (But not necessary.)
100GB HDD+ is pretty decent. But the more the better to be honest.
An SMTP host for registering of user accounts. (Your own, mailchimp, etc should work)
A basic understanding of linux is most likely needed for proper maintainence of Mastodon.(Like using cURL, nano, etc.)

Installing Docker & docker-compose

Installing Docker

You can run the following in order. If an explination is needed on something it will be under the command.

sudo apt-get -y --no-install-recommends install curl apt-transport-https ca-certificates curl software-properties-common

The above command is used to get some dependencies and enable apt-get to use HTTPS connections.

curl -fsSL https://apt.dockerproject.org/gpg | sudo apt-key add -

The above command downloads the GPG key of the Docker repository, this will be needed to download docker in later steps.

sudo add-apt-repository "deb https://apt.dockerproject.org/repo/ ubuntu-$(lsb_release -cs) main"

The above command adds the docker repo for your version of ubuntu (Should at least be 16.04 LTS!!)

sudo apt-get update
sudo apt-get -y install docker-engine

The above 2 commands update the repos, and then installs Docker.

Then make sure the docker service is started: sudo systemctl restart docker.service

Installing docker-compose

You can run the following in order. If an explination is needed on something it will be under the command.

sudo curl -L "https://github.com/docker/compose/releases/download/1.10.0/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose

The above command will grab the version specified by ../download/x.xx.x/docker-compose..... Make sure to use the latest command from https://github.com/docker/compose/releases !!!

sudo chmod +x /usr/local/bin/docker-compose

The above command makes docker-compose executable by any user. (Not a security risk in this case. If you would like to know more about linux permissions please see: https://ss64.com/bash/chmod.html)

Getting the latest Mastodon code from github

Now that we have docker installed, we need to get the latest and greatest code from it's github (https://github.com/tootsuite/mastodon/)

So before we continue we need to do the following:

sudo adduser mastodon && sudo adduser mastodon sudo && sudo adduser mastodon docker

The above command adds a new user to the system. "mastodon" will be the user we run the install/configure commands as.

After filling out the mastodon user password do: sudo su - mastodon to switch to that user. and cd ~ to change into that users "home" directory
git clone https://github.com/tootsuite/mastodon/

The above command downloads the latest mastodon code and puts it in the folder "mastodon" by default. to change it add a -O /path/to/folder/ you would like.

cd mastodon/

The above command will put us in the newly download mastodon source code folder.

Building Mastodon

Since we are using docker for this, building mastodon is actually pretty straight forward.

Mastodon install

Make sure you are in the mastodon source folder. (For this tutorial it might be /home/mastodon/mastodon)
Then cp .env.production.sample .env.production

The above copies a configuration file that will not be overwritten by updates later.

Modify the configuration file using your favorite text editor to meet your needs.
For the application secrets, run the following command 3 times:
docker-compose run --rm web rake secret <- MUST HAVE. See notes in .env.production file. Example config file

The above command will take time to run the first time, then it will be MUCH faster the second and third time. Also make sure that the 3 secrets in the .env.production file are different. (See that file for details.)

Once the configuration is done and dusted run: docker-compose build to build mastodon.
docker-compose up -d

The above command starts the mastodon server. But we are not done yet!!!

docker-compose run --rm web rails db:migrate

Need to upgrade the mastodon database.

docker-compose run --rm web rails assets:precompile

Precompile the asset cache for SPEED.

docker-compose build

Needed again after the precompile command always.

Installing nginx to proxy to mastodon.

nginx is not required here, you COULD use apache - however I have had better performance using nginx.

sudo apt-get install nginx
Move all the files under /etc/nginx/sites-enabled/ to a different folder. We don't need them.
sudo mv /etc/nginx/sites-enabled/* ~/
Now we need to edit a new file that doesn't exist yet: nano /etc/nginx/sites-enabled/mastodon

The above command will create and open a new file in nano.

Download the following file and put it's contents inside the above file. Mastodon nginx configuration

If the above file is not available, you can find the nginx configuration at Masto's github

Put the following in "/etc/nginx/sites-enabled/mastodon-http" making sure to change example.com. This config will redirect all traffic to port 443 on your server. (SSL)

server {
    listen      80;
    server_name example.com;
    rewrite     ^   https://$server_name$request_uri? permanent;
}

Now we need Let's encrypt:
1. sudo apt-get install letsencrypt
2. sudo systemctl stop nginx.service
3. letsencrypt certonly --standalone -d example.com Where example.com is the domain for your masto-instance!!
4. If you need help with this please visit Certbot
Edit /etc/nginx/sites-enabled/mastodon and change the following lines to match your domain name:
- ssl_certificate /etc/letsencrypt/live/example.com/fullchain.pem;
- ssl_certificate_key /etc/letsencrypt/live/example.com/privkey.pem;
Once that is done cd ~ to change back to your home directory.
sudo -i to login as root of your VPS/Server.
Make a new file called update_mastodon, this file will be used to run updates on the Mastodon serivce. (See Maintaing Mastodon for details on how to use.)
Inside that file put the following (Or download):

#!/bin/bash
cd /home/mastodon/mastodon
echo -e "Checking for update.."
git remote update
UPSTREAM=${1:-'@{u}'}
LOCAL=$(git rev-parse @)
REMOTE=$(git rev-parse "$UPSTREAM")
BASE=$(git merge-base @ "$UPSTREAM")
if [ $LOCAL = $REMOTE ]; then
    echo "Up-to-date. No need to continue."
    exit 0
elif [ $LOCAL = $BASE ]; then
    echo "Need to pull"
    echo "Pulling in  10 seconds. CTRL+C to cancel.."
    sleep 10
    docker-compose stop
    git pull
    docker-compose build
    docker-compose run --rm web rails db:migrate
    docker-compose run --rm web rails assets:precompile
    docker-compose build
    docker-compose up -d
	systemctl restart nginx.service
elif [ $REMOTE = $BASE ]; then
    echo "Need to push - nothing to do."
    exit 0
else
    echo "Diverged. Oops."
    exit 0
fi
exit 0

The above file is a script to update mastodon for you. Please keep it handy!

chmod +x update_mastodon

The above command makes the update script executable.

Now run the update script to clean and start mastodon: bash update_mastodon
When that completes all you need to do to start mastodon:
1. sudo su - mastodon
2. cd mastodon/
3. docker-compose stop && docker-compose up -d
The above makes sure mastodon is completely clean before starting again.
1. If needed: systemctl restart nginx.server (As root!!)
Register as a user on your instance RIGHT NOW!!!!! Because you will want to be the admin!

Setting up the cron jobs:

Cron is very important as it keeps your mastodon instance nice and clean.

sudo su - mastodon
nano masto_cron and put the following in there:

cd /home/mastodon/mastodon
# Run jobs:
docker-compose run --rm web rake mastodon:media:clear
docker-compose run --rm web rake mastodon:push:refresh
docker-compose run --rm web rake mastodon:push:clear
docker-compose run --rm web rake mastodon:feeds:clear

Save that file and: sudo chmod +x masto_cron && sudo crontab -e add the following to the end of the file:(Make sure to edit the paths as needed!!!!)

    
0 22 * * * /home/mastodon/masto_cron > /home/mastodon/masto_log

Maintaining & Troubleshooting Mastodon once installed

Starting Mastodon after a reboot, or for whatever reason:

sudo su - mastodon
cd mastodon/
docker-compose up -d
exit
sudo systemctl restart nginx.service

Stopping the Mastodon server:

sudo su - mastodon
cd mastodon/
docker-compose stop
exit

Restarting the Mastodon server

sudo su - mastodon
cd mastodon/
docker-compose stop
docker-compose up -d

The above commands restart the docker container for you. This should really only be done to troubleshoot errors.

Updating:

Updating is pretty simple, just run that update_mastodon script as root you made and it does all of the work for you!

To make an account an admin:

sudo su - mastodon
cd mastodon/
docker-compose run --rm web rails mastodon:make_admin USERNAME=example
Then logout and log back in.

Refresh a users avatar

sudo su - mastodon
cd mastodon/
docker-compose run --rm web rails c
Once the rails terminal opens: (You might need to type in manually, or run line by line as copy-paste of the following code might not work properly)

a =Account.find_remote('-username-', '-domain-')
a.avatar = URI.parse(a.avatar_remote_url)
a.save

Rebuild remote user avatar cache

sudo su - mastodon
cd mastodon/
docker-compose run --rm web rails c
Once the rails terminal opens: (You might need to type in manually, or run line by line as copy-paste of the following code might not work properly)

Account.remote.find_each do |a|
a.avatar = URI.parse(a.avatar_remote_url)
a.save
end

Rebuild all timelines (For troubleshooting only!!!)

This will force all user timeline streams to be nulled - They are rebuilt completely on next user interaction/login.

sudo su - mastodon
cd mastodon/
docker-compose run --rm web rake mastodon:feeds:clear_all

Reset git back to origin/master

sudo -i
cd /home/mastodon/mastodon
git fetch --all
git reset --hard origin/master
git pull origin master
git checkout master
git status To confirm it should output something like: "On branch master Your branch is up-to-date with 'origin/master'. nothing to commit, working directory clean

I am not getting emails from Mastodon

This is a weird issue to have because it could be one of two things:

Your email provider does not allow 3rd party applications to send email
You configured Mastodon with bad SMTP information in .env.production file.

If you put wrong information in the config file (Always double check, it is usually the port number and password that was typed wrong) just fix the information and restart mastodon and nginx.

If you are using a known bad email provider (See list below) then find a new email provider for your instance.

The following email service providers are known to have issues:

Google's gmail services (Both the free and GSuite versions)
Microsoft's Office 365 services (Both the corporate, and personal accounts)
Hotmail
Yahoo (Assumed for now, not actually tested)

To resolve this issue, running your own email is usually the way to go. If you are new to doing this, I would recommend Mail-In-A-Box however - this tutorial does not cover setting up the email server because it is out of the scope of this document. (Mail-In-A-Box has AMAZING Documentation, community, and howto for that!)

If setting up another server is not in your interests, https://mailgun.com might be for you. 10,000 free emails a month, and pretty fast as well.

## Maintaining & Troubleshooting Nginx once installed _The website is throwing a weird error message and telling me that something went wrong! Help!_

OK First things first: Don't panic. This might actually be normal behavior. Read the following guidelines about nginx and mastodon working together.

If you just restarted mastodon's docker container:

Then this is normal - When nginx see the mastodon port close after it is done setting up its internal proxy it will freak out. To fix this, just restart nginx:

sudo systemctl restart nginx.service

Then refresh the website.

Make sure Mastodon is actually up and online

You will also want to make sure Mastodon's docker container is online and active. Restarting it should do the trick:

sudo su - mastodon
cd mastodon/
docker-compose stop
docker-compose up -d

The above commands restart the docker container for you. This should really only be done to troubleshoot errors.

Websites SSL Certificate is invalid!

This is a normal error to see every few months - I am working on putting together another part of this tutorial specifically for this. To fix the error in the mean time just follow steps 7 & 8 under Installing Nginx

Need help with your instance?

You can contact me on GitHub, Facebook, Messenger, email, or XMPP.

Or you can contact me @ https://gnusocial.me/about/more

Or contact the creator of mastodon himself: https://mastodon.social/about/more

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

mastodon_install.md

mastodon_install.md

This guide is for Server Admins only, for user guides please see this site

Mastodon Super-Tutorial!

Tutorial Menu

Warnings & Common Sense

Requirements

Installing Docker & docker-compose

Installing Docker

Installing docker-compose

Getting the latest Mastodon code from github

Building Mastodon

Mastodon install

Installing nginx to proxy to mastodon.

Setting up the cron jobs:

Maintaining & Troubleshooting Mastodon once installed

Starting Mastodon after a reboot, or for whatever reason:

Stopping the Mastodon server:

Restarting the Mastodon server

Updating:

To make an account an admin:

Refresh a users avatar

Rebuild remote user avatar cache

Rebuild all timelines (For troubleshooting only!!!)

Reset git back to origin/master

I am not getting emails from Mastodon

If you just restarted mastodon's docker container:

Make sure Mastodon is actually up and online

Websites SSL Certificate is invalid!

Need help with your instance?

Files

mastodon_install.md

Latest commit

History

mastodon_install.md

File metadata and controls

This guide is for Server Admins only, for user guides please see this site

Mastodon Super-Tutorial!

Tutorial Menu

Warnings & Common Sense

Requirements

Installing Docker & docker-compose

Installing Docker

Installing docker-compose

Getting the latest Mastodon code from github

Building Mastodon

Mastodon install

Installing nginx to proxy to mastodon.

Setting up the cron jobs:

Maintaining & Troubleshooting Mastodon once installed

Starting Mastodon after a reboot, or for whatever reason:

Stopping the Mastodon server:

Restarting the Mastodon server

Updating:

To make an account an admin:

Refresh a users avatar

Rebuild remote user avatar cache

Rebuild all timelines (For troubleshooting only!!!)

Reset git back to origin/master

I am not getting emails from Mastodon

If you just restarted mastodon's docker container:

Make sure Mastodon is actually up and online

Websites SSL Certificate is invalid!

Need help with your instance?