Forkr setup commands keep local deployment state in a .forkr directory. This directory is not part of the deployed box runtime. It belongs to the machine running 4kr setup and stores the config, generated state, secrets, logs, and deploy bundle needed to create or update a Forkr environment.
Do not commit .forkr. It can contain API tokens, JWT secrets, TLS private keys, SSH host keys, cloud service-account material, and generated GitHub App credentials.
Location
4kr resolves the setup directory in this order:
FORKR_SETUP_DIR, when set to a non-empty value.- The nearest parent directory that already contains
.forkr/config.yaml or .forkr/setup-state.json.
- The Forkr source checkout root, when the current directory is inside a Forkr checkout.
- The current working directory.
That means source-tree development normally uses <repo>/.forkr. A repo-free install run from another directory creates .forkr in that directory unless FORKR_SETUP_DIR points somewhere else.
Contents
| Path | Purpose |
|---|
.forkr/config.yaml | Local setup config: selected profile, domains, cloud settings, auth settings, generated API token, generated JWT secret, and optional file paths for TLS and cloud credentials. |
.forkr/setup-state.json | Machine-readable progress for setup steps such as preflight, bundle preparation, secrets, deploy, destroy, GitHub App configuration, and the setup UI. |
.forkr/repo/ | The deploy bundle used by setup commands. It contains the scripts, Ansible files, Kubernetes manifests, base definitions, Rust crates, and web assets needed to deploy. |
.forkr/logs/ | Logs from deploy, destroy, dashboard deploy, docs deploy, and API-only redeploy operations. |
.forkr/secrets/ | Locally generated or stored secret inputs, such as SSH host keys and service-account JSON files. |
.forkr/lego/ | ACME account and certificate state created by lego for wildcard TLS certificates. |
Deploy bundle
Setup commands run from .forkr/repo, not directly from arbitrary files in the current directory. 4kr setup bundle, 4kr setup deploy, 4kr setup secrets, 4kr setup destroy, and GitHub App redeploy all call the same bundle preparation path.
When 4kr is run inside a Forkr source checkout, it copies a selected set of source-tree paths into .forkr/repo:
Cargo.toml
Cargo.lock
bases/
crates/
infra/
k8s/
scripts/
ts/
docs/
old_docs/
4kr is run outside a source checkout, it reuses an existing .forkr/repo if it contains scripts/from-scratch.sh. If that bundle is a git checkout, setup updates it with git pull --ff-only. If no bundle exists, setup clones or downloads the configured source bundle into .forkr/repo.
The deploy bundle is allowed to contain generated files. During deploy, setup writes:
infra/group_vars/<profile>.ymlinfra/inventory.yml- the configured SOPS secrets file, usually
infra/secrets/<profile>.sops.yaml
Keeping these generated files in the bundle lets setup deploy from a stable working directory without requiring the caller to manually edit the source checkout.
Config and generated values
4kr config set writes directly to .forkr/config.yaml. Some values are generated automatically the first time effective config is loaded:
api_tokenauth_jwt_secret- defaults derived from
forkr_domain, such as api_url, boxes_domain, and ssh_host
- the default SOPS secrets file path, derived from
profile
The setup profile can be overridden for a command with FORKR_SETUP_PROFILE. The stored profile remains in config.yaml; the override only changes the effective config for that invocation.
Secrets
4kr setup secrets renders deploy secrets from configured values and input files, then encrypts them with SOPS. The generated encrypted file is written to the configured secrets path. If setup is running from a source checkout and deploying from a copied bundle, it also mirrors that encrypted secret into .forkr/repo so Ansible can read it from the bundle.
Local files under .forkr/secrets and .forkr/lego are still sensitive even when the deploy secret file is encrypted.
Status and logs
4kr setup status reads .forkr/setup-state.json. The setup UI also serves this state so a browser can show the current step and latest message.
Deploy and destroy commands stream output to the terminal and to timestamped files under .forkr/logs. Failure messages usually include the exact log path and rerun command.
Cleaning up
Deleting .forkr/repo removes the local deploy bundle. The next setup command will recreate it.
Deleting .forkr/logs removes only local logs.
Deleting .forkr/config.yaml, .forkr/secrets, or .forkr/lego removes local credentials and setup inputs. Do that only when you intend to reconfigure or regenerate the deployment state.