@loicngr/kobo 2.1.15 → 2.1.18

package/scripts/kobo-github-app-token

@@ -0,0 +1,190 @@
+#!/usr/bin/env python3
+"""Print a short-lived GitHub App installation token, or a secret-free --check result."""
+import argparse
+import base64
+from datetime import datetime
+import fcntl
+import hashlib
+import json
+import os
+from pathlib import Path
+import re
+import stat
+import subprocess
+import sys
+import tempfile
+import time
+import urllib.request
+
+RENEW_MARGIN = 120
+LOCK_TIMEOUT = 45
+MAX_BYTES = 65536
+
+
+class TokenError(Exception):
+    """An operator-facing failure that never contains credential material."""
+
+
+class NoRedirect(urllib.request.HTTPRedirectHandler):
+    def redirect_request(self, req, fp, code, msg, headers, newurl):
+        return None
+
+
+def read_config(path):
+    try:
+        data = json.loads(Path(path).read_text())
+        app_id = data['app_id']
+        installation_id = data['installation_id']
+        key = data['private_key']
+        if isinstance(app_id, bool) or not re.fullmatch(r'[A-Za-z0-9_.-]{1,100}', str(app_id)):
+            raise ValueError()
+        if isinstance(installation_id, bool) or not re.fullmatch(r'[1-9][0-9]*', str(installation_id)):
+            raise ValueError()
+        if not isinstance(key, str) or not Path(key).is_absolute():
+            raise ValueError()
+        key_bytes = Path(key).read_bytes()
+        if not key_bytes or len(key_bytes) > MAX_BYTES:
+            raise ValueError()
+        config = {'app_id': str(app_id), 'installation_id': str(installation_id), 'private_key': key}
+        identity = hashlib.sha256(json.dumps(config, sort_keys=True).encode() + b'\0' + key_bytes).hexdigest()
+        return config, identity
+    except (OSError, ValueError, KeyError, TypeError):
+        raise TokenError('Cannot read GitHub App configuration: check IDs and the absolute RSA key path.') from None
+
+
+def secure_directory(path):
+    path.mkdir(mode=0o700, parents=True, exist_ok=True)
+    info = path.lstat()
+    if not stat.S_ISDIR(info.st_mode) or info.st_uid != os.getuid() or info.st_mode & 0o077:
+        raise TokenError('The token cache directory must be owned by this user, private (0700), and not a symlink.')
+
+
+def private_file(path, flags):
+    fd = os.open(path, flags | os.O_NOFOLLOW | os.O_NONBLOCK, 0o600)
+    info = os.fstat(fd)
+    if not stat.S_ISREG(info.st_mode) or info.st_uid != os.getuid() or info.st_mode & 0o077:
+        os.close(fd)
+        raise TokenError('Token cache files must be regular private files (0600) owned by this user.')
+    return fd
+
+
+def usable_token(data):
+    if not isinstance(data, dict):
+        return False
+    token, expiry = data.get('token'), data.get('expires_at')
+    if not isinstance(token, str) or not re.fullmatch(r'[A-Za-z0-9_.-]{1,8192}', token):
+        return False
+    try:
+        parsed = datetime.fromisoformat(expiry.replace('Z', '+00:00'))
+        return parsed.tzinfo is not None and parsed.timestamp() > time.time() + RENEW_MARGIN
+    except (AttributeError, TypeError, ValueError, OverflowError):
+        return False
+
+
+def read_cache(path, identity):
+    try:
+        with os.fdopen(private_file(path, os.O_RDONLY)) as handle:
+            data = json.loads(handle.read(MAX_BYTES))
+        if data.get('identity') == identity and usable_token(data):
+            return data
+    except (FileNotFoundError, ValueError, AttributeError):
+        pass
+    return None
+
+
+def write_cache(path, data):
+    fd, temp = tempfile.mkstemp(prefix='.token-', dir=path.parent)
+    try:
+        with os.fdopen(fd, 'w') as handle:
+            json.dump(data, handle)
+            handle.flush()
+            os.fsync(handle.fileno())
+        os.replace(temp, path)
+    finally:
+        if os.path.exists(temp):
+            os.unlink(temp)
+
+
+def encode(data):
+    return base64.urlsafe_b64encode(data).rstrip(b'=').decode('ascii')
+
+
+def jwt(config):
+    now = int(time.time())
+    header = encode(json.dumps({'alg': 'RS256', 'typ': 'JWT'}, separators=(',', ':')).encode())
+    payload = encode(json.dumps({'iat': now - 60, 'exp': now + 540, 'iss': config['app_id']},
+                                separators=(',', ':')).encode())
+    unsigned = f'{header}.{payload}'.encode()
+    try:
+        # Reject EC/encrypted keys instead of sending a mislabeled or interactive JWT.
+        subprocess.run(['openssl', 'rsa', '-in', config['private_key'], '-passin', 'pass:',
+                        '-check', '-noout'], check=True, capture_output=True, timeout=10)
+        signature = subprocess.run(['openssl', 'dgst', '-sha256', '-sign', config['private_key'],
+                                    '-passin', 'pass:'], input=unsigned, check=True,
+                                   capture_output=True, timeout=10).stdout
+    except (OSError, subprocess.SubprocessError):
+        raise TokenError('Cannot sign the App JWT: install OpenSSL and provide an unencrypted RSA private key.') from None
+    return f'{header}.{payload}.{encode(signature)}'
+
+
+def mint(config):
+    request = urllib.request.Request(
+        f"https://api.github.com/app/installations/{config['installation_id']}/access_tokens",
+        data=b'{}', method='POST', headers={
+            'Authorization': f'Bearer {jwt(config)}',
+            'Accept': 'application/vnd.github+json',
+            'Content-Type': 'application/json',
+            'User-Agent': 'kobo-github-app-token',
+            'X-GitHub-Api-Version': '2022-11-28',
+        })
+    try:
+        with urllib.request.build_opener(NoRedirect()).open(request, timeout=20) as response:
+            data = json.loads(response.read(MAX_BYTES))
+        if not usable_token(data):
+            raise ValueError()
+        return {'token': data['token'], 'expires_at': data['expires_at']}
+    except (OSError, ValueError, TypeError):
+        raise TokenError('GitHub App token renewal failed: check network, App installation, IDs and key.') from None
+
+
+def get_token(config_path, cache_dir):
+    config, identity = read_config(config_path)
+    cache_dir = Path(cache_dir).expanduser()
+    secure_directory(cache_dir)
+    with os.fdopen(private_file(cache_dir / 'token.lock', os.O_CREAT | os.O_RDWR), 'w') as lock:
+        deadline = time.monotonic() + LOCK_TIMEOUT
+        while True:
+            try:
+                fcntl.flock(lock, fcntl.LOCK_EX | fcntl.LOCK_NB)
+                break
+            except BlockingIOError:
+                if time.monotonic() >= deadline:
+                    raise TokenError('Timed out waiting for another GitHub App token renewal.') from None
+                time.sleep(0.05)
+        cached = read_cache(cache_dir / 'token.json', identity)
+        if cached:
+            return {key: cached[key] for key in ('token', 'expires_at')}
+        token = mint(config)
+        write_cache(cache_dir / 'token.json', {**token, 'identity': identity})
+        return token
+
+
+def main(argv=None):
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument('--config', type=Path, default=Path('/etc/kobo/github-app.json'))
+    parser.add_argument('--cache-dir', type=Path, default=Path.home() / '.cache/kobo/github-app')
+    parser.add_argument('--check', action='store_true', help='Validate authentication without printing the token.')
+    args = parser.parse_args(argv)
+    try:
+        result = get_token(args.config, args.cache_dir)
+        print(json.dumps({'status': 'ok', 'expires_at': result['expires_at']}) if args.check else result['token'])
+        return 0
+    except TokenError as error:
+        print(str(error), file=sys.stderr)
+    except (OSError, ValueError):
+        print('Cannot access the private token configuration or cache. Check paths and permissions.', file=sys.stderr)
+    return 1
+
+
+if __name__ == '__main__':
+    sys.exit(main())

