KAGEOS GUIDES

Deployment & operations

Separate local development from production and verify health after changes.

Choose a deployment

Use local development to inspect and change source. Production self-hosting needs a stable URL, persistent storage and backups. Start with the self-hosting guide.

Run locally

Prepare Go, Node.js and a working Docker or Podman Compose environment:

git clone https://github.com/kageos/kageos.git
cd kageos
./scripts/dev.sh

Open http://localhost:5173 and use system with the password in the startup summary. Check the repository contribution guide for dependency versions. Never commit private .kageos/ configuration or credentials.

Production checklist

  1. Verify the final domain and a trusted HTTPS certificate.
  2. Check platform services and application runtime, not just the homepage.
  3. Sign in and complete a low-risk business operation.
  4. Verify persistence paths, disk space and independent backup copies.
  5. Record the version, installation method and recovery procedure.

For source deployments, use kagectl doctor, status, verify and logs. Installer-managed instances should follow their manager instructions; do not mix storage paths from different deployment modes.

Before and after upgrades

Create and verify a backup; record current image versions and rollback instructions. After upgrading, repeat health and business checks. Diagnose the first failure instead of clearing databases, volumes or workspaces.

Treat TLS files, configuration and business data as persistent state. See Backup & restore for archive verification and restore preflight.