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.

Give each app its own bucket and a scoped key

Juan Denisf23c7a5009d9
diff --git a/backend/app/api/app_attachments.py b/backend/app/api/app_attachments.py
new file mode 100644
index 00000000..ac5929d7
--- /dev/null
+++ b/backend/app/api/app_attachments.py
@@ -0,0 +1,77 @@
+# Bucket: PER-APP (plan 29 #9). Reads gate on can_access_app; attach/detach
+# gate on can_edit_app for the app AND can_access_app for the service used.
+"""Attach services an app uses (plan 86 §C2). Mounted under ``/api/v1/apps``.
+
+ GET /<app_id>/attachments — this app's attachments
+ GET /attachments/storage-services — installed storage it can use
+ POST /<app_id>/attachments/storage — {service_app_id}
+ DELETE /<app_id>/attachments/<attachment_id> — detach (keeps the bucket)
+
+Attach and detach change the app's env; it applies on the next deploy or
+restart, so responses say ``redeploy_required``.
+"""
+from flask import Blueprint, jsonify, request
+
+from app.exceptions import NotFoundError, ValidationError
+from app.middleware.rbac import developer_required, get_current_user, viewer_required
+from app.services.app_attachment_service import AppAttachmentService, AttachmentError
+from app.services.resource_grant_service import ResourceGrantService
+
+app_attachments_bp = Blueprint('app_attachments', __name__)
+
+
+@app_attachments_bp.route('/<int:app_id>/attachments', methods=['GET'])
+@viewer_required
+def list_attachments(app_id):
+ app = AppAttachmentService.live_app(app_id)
+ if app is None or not ResourceGrantService.can_access_app(get_current_user(), app):
+ raise NotFoundError('Application not found')
+ return jsonify({'attachments': [a.to_dict() for a in AppAttachmentService.list_for_app(app)]})
+
+
+@app_attachments_bp.route('/attachments/storage-services', methods=['GET'])
+@viewer_required
+def list_storage_services():
+ user = get_current_user()
+ services = [s for s in AppAttachmentService.storage_services()
+ if ResourceGrantService.can_access_app(user, s)]
+ return jsonify({'services': [{'id': s.id, 'name': s.name, 'status': s.status}
+ for s in services]})
+
+
+@app_attachments_bp.route('/<int:app_id>/attachments/storage', methods=['POST'])
+@developer_required
+def attach_storage(app_id):
+ user = get_current_user()
+ app = AppAttachmentService.live_app(app_id)
+ if app is None or not ResourceGrantService.can_edit_app(user, app):
+ raise NotFoundError('Application not found')
+ data = request.get_json(silent=True) or {}
+ service_app_id = data.get('service_app_id')
+ if not isinstance(service_app_id, int) or isinstance(service_app_id, bool):
+ raise ValidationError("'service_app_id' is required")
+ service = AppAttachmentService.live_app(service_app_id)
+ if service is None or not ResourceGrantService.can_access_app(user, service):
+ raise NotFoundError('Storage service not found')
+ try:
+ row, created = AppAttachmentService.attach_storage(app, service, user_id=user.id)
+ except AttachmentError as exc:
+ raise ValidationError(str(exc)) from exc
+ return jsonify({'attachment': row.to_dict(), 'redeploy_required': created}), (201 if created else 200)
+
+
+@app_attachments_bp.route('/<int:app_id>/attachments/<int:attachment_id>', methods=['DELETE'])
+@developer_required
+def detach(app_id, attachment_id):
+ user = get_current_user()
+ app = AppAttachmentService.live_app(app_id)
+ if app is None or not ResourceGrantService.can_edit_app(user, app):
+ raise NotFoundError('Application not found')
+ attachment = AppAttachmentService.get(app, attachment_id)
+ if attachment is None:
+ raise NotFoundError('Attachment not found')
+ warning = AppAttachmentService.detach(attachment, user_id=user.id)
+ body = {'success': True, 'redeploy_required': True}
+ if warning:
+ body['warning'] = warning
+ return jsonify(body)
diff --git a/backend/app/core_blueprints.py b/backend/app/core_blueprints.py
index 73cdef21..4ec86188 100644
--- a/backend/app/core_blueprints.py
+++ b/backend/app/core_blueprints.py
@@ -52,6 +52,7 @@ CORE_BLUEPRINTS: tuple[BlueprintSpec, ...] = (
BlueprintSpec('app.api.domains', 'domains_bp', '/api/v1/domains'),
BlueprintSpec('app.api.private_urls', 'private_urls_bp', '/api/v1/apps'),
BlueprintSpec('app.api.app_volumes', 'app_volumes_bp', '/api/v1/apps'),
+ BlueprintSpec('app.api.app_attachments', 'app_attachments_bp', '/api/v1/apps'),
BlueprintSpec(
'app.api.app_volumes',
'app_volumes_bp',
diff --git a/backend/app/models/__init__.py b/backend/app/models/__init__.py
index a9cfa9f6..f8eeb194 100644
--- a/backend/app/models/__init__.py
+++ b/backend/app/models/__init__.py
@@ -83,6 +83,7 @@ from app.models.managed_database_user import ManagedDatabaseUser
from app.models.site_import import SiteImport
from app.models.site_bandwidth import SiteBandwidthDaily
from app.models.app_request_metric import AppRequestMetric
+from app.models.app_attachment import AppAttachment
from app.models.cron_run import CronRun
from app.models.fleet_doctor_result import FleetDoctorResult
from app.models.server_survey import ServerSurvey
@@ -140,6 +141,7 @@ __all__ = [
'CronRun',
'SiteBandwidthDaily',
'AppRequestMetric',
+ 'AppAttachment',
'FleetDoctorResult',
'ServerSurvey',
'DnsCutoverSnapshot',
diff --git a/backend/app/models/app_attachment.py b/backend/app/models/app_attachment.py
new file mode 100644
index 00000000..69150718
--- /dev/null
+++ b/backend/app/models/app_attachment.py
@@ -0,0 +1,64 @@
+"""An app's attachment to a service it uses (plan 86 §C2/§C4).
+
+One row per (app, kind): the app's storage bucket on a Garage instance today;
+cache, queue and tracing attachments reuse the same row. ``details_json``
+holds what the provisioner created (bucket, key id, the vault secret that
+carries the key), so detaching can remove exactly that and nothing else. The
+secret itself never lands here.
+
+Both foreign keys have parent-side cascades: deleting either the app or the
+service it is attached to takes the attachment row with it.
+"""
+from datetime import datetime
+
+from app import db
+from app.models.json_column_mixin import JsonColumnMixin
+
+
+class AppAttachment(JsonColumnMixin, db.Model):
+ __tablename__ = 'app_attachments'
+ __table_args__ = (
+ db.UniqueConstraint('app_id', 'kind', name='uq_app_attachments_app_kind'),
+ )
+
+ KINDS = ('storage',)
+
+ id = db.Column(db.Integer, primary_key=True)
+ app_id = db.Column(db.Integer, db.ForeignKey('applications.id', ondelete='CASCADE'),
+ nullable=False, index=True)
+ service_app_id = db.Column(db.Integer, db.ForeignKey('applications.id', ondelete='CASCADE'),
+ nullable=False, index=True)
+ kind = db.Column(db.String(16), nullable=False)
+ details_json = db.Column(db.Text)
+ created_at = db.Column(db.DateTime, default=datetime.utcnow)
+
+ application = db.relationship(
+ 'Application', foreign_keys=[app_id],
+ backref=db.backref('attachments', cascade='all, delete-orphan',
+ lazy='select'))
+ service_app = db.relationship(
+ 'Application', foreign_keys=[service_app_id],
+ backref=db.backref('attached_by', cascade='all, delete-orphan',
+ lazy='select'))
+
+ @property
+ def details(self):
+ return self._json_read('details_json', {}, expect=dict)
+
+ @details.setter
+ def details(self, value):
+ self._json_write('details_json', value)
+
+ def to_dict(self):
+ details = self.details
+ return {
+ 'id': self.id,
+ 'app_id': self.app_id,
+ 'kind': self.kind,
+ 'service_app_id': self.service_app_id,
+ 'service_name': self.service_app.name if self.service_app else None,
+ # Never the secret; the key id alone is safe to show.
+ 'bucket': details.get('bucket'),
+ 'access_key_id': details.get('access_key_id'),
+ 'created_at': self.created_at.isoformat() if self.created_at else None,
+ }
diff --git a/backend/app/services/app_attachment_service.py b/backend/app/services/app_attachment_service.py
new file mode 100644
index 00000000..86842511
--- /dev/null
+++ b/backend/app/services/app_attachment_service.py
@@ -0,0 +1,188 @@
+"""Attach a service an app uses: object storage today (plan 86 §C2).
+
+"Attach storage" gives an app its own bucket on an installed Garage and a key
+that can read and write that bucket only (never the admin token, never another
+bucket). The app receives it through the same env-reference doors everything
+else uses:
+
+ * ``S3_ENDPOINT`` / ``S3_REGION`` → ``fromService`` (C1 properties), reached
+ over the shared service network;
+ * ``S3_BUCKET`` / ``S3_ACCESS_KEY_ID`` → plain values;
+ * ``S3_SECRET_ACCESS_KEY`` → ``fromSecret``, stored encrypted in an internal
+ vault. The ``AWS_*`` names most S3 SDKs read resolve the same way.
+
+Nothing is redeployed here; the caller decides (the new env reaches the app on
+its next deploy or restart). Detaching deletes the key, its secret and the env
+vars the attach wrote, and keeps the bucket and its objects. Data is never
+deleted by a detach.
+"""
+import re
+from typing import Dict, Tuple
+
+from app import db
+
+VAULT_SLUG = 'serverkit-attachments'
+VAULT_NAME = 'Service attachments'
+
+
+class AttachmentError(Exception):
+ pass
+
+
+def _bucket_name(app_name: str) -> str:
+ """S3 bucket naming: 3-63 chars of [a-z0-9-], starting and ending alnum."""
+ name = re.sub(r'[^a-z0-9-]+', '-', (app_name or '').lower()).strip('-')
+ name = re.sub(r'-{2,}', '-', name)[:63].strip('-')
+ return name if len(name) >= 3 else f'app-{name}'.strip('-')
+
+
+def _storage_env(service_name: str, bucket: str, access_key_id: str,
+ secret_ref: str) -> Dict[str, Tuple[str, object]]:
+ """key -> ('ref', reference) | ('value', text)."""
+ endpoint = ('ref', {'kind': 'service', 'service': service_name, 'property': 'endpoint'})
+ region = ('ref', {'kind': 'service', 'service': service_name, 'property': 'region'})
+ secret = ('ref', {'kind': 'secret', 'secret': secret_ref})
+ return {
+ 'S3_ENDPOINT': endpoint, 'AWS_ENDPOINT_URL': endpoint,
+ 'S3_REGION': region, 'AWS_REGION': region,
+ 'S3_BUCKET': ('value', bucket),
+ 'S3_ACCESS_KEY_ID': ('value', access_key_id),
+ 'AWS_ACCESS_KEY_ID': ('value', access_key_id),
+ 'S3_SECRET_ACCESS_KEY': secret, 'AWS_SECRET_ACCESS_KEY': secret,
+ }
+
+
+class AppAttachmentService:
+
+ @staticmethod
+ def live_app(app_id):
+ from app.models.application import Application
+ return Application.query_active().filter_by(id=app_id).first()
+
+ @staticmethod
+ def list_for_app(app):
+ from app.models.app_attachment import AppAttachment
+ return AppAttachment.query.filter_by(app_id=app.id).order_by(AppAttachment.id).all()
+
+ @staticmethod
+ def get(app, attachment_id):
+ from app.models.app_attachment import AppAttachment
+ return AppAttachment.query.filter_by(id=attachment_id, app_id=app.id).first()
+
+ @staticmethod
+ def _provisioner(service_app):
+ from app.services.service_connection_service import _template_for
+ template = _template_for(service_app) or {}
+ connection = template.get('connection') if isinstance(template.get('connection'), dict) else {}
+ return connection.get('provisioner')
+
+ @classmethod
+ def storage_services(cls):
+ """Installed services that can hand out per-app buckets."""
+ from app.models.application import Application
+ return [a for a in Application.query_active().order_by(Application.name).all()
+ if cls._provisioner(a) == 'garage']
+
+ # -- storage ---------------------------------------------------------------
+
+ @classmethod
+ def attach_storage(cls, app, service_app, user_id=None, admin=None):
+ """Bucket + scoped key for ``app`` on ``service_app``. Idempotent: an
+ app already attached to the same service gets its existing row back."""
+ from app.models.app_attachment import AppAttachment
+ from app.services.env_service import EnvService
+ from app.services.garage_admin import GarageAdmin, GarageError
+
+ if service_app.id == app.id:
+ raise AttachmentError('A service cannot be attached to itself')
+ if cls._provisioner(service_app) != 'garage':
+ raise AttachmentError(f'{service_app.name} is not an object storage service')
+ existing = AppAttachment.query.filter_by(app_id=app.id, kind='storage').first()
+ if existing is not None:
+ if existing.service_app_id != service_app.id:
+ raise AttachmentError('This app already has storage attached; detach it first')
+ return existing, False
+
+ admin = admin or GarageAdmin(service_app.name)
+ bucket = _bucket_name(app.name)
+ try:
+ admin.ensure_layout()
+ bucket_id = admin.ensure_bucket(bucket)
+ key = admin.create_key(f'serverkit-{app.name}')
+ admin.allow(bucket_id, key['access_key_id'])
+ except GarageError as exc:
+ raise AttachmentError(f'Storage setup failed: {exc}') from exc
+
+ secret_name = f'{app.name}.s3-secret-key'
+ cls._store_secret(secret_name, key['secret_access_key'], user_id)
+
+ env = _storage_env(service_app.name, bucket, key['access_key_id'],
+ f'{VAULT_SLUG}/{secret_name}')
+ for env_key, (mode, value) in env.items():
+ if mode == 'ref':
+ _v, _c, error = EnvService.set_env_reference(app.id, env_key, value, user_id=user_id)
+ else:
+ _v, _c, error = EnvService.set_env_var(app.id, env_key, value, user_id=user_id)
+ if error:
+ raise AttachmentError(f'Could not set {env_key}: {error}')
+
+ row = AppAttachment(app_id=app.id, service_app_id=service_app.id, kind='storage')
+ row.details = {'bucket': bucket, 'bucket_id': bucket_id,
+ 'access_key_id': key['access_key_id'],
+ 'secret_name': secret_name, 'env_keys': sorted(env)}
+ db.session.add(row)
+ db.session.commit()
+ return row, True
+
+ @classmethod
+ def detach(cls, attachment, user_id=None, admin=None):
+ """Remove the key, its secret and the env the attach wrote. Keeps the
+ bucket and its data."""
+ from app.services.env_service import EnvService
+ from app.services.garage_admin import GarageAdmin, GarageError
+
+ details = attachment.details
+ warning = None
+ if attachment.kind == 'storage' and details.get('access_key_id'):
+ admin = admin or GarageAdmin(attachment.service_app.name)
+ try:
+ admin.delete_key(details['access_key_id'])
+ except GarageError as exc:
+ # The service may already be gone or stopped; the key is
+ # useless without the env, and the row must still go.
+ warning = f'Key could not be revoked on {attachment.service_app.name}: {exc}'
+ for env_key in details.get('env_keys') or []:
+ EnvService.delete_env_var(attachment.app_id, env_key, user_id=user_id)
+ if details.get('secret_name'):
+ cls._delete_secret(details['secret_name'])
+ db.session.delete(attachment)
+ db.session.commit()
+ return warning
+
+ # -- internal vault ----------------------------------------------------------
+
+ @staticmethod
+ def _vault(user_id=None):
+ from app.models.secret_vault import SecretVault
+ vault = SecretVault.query.filter_by(slug=VAULT_SLUG).first()
+ if vault is None:
+ vault = SecretVault(name=VAULT_NAME, slug=VAULT_SLUG, created_by=user_id,
+ description='Keys ServerKit created when attaching a service to an app')
+ db.session.add(vault)
+ db.session.flush()
+ return vault
+
+ @classmethod
+ def _store_secret(cls, name, value, user_id=None):
+ from app.services.secret_vault_service import SecretService
+ SecretService.upsert_internal_secret(
+ cls._vault(user_id).id, name, value,
+ description='S3 secret key for an attached storage bucket')
+
+ @staticmethod
+ def _delete_secret(name):
+ from app.models.secret_vault import Secret, SecretVault
+ vault = SecretVault.query.filter_by(slug=VAULT_SLUG).first()
+ if vault is None:
+ return
+ Secret.query.filter_by(vault_id=vault.id, name=name).delete()
diff --git a/backend/app/services/garage_admin.py b/backend/app/services/garage_admin.py
new file mode 100644
index 00000000..0491b341
--- /dev/null
+++ b/backend/app/services/garage_admin.py
@@ -0,0 +1,93 @@
+"""Garage admin operations through its own CLI (plan 86 §C2).
+
+``garage json-api <Endpoint> <payload>`` invokes the admin API over the node's
+RPC socket and prints the JSON result, so the panel drives Garage with
+``docker exec`` — no admin port to publish, no token to handle, and structured
+output instead of scraped CLI text. Garage logs go to stderr; stdout is the
+JSON answer.
+"""
+import json
+from typing import Any, Dict, Optional
+
+
+class GarageError(Exception):
+ pass
+
+
+# One node, one zone. Capacity is the layout's accounting number, not a
+# quota; a large value keeps the single node from ever reading as "full".
+LAYOUT_ZONE = 'dc1'
+LAYOUT_CAPACITY = 1 << 40
+
+
+class GarageAdmin:
+ def __init__(self, container: str):
+ self.container = container
+
+ def call(self, endpoint: str, payload: Optional[Dict[str, Any]] = None) -> Any:
+ from app.services.docker_service import DockerService
+
+ argv = ['exec', self.container, '/garage', 'json-api', endpoint]
+ if payload is not None:
+ argv.append(json.dumps(payload))
+ result = DockerService.run(argv, timeout=60)
+ if not result.get('success'):
+ detail = (result.get('stderr') or result.get('error') or '').strip()
+ raise GarageError(f'{endpoint} failed: {detail.splitlines()[-1] if detail else "no output"}')
+ try:
+ return json.loads(result.get('output') or 'null')
+ except ValueError as exc:
+ raise GarageError(f'{endpoint} returned non-JSON output') from exc
+
+ # -- cluster -------------------------------------------------------------
+
+ def ensure_layout(self) -> bool:
+ """Give the single node a role once. Returns True when it applied one.
+
+ A fresh Garage node has no layout and refuses every bucket operation
+ until one is applied; later calls are no-ops.
+ """
+ status = self.call('GetClusterStatus') or {}
+ if int(status.get('layoutVersion') or 0) > 0:
+ return False
+ nodes = status.get('nodes') or []
+ if not nodes:
+ raise GarageError('Garage reports no nodes')
+ self.call('UpdateClusterLayout', {'roles': [{
+ 'id': nodes[0]['id'], 'zone': LAYOUT_ZONE,
+ 'capacity': LAYOUT_CAPACITY, 'tags': [],
+ }]})
+ self.call('ApplyClusterLayout', {'version': 1})
+ return True
+
+ # -- buckets and keys ----------------------------------------------------
+
+ def ensure_bucket(self, alias: str) -> str:
+ """The id of the bucket named ``alias``, creating it when missing."""
+ try:
+ info = self.call('GetBucketInfo', {'globalAlias': alias})
+ if info and info.get('id'):
+ return info['id']
+ except GarageError:
+ pass
+ created = self.call('CreateBucket', {'globalAlias': alias}) or {}
+ if not created.get('id'):
+ raise GarageError(f'could not create bucket {alias}')
+ return created['id']
+
+ def create_key(self, name: str) -> Dict[str, str]:
+ created = self.call('CreateKey', {'name': name}) or {}
+ if not created.get('accessKeyId') or not created.get('secretAccessKey'):
+ raise GarageError('CreateKey returned no key')
+ return {'access_key_id': created['accessKeyId'],
+ 'secret_access_key': created['secretAccessKey']}
+
+ def allow(self, bucket_id: str, access_key_id: str) -> None:
+ """Read and write on one bucket; never owner (no bucket admin)."""
+ self.call('AllowBucketKey', {
+ 'bucketId': bucket_id, 'accessKeyId': access_key_id,
+ 'permissions': {'read': True, 'write': True, 'owner': False},
+ })
+
+ def delete_key(self, access_key_id: str) -> None:
+ self.call('DeleteKey', {'id': access_key_id})
diff --git a/backend/migrations/versions/102_app_attachments.py b/backend/migrations/versions/102_app_attachments.py
new file mode 100644
index 00000000..777e1ceb
--- /dev/null
+++ b/backend/migrations/versions/102_app_attachments.py
@@ -0,0 +1,34 @@
+"""App attachments to services they use (plan 86 §C2)."""
+from alembic import op
+import sqlalchemy as sa
+
+revision = '102_app_attachments'
+down_revision = '101_micro_cache_ttl'
+branch_labels = None
+depends_on = None
+
+
+def upgrade():
+ inspector = sa.inspect(op.get_bind())
+ if 'app_attachments' in inspector.get_table_names():
+ return
+ op.create_table(
+ 'app_attachments',
+ sa.Column('id', sa.Integer, primary_key=True),
+ sa.Column('app_id', sa.Integer,
+ sa.ForeignKey('applications.id', ondelete='CASCADE'), nullable=False),
+ sa.Column('service_app_id', sa.Integer,
+ sa.ForeignKey('applications.id', ondelete='CASCADE'), nullable=False),
+ sa.Column('kind', sa.String(16), nullable=False),
+ sa.Column('details_json', sa.Text),
+ sa.Column('created_at', sa.DateTime),
+ sa.UniqueConstraint('app_id', 'kind', name='uq_app_attachments_app_kind'),
+ )
+ op.create_index('ix_app_attachments_app_id', 'app_attachments', ['app_id'])
+ op.create_index('ix_app_attachments_service_app_id', 'app_attachments', ['service_app_id'])
+
+
+def downgrade():
+ op.drop_index('ix_app_attachments_service_app_id', table_name='app_attachments')
+ op.drop_index('ix_app_attachments_app_id', table_name='app_attachments')
+ op.drop_table('app_attachments')
diff --git a/backend/templates/garage.yaml b/backend/templates/garage.yaml
new file mode 100644
index 00000000..6e84c3db
--- /dev/null
+++ b/backend/templates/garage.yaml
@@ -0,0 +1,103 @@
+id: garage
+name: Garage
+version: "2.1.0"
+description: Lightweight S3-compatible object storage. Give each app its own bucket and a key that can only reach it.
+icon: https://serverkit.ai/imgs/template-icons/garage.svg
+website: https://garagehq.deuxfleurs.fr
+documentation: https://garagehq.deuxfleurs.fr/documentation/
+categories:
+ - storage
+ - s3
+
+variables:
+ - name: API_PORT
+ description: Host port for the S3 API
+ type: port
+ default: "3900"
+ hidden: true
+ - name: BIND_ADDRESS
+ type: string
+ default: 127.0.0.1
+ hidden: true
+ description: Address the S3 port binds to. 127.0.0.1 keeps it private; apps reach it over the shared service network.
+ - name: RPC_SECRET
+ description: Cluster RPC secret (32 bytes, hex)
+ type: random
+ length: 64
+ hidden: true
+ - name: ADMIN_TOKEN
+ description: Admin API token
+ type: password
+ length: 40
+ hidden: true
+
+# What an app gets through `fromService`, reachable over the shared service
+# network by container name. Keys are not offered here: "Attach storage"
+# creates a bucket and a key scoped to it for each app.
+connection:
+ port: 3900
+ provisioner: garage
+ properties:
+ endpoint: "http://{host}:{port}"
+ region: garage
+
+files:
+ - path: /etc/garage.toml
+ mode: 0600
+ content: |
+ metadata_dir = "/var/lib/garage/meta"
+ data_dir = "/var/lib/garage/data"
+ db_engine = "sqlite"
+ replication_factor = 1
+ rpc_bind_addr = "[::]:3901"
+ rpc_public_addr = "127.0.0.1:3901"
+ rpc_secret = "${RPC_SECRET}"
+
+ [s3_api]
+ s3_region = "garage"
+ api_bind_addr = "[::]:3900"
+
+ [admin]
+ api_bind_addr = "[::]:3903"
+ admin_token = "${ADMIN_TOKEN}"
+
+ports:
+ - port: "${API_PORT}"
+ protocol: tcp
+ description: S3 API
+
+volumes:
+ - name: meta
+ path: /var/lib/garage/meta
+ description: Object metadata
+ - name: data
+ path: /var/lib/garage/data
+ description: Object data
+
+requirements:
+ memory: 256MB
+ storage: 10GB
+
+compose:
+ services:
+ garage:
+ image: dxflrs/garage:v2.1.0
+ container_name: ${APP_NAME}
+ restart: unless-stopped
+ ports:
+ - "${BIND_ADDRESS}:${API_PORT}:3900"
+ volumes:
+ - garage_meta:/var/lib/garage/meta
+ - garage_data:/var/lib/garage/data
+ healthcheck:
+ # The image is a single static binary (no shell), so the check is the
+ # garage CLI itself: it succeeds once the node answers RPC.
+ test: ["CMD", "/garage", "status"]
+ interval: 30s
+ timeout: 10s
+ retries: 3
+ start_period: 10s
+
+ volumes:
+ garage_meta:
+ garage_data:
diff --git a/backend/tests/test_app_attachments.py b/backend/tests/test_app_attachments.py
new file mode 100644
index 00000000..61b24ccb
--- /dev/null
+++ b/backend/tests/test_app_attachments.py
@@ -0,0 +1,190 @@
+"""Attach storage: bucket + scoped key per app (plan 86 §C2).
+
+Hermetic: a fake Garage admin records calls. The real-Garage round trip
+(write own bucket, refused elsewhere, key revoked on detach) is the
+docker-builds leg in test_real_storage_attach_docker.py.
+"""
+import json
+
+import pytest
+import yaml
+
+from app import db
+from app.models import Application
+from app.models.app_attachment import AppAttachment
+from app.models.secret_vault import Secret, SecretVault
+from app.services import app_attachment_service as svc
+from app.services.app_attachment_service import AppAttachmentService, AttachmentError
+from app.services.env_service import EnvService
+from app.services.template_service import TemplateService
+from tests.factories import make_application
+
+
+class FakeGarage:
+ def __init__(self):
+ self.calls = []
+ self.buckets = {}
+
+ def ensure_layout(self):
+ self.calls.append(('layout',))
+ return True
+
+ def ensure_bucket(self, alias):
+ self.calls.append(('bucket', alias))
+ return self.buckets.setdefault(alias, f'id-{alias}')
+
+ def create_key(self, name):
+ self.calls.append(('key', name))
+ return {'access_key_id': 'GKabc', 'secret_access_key': 'topsecret'}
+
+ def allow(self, bucket_id, access_key_id):
+ self.calls.append(('allow', bucket_id, access_key_id))
+
+ def delete_key(self, access_key_id):
+ self.calls.append(('delete', access_key_id))
+
+
+def installed(app, tmp_path, monkeypatch):
+ records = {}
+ monkeypatch.setattr(TemplateService, 'get_config', classmethod(
+ lambda cls: {'repos': [], 'installed': records}))
+
+ def make(name, template_id=None):
+ root = tmp_path / name
+ root.mkdir()
+ (root / 'docker-compose.yml').write_text(yaml.safe_dump({'services': {name: {'image': 'x'}}}))
+ if template_id:
+ (root / '.serverkit-template.json').write_text(json.dumps(
+ {'template_id': template_id, 'variables': {}}))
+ row = make_application(db, name=name, root_path=str(root))
+ if template_id:
+ records[str(row.id)] = {'template_id': template_id}
+ return row
+ return make
+
+
+def test_attach_creates_scoped_key_and_wires_env(installed):
+ store, web = installed('store', 'garage'), installed('Web_App')
+ fake = FakeGarage()
+
+ row, created = AppAttachmentService.attach_storage(web, store, admin=fake)
+
+ assert created
+ assert fake.calls == [('layout',), ('bucket', 'web-app'), ('key', 'serverkit-Web_App'),
+ ('allow', 'id-web-app', 'GKabc')]
+ env = EnvService.get_effective_env(web.id)
+ assert env['S3_BUCKET'] == 'web-app'
+ assert env['S3_ENDPOINT'] == env['AWS_ENDPOINT_URL'] == 'http://store:3900'
+ assert env['S3_REGION'] == 'garage'
+ assert env['S3_ACCESS_KEY_ID'] == env['AWS_ACCESS_KEY_ID'] == 'GKabc'
+ assert env['S3_SECRET_ACCESS_KEY'] == env['AWS_SECRET_ACCESS_KEY'] == 'topsecret'
+ # The secret lives encrypted in the vault, not in the env row or attachment.
+ stored = EnvService.get_env_var(web.id, 'S3_SECRET_ACCESS_KEY')
+ assert stored.value_from and 'topsecret' not in (stored.encrypted_value or '')
+ assert 'topsecret' not in json.dumps(row.to_dict()) + (row.details_json or '')
+
+
+def test_attach_is_idempotent_and_refuses_a_second_service(installed):
+ store, other, web = installed('store', 'garage'), installed('store2', 'garage'), installed('web')
+ fake = FakeGarage()
+ first, _ = AppAttachmentService.attach_storage(web, store, admin=fake)
+ again, created = AppAttachmentService.attach_storage(web, store, admin=fake)
+ assert again.id == first.id and not created
+ assert [c for c in fake.calls if c[0] == 'key'] == [('key', 'serverkit-web')]
+ with pytest.raises(AttachmentError, match='already has storage'):
+ AppAttachmentService.attach_storage(web, other, admin=fake)
+
+
[email protected]('template_id', [None, 'redis'])
+def test_only_a_storage_provisioner_can_be_attached(installed, template_id):
+ target, web = installed('target', template_id), installed('web')
+ with pytest.raises(AttachmentError, match='not an object storage'):
+ AppAttachmentService.attach_storage(web, target, admin=FakeGarage())
+
+
+def test_detach_revokes_the_key_and_removes_env_and_secret(installed):
+ store, web = installed('store', 'garage'), installed('web')
+ fake = FakeGarage()
+ row, _ = AppAttachmentService.attach_storage(web, store, admin=fake)
+ EnvService.set_env_var(web.id, 'UNRELATED', 'keep')
+
+ assert AppAttachmentService.detach(row, admin=fake) is None
+
+ assert ('delete', 'GKabc') in fake.calls
+ env = EnvService.get_effective_env(web.id)
+ assert not any(k.startswith(('S3_', 'AWS_')) for k in env)
+ assert env['UNRELATED'] == 'keep'
+ vault = SecretVault.query.filter_by(slug=svc.VAULT_SLUG).first()
+ assert Secret.query.filter_by(vault_id=vault.id).count() == 0
+ assert AppAttachment.query.count() == 0
+
+
+def test_detach_still_cleans_up_when_the_service_is_unreachable(installed):
+ from app.services.garage_admin import GarageError
+
+ class Down(FakeGarage):
+ def delete_key(self, access_key_id):
+ raise GarageError('container not running')
+
+ store, web = installed('store', 'garage'), installed('web')
+ row, _ = AppAttachmentService.attach_storage(web, store, admin=FakeGarage())
+ warning = AppAttachmentService.detach(row, admin=Down())
+ assert 'could not be revoked' in warning
+ assert AppAttachment.query.count() == 0
+
+
[email protected]('name,bucket', [
+ ('Shop', 'shop'), ('my_app.v2', 'my-app-v2'), ('a', 'app-a'),
+ ('--x--', 'app-x'), ('a' * 80, 'a' * 63),
+])
+def test_bucket_names_are_s3_valid(name, bucket):
+ assert svc._bucket_name(name) == bucket
+
+
+# ── API ──────────────────────────────────────────────────────────────────────
+
+def test_api_attach_list_detach(installed, client, auth_headers, monkeypatch):
+ store, web = installed('store', 'garage'), installed('web')
+ fake = FakeGarage()
+ monkeypatch.setattr(svc, 'GarageAdmin', lambda name: fake, raising=False)
+ monkeypatch.setattr('app.services.garage_admin.GarageAdmin', lambda name: fake)
+
+ services = client.get('/api/v1/apps/attachments/storage-services', headers=auth_headers)
+ assert [s['name'] for s in services.get_json()['services']] == ['store']
+
+ made = client.post(f'/api/v1/apps/{web.id}/attachments/storage',
+ json={'service_app_id': store.id}, headers=auth_headers)
+ assert made.status_code == 201, made.get_json()
+ body = made.get_json()
+ assert body['redeploy_required'] is True
+ assert body['attachment']['bucket'] == 'web'
+ assert 'secret' not in json.dumps(body).lower().replace('s3_secret', '')
+
+ listed = client.get(f'/api/v1/apps/{web.id}/attachments', headers=auth_headers)
+ assert [a['id'] for a in listed.get_json()['attachments']] == [body['attachment']['id']]
+
+ gone = client.delete(f"/api/v1/apps/{web.id}/attachments/{body['attachment']['id']}",
+ headers=auth_headers)
+ assert gone.status_code == 200
+ assert client.get(f'/api/v1/apps/{web.id}/attachments',
+ headers=auth_headers).get_json()['attachments'] == []
+
+
+def test_api_rejects_bad_input(installed, client, auth_headers):
+ web, plain = installed('web'), installed('plain')
+ url = f'/api/v1/apps/{web.id}/attachments/storage'
+ assert client.post(url, json={}, headers=auth_headers).status_code == 400
+ assert client.post(url, json={'service_app_id': 999999}, headers=auth_headers).status_code == 404
+ assert client.post(url, json={'service_app_id': plain.id},
+ headers=auth_headers).status_code == 400
+ assert client.post('/api/v1/apps/999999/attachments/storage', json={'service_app_id': plain.id},
+ headers=auth_headers).status_code == 404
+
+
+def test_deleting_either_app_takes_the_attachment(installed):
+ store, web = installed('store', 'garage'), installed('web')
+ AppAttachmentService.attach_storage(web, store, admin=FakeGarage())
+ db.session.delete(Application.query.get(store.id))
+ db.session.commit()
+ assert AppAttachment.query.count() == 0
diff --git a/backend/tests/test_core_blueprint_registry.py b/backend/tests/test_core_blueprint_registry.py
index bd854123..67b86a10 100644
--- a/backend/tests/test_core_blueprint_registry.py
+++ b/backend/tests/test_core_blueprint_registry.py
@@ -7,9 +7,9 @@ from pathlib import Path
from app.core_blueprints import CORE_BLUEPRINTS
-EXPECTED_CORE_BLUEPRINT_COUNT = 113
+EXPECTED_CORE_BLUEPRINT_COUNT = 114
EXPECTED_MANIFEST_SHA256 = (
- '55cd5d9a732e1ed2301774ef4462e1424dea408ae4e192a1e177688570bf95d4'
+ 'e47b705607af322a1e1c18c736051165c30dcfe8b8c1b912a0586dfefb885ab1'
)
diff --git a/backend/tests/test_real_storage_attach_docker.py b/backend/tests/test_real_storage_attach_docker.py
new file mode 100644
index 00000000..080af137
--- /dev/null
+++ b/backend/tests/test_real_storage_attach_docker.py
@@ -0,0 +1,166 @@
+"""Attach storage against a REAL Garage (plan 86 §C2).
+
+The bundled Garage template is rendered with the panel's own variable and
+file rules and started with its managed override. Attaching gives an app a
+bucket and a scoped key; a separate project that has only the env the
+attach wrote can write and read its own bucket, is refused on another
+bucket, and after a detach the same key is refused everywhere.
+
+Gated with the other docker legs (pulls images):
+
+ SERVERKIT_DOCKER_BUILDS=1 pytest tests -m docker_builds
+"""
+import json
+import os
+import shutil
+import subprocess
+import time
+import uuid
+
+import pytest
+import yaml
+
+from app import db
+from app.services.app_attachment_service import AppAttachmentService
+from app.services.compose_env_service import ComposeEnvService
+from app.services.env_service import EnvService
+from app.services.garage_admin import GarageAdmin, GarageError
+from app.services.template_service import TemplateService
+from tests.factories import make_application
+
+
+def _docker_ready() -> bool:
+ if shutil.which('docker') is None:
+ return False
+ try:
+ return subprocess.run(['docker', 'info'], capture_output=True,
+ timeout=20).returncode == 0
+ except (OSError, subprocess.TimeoutExpired):
+ return False
+
+
+pytestmark = [
+ pytest.mark.docker_builds,
+ pytest.mark.skipif(os.environ.get('SERVERKIT_DOCKER_BUILDS') != '1',
+ reason='docker-builds leg; opt in with SERVERKIT_DOCKER_BUILDS=1'),
+ pytest.mark.skipif(not _docker_ready(), reason='docker daemon not reachable'),
+]
+
+PROBE = r'''
+import os, sys, boto3, botocore
+cfg = dict(endpoint_url=os.environ["S3_ENDPOINT"], region_name=os.environ["S3_REGION"],
+ aws_access_key_id=os.environ["S3_ACCESS_KEY_ID"],
+ aws_secret_access_key=os.environ["S3_SECRET_ACCESS_KEY"])
+s3 = boto3.client("s3", **cfg)
+def attempt(fn):
+ try:
+ fn(); return "ok"
+ except botocore.exceptions.ClientError as e:
+ return e.response["Error"]["Code"]
+own = os.environ["S3_BUCKET"]
+print("own-put", attempt(lambda: s3.put_object(Bucket=own, Key="k", Body=b"v")))
+print("own-get", attempt(lambda: s3.get_object(Bucket=own, Key="k")["Body"].read()))
+print("other-put", attempt(lambda: s3.put_object(Bucket=sys.argv[1], Key="k", Body=b"v")))
+'''
+
+
+def _compose(project, root, *files, args, check=True, timeout=300):
+ argv = ['docker', 'compose', '-p', project]
+ for name in files:
+ argv += ['-f', os.path.join(root, name)]
+ proc = subprocess.run(argv + args, capture_output=True, text=True,
+ timeout=timeout, cwd=root)
+ if check:
+ assert proc.returncode == 0, f'{argv + args}\n{proc.stdout}\n{proc.stderr}'
+ return proc
+
+
+def _results(stdout):
+ return dict(line.split(' ', 1) for line in stdout.splitlines()
+ if line.split(' ', 1)[0] in ('own-put', 'own-get', 'other-put'))
+
+
+def test_attach_storage_scopes_a_key_to_one_bucket(app, tmp_path, monkeypatch):
+ suffix = uuid.uuid4().hex[:8]
+ store_name, web_name = f'skc-store-{suffix}', f'skc-web-{suffix}'
+ installed = {}
+ monkeypatch.setattr(TemplateService, 'get_config', classmethod(
+ lambda cls: {'repos': [], 'installed': installed}))
+
+ template = TemplateService.get_template('garage')['template']
+ variables = {'APP_NAME': store_name, 'API_PORT': '0', 'BIND_ADDRESS': '127.0.0.1'}
+ for var in template['variables']:
+ if var['name'] not in variables:
+ variables[var['name']] = TemplateService.generate_value(var)
+ store_root = tmp_path / store_name
+ store_root.mkdir()
+ rendered = TemplateService._render_compose_and_files(template, variables, str(store_root))
+ assert rendered['success'], rendered
+ compose = yaml.safe_load(rendered['compose_content'])
+ for svc in compose['services'].values():
+ svc.pop('ports', None) # reachability comes from the network alone
+ (store_root / 'docker-compose.yml').write_text(yaml.safe_dump(compose))
+ for f in rendered['files']:
+ with open(f['path'], 'w', newline='\n') as fh:
+ fh.write(f['content'])
+ (store_root / '.serverkit-template.json').write_text(json.dumps(
+ {'template_id': 'garage', 'variables': variables}))
+ store = make_application(db, name=store_name, root_path=str(store_root))
+ installed[str(store.id)] = {'template_id': 'garage'}
+
+ web_root = tmp_path / web_name
+ web_root.mkdir()
+ (web_root / 'probe.py').write_text(PROBE)
+ web = make_application(db, name=web_name, root_path=str(web_root))
+
+ base, override = 'docker-compose.yml', ComposeEnvService.OVERRIDE_NAME
+ other_bucket = f'other-{suffix}'
+ try:
+ assert ComposeEnvService.refresh_for_project(str(store_root))
+ _compose(store_name, str(store_root), base, override, args=['up', '-d'])
+ admin = GarageAdmin(store_name)
+ deadline = time.time() + 60
+ while True:
+ try:
+ admin.call('GetClusterStatus')
+ break
+ except GarageError:
+ assert time.time() < deadline, 'garage never answered'
+ time.sleep(1)
+
+ row, created = AppAttachmentService.attach_storage(web, store)
+ assert created
+ again, created_again = AppAttachmentService.attach_storage(web, store)
+ assert again.id == row.id and not created_again
+ admin.ensure_bucket(other_bucket)
+
+ (web_root / 'docker-compose.yml').write_text(yaml.safe_dump({'services': {'probe': {
+ 'image': 'python:3.12-alpine',
+ 'volumes': ['./probe.py:/probe.py:ro'],
+ 'command': ['sh', '-c', 'pip install -q --disable-pip-version-check boto3 '
+ f'>/dev/null 2>&1 && python /probe.py {other_bucket}'],
+ }}}))
+ assert ComposeEnvService.refresh_for_project(str(web_root))
+ first = _compose(web_name, str(web_root), base, override, args=['run', '--rm', 'probe'])
+ assert _results(first.stdout) == {
+ 'own-put': 'ok', 'own-get': 'ok', 'other-put': 'AccessDenied'}, first.stdout
+
+ # Detach revokes the key: replay the same credentials explicitly.
+ creds = EnvService.get_effective_env(web.id)
+ assert AppAttachmentService.detach(row) is None
+ assert 'S3_BUCKET' not in EnvService.get_effective_env(web.id)
+ replay = ['run', '--rm']
+ for key in ('S3_ENDPOINT', 'S3_REGION', 'S3_ACCESS_KEY_ID',
+ 'S3_SECRET_ACCESS_KEY', 'S3_BUCKET'):
+ replay += ['-e', f'{key}={creds[key]}']
+ # Keep the network so only the revoked key can explain a refusal.
+ (web_root / 'net.yml').write_text(yaml.safe_dump({
+ 'services': {'probe': {'networks': ['default', 'serverkit-services']}},
+ 'networks': {'serverkit-services': {'external': True}}}))
+ after = _compose(web_name, str(web_root), base, 'net.yml', args=replay + ['probe'])
+ assert _results(after.stdout)['own-put'] in ('InvalidAccessKeyId', 'AccessDenied'), after.stdout
+ finally:
+ _compose(web_name, str(web_root), base, check=False,
+ args=['down', '-v', '--remove-orphans'])
+ _compose(store_name, str(store_root), base, override, check=False,
+ args=['down', '-v', '--remove-orphans'])
diff --git a/docs/API_SURFACE.md b/docs/API_SURFACE.md
index ca18f3c3..b0432c9f 100644
--- a/docs/API_SURFACE.md
+++ b/docs/API_SURFACE.md
@@ -13,6 +13,7 @@ Regenerate (backend/):
- `DELETE /ai/conversations/{conversation_id}`
- `DELETE /api-keys/{key_id}`
- `DELETE /apps/{app_id}`
+- `DELETE /apps/{app_id}/attachments/{attachment_id}`
- `DELETE /apps/{app_id}/backups/{run_id}`
- `DELETE /apps/{app_id}/db-snapshots/{snapshot_id}`
- `DELETE /apps/{app_id}/env/clear`
@@ -157,8 +158,10 @@ Regenerate (backend/):
- `GET /api-keys/scopes`
- `GET /api-keys/{key_id}`
- `GET /apps`
+- `GET /apps/attachments/storage-services`
- `GET /apps/p/{slug}`
- `GET /apps/{app_id}`
+- `GET /apps/{app_id}/attachments`
- `GET /apps/{app_id}/backup-policy`
- `GET /apps/{app_id}/backups`
- `GET /apps/{app_id}/compose-services`
@@ -770,6 +773,7 @@ Regenerate (backend/):
- `POST /apps/scale-sweep`
- `POST /apps/sweep-idle`
- `POST /apps/upload`
+- `POST /apps/{app_id}/attachments/storage`
- `POST /apps/{app_id}/backups`
- `POST /apps/{app_id}/backups/{run_id}/restore`
- `POST /apps/{app_id}/backups/{run_id}/verify`