Apache & Nginx - Revision history

Wikisailor: /* The Core Directive: proxy_intercept_errors on; */

2026-02-28T17:08:47Z

The Core Directive: proxy_intercept_errors on;

← Older revision		Revision as of 17:08, 28 February 2026
Line 567:		Line 567:
	The purpose of this section is to detail the implementation of a professional error-handling layer within our Nginx gateway. In our current multi-server environment, we face a recurring aesthetic and security challenge: the "Leaked Error." When a backend server like Plum or Quince encounters an issue—whether it is a 404 Not Found, a 500 Internal Server Error, or a total system collapse resulting in a 502 Bad Gateway—the default behavior of Nginx is to simply pass that raw error page through to the visitor. This not only looks unprofessional, as it often displays raw Apache or PHP branding, but it also leaks information about our backend infrastructure. By utilizing the proxy_intercept_errors directive, we gain the ability to intercept these failures at the gateway and substitute them with our own branded, unified "Sea of Fate" maintenance and error pages.		The purpose of this section is to detail the implementation of a professional error-handling layer within our Nginx gateway. In our current multi-server environment, we face a recurring aesthetic and security challenge: the "Leaked Error." When a backend server like Plum or Quince encounters an issue—whether it is a 404 Not Found, a 500 Internal Server Error, or a total system collapse resulting in a 502 Bad Gateway—the default behavior of Nginx is to simply pass that raw error page through to the visitor. This not only looks unprofessional, as it often displays raw Apache or PHP branding, but it also leaks information about our backend infrastructure. By utilizing the proxy_intercept_errors directive, we gain the ability to intercept these failures at the gateway and substitute them with our own branded, unified "Sea of Fate" maintenance and error pages.

	===The Core Directive: proxy_intercept_errors on;===		==The Core Directive: proxy_intercept_errors on;==

	By default, Nginx acts as a transparent window. If Plum returns a "404 Not Found," Nginx assumes the backend has already handled the situation and passes that 404 page directly to our browser. However, when we enable proxy_intercept_errors on;, we are telling Nginx to monitor the HTTP status codes coming back from the proxy. If the status code is 300 or higher (typically focusing on the 4xx and 5xx ranges), Nginx stops the transmission of the backend's response. Instead, it looks for a local instruction—the error_page directive—to determine what to show the user instead.		By default, Nginx acts as a transparent window. If Plum returns a "404 Not Found," Nginx assumes the backend has already handled the situation and passes that 404 page directly to our browser. However, when we enable proxy_intercept_errors on;, we are telling Nginx to monitor the HTTP status codes coming back from the proxy. If the status code is 300 or higher (typically focusing on the 4xx and 5xx ranges), Nginx stops the transmission of the backend's response. Instead, it looks for a local instruction—the error_page directive—to determine what to show the user instead.

Wikisailor: /* The "Ghost Backend" Fix: Mastering proxy_intercept_errors and Custom Error Handling */

2026-02-28T17:06:58Z

The "Ghost Backend" Fix: Mastering proxy_intercept_errors and Custom Error Handling

← Older revision		Revision as of 17:06, 28 February 2026
Line 586:		Line 586:
	When we "include" this file inside the http { ... } block of our main configuration, Nginx treats the contents of that file as if they were written directly into the master config. Because the http block is the parent of all server blocks, any directive placed here is inherited by every website we host. This means that if we ever want to change our maintenance message or add a new error code to catch (like a 403 Forbidden), we only have to edit one file and reload Nginx once to update our entire digital frontier.		When we "include" this file inside the http { ... } block of our main configuration, Nginx treats the contents of that file as if they were written directly into the master config. Because the http block is the parent of all server blocks, any directive placed here is inherited by every website we host. This means that if we ever want to change our maintenance message or add a new error code to catch (like a 403 Forbidden), we only have to edit one file and reload Nginx once to update our entire digital frontier.

	Step 1: Creating Our Custom Error Include File		===Step 1: Creating Our Custom Error Include File===

	First, we create the configuration file that will hold our interception logic. We will place this in the conf.d directory, as Nginx is typically configured to load all .conf files from this location automatically, but we will explicitly include it to ensure total control.		First, we create the configuration file that will hold our interception logic. We will place this in the conf.d directory, as Nginx is typically configured to load all .conf files from this location automatically, but we will explicitly include it to ensure total control.
	sudo nano /etc/nginx/conf.d/global-errors.conf		sudo nano /etc/nginx/conf.d/global-errors.conf
