Why main install docs don't use Docker?

Hey, Falco from discourse.org here :wave:.

I’m curious why the main install docs for Mastodon default to installing directly on the server, and requiring quite a lot of commands from the admin, instead of using a docker install which should require less interactions, and leaving less space for typos and wrong or missing dependencies.


I agree. Or at least a script or something.

Hey Falco! Sorry for not seeing this earlier.

The main issue is that we’ve found Docker container setups to be unfriendly for newbie sysadmins. We used to recommend Docker as the primary installation method, but we had lots of problems with people running docker-compose down and destroying volumes, people having problems with finding logs and setting up init systems, and lots of issues of that sort. In the end, we decided that most entry-level sysadmins are better suited by a native installation guide like this one, that works better with the existing body of Unix how-to tutorials, like the ones hosted by DigitalOcean and Linode. Docker installs are still supported and available, they’re just not the main focus of our installation guides.

I will fully admit that many of the issues stem from us, the primary maintainers, not being super familiar with Docker ourselves and also not having the resources (at the time) to invest in a tooling system to make Docker more newbie-friendly, like Discourse has been able to. Some more minor issues: we were reliant on a lot of community patches to maintain the more complicated parts our Docker configuration, and there were a lot of arguments over “best practices” that we weren’t able to resolve ourselves due to our unfamiliarity. This also caused more subtle issues: one contributor would do things one way, and then someone would come with a patch to do things a completely different way, and the conflict between the two approaches wouldn’t be apparent to us until it caused issues down the line.

None of these are insurmountable problems, but ultimately we had a lot more success and a lot fewer tragic issues guiding newbies towards the native install route, and allowing those with more complex setups to choose Docker if they were already comfortable with it.


(Also, re: “at least have a script”, I’m not sure I agree that “require less interactions” is a good quality in an installation guide, especially for a system as complex as Mastodon. A working Mastodon install has a lot of moving parts: Sidekiq, Postgres, Redis, Webpack, etc, and I think it’s good for sysadmins to at least have a basic, high-level understanding of how all of these parts fit together, instead of having them abstracted away behind a single “install mastodon” command)


I spend sometimes quite a lot of time reverse engineering various Docker-only installations to really understand what is working, what is not and how to troubleshoot that.

1 Like

I had a nice example of this few days ago on IRC - for some reason Elastic Search could not be contacted. It took a while to figure out how actually ES is reached (hostname was es).