How to Install Mastodon on Ubuntu 22.04/20.04 Server

This tutorial is going to show you how to install Mastodon on Ubuntu 22.04/20.04 server. Mastodon is an open-source decentralized social network. It’s like Twitter, but decentralized. You can set up a Mastodon instance on your server and connect to other Mastodon instances.

Mastodon Features

  • Total data control. You can download all your posts and migrate to another instance.
  • Never worry about account termination by a central organization.
  • Each Mastodon instance can set its own rules.
  • 500 character limit per post.
  • Mobile-friendly, responsive web design. Users can read or post from laptop, tablet and phone.
  • 100% free open source. No paid commercial version with better or more complete features.
  • Official mobile apps for Mastodon are available for iOS and Android
  • And many more.

Mastodon is written with React.js and Ruby on Rails, using PostgreSQL as the back-end database management system.


Here’s what you should prepare before setting up your own Mastodon instance.

1. A domain name. You need a domain name, so other people can access your Mastodon instance. I registered my domain name at NameCheap because the price is low and they give whois privacy protection free for life.

2. A server. To run Mastodon, you need a server with at least 2GB RAM. If you are looking for a virtual private server (VPS), I recommend Kamatera VPS, which features:

  • 30 days free trial.
  • Starts at $4/month (1GB RAM)
  • High-performance KVM-based VPS
  • 9 data centers around the world, including the United States, Canada, UK, Germany, The Netherlands, Hong Kong, and Isreal.
  • CPU and RAM hot-add. You can temporarily upgrade the server CPU and RAM for free without a reboot.

Follow the tutorial linked below to create your Linux VPS server at Kamatera.

3. SMTP Service. You need to use an SMTP server to send emails for account registration and various other notifications.  You can set up your own email server (which takes some time), or use a free SMTP relay service (easier)

Once the above requirements are met, follow the steps below to install Mastodon.

Step 1: Configure PostgreSQL Database Server

Log into your server via SSH. PostgreSQL is available in the default Ubuntu repository. However, the PostgreSQL team always strives to make performance improvements with every new version, so we will install the latest version of PostgreSQL from the upstream repository.

Add the upstream repository.

echo "deb [signed-by=/etc/apt/keyrings/postgresql.asc] $(lsb_release -cs)-pgdg main" | sudo tee /etc/apt/sources.list.d/pgdg.list

Import the PostgreSQL public key.

sudo mkdir -p /etc/apt/keyrings/

wget --quiet -O - | sudo tee /etc/apt/keyrings/postgresql.asc

Update repository index and install PostgreSQL.

sudo apt update

sudo apt install -y postgresql postgresql-contrib

PostgreSQL database server will automatically start and listens on, as can be seen with the following command.

sudo ss -lnpt | grep postgres

mastodon postgresql ubuntu

If you don’t see any output from the above command, it’s probably because PostgreSQL server isn’t running. You can start PostgreSQL server by issuing the following command.

sudo systemctl start postgresql

The postgres user is created on the OS during the installation process. It’s the super user for PostgreSQL database server. We can use sudo to switch to the postgres user and log into the PostgreSQL console.

sudo -u postgres -i psql

Create a database for Mastodon.


Create a database user.

CREATE USER mastodon;

Set a password for this user.

ALTER USER mastodon WITH ENCRYPTED PASSWORD 'your_preferred_password';

Give this user permission to create database.

ALTER USER mastodon createdb;

Set this user as the owner of Mastodon database.

ALTER DATABASE mastodon OWNER TO mastodon;

Log out from the PostgreSQL console.


postgresql create database for mastodon

Step 2: Install Ruby on Ubuntu 22.04/20.04

Mastodon requires Ruby 2.5+. Ubuntu 22.04/20.04 repository includes the ruby package, so run the following command to install it.

sudo apt install ruby ruby-dev

To check your Ruby version number, run

ruby -v

Sample output:

ruby 2.7.4p191 (2021-07-07 revision a21a3b7d23) [x86_64-linux-gnu]

Step 3: Download and Configure Mastodon

Create the mastodon user.

sudo adduser mastodon --system --group --disabled-login

Install the git tool.

sudo apt install git

Run the following command to clone the Mastodon code repository from Github.

git clone

Create the /var/www/ directory, if it’s not already created.

sudo mkdir -p /var/www/

Move the mastodon directory to /var/www/.

