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.

Run release commands and DB snapshots before the switch

Juan Denis074950859984
diff --git a/backend/app/api/app_slots.py b/backend/app/api/app_slots.py
index a3e0b6a2..cea8a276 100644
--- a/backend/app/api/app_slots.py
+++ b/backend/app/api/app_slots.py
@@ -8,6 +8,10 @@
POST /<app_id>/slots/switch-back — make the standby live again (a rollback
to the release it holds: seconds while
it is warm)
+ POST /<app_id>/slots/restore-db — {deployment_id}: restore the database
+ snapshot taken before that deployment's
+ release ran. Destroys later writes; an
+ explicit second step after a rollback.
"""
from flask import Blueprint, jsonify, request
@@ -58,3 +62,17 @@ def switch_back(app_id):
if not result.get('success'):
return jsonify(result), 409
return jsonify(result)
+
+
+@app_slots_bp.route('/<int:app_id>/slots/restore-db', methods=['POST'])
+@developer_required
+def restore_db(app_id):
+ app, _ = _app(app_id, write=True)
+ data = request.get_json(silent=True) or {}
+ deployment_id = data.get('deployment_id')
+ if not isinstance(deployment_id, int) or isinstance(deployment_id, bool):
+ raise ValidationError("'deployment_id' is required")
+ result = SlotDeployService.restore_databases(app, deployment_id)
+ if not result.get('success'):
+ return jsonify(result), 409
+ return jsonify(result)
diff --git a/backend/app/services/deploy_settings.py b/backend/app/services/deploy_settings.py
index 682214fe..5bb11870 100644
--- a/backend/app/services/deploy_settings.py
+++ b/backend/app/services/deploy_settings.py
@@ -21,6 +21,13 @@ DEFAULTS = {
'watch_seconds': 60,
'standby_warm_minutes': 10,
'slot_volumes_confirmed': False,
+ # Release phase (§D): a command to run once before the switch (overrides
+ # the Procfile's release: line), whether to dump the app's databases
+ # first, and the announced-downtime fallback for schema changes that
+ # cannot stay backward-compatible for one deploy.
+ 'release_command': None,
+ 'snapshot_databases': True,
+ 'stop_old_before_release': False,
}
# key -> (type, min, max). Anything outside is rejected, not clamped: a typo'd
@@ -33,6 +40,9 @@ _RULES = {
'watch_seconds': (int, 0, 900),
'standby_warm_minutes': (int, 0, 1440),
'slot_volumes_confirmed': (bool, None, None),
+ 'release_command': (str, None, 500),
+ 'snapshot_databases': (bool, None, None),
+ 'stop_old_before_release': (bool, None, None),
}
@@ -74,6 +84,13 @@ def validate(changes) -> tuple:
return None, f'{key} must be true or false'
clean[key] = value
continue
+ if kind is str:
+ if not isinstance(value, str):
+ return None, f'{key} must be text'
+ if len(value) > high:
+ return None, f'{key} must be at most {high} characters'
+ clean[key] = value.strip() or None
+ continue
if isinstance(value, bool):
return None, f'{key} must be a number'
try:
diff --git a/backend/app/services/release_phase_service.py b/backend/app/services/release_phase_service.py
new file mode 100644
index 00000000..d282cf8e
--- /dev/null
+++ b/backend/app/services/release_phase_service.py
@@ -0,0 +1,191 @@
+"""Pre-switch phases of a slot deploy: DB snapshot and release command (plan 87 §D).
+
+Both slots talk to the same database, so anything that changes it runs
+exactly once, BEFORE the switch, while the old release still serves:
+
+* **Snapshot** — every managed database the app owns gets a dump through the
+ backup service. It is the safety net for a migration that turns out to be
+ destructive. It never blocks: a failed or skipped snapshot is a warning.
+* **Release** — the Procfile ``release:`` line (or ``release`` in
+ ``serverkit.yaml``, or the app's own setting) runs once in a one-off
+ container of the NEW image with the app's env. A non-zero exit aborts the
+ deploy with the live slot untouched.
+
+Rolling back code never rolls back the database. :func:`restore_databases`
+is the explicit second step the UI offers, with a data-loss warning.
+"""
+import logging
+import os
+from datetime import datetime
+from typing import Callable, Dict, List, Optional, Tuple
+
+logger = logging.getLogger(__name__)
+
+RELEASE_TIMEOUT = 1800
+MANIFEST_NAMES = ('serverkit.yaml', 'serverkit.yml')
+
+
+def _log(log, line):
+ logger.info(line)
+ if log:
+ try:
+ log(line)
+ except Exception: # noqa: BLE001
+ pass
+
+
+def resolve_release_command(app) -> Tuple[Optional[str], Optional[str]]:
+ """``(command, source)``: the app setting, then the Procfile, then serverkit.yaml."""
+ from app.services import deploy_settings
+ from app.services.worker_process_service import parse_procfile
+
+ configured = (deploy_settings.get(app, 'release_command') or '').strip()
+ if configured:
+ return configured, 'settings'
+ root = getattr(app, 'root_path', None)
+ if not root:
+ return None, None
+ try:
+ with open(os.path.join(root, 'Procfile'), encoding='utf-8') as fh:
+ command = parse_procfile(fh.read()).get('release')
+ if command:
+ return command, 'Procfile'
+ except OSError:
+ pass
+ for name in MANIFEST_NAMES:
+ try:
+ import yaml
+ with open(os.path.join(root, name), encoding='utf-8') as fh:
+ data = yaml.safe_load(fh) or {}
+ except (OSError, ValueError, Exception): # noqa: BLE001 - unreadable manifest = none
+ continue
+ if not isinstance(data, dict):
+ continue
+ deploy = data.get('deploy') if isinstance(data.get('deploy'), dict) else {}
+ command = data.get('release') or deploy.get('release')
+ if isinstance(command, str) and command.strip():
+ return command.strip(), name
+ return None, None
+
+
+def run_release(app, image: str, env: Dict, volumes: List[str], command: str,
+ log: Optional[Callable[[str], None]] = None) -> Dict:
+ """Run ``command`` once in a throwaway container of ``image``."""
+ from app.services.docker_service import DockerService
+ from app.services.service_connection_service import SHARED_NETWORK, ServiceConnectionService
+
+ name = f'serverkit-release-{app.id}'
+ args = ['run', '--rm', '--name', name]
+ for key, value in (env or {}).items():
+ args.extend(['-e', f'{key}={value}'])
+ for volume in volumes or []:
+ args.extend(['-v', volume])
+ try:
+ if ServiceConnectionService.needs_shared_network(app):
+ DockerService.ensure_network(SHARED_NETWORK)
+ args.extend(['--network', SHARED_NETWORK])
+ except Exception as exc: # noqa: BLE001 - reach the DB the way the app does, or try anyway
+ logger.warning('release network setup for app %s failed: %s', app.id, exc)
+ args.extend([image, 'sh', '-c', command])
+ _log(log, f'Running release command in a one-off container: {command}')
+ # A leftover from a killed run would make `--name` collide.
+ DockerService.run(['rm', '-f', name], timeout=30)
+ result = DockerService.run(args, timeout=RELEASE_TIMEOUT)
+ for line in (result.get('output') or '').splitlines()[-40:]:
+ _log(log, line)
+ if not result.get('success'):
+ return {'success': False, 'error': result.get('error') or 'release command failed'}
+ return {'success': True}
+
+
+def owned_databases(app):
+ from app.models.managed_database import ManagedDatabase
+ return ManagedDatabase.query.filter_by(owner_application_id=app.id).all()
+
+
+def snapshot_databases(app, deployment, log=None) -> List[Dict]:
+ """Dump every managed DB the app owns; record them on the deployment."""
+ from app import db
+ from app.services import deploy_settings
+ from app.services.backup_service import BackupService
+ from app.services.managed_database_service import ManagedDatabaseService
+
+ databases = owned_databases(app)
+ if not databases:
+ return []
+ if not deploy_settings.get(app, 'snapshot_databases'):
+ _log(log, 'Warning: pre-deploy database snapshot is turned off for this app.')
+ return []
+ taken = []
+ for managed in databases:
+ descriptor = ManagedDatabaseService.backup_descriptor(managed)
+ _log(log, f'Snapshotting database {managed.name} before the release...')
+ try:
+ result = BackupService.backup_database(**descriptor)
+ except Exception as exc: # noqa: BLE001 - a snapshot never blocks
+ result = {'success': False, 'error': str(exc)}
+ if result.get('success'):
+ taken.append({'managed_id': managed.id, 'name': managed.name,
+ 'engine': managed.engine, 'path': result.get('path'),
+ 'taken_at': datetime.utcnow().isoformat()})
+ else:
+ _log(log, f"Warning: snapshot of {managed.name} failed ({result.get('error')}); "
+ 'continuing without it.')
+ if taken:
+ deployment.update_metadata('db_snapshots', taken)
+ db.session.commit()
+ return taken
+
+
+def restore_databases(app, deployment) -> Dict:
+ """Restore the snapshots taken before ``deployment`` ran. Destroys every
+ write made since; the UI asks first."""
+ from app.models.managed_database import ManagedDatabase
+ from app.services.backup_service import BackupService
+ from app.services.managed_database_service import ManagedDatabaseService
+
+ snapshots = (deployment.get_metadata() or {}).get('db_snapshots') or []
+ if not snapshots:
+ return {'success': False, 'error': 'That deployment has no database snapshot.'}
+ restored, failed = [], {}
+ for snap in snapshots:
+ managed = ManagedDatabase.query.get(snap.get('managed_id'))
+ if managed is None or managed.owner_application_id != app.id:
+ failed[snap.get('name')] = 'database no longer belongs to this app'
+ continue
+ d = ManagedDatabaseService.backup_descriptor(managed)
+ result = BackupService.restore_database(snap.get('path'), d['db_type'], d['db_name'],
+ user=d['user'], password=d['password'],
+ host=d['host'])
+ if result.get('success'):
+ restored.append(managed.name)
+ else:
+ failed[managed.name] = result.get('error') or 'restore failed'
+ return {'success': not failed, 'restored': restored, 'failed': failed,
+ **({'error': '; '.join(f'{k}: {v}' for k, v in failed.items())} if failed else {})}
+
+
+def restorable(app) -> Optional[Dict]:
+ """The release whose migration may still be in the database: the newest
+ deployment that ran its release command and is no longer serving (switched
+ back, reverted, or failed after the release) and carries a snapshot. None
+ once a later deploy has gone live on top of it."""
+ from app.models.deployment import Deployment
+ live = Deployment.get_current(app.id)
+ newest = None
+ for dep in (Deployment.query.filter(Deployment.app_id == app.id,
+ Deployment.status.in_(('rolled_back', 'failed')))
+ .order_by(Deployment.id.desc()).limit(10).all()):
+ meta = dep.get_metadata() or {}
+ if meta.get('release_ran') and meta.get('db_snapshots') and not meta.get('db_restored_at'):
+ newest = dep
+ break
+ if newest is None:
+ return None
+ if live and live.id > newest.id and not (live.get_metadata() or {}).get('rolled_back_to'):
+ return None
+ snapshots = newest.get_metadata()['db_snapshots']
+ return {'deployment_id': newest.id, 'version': newest.version,
+ 'taken_at': snapshots[0].get('taken_at'),
+ 'databases': [s.get('name') for s in snapshots]}
+
diff --git a/backend/app/services/slot_deploy_service.py b/backend/app/services/slot_deploy_service.py
index 86413e56..6e381707 100644
--- a/backend/app/services/slot_deploy_service.py
+++ b/backend/app/services/slot_deploy_service.py
@@ -64,6 +64,11 @@ def live_container_name(app) -> str:
return legacy_container_name(app)
+def _restorable(app):
+ from app.services import release_phase_service
+ return release_phase_service.restorable(app)
+
+
class SlotDeployError(RuntimeError):
pass
@@ -183,6 +188,7 @@ class SlotDeployService:
'active_slot': app.active_slot,
'eligibility': cls.eligibility(app),
'volumes': sorted(v.name for v in app.volumes),
+ 'restorable_db': _restorable(app),
'slots': [rows[s].to_dict() for s in SLOTS if s in rows],
}
@@ -235,8 +241,24 @@ class SlotDeployService:
if not app.slot_deploys_enabled:
return None
idle = other(app.active_slot) if app.active_slot in SLOTS else 'b'
- return ['Preflight', 'Build', f'Boot slot {idle.upper()}', 'Health gate',
- 'Switch', 'Watch']
+ return ['Preflight', 'Build', 'Snapshot', 'Release', f'Boot slot {idle.upper()}',
+ 'Health gate', 'Switch', 'Watch']
+
+ @classmethod
+ def restore_databases(cls, app, deployment_id) -> Dict:
+ """Put the app's databases back to before ``deployment_id``'s release."""
+ from app.models.deployment import Deployment
+ from app.services import release_phase_service
+ from app.services.deploy_lock import deploy_lock
+ deployment = Deployment.query.filter_by(id=deployment_id, app_id=app.id).first()
+ if deployment is None:
+ return {'success': False, 'error': 'Deployment not found'}
+ with deploy_lock(app.id, 'database restore'):
+ result = release_phase_service.restore_databases(app, deployment)
+ if result.get('success'):
+ deployment.update_metadata('db_restored_at', _now().isoformat())
+ db.session.commit()
+ return result
@classmethod
def protected_images(cls, app) -> set:
@@ -274,6 +296,32 @@ class SlotDeployService:
reuse = (idle.image_ref == image and idle.state in ('standby', 'stopped')
and idle.container_name and DockerService.get_container(idle.container_name))
+ # ---- snapshot + release (§D): once, before the switch, old slot live
+ from app.services import release_phase_service as release
+ stage('Snapshot')
+ release.snapshot_databases(app, deployment, log)
+ stage('Release')
+ old_stopped = False
+ command, source = release.resolve_release_command(app)
+ if command and (reuse or getattr(deployment, 'deploy_trigger', None) == 'rollback'):
+ # Rolling code back never re-runs migrations; the DB stays as it is.
+ _log(log, f'Rollback: not running the release command ({source}).')
+ command = None
+ if command:
+ if deploy_settings.get(app, 'stop_old_before_release'):
+ _log(log, f'Stopping slot {live.slot.upper()} before the release command, as this '
+ 'app is set to: the site is down until the new release passes its '
+ 'health check.')
+ DockerService.stop_container(live.container_name)
+ old_stopped = True
+ ran = release.run_release(app, image, env, volumes, command, log)
+ deployment.update_metadata('release_ran', True)
+ db.session.commit()
+ if not ran['success']:
+ return cls._abort(app, live, old_stopped,
+ f"The release command ({source}) failed: {ran['error']}. "
+ f'The new release was not started; the site is still serving {version}.')
+
name = idle.container_name if reuse else slot_container_name(app, idle.slot)
stage(f'Boot slot {idle.slot.upper()}')
if reuse:
@@ -310,10 +358,9 @@ class SlotDeployService:
idle.state = 'failed'
idle.last_health = (run.get('error') or 'did not start')[:255]
db.session.commit()
- message = (f"The new release did not start: {run.get('error')}. "
- f'The site is still serving {version}.')
- _notify('app.deploy_aborted', app, 'warning', message)
- return {'success': False, 'still_serving': True, 'error': message}
+ return cls._abort(app, live, old_stopped,
+ f"The new release did not start: {run.get('error')}. "
+ f'The site is still serving {version}.')
connect_shared_network(app, name)
stage('Health gate')
@@ -323,10 +370,9 @@ class SlotDeployService:
idle.last_health = f"{result['status']} on {result['url']}"[:255]
except HealthGateError as exc:
cls._discard(idle, str(exc), remove=not reuse)
- message = f'The new release never became healthy: {exc}. The site is still serving {version}.'
- _log(log, message)
- _notify('app.deploy_aborted', app, 'warning', message)
- return {'success': False, 'still_serving': True, 'error': message}
+ return cls._abort(app, live, old_stopped,
+ f'The new release never became healthy: {exc}. '
+ f'The site is still serving {version}.', log=log)
idle.state = 'healthy'
db.session.commit()
@@ -334,9 +380,9 @@ class SlotDeployService:
switched = cls._switch(app, idle, live, log)
if not switched['success']:
cls._discard(idle, switched['error'], remove=not reuse)
- message = f"Could not switch traffic: {switched['error']}. The site is still serving {version}."
- _notify('app.deploy_aborted', app, 'warning', message)
- return {'success': False, 'still_serving': True, 'error': message}
+ return cls._abort(app, live, old_stopped,
+ f"Could not switch traffic: {switched['error']}. "
+ f'The site is still serving {version}.')
stage('Watch')
watched = cls._watch(app, idle, log)
@@ -352,6 +398,21 @@ class SlotDeployService:
workers = WorkerProcessService.deploy(app, image, env, volumes, log=log)
return {'success': True, 'slot': idle.slot, 'workers': workers, 'container_id': name}
+ @classmethod
+ def _abort(cls, app, live: AppSlot, old_stopped: bool, message: str, log=None) -> Dict:
+ """End a deploy before the switch. The live slot kept serving — unless
+ the app stops it for its release, in which case it is started again."""
+ from app.services.docker_service import DockerService
+ serving = True
+ if old_stopped:
+ serving = bool(DockerService.start_container(live.container_name).get('success'))
+ if not serving:
+ message += ' Starting the previous release again FAILED — the site is down.'
+ _log(log, message)
+ _notify('app.deploy_aborted' if serving else 'app.deploy_revert_failed', app,
+ 'warning' if serving else 'critical', message)
+ return {'success': False, 'still_serving': serving, 'error': message}
+
# ------------------------------------------------------------------ #
# Switch / watch / revert / standby
# ------------------------------------------------------------------ #
diff --git a/backend/tests/test_plan87_slot_deploys.py b/backend/tests/test_plan87_slot_deploys.py
index 7170a071..5275ed15 100644
--- a/backend/tests/test_plan87_slot_deploys.py
+++ b/backend/tests/test_plan87_slot_deploys.py
@@ -542,7 +542,8 @@ def test_a_slot_deploy_job_reports_each_stage_to_the_console(app, world, monkeyp
queued = DeploymentJobService.enqueue_app_deploy(row)
job = db.session.get(DeploymentJob, queued['job_id'])
steps = [s['name'] for s in job.get_plan()['steps']]
- assert steps == ['Preflight', 'Build', 'Boot slot B', 'Health gate', 'Switch', 'Watch']
+ assert steps == ['Preflight', 'Build', 'Snapshot', 'Release', 'Boot slot B', 'Health gate',
+ 'Switch', 'Watch']
from app.services.run_log_service import RunLogStream
reached = []
@@ -557,8 +558,8 @@ def test_a_slot_deploy_job_reports_each_stage_to_the_console(app, world, monkeyp
result = DeploymentJobService.run_job(job.id)
assert result['success'], result
- assert reached == [(1, 'Preflight'), (2, 'Build'), (3, 'Boot slot B'), (4, 'Health gate'),
- (5, 'Switch'), (6, 'Watch')]
+ assert reached == [(1, 'Preflight'), (2, 'Build'), (3, 'Snapshot'), (4, 'Release'),
+ (5, 'Boot slot B'), (6, 'Health gate'), (7, 'Switch'), (8, 'Watch')]
def test_an_in_place_deploy_job_keeps_its_three_steps(app, world, monkeypatch):
@@ -570,3 +571,161 @@ def test_an_in_place_deploy_job_keeps_its_three_steps(app, world, monkeypatch):
job = db.session.get(DeploymentJob, queued['job_id'])
assert [s['name'] for s in job.get_plan()['steps']] == [
'Prepare deployment', 'Build application', 'Start containers']
+
+
+# ── §D: release command + DB snapshot ────────────────────────────────────────
+
+def release_world(world, monkeypatch, tmp_path):
+ """The world, plus a Procfile with a release line and a recording docker run."""
+ (tmp_path / 'Procfile').write_text('web: node server.js\nrelease: npm run migrate\n')
+ world.releases = []
+ world.release_fails = False
+
+ def run(cls, args, **kw):
+ if args[:2] == ['run', '--rm']:
+ world.releases.append((args[args.index('sh') - 1], args[-1]))
+ world.note('release')
+ if world.release_fails:
+ return {'success': False, 'error': 'exit status 1', 'output': 'migration 42 failed'}
+ return {'success': True, 'output': ''}
+
+ monkeypatch.setattr(DockerService, 'run', classmethod(run))
+ from app.services.service_connection_service import ServiceConnectionService
+ monkeypatch.setattr(ServiceConnectionService, 'needs_shared_network',
+ classmethod(lambda cls, app: False))
+ world.root = tmp_path
+ return world
+
+
+def _order(world):
+ return [event.split(' ')[0] for event, _ in world.timeline]
+
+
+def test_the_release_command_runs_once_in_the_new_image_before_the_boot(app, release_world):
+ world = release_world
+ row = _live_app(world, root_path=str(world.root))
+ _enable(row)
+ result = DeploymentService.deploy(row.id)
+ assert result['success'], result
+ image = result['deployment']['image_tag']
+ assert world.releases == [(image, 'npm run migrate')]
+ order = _order(world)
+ assert order.index('release') < order.index('run'), 'release must run before the new slot boots'
+ assert Deployment.query.get(result['deployment']['id']).get_metadata()['release_ran'] is True
+ assert world.outage() == []
+
+
+def test_a_failed_release_aborts_with_the_live_slot_untouched(app, release_world):
+ world = release_world
+ world.release_fails = True
+ row = _live_app(world, root_path=str(world.root))
+ _enable(row)
+ result = DeploymentService.deploy(row.id)
+ assert result['success'] is False and result['still_serving'] is True
+ assert 'release command (Procfile) failed' in result['error']
+ assert world.ran == [] and row.active_slot == 'a' and world.outage() == []
+ assert 'app.deploy_aborted' in world.notified
+
+
+def test_a_rollback_never_reruns_the_release(app, release_world):
+ world = release_world
+ row = _live_app(world, root_path=str(world.root))
+ _enable(row)
+ assert DeploymentService.deploy(row.id)['success']
+ assert len(world.releases) == 1
+ assert SlotDeployService.switch_back(row)['success']
+ assert len(world.releases) == 1
+
+
+def test_stop_old_before_release_is_announced_downtime_that_heals_on_failure(app, release_world):
+ world = release_world
+ world.release_fails = True
+ row = _live_app(world, root_path=str(world.root))
+ _enable(row)
+ deploy_settings.update(row, {'stop_old_before_release': True})
+ db.session.commit()
+ result = DeploymentService.deploy(row.id)
+ assert result['success'] is False and result['still_serving'] is True
+ # Down during the release (the operator chose that), serving again after.
+ assert world.outage() == [f'stop serverkit-app-{row.id}', 'release']
+ assert world.timeline[-1][1] is True
+ assert world.containers[f'serverkit-app-{row.id}']['running'] is True
+
+
+def test_the_release_command_can_come_from_settings(app, release_world):
+ world = release_world
+ row = _live_app(world, root_path=str(world.root))
+ _enable(row)
+ deploy_settings.update(row, {'release_command': 'python manage.py migrate'})
+ db.session.commit()
+ assert DeploymentService.deploy(row.id)['success']
+ assert world.releases[0][1] == 'python manage.py migrate'
+
+
+def _owned_db(row):
+ from app.models.managed_database import ManagedDatabase
+ managed = ManagedDatabase(engine='postgresql', name='shopdb', host='localhost', port=5432,
+ owner_application_id=row.id)
+ db.session.add(managed)
+ db.session.commit()
+ return managed
+
+
+def test_owned_databases_are_snapshotted_before_the_release(app, release_world, monkeypatch):
+ from app.services.backup_service import BackupService
+ world = release_world
+ dumped = []
+ monkeypatch.setattr(BackupService, 'backup_database', classmethod(
+ lambda cls, **kw: (dumped.append(kw['db_name']), world.note('dump'),
+ {'success': True, 'path': '/backups/shopdb.sql.gz'})[2]))
+ row = _live_app(world, root_path=str(world.root))
+ _owned_db(row)
+ _enable(row)
+ result = DeploymentService.deploy(row.id)
+ assert result['success'], result
+ assert dumped == ['shopdb']
+ order = _order(world)
+ assert order.index('dump') < order.index('release')
+ snaps = Deployment.query.get(result['deployment']['id']).get_metadata()['db_snapshots']
+ assert snaps[0]['path'] == '/backups/shopdb.sql.gz'
+
+
+def test_a_failed_snapshot_warns_but_never_blocks(app, release_world, monkeypatch):
+ from app.services.backup_service import BackupService
+ world = release_world
+ monkeypatch.setattr(BackupService, 'backup_database', classmethod(
+ lambda cls, **kw: {'success': False, 'error': 'pg_dump: connection refused'}))
+ lines = []
+ row = _live_app(world, root_path=str(world.root))
+ _owned_db(row)
+ _enable(row)
+ result = DeploymentService.deploy(row.id, log_callback=lines.append)
+ assert result['success'], result
+ assert any('snapshot of shopdb failed' in line for line in lines)
+
+
+def test_after_a_switch_back_the_database_restore_is_offered_then_applied(
+ app, release_world, monkeypatch, client, auth_headers):
+ from app.services.backup_service import BackupService
+ world = release_world
+ monkeypatch.setattr(BackupService, 'backup_database', classmethod(
+ lambda cls, **kw: {'success': True, 'path': '/backups/shopdb.sql.gz'}))
+ restored = []
+ monkeypatch.setattr(BackupService, 'restore_database', classmethod(
+ lambda cls, path, db_type, db_name, **kw: restored.append((path, db_name)) or {'success': True}))
+ row = _live_app(world, root_path=str(world.root))
+ _owned_db(row)
+ _enable(row)
+ bad = DeploymentService.deploy(row.id)['deployment']
+ assert SlotDeployService.status(row)['restorable_db'] is None, 'nothing to undo while it serves'
+ assert SlotDeployService.switch_back(row)['success']
+
+ offer = SlotDeployService.status(row)['restorable_db']
+ assert offer['deployment_id'] == bad['id'] and offer['databases'] == ['shopdb']
+
+ resp = client.post(f'/api/v1/apps/{row.id}/slots/restore-db', headers=auth_headers,
+ json={'deployment_id': bad['id']})
+ assert resp.status_code == 200, resp.get_json()
+ assert restored == [('/backups/shopdb.sql.gz', 'shopdb')]
+ assert SlotDeployService.status(row)['restorable_db'] is None
diff --git a/docs/API_SURFACE.md b/docs/API_SURFACE.md
index 589dec55..d79885cf 100644
--- a/docs/API_SURFACE.md
+++ b/docs/API_SURFACE.md
@@ -793,6 +793,7 @@ Regenerate (backend/):
- `POST /apps/{app_id}/restart`
- `POST /apps/{app_id}/rollback`
- `POST /apps/{app_id}/sleep`
+- `POST /apps/{app_id}/slots/restore-db`
- `POST /apps/{app_id}/slots/switch-back`
- `POST /apps/{app_id}/snapshots/{snap_id}/restore`
- `POST /apps/{app_id}/start`
diff --git a/docs/screenshots/service-slots.png b/docs/screenshots/service-slots.png
index f225b147..0564e04f 100644
Binary files a/docs/screenshots/service-slots.png and b/docs/screenshots/service-slots.png differ
diff --git a/frontend/src/components/apps/SlotDeploysPanel.jsx b/frontend/src/components/apps/SlotDeploysPanel.jsx
index 3700be30..4b3b27ca 100644
--- a/frontend/src/components/apps/SlotDeploysPanel.jsx
+++ b/frontend/src/components/apps/SlotDeploysPanel.jsx
@@ -31,6 +31,9 @@ const SlotDeploysPanel = ({ app, onChanged }) => {
const [watch, setWatch] = useState(String(settings.watch_seconds ?? WATCH_DEFAULT));
const [standby, setStandby] = useState(String(settings.standby_warm_minutes ?? STANDBY_DEFAULT));
const [volumesOk, setVolumesOk] = useState(!!settings.slot_volumes_confirmed);
+ const [releaseCommand, setReleaseCommand] = useState(settings.release_command || '');
+ const [snapshotDbs, setSnapshotDbs] = useState(settings.snapshot_databases ?? true);
+ const [stopOld, setStopOld] = useState(!!settings.stop_old_before_release);
useEffect(() => {
let cancelled = false;
@@ -44,7 +47,10 @@ const SlotDeploysPanel = ({ app, onChanged }) => {
const standbyValue = intIn(standby, 0, STANDBY_MAX);
const dirty = (watchValue !== null && watchValue !== (settings.watch_seconds ?? WATCH_DEFAULT))
|| (standbyValue !== null && standbyValue !== (settings.standby_warm_minutes ?? STANDBY_DEFAULT))
- || volumesOk !== !!settings.slot_volumes_confirmed;
+ || volumesOk !== !!settings.slot_volumes_confirmed
+ || releaseCommand.trim() !== (settings.release_command || '')
+ || snapshotDbs !== (settings.snapshot_databases ?? true)
+ || stopOld !== !!settings.stop_old_before_release;
async function handleToggle(next) {
setToggling(true);
@@ -70,6 +76,9 @@ const SlotDeploysPanel = ({ app, onChanged }) => {
watch_seconds: watchValue,
standby_warm_minutes: standbyValue,
slot_volumes_confirmed: volumesOk,
+ release_command: releaseCommand.trim() || null,
+ snapshot_databases: snapshotDbs,
+ stop_old_before_release: stopOld,
},
});
toast.success(t('app.slotDeploysPanel.saved', 'Rollout settings saved.'));
@@ -160,6 +169,47 @@ const SlotDeploysPanel = ({ app, onChanged }) => {
</div>
)}
+ <div className="settings-row">
+ <div className="settings-label">
+ <label htmlFor={`slot-release-${app.id}`}>
+ {t('app.slotDeploysPanel.release', 'Release command')}
+ </label>
+ <span className="settings-hint">
+ {t('app.slotDeploysPanel.releaseHint', 'Runs once in a throwaway container of the new release, before traffic switches, for example database migrations. If it fails the deploy stops and the live release is untouched. Empty uses the release: line of the Procfile or serverkit.yaml, if there is one.')}
+ </span>
+ </div>
+ <div className="settings-control">
+ <Input id={`slot-release-${app.id}`} placeholder={t('app.slotDeploysPanel.releasePlaceholder', 'npm run migrate')}
+ value={releaseCommand} onChange={(e) => setReleaseCommand(e.target.value)} disabled={saving} />
+ </div>
+ </div>
+
+ <div className="settings-row">
+ <div className="settings-label">
+ <span>{t('app.slotDeploysPanel.snapshot', 'Snapshot the databases first')}</span>
+ <span className="settings-hint">
+ {t('app.slotDeploysPanel.snapshotHint', 'Dumps the databases this app owns before the release command runs, so a migration can be undone after a switch back.')}
+ </span>
+ </div>
+ <div className="settings-control">
+ <Switch checked={snapshotDbs} onCheckedChange={setSnapshotDbs} disabled={saving}
+ aria-label={t('app.slotDeploysPanel.snapshot', 'Snapshot the databases first')} />
+ </div>
+ </div>
+
+ <div className="settings-row">
+ <div className="settings-label">
+ <span>{t('app.slotDeploysPanel.stopOld', 'Stop the live release before the release command')}</span>
+ <span className="settings-hint">
+ {t('app.slotDeploysPanel.stopOldHint', 'For schema changes the running release cannot survive. The site is down from the release command until the new release passes its health check; a failure starts the old release again.')}
+ </span>
+ </div>
+ <div className="settings-control">
+ <Switch checked={stopOld} onCheckedChange={setStopOld} disabled={saving}
+ aria-label={t('app.slotDeploysPanel.stopOld', 'Stop the live release before the release command')} />
+ </div>
+ </div>
+
<div className="settings-row">
<div className="settings-label" />
<div className="settings-control">
diff --git a/frontend/src/components/service-detail/SlotsCard.jsx b/frontend/src/components/service-detail/SlotsCard.jsx
index e1a768d8..1220e161 100644
--- a/frontend/src/components/service-detail/SlotsCard.jsx
+++ b/frontend/src/components/service-detail/SlotsCard.jsx
@@ -27,6 +27,7 @@ export default function SlotsCard({ app }) {
const { confirm } = useConfirm();
const [state, setState] = useState(null);
const [switching, setSwitching] = useState(false);
+ const [restoring, setRestoring] = useState(false);
const load = useCallback(() => {
let cancelled = false;
@@ -64,6 +65,30 @@ export default function SlotsCard({ app }) {
}
}
+ // Rolling code back never rolls the database back. This is the explicit
+ // second step, with the data-loss warning where the choice is made.
+ async function handleRestoreDb() {
+ const offer = state.restorable_db;
+ if (!await confirm({
+ title: t('app.slots.restoreDb', 'Restore the database'),
+ message: t('app.slots.restoreDbConfirm', 'Restore {{databases}} to the snapshot taken before v{{version}} ran its release command? Everything written to the database since then is lost.', {
+ databases: offer.databases.join(', '), version: offer.version,
+ }),
+ confirmText: t('app.slots.restoreDbConfirmButton', 'Restore and lose later writes'),
+ variant: 'danger',
+ })) return;
+ setRestoring(true);
+ try {
+ await api.restoreAppSlotDatabase(app.id, offer.deployment_id);
+ toast.success(t('app.slots.restoredDb', 'Database restored to before v{{version}}.', { version: offer.version }));
+ load();
+ } catch (err) {
+ toast.error(err.message || t('app.slots.restoreDbFailed', 'Restoring the database failed'));
+ } finally {
+ setRestoring(false);
+ }
+ }
+
function slotLine(slot) {
const parts = [slot.slot.toUpperCase()];
if (slot.version) parts.push(`v${slot.version}`);
@@ -135,6 +160,17 @@ export default function SlotsCard({ app }) {
</div>
)}
+ {state.enabled && state.restorable_db && (
+ <div className="slots-card__restore">
+ <p className="slots-card__hint">
+ {t('app.slots.restoreDbHint', 'v{{version}} ran its release command before it was switched away from, so the database may still have its changes. The code went back; the database did not.', { version: state.restorable_db.version })}
+ </p>
+ <Button variant="outline" size="sm" onClick={handleRestoreDb} disabled={restoring}>
+ {restoring ? t('app.slots.restoringDb', 'Restoring…') : t('app.slots.restoreDb', 'Restore the database')}
+ </Button>
+ </div>
+ )}
+
{state.enabled && state.eligibility.warnings.length > 0 && (
<ul className="slots-card__reasons slots-card__reasons--warn">
{state.eligibility.warnings.map((warning) => <li key={warning}>{warning}</li>)}
diff --git a/frontend/src/i18n/locales/en.json b/frontend/src/i18n/locales/en.json
index 421360e6..220e3688 100644
--- a/frontend/src/i18n/locales/en.json
+++ b/frontend/src/i18n/locales/en.json
@@ -5633,11 +5633,18 @@
"enableHint": "Turning it on restarts nothing: the running container becomes slot A.",
"enabled": "Slot deploys on. The running container is now slot A; the next deploy boots slot B.",
"intro": "Each deploy boots the new release in a second slot on its own port while the live one keeps serving. It switches traffic only after the new release passes its health check, watches it for a while, and switches back on its own if it falls over. The previous release stays warm for an instant manual switch back.",
+ "release": "Release command",
+ "releaseHint": "Runs once in a throwaway container of the new release, before traffic switches, for example database migrations. If it fails the deploy stops and the live release is untouched. Empty uses the release: line of the Procfile or serverkit.yaml, if there is one.",
+ "releasePlaceholder": "npm run migrate",
"saveFailed": "Failed to save rollout settings",
"saved": "Rollout settings saved.",
"schemaRule": "Both releases use the same database during the switch. Keep schema changes backward-compatible for one deploy: add first, deploy, remove later.",
+ "snapshot": "Snapshot the databases first",
+ "snapshotHint": "Dumps the databases this app owns before the release command runs, so a migration can be undone after a switch back.",
"standby": "Keep the previous release warm (minutes)",
"standbyHint": "While warm, switching back takes seconds. After that it is stopped: it no longer uses memory, and switching back starts it first.",
+ "stopOld": "Stop the live release before the release command",
+ "stopOldHint": "For schema changes the running release cannot survive. The site is down from the release command until the new release passes its health check; a failure starts the old release again.",
"title": "Slot deploys",
"toggleFailed": "Could not change slot deploys",
"volumes": "Two copies may share the volumes",
@@ -5652,6 +5659,13 @@
"noStandby": "None yet. The next deploy boots beside the live release, and this one becomes the standby.",
"off": "Off",
"on": "On",
+ "restoreDb": "Restore the database",
+ "restoreDbConfirm": "Restore {{databases}} to the snapshot taken before v{{version}} ran its release command? Everything written to the database since then is lost.",
+ "restoreDbConfirmButton": "Restore and lose later writes",
+ "restoreDbFailed": "Restoring the database failed",
+ "restoreDbHint": "v{{version}} ran its release command before it was switched away from, so the database may still have its changes. The code went back; the database did not.",
+ "restoredDb": "Database restored to before v{{version}}.",
+ "restoringDb": "Restoring…",
"standby": "Standby",
"stopped": "stopped, starts on switch back",
"switchBack": "Switch back",
diff --git a/frontend/src/i18n/locales/es.json b/frontend/src/i18n/locales/es.json
index 4fece2f5..2f67e6ff 100644
--- a/frontend/src/i18n/locales/es.json
+++ b/frontend/src/i18n/locales/es.json
@@ -6812,7 +6812,14 @@
"noStandby": "Todavía ninguna. El próximo despliegue arranca junto a la versión en vivo, y esta pasa a estar en espera.",
"explain": "Un despliegue arranca la versión nueva junto a la que está en vivo, comprueba que responde y luego cambia el tráfico. Una versión que falla nunca reemplaza a la que funciona, y la anterior queda lista para volver atrás al instante.",
"eligible": "Esta app cumple los requisitos.",
- "turnOn": "Actívalo en Ajustes"
+ "turnOn": "Actívalo en Ajustes",
+ "restoreDb": "Restaurar la base de datos",
+ "restoreDbConfirm": "¿Restaurar {{databases}} a la copia tomada antes de que v{{version}} ejecutara su comando de publicación? Todo lo escrito en la base de datos desde entonces se pierde.",
+ "restoreDbConfirmButton": "Restaurar y perder lo escrito después",
+ "restoredDb": "Base de datos restaurada a antes de v{{version}}.",
+ "restoreDbFailed": "No se pudo restaurar la base de datos",
+ "restoreDbHint": "v{{version}} ejecutó su comando de publicación antes de volver atrás, así que la base de datos puede conservar sus cambios. El código volvió atrás; la base de datos no.",
+ "restoringDb": "Restaurando…"
},
"slotDeploysPanel": {
"title": "Despliegues por ranuras",
@@ -6830,7 +6837,14 @@
"standbyHint": "Mientras está lista, volver atrás tarda segundos. Después se detiene: deja de usar memoria, y volver atrás la arranca primero.",
"volumes": "Dos copias pueden compartir los volúmenes",
"volumesHint": "Durante unos segundos en cada cambio, las dos versiones montan los mismos volúmenes. Déjalo desactivado si la app guarda ahí algo como SQLite, que se rompe cuando dos procesos escriben a la vez.",
- "schemaRule": "Las dos versiones usan la misma base de datos durante el cambio. Mantén los cambios de esquema compatibles durante un despliegue: primero añade, despliega y elimina después."
+ "schemaRule": "Las dos versiones usan la misma base de datos durante el cambio. Mantén los cambios de esquema compatibles durante un despliegue: primero añade, despliega y elimina después.",
+ "release": "Comando de publicación",
+ "releaseHint": "Se ejecuta una vez en un contenedor desechable de la versión nueva, antes de cambiar el tráfico; por ejemplo, migraciones de base de datos. Si falla, el despliegue se detiene y la versión en vivo no se toca. Vacío usa la línea release: del Procfile o de serverkit.yaml, si existe.",
+ "snapshot": "Copiar las bases de datos antes",
+ "snapshotHint": "Vuelca las bases de datos de esta app antes de ejecutar el comando de publicación, para poder deshacer una migración después de volver atrás.",
+ "stopOld": "Detener la versión en vivo antes del comando de publicación",
+ "stopOldHint": "Para cambios de esquema que la versión en marcha no soporta. El sitio queda caído desde el comando de publicación hasta que la versión nueva pasa su comprobación de salud; si algo falla, la versión anterior vuelve a arrancar.",
+ "releasePlaceholder": "npm run migrate"
}
},
"auth": {
diff --git a/frontend/src/services/api/apps.js b/frontend/src/services/api/apps.js
index 734c9607..75064eea 100644
--- a/frontend/src/services/api/apps.js
+++ b/frontend/src/services/api/apps.js
@@ -588,3 +588,9 @@ export async function setAppSlots(appId, enabled) {
export async function switchBackAppSlot(appId) {
return this.request(`/apps/${appId}/slots/switch-back`, { method: 'POST' });
}
+
+export async function restoreAppSlotDatabase(appId, deploymentId) {
+ return this.request(`/apps/${appId}/slots/restore-db`, {
+ method: 'POST', body: { deployment_id: deploymentId },
+ });
+}
diff --git a/frontend/src/styles/pages/_bandwidth.scss b/frontend/src/styles/pages/_bandwidth.scss
index e57d2db4..fa24a66e 100644
--- a/frontend/src/styles/pages/_bandwidth.scss
+++ b/frontend/src/styles/pages/_bandwidth.scss
@@ -357,6 +357,16 @@
color: var(--text-dim);
}
+ &__restore {
+ display: flex;
+ flex-wrap: wrap;
+ align-items: center;
+ gap: 10px;
+ margin-top: 12px;
+ padding-top: 12px;
+ border-top: 1px solid var(--border-soft);
+ }
+
&__off {
display: flex;
flex-direction: column;