Line 629:		Line 630:
	internal;		internal;
	}</nowiki>		}</nowiki>
	Step 2: Integrating the Include into nginx.conf
			===Step 2: Integrating the Include into nginx.conf===

	Now, we must ensure our master configuration file is aware of this new logic. We open /etc/nginx/nginx.conf and look for the http { ... } block. We place our include directive inside this block, usually near the end of the section but before the closing brace.		Now, we must ensure our master configuration file is aware of this new logic. We open /etc/nginx/nginx.conf and look for the http { ... } block. We place our include directive inside this block, usually near the end of the section but before the closing brace.
	sudo nano /etc/nginx/nginx.conf		sudo nano /etc/nginx/nginx.conf
Line 650:		Line 653:
	include /etc/nginx/sites-enabled/*;		include /etc/nginx/sites-enabled/*;
	}</nowiki>		}</nowiki>
	Step 3: Creating the Physical Error Pages
			===Step 3: Creating the Physical Error Pages===

	For this to function, we must create the corresponding HTML files on the gateway filesystem. We organize these in /var/www/html/errors/ to keep them separate from our primary application data.		For this to function, we must create the corresponding HTML files on the gateway filesystem. We organize these in /var/www/html/errors/ to keep them separate from our primary application data.
	* seaoffate-maintenance.html: Provides a helpful message stating the backend (Plum, Quince, etc.) is undergoing work.		* seaoffate-maintenance.html: Provides a helpful message stating the backend (Plum, Quince, etc.) is undergoing work.
Line 658:		Line 663:
	===The Result: Inheritance and Defense in Depth===		===The Result: Inheritance and Defense in Depth===
	By structuring our configuration this way, we achieve a powerful "Waterfall" effect. When a request comes in for jellyfin.seaoffate.net and the Quince server happens to be rebooting, the following logic occurs:		By structuring our configuration this way, we achieve a powerful "Waterfall" effect. When a request comes in for jellyfin.seaoffate.net and the Quince server happens to be rebooting, the following logic occurs:

	# The server block for Jellyfin handles the request.		# The server block for Jellyfin handles the request.
	# The request is proxied to 192.168.100.75.		# The request is proxied to 192.168.100.75.

Wikisailor: /* The "Ghost Backend" Fix: Mastering proxy_intercept_errors and Custom Error Handling */

2026-02-28T17:05:39Z

The "Ghost Backend" Fix: Mastering proxy_intercept_errors and Custom Error Handling