sudo mv mastodon/ /var/www/

Change the owner to mastodon.

sudo chown mastodon:mastodon /var/www/mastodon/ -R

Change directory and check out the latest stable release of Mastodon. You can go to the Github releases page to see the latest stable version. I’m now using v4.0.2.

cd /var/www/mastodon/

sudo -u mastodon git checkout v4.0.2

Install bundler: the Ruby dependency manager.

sudo gem install bundler

Install Node.js v16. (Mastodon isn’t compatible with Node.js v18 or v19).

curl -sL | sudo bash -

sudo apt install nodejs

Install Yarn, a Node.js package manager.

echo "deb stable main" | sudo tee /etc/apt/sources.list.d/yarn.list

curl -sL | sudo apt-key add -

sudo apt update

sudo apt -y install yarn

Install required packages to compile source code.

sudo apt install redis-server optipng pngquant jhead jpegoptim gifsicle nodejs imagemagick ffmpeg libpq-dev libxml2-dev libxslt1-dev file 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 libidn11-dev libicu-dev libjemalloc-dev

Then install dependency packages for Mastodon.

sudo -u mastodon bundle config deployment 'true'

sudo -u mastodon bundle config without 'development test'

sudo -u mastodon bundle install -j$(getconf _NPROCESSORS_ONLN)

Run the setup wizard.

sudo -u mastodon RAILS_ENV=production bundle exec rake mastodon:setup

First, it will ask you a series of questions.

  • Domain name: Choose a domain name to use for your Mastodon instance. For example, I use
  • Enable single user mode: If you want visitors to be able to register on your Mastodon instance, then don’t enable single user mode.
  • Are you using Docker to run Mastodon: No.
  • PostgreSQL host:
  • PostgreSQL port: 5432
  • PostgreSQL database: mastodon
  • PostgreSQL user: mastodon
  • PostgreSQL user password: enter the password for the mastodon user which is created in step 1.
  • Redis host:
  • Redis port: 6379
  • Redis password: Just press Enter, because there’s no password for Redis.
  • Do you want to store uploaded files on the cloud? If you want to store user-uploaded files in S3 object storage, then you can choose Yes. I just want to store files on my own server, so I choose No.
  • Do you want to send emails from localhost? If this is your mail server, or you have set up an SMTP relay, then you can choose Yes. If you choose No, then you need to enter your SMTP server login credentials.
  • E-mail address to send e-mails “from”: You can press Enter to use the default sender email address.
  • Send a test e-mail with this configuration right now? Choose Yes to send a test email.
  • Send test e-mail to: Enter the test email address.
  • Save configuration? Choose Yes.

mastodon Create a configuration file

Next, Choose Yes to set up the database.

Now that configuration is saved, the database schema must be loaded.
If the database already exists, this will erase its contents.
Prepare the database now? y

Finally, choose Yes to compile CSS/JS assets.

The final step is compiling CSS/JS assets.
This may take a while and consume a lot of RAM.
Compile the assets now? (Y/n) y

ubuntu mastodon setup wizard

Hint: If Mastodon fails to compile, you should upgrade the server to 2 CPU cores and 3G RAM. If you use Kamatera VPS, it allows you to temporarily upgrade the server CPU and RAM for free without a reboot (Hot Add). Then run the following command again to compile Mastodon CSS/JS assets. Make sure you change back to the original server specs, so Kamatera won’t charge extra dollars for CPU/RAM hot add.

sudo -u mastodon RAILS_ENV=production bundle exec rake mastodon:setup

Once that’s done, you can create an admin user.

Do you want to create an admin user straight away? Yes
Username: super_admin
E-mail: [email protected]
You can login with the password: 0b8c9359a98059aWg0yhPyVP3eeOn6715eeb

Step 4: Start Mastodon

Mastodon provides convenient systemd service templates. We can copy them to the /etc/sysetmd/system/ directory.

sudo cp /var/www/mastodon/dist/mastodon*.service /etc/systemd/system/

Then we need to make some changes to the .service files. Change the working directory from /home/mastodon/live/ to /var/www/mastodon/.

sudo sed -i 's/home\/mastodon\/live/var\/www\/mastodon/g' /etc/systemd/system/mastodon-*.service

Change /home/mastodon/.rbenv/shims/bundle to /usr/local/bin/bundle.

