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(docker): horizontal auto-scaling (CPU thresholds, min/max, cooldown)

Juan Denis633c626d43fa
diff --git a/backend/app/api/apps.py b/backend/app/api/apps.py
index 2990d8e9..dcbaec90 100644
--- a/backend/app/api/apps.py
+++ b/backend/app/api/apps.py
@@ -15,6 +15,7 @@ from app.services.source_connection_service import SourceConnectionService
from app.services.remote_docker_service import RemoteDockerService
from app.services.image_update_service import ImageUpdateService
from app.services.container_sleep_service import ContainerSleepService
+from app.services.container_scale_service import ContainerScaleService
from app.services.log_service import LogService
from app.services.process_service import ProcessService
from app.services.upload_service import (
@@ -1277,6 +1278,72 @@ def sweep_idle_apps():
return jsonify(ContainerSleepService.sweep_idle())
+@apps_bp.route('/<int:app_id>/scale-policy', methods=['GET'])
+@jwt_required()
+def get_scale_policy(app_id):
+ app = Application.query.get(app_id)
+ if not app:
+ return jsonify({'error': 'Application not found'}), 404
+ return jsonify(ContainerScaleService.get_or_create_policy(app_id).to_dict())
+
+
+@apps_bp.route('/<int:app_id>/scale-policy', methods=['PUT'])
+@jwt_required()
+def update_scale_policy(app_id):
+ 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 {}
+ policy = ContainerScaleService.set_policy(app_id, **data)
+ return jsonify(policy.to_dict())
+
+
+@apps_bp.route('/<int:app_id>/scale', methods=['POST'])
+@jwt_required()
+def scale_app(app_id):
+ 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 data.get('replicas') is None:
+ return jsonify({'error': 'replicas is required'}), 400
+ result = ContainerScaleService.scale_to(app_id, data['replicas'])
+ if not result.get('success'):
+ return jsonify({'error': result['error']}), 400
+ return jsonify(result)
+
+
+@apps_bp.route('/<int:app_id>/scale/evaluate', methods=['POST'])
+@jwt_required()
+def evaluate_scale(app_id):
+ 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
+ result = ContainerScaleService.evaluate(app_id)
+ if not result.get('success'):
+ return jsonify({'error': result.get('error', 'Evaluation failed')}), 400
+ return jsonify(result)
+
+
+@apps_bp.route('/scale-sweep', methods=['POST'])
+@jwt_required()
+def scale_sweep():
+ """Evaluate every enabled auto-scaling policy. Intended for cron/scheduler."""
+ user = User.query.get(get_jwt_identity())
+ if not (user and user.is_admin):
+ return jsonify({'error': 'Admin access required'}), 403
+ return jsonify(ContainerScaleService.sweep())
+
+
@apps_bp.route('/<int:app_id>/stop', methods=['POST'])
@jwt_required()
def stop_app(app_id):
diff --git a/backend/app/models/container_scale_policy.py b/backend/app/models/container_scale_policy.py
new file mode 100644
index 00000000..407b7684
--- /dev/null
+++ b/backend/app/models/container_scale_policy.py
@@ -0,0 +1,40 @@
+from datetime import datetime
+from app import db
+
+
+class ContainerScalePolicy(db.Model):
+ """Per-application horizontal auto-scaling policy. When enabled, the named
+ compose service is scaled between min/max replicas based on average CPU,
+ with a cooldown between actions. Requires a scale-capable service (no fixed
+ host port or container_name). One row per application."""
+ __tablename__ = 'container_scale_policies'
+
+ id = db.Column(db.Integer, primary_key=True)
+ application_id = db.Column(db.Integer, db.ForeignKey('applications.id'),
+ nullable=False, unique=True, index=True)
+ enabled = db.Column(db.Boolean, default=False, nullable=False)
+ service_name = db.Column(db.String(100)) # compose service to scale
+ min_replicas = db.Column(db.Integer, default=1, nullable=False)
+ max_replicas = db.Column(db.Integer, default=3, nullable=False)
+ cpu_high_percent = db.Column(db.Integer, default=75, nullable=False)
+ cpu_low_percent = db.Column(db.Integer, default=25, nullable=False)
+ cooldown_seconds = db.Column(db.Integer, default=300, nullable=False)
+ current_replicas = db.Column(db.Integer, default=1, nullable=False)
+ last_scaled_at = db.Column(db.DateTime)
+ updated_at = db.Column(db.DateTime, default=datetime.utcnow, onupdate=datetime.utcnow)
+
+ application = db.relationship('Application', backref=db.backref('scale_policy', uselist=False))
+
+ def to_dict(self):
+ return {
+ 'application_id': self.application_id,
+ 'enabled': self.enabled,
+ 'service_name': self.service_name,
+ 'min_replicas': self.min_replicas,
+ 'max_replicas': self.max_replicas,
+ 'cpu_high_percent': self.cpu_high_percent,
+ 'cpu_low_percent': self.cpu_low_percent,
+ 'cooldown_seconds': self.cooldown_seconds,
+ 'current_replicas': self.current_replicas,
+ 'last_scaled_at': self.last_scaled_at.isoformat() if self.last_scaled_at else None,
+ }
diff --git a/backend/app/services/container_scale_service.py b/backend/app/services/container_scale_service.py
new file mode 100644
index 00000000..0e9a0113
--- /dev/null
+++ b/backend/app/services/container_scale_service.py
@@ -0,0 +1,148 @@
+"""Horizontal auto-scaling: adjust a compose service's replica count based on
+average CPU, within min/max bounds and a cooldown. Local apps only for now;
+the service must be scale-capable (no fixed host port or container_name)."""
+import logging
+import os
+import subprocess
+from datetime import datetime, timedelta
+
+from app import db
+from app.models import Application
+from app.models.container_scale_policy import ContainerScalePolicy
+
+logger = logging.getLogger(__name__)
+
+
+def _compose_path(app):
+ return os.path.join(app.root_path, app.compose_file or 'docker-compose.yml')
+
+
+class ContainerScaleService:
+
+ @staticmethod
+ def get_or_create_policy(application_id):
+ policy = ContainerScalePolicy.query.filter_by(application_id=application_id).first()
+ if not policy:
+ policy = ContainerScalePolicy(application_id=application_id)
+ db.session.add(policy)
+ db.session.commit()
+ return policy
+
+ @classmethod
+ def set_policy(cls, application_id, **fields):
+ policy = cls.get_or_create_policy(application_id)
+ if fields.get('enabled') is not None:
+ policy.enabled = bool(fields['enabled'])
+ if fields.get('service_name') is not None:
+ policy.service_name = (fields['service_name'] or '').strip() or None
+ for key in ('min_replicas', 'max_replicas', 'cpu_high_percent',
+ 'cpu_low_percent', 'cooldown_seconds'):
+ if fields.get(key) is not None:
+ setattr(policy, key, max(0, int(fields[key])))
+ policy.min_replicas = max(1, policy.min_replicas)
+ policy.max_replicas = max(policy.min_replicas, policy.max_replicas)
+ db.session.commit()
+ return policy
+
+ @classmethod
+ def _service_cpu(cls, app, policy):
+ """Average CPU% across the service's running containers, or None."""
+ try:
+ ps_cmd = ['docker', 'compose', '-f', _compose_path(app), 'ps', '-q']
+ if policy.service_name:
+ ps_cmd.append(policy.service_name)
+ ps = subprocess.run(ps_cmd, cwd=app.root_path, capture_output=True, text=True, timeout=15)
+ ids = [line.strip() for line in ps.stdout.splitlines() if line.strip()]
+ if not ids:
+ return None
+ stats = subprocess.run(['docker', 'stats', '--no-stream', '--format', '{{.CPUPerc}}'] + ids,
+ capture_output=True, text=True, timeout=15)
+ values = []
+ for line in stats.stdout.splitlines():
+ try:
+ values.append(float(line.strip().rstrip('%')))
+ except ValueError:
+ pass
+ return round(sum(values) / len(values), 1) if values else None
+ except Exception:
+ return None
+
+ @classmethod
+ def _apply_scale(cls, app, policy, replicas):
+ if app.server_id:
+ return {'success': False, 'error': 'Scaling is not yet supported for apps on remote servers'}
+ if not (app.app_type == 'docker' and app.root_path and policy.service_name):
+ return {'success': False, 'error': 'Scaling requires a docker-compose app with a service_name set'}
+ try:
+ result = subprocess.run(
+ ['docker', 'compose', '-f', _compose_path(app), 'up', '-d', '--no-recreate',
+ '--scale', f'{policy.service_name}={replicas}'],
+ cwd=app.root_path, capture_output=True, text=True, timeout=120)
+ if result.returncode != 0:
+ return {'success': False, 'error': (result.stderr or 'scale failed')[:300]}
+ return {'success': True}
+ except Exception as e:
+ return {'success': False, 'error': str(e)}
+
+ @classmethod
+ def scale_to(cls, application_id, replicas):
+ app = Application.query.get(application_id)
+ if not app:
+ return {'success': False, 'error': 'Application not found'}
+ policy = cls.get_or_create_policy(application_id)
+ replicas = max(1, int(replicas))
+ result = cls._apply_scale(app, policy, replicas)
+ if not result.get('success'):
+ return result
+ policy.current_replicas = replicas
+ policy.last_scaled_at = datetime.utcnow()
+ db.session.commit()
+ return {'success': True, 'replicas': replicas, 'policy': policy.to_dict()}
+
+ @classmethod
+ def evaluate(cls, application_id):
+ app = Application.query.get(application_id)
+ if not app:
+ return {'success': False, 'error': 'Application not found'}
+ policy = cls.get_or_create_policy(application_id)
+ if not policy.enabled:
+ return {'success': True, 'action': 'disabled', 'replicas': policy.current_replicas}
+
+ now = datetime.utcnow()
+ if policy.last_scaled_at and (now - policy.last_scaled_at) < timedelta(seconds=policy.cooldown_seconds):
+ return {'success': True, 'action': 'cooldown', 'replicas': policy.current_replicas}
+
+ cpu = cls._service_cpu(app, policy)
+ if cpu is None:
+ return {'success': True, 'action': 'unknown', 'replicas': policy.current_replicas}
+
+ current = policy.current_replicas
+ target = current
+ if cpu > policy.cpu_high_percent and current < policy.max_replicas:
+ target = current + 1
+ elif cpu < policy.cpu_low_percent and current > policy.min_replicas:
+ target = current - 1
+
+ if target == current:
+ return {'success': True, 'action': 'hold', 'replicas': current, 'cpu': cpu}
+
+ result = cls._apply_scale(app, policy, target)
+ if not result.get('success'):
+ return {'success': False, 'error': result['error'], 'replicas': current}
+ policy.current_replicas = target
+ policy.last_scaled_at = now
+ db.session.commit()
+ action = 'scaled_up' if target > current else 'scaled_down'
+ logger.info('Auto-scale %s: %s -> %s replicas (cpu=%.1f)', app.name, current, target, cpu)
+ return {'success': True, 'action': action, 'replicas': target, 'cpu': cpu}
+
+ @classmethod
+ def sweep(cls):
+ """Evaluate every enabled policy. Meant to run periodically."""
+ scaled = []
+ for policy in ContainerScalePolicy.query.filter_by(enabled=True).all():
+ result = cls.evaluate(policy.application_id)
+ if result.get('action') in ('scaled_up', 'scaled_down'):
+ scaled.append({'application_id': policy.application_id,
+ 'action': result['action'], 'replicas': result['replicas']})
+ return {'success': True, 'scaled': scaled}
diff --git a/backend/tests/test_container_scale.py b/backend/tests/test_container_scale.py
new file mode 100644
index 00000000..20cfc644
--- /dev/null
+++ b/backend/tests/test_container_scale.py
@@ -0,0 +1,109 @@
+"""Tests for container horizontal auto-scaling (decision logic)."""
+import uuid
+from datetime import datetime
+
+from app import db
+from app.models import Application
+from app.models.container_scale_policy import ContainerScalePolicy
+from app.services.container_scale_service import ContainerScaleService
+
+
+def _seed_app(**kw):
+ from app.models import User
+ uid = uuid.uuid4().hex[:8]
+ user = User(email=f'{uid}@t.local', username=f'u{uid}',
+ password_hash='x', role=User.ROLE_ADMIN, is_active=True)
+ db.session.add(user)
+ db.session.commit()
+ defaults = dict(name='web', app_type='docker', source='manual', root_path='/tmp/web',
+ compose_file='docker-compose.yml', docker_image='nginx:latest', user_id=user.id)
+ defaults.update(kw)
+ row = Application(**defaults)
+ db.session.add(row)
+ db.session.commit()
+ return row
+
+
+def _set_current(app_id, n):
+ p = ContainerScalePolicy.query.filter_by(application_id=app_id).first()
+ p.current_replicas = n
+ db.session.commit()
+ return p
+
+
+class TestScalePolicy:
+ def test_set_policy_clamps_bounds(self, app):
+ a = _seed_app()
+ p = ContainerScaleService.set_policy(a.id, enabled=True, service_name='web',
+ min_replicas=0, max_replicas=2)
+ assert p.enabled and p.service_name == 'web'
+ assert p.min_replicas == 1 and p.max_replicas == 2
+
+ def test_max_never_below_min(self, app):
+ a = _seed_app()
+ p = ContainerScaleService.set_policy(a.id, min_replicas=5, max_replicas=2)
+ assert p.max_replicas == 5
+
+
+class TestEvaluate:
+ def test_scales_up_on_high_cpu(self, app, monkeypatch):
+ a = _seed_app()
+ ContainerScaleService.set_policy(a.id, enabled=True, service_name='web',
+ min_replicas=1, max_replicas=3, cpu_high_percent=75, cooldown_seconds=0)
+ monkeypatch.setattr(ContainerScaleService, '_service_cpu', lambda app_, policy: 90.0)
+ monkeypatch.setattr(ContainerScaleService, '_apply_scale', lambda app_, policy, n: {'success': True})
+ r = ContainerScaleService.evaluate(a.id)
+ assert r['action'] == 'scaled_up' and r['replicas'] == 2
+
+ def test_scales_down_on_low_cpu(self, app, monkeypatch):
+ a = _seed_app()
+ ContainerScaleService.set_policy(a.id, enabled=True, service_name='web',
+ min_replicas=1, max_replicas=3, cpu_low_percent=25, cooldown_seconds=0)
+ _set_current(a.id, 2)
+ monkeypatch.setattr(ContainerScaleService, '_service_cpu', lambda app_, policy: 5.0)
+ monkeypatch.setattr(ContainerScaleService, '_apply_scale', lambda app_, policy, n: {'success': True})
+ r = ContainerScaleService.evaluate(a.id)
+ assert r['action'] == 'scaled_down' and r['replicas'] == 1
+
+ def test_holds_at_max(self, app, monkeypatch):
+ a = _seed_app()
+ ContainerScaleService.set_policy(a.id, enabled=True, service_name='web',
+ max_replicas=2, cpu_high_percent=75, cooldown_seconds=0)
+ _set_current(a.id, 2)
+ monkeypatch.setattr(ContainerScaleService, '_service_cpu', lambda app_, policy: 99.0)
+ r = ContainerScaleService.evaluate(a.id)
+ assert r['action'] == 'hold' and r['replicas'] == 2
+
+ def test_cooldown_blocks_action(self, app, monkeypatch):
+ a = _seed_app()
+ ContainerScaleService.set_policy(a.id, enabled=True, service_name='web', cooldown_seconds=300)
+ p = ContainerScalePolicy.query.filter_by(application_id=a.id).first()
+ p.last_scaled_at = datetime.utcnow()
+ db.session.commit()
+ monkeypatch.setattr(ContainerScaleService, '_service_cpu', lambda app_, policy: 99.0)
+ assert ContainerScaleService.evaluate(a.id)['action'] == 'cooldown'
+
+ def test_disabled_policy_is_noop(self, app):
+ a = _seed_app()
+ ContainerScaleService.set_policy(a.id, enabled=False)
+ assert ContainerScaleService.evaluate(a.id)['action'] == 'disabled'
+
+ def test_unknown_cpu_holds(self, app, monkeypatch):
+ a = _seed_app()
+ ContainerScaleService.set_policy(a.id, enabled=True, service_name='web', cooldown_seconds=0)
+ monkeypatch.setattr(ContainerScaleService, '_service_cpu', lambda app_, policy: None)
+ assert ContainerScaleService.evaluate(a.id)['action'] == 'unknown'
+
+
+class TestScaleApi:
+ def test_manual_scale_endpoint(self, client, auth_headers, app, monkeypatch):
+ from app.models import User
+ admin = User.query.filter_by(username='testadmin').first()
+ a = _seed_app(user_id=admin.id)
+ ContainerScaleService.set_policy(a.id, service_name='web')
+ monkeypatch.setattr(ContainerScaleService, '_apply_scale', lambda app_, policy, n: {'success': True})
+ resp = client.post(f'/api/v1/apps/{a.id}/scale', json={'replicas': 3}, headers=auth_headers)
+ assert resp.status_code == 200 and resp.get_json()['replicas'] == 3
+
+ def test_scale_sweep_requires_admin(self, client, app):
+ assert client.post('/api/v1/apps/scale-sweep').status_code == 401