Quick Start

Quick Start

This is the shortest honest path to a working GloriousFlywheel stack from this repo against the current on-prem target.

Current Target

For the current Tinyland on-prem rollout:

  • physical cluster: honey
  • primary kubeconfig: ~/.kube/kubeconfig-honey.yaml
  • primary context: honey
  • current API server: https://100.113.89.12:6443
  • former compatibility context: tinyland-civo-dev (Civo decommissioned April 2026)
  • former compatibility kubeconfig: ~/.kube/kubeconfig-civo.yaml

Important:

  • honey is the only cluster target for this rollout
  • bumble and sting are node-role inputs inside honey, not separate clusters
  • GloriousFlywheel dev and prod remain logical deploy environments that can both map to honey

Placement bias:

  • control plane and operator-facing services on honey
  • durable backing state on bumble
  • explicit stateless compute expansion on sting
  • no dependence on Civo (decommissioned April 2026)

1. Enter The Tooling Environment

git clone https://github.com/tinyland-inc/GloriousFlywheel.git
cd GloriousFlywheel
direnv allow

If you prefer not to use direnv:

nix develop

Developer Contract

After direnv allow or nix develop, GloriousFlywheel development should use the same shared substrate contract as CI. On current main, that only becomes shared-cache-backed Bazel dogfood once the shell has a real BAZEL_REMOTE_CACHE value; otherwise the shell stays in compatibility-local mode. Heavy Bazel, Nix, and toolchain work should not be documented as “just run it locally and hope the cache helps.”

Start each session by checking the actual shell state:

just info

For Bazel dogfood, prefer just cache-contract-strict, then just bazel-build-cached once the shell is attached to a real BAZEL_REMOTE_CACHE value and GF_BAZEL_SUBSTRATE_MODE is shared-cache-backed.

Treat raw local bazel build, raw local bazel test, bazelisk, and --config=ci as compatibility or debug paths only.

Current main proves cache-backed local execution with shared cache acceleration. It does not yet by itself prove full remote execution for every developer workload, so keep that boundary explicit.

For the exact cache attachment contract, see Cache and State Backend Roles and Cache Integration. Do not substitute historical fuzzy-dev, attic-cache-dev, or repo-shaped runner endpoints for the missing local Bazel value.

2. Bootstrap On-Prem Access

The current host-secret materialization and baseline checks live in adjacent operator tooling, not in this repo. Run them before you try to deploy from GloriousFlywheel:

just host-secrets-materialize
source /tmp/blahaj-host-secrets.env
just cluster-access-audit-local
just onprem-baseline-check

3. Set Cluster Access

export KUBECONFIG=~/.kube/kubeconfig-honey.yaml
export KUBE_CONTEXT=honey
kubectl --context honey cluster-info
kubectl --context honey get nodes -o wide

The Kubernetes API should remain private and tailnet-only. Do not introduce a new public management path.

The Civo cloud path (tinyland-civo-dev) has been decommissioned as of April 2026 and is no longer available.

4. Copy Local Config

cp config/organization.example.yaml config/organization.yaml
cp .env.example .env
mkdir -p config/backends

Update config/organization.yaml with your real domains and any local backend coordinates you use. In the current Tinyland shape, both logical environments can map to context: honey.

5. Choose Backend Init

All four active stacks on current main now use backend "s3" directly. Treat environment-owned S3-compatible state on honey as the normal backend contract for local init.

The preferred local init paths are:

  • config/backends/<stack>-<env>.hcl
  • TOFU_BACKEND_CONFIG_FILE
  • TOFU_BACKEND_CONFIG_DIR
  • TOFU_BACKEND_S3_*

Keep TF_HTTP_* and just tofu-init-gitlab-legacy <stack> only for legacy or archived HTTP-backend repair work.

Preferred:

just tofu-backend-scaffold-s3 arc-runners

The scaffolded file becomes the implicit local default for just tofu-init arc-runners. On current main, that is the live S3-compatible backend family for arc-runners.

Alternative:

export TF_HTTP_ADDRESS=https://state.example.com/terraform/runner-dashboard-dev
export TF_HTTP_LOCK_ADDRESS=https://state.example.com/terraform/runner-dashboard-dev/lock
export TF_HTTP_UNLOCK_ADDRESS=https://state.example.com/terraform/runner-dashboard-dev/lock
export TF_HTTP_USERNAME=operator
export TF_HTTP_PASSWORD=...

