How to create a Mastodon server

Running your own Mastodon server gives you full control over your data and community moderation, providing a personalised, privacy-friendly, and ad-free experience.

What are the requirements for a Mastodon server?

You can launch a small server and expand it as needed to keep pace with your growing community. To set up a Mastodon server you need:

• VPS or another server: While you can run Mastodon on a local server, a Virtual Private Server (VPS) is more flexible and easier to manage. Ideally, the server should run Ubuntu 20.04 or Debian 11 and provide root access for necessary configurations.

• Domain or subdomain: You’ll need a domain or subdomain to identify your Mastodon server, making it easier for users to find and connect to your instance.

• Constant online availability: Your server must be online 24/7 to keep your Mastodon instance accessible to others.

• Email provider: Mastodon sends notifications and confirmation links via email, so you’ll need an email provider. While you can install your own SMTP server, third-party services like Mailgun, SparkPost, or SendGrid are often more practical.

• Object Storage Provider (optional): Using an Amazon S3-compatible object storage provider is recommended, as Mastodon stores data like images, videos, and other media on the server. This additional storage helps your instance run smoothly and provides ample space for user data.

Your server should also meet the following minimum technical requirements:

• CPU/Computing Power: min. 2 cores
• RAM/Memory: min. 2 GB
• Hard disk storage: min. 30 GB

Mastodon relies on a PostgreSQL database to store user data and other information. With a large user base, database access can become intensive. Ensure your database is well-optimised and that sufficient CPU and RAM resources are available to handle these accesses efficiently.

How to host a Mastodon server with IONOS VPS

Ready to start your own Mastodon instance but unsure which VPS package suits your needs? IONOS offers high-performance VPS packages with dedicated resources and unlimited traffic, all at affordable prices.

For a simple Mastodon server, the VPS Linux S package from IONOS is an ideal choice. It offers 80 GB of storage space and up to 1 Gbit/s bandwidth. If you require more resources, you can easily upgrade to a higher service package.

Possible Mastodon server scenarios and corresponding IONOS packages

When deciding on a suitable VPS package, you should assess the potential number of users of your Mastodon instance. Depending on the expected traffic, we recommend the following IONOS packages:

You can run your Mastodon server in parallel with other services. For a small user base, you can start with these packages:

How to create a Mastodon server step by step

Step 1: prepare server

Most hosting providers allow you to select the operating system during setup. Mastodon runs best on Ubuntu 20.04 or Debian 11, so choose one of these if available. After your VPS is set up, connect to your server via SSH. You can use a terminal (Linux/Mac) or an SSH client like PuTTY (Windows) to do this.

ssh root@your_server_ip

Replace your_server_ip with the IP address of your VPS.

To secure your system, use SSH keys and configure firewall rules with iptables leaving only the HTTP(S) and SSH ports open. Next, point the A-record of your domain or subdomain to your VPS’s IP address. For IPv6, add an additional AAAA record.

Update the package manager and the system packages:

apt update && apt upgrade -y

Step 2: install the required packages

Mastodon requires several packages and dependencies to function properly. These include Node.js, Yarn, PostgreSQL, Redis and Nginx.

Install basic packages first:

apt install -y curl wget gnupg apt-transport-https lsb-release ca-certificates

Node.js

curl -fsSL https://deb.nodesource.com/gpgkey/nodesource-repo.gpg.key | gpg --dearmor -o /etc/apt/keyrings/nodesource.gpg
echo "deb [signed-by=/etc/apt/keyrings/nodesource.gpg] https://deb.nodesource.com/node_20.x nodistro main" | tee /etc/apt/sources.list.d/nodesource.list

PostgreSQL

wget -O /usr/share/keyrings/postgresql.asc https://www.postgresql.org/media/keys/ACCC4CF8.asc
echo "deb [signed-by=/usr/share/keyrings/postgresql.asc] http://apt.postgresql.org/pub/repos/apt $(lsb_release -cs)-pgdg main" > /etc/apt/sources.list.d/postgresql.list

System packages

apt update

apt install -y imagemagick ffmpeg libpq-dev libxml2-dev libxslt1-dev file git-core g++ libprotobuf-dev protobuf-compiler pkg-config gcc autoconf bison build-essential libssl-dev libyaml-dev libreadline6-dev zlib1g-dev libncurses5-dev libffi-dev libgdbm-dev nginx nodejs redis-server redis-tools postgresql postgresql-contrib certbot python3-certbot-nginx libidn11-dev libicu-dev libjemalloc-dev

Yarn

corepack enable
yarn set version classic

Ruby

Mastodon is written in Ruby and therefore requires Ruby and Bundler. To do this, first create the user under which Mastodon is to run:

adduser --disabled-login mastodon

Now switch to the user account you created:

su - mastodon

Install rbenv and rbenv-build:

git clone https://github.com/rbenv/rbenv.git ~/.rbenv
echo 'export PATH="$HOME/.rbenv/bin:$PATH"' >> ~/.bashrc
echo 'eval "$(rbenv init -)"' >> ~/.bashrc
exec bash
git clone https://github.com/rbenv/ruby-build.git ~/.rbenv/plugins/ruby-build

Once complete, install the correct version of Ruby and the Bundler:

RUBY_CONFIGURE_OPTS=--with-jemalloc rbenv install 3.2.3
rbenv global 3.2.3
gem install bundler --no-document

Use exit to return to the root user.

Step 3: configure PostgreSQL

PostgreSQL is used by the Mastodon server to store and manage data. After installing the database server, switch to the Postgres user to access the PostgreSQL shell:

sudo -u postgres psql

Mastodon connects to the database server without a password, so the Linux system username and the database username must match. Execute the following commands in the PostgreSQL shell to create the database:

