Docker Compose
For a container-only local evaluation, run these commands from the repository root:
./scripts/setup-compose.sh
docker compose up --build -d --wait
Open http://localhost:3000 and sign in as admin@localhost using the password generated in .env. This starts PostgreSQL, applies migrations, and waits for application health. Data persists in named volumes. The local HTTP template uses external Git sources; hosted Git and production HTTPS/OIDC use deployments/preproduction/. See Compose operations for ports, upgrades, and data retention.
Start locally
Prepare Docker, Node.js 24, Git, Python 3, and Go with automatic toolchain support. The Makefile selects Go 1.26.10. From the repository root:
cp .env.example .env.local
# Set a unique administrator password of at least 14 characters
chmod 600 .env.local
make deps
make dev
Default ports: console 3000, API 8080, PostgreSQL 55432. To change the console port, set both SKIVA_WEB_PORT and SKIVA_WEB_ORIGIN.
Production deployment
Configure TLS, persistent PostgreSQL and content storage, OIDC, Git host allowlists, Secret references, and backups. Migrate before starting API / workers. Templates are in deployments/compose.yaml and deployments/docker/.
Route /distribution/ directly to Go. Expose /metrics only on the monitoring network. The server image and migration command were verified locally; see deployments/preproduction/ for a single-host template. Actual domain TLS, enterprise IdP, and alert delivery still need deployment acceptance.
Detailed installation, OIDC, SSH, and restore procedures are in docs/OPERATIONS.md.
Backup and recovery
Back up PostgreSQL together with Git / CAS data. Stop API / worker writes first for a consistent recovery point. Store backups in protected storage outside the data directory.
# Configure database, data directory, and backup location first
export SKIVA_BACKUP_DIR=/secure-backups/skiva
./scripts/backup.sh
Restore into an empty database and data directory. Verify backup checksums and referenced objects before switching service. Never run migration rollback tests against production.
Troubleshooting
| Symptom | Check |
|---|---|
| Git connection fails | URL/ref → allowlist/DNS → Secret reference → CA or SSH known_hosts |
| No new version after sync | Diagnostics → commit → actual content changes → scan directory |
| Build succeeds but client stays old | Snapshot created → correct channel promoted → Profile → dynamic/pinned |
| A Skill disappears | Present in snapshot → authorized by Profile |
| Blob returns 403 | Client identity → Profile → snapshot authorization → file membership |
| Blob returns 503 | Missing/corrupt object; run integrity checks |
| Release returns 409 | Concurrent generation change; refresh and review |
| Files update but Agent does not | Agent index/context cache, existing handles, pinned mode |
| Lost token | Rotate credentials and sign in again |
Verification and maintenance
make test-db
make lint test build
# Configure SKIVA_DATABASE_URL and SKIVA_DATA_DIR before inspection
make verify-artifacts
Keep test and application databases separate. See docs/OPERATIONS.md for maintenance and docs/ACCEPTANCE.md for evidence and boundaries. Production SLOs, enterprise identity, and real network recovery require deployment-specific acceptance.