← Older revision		Revision as of 17:05, 28 February 2026
Line 564:		Line 564:

	==The "Ghost Backend" Fix: Mastering proxy_intercept_errors and Custom Error Handling==		==The "Ghost Backend" Fix: Mastering proxy_intercept_errors and Custom Error Handling==

	The purpose of this section is to detail the implementation of a professional error-handling layer within our Nginx gateway. In our current multi-server environment, we face a recurring aesthetic and security challenge: the "Leaked Error." When a backend server like Plum or Quince encounters an issue—whether it is a 404 Not Found, a 500 Internal Server Error, or a total system collapse resulting in a 502 Bad Gateway—the default behavior of Nginx is to simply pass that raw error page through to the visitor. This not only looks unprofessional, as it often displays raw Apache or PHP branding, but it also leaks information about our backend infrastructure. By utilizing the proxy_intercept_errors directive, we gain the ability to intercept these failures at the gateway and substitute them with our own branded, unified "Sea of Fate" maintenance and error pages.		The purpose of this section is to detail the implementation of a professional error-handling layer within our Nginx gateway. In our current multi-server environment, we face a recurring aesthetic and security challenge: the "Leaked Error." When a backend server like Plum or Quince encounters an issue—whether it is a 404 Not Found, a 500 Internal Server Error, or a total system collapse resulting in a 502 Bad Gateway—the default behavior of Nginx is to simply pass that raw error page through to the visitor. This not only looks unprofessional, as it often displays raw Apache or PHP branding, but it also leaks information about our backend infrastructure. By utilizing the proxy_intercept_errors directive, we gain the ability to intercept these failures at the gateway and substitute them with our own branded, unified "Sea of Fate" maintenance and error pages.

	===The Core Directive: proxy_intercept_errors on;===		===The Core Directive: proxy_intercept_errors on;===

	By default, Nginx acts as a transparent window. If Plum returns a "404 Not Found," Nginx assumes the backend has already handled the situation and passes that 404 page directly to our browser. However, when we enable proxy_intercept_errors on;, we are telling Nginx to monitor the HTTP status codes coming back from the proxy. If the status code is 300 or higher (typically focusing on the 4xx and 5xx ranges), Nginx stops the transmission of the backend's response. Instead, it looks for a local instruction—the error_page directive—to determine what to show the user instead.		By default, Nginx acts as a transparent window. If Plum returns a "404 Not Found," Nginx assumes the backend has already handled the situation and passes that 404 page directly to our browser. However, when we enable proxy_intercept_errors on;, we are telling Nginx to monitor the HTTP status codes coming back from the proxy. If the status code is 300 or higher (typically focusing on the 4xx and 5xx ranges), Nginx stops the transmission of the backend's response. Instead, it looks for a local instruction—the error_page directive—to determine what to show the user instead.

Line 572:		Line 574:

	===Defining Custom Error Pages: Global vs. Per-Domain===		===Defining Custom Error Pages: Global vs. Per-Domain===

	One of the most frequent questions we encounter in our documentation is whether we must define these error pages for every single subdomain (like notes, jellyfin, and n8n) or if we can set them once and forget them. The answer lies in the hierarchy of the Nginx configuration.		One of the most frequent questions we encounter in our documentation is whether we must define these error pages for every single subdomain (like notes, jellyfin, and n8n) or if we can set them once and forget them. The answer lies in the hierarchy of the Nginx configuration.

	===The Global Approach: Standardizing Our Infrastructure via Nginx Includes===		===The Global Approach: Standardizing Our Infrastructure via Nginx Includes===

	The purpose of this section is to detail the most efficient method for implementing a universal "Maintenance and Error" strategy across our entire network. As our infrastructure grows to include multiple backend servers like Plum, Blackberry, and Quince, we must avoid the administrative burden of repeating the same error-handling code in every individual site configuration. Instead, we utilize the power of the Nginx include directive within our global http block. This allows us to define our "Sea of Fate" branding and error-interception logic in one central file, which is then automatically inherited by every subdomain under the *.seaoffate.net umbrella. This "Single Source of Truth" approach ensures that whether a visitor is trying to reach our notes, our media, or our automation tools, they receive a consistent and professional response if a backend service goes offline.		The purpose of this section is to detail the most efficient method for implementing a universal "Maintenance and Error" strategy across our entire network. As our infrastructure grows to include multiple backend servers like Plum, Blackberry, and Quince, we must avoid the administrative burden of repeating the same error-handling code in every individual site configuration. Instead, we utilize the power of the Nginx include directive within our global http block. This allows us to define our "Sea of Fate" branding and error-interception logic in one central file, which is then automatically inherited by every subdomain under the *.seaoffate.net umbrella. This "Single Source of Truth" approach ensures that whether a visitor is trying to reach our notes, our media, or our automation tools, they receive a consistent and professional response if a backend service goes offline.

Wikisailor: /* The Per-Domain Approach (Specific Branding) */

2026-02-28T17:02:57Z

The Per-Domain Approach (Specific Branding)

Show changes

Wikisailor: /* Summary Table: Advanced Directives for Our Infrastructure */

2026-02-28T16:37:17Z

Summary Table: Advanced Directives for Our Infrastructure

