Documentation Index

Fetch the complete documentation index at: https://docs.stacyide.xyz/llms.txt

Use this file to discover all available pages before exploring further.

​

Phase 4 Production Deployment Release Notes

​

Summary

​

What Changed

​

Continuous Integration

• Added a GitHub Actions workflow for core project verification.
• CI now validates:
  • Go tests across the repository.
  • CLI build.
  • Swagger/OpenAPI drift.
  • Web dashboard production build.
  • TypeScript SDK build.
  • Python SDK package install, compile, and import.
• Stabilized the Swagger drift check for cold CI runners by downloading Go modules before invoking swag.

​

Production Deployment Templates

• Added deploy/docker-compose.yml for a production-oriented Docker provider deployment with Traefik live-preview routing.
• Added deploy/stacyvm.production.yaml with production defaults for:
  • API auth.
  • API rate limiting.
  • sandbox caps and queue backpressure.
  • JSON logging.
  • persistent SQLite state.
  • Docker as the default provider.
• Added Compose and systemd environment templates:
  • deploy/.env.example
  • deploy/stacyvm.env.example
• Added deploy/stacyvm.service for binary-based Linux/systemd installs.

​

Release Automation

• Added a release workflow for tag-driven and manually-dispatched releases.
• Release automation builds static Linux binary artifacts for amd64 and arm64.
• Release automation publishes multi-arch container images to ghcr.io/stacyos/stacyvm.
• Docker image builds now accept an explicit VERSION build argument.
• Release artifacts now build into dist/ instead of the repository root.
• Added .dockerignore to keep local build outputs and dependency directories out of release image contexts.

​

Deployment Runbook

• Added docs/deployment.md covering:
  • host requirements.
  • Docker Compose deployment.
  • systemd deployment.
  • health, readiness, liveness, and Prometheus endpoints.
  • reverse proxy expectations.
  • SQLite backup and restore basics.
  • upgrade procedure.
  • Docker, Firecracker, and PRoot provider notes.
• Linked the deployment guide from the README.
• Added scripts/smoke-deployment.sh for liveness, health, readiness, and Prometheus deployment probes.
• Added docs/runtime-conformance.md with host requirements and signoff checks for Docker, gVisor, Kata, Firecracker, PRoot, E2B, and custom providers.
• Registered the mock provider in stacyvm serve when providers.mock.enabled is set, giving operators and CI a no-Docker smoke path.
• Validated the production Compose template with StacyVM, Traefik, Docker provider readiness, API smoke probes, and a port 3000 live-preview route.

​

Code Changes By Area

​

CI

• .github/workflows/ci.yml
  • Adds repository verification jobs for Go, Swagger, web, and SDKs.
  • Opts into Node 24-based JavaScript actions to address the GitHub Actions Node 20 deprecation warning.
  • Runs a mock-provider deployment smoke job against the production smoke script.
• .github/workflows/release.yml
  • Adds binary and container image release automation.
• scripts/check-swagger.sh
  • Downloads modules before generating docs in a temporary workspace.
• scripts/ci-smoke-deployment.sh
  • Starts StacyVM with the mock provider and runs deployment smoke probes in CI.
• cmd/stacyvm/cmd_serve.go
  • Registers the mock provider when enabled in config.

​

Deployment

• deploy/docker-compose.yml
  • Adds a reusable production Compose template.
  • Allows the Traefik host port to be overridden for smoke runs.
• deploy/stacyvm.production.yaml
  • Adds a production baseline config.
• deploy/stacyvm.service
  • Adds a systemd unit for running the StacyVM binary.
• deploy/.env.example and deploy/stacyvm.env.example
  • Add environment templates for Compose and systemd.
• Dockerfile
  • Adds BuildKit platform args and explicit version injection for release image publishing.
• Makefile
  • Moves release artifacts into dist/ and keeps checksums with the artifacts.
• .dockerignore
  • Excludes build outputs, local dependency directories, and local state files from Docker build contexts.
• scripts/smoke-deployment.sh
  • Adds a portable post-deploy smoke test for live, health, readiness, and Prometheus metrics endpoints.

​

Docs

• docs/deployment.md
  • Adds the deployment guide and operator runbook.
• docs/releasing.md
  • Adds release workflow and GHCR publishing instructions.
• docs/runtime-conformance.md
  • Adds provider/runtime production signoff expectations.
• README.md
  • Links the deployment guide from navigation and configuration docs.
• CHANGELOG.md
  • Adds this Phase 4 checkpoint entry.

​

Verification

docker compose --env-file deploy/.env.example -f deploy/docker-compose.yml config
ruby -e 'require "yaml"; YAML.load_file("deploy/docker-compose.yml"); YAML.load_file("deploy/stacyvm.production.yaml")'
git diff --check
go test ./...
cd web && npm run build
scripts/check-swagger.sh
make release-build-all VERSION=phase-4-test
scripts/smoke-deployment.sh http://127.0.0.1:7423
scripts/ci-smoke-deployment.sh
docker build --build-arg VERSION=phase-4-compose -t stacyvm:phase-4-compose .
docker compose -p stacyvm-phase4-smoke -f deploy/docker-compose.yml up -d
scripts/smoke-deployment.sh http://127.0.0.1:17426 phase4-compose-key
curl -H 'Host: 3000-<sandbox-id>.localhost' http://127.0.0.1:18080/

​

Platform Notes

• Docker Compose validation does not require daemon access, but runtime sandbox conformance still requires Docker daemon access on the host.
• Firecracker remains Linux/KVM-gated and should be rolled out only after host conformance checks pass.
• PRoot remains gated on a real proot binary and a rootfs with the expected sandbox tooling.

​

Phase 4 Closeout

• Trigger a real versioned release run when the project is ready to publish binaries and the GHCR image.
• Collect real-host runtime signoffs for optional host-gated runtimes such as gVisor, Kata, Firecracker, and PRoot.