diff --git a/website/docs/deployment/nginx.mdx b/website/docs/deployment/nginx.mdx new file mode 100644 index 000000000000..8d06aae0b2d6 --- /dev/null +++ b/website/docs/deployment/nginx.mdx @@ -0,0 +1,88 @@ +--- +sidebar_label: NGINX +description: Deploy your Docusaurus app on an NGINX server. +--- + +# Deploying to NGINX + +Deploying your Docusaurus project to [NGINX](https://nginx.org/) gives you full control over your hosting environment and is a great choice for production deployments. + +## Build your site + +```bash +npm run build +``` + +This generates static files in the `build/` directory. + +## Basic NGINX configuration + +Create an NGINX server block configuration file: + +```nginx title="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 title="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: + +```bash +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: + +```nginx +error_page 404 /404.html; +location = /404.html { + internal; +} +``` + +Now your Docusaurus site is live and served by NGINX. diff --git a/website/sidebars.ts b/website/sidebars.ts index ee8ae9d46a2b..93eba48f968c 100644 --- a/website/sidebars.ts +++ b/website/sidebars.ts @@ -100,6 +100,7 @@ const sidebars: SidebarsConfig = { 'deployment/github-pages', 'deployment/netlify', 'deployment/vercel', + 'deployment/nginx', ], }, {