If you already have real values exported in your shell and are repairing a legacy HTTP backend path, you can persist them into a local stack file without editing HCL by hand:

just tofu-backend-materialize-http <legacy-stack>

If you already have real S3-compatible values exported in your shell and want to capture them into a local backend file:

export TOFU_BACKEND_S3_ENDPOINT=http://s3.example.com:9000
export TOFU_BACKEND_S3_BUCKET=gloriousflywheel-state
export TOFU_BACKEND_S3_ACCESS_KEY=...
export TOFU_BACKEND_S3_SECRET_KEY=...
just tofu-backend-materialize-s3 arc-runners

All four active stacks now use this S3-compatible path directly on current main.

For the current proven honey baseline, ENV=dev uses these live S3 keys:

  • attic -> attic/terraform.tfstate
  • arc-runners -> arc-runners/terraform.tfstate
  • gitlab-runners -> tinyland-infra/gitlab-runners/terraform.tfstate
  • runner-dashboard -> tinyland-infra/runner-dashboard/terraform.tfstate

If you need a different environment or a different key layout, set TOFU_BACKEND_S3_KEY explicitly before materializing the backend file.

To inspect the current stack contract directly:

just tofu-state-contract runner-dashboard

Legacy compatibility:

just tofu-backend-materialize-gitlab-legacy <legacy-stack>
export TF_HTTP_PASSWORD=glpat-...
just tofu-init-gitlab-legacy <legacy-stack>

Use the GitLab path only if you still rely on legacy GitLab-managed HTTP state. This requires gitlab.project_id in config/organization.yaml. Archived mirrors like tinyland/gf-overlay are not enough by themselves; this path only works when a real GitLab project owns OpenTofu state.

Before tofu init, run:

ENV=dev just tofu-backend-audit

That gives a one-screen read across all four active stacks and will tell you whether the current blocker is missing local scaffolding or one shared backend authority decision.

6. Copy The Stack Tfvars You Need

cp tofu/stacks/attic/terraform.tfvars.example tofu/stacks/attic/dev.tfvars
cp tofu/stacks/arc-runners/terraform.tfvars.example tofu/stacks/arc-runners/dev.tfvars
cp tofu/stacks/runner-dashboard/terraform.tfvars.example tofu/stacks/runner-dashboard/dev.tfvars

Set cluster_context = "honey" in the tfvars you actually use unless you are intentionally exercising a transitional compatibility path.

For arc-runners, the local operator path also includes <env>-policy.tfvars before local overrides and <env>-extra-runner-sets.tfvars when present, so the committed ARC baseline and additive lanes like tinyland-nix-heavy are part of the same local rollout.

7. Deploy In Order

Cache first:

ENV=dev just tofu-preflight attic
ENV=dev just tofu-init attic
ENV=dev just tofu-plan attic
ENV=dev just tofu-apply attic

Then ARC if you need GitHub Actions capacity:

ENV=dev just tofu-preflight arc-runners
ENV=dev just tofu-init arc-runners
ENV=dev just tofu-plan arc-runners
ENV=dev just tofu-apply arc-runners

Then the dashboard:

ENV=dev just tofu-preflight runner-dashboard
ENV=dev just tofu-init runner-dashboard
ENV=dev just tofu-plan runner-dashboard
ENV=dev just tofu-apply runner-dashboard

Deploy gitlab-runners only if you still need the legacy GitLab runner path.

8. Verify

kubectl --context honey get pods -n nix-cache
kubectl --context honey get pods -n arc-systems
kubectl --context honey get pods -n arc-runners
kubectl --context honey get pods -n runner-dashboard

Notes

  • just tofu-plan and related recipes read cluster_context from config/organization.yaml, unless you override with KUBE_CONTEXT
  • the canonical rollout sentence is: move runner/control workloads into the honey cluster only, keep them tailnet-only, put durable backing state on bumble, and use sting only for explicit stateless compute capacity
  • just tofu-preflight <stack> is the shortest local check before init; it validates organization.yaml, kubeconfig/context resolution, stack tfvars, and the currently configured backend-init path
  • the active root operator path now uses the environment-owned S3-compatible backend family for the four live stacks on honey; generic HTTP and stack-local GitLab init entrypoints are legacy compatibility-only paths
  • the current live Tinyland cache runtime is in namespace nix-cache, not attic-cache-dev
  • current dashboard release authority is still the GHCR image path, not a standalone Nix artifact or FlakeHub publication path

GloriousFlywheel