Deploying to NGINX

Deploying your Docusaurus project to NGINX gives you full control over your hosting environment and is a great choice for production deployments.

Build your site

npm run build

This generates static files in the build/ directory.

Basic NGINX configuration

Create an NGINX server block configuration file:

nginx.conf

server {
    listen 80;
    server_name example.com;

    root /var/www/docusaurus/build;
    index index.html;

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

    # Enable gzip compression
    gzip on;
    gzip_types text/plain text/css application/json application/javascript text/xml application/xml text/javascript;
    gzip_min_length 1000;

    # Cache static assets
    location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|woff|woff2|ttf|eot)$ {
        expires 30d;
        add_header Cache-Control "public, immutable";
    }

    # Security headers
    add_header X-Frame-Options "SAMEORIGIN" always;
    add_header X-Content-Type-Options "nosniff" always;
    add_header Referrer-Policy "strict-origin-when-cross-origin" always;
}

Dockerized NGINX deployment

Create a Dockerfile in your project root:

Dockerfile

FROM nginx:alpine

COPY build /usr/share/nginx/html

COPY nginx.conf /etc/nginx/conf.d/default.conf

EXPOSE 80

CMD ["nginx", "-g", "daemon off;"]

Build and run the container:

docker build -t docusaurus-app .
docker run -d -p 80:80 docusaurus-app

Single-page application routing

Docusaurus generates static files, but client-side routing needs proper fallback handling. The try_files directive in the NGINX config above redirects all unknown paths to 404.html.

For custom 404 pages or SPA-style fallback routing, ensure your NGINX config includes:

error_page 404 /404.html;
location = /404.html {
    internal;
}

Now your Docusaurus site is live and served by NGINX.