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.

feat(hosting): per-site nginx micro-cache toggle

Juan Denis96d162e9a442
diff --git a/backend/app/api/apps.py b/backend/app/api/apps.py
index 24454ef4..0aaaab79 100644
--- a/backend/app/api/apps.py
+++ b/backend/app/api/apps.py
@@ -1621,6 +1621,86 @@ def update_app_resources(app_id):
return jsonify(response), 200
+# ==================== MICRO-CACHE (task #21) ====================
+
+@apps_bp.route('/<int:app_id>/micro-cache', methods=['PUT'])
+@jwt_required()
+def set_micro_cache(app_id):
+ """Toggle the per-site nginx micro-cache and republish the vhost.
+
+ The flag flows through the same kwargs pipeline drift detection uses
+ (SiteDomainService.app_vhost_kwargs -> NginxService.render_site_config),
+ so an enabled cache is part of the expected vhost and never reads as
+ config drift. When the app has no domains yet, the flag is save-only and
+ takes effect on first publish.
+ """
+ user = User.query.get(get_jwt_identity())
+ app = Application.query.get(app_id)
+ if not app:
+ return jsonify({'error': 'Application not found'}), 404
+ if not _can_edit_app(user, app):
+ return jsonify({'error': 'Access denied'}), 403
+
+ data = request.get_json() or {}
+ if 'enabled' not in data:
+ return jsonify({'error': "'enabled' is required"}), 400
+
+ app.micro_cache_enabled = bool(data['enabled'])
+ db.session.commit()
+
+ applied = False
+ note = None
+ warning = None
+ if app.domains:
+ # Reuse the exact publish path (render + write + enable + reload).
+ from app.services.site_domain_service import SiteDomainService
+ result = SiteDomainService.write_app_vhost(app)
+ warning = result.get('warning')
+ applied = result.get('nginx') is not None and not warning
+ else:
+ note = ('Saved. The micro-cache takes effect when this service is '
+ 'published at a domain.')
+
+ response = {
+ 'message': f"Micro-cache {'enabled' if app.micro_cache_enabled else 'disabled'}",
+ 'micro_cache_enabled': bool(app.micro_cache_enabled),
+ 'applied': applied,
+ }
+ if note:
+ response['note'] = note
+ if warning:
+ response['warning'] = warning
+ return jsonify(response), 200
+
+
+@apps_bp.route('/<int:app_id>/micro-cache/purge', methods=['POST'])
+@jwt_required()
+def purge_micro_cache(app_id):
+ """Manually clear the micro-cache.
+
+ The cache is ONE shared nginx zone for all opted-in sites (zones must be
+ declared statically, so per-site zones don't scale) — purging therefore
+ wipes cached entries for every opted-in site. With the 10-second TTL this
+ is near-harmless, and no nginx reload is needed.
+ """
+ user = User.query.get(get_jwt_identity())
+ app = Application.query.get(app_id)
+ if not app:
+ return jsonify({'error': 'Application not found'}), 404
+ if not _can_edit_app(user, app):
+ return jsonify({'error': 'Access denied'}), 403
+
+ from app.services.nginx_service import NginxService
+ result = NginxService.purge_micro_cache()
+ if not result.get('success'):
+ return jsonify({'error': result.get('error', 'Purge failed')}), 500
+
+ response = {'message': result.get('message', 'Micro-cache cleared')}
+ if result.get('note'):
+ response['note'] = result['note']
+ return jsonify(response), 200
+
+
@apps_bp.route('/<int:app_id>/scale-policy', methods=['GET'])
@jwt_required()
def get_scale_policy(app_id):
diff --git a/backend/app/models/application.py b/backend/app/models/application.py
index 6f587dd5..e3824e81 100644
--- a/backend/app/models/application.py
+++ b/backend/app/models/application.py
@@ -69,6 +69,11 @@ class Application(db.Model):
private_slug = db.Column(db.String(50), unique=True, nullable=True, index=True)
private_url_enabled = db.Column(db.Boolean, default=False)
+ # Opt-in nginx micro-cache (task #21): short-TTL page cache emitted into
+ # the site's vhost, with bypasses for auth/admin/cart traffic. NULL/False
+ # = off (today's behavior).
+ micro_cache_enabled = db.Column(db.Boolean, default=False, nullable=True)
+
# Environment linking
environment_type = db.Column(db.String(20), default='standalone') # 'production', 'development', 'staging', 'standalone'
linked_app_id = db.Column(db.Integer, db.ForeignKey('applications.id'), nullable=True)
@@ -130,6 +135,7 @@ class Application(db.Model):
'upload_path': self.upload_path,
'private_slug': self.private_slug,
'private_url_enabled': self.private_url_enabled,
+ 'micro_cache_enabled': bool(self.micro_cache_enabled),
'environment_type': self.environment_type,
'linked_app_id': self.linked_app_id,
'shared_config': json.loads(self.shared_config) if self.shared_config else None,
diff --git a/backend/migrations/versions/053_micro_cache.py b/backend/migrations/versions/053_micro_cache.py
new file mode 100644
index 00000000..d93468be
--- /dev/null
+++ b/backend/migrations/versions/053_micro_cache.py
@@ -0,0 +1,45 @@
+"""Per-site micro-cache toggle (task #21).
+
+Adds:
+- applications.micro_cache_enabled (Boolean, nullable)
+
+NULL/False = off (today's behavior). When enabled, the app's nginx vhost is
+rendered with short-TTL fastcgi/proxy cache directives plus auth/admin/cart
+bypasses (see NginxService._with_micro_cache).
+
+Idempotent: MigrationService runs _fix_missing_columns() + db.create_all() on boot
+before Alembic, so guard on the live schema.
+
+Revision ID: 053_micro_cache
+Revises: 052_site_bandwidth
+Create Date: 2026-07-03
+"""
+from alembic import op
+import sqlalchemy as sa
+
+revision = '053_micro_cache'
+down_revision = '052_site_bandwidth'
+branch_labels = None
+depends_on = None
+
+_COLUMN = 'micro_cache_enabled'
+
+
+def upgrade():
+ conn = op.get_bind()
+ inspector = sa.inspect(conn)
+ if 'applications' not in set(inspector.get_table_names()):
+ return
+ cols = {c['name'] for c in inspector.get_columns('applications')}
+ if _COLUMN not in cols:
+ op.add_column('applications', sa.Column(_COLUMN, sa.Boolean(), nullable=True))
+
+
+def downgrade():
+ conn = op.get_bind()
+ inspector = sa.inspect(conn)
+ if 'applications' not in set(inspector.get_table_names()):
+ return
+ cols = {c['name'] for c in inspector.get_columns('applications')}
+ if _COLUMN in cols:
+ op.drop_column('applications', _COLUMN)
diff --git a/backend/tests/test_micro_cache.py b/backend/tests/test_micro_cache.py
new file mode 100644
index 00000000..a56d097b
--- /dev/null
+++ b/backend/tests/test_micro_cache.py
@@ -0,0 +1,391 @@
+"""Per-site micro-cache toggle (task #21) — renderer, zone snippet, kwargs
+plumbing, API, and drift consistency.
+
+Proving points:
+- render_site_config(micro_cache=True) emits the cache directives + every
+ bypass condition (method/query/cookies/paths) and the X-SK-Cache header;
+ disabled renders are byte-identical to before the feature
+- fastcgi_cache for PHP sites, proxy_cache for proxied ones, no-op for static
+- only ONE proxy_cache_bypass directive (folded into the template's
+ $http_upgrade bypass — nginx rejects duplicates)
+- the conf.d zone snippet is written once and is idempotent
+- SiteDomainService.app_vhost_kwargs carries micro_cache from the app row, so
+ the write path and the drift re-render agree (an enabled cache is never
+ reported as drift)
+- PUT /apps/<id>/micro-cache saves + republishes when the app has domains,
+ save-only note when not; POST .../purge wipes the shared cache dir
+ (Linux-guarded); both require auth
+"""
+from types import SimpleNamespace
+
+import pytest
+
+from app import db
+from app.models import Application, User
+from app.models.domain import Domain
+from app.services import nginx_service
+from app.services.nginx_service import NginxService
+from app.services.site_domain_service import SiteDomainService
+
+
+def _proc(returncode=0, stdout='', stderr=''):
+ return SimpleNamespace(returncode=returncode, stdout=stdout, stderr=stderr)
+
+
+BYPASS_MARKERS = [
+ 'set $sk_skip_cache 0;',
+ '$request_method !~ ^(GET|HEAD)$', # non-GET/HEAD
+ '$query_string != ""', # any query string
+ 'wordpress_logged_in_', # cookie bypasses
+ 'wp-postpass',
+ 'woocommerce_cart_hash',
+ 'woocommerce_items_in_cart',
+ 'comment_author',
+ 'PHPSESSID',
+ '^/(wp-admin|wp-login|admin|login|cart|checkout|my-account)', # path bypasses
+ 'add_header X-SK-Cache $upstream_cache_status;',
+]
+
+
+# ── renderer ─────────────────────────────────────────────────────────────────
+
+def test_php_site_gets_fastcgi_cache_with_all_bypasses():
+ res = NginxService.render_site_config(
+ 'blog', 'php', ['blog.lvh.me'], root_path='/srv/blog', micro_cache=True)
+ assert res['success'] is True
+ cfg = res['config']
+ assert 'fastcgi_cache serverkit_microcache_php;' in cfg
+ assert 'fastcgi_cache_valid 200 301 10s;' in cfg
+ assert 'fastcgi_cache_use_stale updating error timeout;' in cfg
+ assert 'fastcgi_cache_lock on;' in cfg
+ assert 'fastcgi_cache_bypass $sk_skip_cache;' in cfg
+ assert 'fastcgi_no_cache $sk_skip_cache;' in cfg
+ for marker in BYPASS_MARKERS:
+ assert marker in cfg, marker
+ # PHP path never references the proxy zone.
+ assert 'proxy_cache serverkit_microcache;' not in cfg
+
+
+def test_docker_site_gets_proxy_cache_with_folded_bypass():
+ res = NginxService.render_site_config(
+ 'shop', 'docker', ['shop.lvh.me'], port=8300, micro_cache=True)
+ assert res['success'] is True
+ cfg = res['config']
+ assert 'proxy_cache serverkit_microcache;' in cfg
+ assert 'proxy_cache_valid 200 301 10s;' in cfg
+ assert 'proxy_cache_use_stale updating error timeout;' in cfg
+ assert 'proxy_cache_lock on;' in cfg
+ assert 'proxy_no_cache $sk_skip_cache;' in cfg
+ for marker in BYPASS_MARKERS:
+ assert marker in cfg, marker
+ # nginx rejects duplicate proxy_cache_bypass directives — the skip var is
+ # folded into the template's existing $http_upgrade bypass.
+ assert cfg.count('proxy_cache_bypass') == 1
+ assert 'proxy_cache_bypass $sk_skip_cache $http_upgrade;' in cfg
+
+
+def test_python_site_gets_proxy_cache():
+ res = NginxService.render_site_config(
+ 'api', 'flask', ['api.lvh.me'], root_path='/srv/api', port=5001, micro_cache=True)
+ assert res['success'] is True
+ assert 'proxy_cache serverkit_microcache;' in res['config']
+
+
+def test_disabled_render_is_unchanged():
+ plain = NginxService.render_site_config('shop', 'docker', ['shop.lvh.me'], port=8300)
+ off = NginxService.render_site_config('shop', 'docker', ['shop.lvh.me'], port=8300,
+ micro_cache=False)
+ assert plain['config'] == off['config']
+ for token in ('serverkit_microcache', 'sk_skip_cache', 'X-SK-Cache'):
+ assert token not in plain['config']
+
+
+def test_static_site_is_a_noop_even_when_enabled():
+ on = NginxService.render_site_config('docs', 'static', ['docs.lvh.me'],
+ root_path='/srv/docs', micro_cache=True)
+ off = NginxService.render_site_config('docs', 'static', ['docs.lvh.me'],
+ root_path='/srv/docs')
+ assert on['config'] == off['config']
+ assert 'serverkit_microcache' not in on['config']
+
+
+def test_ssl_wrap_keeps_cache_in_app_block_only():
+ res = NginxService.render_site_config(
+ 'shop', 'docker', ['shop.lvh.me'], port=8300, micro_cache=True,
+ ssl_cert='/c/fullchain.pem', ssl_key='/c/privkey.pem')
+ cfg = res['config']
+ assert 'return 301 https://$server_name$request_uri;' in cfg
+ assert cfg.count('proxy_cache serverkit_microcache;') == 1
+ assert cfg.count('set $sk_skip_cache 0;') == 1
+ # The skip block lives in the 443 app block, after the redirect block.
+ assert cfg.index('return 301') < cfg.index('set $sk_skip_cache 0;')
+ # Cache directives are scheme-agnostic — nothing forces HTTPS.
+ assert 'listen 443 ssl http2;' in cfg
+
+
+# ── zone snippet ─────────────────────────────────────────────────────────────
+
+def test_zone_snippet_declares_shared_zones():
+ snippet = NginxService.MICROCACHE_ZONE_SNIPPET
+ assert 'keys_zone=serverkit_microcache:10m' in snippet
+ assert 'keys_zone=serverkit_microcache_php:10m' in snippet
+ assert 'max_size=256m' in snippet
+ assert 'inactive=10m' in snippet
+ assert snippet.count('/var/cache/nginx/serverkit-microcache') == 2
+
+
+def test_ensure_cache_zone_writes_once_and_is_idempotent(tmp_path, monkeypatch):
+ import os as _os
+ conf_dir = tmp_path / 'nginx'
+ monkeypatch.setattr(NginxService, 'NGINX_CONF_DIR', str(conf_dir))
+
+ calls = []
+
+ def fake_run(cmd, **kw):
+ calls.append(list(cmd))
+ if cmd[0] == 'tee':
+ path = cmd[1]
+ _os.makedirs(_os.path.dirname(path), exist_ok=True)
+ with open(path, 'w') as f:
+ f.write(kw.get('input', ''))
+ return _proc()
+
+ monkeypatch.setattr(nginx_service, 'run_privileged', fake_run)
+
+ first = NginxService.ensure_cache_zone()
+ assert first['success'] is True and first['changed'] is True
+ conf_path = conf_dir / 'conf.d' / 'serverkit-microcache.conf'
+ assert conf_path.read_text() == NginxService.MICROCACHE_ZONE_SNIPPET
+ tees = [c for c in calls if c[0] == 'tee']
+ assert len(tees) == 1
+
+ second = NginxService.ensure_cache_zone()
+ assert second['success'] is True and second['changed'] is False
+ assert len([c for c in calls if c[0] == 'tee']) == 1 # no rewrite
+
+
+def test_create_site_ensures_zone_when_enabled(tmp_path, monkeypatch):
+ monkeypatch.setattr(NginxService, 'SITES_AVAILABLE', str(tmp_path))
+ ensured = []
+ monkeypatch.setattr(NginxService, 'ensure_cache_zone',
+ classmethod(lambda cls: ensured.append(True) or {'success': True}))
+ written = {}
+
+ def fake_run(cmd, **kw):
+ if cmd[0] == 'tee':
+ written['path'] = cmd[1]
+ written['content'] = kw.get('input', '')
+ return _proc()
+
+ monkeypatch.setattr(nginx_service, 'run_privileged', fake_run)
+
+ res = NginxService.create_site('shop', 'docker', ['shop.lvh.me'],
+ root_path=None, port=8300, micro_cache=True)
+ assert res['success'] is True
+ assert ensured == [True]
+ assert 'proxy_cache serverkit_microcache;' in written['content']
+
+ # Disabled writes never touch the zone.
+ NginxService.create_site('shop', 'docker', ['shop.lvh.me'],
+ root_path=None, port=8300)
+ assert ensured == [True]
+
+
+# ── kwargs plumbing / drift consistency ──────────────────────────────────────
+
+def _mk_owner(username='mcowner'):
+ from werkzeug.security import generate_password_hash
+ user = User(email=f'{username}@test.local', username=username,
+ password_hash=generate_password_hash('x'),
+ role=User.ROLE_ADMIN, is_active=True)
+ db.session.add(user)
+ db.session.commit()
+ return user
+
+
+def _mk_site(user_id, name='mcshop', host='mcshop.lvh.me', micro_cache=False, **kw):
+ a = Application(name=name, app_type='docker', user_id=user_id, port=8300,
+ micro_cache_enabled=micro_cache, **kw)
+ db.session.add(a)
+ db.session.commit()
+ if host:
+ db.session.add(Domain(name=host, is_primary=True, application_id=a.id))
+ db.session.commit()
+ return a
+
+
+def test_app_vhost_kwargs_carries_micro_cache_flag(app):
+ user = _mk_owner()
+ on = _mk_site(user.id, name='mc-on', host='mc-on.lvh.me', micro_cache=True)
+ off = _mk_site(user.id, name='mc-off', host='mc-off.lvh.me', micro_cache=False)
+
+ kwargs_on, warn = SiteDomainService.app_vhost_kwargs(on)
+ assert warn is None
+ assert kwargs_on['micro_cache'] is True
+
+ kwargs_off, _ = SiteDomainService.app_vhost_kwargs(off)
+ assert kwargs_off['micro_cache'] is False
+
+
+def test_drift_expected_render_includes_micro_cache(app):
+ """Drift renders the expected vhost through app_vhost_kwargs — with the
+ flag on, the expected content carries the cache directives, so the file
+ the write path produced compares in_sync."""
+ from app.services.drift_service import _nginx_render_expected
+
+ user = _mk_owner('mcdrift')
+ site = _mk_site(user.id, name='mc-drift', host='mc-drift.lvh.me', micro_cache=True)
+
+ expected = _nginx_render_expected(site.id)
+ [(path, content)] = expected.items()
+ assert path.endswith('mc-drift')
+ assert 'proxy_cache serverkit_microcache;' in content
+ assert 'set $sk_skip_cache 0;' in content
+
+ # And it matches the renderer output for the same kwargs byte-for-byte
+ # (same pipeline both ways).
+ kwargs, _ = SiteDomainService.app_vhost_kwargs(site)
+ assert content == NginxService.render_site_config(**kwargs)['config']
+
+
+def test_model_round_trip_and_to_dict(app):
+ user = _mk_owner('mcmodel')
+ site = _mk_site(user.id, name='mc-model', host=None, micro_cache=True)
+ reloaded = Application.query.get(site.id)
+ assert reloaded.micro_cache_enabled is True
+ assert reloaded.to_dict()['micro_cache_enabled'] is True
+
+ plain = _mk_site(user.id, name='mc-plain', host=None)
+ assert plain.to_dict()['micro_cache_enabled'] is False
+
+
+# ── API ──────────────────────────────────────────────────────────────────────
+
+def _api_site(host='api-mc.lvh.me', name='api-mc'):
+ owner = User.query.filter_by(username='testadmin').first()
+ return _mk_site(owner.id, name=name, host=host)
+
+
+def test_api_put_published_saves_and_rewrites_vhost(client, auth_headers, app, monkeypatch):
+ site = _api_site()
+ calls = []
+ monkeypatch.setattr(SiteDomainService, 'write_app_vhost',
+ classmethod(lambda cls, a, force_type=None:
+ calls.append(a.id) or {'nginx': {'success': True}, 'warning': None}))
+
+ resp = client.put(f'/api/v1/apps/{site.id}/micro-cache', headers=auth_headers,
+ json={'enabled': True})
+ assert resp.status_code == 200, resp.get_json()
+ data = resp.get_json()
+ assert data['micro_cache_enabled'] is True
+ assert data['applied'] is True
+ assert 'note' not in data
+ assert calls == [site.id]
+ assert Application.query.get(site.id).micro_cache_enabled is True
+
+ # Toggle back off — vhost rewritten again without the directives.
+ resp = client.put(f'/api/v1/apps/{site.id}/micro-cache', headers=auth_headers,
+ json={'enabled': False})
+ assert resp.status_code == 200
+ assert resp.get_json()['micro_cache_enabled'] is False
+ assert calls == [site.id, site.id]
+ assert Application.query.get(site.id).micro_cache_enabled is False
+
+
+def test_api_put_unpublished_is_save_only(client, auth_headers, app, monkeypatch):
+ site = _api_site(host=None, name='api-mc-nodom')
+ monkeypatch.setattr(SiteDomainService, 'write_app_vhost',
+ classmethod(lambda cls, a, force_type=None:
+ (_ for _ in ()).throw(AssertionError('must not write'))))
+
+ resp = client.put(f'/api/v1/apps/{site.id}/micro-cache', headers=auth_headers,
+ json={'enabled': True})
+ assert resp.status_code == 200
+ data = resp.get_json()
+ assert data['applied'] is False
+ assert 'published' in data['note']
+ assert Application.query.get(site.id).micro_cache_enabled is True
+
+
+def test_api_put_surfaces_write_warning(client, auth_headers, app, monkeypatch):
+ site = _api_site(name='api-mc-warn', host='api-mc-warn.lvh.me')
+ monkeypatch.setattr(SiteDomainService, 'write_app_vhost',
+ classmethod(lambda cls, a, force_type=None:
+ {'nginx': None, 'warning': 'docker app has no published port to route to.'}))
+
+ resp = client.put(f'/api/v1/apps/{site.id}/micro-cache', headers=auth_headers,
+ json={'enabled': True})
+ assert resp.status_code == 200
+ data = resp.get_json()
+ assert data['applied'] is False
+ assert 'warning' in data
+ # The flag is still saved even when the vhost write degraded.
+ assert Application.query.get(site.id).micro_cache_enabled is True
+
+
+def test_api_put_requires_enabled_key(client, auth_headers, app):
+ site = _api_site(name='api-mc-bad', host=None)
+ resp = client.put(f'/api/v1/apps/{site.id}/micro-cache', headers=auth_headers, json={})
+ assert resp.status_code == 400
+ assert 'error' in resp.get_json()
+
+
+def test_api_404_for_missing_app(client, auth_headers, app):
+ assert client.put('/api/v1/apps/999999/micro-cache', headers=auth_headers,
+ json={'enabled': True}).status_code == 404
+ assert client.post('/api/v1/apps/999999/micro-cache/purge',
+ headers=auth_headers).status_code == 404
+
+
+def test_api_requires_auth(client, app):
+ assert client.put('/api/v1/apps/1/micro-cache', json={'enabled': True}).status_code == 401
+ assert client.post('/api/v1/apps/1/micro-cache/purge').status_code == 401
+
+
+def test_api_purge_happy_path(client, auth_headers, app, monkeypatch):
+ site = _api_site(name='api-mc-purge', host=None)
+ monkeypatch.setattr(NginxService, 'purge_micro_cache',
+ classmethod(lambda cls: {'success': True, 'message': 'Micro-cache cleared',
+ 'note': 'shared zone'}))
+ resp = client.post(f'/api/v1/apps/{site.id}/micro-cache/purge', headers=auth_headers)
+ assert resp.status_code == 200
+ data = resp.get_json()
+ assert data['message'] == 'Micro-cache cleared'
+ assert data['note'] == 'shared zone'
+
+
+def test_api_purge_failure_is_500_with_error(client, auth_headers, app, monkeypatch):
+ site = _api_site(name='api-mc-purgefail', host=None)
+ monkeypatch.setattr(NginxService, 'purge_micro_cache',
+ classmethod(lambda cls: {'success': False, 'error': 'boom'}))
+ resp = client.post(f'/api/v1/apps/{site.id}/micro-cache/purge', headers=auth_headers)
+ assert resp.status_code == 500
+ assert resp.get_json() == {'error': 'boom'}
+
+
+# ── purge service ────────────────────────────────────────────────────────────
+
+def test_purge_wipes_and_recreates_cache_dirs(monkeypatch):
+ import os as _os
+ monkeypatch.setattr(_os, 'name', 'posix') # force the Linux branch
+ calls = []
+ monkeypatch.setattr(nginx_service, 'run_privileged',
+ lambda cmd, **kw: calls.append(list(cmd)) or _proc())
+
+ res = NginxService.purge_micro_cache()
+ assert res['success'] is True
+ assert 'shared' in res['note'] # documents the full-zone tradeoff
+ rm, mkdir = calls
+ assert rm[:2] == ['rm', '-rf']
+ assert f'{NginxService.MICROCACHE_DIR}/proxy'.replace('/', _os.sep) in [p.replace('/', _os.sep) for p in rm]
+ assert mkdir[:2] == ['mkdir', '-p']
+
+
+def test_purge_is_linux_guarded(monkeypatch):
+ import os as _os
+ monkeypatch.setattr(_os, 'name', 'nt')
+ monkeypatch.setattr(nginx_service, 'run_privileged',
+ lambda *a, **kw: (_ for _ in ()).throw(AssertionError('must not run')))
+ res = NginxService.purge_micro_cache()
+ assert res['success'] is False
+ assert 'Linux' in res['error']
diff --git a/frontend/src/components/apps/MicroCachePanel.jsx b/frontend/src/components/apps/MicroCachePanel.jsx
new file mode 100644
index 00000000..fcfb683a
--- /dev/null
+++ b/frontend/src/components/apps/MicroCachePanel.jsx
@@ -0,0 +1,117 @@
+import { useState } from 'react';
+import { Zap, Eraser } from 'lucide-react';
+import api from '../../services/api';
+import { useToast } from '../../contexts/ToastContext';
+import { Button } from '@/components/ui/button';
+import { Switch } from '@/components/ui/switch';
+
+// Micro-cache panel (task #21) — opt-in nginx page cache per site. The
+// backend rewrites the site's vhost with short-TTL cache directives plus
+// hard bypasses for anything personalized (logged-in cookies, carts,
+// admin/login paths, non-GET requests, query strings).
+const MicroCachePanel = ({ app, onChanged }) => {
+ const toast = useToast();
+ const [enabled, setEnabled] = useState(!!app.micro_cache_enabled);
+ const [saving, setSaving] = useState(false);
+ const [purging, setPurging] = useState(false);
+
+ async function handleToggle(next) {
+ setSaving(true);
+ setEnabled(next); // optimistic; reverted on failure
+ try {
+ const data = await api.setMicroCache(app.id, next);
+ if (data.warning) toast.warning(data.warning);
+ if (data.note) {
+ toast.info(data.note);
+ } else {
+ toast.success(next
+ ? 'Micro-cache enabled — the site config was updated.'
+ : 'Micro-cache disabled — the site config was updated.');
+ }
+ onChanged?.();
+ } catch (err) {
+ setEnabled(!next);
+ toast.error(err.message || 'Failed to update micro-cache');
+ } finally {
+ setSaving(false);
+ }
+ }
+
+ async function handlePurge() {
+ if (!confirm('Clear the micro-cache now? This clears cached pages for every site using the shared cache (entries expire within 10 seconds anyway).')) return;
+ setPurging(true);
+ try {
+ const data = await api.purgeMicroCache(app.id);
+ toast.success(data.message || 'Micro-cache cleared');
+ } catch (err) {
+ toast.error(err.message || 'Failed to clear the micro-cache');
+ } finally {
+ setPurging(false);
+ }
+ }
+
+ return (
+ <div className="app-panel">
+ <div className="app-panel-header">
+ <Zap />
+ <span>Micro-cache</span>
+ </div>
+ <div className="app-panel-body">
+ <p className="app-panel-hint">
+ Caches full pages in nginx for 10 seconds, so traffic spikes hit the
+ cache instead of your app — a big, cheap win for WordPress and PHP
+ sites. It is safe to enable: requests from logged-in users, carts and
+ checkouts, admin and login pages, non-GET requests, and URLs with
+ query strings always bypass the cache and reach the app directly.
+ </p>
+
+ <div className="settings-row">
+ <div className="settings-label">
+ <span>Enable micro-cache</span>
+ <span className="settings-hint">
+ Rewrites this site&apos;s nginx config with the cache rules.
+ Turning it off removes them again.
+ </span>
+ </div>
+ <div className="settings-control">
+ <Switch
+ checked={enabled}
+ onCheckedChange={handleToggle}
+ disabled={saving}
+ aria-label="Enable micro-cache"
+ />
+ {saving && <span className="settings-saving">Saving...</span>}
+ </div>
+ </div>
+
+ {enabled && (
+ <div className="settings-row">
+ <div className="settings-label">
+ <span>Clear cache</span>
+ <span className="settings-hint">
+ Entries expire on their own within 10 seconds; use this when
+ a change must be visible immediately. The cache is shared, so
+ this clears it for every site that uses it.
+ </span>
+ </div>
+ <div className="settings-control">
+ <Button variant="outline" size="sm" onClick={handlePurge} disabled={purging}>
+ <Eraser size={14} />
+ {purging ? 'Clearing…' : 'Clear cache'}
+ </Button>
+ </div>
+ </div>
+ )}
+
+ <p className="app-panel-hint">
+ To verify it works, check the <code>X-SK-Cache</code> response header
+ on the site: <code>HIT</code> means the page came from the cache,
+ <code> MISS</code>/<code>EXPIRED</code> that it was fetched fresh, and
+ <code> BYPASS</code> that a bypass rule applied.
+ </p>
+ </div>
+ </div>
+ );
+};
+
+export default MicroCachePanel;
diff --git a/frontend/src/components/service-detail/SettingsTab.jsx b/frontend/src/components/service-detail/SettingsTab.jsx
index 474cea6d..a5f4965a 100644
--- a/frontend/src/components/service-detail/SettingsTab.jsx
+++ b/frontend/src/components/service-detail/SettingsTab.jsx
@@ -16,6 +16,7 @@ import {
CircleCheck,
CircleX,
Sparkles,
+ Zap,
} from 'lucide-react';
import api from '../../services/api';
import { useToast } from '../../contexts/ToastContext';
@@ -25,6 +26,7 @@ import ProtectionPanel from '../backups/ProtectionPanel';
import ContainerOpsPanel from '../apps/ContainerOpsPanel';
import VolumesPanel from '../apps/VolumesPanel';
import ResourceLimitsPanel from '../apps/ResourceLimitsPanel';
+import MicroCachePanel from '../apps/MicroCachePanel';
import AppWafPanel from '../apps/AppWafPanel';
import BuildTab from '../appdetail/BuildTab';
import DeployTab from '../appdetail/DeployTab';
@@ -45,6 +47,9 @@ import { Select, SelectTrigger, SelectContent, SelectItem, SelectValue } from '@
function buildSettingsGroups(app) {
const isDocker = app.isDocker ?? app.app_type === 'docker';
const isPython = app.isPython ?? ['flask', 'django'].includes(app.app_type);
+ // Micro-cache applies to anything nginx fronts with an upstream (proxied
+ // or PHP-FPM); static sites already serve files straight off disk.
+ const isCacheable = isDocker || isPython || ['php', 'wordpress'].includes(app.app_type);
return [
{
@@ -56,6 +61,7 @@ function buildSettingsGroups(app) {
{ id: 'domain', label: 'Domain & SSL', icon: Shield },
...(isDocker ? [{ id: 'ops', label: 'Container Ops', icon: Boxes }] : []),
...(isDocker ? [{ id: 'resources', label: 'Resource Limits', icon: Gauge }] : []),
+ ...(isCacheable ? [{ id: 'cache', label: 'Cache', icon: Zap }] : []),
],
},
{
@@ -308,6 +314,15 @@ const SettingsTab = ({ app, deployConfig, domains, primaryDomain, onUpdate }) =>
</div>
)}
+ {/* Cache — opt-in nginx micro-cache (task #21): 10s page cache
+ with auth/admin/cart bypasses and a manual purge. */}
+ {section === 'cache' && (
+ <div className="svc-settings__section">
+ <h3 className="svc-settings__section-title">Cache</h3>
+ <MicroCachePanel app={app} onChanged={onUpdate} />
+ </div>
+ )}
+
{/* Storage (Docker only) — first-class managed volumes that
survive redeploys, replacing fragile relative bind mounts. */}
{section === 'storage' && (
diff --git a/frontend/src/services/api/apps.js b/frontend/src/services/api/apps.js
index de046b4b..6b59578b 100644
--- a/frontend/src/services/api/apps.js
+++ b/frontend/src/services/api/apps.js
@@ -127,6 +127,15 @@ export async function updateAppResources(id, data) {
return this.request(`/apps/${id}/resources`, { method: 'PUT', body: data });
}
+// Per-site nginx micro-cache (short-TTL page cache with auth/admin/cart bypasses).
+export async function setMicroCache(id, enabled) {
+ return this.request(`/apps/${id}/micro-cache`, { method: 'PUT', body: { enabled } });
+}
+
+export async function purgeMicroCache(id) {
+ return this.request(`/apps/${id}/micro-cache/purge`, { method: 'POST' });
+}
+
export async function startApp(id) {
return this.request(`/apps/${id}/start`, { method: 'POST' });
}