From f65053c1c6d15a8a7867a5363484656a6ba766f1 Mon Sep 17 00:00:00 2001
From: Florian Sattler <65666934+florian-sattler@users.noreply.github.com>
Date: Wed, 10 Apr 2024 05:39:34 +0200
Subject: [PATCH] docs: added nginx deployment documentation (#3770)

closes #3235
---
 docs/guide/deploy.md | 44 ++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 44 insertions(+)

diff --git a/docs/guide/deploy.md b/docs/guide/deploy.md
index 471e785891d5..01eeafd31442 100644
--- a/docs/guide/deploy.md
+++ b/docs/guide/deploy.md
@@ -291,3 +291,47 @@ You can deploy your Vitepress website on [Kinsta](https://kinsta.com/static-site
 ### Stormkit
 
 You can deploy your VitePress project to [Stormkit](https://www.stormkit.io) by following these [instructions](https://stormkit.io/blog/how-to-deploy-vitepress).
+
+### Nginx
+
+Here is a example of an Nginx server block configuration. This setup includes gzip compression for common text-based assets, rules for serving your VitePress site's static files with proper caching headers as well as handling `cleanUrls: true`.
+
+```nginx
+server {
+    gzip on;
+    gzip_types text/plain text/css application/json application/javascript text/xml application/xml application/xml+rss text/javascript;
+
+    listen 80;
+    server_name _;
+    index index.html;
+
+    location / {
+        # content location
+        root /app;
+
+        # exact matches -> reverse clean urls -> folders -> not found
+        try_files $uri $uri.html $uri/ =404;
+
+        # non existent pages
+        error_page 404 /404.html;
+
+        # a folder without index.html raises 403 in this setup
+        error_page 403 /404.html;
+
+        # adjust caching headers
+        # files in the assets folder have hashes filenames
+        location ~* ^/assets/ {
+            expires 1y;
+            add_header Cache-Control "public, immutable";
+        }
+    }
+}
+```
+
+This configuration assumes that your built VitePress site is located in the `/app` directory on your server. Adjust the `root` directive accordingly if your site's files are located elsewhere.
+
+::: warning Do not default to index.html
+The try_files resolution must not default to index.html like in other Vue applications. This would result in an invalid page state.
+:::
+
+Further information can be found in the [official nginx documentation](https://nginx.org/en/docs/), in these issues [#2837](https://github.com/vuejs/vitepress/discussions/2837), [#3235](https://github.com/vuejs/vitepress/issues/3235) as well as in this [blog post](https://blog.mehdi.cc/articles/vitepress-cleanurls-on-nginx-environment#readings) by Mehdi Merah.