From 98db267f61c41d52b11b1e863fe1c47072c91cba Mon Sep 17 00:00:00 2001
From: Ryan McCue <me@ryanmccue.info>
Date: Tue, 31 May 2022 13:55:37 +0100
Subject: [PATCH] Add more details and examples to nginx config

---
 docs/nginx-configuration.md | 41 ++++++++++++++++++++++++++++++++++---
 1 file changed, 38 insertions(+), 3 deletions(-)

diff --git a/docs/nginx-configuration.md b/docs/nginx-configuration.md
index fb3bce92..2b635cd9 100644
--- a/docs/nginx-configuration.md
+++ b/docs/nginx-configuration.md
@@ -4,6 +4,8 @@ Altis Cloud uses Nginx within your [web containers](./architecture.md). For adva
 
 **Note:** Custom configuration will only apply to traffic served by the web container, which does not include media or tachyon (see the [architecture diagram for more information](./architecture.md)). Specifically, any URLs beginning with `/uploads/` or `/tachyon/` are routed directly to [S3](./s3-storage.md) and [Tachyon](docs://media/dynamic-images.md) directly.
 
+**Important:** Nginx configuration is a powerful low-level tool, and incorrect configuration may prohibit access to your site. Ensure that any configuration changes are carefully tested on local and pre-production environments. Altis is not responsible for downtime resulting from misconfiguration of nginx.
+
 
 ## Server Configuration
 
@@ -45,9 +47,9 @@ http {
 
 ## Examples
 
-Developers can use this advanced configuration to do complex redirect, rewrites or other server-level routing.
+### Redirection
 
-For example, if you want to redirect a specific domain to a new domain and for some reason not able to do this at the PHP / application layer:
+If you want to redirect a specific domain to a new domain and for some reason not able to do this at the PHP / application layer:
 
 `.config/nginx-additions.conf`
 
@@ -57,7 +59,10 @@ if ( $host = "example.com" ) {
 }
 ```
 
-Alternatively, if you have one or more local files in your repository you wish to explicitly block from being publicly accessed you may manually configure a 404 for a specific resource or filename pattern:
+
+### Block access to files
+
+If you have one or more local files in your repository you wish to explicitly block from being publicly accessed you may manually configure a 404 for a specific resource or filename pattern:
 
 ```
 # Block access to any file entitled `config.local.yaml`.
@@ -66,3 +71,33 @@ location ~* config.local.yaml {
     return 404;
 }
 ```
+
+
+### Limit access based on IP address
+
+Access to certain URLs can be limited based on IP address, using the `allow` and `deny` directives.
+
+Any URLs limited through this manner **must not** be set as cacheable, otherwise the response will be cached at the CDN layer. If this behaviour is desired, limitations must be made at the firewall layer instead; contact support for further details.
+
+Additionally, be careful to ensure internal systems and loopback (localhost) requests are permitted to access these URLs, as this may cause problems with functionality or may cause your site to be marked as unhealthy.
+
+```
+# Block access to /internal/ to known subnets
+location /internal/ {
+    # Allow known subnets.
+    allow 152.37.71.106;
+    allow 8.8.8.8/16;
+
+    # Allow internal Altis systems.
+    allow 172.16.0.0/12;
+
+    # Deny access to all others.
+    deny all;
+
+    # Mark as uncacheable.
+    add_header Cache-Control 'no-store, no-cache';
+
+    # Route as per usual.
+    try_files $uri $uri/ /index.php?$args;
+}
+```