← Older revision		Revision as of 16:37, 28 February 2026
Line 896:		Line 896:
	\|proxy_redirect \|\| default; \|\| Corrects broken redirects that point to internal IPs.		\|proxy_redirect \|\| default; \|\| Corrects broken redirects that point to internal IPs.
	\|-		\|-
	\|RemoteIPInternalProxy \|\|192.168.100.XX Fixes logging; shows real IPs on Fig/Plum.		\|RemoteIPInternalProxy \|\|192.168.100.XX\|\| Fixes logging; shows real IPs on Fig/Plum.
	\|-		\|-
	\|proxy_request_buffering\|\|off; \|\|Allows massive Nextcloud uploads without gateway lag.		\|proxy_request_buffering\|\|off; \|\|Allows massive Nextcloud uploads without gateway lag.
	\|-		\|-
	\|\|\| 0; \|\|Protects the gateway SSD from being filled by temp files.		\|proxy_max_temp_file_size \|\| 0; \|\|Protects the gateway SSD from being filled by temp files.
	\|-		\|-
	\|keepalive \|\|32; \|\|(In Upstream block) Keeps internal links "hot" for speed.		\|keepalive \|\|32; \|\|(In Upstream block) Keeps internal links "hot" for speed.

Wikisailor: /* Summary Table: Advanced Directives for Our Infrastructure */

2026-02-28T16:36:34Z

Summary Table: Advanced Directives for Our Infrastructure

← Older revision		Revision as of 16:36, 28 February 2026
Line 898:		Line 898:
	\|RemoteIPInternalProxy \|\|192.168.100.XX Fixes logging; shows real IPs on Fig/Plum.		\|RemoteIPInternalProxy \|\|192.168.100.XX Fixes logging; shows real IPs on Fig/Plum.
	\|-		\|-
	\|proxy_request_buffering\|\|off; Allows massive Nextcloud uploads without gateway lag.		\|proxy_request_buffering\|\|off; \|\|Allows massive Nextcloud uploads without gateway lag.
	\|-		\|-
	\|\|\| 0; Protects the gateway SSD from being filled by temp files.		\|\|\| 0; \|\|Protects the gateway SSD from being filled by temp files.
	\|-		\|-
	\|keepalive \|\|32; \|\|(In Upstream block) Keeps internal links "hot" for speed.		\|keepalive \|\|32; \|\|(In Upstream block) Keeps internal links "hot" for speed.

Wikisailor: /* Summary Table: Advanced Directives for Our Infrastructure */

2026-02-28T16:36:04Z

Summary Table: Advanced Directives for Our Infrastructure

@@ Line 895: / Line 895: @@
 |-
 |proxy_redirect		|| default;	|| 	Corrects broken redirects that point to internal IPs.
 |}
 ==Orchestrating the Digital Frontier: A Unified Guide to Advanced Proxy Directives==

Wikisailor: /* The "Domain Mirror": proxy_redirect */

2026-02-28T16:25:43Z

The "Domain Mirror": proxy_redirect

@@ Line 859: / Line 859: @@
       # proxy_redirect http://192.168.100.22/ https://notes.seaoffate.net/;
   }</nowiki>
 ===Summary Table: Advanced Directives for Our Infrastructure===

Wikisailor: /* The Apache Proxy Trust: RemoteIPInternalProxy */

2026-02-28T16:24:23Z

The Apache Proxy Trust: RemoteIPInternalProxy

@@ Line 720: / Line 720: @@
   client_header_timeout 10s;
 we tell Nginx: "If a user starts sending a request but doesn't send the next piece within 10 seconds, drop them." Real users on a normal connection will never hit this, but it prevents bots from "clogging the pipes" of our gateway.
 ===The "Nextcloud Set": Managing Massive Data Streams===

Wikisailor: /* The "Nextcloud Set": Managing Massive Data Streams */

2026-02-28T16:22:54Z

The "Nextcloud Set": Managing Massive Data Streams

@@ Line 720: / Line 720: @@
   client_header_timeout 10s;
 we tell Nginx: "If a user starts sending a request but doesn't send the next piece within 10 seconds, drop them." Real users on a normal connection will never hit this, but it prevents bots from "clogging the pipes" of our gateway.
 ===The "Nextcloud Set": Managing Massive Data Streams===