sudo sed -i 's/home\/mastodon\/.rbenv\/shims/usr\/local\/bin/g' /etc/systemd/system/mastodon-*.service

Reload systemd for the changes to take effect.

sudo systemctl daemon-reload

Start the 3 systemd services.

sudo systemctl enable --now mastodon-web mastodon-sidekiq mastodon-streaming

Check status. Make sure they are all in active (running) state.

sudo systemctl status mastodon-web mastodon-sidekiq mastodon-streaming

Wait a few seconds, then run the following command to check if Mastodon is listing on port 3000.

sudo ss -lnpt | grep 3000

If Mastodon is running properly, it should output:

LISTEN 0   1024*    users:(("ruby2.7",pid=43543,fd=5),("ruby2.7",pid=43535,fd=5),("ruby2.7",pid=43520,fd=5))

If port 3000 thousand is already taken by another process, you need to edit the /etc/systemd/system/mastodon-web.service file.

sudo nano etc/systemd/system/mastodon-web.service

Find the following line.


Change the port number like 3001, so Mastodon will be listening on port 3001. Reload systemd and restart Mastodon.

sudo systemctl daemon-reload

sudo systemctl restart mastodon-web

Step 5: Configure Nginx Reverse Proxy

Install Nginx web server from the default Ubuntu 22.04/20.04 software repository.

sudo apt install nginx

Copy the Nginx template configuration file.

sudo cp /var/www/mastodon/dist/nginx.conf /etc/nginx/conf.d/mastodon.conf

Edit the new file.

sudo nano /etc/nginx/conf.d/mastodon.conf

Find the following line in both the port 80 server block and port 443 server block.


Change the server name. Don’t forget to add DNS A record for the domain name.


Find the following line in both the port 80 server block and port 443 server block.

root /home/mastodon/live/public;

Change it to:

root /var/www/mastodon/public;

Find the following two lines.

 # ssl_certificate /etc/letsencrypt/live/;
# ssl_certificate_key /etc/letsencrypt/live/;

Change them to the following, so Nginx will tempoarily use a self-signed TLS certificate. We will obtain a valid Let’s Encrypt certificate later.

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

Save and close the file. Create the cache directory.

sudo mkdir -p /var/nginx/cache/

Then test Nginx configuration.

sudo nginx -t

If the test is successful, reload Nginx for the changes to take effect.

sudo systemctl reload nginx

Now you should be able to see the Mastodon forum at

Step 7: Enable HTTPS

To encrypt HTTP traffic, we can enable HTTPS by installing a free TLS certificate issued from Let’s Encrypt. Run the following command to install Let’s Encrypt client (certbot) on Ubuntu 22.04/20.04 server.

sudo apt install certbot python3-certbot-nginx

Next, run the following command to obtain and install TLS certificate.

sudo certbot --nginx --agree-tos --redirect --hsts --staple-ocsp --email [email protected] -d


  • --nginx: Use the nginx plugin.
  • --agree-tos: Agree to terms of service.
  • --redirect: Force HTTPS by 301 redirect.
  • --hsts: Add the Strict-Transport-Security header to every HTTP response. Forcing browser to always use TLS for the domain. Defends against SSL/TLS Stripping.
  • --staple-ocsp: Enables OCSP Stapling. A valid OCSP response is stapled to the certificate that the server offers during TLS.
  • --email: an email address is required to receive important email notification for your TLS certificates.

The certificate should now be obtained and automatically installed.

mastodon letsencrypt https