CREATE USER mastodon CREATEDB;
\q

You can enhance PostgreSQL database performance by adjusting system resources. A useful tool for this is the configuration generator pgTune. Enter details like the number of CPU cores and RAM size to get an optimised PostgreSQL configuration, which you then apply in postgresql.conf.

Step 4: install Mastodon

Next, return to the Mastodon user:

su - mastodon

Download the latest stable version of Mastodon:

git clone https://github.com/mastodon/mastodon.git live && cd live
git checkout $(git tag -l | grep '^v[0-9.]*$' | sort -V | tail -n 1)

Also install the Ruby and JavaScript dependencies:

bundle config deployment 'true'
bundle config without 'development test'
bundle install -j$(getconf _NPROCESSORS_ONLN)
yarn install --pure-lockfile

Execute the Mastodon Setup Wizard:

RAILS_ENV=production bundle exec rake mastodon:setup

You’ll now be asked about various settings, which will be saved in the .env.production file at the end.

• Domain name: Enter the domain name of the VPS server
• Do you want to enable single user mode?: N
• Are you using Docker to run Mastodon?: N
• PostgreSQL host: default - Enter
• PostgreSQL port: default - Enter
• Name of PostgreSQL database: default - Enter
• Name of PostgreSQL user: default - Enter
• Password of PostgreSQL user: leer lassen - Enter
• Redis host: default - Enter
• Redis port: default - Enter
• Redis password: default – Enter
• Do you want to store uploaded files on the cloud?: N
• Do you want to send emails from localhost?: N
• SMTP server: Specify SMTP server
• SMTP port: Specify the port of the SMTP server
• SMTP username: User name for the login
• SMTP authentication: plain
• SMTP OpenSSL verify mode: none
• Email address to send emails ‘from’: mostly like SMTP-Login
• Send a test email with this configuration right now?: Y
• Send test email to: Enter any email address as recipient
• Save configuration?: Y
• Prepare the database now?: Y
• Compile the assets now?: Y
• Do you want to create an admin user straight away?: Y
• Username: admin
• Email: your email

Switch back to the root user:

exit

Step 5: install SSL certificate

IONOS VPS servers come with an SSL certificate included by default. If your package doesn’t include one, you can install it later.

For a free SSL certificate, consider Let’s Encrypt, which provides automated certificates that are easy to install and renew.

certbot certonly --nginx -d example.com

The certificate is saved in the folder /etc/letsencrypt/live/example.com/ on your Mastodon server.

Step 6: set up Nginx

You must copy the configuration template for Nginx from the Mastodon directory and paste it into the sites-available directory of Nginx:

cp /home/mastodon/live/dist/nginx.conf /etc/nginx/sites-available/mastodon

Create a symbolic link from the configuration file in sites-enabled to enable it and remove the default configuration:

ln -s /etc/nginx/sites-available/mastodon /etc/nginx/sites-enabled/mastodon
rm /etc/nginx/sites-enabled/default

Launch the configuration file for your Mastodon server:

nano /etc/nginx/sites-available/mastodon

Enter your own domain name instead of example.com.

Uncomment the lines ssl_certificate and ssl_certificate_key and replace the paths with those to your SSL certificate. If you use the default self-signing certificate, the paths remain unchanged:

ssl_certificate     /etc/ssl/certs/ssl-cert-snakeoil.pem;
ssl_certificate_key /etc/ssl/private/ssl-cert-snakeoil.key;

Once you’ve adjusted the configuration, you must reload Nginx for the changes to take effect:

systemctl reload nginx

Step 7: set up systemd services

If you activate the Systemd services, the Mastodon web application and the real-time streaming functions are started automatically when the server is started. This ensures that your Mastodon server is permanently available.

Copy the Systemd service templates from Mastodon to the corresponding directory:

cp /home/mastodon/live/dist/mastodon-*.service /etc/systemd/system/

If you’ve changed any default values, verify that the username and paths in the service templates are correct.

$EDITOR /etc/systemd/system/mastodon-*.service

Start and activate the Systemd services:

systemctl daemon-reload
systemctl enable --now mastodon-web mastodon-sidekiq mastodon-streaming

• systemctl daemon-reload: Updates the configuration of systemd to reflect the new service templates.

• systemctl enable –now mastodon-web mastodon-sidekiq mastodon-streaming: These services are responsible for the web application, background processing and real-time streaming functions of Mastodon.

Step 8: change character limit

Running your own Mastodon server gives you the flexibility to adjust settings not available on public servers. For instance, you can modify the character limit for posts, which is set to 500 characters by default but can be increased or decreased.

First, switch to the Mastodon user in the console. Then, edit two specific files.

Enter your desired value for the character limit in the following files:

• compose_form.js in directory ~/live/app/javascript/mastodon/features/compose/components/
• status_length_validator.rb in ~/live/app/validators/

In the file instance_serializer.rb in the directory ~/live/app/serializers/rest/, find the line containing :languages, :registrations, and add :max_toot_chars, after it.

In addition, add the following code under the line beginning with private, inserting the desired value:

def max_toot_chars
    1000
end

After you have made these changes, the Mastodon services must be restarted. This is done as the root user with the command:

service mastodon-* restart

Now you can write posts with a character limit of 1000 characters.

Step 9: moderation function

The moderation function under ‘Settings > Moderation’ on your Mastodon server lets you, as an admin, monitor and manage content and user activity to ensure compliance with the Community Guidelines and remove unwanted content.

You can block, unblock, or delete individual accounts, domains, IP addresses, or email servers. Additionally, you can moderate user content by removing or editing inappropriate or offensive posts.