Add an offline page to display when Discourse is rebuilding or starting up

Well, if you want to display a 502 page through Cloudflare you have to pay :sweat_smile:


It should be noted that running an nginx proxy in front of Discourse as described here will result in the rate limit, which is by default configured in Discourse Docker to apply for requests for all users.

The rate limit template templates/web.ratelimited.template.yml should be removed from the docker config and the rate limit should then be configured in the outer nginx instance instead.


Why is that? The inner Nginx should trust the forwarded source IP as per this line:

The rate limit uses $binary_remote_addr, which seems to be not overwritten by set_real_ip_from.
I also see that $remote_addr is shown as ´unix:` in the discourse nxing access.log.

IP adresses inside discourse itself seem to work (looking at IPs for user login).

1 Like

Nginx requires the X-Real-IP header to be set for this to work properly!

Default: real_ip_header X-Real-IP;

So the following header needs to be added to the proxy (this is missing in your config above):

proxy_set_header X-Real-IP $remote_addr;

How certain are you that X-Forwarded-For is ignored by default? This guide isn’t particularly new, this one only sets X-Forwarded-For in the HTTP-only case, and I haven’t seen any complaints about rate limits hitting. Also, I’m operating a Discourse site behind such a Nginx proxy, and Discourse does see the real IP address.

If you’re certain, feel free to add the line above – it’s a wiki!


Nginx access logs show unix: as the client when I do not add the header. I get the correct IP when I add it. This also complies to what the nginx docs say so I am very certain this is how it works.

Discourse itself seems to evaluate the X-Forwarded-For header so the problem here only affects IP handling on the nginx which sits in the Discourse Docker container.

I updated the wiki post.


From what happened in my case i believe @cebe is right and you need X-Real-IP specifically for inner nginx.
See Discourse socketed: Nginx in front of discourse: no IP adresses for reference.


Is this possible today? Right now our site goes down when doing an upgrade.

Yes, I use it without any issue.


Cool good to know, thanks for your feedback

The first post says this

Is this the only way to do it? We don’t have nginx running outside docker

Yes, that’s the only way. The idea is to install a webserver (nginx recommended) to serve the request, if Discourse is up it routes it there. If not it does something else. All the installation process is explained step by step.


Hi there,


Thanks for that solution, @fefrei! We’ve implemented this on and it works like a charm.

Further thoughts

However, we would like to reference the related question by @mlinksva at Site maintenance mode during rebuilds? here, as this also resonates with us and does not get solved by the /errorpages solution yet. This is about improving the generic text “Sorry, we couldn’t load that topic, possibly due to a connection problem.”. We will try to outline this in more detail.

Serving discourse_offline.html

This is perfect when users come along fresh to the site.

Serving a different “Sorry for that” text

However, when navigating within Discourse, it will yell at you like


without reveilling anything about the reason.

As we know you already, there will probably be a customization feature for being able to change that text, right? We might just have missed that. We’ve also not investigated whether the Feature Admin » Backup » Enable read-only would solve that already as outlined in Maintenance Mode?.

Nevertheless, it made sense to us to bring up this topic here again and hope you don’t mind if that would have been silly.

With kind regards,

P.S.: @staff: As this discussion somehow spiraled out of control regarding appropriate Nginx or Web server configuration details, I would like to suggest a thorough refactoring by splitting these posts into an appropriately named topic like “Configuring web server for offline page”. I’m sure you will find a good title. Thanks already if you like that suggestion and find it worth to follow.

Now, we actually do feel silly after finding it right away as a customizable site text block:

We’ve changed the standard text js.topic.server_error.description to read:

Thanks for listening ;].


Hm. We are not sure if changing that text actually works for us. Do we have to consider something special here when amending this guy?

Also, we would like to mention that during specific time range while the site was down, it was yelling differently like


Do you have an idea how we would be able to change that also?

1 Like

I use that, but i want a custom offline webpage and im not able to do it

Wonderful guide.
But if only you had told some commands to auto-renew this certificate also. It’d be a complete guide.
Because I’ve seen the link mentioned here. But that link only tells to install the certificate fresh. Or to renew it.
But I couldn’t find the guidance to ‘Auto-renew’ the same.


1 Like

Good point! I updated this section above in the original post :arrow_double_up:

1 Like

Has anyone else noticed that they are seeing a more generic 500 error when the upgrade occurs? I might have caught it at a bad time maybe?

1 Like

When the container is stopped during a rebuild there’s nothing running to provide an error 500.