wehub-resource-sync
225 lines
11 KiB
Plaintext
225 lines
11 KiB
Plaintext
---
|
|
title: Config as code
|
|
description: Manage InsForge auth, SMTP, storage, retention, and deployment settings declaratively from a single insforge.toml using the CLI's plan, apply, and export workflow.
|
|
---
|
|
|
|
## Overview
|
|
|
|
`insforge.toml` is a declarative, version-controlled snapshot of a subset of your project's config: auth policy, allowed redirect URLs, password rules, SMTP, storage upload size, realtime and schedule retention, and the deployment subdomain. The CLI provides three commands that work against this file:
|
|
|
|
- **`config plan`**: diff `insforge.toml` against the linked project. Shows what would change.
|
|
- **`config apply`**: push the diff to the live project. Per-change capability gating, env-resolved secrets, dry-run mode.
|
|
- **`config export`**: pull current project state and write a fresh `insforge.toml`. Useful for bootstrapping from an existing project.
|
|
|
|
You keep **one** `insforge.toml` in your repo. To apply it to a different environment (staging, prod, a teammate's local backend, or a self-hosted instance), point the CLI at a different project (re-link or use `--project-id`). Secrets are read from environment variables via `env(...)` references, so the file itself stays free of credentials and can be committed safely.
|
|
|
|
This works the same way on InsForge Cloud projects and on self-hosted OSS deployments.
|
|
|
|
<Note>
|
|
All examples use `npx @insforge/cli`. Do not install the CLI globally.
|
|
</Note>
|
|
|
|
## Command summary
|
|
|
|
| Command | Purpose |
|
|
|---------|---------|
|
|
| `config plan` | Show diff between `insforge.toml` and live project state |
|
|
| `config apply` | Apply `insforge.toml` to the live project |
|
|
| `config apply --dry-run` | Print the plan without applying |
|
|
| `config apply --auto-approve` | Skip the interactive confirmation prompt (required in `--json` mode) |
|
|
| `config export` | Pull live config and write `insforge.toml` |
|
|
| `config export --force` | Overwrite an existing `insforge.toml` without confirmation |
|
|
|
|
`config plan` and `config apply` read `insforge.toml`; pass `--file <path>` if it lives somewhere other than `./insforge.toml`. `config export` writes the file; pass `--out <path>` to write it to a custom location.
|
|
|
|
## Recommended workflow
|
|
|
|
<Steps>
|
|
<Step title="Bootstrap from an existing project">
|
|
If you already configured the project through the dashboard, export it once to get a working file:
|
|
|
|
```bash
|
|
npx @insforge/cli config export
|
|
```
|
|
|
|
This writes `insforge.toml` reflecting the current backend state.
|
|
</Step>
|
|
|
|
<Step title="Commit it">
|
|
Check `insforge.toml` into version control. Secrets are referenced via `env(...)`, so the file is safe to commit.
|
|
</Step>
|
|
|
|
<Step title="Edit and plan">
|
|
Change the TOML, then preview the diff before applying:
|
|
|
|
```bash
|
|
npx @insforge/cli config plan
|
|
```
|
|
</Step>
|
|
|
|
<Step title="Apply">
|
|
```bash
|
|
npx @insforge/cli config apply
|
|
```
|
|
|
|
Review the rendered plan and confirm. In CI, pass `--auto-approve` and `--json`.
|
|
</Step>
|
|
|
|
<Step title="Apply the same file elsewhere">
|
|
To push the same config to staging or a self-hosted backend, point the CLI at the other project and re-run apply:
|
|
|
|
```bash
|
|
npx @insforge/cli --project-id <staging-project-id> config apply
|
|
```
|
|
|
|
Secrets that differ between environments (SMTP password, etc.) are resolved per-environment from the local shell, so the TOML doesn't need to change.
|
|
</Step>
|
|
</Steps>
|
|
|
|
## What `insforge.toml` covers
|
|
|
|
The file mirrors a curated subset of project config, the parts that are useful to manage declaratively. Anything not in this list still lives on the dashboard and the API.
|
|
|
|
| Section | Keys |
|
|
|---------|------|
|
|
| `[auth]` | `allowed_redirect_urls`, `require_email_verification`, `verify_email_method`, `reset_password_method`, `disable_signup` |
|
|
| `[auth.password]` | `min_length`, `require_number`, `require_lowercase`, `require_uppercase`, `require_special_char` |
|
|
| `[auth.smtp]` | `enabled`, `host`, `port`, `username`, `password`, `sender_email`, `sender_name`, `min_interval_seconds` |
|
|
| `[storage]` | `max_file_size_mb` |
|
|
| `[realtime]` | `retention_days` |
|
|
| `[schedules]` | `retention_days` |
|
|
| `[deployments]` | `subdomain` |
|
|
|
|
Because TOML has no `null` literal, use `retention_days = 0` to disable retention cleanup for realtime messages or schedule execution logs; `config apply` sends `null` to the backend for that value. Email templates, OAuth provider app credentials, buckets, realtime channels, functions, deployment environment variables, and secrets are not managed through this file.
|
|
|
|
A complete example:
|
|
|
|
```toml
|
|
[auth]
|
|
require_email_verification = true
|
|
verify_email_method = "code"
|
|
reset_password_method = "code"
|
|
disable_signup = false
|
|
allowed_redirect_urls = [
|
|
"https://app.example.com/auth/callback",
|
|
"http://localhost:3000/auth/callback",
|
|
]
|
|
|
|
[auth.password]
|
|
min_length = 12
|
|
require_number = true
|
|
require_lowercase = true
|
|
require_uppercase = true
|
|
require_special_char = false
|
|
|
|
[auth.smtp]
|
|
enabled = true
|
|
host = "smtp.sendgrid.net"
|
|
port = 587
|
|
username = "apikey"
|
|
password = "env(SENDGRID_API_KEY)"
|
|
sender_email = "noreply@example.com"
|
|
sender_name = "Acme"
|
|
|
|
[storage]
|
|
max_file_size_mb = 100
|
|
|
|
[realtime]
|
|
retention_days = 7
|
|
|
|
[schedules]
|
|
retention_days = 0
|
|
|
|
[deployments]
|
|
subdomain = "acme-prod"
|
|
```
|
|
|
|
## `config plan`
|
|
|
|
```bash
|
|
npx @insforge/cli config plan
|
|
npx @insforge/cli config plan --file ./config/insforge.toml
|
|
npx @insforge/cli --json config plan
|
|
```
|
|
|
|
`plan` reads `insforge.toml`, fetches live state via `/api/metadata` and the optional config endpoints for storage, realtime, and schedules, then prints a rendered diff. It also tags any section the live backend doesn't expose yet (older self-hosted versions, etc.). Apply will skip those instead of failing the whole run.
|
|
|
|
Use `plan` before every `apply` in interactive sessions, and as a CI gate to catch unintended drift.
|
|
|
|
## `config apply`
|
|
|
|
```bash
|
|
npx @insforge/cli config apply
|
|
npx @insforge/cli config apply --dry-run
|
|
npx @insforge/cli config apply --auto-approve
|
|
npx @insforge/cli --json config apply --auto-approve
|
|
```
|
|
|
|
`apply` runs the same diff as `plan`, then walks the change set:
|
|
|
|
1. **Per-change capability gate.** Each change is checked against the backend's metadata or the section's config endpoint. If the backend doesn't support a section (e.g. an older self-hosted instance without SMTP exposed), that section is skipped with a named warning, and the rest of the changes still apply.
|
|
2. **Secret resolution.** `env(...)` references in the TOML are resolved at apply time from the local environment. If a referenced variable is missing, the command aborts before sending any update, so the backend isn't left half-configured.
|
|
3. **Per-section dispatch.** Each change is sent to the appropriate backend endpoint (`/api/auth/config`, `/api/auth/smtp-config`, `/api/storage/config`, `/api/realtime/config`, `/api/schedules/config`, `/api/deployments/slug`, etc.). Changes are independent, so a failure on one section won't roll back earlier successful sections.
|
|
|
|
Flags:
|
|
|
|
- `--dry-run` prints the plan and exits without applying.
|
|
- `--auto-approve` skips the interactive confirmation. Required when `--json` is set, since there's no TTY for the prompt.
|
|
- `--file <path>` overrides the default `./insforge.toml` location.
|
|
|
|
## `config export`
|
|
|
|
```bash
|
|
npx @insforge/cli config export
|
|
npx @insforge/cli config export --out ./config/insforge.toml
|
|
npx @insforge/cli config export --force
|
|
```
|
|
|
|
`export` pulls the live project's configurable surface and writes it to a TOML file. Use it to:
|
|
|
|
- Bootstrap an `insforge.toml` from a project you've been configuring through the dashboard.
|
|
- Diff hand-edits against current backend state by exporting to a temporary file and comparing.
|
|
- Snapshot config before a risky change so you can re-apply the snapshot if you need to roll back.
|
|
|
|
The file written by `export` is the same shape the CLI expects from `apply`, so round-tripping is supported.
|
|
|
|
Without `--force`, `export` refuses to overwrite an existing file in interactive mode and surfaces an `OUTPUT_EXISTS` error in `--json` mode.
|
|
|
|
## Secret references
|
|
|
|
`auth.smtp.password` and any other sensitive field can be expressed as `env(VAR_NAME)` instead of a literal value:
|
|
|
|
```toml
|
|
[auth.smtp]
|
|
password = "env(SENDGRID_API_KEY)"
|
|
```
|
|
|
|
At apply time the CLI reads `SENDGRID_API_KEY` from the local environment, validates it's present, and sends the resolved value to the backend. The TOML itself never contains the secret, so it can be committed.
|
|
|
|
This is what lets one `insforge.toml` apply cleanly to multiple environments: the dev and prod backends differ only in *which* `SENDGRID_API_KEY` is in scope when you run `apply`.
|
|
|
|
`env(...)` refs in a TOML that's the target of `apply` re-send the resolved password on every run. That is the only way the CLI can tell the backend "the secret may have rotated, please update." Fields without an `env(...)` ref are treated as preserve-existing.
|
|
|
|
## When to use this
|
|
|
|
- **Version control for project config.** Redirect URLs, sign-up policy, password policy, email verification mode, SMTP, storage upload size, and retention windows live in a file your team reviews via PR.
|
|
- **Multi-environment parity.** One TOML, applied to dev, staging, and prod, keeps the supported project settings aligned everywhere. Environment-specific values (subdomain, SMTP credentials) flow through `--project-id` overrides and `env(...)` refs.
|
|
- **CI-driven config changes.** Run `config apply --auto-approve --json` from your deploy pipeline. Combine with `config plan` as a PR check so reviewers see what the merge will change in prod.
|
|
- **Disaster recovery.** A committed `insforge.toml` is a known-good config snapshot. Re-apply it after restoring a project to bring auth, SMTP, storage, retention, and deployment settings back to the expected shape in seconds.
|
|
- **Self-hosted and local OSS development.** Run `npx @insforge/cli link --api-base-url http://localhost:7130 --api-key <local-key>` against a docker-compose stack, then point the CLI's config commands at your local OSS instance the same way you'd point at cloud.
|
|
|
|
## Troubleshooting
|
|
|
|
**`Refusing to apply in --json mode without --auto-approve or --yes`.** The CLI never silently applies changes in non-interactive runs. Pass `--auto-approve` (or `-y`) explicitly.
|
|
|
|
**`your backend doesn't expose <section>`.** The linked backend is on a version that doesn't have the relevant API yet. The rest of your changes still applied. Upgrade the backend (or wait for the next release) to apply that section.
|
|
|
|
**`env(...)` reference resolves to nothing.** The CLI aborts before any API call when a referenced env var is missing. Set the variable in your shell or your CI's secret store and re-run.
|
|
|
|
**`Slug is already taken`.** `deployments.subdomain` conflicts with another project's subdomain on the same backend. Pick a different value.
|
|
|
|
## Related
|
|
|
|
- [CLI harness](/agent-native/cli-harness): the full command surface an agent drives
|
|
- [Deployment security guide](/deployment/deployment-security-guide): hardening a self-hosted backend after deploy
|