documentation

documentation copied to clipboard

When installing mastodon in Ubuntu 20.04 LTS recently I've encountered some issues with existing installation manual:

1. certbot is meant for installation via snapd.
2. Previously, the nginx configuration has been put into place requiring the user to restart nginx afterwards. But this is failing due to including SSL setup blocks lacking definition of cert files to use there.
3. The provided nginx configuration got pretty corrupted by certbot. When I was trying to fix it I've missed a spot so that IPv6 users got redirected to default site of nginx which isn't happening when sticking with your configuration as provided.

This merge request is addressing these three issues on behalf of the installation manual. However, it is relying on mastodon repo providing the existing nginx configuration split up in two parts: one for the SSL server definition and one for the rest of currently existing configuration.

This seems like a more complicated solution than is necessary. I just recently migrated to a new Ubuntu 20.04 server and similarly had issues with the instructions. A simpler way to resolve it is to simply run certbot in --standalone mode before (re)loading nginx:

1. install python3-certbot-nginx instead of python-certbot-nginx
2. Stop nginx (systemctl stop nginx) before running certbot (otherwise --standalone can't access ports 80/443)
3. uncomment the certificate paths in the nginx.conf file and replace 'example.com' with the real domain
4. run certbot with certonly --standalone (certbot certonly --standalone -d example.com)
5. Restart nginx: systemctl start nginx

The provided nginx configuration got pretty corrupted by certbot. When I was trying to fix it I've missed a spot so that IPv6 users got redirected to default site of nginx which isn't happening when sticking with your configuration as provided.

Can you please provide more details here? This sounds like a bug in the upstream library, rather then something Mastodon should have to deal with. I'm adverse to putting specific workarounds in our documentation for upstream library bugs, particularly workarounds that are persistent as this one (once we introduce the "split" nginx configs and people integrate it into their workflow, it will be very difficult to remove later)

certbot messing nginx configuration isn't new - at least to me - and that's an issue with certbot for sure. But as of now, people have to deal with it. Your setup in nginx is anything but common (by means of having just two server sections, one on :80 redirecting everything to :443 and another one just exposing a folder via :443). I assume that those cases work well with upstream certbot code for adjusting nginx ... if I go to certbot here, they will tell me that it is impossible to cover each and every use case whatever ... and they are right as well. So, in the end the user of Mastodon has to deal with the dead lock and I don't think that's acceptable.

In my case I wasn't able to use the nginx-mode of certbot for really breaking nginx configuration files. Maybe, there is a fix and that's fine. Maybe it isn't available. Maybe there will be another scenario like this one. After setting up lots of servers using nginx and letsencrypt all I've learned is to ignore the nginx support in certbot altogether. That results in a more reliable and future-proof approach to setting up things, but it also requires to set up nginx w/o ssl support first and have it enabled after first retrieval of letsencrypt-based certificate. That's all I'm suggesting here.

A simpler way to resolve it is to simply run certbot in --standalone mode before (re)loading nginx

This looks just short-sighted to me for it won't work for long probably unless there is a manual adjustment of letsencrypt configuration file. The mode standalone will be stored there for nightly attempts to renew the certificate. And the configuration for standalone mode is different from the one required for webroot mode. So, you still have to tell people how to fix their configuration or how to set up pre/post hooks in lets encrypt to have a downtime of your service while renewing the cert.

This pull request has merge conflicts that must be resolved before it can be merged.

Closed as stale and rebase required. Please resubmit if necessary.