Skip to content

ServerKit is a lightweight, modern server control panel for managing web applications, databases, and services on your VPS or dedicated server. Built with Python/Flask backend and React frontend.

refactor: separate nginx configuration rendering from host operations

Juan Denis69a9ad345a43
diff --git a/backend/app/services/nginx/__init__.py b/backend/app/services/nginx/__init__.py
new file mode 100644
index 00000000..974811e5
--- /dev/null
+++ b/backend/app/services/nginx/__init__.py
@@ -0,0 +1 @@
+"""Nginx configuration generation, independent of host operations."""
diff --git a/backend/app/services/nginx/compression.py b/backend/app/services/nginx/compression.py
new file mode 100644
index 00000000..76470516
--- /dev/null
+++ b/backend/app/services/nginx/compression.py
@@ -0,0 +1,63 @@
+"""Render compression directives from supplied nginx dump/version text."""
+import re
+
+from . import templates
+
+
+def _http_level_directives(dump: str, skip_file: str) -> set:
+ """Directive names set at http level in an ``nginx -T`` dump.
+
+ ``nginx -T`` prints each file after a ``# configuration file <path>:``
+ header. In the main nginx.conf, http level is depth 1 inside
+ ``http {}``; every other file is included from the http block (conf.d)
+ or a server (sites), so its depth-0 directives are the http-level
+ ones. ``skip_file`` (our own snippet) is ignored so a rewrite never
+ mistakes its own lines for someone else's.
+ """
+ found = set()
+ current = None
+ depth = 0
+ in_http = False
+ for raw in dump.splitlines():
+ header = re.match(r'^# configuration file (.+):$', raw.strip())
+ if header:
+ current = header.group(1)
+ depth = 0
+ in_http = False
+ continue
+ if current is None or current == skip_file:
+ continue
+ line = raw.split('#', 1)[0].strip()
+ if not line:
+ continue
+ is_main = current.endswith('/nginx.conf')
+ http_level = (depth == 1 and in_http) if is_main else depth == 0
+ name = line.split(None, 1)[0].rstrip(';{')
+ if http_level and line.endswith(';'):
+ found.add(name)
+ if is_main and depth == 0 and name == 'http' and '{' in line:
+ in_http = True
+ depth += line.count('{') - line.count('}')
+ if is_main and depth == 0:
+ in_http = False
+ return found
+
+
+def render_compression_snippet(dump: str, conf_path: str,
+ nginx_v: str = '', *, gzip_directives=templates.GZIP_DIRECTIVES, brotli_directives=templates.BROTLI_DIRECTIVES) -> str:
+ """The snippet for this box. When the running config already sets
+ everything it is comments only: still written, so the "already
+ handled" check stays a file-exists test instead of an ``nginx -T``
+ on every vhost write."""
+ present = _http_level_directives(dump, conf_path)
+ brotli = ('ngx_http_brotli_filter_module' in dump
+ or 'brotli' in (nginx_v or '').lower())
+ wanted = list(gzip_directives)
+ if brotli:
+ wanted += list(brotli_directives)
+ lines = [f'{name} {value};' for name, value in wanted if name not in present]
+ kept = sorted(name for name, _ in wanted if name in present)
+ header = ['# ServerKit compression (auto-generated; do not edit).']
+ if kept:
+ header.append('# Already set elsewhere, left alone: ' + ', '.join(kept))
+ return '\n'.join(header + lines) + '\n'
diff --git a/backend/app/services/nginx/rendering.py b/backend/app/services/nginx/rendering.py
new file mode 100644
index 00000000..5c131889
--- /dev/null
+++ b/backend/app/services/nginx/rendering.py
@@ -0,0 +1,221 @@
+"""Pure vhost rendering. Inputs are values; output is text or a validation error."""
+import re
+from dataclasses import dataclass
+from typing import Dict, List, Optional
+
+from . import templates
+from .validation import _validate_domain, _validate_path
+
+
+@dataclass(frozen=True)
+class RenderSettings:
+ """Template values, isolated from the service's filesystem/process methods."""
+ DOCKER_SITE_TEMPLATE: str = templates.DOCKER_SITE_TEMPLATE
+ IMMUTABLE_ASSET_HEADERS: str = templates.IMMUTABLE_ASSET_HEADERS
+ IMMUTABLE_ASSET_PATTERN: str = templates.IMMUTABLE_ASSET_PATTERN
+ MICROCACHE_FASTCGI_BLOCK: str = templates.MICROCACHE_FASTCGI_BLOCK
+ MICROCACHE_PROXY_BLOCK: str = templates.MICROCACHE_PROXY_BLOCK
+ MICROCACHE_SKIP_BLOCK: str = templates.MICROCACHE_SKIP_BLOCK
+ MICROCACHE_TTL_DEFAULT: int = templates.MICROCACHE_TTL_DEFAULT
+ MICROCACHE_TTL_MAX: int = templates.MICROCACHE_TTL_MAX
+ PHP_SITE_TEMPLATE: str = templates.PHP_SITE_TEMPLATE
+ PYTHON_SITE_TEMPLATE: str = templates.PYTHON_SITE_TEMPLATE
+ REMOTE_UPSTREAM_TEMPLATE: str = templates.REMOTE_UPSTREAM_TEMPLATE
+ SSL_BLOCK: str = templates.SSL_BLOCK
+ SSL_REDIRECT_TEMPLATE: str = templates.SSL_REDIRECT_TEMPLATE
+ STATIC_SITE_TEMPLATE: str = templates.STATIC_SITE_TEMPLATE
+ WORDPRESS_PROTECTION_BLOCK: str = templates.WORDPRESS_PROTECTION_BLOCK
+
+
+DEFAULT_SETTINGS = RenderSettings()
+
+
+def render_site_config(name: str, app_type: str, domains: List[str],
+ root_path: str = None, port: int = None,
+ php_version: str = '8.2',
+ ssl_cert: str = None, ssl_key: str = None,
+ upstream: str = None,
+ micro_cache: bool = False,
+ micro_cache_ttl: Optional[int] = None,
+ immutable_assets: bool = False,
+ wordpress_protection: bool = False, *,
+ settings: RenderSettings = DEFAULT_SETTINGS) -> Dict:
+ """Render the vhost config for a site to a string — no side effects.
+
+ This is the exact template pipeline :meth:`create_site` writes to disk;
+ it is exposed separately so callers (e.g. drift detection) can compute
+ the expected on-disk content without touching the filesystem.
+ Returns ``{'success': True, 'config': str}`` or
+ ``{'success': False, 'error': msg}``.
+ """
+ if not domains:
+ return {'success': False, 'error': 'At least one domain is required'}
+
+ # Validate all domains
+ for domain in domains:
+ if domain == '_':
+ return {'success': False, 'error': 'Wildcard server_name "_" is reserved for the ServerKit panel'}
+ if not _validate_domain(domain):
+ return {'success': False, 'error': f'Invalid domain name: {domain}'}
+
+ # Validate root_path if provided
+ if root_path and not _validate_path(root_path):
+ return {'success': False, 'error': f'Invalid root path: {root_path}'}
+
+ domains_str = ' '.join(domains)
+
+ # Select template based on app type
+ if app_type in ['php', 'wordpress']:
+ config = settings.PHP_SITE_TEMPLATE.format(
+ name=name,
+ domains=domains_str,
+ root_path=root_path,
+ php_version=php_version
+ )
+ elif app_type in ['flask', 'django', 'python']:
+ if not port:
+ return {'success': False, 'error': 'Python services need a port'}
+ config = settings.PYTHON_SITE_TEMPLATE.format(
+ name=name,
+ domains=domains_str,
+ root_path=root_path,
+ port=port
+ )
+ elif app_type == 'docker':
+ if not port:
+ return {'success': False, 'error': 'Docker services need a port'}
+ config = settings.DOCKER_SITE_TEMPLATE.format(
+ name=name,
+ domains=domains_str,
+ port=port
+ )
+ elif app_type == 'remote':
+ if not upstream:
+ return {'success': False, 'error': 'Services on remote servers need an upstream (host:port)'}
+ config = settings.REMOTE_UPSTREAM_TEMPLATE.format(
+ name=name,
+ domains=domains_str,
+ upstream=upstream,
+ )
+ elif app_type == 'static':
+ config = settings.STATIC_SITE_TEMPLATE.format(
+ name=name,
+ domains=domains_str,
+ root_path=root_path
+ )
+ else:
+ return {'success': False, 'error': f'Unknown service type: {app_type}'}
+
+ if immutable_assets:
+ config = _with_immutable_assets(config, app_type, settings=settings)
+
+ if micro_cache:
+ # Inject before the SSL wrap so the redirect server block (which
+ # also carries a server_name line) never receives cache directives.
+ config = _with_micro_cache(config, app_type, micro_cache_ttl, settings=settings)
+
+ if wordpress_protection:
+ if app_type != 'docker' or not port:
+ return {
+ 'success': False,
+ 'error': 'WordPress protection requires a Docker proxy port',
+ }
+ config = _with_wordpress_protection(config, port, settings=settings)
+
+ if ssl_cert and ssl_key:
+ config = _with_ssl(config, domains_str, ssl_cert, ssl_key, settings=settings)
+
+ return {'success': True, 'config': config}
+
+
+def _with_wordpress_protection(config: str, port: int, *,
+ settings: RenderSettings = DEFAULT_SETTINGS) -> str:
+ """Add exact-match throttling locations before the catch-all proxy."""
+ anchor = ' location / {\n'
+ if anchor not in config:
+ return config
+ block = settings.WORDPRESS_PROTECTION_BLOCK.format(port=port)
+ return config.replace(anchor, block + anchor, 1)
+
+
+def _with_immutable_assets(config: str, app_type: str, *,
+ settings: RenderSettings = DEFAULT_SETTINGS) -> str:
+ """Add a regex location for fingerprinted assets to a proxied vhost:
+ the same proxying as ``location /`` plus a one-year immutable cache.
+ Appended after ``location /`` (a matching regex location wins over the
+ ``/`` prefix wherever it sits) so the micro-cache injection still
+ anchors on the real ``location /``."""
+ if (app_type or '').lower() not in ('flask', 'django', 'python', 'docker', 'remote'):
+ return config
+ match = re.search(r'^ location / \{\n(.*?)^ \}\n', config, re.MULTILINE | re.DOTALL)
+ if not match:
+ return config
+ block = ('\n # ServerKit: fingerprinted assets never change\n'
+ f' location ~* "{settings.IMMUTABLE_ASSET_PATTERN}" {{\n'
+ + match.group(1) + settings.IMMUTABLE_ASSET_HEADERS + ' }\n')
+ return config[:match.end()] + block + config[match.end():]
+
+
+def _with_micro_cache(config: str, app_type: str,
+ ttl: Optional[int] = None, *,
+ settings: RenderSettings = DEFAULT_SETTINGS) -> str:
+ """Inject the shared-zone micro-cache directives into a rendered vhost.
+
+ fastcgi_cache for PHP-FPM-served sites, proxy_cache for reverse-proxied
+ ones; static sites are a no-op (files already come straight off disk).
+ Scheme-agnostic — nothing here depends on HTTP vs HTTPS. The referenced
+ zones are declared once in conf.d by :meth:`ensure_cache_zone`.
+ """
+ t = (app_type or '').lower()
+ ttl = clamp_micro_cache_ttl(ttl, settings=settings)
+ if t in ('php', 'wordpress'):
+ anchor = ' include fastcgi_params;\n'
+ if anchor not in config:
+ return config
+ config = config.replace(
+ anchor, anchor + settings.MICROCACHE_FASTCGI_BLOCK.format(ttl=ttl), 1)
+ elif t in ('flask', 'django', 'python', 'docker', 'remote'):
+ # proxy_cache_bypass may only be declared once per location, so
+ # fold $sk_skip_cache into the template's existing $http_upgrade
+ # bypass instead of adding a duplicate directive.
+ anchor = ' proxy_cache_bypass $http_upgrade;\n'
+ if anchor not in config:
+ return config
+ config = config.replace(
+ anchor,
+ ' proxy_cache_bypass $sk_skip_cache $http_upgrade;\n'
+ + settings.MICROCACHE_PROXY_BLOCK.format(ttl=ttl),
+ 1,
+ )
+ else:
+ return config
+
+ # Server-level $sk_skip_cache logic, right after server_name.
+ match = re.search(r'^( server_name [^;]+;\n)', config, re.MULTILINE)
+ if match:
+ config = config.replace(
+ match.group(1), match.group(1) + '\n' + settings.MICROCACHE_SKIP_BLOCK, 1)
+ return config
+
+
+def clamp_micro_cache_ttl(ttl, *, settings: RenderSettings = DEFAULT_SETTINGS) -> int:
+ """A stored TTL as the seconds the vhost uses: unset → the 10s
+ default, anything else clamped to 1..MICROCACHE_TTL_MAX."""
+ if ttl in (None, ''):
+ return settings.MICROCACHE_TTL_DEFAULT
+ return max(1, min(int(ttl), settings.MICROCACHE_TTL_MAX))
+
+
+def _with_ssl(http_config: str, domains: str, ssl_cert: str, ssl_key: str, *,
+ settings: RenderSettings = DEFAULT_SETTINGS) -> str:
+ """Turn an HTTP server block into HTTPS: swap the :80 listens for the TLS
+ block (so the existing server serves 443) and prepend an HTTP->HTTPS
+ redirect. Idempotent because create_site regenerates the whole file."""
+ ssl_block = settings.SSL_BLOCK.format(ssl_cert=ssl_cert, ssl_key=ssl_key)
+ https_config = http_config.replace(
+ ' listen 80;\n listen [::]:80;',
+ ssl_block.strip('\n'),
+ 1,
+ )
+ redirect = settings.SSL_REDIRECT_TEMPLATE.format(domains=domains)
+ return redirect + '\n' + https_config
diff --git a/backend/app/services/nginx/templates.py b/backend/app/services/nginx/templates.py
new file mode 100644
index 00000000..e60ec4de
--- /dev/null
+++ b/backend/app/services/nginx/templates.py
@@ -0,0 +1,452 @@
+"""Configuration text and defaults only; no environment or host access."""
+
+PHP_SITE_TEMPLATE = '''server {{
+ listen 80;
+ listen [::]:80;
+ server_name {domains};
+
+ root {root_path};
+ index index.php index.html index.htm;
+
+ access_log /var/log/nginx/{name}.access.log serverkit_timed;
+ error_log /var/log/nginx/{name}.error.log;
+
+ location / {{
+ try_files $uri $uri/ /index.php?$query_string;
+ }}
+
+ location ~ \\.php$ {{
+ fastcgi_pass unix:/run/php/php{php_version}-fpm.sock;
+ fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
+ include fastcgi_params;
+ fastcgi_intercept_errors on;
+ fastcgi_buffer_size 16k;
+ fastcgi_buffers 4 16k;
+ }}
+
+ location ~ /\\.ht {{
+ deny all;
+ }}
+
+ location = /favicon.ico {{
+ log_not_found off;
+ access_log off;
+ }}
+
+ location = /robots.txt {{
+ log_not_found off;
+ access_log off;
+ allow all;
+ }}
+
+ location ~* \\.(css|gif|ico|jpeg|jpg|js|png|svg|woff|woff2)$ {{
+ expires 1y;
+ log_not_found off;
+ }}
+}}
+'''
+
+PYTHON_SITE_TEMPLATE = '''server {{
+ listen 80;
+ listen [::]:80;
+ server_name {domains};
+
+ access_log /var/log/nginx/{name}.access.log serverkit_timed;
+ error_log /var/log/nginx/{name}.error.log;
+
+ location / {{
+ proxy_pass http://127.0.0.1:{port};
+ proxy_http_version 1.1;
+ proxy_set_header Upgrade $http_upgrade;
+ proxy_set_header Connection 'upgrade';
+ proxy_set_header Host $host;
+ proxy_set_header X-Real-IP $remote_addr;
+ proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+ proxy_set_header X-Forwarded-Proto $scheme;
+ proxy_cache_bypass $http_upgrade;
+ proxy_read_timeout 86400;
+ }}
+
+ location /static {{
+ alias {root_path}/static;
+ expires 1y;
+ }}
+}}
+'''
+
+STATIC_SITE_TEMPLATE = '''server {{
+ listen 80;
+ listen [::]:80;
+ server_name {domains};
+
+ root {root_path};
+ index index.html index.htm;
+
+ access_log /var/log/nginx/{name}.access.log serverkit_timed;
+ error_log /var/log/nginx/{name}.error.log;
+
+ location / {{
+ try_files $uri $uri/ =404;
+ }}
+
+ location ~* \\.(css|gif|ico|jpeg|jpg|js|png|svg|woff|woff2)$ {{
+ expires 1y;
+ log_not_found off;
+ }}
+}}
+'''
+
+# Docker reverse proxy template (for containerized apps)
+DOCKER_SITE_TEMPLATE = '''server {{
+ listen 80;
+ listen [::]:80;
+ server_name {domains};
+
+ access_log /var/log/nginx/{name}.access.log serverkit_timed;
+ error_log /var/log/nginx/{name}.error.log;
+
+ location / {{
+ proxy_pass http://127.0.0.1:{port};
+ proxy_http_version 1.1;
+ proxy_set_header Upgrade $http_upgrade;
+ proxy_set_header Connection 'upgrade';
+ proxy_set_header Host $host;
+ proxy_set_header X-Real-IP $remote_addr;
+ proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+ proxy_set_header X-Forwarded-Proto $scheme;
+ proxy_cache_bypass $http_upgrade;
+ proxy_read_timeout 86400;
+ proxy_connect_timeout 60;
+ proxy_send_timeout 60;
+ }}
+}}
+'''
+
+# WordPress authentication endpoints receive a dedicated request limit in
+# published reverse-proxy vhosts. The zones are shared across vhosts, while
+# the key includes server_name so traffic to one site cannot consume
+# another site's allowance.
+WORDPRESS_RATE_LIMIT_CONF_NAME = 'serverkit-wordpress-rate-limit.conf'
+WORDPRESS_RATE_LIMIT_ZONE_SNIPPET = '''# ServerKit WordPress request-limit zones (auto-generated; do not edit).
+limit_req_zone $server_name$binary_remote_addr zone=serverkit_wp_login:10m rate=10r/m;
+limit_req_zone $server_name$binary_remote_addr zone=serverkit_wp_xmlrpc:10m rate=30r/m;
+'''
+
+WORDPRESS_PROTECTION_BLOCK = ''' # ServerKit WordPress brute-force protection
+ location = /wp-login.php {{
+ limit_req zone=serverkit_wp_login burst=10 nodelay;
+ limit_req_status 429;
+ proxy_pass http://127.0.0.1:{port};
+ proxy_http_version 1.1;
+ proxy_set_header Host $host;
+ proxy_set_header X-Real-IP $remote_addr;
+ proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+ proxy_set_header X-Forwarded-Proto $scheme;
+ proxy_read_timeout 86400;
+ proxy_connect_timeout 60;
+ proxy_send_timeout 60;
+ }}
+
+ location = /xmlrpc.php {{
+ limit_req zone=serverkit_wp_xmlrpc burst=20 nodelay;
+ limit_req_status 429;
+ proxy_pass http://127.0.0.1:{port};
+ proxy_http_version 1.1;
+ proxy_set_header Host $host;
+ proxy_set_header X-Real-IP $remote_addr;
+ proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+ proxy_set_header X-Forwarded-Proto $scheme;
+ proxy_read_timeout 86400;
+ proxy_connect_timeout 60;
+ proxy_send_timeout 60;
+ }}
+
+'''
+
+# Reverse proxy to a service reached over a WireGuard tunnel (roadmap
+# #12). The upstream is a peer's WG IP:port; the private agent forwards
+# it to the real service. proxy_buffering off keeps media/streaming
+# (e.g. Jellyfin) responsive.
+REMOTE_UPSTREAM_TEMPLATE = '''server {{
+ listen 80;
+ listen [::]:80;
+ server_name {domains};
+
+ access_log /var/log/nginx/{name}.access.log serverkit_timed;
+ error_log /var/log/nginx/{name}.error.log;
+
+ location / {{
+ proxy_pass http://{upstream};
+ proxy_http_version 1.1;
+ proxy_set_header Upgrade $http_upgrade;
+ proxy_set_header Connection 'upgrade';
+ proxy_set_header Host $host;
+ proxy_set_header X-Real-IP $remote_addr;
+ proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+ proxy_set_header X-Forwarded-Proto $scheme;
+ proxy_cache_bypass $http_upgrade;
+ proxy_buffering off;
+ proxy_read_timeout 86400;
+ proxy_connect_timeout 60;
+ proxy_send_timeout 60;
+ }}
+}}
+'''
+
+SSL_BLOCK = '''
+ listen 443 ssl http2;
+ listen [::]:443 ssl http2;
+
+ ssl_certificate {ssl_cert};
+ ssl_certificate_key {ssl_key};
+ ssl_session_timeout 1d;
+ ssl_session_cache shared:SSL:50m;
+ ssl_session_tickets off;
+
+ ssl_protocols TLSv1.2 TLSv1.3;
+ ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384;
+ ssl_prefer_server_ciphers off;
+ ssl_ecdh_curve X25519:secp384r1;
+
+ # HSTS: 2 years, all subdomains, preload-eligible. Submit the domain at
+ # https://hstspreload.org to get onto the browser preload list (this is what
+ # protects first-time visitors from an initial-request MITM downgrade).
+ add_header Strict-Transport-Security "max-age=63072000; includeSubDomains; preload" always;
+
+ # Baseline response-header hardening. These are safe for reverse-proxied apps;
+ # the CSP is deliberately permissive so it does not break managed apps while
+ # still satisfying "a CSP is present" and blocking cross-origin framing.
+ # Tighten the CSP per-app when the upstream can support a stricter policy.
+ add_header X-Content-Type-Options "nosniff" always;
+ add_header X-Frame-Options "SAMEORIGIN" always;
+ add_header Referrer-Policy "strict-origin-when-cross-origin" always;
+ add_header Content-Security-Policy "default-src 'self' 'unsafe-inline' 'unsafe-eval' data: blob: https:; frame-ancestors 'self'; upgrade-insecure-requests" always;
+'''
+
+SSL_REDIRECT_TEMPLATE = '''server {{
+ listen 80;
+ listen [::]:80;
+ server_name {domains};
+ return 301 https://$server_name$request_uri;
+}}
+'''
+
+# Private URL routing templates
+PRIVATE_URL_CONFIG_NAME = 'serverkit-private-urls'
+GITEA_CONFIG_NAME = 'serverkit-gitea'
+WORDPRESS_CONFIG_NAME = 'serverkit-wordpress'
+
+# Gitea location block for /gitea path (included inside main server block)
+GITEA_LOCATION_TEMPLATE = '''# Gitea at /gitea path
+location /gitea/ {{
+ proxy_pass http://127.0.0.1:{port}/;
+ proxy_http_version 1.1;
+ proxy_set_header Upgrade $http_upgrade;
+ proxy_set_header Connection "upgrade";
+ proxy_set_header Host $host;
+ proxy_set_header X-Real-IP $remote_addr;
+ proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+ proxy_set_header X-Forwarded-Proto $scheme;
+ proxy_set_header X-Forwarded-Host $host;
+ proxy_cache_bypass $http_upgrade;
+ proxy_read_timeout 86400;
+ proxy_connect_timeout 60;
+ proxy_send_timeout 60;
+
+ # Required for Gitea WebSocket connections
+ proxy_buffering off;
+ client_max_body_size 100M;
+}}
+
+# Handle /gitea without trailing slash
+location = /gitea {{
+ return 301 /gitea/;
+}}
+'''
+
+# WordPress location block for /wordpress path (included inside main server block)
+WORDPRESS_LOCATION_TEMPLATE = '''# WordPress at /wordpress path
+location /wordpress/ {{
+ proxy_pass http://127.0.0.1:{port}/;
+ proxy_http_version 1.1;
+ proxy_set_header Host $host;
+ proxy_set_header X-Real-IP $remote_addr;
+ proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+ proxy_set_header X-Forwarded-Proto $scheme;
+ proxy_set_header X-Forwarded-Host $host;
+ proxy_cache_bypass $http_upgrade;
+ proxy_read_timeout 300;
+ proxy_connect_timeout 60;
+ proxy_send_timeout 60;
+
+ # WordPress file uploads
+ client_max_body_size 256M;
+}}
+
+# Handle /wordpress without trailing slash
+location = /wordpress {{
+ return 301 /wordpress/;
+}}
+'''
+
+PRIVATE_URL_LOCATION_TEMPLATE = ''' # Private URL: /p/{slug}
+ location /p/{slug}/ {{
+ proxy_pass http://127.0.0.1:{port}/;
+ proxy_http_version 1.1;
+ proxy_set_header Upgrade $http_upgrade;
+ proxy_set_header Connection 'upgrade';
+ proxy_set_header Host $host;
+ proxy_set_header X-Real-IP $remote_addr;
+ proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+ proxy_set_header X-Forwarded-Proto $scheme;
+ proxy_set_header X-Private-URL {slug};
+ proxy_cache_bypass $http_upgrade;
+ proxy_read_timeout 86400;
+ }}
+
+ # Also handle without trailing slash
+ location = /p/{slug} {{
+ return 301 /p/{slug}/;
+ }}
+'''
+
+# ==================== TIMED ACCESS LOG ====================
+# Every vhost ServerKit writes logs in this format. The combined fields come
+# first, unchanged, so every existing combined-format reader (bandwidth
+# accounting, the fail2ban `^<HOST> -` filters) keeps matching; the timing
+# fields are appended after them. The app id is the log file itself
+# (/var/log/nginx/<app>.access.log) — a per-vhost `set` variable would make
+# `nginx -t` warn on every server block that never sets it.
+TIMED_LOG_FORMAT = 'serverkit_timed'
+TIMED_LOG_CONF_NAME = 'serverkit-log-format.conf'
+TIMED_LOG_FORMAT_SNIPPET = """# ServerKit timed access-log format (auto-generated; do not edit).
+# Combined fields first (compatible with combined parsers), then timing.
+log_format serverkit_timed '$remote_addr - $remote_user [$time_local] "$request" '
+ '$status $body_bytes_sent "$http_referer" "$http_user_agent" '
+ 'rt=$request_time urt="$upstream_response_time" '
+ 'cs=$upstream_cache_status h=$host';
+"""
+
+# ==================== COMPRESSION ====================
+# gzip (and brotli when the module is loaded) for every site, as one
+# http-level conf.d snippet. Stock configs already set some of these —
+# Debian's nginx.conf ships `gzip on;` — and a repeated http-level
+# directive is fatal to `nginx -t`, so the snippet only carries the
+# directives the running config does not already set (read from `nginx -T`).
+COMPRESSION_CONF_NAME = 'serverkit-compression.conf'
+# text/html is always compressed by nginx; listing it again only warns.
+COMPRESSION_TYPES = (
+ 'text/plain text/css text/xml text/javascript application/javascript '
+ 'application/json application/xml application/rss+xml '
+ 'application/atom+xml image/svg+xml application/wasm '
+ 'font/ttf font/otf application/vnd.ms-fontobject'
+)
+GZIP_DIRECTIVES = (
+ ('gzip', 'on'),
+ ('gzip_vary', 'on'),
+ ('gzip_proxied', 'any'),
+ ('gzip_comp_level', '5'),
+ ('gzip_min_length', '1024'),
+ ('gzip_types', COMPRESSION_TYPES),
+)
+BROTLI_DIRECTIVES = (
+ ('brotli', 'on'),
+ ('brotli_comp_level', '5'),
+ ('brotli_min_length', '1024'),
+ ('brotli_types', COMPRESSION_TYPES),
+)
+
+# ==================== IMMUTABLE ASSETS ====================
+# Opt-in, proxied sites only: a fingerprinted asset (a hash in its name)
+# never changes, so the browser may keep it a year. Off by default because
+# the panel cannot know an app's asset layout. The hash must be 8+ chars
+# after a '.' or '-' AND contain a digit, so `app-settings.js` is never
+# pinned; a hash with no digit is simply not long-cached (the safe miss).
+IMMUTABLE_ASSET_PATTERN = (
+ r'[.-](?=[A-Za-z0-9_]*[0-9])[A-Za-z0-9_]{8,}'
+ r'\.(?:js|mjs|css|map|woff2?|ttf|otf|png|jpe?g|gif|svg|webp|avif|ico)$'
+)
+# One Cache-Control header: `expires` would emit its own max-age header
+# next to this one, and clients read either.
+IMMUTABLE_ASSET_HEADERS = ''' add_header Cache-Control "public, max-age=31536000, immutable";
+'''
+
+# ==================== MICRO-CACHE (task #21) ====================
+# Opt-in per-site micro-cache: a very short (10s) full-page cache in front
+# of proxied/PHP sites, with hard bypasses for anything personalized.
+#
+# Design tradeoff — ONE shared zone/path for every opted-in site: nginx
+# cache zones must be declared statically in the http context, so a zone
+# per site does not scale (and can't be added/removed without touching a
+# global file per site). Purge is still per site: the cache key carries
+# $host, and purge_micro_cache(hosts) deletes only the files whose KEY
+# line names that host. proxy_* and fastcgi_* caches cannot
+# share a keys_zone, hence two zones over one base directory.
+MICROCACHE_CONF_NAME = 'serverkit-microcache.conf'
+MICROCACHE_DIR = '/var/cache/nginx/serverkit-microcache'
+
+MICROCACHE_ZONE_SNIPPET = '''# ServerKit micro-cache zones (auto-generated; do not edit).
+# One shared zone pair serves every site with micro-cache enabled — nginx
+# requires cache zones to be declared statically in the http context, so
+# per-site zones are not practical. Each site sets its own TTL; a purge
+# removes only that site's entries (the cache key carries the host).
+proxy_cache_path /var/cache/nginx/serverkit-microcache/proxy levels=1:2 keys_zone=serverkit_microcache:10m max_size=256m inactive=10m use_temp_path=off;
+fastcgi_cache_path /var/cache/nginx/serverkit-microcache/fastcgi levels=1:2 keys_zone=serverkit_microcache_php:10m max_size=256m inactive=10m use_temp_path=off;
+'''
+
+# Server-level bypass logic, shared by the proxy and fastcgi variants.
+# Cached responses are never stored/served for: non-GET/HEAD requests,
+# requests with a query string (safer default), session/auth/cart cookies,
+# or admin/login/cart paths.
+MICROCACHE_SKIP_BLOCK = ''' # ServerKit micro-cache bypass (never cache personalized responses)
+ set $sk_skip_cache 0;
+ if ($request_method !~ ^(GET|HEAD)$) { set $sk_skip_cache 1; }
+ if ($query_string != "") { set $sk_skip_cache 1; }
+ if ($http_cookie ~* "wordpress_logged_in_|wp-postpass|woocommerce_cart_hash|woocommerce_items_in_cart|comment_author|PHPSESSID|session|auth") { set $sk_skip_cache 1; }
+ if ($request_uri ~* "^/(wp-admin|wp-login|admin|login|cart|checkout|my-account)") { set $sk_skip_cache 1; }
+'''
+
+# Page-cache behaviour:
+# * the key is `$scheme://$host$request_uri`, so the cache files of one
+# site can be found by host and purged alone (the proxy default key is
+# `$scheme$proxy_host$request_uri` — the upstream port, not the site);
+# * a failing or slow upstream serves the last good copy (use_stale), an
+# expired entry is refreshed in the background while the stale copy is
+# served, and cache_lock sends one request upstream per missing entry
+# instead of a stampede. The zone's inactive=10m bounds how long a stale
+# copy survives, so the TTL is capped well below it.
+MICROCACHE_TTL_DEFAULT = 10
+MICROCACHE_TTL_MAX = 300
+
+MICROCACHE_PROXY_BLOCK = ''' proxy_cache serverkit_microcache;
+ proxy_cache_key $scheme://$host$request_uri;
+ proxy_cache_valid 200 301 {ttl}s;
+ proxy_cache_use_stale error timeout updating http_500 http_502 http_503;
+ proxy_cache_background_update on;
+ proxy_cache_lock on;
+ proxy_no_cache $sk_skip_cache;
+ add_header X-SK-Cache $upstream_cache_status;
+'''
+
+MICROCACHE_FASTCGI_BLOCK = ''' fastcgi_cache serverkit_microcache_php;
+ fastcgi_cache_key $scheme://$host$request_uri;
+ fastcgi_cache_valid 200 301 {ttl}s;
+ fastcgi_cache_use_stale error timeout updating http_500 http_503;
+ fastcgi_cache_background_update on;
+ fastcgi_cache_lock on;
+ fastcgi_cache_bypass $sk_skip_cache;
+ fastcgi_no_cache $sk_skip_cache;
+ add_header X-SK-Cache $upstream_cache_status;
+'''
+
+PRIVATE_URL_MAIN_CONFIG = '''# ServerKit Private URL Routes
+# This file is auto-generated. Do not edit manually.
+# Generated at: {timestamp}
+
+{locations}
+
+# Fallback for unknown slugs under /p/
+location /p/ {{
+ return 404;
+}}
+'''
diff --git a/backend/app/services/nginx/validation.py b/backend/app/services/nginx/validation.py
new file mode 100644
index 00000000..a5d78c3c
--- /dev/null
+++ b/backend/app/services/nginx/validation.py
@@ -0,0 +1,15 @@
+"""Pure validation shared by rendering and host cache operations."""
+import re
+
+
+def _validate_domain(domain: str) -> bool:
+ """Validate domain name to prevent nginx config injection."""
+ return bool(re.match(r'^(?:[a-z0-9](?:[a-z0-9\-]{0,61}[a-z0-9])?\.)*[a-z0-9](?:[a-z0-9\-]{0,61}[a-z0-9])?$', domain, re.IGNORECASE))
+
+
+def _validate_path(path: str) -> bool:
+ """Validate filesystem path for nginx config."""
+ # Block path traversal and special characters
+ if '..' in path or '\n' in path or '\r' in path or ';' in path:
+ return False
+ return bool(re.match(r'^/[a-zA-Z0-9/_\-\.]+$', path))
diff --git a/backend/app/services/nginx_service.py b/backend/app/services/nginx_service.py
index 570fcd73..f0376e43 100644
--- a/backend/app/services/nginx_service.py
+++ b/backend/app/services/nginx_service.py
@@ -8,6 +8,9 @@ from pathlib import Path
from app.utils.system import (ServiceControl, is_command_available,
run_privileged, write_privileged_file)
+from app.services.nginx import templates, rendering, compression
+from app.services.nginx.validation import _validate_domain, _validate_path # compatibility exports
+
logger = logging.getLogger(__name__)
@@ -24,19 +27,6 @@ def _auto_capture_vhost(name, action):
return auto_capture('nginx_vhost', name, action)
-def _validate_domain(domain: str) -> bool:
- """Validate domain name to prevent nginx config injection."""
- return bool(re.match(r'^(?:[a-z0-9](?:[a-z0-9\-]{0,61}[a-z0-9])?\.)*[a-z0-9](?:[a-z0-9\-]{0,61}[a-z0-9])?$', domain, re.IGNORECASE))
-
-
-def _validate_path(path: str) -> bool:
- """Validate filesystem path for nginx config."""
- # Block path traversal and special characters
- if '..' in path or '\n' in path or '\r' in path or ';' in path:
- return False
- return bool(re.match(r'^/[a-zA-Z0-9/_\-\.]+$', path))
-
-
class NginxService:
"""Service for Nginx configuration management."""
@@ -47,462 +37,67 @@ class NginxService:
NGINX_BIN = os.environ.get('NGINX_BIN', '/usr/sbin/nginx')
LOCATIONS_DIR = os.path.join(NGINX_CONF_DIR, 'serverkit-locations')
# Per-site log directory. Must stay in sync with the access_log/error_log
- # paths hard-coded in the site templates below. site_access_log_path() is the
+ # paths hard-coded in nginx/templates.py. site_access_log_path() is the
# single source of truth consumers should use (e.g. the fail2ban jail layer
# watches this exact file), so the path can never drift from what nginx writes.
LOG_DIR = '/var/log/nginx'
- # Templates
- PHP_SITE_TEMPLATE = '''server {{
- listen 80;
- listen [::]:80;
- server_name {domains};
-
- root {root_path};
- index index.php index.html index.htm;
-
- access_log /var/log/nginx/{name}.access.log serverkit_timed;
- error_log /var/log/nginx/{name}.error.log;
-
- location / {{
- try_files $uri $uri/ /index.php?$query_string;
- }}
-
- location ~ \\.php$ {{
- fastcgi_pass unix:/run/php/php{php_version}-fpm.sock;
- fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
- include fastcgi_params;
- fastcgi_intercept_errors on;
- fastcgi_buffer_size 16k;
- fastcgi_buffers 4 16k;
- }}
-
- location ~ /\\.ht {{
- deny all;
- }}
-
- location = /favicon.ico {{
- log_not_found off;
- access_log off;
- }}
-
- location = /robots.txt {{
- log_not_found off;
- access_log off;
- allow all;
- }}
-
- location ~* \\.(css|gif|ico|jpeg|jpg|js|png|svg|woff|woff2)$ {{
- expires 1y;
- log_not_found off;
- }}
-}}
-'''
-
- PYTHON_SITE_TEMPLATE = '''server {{
- listen 80;
- listen [::]:80;
- server_name {domains};
-
- access_log /var/log/nginx/{name}.access.log serverkit_timed;
- error_log /var/log/nginx/{name}.error.log;
-
- location / {{
- proxy_pass http://127.0.0.1:{port};
- proxy_http_version 1.1;
- proxy_set_header Upgrade $http_upgrade;
- proxy_set_header Connection 'upgrade';
- proxy_set_header Host $host;
- proxy_set_header X-Real-IP $remote_addr;
- proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
- proxy_set_header X-Forwarded-Proto $scheme;
- proxy_cache_bypass $http_upgrade;
- proxy_read_timeout 86400;
- }}
-
- location /static {{
- alias {root_path}/static;
- expires 1y;
- }}
-}}
-'''
-
- STATIC_SITE_TEMPLATE = '''server {{
- listen 80;
- listen [::]:80;
- server_name {domains};
-
- root {root_path};
- index index.html index.htm;
-
- access_log /var/log/nginx/{name}.access.log serverkit_timed;
- error_log /var/log/nginx/{name}.error.log;
-
- location / {{
- try_files $uri $uri/ =404;
- }}
-
- location ~* \\.(css|gif|ico|jpeg|jpg|js|png|svg|woff|woff2)$ {{
- expires 1y;
- log_not_found off;
- }}
-}}
-'''
-
- # Docker reverse proxy template (for containerized apps)
- DOCKER_SITE_TEMPLATE = '''server {{
- listen 80;
- listen [::]:80;
- server_name {domains};
-
- access_log /var/log/nginx/{name}.access.log serverkit_timed;
- error_log /var/log/nginx/{name}.error.log;
-
- location / {{
- proxy_pass http://127.0.0.1:{port};
- proxy_http_version 1.1;
- proxy_set_header Upgrade $http_upgrade;
- proxy_set_header Connection 'upgrade';
- proxy_set_header Host $host;
- proxy_set_header X-Real-IP $remote_addr;
- proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
- proxy_set_header X-Forwarded-Proto $scheme;
- proxy_cache_bypass $http_upgrade;
- proxy_read_timeout 86400;
- proxy_connect_timeout 60;
- proxy_send_timeout 60;
- }}
-}}
-'''
-
- # WordPress authentication endpoints receive a dedicated request limit in
- # published reverse-proxy vhosts. The zones are shared across vhosts, while
- # the key includes server_name so traffic to one site cannot consume
- # another site's allowance.
- WORDPRESS_RATE_LIMIT_CONF_NAME = 'serverkit-wordpress-rate-limit.conf'
- WORDPRESS_RATE_LIMIT_ZONE_SNIPPET = '''# ServerKit WordPress request-limit zones (auto-generated; do not edit).
-limit_req_zone $server_name$binary_remote_addr zone=serverkit_wp_login:10m rate=10r/m;
-limit_req_zone $server_name$binary_remote_addr zone=serverkit_wp_xmlrpc:10m rate=30r/m;
-'''
-
- WORDPRESS_PROTECTION_BLOCK = ''' # ServerKit WordPress brute-force protection
- location = /wp-login.php {{
- limit_req zone=serverkit_wp_login burst=10 nodelay;
- limit_req_status 429;
- proxy_pass http://127.0.0.1:{port};
- proxy_http_version 1.1;
- proxy_set_header Host $host;
- proxy_set_header X-Real-IP $remote_addr;
- proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
- proxy_set_header X-Forwarded-Proto $scheme;
- proxy_read_timeout 86400;
- proxy_connect_timeout 60;
- proxy_send_timeout 60;
- }}
-
- location = /xmlrpc.php {{
- limit_req zone=serverkit_wp_xmlrpc burst=20 nodelay;
- limit_req_status 429;
- proxy_pass http://127.0.0.1:{port};
- proxy_http_version 1.1;
- proxy_set_header Host $host;
- proxy_set_header X-Real-IP $remote_addr;
- proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
- proxy_set_header X-Forwarded-Proto $scheme;
- proxy_read_timeout 86400;
- proxy_connect_timeout 60;
- proxy_send_timeout 60;
- }}
-
-'''
-
- # Reverse proxy to a service reached over a WireGuard tunnel (roadmap
- # #12). The upstream is a peer's WG IP:port; the private agent forwards
- # it to the real service. proxy_buffering off keeps media/streaming
- # (e.g. Jellyfin) responsive.
- REMOTE_UPSTREAM_TEMPLATE = '''server {{
- listen 80;
- listen [::]:80;
- server_name {domains};
-
- access_log /var/log/nginx/{name}.access.log serverkit_timed;
- error_log /var/log/nginx/{name}.error.log;
-
- location / {{
- proxy_pass http://{upstream};
- proxy_http_version 1.1;
- proxy_set_header Upgrade $http_upgrade;
- proxy_set_header Connection 'upgrade';
- proxy_set_header Host $host;
- proxy_set_header X-Real-IP $remote_addr;
- proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
- proxy_set_header X-Forwarded-Proto $scheme;
- proxy_cache_bypass $http_upgrade;
- proxy_buffering off;
- proxy_read_timeout 86400;
- proxy_connect_timeout 60;
- proxy_send_timeout 60;
- }}
-}}
-'''
-
- SSL_BLOCK = '''
- listen 443 ssl http2;
- listen [::]:443 ssl http2;
-
- ssl_certificate {ssl_cert};
- ssl_certificate_key {ssl_key};
- ssl_session_timeout 1d;
- ssl_session_cache shared:SSL:50m;
- ssl_session_tickets off;
-
- ssl_protocols TLSv1.2 TLSv1.3;
- ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384;
- ssl_prefer_server_ciphers off;
- ssl_ecdh_curve X25519:secp384r1;
-
- # HSTS: 2 years, all subdomains, preload-eligible. Submit the domain at
- # https://hstspreload.org to get onto the browser preload list (this is what
- # protects first-time visitors from an initial-request MITM downgrade).
- add_header Strict-Transport-Security "max-age=63072000; includeSubDomains; preload" always;
-
- # Baseline response-header hardening. These are safe for reverse-proxied apps;
- # the CSP is deliberately permissive so it does not break managed apps while
- # still satisfying "a CSP is present" and blocking cross-origin framing.
- # Tighten the CSP per-app when the upstream can support a stricter policy.
- add_header X-Content-Type-Options "nosniff" always;
- add_header X-Frame-Options "SAMEORIGIN" always;
- add_header Referrer-Policy "strict-origin-when-cross-origin" always;
- add_header Content-Security-Policy "default-src 'self' 'unsafe-inline' 'unsafe-eval' data: blob: https:; frame-ancestors 'self'; upgrade-insecure-requests" always;
-'''
-
- SSL_REDIRECT_TEMPLATE = '''server {{
- listen 80;
- listen [::]:80;
- server_name {domains};
- return 301 https://$server_name$request_uri;
-}}
-'''
-
- # Private URL routing templates
- PRIVATE_URL_CONFIG_NAME = 'serverkit-private-urls'
- GITEA_CONFIG_NAME = 'serverkit-gitea'
- WORDPRESS_CONFIG_NAME = 'serverkit-wordpress'
-
- # Gitea location block for /gitea path (included inside main server block)
- GITEA_LOCATION_TEMPLATE = '''# Gitea at /gitea path
-location /gitea/ {{
- proxy_pass http://127.0.0.1:{port}/;
- proxy_http_version 1.1;
- proxy_set_header Upgrade $http_upgrade;
- proxy_set_header Connection "upgrade";
- proxy_set_header Host $host;
- proxy_set_header X-Real-IP $remote_addr;
- proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
- proxy_set_header X-Forwarded-Proto $scheme;
- proxy_set_header X-Forwarded-Host $host;
- proxy_cache_bypass $http_upgrade;
- proxy_read_timeout 86400;
- proxy_connect_timeout 60;
- proxy_send_timeout 60;
-
- # Required for Gitea WebSocket connections
- proxy_buffering off;
- client_max_body_size 100M;
-}}
-
-# Handle /gitea without trailing slash
-location = /gitea {{
- return 301 /gitea/;
-}}
-'''
-
- # WordPress location block for /wordpress path (included inside main server block)
- WORDPRESS_LOCATION_TEMPLATE = '''# WordPress at /wordpress path
-location /wordpress/ {{
- proxy_pass http://127.0.0.1:{port}/;
- proxy_http_version 1.1;
- proxy_set_header Host $host;
- proxy_set_header X-Real-IP $remote_addr;
- proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
- proxy_set_header X-Forwarded-Proto $scheme;
- proxy_set_header X-Forwarded-Host $host;
- proxy_cache_bypass $http_upgrade;
- proxy_read_timeout 300;
- proxy_connect_timeout 60;
- proxy_send_timeout 60;
-
- # WordPress file uploads
- client_max_body_size 256M;
-}}
-
-# Handle /wordpress without trailing slash
-location = /wordpress {{
- return 301 /wordpress/;
-}}
-'''
-
- PRIVATE_URL_LOCATION_TEMPLATE = ''' # Private URL: /p/{slug}
- location /p/{slug}/ {{
- proxy_pass http://127.0.0.1:{port}/;
- proxy_http_version 1.1;
- proxy_set_header Upgrade $http_upgrade;
- proxy_set_header Connection 'upgrade';
- proxy_set_header Host $host;
- proxy_set_header X-Real-IP $remote_addr;
- proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
- proxy_set_header X-Forwarded-Proto $scheme;
- proxy_set_header X-Private-URL {slug};
- proxy_cache_bypass $http_upgrade;
- proxy_read_timeout 86400;
- }}
-
- # Also handle without trailing slash
- location = /p/{slug} {{
- return 301 /p/{slug}/;
- }}
-'''
-
- # ==================== TIMED ACCESS LOG ====================
- # Every vhost ServerKit writes logs in this format. The combined fields come
- # first, unchanged, so every existing combined-format reader (bandwidth
- # accounting, the fail2ban `^<HOST> -` filters) keeps matching; the timing
- # fields are appended after them. The app id is the log file itself
- # (/var/log/nginx/<app>.access.log) — a per-vhost `set` variable would make
- # `nginx -t` warn on every server block that never sets it.
- TIMED_LOG_FORMAT = 'serverkit_timed'
- TIMED_LOG_CONF_NAME = 'serverkit-log-format.conf'
- TIMED_LOG_FORMAT_SNIPPET = """# ServerKit timed access-log format (auto-generated; do not edit).
-# Combined fields first (compatible with combined parsers), then timing.
-log_format serverkit_timed '$remote_addr - $remote_user [$time_local] "$request" '
- '$status $body_bytes_sent "$http_referer" "$http_user_agent" '
- 'rt=$request_time urt="$upstream_response_time" '
- 'cs=$upstream_cache_status h=$host';
-"""
-
- # ==================== COMPRESSION ====================
- # gzip (and brotli when the module is loaded) for every site, as one
- # http-level conf.d snippet. Stock configs already set some of these —
- # Debian's nginx.conf ships `gzip on;` — and a repeated http-level
- # directive is fatal to `nginx -t`, so the snippet only carries the
- # directives the running config does not already set (read from `nginx -T`).
- COMPRESSION_CONF_NAME = 'serverkit-compression.conf'
- # text/html is always compressed by nginx; listing it again only warns.
- COMPRESSION_TYPES = (
- 'text/plain text/css text/xml text/javascript application/javascript '
- 'application/json application/xml application/rss+xml '
- 'application/atom+xml image/svg+xml application/wasm '
- 'font/ttf font/otf application/vnd.ms-fontobject'
- )
- GZIP_DIRECTIVES = (
- ('gzip', 'on'),
- ('gzip_vary', 'on'),
- ('gzip_proxied', 'any'),
- ('gzip_comp_level', '5'),
- ('gzip_min_length', '1024'),
- ('gzip_types', COMPRESSION_TYPES),
- )
- BROTLI_DIRECTIVES = (
- ('brotli', 'on'),
- ('brotli_comp_level', '5'),
- ('brotli_min_length', '1024'),
- ('brotli_types', COMPRESSION_TYPES),
- )
-
- # ==================== IMMUTABLE ASSETS ====================
- # Opt-in, proxied sites only: a fingerprinted asset (a hash in its name)
- # never changes, so the browser may keep it a year. Off by default because
- # the panel cannot know an app's asset layout. The hash must be 8+ chars
- # after a '.' or '-' AND contain a digit, so `app-settings.js` is never
- # pinned; a hash with no digit is simply not long-cached (the safe miss).
- IMMUTABLE_ASSET_PATTERN = (
- r'[.-](?=[A-Za-z0-9_]*[0-9])[A-Za-z0-9_]{8,}'
- r'\.(?:js|mjs|css|map|woff2?|ttf|otf|png|jpe?g|gif|svg|webp|avif|ico)$'
- )
- # One Cache-Control header: `expires` would emit its own max-age header
- # next to this one, and clients read either.
- IMMUTABLE_ASSET_HEADERS = ''' add_header Cache-Control "public, max-age=31536000, immutable";
-'''
-
- # ==================== MICRO-CACHE (task #21) ====================
- # Opt-in per-site micro-cache: a very short (10s) full-page cache in front
- # of proxied/PHP sites, with hard bypasses for anything personalized.
- #
- # Design tradeoff — ONE shared zone/path for every opted-in site: nginx
- # cache zones must be declared statically in the http context, so a zone
- # per site does not scale (and can't be added/removed without touching a
- # global file per site). Purge is still per site: the cache key carries
- # $host, and purge_micro_cache(hosts) deletes only the files whose KEY
- # line names that host. proxy_* and fastcgi_* caches cannot
- # share a keys_zone, hence two zones over one base directory.
- MICROCACHE_CONF_NAME = 'serverkit-microcache.conf'
- MICROCACHE_DIR = '/var/cache/nginx/serverkit-microcache'
-
- MICROCACHE_ZONE_SNIPPET = '''# ServerKit micro-cache zones (auto-generated; do not edit).
-# One shared zone pair serves every site with micro-cache enabled — nginx
-# requires cache zones to be declared statically in the http context, so
-# per-site zones are not practical. Each site sets its own TTL; a purge
-# removes only that site's entries (the cache key carries the host).
-proxy_cache_path /var/cache/nginx/serverkit-microcache/proxy levels=1:2 keys_zone=serverkit_microcache:10m max_size=256m inactive=10m use_temp_path=off;
-fastcgi_cache_path /var/cache/nginx/serverkit-microcache/fastcgi levels=1:2 keys_zone=serverkit_microcache_php:10m max_size=256m inactive=10m use_temp_path=off;
-'''
-
- # Server-level bypass logic, shared by the proxy and fastcgi variants.
- # Cached responses are never stored/served for: non-GET/HEAD requests,
- # requests with a query string (safer default), session/auth/cart cookies,
- # or admin/login/cart paths.
- MICROCACHE_SKIP_BLOCK = ''' # ServerKit micro-cache bypass (never cache personalized responses)
- set $sk_skip_cache 0;
- if ($request_method !~ ^(GET|HEAD)$) { set $sk_skip_cache 1; }
- if ($query_string != "") { set $sk_skip_cache 1; }
- if ($http_cookie ~* "wordpress_logged_in_|wp-postpass|woocommerce_cart_hash|woocommerce_items_in_cart|comment_author|PHPSESSID|session|auth") { set $sk_skip_cache 1; }
- if ($request_uri ~* "^/(wp-admin|wp-login|admin|login|cart|checkout|my-account)") { set $sk_skip_cache 1; }
-'''
-
- # Page-cache behaviour:
- # * the key is `$scheme://$host$request_uri`, so the cache files of one
- # site can be found by host and purged alone (the proxy default key is
- # `$scheme$proxy_host$request_uri` — the upstream port, not the site);
- # * a failing or slow upstream serves the last good copy (use_stale), an
- # expired entry is refreshed in the background while the stale copy is
- # served, and cache_lock sends one request upstream per missing entry
- # instead of a stampede. The zone's inactive=10m bounds how long a stale
- # copy survives, so the TTL is capped well below it.
- MICROCACHE_TTL_DEFAULT = 10
- MICROCACHE_TTL_MAX = 300
-
- MICROCACHE_PROXY_BLOCK = ''' proxy_cache serverkit_microcache;
- proxy_cache_key $scheme://$host$request_uri;
- proxy_cache_valid 200 301 {ttl}s;
- proxy_cache_use_stale error timeout updating http_500 http_502 http_503;
- proxy_cache_background_update on;
- proxy_cache_lock on;
- proxy_no_cache $sk_skip_cache;
- add_header X-SK-Cache $upstream_cache_status;
-'''
-
- MICROCACHE_FASTCGI_BLOCK = ''' fastcgi_cache serverkit_microcache_php;
- fastcgi_cache_key $scheme://$host$request_uri;
- fastcgi_cache_valid 200 301 {ttl}s;
- fastcgi_cache_use_stale error timeout updating http_500 http_503;
- fastcgi_cache_background_update on;
- fastcgi_cache_lock on;
- fastcgi_cache_bypass $sk_skip_cache;
- fastcgi_no_cache $sk_skip_cache;
- add_header X-SK-Cache $upstream_cache_status;
-'''
-
- PRIVATE_URL_MAIN_CONFIG = '''# ServerKit Private URL Routes
-# This file is auto-generated. Do not edit manually.
-# Generated at: {timestamp}
+ # Compatibility aliases; configuration text is owned by nginx/templates.py.
+ PHP_SITE_TEMPLATE = templates.PHP_SITE_TEMPLATE
+ PYTHON_SITE_TEMPLATE = templates.PYTHON_SITE_TEMPLATE
+ STATIC_SITE_TEMPLATE = templates.STATIC_SITE_TEMPLATE
+ DOCKER_SITE_TEMPLATE = templates.DOCKER_SITE_TEMPLATE
+ WORDPRESS_RATE_LIMIT_CONF_NAME = templates.WORDPRESS_RATE_LIMIT_CONF_NAME
+ WORDPRESS_RATE_LIMIT_ZONE_SNIPPET = templates.WORDPRESS_RATE_LIMIT_ZONE_SNIPPET
+ WORDPRESS_PROTECTION_BLOCK = templates.WORDPRESS_PROTECTION_BLOCK
+ REMOTE_UPSTREAM_TEMPLATE = templates.REMOTE_UPSTREAM_TEMPLATE
+ SSL_BLOCK = templates.SSL_BLOCK
+ SSL_REDIRECT_TEMPLATE = templates.SSL_REDIRECT_TEMPLATE
+ PRIVATE_URL_CONFIG_NAME = templates.PRIVATE_URL_CONFIG_NAME
+ GITEA_CONFIG_NAME = templates.GITEA_CONFIG_NAME
+ WORDPRESS_CONFIG_NAME = templates.WORDPRESS_CONFIG_NAME
+ GITEA_LOCATION_TEMPLATE = templates.GITEA_LOCATION_TEMPLATE
+ WORDPRESS_LOCATION_TEMPLATE = templates.WORDPRESS_LOCATION_TEMPLATE
+ PRIVATE_URL_LOCATION_TEMPLATE = templates.PRIVATE_URL_LOCATION_TEMPLATE
+ TIMED_LOG_FORMAT = templates.TIMED_LOG_FORMAT
+ TIMED_LOG_CONF_NAME = templates.TIMED_LOG_CONF_NAME
+ TIMED_LOG_FORMAT_SNIPPET = templates.TIMED_LOG_FORMAT_SNIPPET
+ COMPRESSION_CONF_NAME = templates.COMPRESSION_CONF_NAME
+ COMPRESSION_TYPES = templates.COMPRESSION_TYPES
+ GZIP_DIRECTIVES = templates.GZIP_DIRECTIVES
+ BROTLI_DIRECTIVES = templates.BROTLI_DIRECTIVES
+ IMMUTABLE_ASSET_PATTERN = templates.IMMUTABLE_ASSET_PATTERN
+ IMMUTABLE_ASSET_HEADERS = templates.IMMUTABLE_ASSET_HEADERS
+ MICROCACHE_CONF_NAME = templates.MICROCACHE_CONF_NAME
+ MICROCACHE_DIR = templates.MICROCACHE_DIR
+ MICROCACHE_ZONE_SNIPPET = templates.MICROCACHE_ZONE_SNIPPET
+ MICROCACHE_SKIP_BLOCK = templates.MICROCACHE_SKIP_BLOCK
+ MICROCACHE_TTL_DEFAULT = templates.MICROCACHE_TTL_DEFAULT
+ MICROCACHE_TTL_MAX = templates.MICROCACHE_TTL_MAX
+ MICROCACHE_PROXY_BLOCK = templates.MICROCACHE_PROXY_BLOCK
+ MICROCACHE_FASTCGI_BLOCK = templates.MICROCACHE_FASTCGI_BLOCK
+ PRIVATE_URL_MAIN_CONFIG = templates.PRIVATE_URL_MAIN_CONFIG
-{locations}
-
-# Fallback for unknown slugs under /p/
-location /p/ {{
- return 404;
-}}
-'''
+ @classmethod
+ def _render_settings(cls):
+ """Pass only template values into the pure rendering layer."""
+ return rendering.RenderSettings(
+ DOCKER_SITE_TEMPLATE=cls.DOCKER_SITE_TEMPLATE,
+ IMMUTABLE_ASSET_HEADERS=cls.IMMUTABLE_ASSET_HEADERS,
+ IMMUTABLE_ASSET_PATTERN=cls.IMMUTABLE_ASSET_PATTERN,
+ MICROCACHE_FASTCGI_BLOCK=cls.MICROCACHE_FASTCGI_BLOCK,
+ MICROCACHE_PROXY_BLOCK=cls.MICROCACHE_PROXY_BLOCK,
+ MICROCACHE_SKIP_BLOCK=cls.MICROCACHE_SKIP_BLOCK,
+ MICROCACHE_TTL_DEFAULT=cls.MICROCACHE_TTL_DEFAULT,
+ MICROCACHE_TTL_MAX=cls.MICROCACHE_TTL_MAX,
+ PHP_SITE_TEMPLATE=cls.PHP_SITE_TEMPLATE,
+ PYTHON_SITE_TEMPLATE=cls.PYTHON_SITE_TEMPLATE,
+ REMOTE_UPSTREAM_TEMPLATE=cls.REMOTE_UPSTREAM_TEMPLATE,
+ SSL_BLOCK=cls.SSL_BLOCK,
+ SSL_REDIRECT_TEMPLATE=cls.SSL_REDIRECT_TEMPLATE,
+ STATIC_SITE_TEMPLATE=cls.STATIC_SITE_TEMPLATE,
+ WORDPRESS_PROTECTION_BLOCK=cls.WORDPRESS_PROTECTION_BLOCK,
+ )
@classmethod
def test_config(cls) -> Dict:
@@ -646,101 +241,17 @@ location /p/ {{
micro_cache_ttl: Optional[int] = None,
immutable_assets: bool = False,
wordpress_protection: bool = False) -> Dict:
- """Render the vhost config for a site to a string — no side effects.
-
- This is the exact template pipeline :meth:`create_site` writes to disk;
- it is exposed separately so callers (e.g. drift detection) can compute
- the expected on-disk content without touching the filesystem.
- Returns ``{'success': True, 'config': str}`` or
- ``{'success': False, 'error': msg}``.
- """
- if not domains:
- return {'success': False, 'error': 'At least one domain is required'}
-
- # Validate all domains
- for domain in domains:
- if domain == '_':
- return {'success': False, 'error': 'Wildcard server_name "_" is reserved for the ServerKit panel'}
- if not _validate_domain(domain):
- return {'success': False, 'error': f'Invalid domain name: {domain}'}
-
- # Validate root_path if provided
- if root_path and not _validate_path(root_path):
- return {'success': False, 'error': f'Invalid root path: {root_path}'}
-
- domains_str = ' '.join(domains)
-
- # Select template based on app type
- if app_type in ['php', 'wordpress']:
- config = cls.PHP_SITE_TEMPLATE.format(
- name=name,
- domains=domains_str,
- root_path=root_path,
- php_version=php_version
- )
- elif app_type in ['flask', 'django', 'python']:
- if not port:
- return {'success': False, 'error': 'Python services need a port'}
- config = cls.PYTHON_SITE_TEMPLATE.format(
- name=name,
- domains=domains_str,
- root_path=root_path,
- port=port
- )
- elif app_type == 'docker':
- if not port:
- return {'success': False, 'error': 'Docker services need a port'}
- config = cls.DOCKER_SITE_TEMPLATE.format(
- name=name,
- domains=domains_str,
- port=port
- )
- elif app_type == 'remote':
- if not upstream:
- return {'success': False, 'error': 'Services on remote servers need an upstream (host:port)'}
- config = cls.REMOTE_UPSTREAM_TEMPLATE.format(
- name=name,
- domains=domains_str,
- upstream=upstream,
- )
- elif app_type == 'static':
- config = cls.STATIC_SITE_TEMPLATE.format(
- name=name,
- domains=domains_str,
- root_path=root_path
- )
- else:
- return {'success': False, 'error': f'Unknown service type: {app_type}'}
-
- if immutable_assets:
- config = cls._with_immutable_assets(config, app_type)
-
- if micro_cache:
- # Inject before the SSL wrap so the redirect server block (which
- # also carries a server_name line) never receives cache directives.
- config = cls._with_micro_cache(config, app_type, micro_cache_ttl)
-
- if wordpress_protection:
- if app_type != 'docker' or not port:
- return {
- 'success': False,
- 'error': 'WordPress protection requires a Docker proxy port',
- }
- config = cls._with_wordpress_protection(config, port)
-
- if ssl_cert and ssl_key:
- config = cls._with_ssl(config, domains_str, ssl_cert, ssl_key)
-
- return {'success': True, 'config': config}
+ """Compatibility entry point for the pure configuration layer."""
+ return rendering.render_site_config(
+ name, app_type, domains, root_path, port, php_version, ssl_cert,
+ ssl_key, upstream, micro_cache, micro_cache_ttl, immutable_assets,
+ wordpress_protection, settings=cls._render_settings())
@classmethod
def _with_wordpress_protection(cls, config: str, port: int) -> str:
- """Add exact-match throttling locations before the catch-all proxy."""
- anchor = ' location / {\n'
- if anchor not in config:
- return config
- block = cls.WORDPRESS_PROTECTION_BLOCK.format(port=port)
- return config.replace(anchor, block + anchor, 1)
+ """Compatibility entry point for the pure configuration layer."""
+ return rendering._with_wordpress_protection(
+ config, port, settings=cls._render_settings())
@classmethod
def ensure_wordpress_rate_limit_zones(cls) -> Dict:
@@ -777,69 +288,22 @@ location /p/ {{
@classmethod
def _with_immutable_assets(cls, config: str, app_type: str) -> str:
- """Add a regex location for fingerprinted assets to a proxied vhost:
- the same proxying as ``location /`` plus a one-year immutable cache.
- Appended after ``location /`` (a matching regex location wins over the
- ``/`` prefix wherever it sits) so the micro-cache injection still
- anchors on the real ``location /``."""
- if (app_type or '').lower() not in ('flask', 'django', 'python', 'docker', 'remote'):
- return config
- match = re.search(r'^ location / \{\n(.*?)^ \}\n', config, re.MULTILINE | re.DOTALL)
- if not match:
- return config
- block = ('\n # ServerKit: fingerprinted assets never change\n'
- f' location ~* "{cls.IMMUTABLE_ASSET_PATTERN}" {{\n'
- + match.group(1) + cls.IMMUTABLE_ASSET_HEADERS + ' }\n')
- return config[:match.end()] + block + config[match.end():]
+ """Compatibility entry point for the pure configuration layer."""
+ return rendering._with_immutable_assets(
+ config, app_type, settings=cls._render_settings())
@classmethod
def _with_micro_cache(cls, config: str, app_type: str,
ttl: Optional[int] = None) -> str:
- """Inject the shared-zone micro-cache directives into a rendered vhost.
-
- fastcgi_cache for PHP-FPM-served sites, proxy_cache for reverse-proxied
- ones; static sites are a no-op (files already come straight off disk).
- Scheme-agnostic — nothing here depends on HTTP vs HTTPS. The referenced
- zones are declared once in conf.d by :meth:`ensure_cache_zone`.
- """
- t = (app_type or '').lower()
- ttl = cls.clamp_micro_cache_ttl(ttl)
- if t in ('php', 'wordpress'):
- anchor = ' include fastcgi_params;\n'
- if anchor not in config:
- return config
- config = config.replace(
- anchor, anchor + cls.MICROCACHE_FASTCGI_BLOCK.format(ttl=ttl), 1)
- elif t in ('flask', 'django', 'python', 'docker', 'remote'):
- # proxy_cache_bypass may only be declared once per location, so
- # fold $sk_skip_cache into the template's existing $http_upgrade
- # bypass instead of adding a duplicate directive.
- anchor = ' proxy_cache_bypass $http_upgrade;\n'
- if anchor not in config:
- return config
- config = config.replace(
- anchor,
- ' proxy_cache_bypass $sk_skip_cache $http_upgrade;\n'
- + cls.MICROCACHE_PROXY_BLOCK.format(ttl=ttl),
- 1,
- )
- else:
- return config
-
- # Server-level $sk_skip_cache logic, right after server_name.
- match = re.search(r'^( server_name [^;]+;\n)', config, re.MULTILINE)
- if match:
- config = config.replace(
- match.group(1), match.group(1) + '\n' + cls.MICROCACHE_SKIP_BLOCK, 1)
- return config
+ """Compatibility entry point for the pure configuration layer."""
+ return rendering._with_micro_cache(
+ config, app_type, ttl, settings=cls._render_settings())
@classmethod
def clamp_micro_cache_ttl(cls, ttl) -> int:
- """A stored TTL as the seconds the vhost uses: unset → the 10s
- default, anything else clamped to 1..MICROCACHE_TTL_MAX."""
- if ttl in (None, ''):
- return cls.MICROCACHE_TTL_DEFAULT
- return max(1, min(int(ttl), cls.MICROCACHE_TTL_MAX))
+ """Compatibility entry point for the pure configuration layer."""
+ return rendering.clamp_micro_cache_ttl(
+ ttl, settings=cls._render_settings())
@classmethod
def ensure_cache_zone(cls) -> Dict:
@@ -891,62 +355,17 @@ location /p/ {{
@classmethod
def _http_level_directives(cls, dump: str, skip_file: str) -> set:
- """Directive names set at http level in an ``nginx -T`` dump.
-
- ``nginx -T`` prints each file after a ``# configuration file <path>:``
- header. In the main nginx.conf, http level is depth 1 inside
- ``http {}``; every other file is included from the http block (conf.d)
- or a server (sites), so its depth-0 directives are the http-level
- ones. ``skip_file`` (our own snippet) is ignored so a rewrite never
- mistakes its own lines for someone else's.
- """
- found = set()
- current = None
- depth = 0
- in_http = False
- for raw in dump.splitlines():
- header = re.match(r'^# configuration file (.+):$', raw.strip())
- if header:
- current = header.group(1)
- depth = 0
- in_http = False
- continue
- if current is None or current == skip_file:
- continue
- line = raw.split('#', 1)[0].strip()
- if not line:
- continue
- is_main = current.endswith('/nginx.conf')
- http_level = (depth == 1 and in_http) if is_main else depth == 0
- name = line.split(None, 1)[0].rstrip(';{')
- if http_level and line.endswith(';'):
- found.add(name)
- if is_main and depth == 0 and name == 'http' and '{' in line:
- in_http = True
- depth += line.count('{') - line.count('}')
- if is_main and depth == 0:
- in_http = False
- return found
+ """Compatibility entry point for the pure configuration layer."""
+ return compression._http_level_directives(
+ dump, skip_file)
@classmethod
def render_compression_snippet(cls, dump: str, conf_path: str,
nginx_v: str = '') -> str:
- """The snippet for this box. When the running config already sets
- everything it is comments only: still written, so the "already
- handled" check stays a file-exists test instead of an ``nginx -T``
- on every vhost write."""
- present = cls._http_level_directives(dump, conf_path)
- brotli = ('ngx_http_brotli_filter_module' in dump
- or 'brotli' in (nginx_v or '').lower())
- wanted = list(cls.GZIP_DIRECTIVES)
- if brotli:
- wanted += list(cls.BROTLI_DIRECTIVES)
- lines = [f'{name} {value};' for name, value in wanted if name not in present]
- kept = sorted(name for name, _ in wanted if name in present)
- header = ['# ServerKit compression (auto-generated; do not edit).']
- if kept:
- header.append('# Already set elsewhere, left alone: ' + ', '.join(kept))
- return '\n'.join(header + lines) + '\n'
+ """Compatibility entry point for the pure configuration layer."""
+ return compression.render_compression_snippet(
+ dump, conf_path, nginx_v, gzip_directives=cls.GZIP_DIRECTIVES,
+ brotli_directives=cls.BROTLI_DIRECTIVES)
@classmethod
def ensure_compression(cls) -> Dict:
@@ -1087,17 +506,9 @@ location /p/ {{
@classmethod
def _with_ssl(cls, http_config: str, domains: str, ssl_cert: str, ssl_key: str) -> str:
- """Turn an HTTP server block into HTTPS: swap the :80 listens for the TLS
- block (so the existing server serves 443) and prepend an HTTP->HTTPS
- redirect. Idempotent because create_site regenerates the whole file."""
- ssl_block = cls.SSL_BLOCK.format(ssl_cert=ssl_cert, ssl_key=ssl_key)
- https_config = http_config.replace(
- ' listen 80;\n listen [::]:80;',
- ssl_block.strip('\n'),
- 1,
- )
- redirect = cls.SSL_REDIRECT_TEMPLATE.format(domains=domains)
- return redirect + '\n' + https_config
+ """Compatibility entry point for the pure configuration layer."""
+ return rendering._with_ssl(
+ http_config, domains, ssl_cert, ssl_key, settings=cls._render_settings())
@classmethod
def site_access_log_path(cls, name: str) -> str: