Let's deploy an Instance aka "I'm going on an adventure" [2.4.3 Docker on Ubuntu 18.04 - Aug 2018]

Hey, I’ve decided to join the Mastodon party and DevOps my way into a clean secure server… and I figure I might as well write some more detailed documentation while catching and fixing bugs along the way. I’m going to document my adventure and hopefully get some assistance from the community along the way.

I’ve started to document the Ubuntu Server preparation, and trying to make the process as hands off as possible… Please feel free to PR my guide as it starts to grow.

Status: Almost ready to launch my instance.

1 Like

Current blockers:


  1. There doesn’t seem to be a lot of diagnostic tools? How can you tell the server is talking to other federated services?
  2. bridge dot joinmastodon dot org seems to be broken when trying to auth to my server?
  3. Relay seems to be broken. I think this is a new feature that isn’t meant to be working yet?
  4. How long until back federation? Grabbing older tweets/follows/followers list when following existing users on other instances?


  1. Deployed a brand new Ubuntu 18.04 Instance
  • Updated the locales
  • Updated the server packages/AWS specific packages.
  • Rebooted box
  1. Prepared box for Mastodon
  • Created a mastodon user/group - forcing the UID/GID to 991 on the local box to match the docker container UID/GID
  • Installed Docker-ce
  • Installed Docker-Compose
  • Activated swap


  1. Log into the new mastodon account
    Confirm the mastodon account has sudo/docker/mastodon 991 groups.
    uid=991(mastodon) gid=991(mastodon) groups=991(mastodon),27(sudo),999(docker) or similar

  2. clone the mastodon git
    checkout latest tag (v2.4.3 for example)

  3. Edit the docker-compose.yml

  • Hardcode version instead of latest
    image: tootsuite/mastodon:v2.4.3 (Match checkout verison)
  • Comment out DB/Redis parts (as they’re running on RDS/ElasticCache)
  • Left the tor/proxify parts commented for now - investigate
  1. Run docker build
    I’m going to build locally, instead of pulling docker hub images
    docker-compose build

  2. Setup Mastodon
    docker-compose run --rm web bundle exec rake mastodon:setup

  • mastodon:setup process states it will save the new .env.production even when using docker - but I don’t think it actually does… This thing will ask questions about the DB/Redis/Storage (S3)/Email (Mailgun)…

  • This should result in the DB schema being created (the first time I did this, it gave me an error… rerunning it worked correctly)

  • Next it will generate the assets:precompile webpacker templates… but because these were pre-generated inside the docker image - this seems to be completed quickly.


  1. Install nginx and certbox for Let’s Encrypt
  • Installed nginx
  • Deleted standard conf
  • Created mastodon conf (using default conf from doco)
    ** make sure you edit the paths to match your public path/domain/tls certs.
  • Installed certbot
  • Generated TLS certs using certonly mode
  • Started nginx without errors (no major changes from default)


  1. 2GB of memory + 5GB of swap seems to be fine for a starting point (1GB of memory seems to run out of memory during the assets precompile and just generally) - I’m running the DB/Redis on a seperate dedicated server (more memory might be required if you’re running them all locally)

  2. Some documents state docker run and some docker-compose run - make sure you use the correct one as docker-compose should bring in the .env.production values…

  3. some documents state you need to manually generate secrets/vapid keys… but mastodo:setup seems to be that for you.
    docker-compose run --rm web rake secret

  4. docker-compose run --rm web rails db:migrate is apparently meant to be run after upgrading - but some guides recommend running it anyway? I ran it against my fresh server and had no output… I assume because it required no changes to the newly deployed DB schema.

Little Bugs

  1. “X-Accel-Mapping header missing” spamming web logs
    “X-Accel-Mapping header missing” spamming web logs · Issue #8306 · tootsuite/mastodon · GitHub

AWS Design
If you’re looking to build a “scalable” environment in AWS… this is how I’ve deployed my mastodon instance.

The moving pieces are all tiny - and can be increased as required… each are independent and can be upgraded/downgraded as required or replaced as required.

1 Like