How to create a Mastodon server

Running your own Mastodon server gives you full control over your data and community mod­er­a­tion, providing a per­son­al­ized, privacy-friendly, and ad-free ex­pe­ri­ence.

What are the re­quire­ments 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 con­fig­u­ra­tions.

• 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 avail­abil­i­ty: Your server must be online 24/7 to keep your Mastodon instance ac­ces­si­ble to others.

• Email provider: Mastodon sends no­ti­fi­ca­tions and con­fir­ma­tion 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-com­pat­i­ble object storage provider is rec­om­mend­ed, as Mastodon stores data like images, videos, and other media on the server. This ad­di­tion­al storage helps your instance run smoothly and provides ample space for user data.

Your server should also meet the following minimum technical re­quire­ments:

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

Mastodon relies on a Post­greSQL database to store user data and other in­for­ma­tion. With a large user base, database access can become intensive. Ensure your database is well-optimized and that suf­fi­cient CPU and RAM resources are available to handle these accesses ef­fi­cient­ly.

How to host a Mastodon server with IONOS VPS

Ready to start your own Mastodon instance but unsure which VPS plan suits your needs? IONOS offers high-per­for­mance VPS plans with dedicated resources and unlimited traffic, all at af­ford­able prices.

For a simple Mastodon server, the VPS Linux S plan 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 plan.

Possible Mastodon server scenarios and cor­re­spond­ing IONOS plans

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

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

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 ad­di­tion­al 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 de­pen­den­cies to function properly. These include Node.js, Yarn, Post­greSQL, 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

Post­greSQL

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 Post­greSQL

Post­greSQL is used by the Mastodon server to store and manage data. After in­stalling the database server, switch to the Postgres user to access the Post­greSQL 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 Post­greSQL shell to create the database:

CREATE USER mastodon CREATEDB;
\q

You can enhance Post­greSQL database per­for­mance by adjusting system resources. A useful tool for this is the con­fig­u­ra­tion generator pgTune. Enter details like the number of CPU cores and RAM size to get an optimized Post­greSQL con­fig­u­ra­tion, 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 de­pen­den­cies:

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
• Post­greSQL host: default - Enter
• Post­greSQL port: default - Enter
• Name of Post­greSQL database: default - Enter
• Name of Post­greSQL user: default - Enter
• Password of Post­greSQL 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 au­then­ti­ca­tion: plain
• SMTP OpenSSL verify mode: none
• Email address to send emails “from”: mostly like SMTP-Login
• Send a test email with this con­fig­u­ra­tion right now?: Y
• Send test email to: Enter any email address as recipient
• Save con­fig­u­ra­tion?: 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 cer­tifi­cate

IONOS VPS servers come with an SSL cer­tifi­cate included by default. If your plan doesn’t include one, you can install it later.

For a free SSL cer­tifi­cate, consider Let’s Encrypt, which provides automated cer­tifi­cates that are easy to install and renew.

certbot certonly --nginx -d example.com

The cer­tifi­cate is saved in the folder /etc/letsencrypt/live/example.com/ on your Mastodon server.

Step 6: set up Nginx

You must copy the con­fig­u­ra­tion 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 con­fig­u­ra­tion file in sites-enabled to enable it and remove the default con­fig­u­ra­tion:

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

Launch the con­fig­u­ra­tion 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 cer­tifi­cate. If you use the default self-signing cer­tifi­cate, 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 con­fig­u­ra­tion, 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 ap­pli­ca­tion and the real-time streaming functions are started au­to­mat­i­cal­ly when the server is started. This ensures that your Mastodon server is per­ma­nent­ly available.

Copy the Systemd service templates from Mastodon to the cor­re­spond­ing 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 con­fig­u­ra­tion of systemd to reflect the new service templates.

• systemctl enable –now mastodon-web mastodon-sidekiq mastodon-streaming: These services are re­spon­si­ble for the web ap­pli­ca­tion, back­ground pro­cess­ing and real-time streaming functions of Mastodon.

Step 8: change character limit

Running your own Mastodon server gives you the flex­i­bil­i­ty to adjust settings not available on public servers. For instance, you can modify the character limit for posts, which is set to 500 char­ac­ters 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 con­tain­ing :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 char­ac­ters.

Step 9: mod­er­a­tion function

The mod­er­a­tion function under “Settings > Mod­er­a­tion” on your Mastodon server lets you, as an admin, monitor and manage content and user activity to ensure com­pli­ance with the Community Guide­lines and remove unwanted content.

You can block, unblock, or delete in­di­vid­ual accounts, domains, IP addresses, or email servers. Ad­di­tion­al­ly, you can moderate user content by removing or editing in­ap­pro­pri­ate or offensive posts.