Add deployment guide for NGINX

[rawsashimi1604]

Have you read the Contributing Guidelines on issues?

• [x] I have read the Contributing Guidelines on issues.

Description

Hey all, feel like we could enhance the Deployment docs by providing a quick getting started guide on hosting docusaurus static build files via a dockerised NGINX. Would be willing to write a quick guide!

Self-service

• [x] I'd be willing to address this documentation request myself.

[slorber]

Hi

Honestly I'd prefer to not add this guide to our official docs, and would prefer if it was an external resource we simply link to.

The reason is: I don't have the skills to maintain it. Introducing it means that it's now my responsibility to ensure this "official" guide remains up to date over time and for all the upcoming versions of Nginx.

There's an infinite number of ways to host static websites, using various software. We can't document them all officially: we count on our community for that.

[tats-u]

The important things to host a website built by Docusaurus by Nginx/Apache are:

• How to add/remove a/the trailing slash in the URL
• How long and which directories should be cached

I think the former is stable, and the latter can be shared with Apache.

[tats-u]

The latter:

• /static/: several weeks?
• /assets/: maybe immutable can be added to Cache-Control. Several months–half or one year?

I think an official guideline for them would be appreciated.

[jozefRudy]

I would also appreciate official guide to caching in nginx mentioned by @tats-u , it would be immensely helpful.

my hypothesis here is this, feedback welcome, so that we can arrive at idiomatic configuration in nginx for file /etc/nginx/conf.d/default.conf is this:

server {
    listen 80;
    index index.html;
    root /var/www/html;
    
    location ~* \.html$ {
        add_header Cache-Control "no-store, no-cache, must-revalidate, proxy-revalidate, max-age=0" always;
    }
    
    # /static/ directory - medium-term caching
    location /static/ {
        expires 4w;
        add_header Cache-Control "public, max-age=2419200";
        try_files $uri =404;
    }
    
    # All other static assets - long-term caching
    location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|woff2?|ttf|eot|webp)$ {
        expires 1y;
        add_header Cache-Control "public, max-age=31536000, immutable";
        try_files $uri =404;
    }

    location ~* ^(.+)/$ {
        return 301 $1;
    }

    
    location / {
        try_files $uri $uri/index.html $uri/ =404;
    }
}

[tats-u]

You may want to redirect from a URL with a trailing / to that without it. Also you should use the port 443 with ssl h2 instead of 80 and add the redirection server from 80 to 443 if you have a TLS certificate.

[jozefRudy]

You may want to redirect from a URL with a trailing / to that without it. Also you should use the port 443 with ssl h2 instead of 80 and add the redirection server from 80 to 443 if you have a TLS certificate.

updated, thanks

[bergentroll]

@jozefRudy, error_page 404 404.html; seems also in deal.

And also location ~* ^(.*)/$ { return 301 $1; } gives for me recursion error.

[tats-u]

gives for me recursion error.

Only the top page? If so .+ instead of .* works?

[jozefRudy]

@jozefRudy, error_page 404 404.html; seems also in deal.

And also location ~* ^(.*)/$ { return 301 $1; } gives for me recursion error.

yes, as @tats-u mentioned, this might fix it?

@bergentroll could you confirm?

location ~* ^(.+)/$ {
    return 301 $1;
}

[jozefRudy]

You may want to redirect from a URL with a trailing / to that without it. Also you should use the port 443 with ssl h2 instead of 80 and add the redirection server from 80 to 443 if you have a TLS certificate.

sure, but that is already general config unrelated to docusaurus i think. maybe you are behind traefik which does that and this is purely docusaurus specific. (hence ommitted 443 redirection).

[bergentroll]

@jozefRudy, confirming, .+ works.

[dohrisalim]

I can write a comprehensive deployment guide for hosting Docusaurus sites with dockerized NGINX. I understand the need for practical deployment documentation and will cover nginx configuration, docker setup, static file serving optimization, and best practices for production environments.