package/scripts/kobo-install

@@ -0,0 +1,392 @@
+#!/usr/bin/env python3
+"""Install a fresh Kōbō instance behind an existing Traefik. Python 3.10+."""
+import argparse
+import fcntl
+import hashlib
+import importlib.machinery
+import importlib.util
+import json
+import os
+from pathlib import Path
+import re
+import shutil
+import sys
+import uuid
+
+sys.dont_write_bytecode = True
+ASSETS = Path(__file__).resolve().parent
+loader = importlib.machinery.SourceFileLoader('kobo_updater', str(ASSETS / 'kobo-update'))
+spec = importlib.util.spec_from_loader(loader.name, loader)
+updater = importlib.util.module_from_spec(spec)
+loader.exec_module(updater)
+InstallError = updater.UpdateError
+TOOLS = ('kobo-install', 'kobo-update', 'kobo-github-app-token', 'kobo-gh')
+ENV_KEYS = updater.COMPOSE_ENV_KEYS
+
+
+def safe_path(value):
+    path = Path(value)
+    if not path.is_absolute() or any(re.search(r'[\x00-\x1f\x7f\"\'`$,:\\]', str(p)) for p in (path, path.resolve())):
+        raise InstallError('Use absolute paths without control characters, quotes, $, commas, colons or backslashes.')
+    return path.resolve()
+
+
+def validate_config(config):
+    domain = config['domain']
+    if (len(domain) > 253 or '.' not in domain or
+            not all(re.fullmatch(r'[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?', label)
+                    for label in domain.split('.'))):
+        raise InstallError('Domain must be a DNS hostname, without scheme, port or path.')
+    for name in ('network', 'entrypoint', 'certresolver'):
+        if name == 'certresolver' and config[name] == '':
+            continue
+        if not re.fullmatch(r'[A-Za-z0-9][A-Za-z0-9_.-]{0,99}', config[name]):
+            raise InstallError(f'Invalid {name}; use letters, numbers, dots, underscores or hyphens.')
+    projects = safe_path(config['projects_directory'])
+    # A bind over the runtime/home/config would hide executables or persistent credentials.
+    protected = ('/root', '/app', '/usr', '/bin', '/sbin', '/etc', '/run', '/var', '/proc', '/sys', '/dev')
+    if projects == Path('/') or any(projects == Path(p) or Path(p) in projects.parents for p in protected):
+        raise InstallError('Projects must be outside container system paths, /app and /root (for example /opt/kobo/projects).')
+    if projects.exists() and not projects.is_dir():
+        raise InstallError('The projects path must be a directory.')
+    app = [config.get(k) for k in ('github_app_id', 'github_installation_id', 'github_private_key')]
+    if any(app):
+        if not all(app):
+            raise InstallError('GitHub App requires all three flags: App ID, installation ID and private key.')
+        if not re.fullmatch(r'[A-Za-z0-9_.-]{1,100}', app[0]) or not re.fullmatch(r'[1-9][0-9]*', app[1]):
+            raise InstallError('Invalid GitHub App or installation ID.')
+        key = safe_path(app[2])
+        if not key.is_file() or not os.access(key, os.R_OK) or key.stat().st_mode & 0o077:
+            raise InstallError('The GitHub private key must be a readable regular file with private permissions (0600).')
+    if config['version'] != 'latest':
+        updater.normalize_version(config['version'])
+
+
+def render(config, stack):
+    text = (ASSETS.parent / 'docker-compose.vps.yml').read_text()
+    if not config['certresolver']:
+        text = '\n'.join(line for line in text.split('\n') if 'tls.certresolver:' not in line)
+    if config['docker_socket']:
+        text = text.replace('      # - /var/run/docker.sock:', '      - /var/run/docker.sock:')
+    if config.get('github_app_id'):
+        mounts = ''
+        for source, target in (
+            (stack / 'bin/kobo-gh', '/usr/local/bin/gh'),
+            (stack / 'bin/kobo-github-app-token', '/usr/local/bin/kobo-github-app-token'),
+            (stack / 'auth/github-app.json', '/etc/kobo/github-app.json'),
+            (safe_path(config['github_private_key']), '/run/secrets/kobo-github-app.pem'),
+        ):
+            mounts += (f'      - type: bind\n        source: {json.dumps(str(source))}\n'
+                       f'        target: {target}\n        read_only: true\n'
+                       '        bind:\n          create_host_path: false\n')
+        text = text.replace('    networks:\n', mounts + '    networks:\n', 1)
+    values = (config['domain'], config['projects_directory'], config['network'],
+              config['entrypoint'], config['certresolver'])
+    env = ''.join(f"{key}='{value}'\n" for key, value in zip(ENV_KEYS, values))
+    return text, env
+
+
+def digest(name, data):
+    # kobo-update owns the image pin after installation; all other edits still require review.
+    if name == 'compose.yaml':
+        data = updater.image_config(data.decode(), 'kobo:managed').encode()
+    return hashlib.sha256(data).hexdigest()
+
+
+class Installer(updater.Updater):
+    def __init__(self, stack):
+        super().__init__(safe_path(str(stack)))
+        self.manifest = self.stack / '.kobo-install.json'
+        self.project_name = 'kobo'
+        self.state = json.loads(self.manifest.read_text()) if self.manifest.exists() else {}
+        if self.state and (self.state.get('format') != 1 or self.state.get('directory') != str(self.stack)):
+            raise InstallError('Unrecognized or relocated installation manifest; review it manually.')
+
+    def preflight(self, config):
+        for tool in ('docker', 'git'):
+            if not shutil.which(tool):
+                raise InstallError(f'Install {tool} first.')
+        endpoint = os.environ.get('DOCKER_HOST')
+        if not endpoint or os.environ.get('DOCKER_CONTEXT'):
+            context = json.loads(self.run(['docker', 'context', 'inspect']))[0]
+            endpoint = context['Endpoints']['docker']['Host']
+        if not endpoint.startswith('unix://'):
+            raise InstallError('Run this installer on the Docker host using a local Unix socket context.')
+        info = json.loads(self.run(['docker', 'info', '--format', '{{json .}}']))
+        if info.get('OSType') != 'linux' or info.get('Architecture') not in ('x86_64', 'amd64'):
+            raise InstallError('This image currently requires Linux amd64.')
+        self.run(['docker', 'compose', 'version'])
+        self.run(['docker', 'network', 'inspect', config['network']])
+        if config['docker_socket'] and not Path('/var/run/docker.sock').is_socket():
+            raise InstallError('Docker socket access requires /var/run/docker.sock on this host.')
+
+    def discover(self):
+        """Suggest CLI/env-based Traefik settings without displaying raw container configuration."""
+        found = {name: set() for name in ('network', 'entrypoint', 'certresolver')}
+        ids = self.run(['docker', 'ps', '-q']).split()
+        if not ids:
+            return found
+        for container in json.loads(self.run(['docker', 'inspect', *ids])):
+            config = container.get('Config', {})
+            if 'traefik' not in config.get('Image', '').lower():
+                continue
+            found['network'].update(name for name in container.get('NetworkSettings', {}).get('Networks', {})
+                                    if name not in {'bridge', 'host', 'none'})
+            args = (config.get('Cmd') or []) + (config.get('Env') or [])
+            for arg in args:
+                entry = re.fullmatch(r'--entrypoints\.([\w-]+)\.address=:(?:443)(?:/tcp)?', arg, re.I)
+                env_entry = re.fullmatch(r'TRAEFIK_ENTRYPOINTS_([\w-]+)_ADDRESS=:443(?:/tcp)?', arg, re.I)
+                resolver = re.match(r'--certificatesresolvers\.([\w-]+)\.', arg, re.I)
+                env_resolver = re.match(r'TRAEFIK_CERTIFICATESRESOLVERS_([\w-]+)_ACME_', arg, re.I)
+                if entry or env_entry:
+                    found['entrypoint'].add((entry or env_entry).group(1).lower())
+                if resolver or env_resolver:
+                    found['certresolver'].add((resolver or env_resolver).group(1).lower())
+        return found
+
+    def collisions(self):
+        containers = self.run(['docker', 'ps', '-aq', '--filter', 'label=com.docker.compose.project=kobo'])
+        volumes = self.run(['docker', 'volume', 'ls', '-q', '--filter', 'name=^kobo_kobo-home$'])
+        routers = self.run(['docker', 'ps', '-aq', '--filter', 'label=traefik.http.routers.kobo.rule'])
+        if containers or volumes or routers:
+            raise InstallError('Compose project kobo, router kobo or volume kobo_kobo-home already exists. Refusing to adopt or replace it.')
+
+    def assert_fresh(self):
+        for name in ('compose.yaml', '.env', '.kobo-install.json', 'bin', 'auth', 'docker-compose.vps.yml'):
+            path = self.stack / name
+            if path.exists() or path.is_symlink():
+                raise InstallError(f'Unmanaged installation file already exists: {path}. Use the manual guide.')
+
+    def save(self, **changes):
+        self.state.update(changes)
+        updater.atomic_write(self.manifest, (json.dumps(self.state, indent=2) + '\n').encode())
+
+    def initialize(self, config):
+        self.assert_fresh()
+        compose, env = render(config, self.stack)
+        files = {'compose.yaml': compose.encode(), '.env': env.encode(),
+                 'docker-compose.vps.yml': (ASSETS.parent / 'docker-compose.vps.yml').read_bytes()}
+        files.update({f'bin/{name}': (ASSETS / name).read_bytes() for name in TOOLS})
+        if config.get('github_app_id'):
+            files['auth/github-app.json'] = json.dumps({
+                'app_id': config['github_app_id'], 'installation_id': config['github_installation_id'],
+                'private_key': '/run/secrets/kobo-github-app.pem',
+            }, indent=2).encode()
+        self.stack.mkdir(parents=True, exist_ok=True, mode=0o700)
+        # Record intent first. An interrupted file copy is explicit, never silently adopted.
+        self.save(format=1, directory=str(self.stack), config=config, phase='writing-files',
+                  hashes={name: digest(name, data) for name, data in files.items()})
+        for name, data in files.items():
+            path = self.stack / name
+            path.parent.mkdir(mode=0o700, parents=True, exist_ok=True)
+            updater.atomic_write(path, data, 0o755 if name.startswith('bin/') else 0o600)
+        Path(config['projects_directory']).mkdir(parents=True, exist_ok=True)
+        self.save(phase='configured')
+
+    def verify_files(self):
+        if self.state['phase'] == 'writing-files':
+            raise InstallError('File preparation was interrupted. Review .kobo-install.json and files before retrying; nothing was started.')
+        for name, expected in self.state['hashes'].items():
+            path = self.stack / name
+            if path.is_symlink() or not path.is_file() or digest(name, path.read_bytes()) != expected:
+                raise InstallError(f'Managed file changed or missing: {path}. Preserved; review it manually.')
+        if self.state['phase'] != 'complete' and self.state.get('image'):
+            if f'    image: {self.state["image"]}\n' not in self.compose_file.read_text():
+                raise InstallError('Prepared image was changed; refusing to start it.')
+
+    def validate_compose(self, config):
+        # No files or directories are needed for --check. All substitutions are supplied explicitly.
+        text, _ = render(config, self.stack)
+        for key, value in zip(ENV_KEYS, (config['domain'], config['projects_directory'], config['network'],
+                                       config['entrypoint'], config['certresolver'])):
+            text = re.sub(r'\$\{' + key + r'(?::[^}]*)?\}', lambda _: value, text)
+        self.run(['docker', 'compose', '--env-file', '/dev/null', '-p', 'kobo', '-f', '-', 'config', '--quiet'],
+                 data=text.encode())
+
+    def configure_github(self):
+        self.run(self.compose('exec', '-T', 'kobo', '/usr/local/bin/kobo-github-app-token', '--check'))
+        helper = 'credential.https://github.com.helper'
+        self.run(self.compose('exec', '-T', 'kobo', 'git', 'config', '--global', '--replace-all', helper, ''))
+        self.run(self.compose('exec', '-T', 'kobo', 'git', 'config', '--global', '--add', helper,
+                             '!/usr/local/bin/gh auth git-credential'))
+
+    def assert_started(self):
+        container = self.run(self.compose('ps', '-aq', 'kobo'))
+        if not container or len(container.split()) != 1:
+            raise InstallError('Expected installation container is missing or ambiguous. Inspect compose ps; no automatic restart was attempted.')
+        info = json.loads(self.run(['docker', 'inspect', container]))[0]
+        expected_hash = self.run(self.compose('config', '--hash', 'kobo')).split()
+        labels = info.get('Config', {}).get('Labels', {}) or {}
+        state = info.get('State', {})
+        expected_labels = {'com.docker.compose.project': 'kobo', 'com.docker.compose.service': 'kobo',
+                           'com.docker.compose.project.working_dir': str(self.stack)}
+        if (not state.get('Running') or state.get('Health', {}).get('Status') != 'healthy'
+                or info.get('Config', {}).get('Image') != self.state['image']
+                or any(labels.get(key) != value for key, value in expected_labels.items())
+                or len(expected_hash) != 2 or expected_hash[0] != 'kobo'
+                or labels.get('com.docker.compose.config-hash') != expected_hash[1]):
+            raise InstallError('Installation container is unhealthy or differs from the prepared configuration. Inspect compose ps and private logs; no automatic restart was attempted.')
+        self.container = container
+
+    def finish(self, config):
+        # A previous up may have succeeded even if its CLI or the HTTPS check failed.
+        # Verify ownership before doing anything; never recreate an uncertain container.
+        self.assert_started()
+        self.save(phase='verifying')
+        if config.get('github_app_id') and not self.state.get('github_configured'):
+            self.configure_github()
+            self.save(github_configured=True)
+        self.public_url = 'https://' + config['domain']
+        self.verify(self.state['version'])
+        self.save(phase='complete')
+        print(f'Kōbō is ready at {self.public_url}. Follow docs/deployment-vps.md to retrieve the private login link and sign in to an engine.')
+
+    def execute(self, config, check=False, prepare=False):
+        validate_config(config)
+        if self.state:
+            if config != self.state['config']:
+                raise InstallError('This directory is already configured with different options. No reconfiguration was applied.')
+            self.verify_files()
+        else:
+            self.assert_fresh()
+        self.preflight(config)
+        if not self.state or self.state['phase'] in {'configured', 'building', 'prepared'}:
+            self.collisions()
+        self.validate_compose(config)
+        if check:
+            print('Configuration and local Docker checks passed. No files, images or containers changed.')
+            return
+        if self.state.get('phase') == 'complete':
+            print('Installation already complete; no restart or reconfiguration. Use bin/kobo-update to upgrade.')
+            return
+        if self.state.get('phase') in {'starting', 'verifying'}:
+            if prepare:
+                raise InstallError('Start was already attempted. Inspect compose ps or rerun without --prepare to verify it.')
+            self.finish(config)
+            return
+        if not self.state:
+            self.initialize(config)
+        if self.state['phase'] != 'prepared':
+            self.installed = '0.0.0'
+            version, sha = self.resolve(config['version'])
+            self.job = self.stack / 'install-builds' / uuid.uuid4().hex
+            self.job.mkdir(mode=0o700, parents=True)
+            self.log = self.job / 'install.log'
+            self.log.touch(mode=0o600)
+            self.save(phase='building', version=version, sha=sha, log=str(self.log))
+            print(f'Building Kōbō {version}. Private log: {self.log}', flush=True)
+            image = self.build(version, sha)
+            # Older release images also need the explicit helper dependencies.
+            self.run(['docker', 'run', '--rm', '--network', 'none', '--entrypoint', 'sh', image,
+                      '-c', 'python3 -c "import sys; assert sys.version_info >= (3,10)" && openssl version'])
+            self.verify_files()
+            self.save(phase='pinning', image=image)
+            updater.atomic_write(self.compose_file, updater.image_config(self.compose_file.read_text(), image).encode())
+            self.save(phase='prepared')
+        if prepare:
+            print('Image and configuration ready. Run the same command without --prepare to start.')
+            return
+        self.verify_files()
+        self.collisions()
+        self.run(self.compose('config', '--quiet'))
+        self.save(phase='starting')
+        self.run(self.compose('up', '-d', '--wait', '--wait-timeout', '180', 'kobo'), timeout=240)
+        self.finish(config)
+
+
+def arguments(argv=None):
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument('--directory', type=Path, required=True)
+    for name in ('domain', 'projects-directory', 'network', 'entrypoint', 'certresolver', 'version',
+                 'github-app-id', 'github-installation-id', 'github-private-key'):
+        parser.add_argument('--' + name)
+    parser.add_argument('--docker-socket', action='store_true', default=None,
+                        help='Give agents root-equivalent access to this host through Docker.')
+    parser.add_argument('--yes', action='store_true', help='Use explicit flags without interactive questions.')
+    mode = parser.add_mutually_exclusive_group()
+    mode.add_argument('--check', action='store_true', help='Read-only local prerequisite/configuration checks.')
+    mode.add_argument('--prepare', action='store_true', help='Write configuration and build without starting.')
+    return parser.parse_args(argv)
+
+
+def configure(args, installer):
+    names = ('domain', 'projects_directory', 'network', 'entrypoint', 'certresolver', 'version',
+             'github_app_id', 'github_installation_id', 'github_private_key', 'docker_socket')
+    config = installer.state.get('config', {}).copy()
+    config.update({name: getattr(args, name) for name in names if getattr(args, name) is not None})
+    interactive = sys.stdin.isatty() and not args.yes
+    suggestions = installer.discover() if interactive and not installer.state else {}
+
+    def ask(name, label, default=None):
+        if name in config:
+            return
+        if interactive:
+            options = sorted(suggestions.get(name, []))
+            if len(options) == 1:
+                default = options[0]
+            if options:
+                print(f'Detected {name}: {", ".join(options)}')
+            answer = input(f'{label}' + (f' [{default}]' if default is not None else '') + ': ').strip()
+            config[name] = answer or default
+        else:
+            config[name] = default
+        if config[name] is None:
+            raise InstallError(f'Missing --{name.replace("_", "-")}.')
+
+    ask('domain', 'Public hostname')
+    ask('projects_directory', 'Projects directory', str(installer.stack / 'projects'))
+    ask('network', 'Existing Traefik Docker network')
+    ask('entrypoint', 'Traefik HTTPS entrypoint')
+    ask('certresolver', 'Traefik certificate resolver (empty for preloaded certificate)', '')
+    ask('version', 'Stable release version', 'latest')
+    if config.get('docker_socket') is None:
+        config['docker_socket'] = interactive and input('Give agents Docker access (root-equivalent host control)? [y/N]: ').lower() == 'y'
+    if not any(config.get(name) for name in ('github_app_id', 'github_installation_id', 'github_private_key')):
+        if interactive and input('Configure a GitHub App bot? [y/N]: ').lower() == 'y':
+            ask('github_app_id', 'GitHub App client ID or App ID')
+            ask('github_installation_id', 'GitHub installation ID')
+            ask('github_private_key', 'Absolute path to private RSA key (0600)')
+    for name in ('github_app_id', 'github_installation_id', 'github_private_key'):
+        config.setdefault(name, None)
+    config['projects_directory'] = str(safe_path(config['projects_directory']))
+    if config['github_private_key']:
+        config['github_private_key'] = str(safe_path(config['github_private_key']))
+    return config
+
+
+def main(argv=None):
+    args = arguments(argv)
+    try:
+        installer = Installer(args.directory)
+        config = configure(args, installer)
+        validate_config(config)
+        if args.check:
+            installer.execute(config, check=True)
+            return 0
+        print(f'Install directory: {installer.stack}\nURL: https://{config["domain"]}\n'
+              f'Projects: {config["projects_directory"]}\nDocker socket: {config["docker_socket"]}\n'
+              f'GitHub App: {bool(config["github_app_id"])}')
+        if not args.yes and not installer.state:
+            if not sys.stdin.isatty() or input('Create this installation? [y/N]: ').lower() != 'y':
+                raise InstallError('Installation not started. Use --yes with explicit configuration for unattended setup.')
+        installer.stack.mkdir(mode=0o700, parents=True, exist_ok=True)
+        with (installer.stack / '.update.lock').open('a') as lock:
+            try:
+                fcntl.flock(lock, fcntl.LOCK_EX | fcntl.LOCK_NB)
+            except BlockingIOError:
+                raise InstallError('An installer or updater already holds this directory lock.') from None
+            # Reload after locking so concurrent installers cannot adopt one another's stale state.
+            installer = Installer(args.directory)
+            installer.execute(config, prepare=args.prepare)
+        return 0
+    except (InstallError, OSError, ValueError, KeyError, EOFError) as error:
+        print(str(error) if isinstance(error, InstallError) else
+              'Installation failed: check local paths, prerequisites and the private installation state.', file=sys.stderr)
+        return 1
+    except KeyboardInterrupt:
+        print('Interrupted. Files and data retained; inspect .kobo-install.json before resuming.', file=sys.stderr)
+        return 130
+
+
+if __name__ == '__main__':
+    sys.exit(main())