And you can access Mastodon forum via HTTPS (

mastodon login page

And you can login using the admin account created in step 3. After login, you should change the password.

Hint: My Mastodon account:

Can’t Send Emails?

If Mastodon fails to send emails, you can find out what went wrong by going to the URL, assuming you are logged in as the admin user.

How to Back Up and Restore Mastodon Database

Dump the database into a tar archive.

sudo -u postgres -i pg_dump -F t mastodon > mastodon_pgsql.tar

Restore the database.

sudo -u postgres -i pg_restore --clean --dbname=mastodon /path/to/the/mastodon_pgsql.tar

To back up the /var/www/mastodon/ folder, I recommend using Duplicati.

Troubleshooting Mastodon Runtime Error

If the Mastodon web page isn’t working, you should check the sysetmd journals.

sudo journalctl -eu mastodon-web

sudo journalctl -eu mastodon-sidekiq

sudo journalctl -eu mastodon-streaming

How to Upgrade Mastodon

First, back up the database as mentioned above.

Then go to the Mastodon web root directory.

cd /var/www/mastodon/

Fetch new release tags.

sudo -u mastodon git fetch --tags

Sample output:

 * [new tag]             v3.5.4                                                          -> v3.5.4
 * [new tag]             v3.5.5                                                          -> v3.5.5
 * [new tag]             v4.0.0                                                          -> v4.0.0
 * [new tag]             v4.0.0rc1                                                       -> v4.0.0rc1
 * [new tag]             v4.0.0rc2                                                       -> v4.0.0rc2
 * [new tag]             v4.0.0rc3                                                       -> v4.0.0rc3
 * [new tag]             v4.0.0rc4                                                       -> v4.0.0rc4
 * [new tag]             v4.0.1                                                          -> v4.0.1
 * [new tag]             v4.0.2                                                          -> v4.0.2

Upgrade to v4.0.2

sudo -u mastodon git checkout v4.0.2

Migrate the database.

sudo -u mastodon RAILS_ENV=production bundle exec rake db:migrate

Compile the assets.

sudo -u mastodon bundle install -j$(getconf _NPROCESSORS_ONLN)

sudo -u mastodon RAILS_ENV=production bundle exec rails assets:precompile

Migrate the database again.

sudo -u mastodon RAILS_ENV=production bundle exec rake db:migrate

Once that’s done. Restart Mastodon.

sudo systemctl restart mastodon-web mastodon-sidekiq mastodon-streaming


I hope this article helped you install Mastodon forum software on Ubuntu 22.04/20.04. As always, if you found this post useful, then subscribe to our free newsletter to get more tips and tricks. Take care 🙂

Rate this tutorial
[Total: 17 Average: 4.8]

42 Responses to “How to Install Mastodon on Ubuntu 22.04/20.04 Server

  • Unfortunately I always receive an error while trying to install bundler

    ERROR: Could not find a valid gem ‘bundler’ (>= 0), here is why:
    Unable to download data from – timed out (

  • Please, where to find the .env file?

    • Xiao Guoan (Admin)
      6 months ago

      Hi Propper,

      Some commands require you to be in the /var/www/mastodon/ directory, which stores the .env files.

      cd /var/www/mastodon
      • @Xiao
        Thank you for your quick reply. My fingers were faster than my thoughts… sorry about that.
        Could not find (see) the [.env] file because of the [.]

        Very good post, Mastodon runs right away.

  • I cannot figure out how to fix

    An error occurred while installing openssl (2.2.0), and Bundler cannot continue.
    In Gemfile:
      webauthn was resolved to 3.0.0.alpha1, which depends on

    I presume i need a older version of openssl, but i dont know how to install it.

  • error @mastodon/[email protected]: The engine "node" is incompatible with this module. Expected version ">=12". Got "10.19.0"
    error Found incompatible module.

    I don’t seem to be able to convince it there is actually a newer node module already, how can I resolve this – I’m not quite sure I understand why it thinks there is 10.19.0 when a node -v says v19.0.1

    • Xiao Guoan (Admin)
      2 weeks ago

      Mastodon isn’t compatible with NodeJS v18 and v19. You can use v16.

  • Works like a charm thank you

  • Unfortunately not working.

    [email protected]:/var/www/mastodon# gem env
    RubyGems Environment:
      - RUBYGEMS VERSION: 3.1.2
      - RUBY VERSION: 2.7.0 (2019-12-25 patchlevel 0) [x86_64-linux-gnu]
      - INSTALLATION DIRECTORY: /var/lib/gems/2.7.0
      - USER INSTALLATION DIRECTORY: /root/.gem/ruby/2.7.0
      - RUBY EXECUTABLE: /usr/bin/ruby2.7
      - GIT EXECUTABLE: /usr/bin/git
      - EXECUTABLE DIRECTORY: /usr/local/bin
      - SPEC CACHE DIRECTORY: /root/.gem/specs
        - ruby
        - x86_64-linux
      - GEM PATHS:
         - /var/lib/gems/2.7.0
         - /root/.gem/ruby/2.7.0
         - /usr/lib/ruby/gems/2.7.0
         - /usr/share/rubygems-integration/2.7.0
         - /usr/share/rubygems-integration/all
         - /usr/lib/x86_64-linux-gnu/rubygems-integration/2.7.0
         - :update_sources => true
         - :verbose => true
         - :backtrace => false
         - :bulk_threshold => 1000
      - SHELL PATH:
         - /usr/local/sbin
         - /usr/local/bin
         - /usr/sbin
         - /usr/bin
         - /sbin
         - /bin
         - /usr/games
         - /usr/local/games
         - /snap/bin
    sudo journalctl -eu mastodon-web
    Nov 10 20:16:59 localhost systemd[19890]: mastodon-web.service: Failed to execute command: No such file or directory
    Nov 10 20:16:59 localhost systemd[19890]: mastodon-web.service: Failed at step EXEC spawning /home/mastodon/.rbenv/shims/bundle: No such file or directo>
    Nov 10 20:16:59 localhost systemd[1]: mastodon-web.service: Main process exited, code=exited, status=203/EXEC
    Nov 10 20:16:59 localhost systemd[1]: mastodon-web.service: Failed with result 'exit-code'.
    Nov 10 20:16:59 localhost systemd[1]: mastodon-web.service: Scheduled restart job, restart counter is at 3.
    Nov 10 20:16:59 localhost systemd[1]: Stopped mastodon-web.
    sudo journalctl -eu mastodon-sidekiq
    Nov 10 20:16:59 localhost systemd[19889]: mastodon-sidekiq.service: Failed to execute command: No such file or directory
    Nov 10 20:16:59 localhost systemd[19889]: mastodon-sidekiq.service: Failed at step EXEC spawning /home/mastodon/.rbenv/shims/bundle: No such file or dir>
    Nov 10 20:16:59 localhost systemd[1]: mastodon-sidekiq.service: Main process exited, code=exited, status=203/EXEC
    Nov 10 20:16:59 localhost systemd[1]: mastodon-sidekiq.service: Failed with result 'exit-code'.
    Nov 10 20:16:59 localhost systemd[1]: mastodon-sidekiq.service: Scheduled restart job, restart counter is at 3.
    Nov 10 20:16:59 localhost systemd[1]: Stopped mastodon-sidekiq.
    • Xiao Guoan (Admin)
      2 weeks ago

      The systemd status output indicates that it was trying to find the /home/mastodon/.rbenv/shims/bundle binary.

      Please follow step 4 to change the working directory from /home/mastodon/live/ to /var/www/mastodon/.

      And change /home/mastodon/.rbenv/shims/bundle to /usr/local/bin/bundle.

      You can copy and paste my commands, or open the systemd service files and change them manually. Be careful of typo mistakes.

  • I installed locally. I have NPM setup, but I cannot get the interface to load after running through this entire tutorial twice. I set Lets Encrypt through NPM, but cannot even access locally (direct IP). Any ideas?

  • Hiya. They just fixed compatibility with Openssl 3.0

    • Xiao Guoan (Admin)
      2 weeks ago

      Thanks for your notification. I just updated this article.

  • Xiao Guoan (Admin)
    2 weeks ago

    For Ubuntu 22.10 users:

    Ubuntu 22.10 ships with NodeJS v18, which isn’t compatible with Mastodon now. After adding the nodejs repository as mentioned in this article, you should run the following command to list available nodejs packages.

    apt-cache policy nodejs

    Sample output:

      Installed: 16.18.1-deb-1nodesource1
      Candidate: 18.7.0+dfsg-5ubuntu1
      Version table:
         18.7.0+dfsg-5ubuntu1 500
            500 kinetic/universe amd64 Packages
         16.18.1-deb-1nodesource1 500
            500 kinetic/main amd64 Packages
            100 /var/lib/dpkg/status

    Then download nodejs from the nodesource repository.

    sudo apt download nodejs=16.18.1-deb-1nodesource1

    Install this package.

    sudo apt install ./nodejs_16.18.1-deb-1nodesource1_amd64.deb
  • Thanks for this excellent guide! I used it a few weeks ago to install 3.5.3 on 20.04. I was trying to do the upgrade listed here, it appears to go smoothly, but when its done, I keep getting a ‘something went wrong’ splash page. Is there an intermediate step I should do between 3.5.3 and 4.0.2 (like when it goes to 4.0.0?)

  • Whoopee
    2 weeks ago

    I got so close! I’m getting ERR_TOO_MANY_REDIRECTS and the site won’t load. Are there logs I can share that will help get it fixed?

  • Thanks, Xiao, for the best instructions I have seen in a very long time. I had tried several others before finding LinuxBabe, and they all had significant gaps. Xiao, yours is the Gold Standard, IMHO. I was happy to see you move the site to /var/www/mastodon/public out of the /home directory.

    The one issue I have is a problem running tootctl. It says Could not find rake.

    [email protected]:/var/www/mastodon/bin$ ./tootctl help
    Could not find rake-13.0.6 in any of the sources
    Run `bundle install` to install missing gems.

    I tried running “bundle install,” but that did not resolve the issue. I have the environment variable set in .bashrc to production.

    Thanks for any help, and thank again for your hard work.

    • Xiao Guoan (Admin)
      1 week ago

      Hi Jay,

      I use the following method to run tootctl.

      cd /var/www/mastodon
      sudo -u mastodon RAILS_ENV=production bin/tootctl help
      • Hi Xiao and thanks for your suggestion. I tried it and get the same “Could not find rake…”

        [email protected]:/var/www/mastodon$ sudo -u mastodon RAILS_ENV=production bin/tootctl help
        Could not find rake-13.0.6 in any of the sources
        Run `bundle install` to install missing gems.

        A search for rake shows:

        [email protected]:/var/www/mastodon$ find . -name rake

        Thanks again for your help.

    • Xiao Guoan (Admin)
      6 days ago

      Maybe you need to run the following commands again?

      cd /var/www/mastodon/
      sudo -u mastodon bundle config deployment 'true'
      sudo -u mastodon bundle config without 'development test'
      sudo -u mastodon bundle install -j$(getconf _NPROCESSORS_ONLN)
      • Hello again. I can’t thank you enough for your help. I reran those commands, but no luck.

        [email protected]:~$ cd /var/www/mastodon/
        [email protected]:/var/www/mastodon$ RAILS_ENV=production ./bin/tootctl --version
        Could not find rake-13.0.6 in any of the sources
        Run `bundle install` to install missing gems.
        [email protected]:/var/www/mastodon$ sudo -u mastodon bundle config deployment 'true'
        [email protected]:/var/www/mastodon$ sudo -u mastodon bundle config without 'development test'
        You are replacing the current local value of without, which is currently "development:test"
        [email protected]:/var/www/mastodon$ sudo -u mastodon bundle install -j$(getconf _NPROCESSORS_ONLN)
        Fetching gem metadata from
        Using rake 13.0.6
        Using rails 6.1.7
        Using rails-settings-cached 0.6.6
        Bundle complete! 124 Gemfile dependencies, 226 gems now installed.
        Gems in the groups 'development' and 'test' were not installed.
        Bundled gems are installed into `./vendor/bundle`
        [email protected]:/var/www/mastodon$ sudo -u mastodon RAILS_ENV=production bin/tootctl help
        Could not find rake-13.0.6 in any of the sources
        Run `bundle install` to install missing gems.

        The response said, “Gems in the groups ‘development’ and ‘test’ were not installed.” Is that normal?

        Everything else with the installation appears to be working fine. It’s a shame they had to make the tootctl so convoluted. I have not found anything in the log files that shed any light.

        [email protected]:/var/www/mastodon$ cd /
        [email protected]:/$ sudo find . -name rake-*
        [email protected]:/$ 
        [email protected]:/$ ruby -v
        ruby 2.7.0p0 (2019-12-25 revision 647ee6f091) [x86_64-linux-gnu]

        Thanks again for your help,

        • I’m happy to report that my “missing tootctl – rake-13.0.6” issue has been resolved. I initially tried to install it using ubuntu 22.10 x64 which failed to compile. I’m sure it’s a well-documented issue, but I missed it. So I found that 20.04 (LTS) x64 would compile, and Mastodon ran with no apparent issues except I could not run the tootctl script, which reported: “could not find rake-13.0.6”. Once I realized I should have been using 22.04 (LTS) x64, everything worked as expected, along with the tootctl script. I can’t thank Xiao for his help and patience.

    • Xiao Guoan (Admin)
      5 days ago

      Install rake from the Ubuntu repository.

      sudo apt install rake

      Check rake version.

      rake -V

      Sample output:

      rake, version 13.0.6
    • Xiao Guoan (Admin)
      5 days ago

      Or you should set the path before installing the gems.

      cd /var/www/mastodon/
      sudo -u mastodon RAILS_ENV=production /usr/local/bin/bundle config set path '/var/www/mastodon/vendor/bundle/'
      sudo -u mastodon RAILS_ENV=production /usr/local/bin/bundle install
  • Hi there! Yesterday I used the prior version of this page to get mastodon 3.5.3 running successfully. It was great! Today I found the newer version of this page and used your instructions to upgrade to mastodon 4.0.2. There were no errors in setting the tag and rebuilding… but I’m now getting runtime errors from the mastodon web service, which is throwing a 500 to the user’s GET request:

    ActionView::Template::Error (undefined local variable or method `role_id' for #
    Did you mean?  role):
     7:   %meta{ name: 'applicationServerKey', content: Rails.configuration.x.vapid_public_key }
    9:   = render_initial_state
    10:   = javascript_pack_tag 'application', crossorigin: 'anonymous'
    12:{ data: { props: Oj.dump(default_props) } }
  • Replying to myself: all fixed! Turns out the db needed to be upgraded to get from 3.5 to 4.0, which you can see at the bottom of the 4.0 release notes here ( You need to update your ‘how to upgrade’ section to include the two db:migrate commands — one before the assets:precompile, and one again afterwards. Nevertheless, I sent you a paypal tip! Thanks for the great guide!

    • Xiao Guoan (Admin)
      1 week ago

      Thanks for your tip 🙂 (Pun intended)

  • Great guide, all went smoothly even email worked, but upon loading the site I just get a white blank page with the mastodon logo top left in any broswer, tried rebooting the server, can’t see any errors, any idea?

    • Fixed, i left ‘live’ in the lines to change: root /var/www/mastodon/public

      All working. Brilliant guide.

  • Hello. Great guide. I am excited to give it a try. Do you have any instructions to install elasticsearch as well?

  • Zaraki
    6 days ago

    Thank you for the wonderful instructions. Everything worked just fine. I only have one question. Instead of saving the files to the server, I want to use StorJ as S3. Since this can’t be done directly through the “install wizard”, I need to edit it directly in the cfg file. The problem is that the instructions says “For convenience, it can read them from a flat file called .env.production in the Mastodon directory (called a “dotenv” file), but they can always be overridden by a specific process.” , but I can’t find that file anywhere.

    Do you have any advice on where I can find it after installation? It’s strange, because when I followed the instructions elsewhere I had it there, but everything else didn’t work. :))

  • bakamenon
    6 days ago

    hi Xiao! Great tutorial… Would it be possible for your to explain a bit on how to go about attaching a block storage for added storage? Thank you!

  • Andrew
    6 days ago

    I have followed these instructions twice and my website only shows the Mastodon logos nothing else. I have attached a screenshot

    • Xiao Guoan (Admin)
      5 days ago

      Check your Nginx logs to find out what went wrong. (/var/log/nginx/error.log and /var/log/nginx/access.log)

    • I had that by mssing the word live removal here:
      Find the following line in both the port 80 server block and port 443 server block.

      root /home/mastodon/live/public;

      Change it to:

      root /var/www/mastodon/public;

  • Thank you for this guide, and for keeping it updated.
    I installed 2 ubuntu servers from your instructions and ran into a couple issues with missing gem files as other folks in the comments here and figured them out by Googling.

    One issue I ran into was the Federated timeline in both servers stopped working after 3 days and it turns out that the /etc/systemd/system/mastodon-sidekiq.service file needs to be updated to specify each of the queues being used, so in this line of the file:

    ExecStart=/usr/local/bin/bundle exec sidekiq -c 25

    I had to append -q ingress -q scheduler -q default -q push -q mailers -q pull
    and then restart the mastodon-sidekiq service.

    Again, many thanks for this quide.

Leave a Comment

  • Comments with links are moderated by admin before published.
  • Your email address will not be published.
  • Use <pre> ... </pre> HTML tag to quote the output from your terminal/console.
  • Please use the community ( for questions unrelated to this article.
  • I don't have time to answer every question. Making a donation would incentivize me to spend more time answering questions.

The maximum upload file size: 2 MB. You can upload: image. Links to YouTube, Facebook, Twitter and other services inserted in the comment text will be automatically embedded. Drop file here