Product docs and API reference are now on Akamai TechDocs.
Search product docs.
Search for “” in product docs.
Search API reference.
Search for “” in API reference.
Search Results
 results matching 
 results
No Results
Filters
Install a Mastodon Server on Ubuntu 20.04
- Debian 10
- CentOS Stream 8
- Deprecated guides:
- Ubuntu 16.04
Traducciones al EspañolEstamos traduciendo nuestros guías y tutoriales al Español. Es posible que usted esté viendo una traducción generada automáticamente. Estamos trabajando con traductores profesionales para verificar las traducciones de nuestro sitio web. Este proyecto es un trabajo en curso.
Mastodon is an open-source and decentralized micro-blogging platform. Like Twitter, it lets users follow other users and post text, photos, and video content. Mastodon also allows you to create a non-profit social network based on open web standards and principles. Unlike Twitter, Mastodon is decentralized, meaning that its content is not maintained by a central authority.
What sets the Mastodon platform apart is its federated approach to social networking. Each Mastodon instance operates independently — anyone can create an instance and build their community. But users from different instances can still follow each other, share content, and communicate.
Mastodon participates in the Fediverse , a collection of social networks and other websites that communicate using the ActivityPub protocol. It allows different Mastodon instances to communicate and also allows other platforms in the Fediverse to communicate with Mastodon.
Mastodon servers range in size from small private instances to massive public instances and typically center on specific interests or shared principles. The biggest Mastodon server is Mastodon.social , a general-interest server created by the developers of the Mastodon platform. It has over 540,000 users and boasts a thorough Code of Conduct .
Before You Begin
If you have not already done so, create a Linode account and Compute Instance. See our Getting Started with Linode and Creating a Compute Instance guides.
Follow our Setting Up and Securing a Compute Instance guide to update your system. You may also wish to set the timezone, configure your hostname, create a limited user account, and harden SSH access.
Complete the steps in the Add DNS Records section to register a domain name to point to your Mastodon instance.
Prepare an SMTP server for Mastodon to send email notifications to users when they register for the site, get a follower, receive a message, and for other Mastodon activity.
You can create your SMTP server — and even host it on the same machine as your Mastodon server — by following the Configure an Email Server with Postfix, Dovecot, and MySQL on Debian, and Ubuntu guide.
Note This guide uses the PostgreSQL database as a backend for Mastodon. You can set up the SMTP server with the PostgreSQL database instead of MySQL.Alternatively, you can use a third-party SMTP service. This guide provides instructions for using Mailgun as your SMTP provider.
Replace occurrences of
example.com
in this guide with the domain name you are using for your Mastodon instance.
sudo
. If you’re not familiar with the sudo
command, see the Linux Users and Groups
guide.Install Docker and Docker Compose
Mastodon can be installed using its included Docker Compose file. Docker Compose installs and runs all of the requisites for the Mastodon environment in Docker containers. If you have not used Docker before, it is recommended that you review the following guides:
Install Docker
To install Docker CE (Community Edition), follow the instructions within one of the guides below:
To see installation instructions for other Linux distributions or operating systems like Mac or Windows, reference Docker’s official documentation here: Install Docker Engine
Install Docker Compose
Docker Compose is available in plugin and standalone variants. However, Docker’s official documentation prioritizes the plugin. Further, the plugin has a straightforward installation and works well with past Docker Compose commands.
These steps thus show how to install the Docker Compose plugin. If you are interested in installing the standalone Docker Compose application, follow Docker’s official installation guide .
Many tutorials retain the Docker Compose standalone command format, which looks like the following:
docker-compose [command]
Be sure to replace this with the plugin’s command format when using this installation method. This typically just means replacing the hyphen with a space, as in:
docker compose [command]
Enable the Docker repository for your system’s package manager. The repository is typically already enabled after you have installed the Docker engine. Follow our relevant guide on installing Docker to enable the repository on your system.
Update your package manager, and install the Docker Compose plugin.
- On Debian and Ubuntu systems, use the following commands:
sudo apt update sudo apt install docker-compose-plugin
- On CentOS, Fedora, and other RPM-based distributions, use the following commands:
sudo yum update sudo yum install docker-compose-plugin
Download Mastodon
Clone the Mastodon Git repository into the home directory. Then, change into the resulting Mastodon directory and grab the latest Mastodon release.
cd ~/ git clone https://github.com/tootsuite/mastodon.git cd mastodon git checkout $(git tag -l | grep -v 'rc[0-9]*$' | sort -V | tail -n 1)
Note Unless otherwise stated, all the Docker Compose–related commands are to be run in this directory.
Configure Docker Compose
Using your preferred text editor, open the
docker-compose.yml
file located in themastodon
directory.Comment out the
build
lines (adding#
in front of each), and append a release number to the end of eachimage: tootsuite/mastodon
line like:tootsuite/mastodon:v4.0.2
.Although you can use
latest
as the release, it is recommended that you select a specific release number. The Mastodon GitHub page provides a chronological list of Mastodon releases .The resulting
docker-compose.yml
file should resemble the example Docker file .Copy the
.env.production.sample
file (which is in the currentmastodon
directory) to create a new environment configuration file.cp .env.production.sample .env.production
Use Docker and Mastodon to generate a new value for the
SECRET_KEY_BASE
setting.SECRET_KEY_BASE=$(docker compose run --rm web bundle exec rake secret)
This creates a string of random characters. If you encounter an error in the next step, run the command again to generate another string.
Insert the
SECRET_KEY_BASE
setting into.env.production
using thesed
command.sed -i -e "s/SECRET_KEY_BASE=/&${SECRET_KEY_BASE}/" .env.production
Combine the previous two actions into one step to set a value for the
OTP_SECRET
setting in.env.production
.sed -i "s/OTP_SECRET=$/&$(docker compose run --rm web bundle exec rake secret)/" .env.production
Generate values for
VAPID_PRIVATE_KEY
andVAPID_PUBLIC_KEY
settings.docker compose run --rm web bundle exec rake mastodon:webpush:generate_vapid_key
Copy the output from the previous command, open
.env.production
in your text editor, and paste the command output into the two lines forVAPID_PRIVATE_KEY
andVAPID_PUBLIC_KEY
.Fill out the remaining fields of the
.env.production
file:LOCAL_DOMAIN
: Enter your Mastodon server’s domain nameDB_USER
: Change this topostgres
, and leave theDB_PASS
field emptyEnter
mastodon-db-1
forDB_HOST
andmastodon-redis-1
forREDIS_HOST
. In both of these values,mastodon
corresponds to the name of the Mastodon base folderFill out the
SMTP
fields with the information from your SMTP provider. If you set up your SMTP server, use its domain name forSMTP_SERVER
and add the following lines:- File: .env.production
1 2
SMTP_AUTH_METHOD=plain SMTP_OPENSSL_VERIFY_MODE=none
Comment out the sections denoted as “optional” by adding a
#
before each line in the section.The resulting
.env.production
file should resemble the example environment file .
Complete the Docker Compose Setup
Build the Docker Compose environment using the following command:
docker compose build
Give ownership of the Mastodon
public
directory to user991
. This is the default user ID for Mastodon, and this command ensures that it has the necessary permissions.sudo chown -R 991:991 public
Run Mastodon’s Docker Compose setup script. You are prompted to enter information about the Docker Compose services and the Mastodon instance.
docker compose run --rm web bundle exec rake mastodon:setup
Many prompts repeat fields you completed in the
.env.production
file. Make sure to enter the same information here as you entered in the file.When prompted to create a Mastodon administrator user account, choose to do so (
Y
). Enter the username, password, and email address you would like to use to access the account.For any other prompts, enter the default values by pressing Enter.
Initiate the Docker Compose Services
Start the Docker Compose services.
docker compose up -d
Unless manually stopped, the Docker Compose services begin running automatically at system startup. Run the following command to manually stop the Docker Compose services.
docker compose down
Setup an HTTP/HTTPS Proxy
Allow HTTP and HTTPS connection on the system’s firewall.
sudo ufw allow http sudo ufw allow https sudo ufw reload
Install NGINX, which proxies requests to your Mastodon server.
sudo apt install nginx
Copy the
nginx.conf
file included with the Mastodon installation to thesites-available
NGINX folder; use your Mastodon domain name instead ofexample.com
in the file name.sudo cp ~/mastodon/dist/nginx.conf /etc/nginx/sites-available/example.com.conf
Open the
example.com.conf
file with your preferred text editor, and replace all instances ofexample.com
with the domain name for your Mastodon site. This domain name must match the one you used to set up Docker Compose for Mastodon.Create a symbolic link of this file in the
sites-enabled
NGINX folder.cd /etc/nginx/sites-enabled sudo ln -s ../sites-available/example.com.conf
Get an SSL/TLS Certificate
Mastodon is served over HTTPS, so you need an SSL/TLS certificate. This guide uses Certbot to request and downloads a free certificate from Let’s Encrypt .
Update the Snap app store. Snap provides application bundles that work across major Linux distributions and comes by default with all Ubuntu releases since 16.04.
sudo snap install core && sudo snap refresh core
Ensure that any existing Certbot installation is removed.
sudo apt remove certbot
Install Certbot.
sudo snap install --classic certbot
Download a certificate for your site.
sudo certbot certonly --nginx
Certbot prompts you to select from the NGINX sites configured on your machine. Select the one with the domain name you set up for your Mastodon instance.
Certbot includes a chron job that automatically renews your certificate before it expires. You can test the automatic renewal with the following command:
sudo certbot renew --dry-run
Open the
/etc/nginx/sites-available/example.com.conf
file again, and un-comment thessl_certificate
andssl_certificate_key
lines.Restart the NGINX server.
sudo systemctl restart nginx
Using Mastodon
In a web browser, navigate to your Mastodon site’s domain. You should see the Mastodon login page, where you can log in as the admin user you created earlier or create a new user.
You can navigate to your instance’s administration page by navigating to
example.com/admin/settings/edit
. The administration page allows you to alter the look, feel, and behavior of your instance.If your instance is running but having issues, you can troubleshoot them from the Sidekiq dashboard. Either select Sidekiq from the administration menu or navigate to
example.com/sidekiq
to see the dashboard.
To learn more about Mastodon, check out the official Mastodon blog with news and articles related to Mastodon. You can engage with the Mastodon administrative community on Mastodon’s discussion forum , where you can peruse conversations about technical issues and community governance.
When you are ready to make your instance known to the world, you can add it to the list over at Instances.social by filling out the admin form.
More Information
You may wish to consult the following resources for additional information on this topic. While these are provided in the hope that they will be useful, please note that we cannot vouch for the accuracy or timeliness of externally hosted materials.
This page was originally published on