StudioTeal/GodotBinaryBuilder
2
0
Fork 0
Code Issues Pull requests Projects Releases 21 Packages 6 Wiki Activity Actions
Page: Deployment and Operations
Pages
API Architecture Building Godot Configuration Contributing Deployment and Operations Development Getting Started Home Modules and Administration Reference API Reference Abuse Enforcement Reference Admin Reference Anonymous Verification Reference Architecture Reference Artifacts Reference Authelia Administration Reference CI CD Reference Deployment Reference Download Gateway Reference Durable Execution Store Reference Immutable Build Configuration Reference Kubernetes Execution Reference Module Registry Reference Modules Reference Public Logs Reference Public Service Remediation Reference macOS SDK Roadmap Security Troubleshooting
1 Deployment and Operations
picklemustard edited this page 2026-09-07 15:49:27 -04:00
Table of Contents

Deployment and operations

Current deployment model

The base Kubernetes manifests run the API with a Docker-in-Docker sidecar. The sidecar is privileged and starts as a native sidecar before the API. The server performs Git preparation; the daemon launches compiler containers. This is distinct from the unfinished Kubernetes phase executor.

Review deploy/k8s (deploy/k8s/README.md in the repo) and the deployment history. Some historical sections describe older settings; inspect the actual manifests before applying them.

Prepare a deployment

  1. Provision PostgreSQL and a private artifact bucket. Public mode also requires Redis, Turnstile, and administrative authentication through ingress.
  2. Build application and toolchain images with make server-image, make gateway-image, and make images. Publish the images to a registry the relevant runtimes can access.
  3. Supply application secrets, registry credentials, and private module SSH identity where needed. Keep gateway credentials separate and read-only for artifacts.
  4. Configure persistent storage and resource limits. The API and dind must see the same /data workspace path with workspace_mount: bind.
  5. Configure HTTPS ingress, identity-header handling, trusted proxy CIDRs, and private origin access for public mode.
  6. Render and review the overlay before applying it to your intended cluster.
kubectl kustomize deploy/k8s
# After customizing configuration, secrets, images, and infrastructure:
kubectl apply -k deploy/k8s

Images in the Kubernetes node runtime are not automatically available inside dind. Toolchain images must be available to the daemon that actually starts compilation. Keep its unauthenticated loopback endpoint private to the pod.

The local overlay guide (deploy/local/README.md in the repo) covers k3s/k3d, host service addresses, registry secrets, and image loading. It does not provision PostgreSQL, Redis, or object storage.

Private download gateway

Route /api/v1/builds/{id}/artifacts/{name} directly to the gateway on the same HTTPS origin as the API. Verification cookies depend on that origin. Set GBB_DOWNLOAD_GATEWAY_ENABLED=true on the API at cutover; a misrouted download then fails rather than falling back to old delivery.

The gateway reads publication metadata and private objects, checks verification and bans, and supports bounded range transfers. Disable ingress/CDN caching and buffering for downloads. It performs no migrations; start the API to establish the database schema first.

Use gateway deployment and grants for the exact environment, role permissions, routing, and readiness requirements.

Health, storage, and recovery

Use /livez for process liveness and /readyz for dependency readiness. A dependency outage should remove an instance from service rather than be treated as proof that the process needs restarting. Inspect startup logs when the API cannot initially connect to required services.

Monitor queue age, failed builds, lease losses, disk space, compiler memory, storage errors, and enforcement dependency failures. Compilation parallelism multiplies memory and CPU use; increasing replicas is not sufficient proof that shared caches and raw log access work across workers.

Back up PostgreSQL, retained artifacts, and private logs according to their required recovery windows. Repository and compiler caches can be rebuilt, but require time and storage. Test restoration with consistent publication metadata and objects. Do not remove active workspace or daemon storage directories as a routine disk-space fix.

Artifact retention stamps deadlines at successful completion. Expired objects become unavailable even if users retain their links. Log and audit collectors have separate policies. Public admission/IP retention and external proxy access-log retention also require attention; see abuse enforcement.

Deployment acceptance

Before relying on a deployment, exercise a real compile, module checkout, mid-build cancellation, worker restart, and artifact download/checksum round trip. In public mode also verify identity-header spoof rejection, session/IP binding, cross-replica enforcement, range downloads, and gateway credential restrictions through the real ingress.

Recorded test results in design documents are scoped to those tests. Kubernetes server-side dry runs do not prove scheduling, PVC provisioning, network isolation, or recovery. Follow the public-service work plan for outstanding launch work.

Guide

Reference

Project