diff --git a/.github/workflows/lint-docs.yml b/.github/workflows/lint-docs.yml deleted file mode 100644 index 3c900437..00000000 --- a/.github/workflows/lint-docs.yml +++ /dev/null @@ -1,15 +0,0 @@ -name: Lint docs - -on: - pull_request: - paths: - - "docs/**" - -permissions: - contents: read - -jobs: - docs: - uses: Kong/volcano-docs/.github/workflows/lint-docs.yml@06b40d8613779ad44bca0aceaca0d8f11bc25652 # main - with: - path: docs diff --git a/AGENTS.md b/AGENTS.md index 4dbc6613..7b238e5d 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -2,30 +2,14 @@ ## Documentation -Everything under `docs/` is **published** — CI syncs it to the public developer -docs site (`Kong/volcano-docs`). So `docs/` is for **end-user-facing docs only**: -the commands, flags, and behavior a Volcano user relies on. +Public CLI docs live in [`Kong/volcano-docs`](https://github.com/Kong/volcano-docs) +under `content/cli` and publish to https://docs.volcano.dev/cli. This +repository no longer carries published docs. -**When you add or change user-facing behavior, update the matching doc under -`docs/` in the same PR.** Do **not** put internal or maintainer material in -`docs/` — dev-only env vars and overrides (e.g. pointing the CLI at a specific -API endpoint for local testing), design notes, or implementation detail. That -lives **next to the code it describes**: a code comment, or a notes/README file -in the relevant package — never under `docs/`, which is the sync target. When -unsure whether something is meant for users, keep it out of `docs/`. +**When you add or change user-facing behavior, open a companion PR in +`Kong/volcano-docs` that updates `content/cli`**, following its format contract +(`spec/markdown-format.md`), and link the two PRs. -Every doc must follow the Volcano docs format -(https://github.com/Kong/volcano-docs/blob/main/spec/markdown-format.md): - -- YAML frontmatter with **`title`** and **`description`** (both required). -- **No H1 in the body** — the title comes from frontmatter; start at `##`. -- `kebab-case.md` filenames; `_index.md` (or `README.md`) for a section landing. -- Every fenced code block declares a language. -- For links within `docs/`, use a relative path with the `.md` extension. For - links to another docs section, use a site-absolute path without an extension, - such as `/platform/functions/overview` or `/sdk/js/authentication`. Do not use - source-root paths such as `/commands`; this repository is synced under `/cli`. - -The shared lint (`.github/workflows/lint-docs.yml`) validates this on PRs that -touch `docs/`, and `internal/docs` parses the frontmatter for `volcano docs -search`, so malformed docs fail CI. +Keep internal or maintainer material — dev-only env vars and overrides, design +notes, implementation detail — next to the code it describes: a code comment, +or a notes/README file in the relevant package. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 47ab3d18..8d439fd8 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -162,4 +162,4 @@ curl -fsSL https://download.volcano.dev/builds/install.sh | bash Set `VOLCANO_VERSION=vMAJOR.MINOR.PATCH` to install a pinned release. To verify the installer against `install.sh.sigstore.json` before running it, follow -[Installation](docs/installation.md). +[Installation](https://docs.volcano.dev/cli/installation). diff --git a/README.md b/README.md index 06519ea1..f4dcf0b5 100644 --- a/README.md +++ b/README.md @@ -61,14 +61,13 @@ files, migrations directory, and README). Use a template to add language-specific files: `javascript` (aliases: `js`, `node`, `nodejs`), `nextjs`, `python`, or `ruby`. -More detail lives in `docs/`: - -- [Installation details](docs/installation.md) -- [Authentication](docs/authentication.md) -- [Deploy a project](docs/deploy.md) -- [Project configuration](docs/project-configuration.md) -- [CLI operations overview](docs/cli/overview.md) -- [Documentation search (`volcano docs`)](docs/docs-search.md) +More detail lives in the [CLI docs](https://docs.volcano.dev/cli): + +- [Installation details](https://docs.volcano.dev/cli/installation) +- [Authentication](https://docs.volcano.dev/cli/authentication) +- [Deploy a project](https://docs.volcano.dev/cli/deploy) +- [Project configuration](https://docs.volcano.dev/cli/project-configuration) +- [Documentation search (`volcano docs`)](https://docs.volcano.dev/cli/docs-search) ## Contributing diff --git a/docs/README.md b/docs/README.md deleted file mode 100644 index abab5a8b..00000000 --- a/docs/README.md +++ /dev/null @@ -1,270 +0,0 @@ ---- -title: "CLI operations overview" -description: "This is a map of the Volcano building blocks (\"elements\") the CLI operates on, how they relate, and where the CLI can act on each." ---- - -This is a map of the Volcano building blocks ("elements") the CLI operates on, -how they relate, and where the CLI can act on each. Each element has its own -page with concrete command examples. For exact, always-current flags, run -`volcano --help`. - -## The model - -A **project** is the container for everything else. You authenticate, select an -active project, then operate on the resources inside it: - -```text -account (auth) -├── verified domains .......... domains you own, for custom domains → domains.md -└── project ................... volcano projects / use - ├── functions ............. deployed backend logic → functions.md - │ ├── uses → variables (config & secrets) - │ ├── connects → databases, storage - │ ├── runs on → a runtime - │ ├── invoked via → alias / HTTP / scheduler - ├── durable functions ..... long-running, checkpointed logic → durable-functions.md - ├── databases ............. managed Postgres → databases.md - │ └── schema changed by → migrations - ├── storage ............... buckets → objects, policies → storage.md - ├── variables ............. env vars / secrets → variables.md - ├── frontends ............. deployed sites, custom domains → frontends.md - ├── git connection ........ push-to-deploy from GitHub → git.md - ├── share and fork ........ one-click copies of a project → share.md - ├── access tokens ......... project-scoped CI credentials → access-tokens.md - ├── notifications ......... alerts when schedulers fail → notifications.md - ├── LavaFlow .............. diagnoses errors, opens fix PRs → lavaflow.md - ├── logs .................. search, tail, count runtime logs → logs.md - └── declarative config .... one YAML syncing the above → ../project-configuration.md -``` - -Cross-cutting concerns: - -- **Authentication** gates all cloud access — see [authentication.md](authentication.md). -- **Declarative configuration** applies settings across every element from one - manifest — see [project-configuration.md](project-configuration.md). -- **Git connection** lets a push deploy the project without a CLI invocation — - see [git.md](git.md). - -## Local vs. cloud target - -The CLI can operate against two targets: - -- **Local** development environment (`volcano start` / `stop` / `restart` / - `status` / `reset`), targeted by top-level resource commands. -- **Cloud** project — targeted with the `cloud` prefix (e.g. `volcano cloud - functions list`). - -Top-level resource commands (`volcano functions …`, `volcano durable …`, -`volcano databases …`, etc.) always target local development. They fail if the -local environment is not running; they do not fall back to cloud. Use the -explicit `volcano cloud …` prefix for cloud operations. - -## Output styling - -Command output is colorized to share one identity with `volcano setup`: success -marks and active states in orange, warnings in amber, errors in red, table -headers and titles in lava, and suggested commands in flame. Color is written -only to an interactive terminal. It is disabled automatically when output is -piped or redirected, in CI, or when `NO_COLOR` is set, so machine-read output -(including `--json`) stays plain. - -```bash -volcano databases list # colorized on a terminal -volcano databases list | cat # plain (piped) -NO_COLOR=1 volcano databases list -``` - -## Account credit notices - -Cloud commands can report when your account is running low on credits or has -no credits left. The notice includes the billing page address when available. -Open that page to add credits. These notices do not prompt or open a browser. -Piped, CI, and `NO_COLOR` output remains plain. Machine output is unchanged. - -## Telemetry - -The CLI sends one usage event per command: the command and flag names, the -project and resource names it acts on, error messages, CLI version, platform, -and which coding agent ran it. Turn it off with `volcano telemetry disable` or -`VOLCANO_TELEMETRY_DISABLED=1`. See [telemetry.md](telemetry.md). - -## Feedback - -`volcano feedback` sends the Volcano team a report about a problem with the -CLI, the platform, the docs, or the agent skills. Coding agents run it after a -task. Turning telemetry off also turns it off, unless you run `volcano feedback -enable`. Turn it off on its own with `volcano feedback disable`. See -[feedback.md](feedback.md). - -## Element → CLI ability at a glance - -| Element | CLI can… | Commands | Details | -|---|---|---|---| -| Get started | sign in, create a project, and link a directory in one step | `connect` | [connect.md](connect.md) | -| Account / auth | sign up, log in/out | `signup`, `login`, `logout` | [authentication.md](authentication.md) | -| Access tokens | create, list, get, revoke project credentials | `cloud access-tokens …` | [access-tokens.md](access-tokens.md) | -| Project | create, list, get, rename, delete, select, get keys and usage | `projects …`, `use` | below | -| Whole project | deploy variables, migrations, functions, frontends, and config in one run | `deploy`, `cloud deploy` | [deploy.md](deploy.md) | -| Deployments | list, inspect and summarize every function and frontend deployment | `deployments …`, `cloud deployments …` | [deployments.md](deployments.md) | -| Logs | search, tail and count logs across functions, frontends and databases | `logs …`, `cloud logs …` | [logs.md](logs.md) | -| Functions | deploy, invoke, inspect, set visibility, schedule, alias | `functions …` | [functions.md](functions.md) | -| Durable functions | deploy, start, inspect executions, read logs, schedule, decide approvals, send and read messages, answer callbacks | `durable …`, `cloud durable …` | [durable-functions.md](durable-functions.md) | -| Databases | create, inspect, delete, migrate | `databases …`, `migrations …` | [databases.md](databases.md) | -| Storage | manage buckets, objects, policies | `storage …` | [storage.md](storage.md) | -| Variables | deploy, list, get, delete | `variables …` | [variables.md](variables.md) | -| Notifications | alert by email or webhook when schedulers fail, rotate the webhook secret, send a test | `notifications …`, `cloud notifications …` | [notifications.md](notifications.md) | -| LavaFlow | turn on or off, set how far it goes, start runs, see stats and runs with their diagnoses | `cloud lavaflow …` | [lavaflow.md](lavaflow.md) | -| Frontends | deploy, inspect, custom domains, function and Frontend routes | `frontends …`, `cloud frontends …` | [frontends.md](frontends.md) | -| Share and fork | share the project, see and stop the share, list releases, fork a shared project | `share …`, `fork` | [share.md](share.md) | -| Config (declarative) | deploy/pull one YAML manifest | `config deploy`, `config pull` | [project-configuration.md](project-configuration.md) | -| Local environment | check prerequisites, start/stop/status/reset | `doctor`, `start`, `stop`, `restart`, `status`, `reset` | above | -| Coding agents | install Volcano skills/plugins, keep them current | `setup` | [setup.md](setup.md) | -| Documentation | search/read the docs | `docs …` | [docs-search.md](docs-search.md) | -| Scripts and agents | exit codes, JSON output | `--json` | [scripting.md](scripting.md) | - -## Projects - -A project owns all resources. Authentication and an active project are -prerequisites for cloud operations. - -```bash -volcano projects create my-app # create a project -volcano projects list # list your projects -volcano use my-app # set the active project -volcano connect . # link this directory to a new project -volcano projects get # project details -volcano projects rename eac37d5a-5f6f-42d8-acf6-0f2ae9c7a550 new-name # rename a project -volcano projects keys anon list # anon (publishable) API keys for the browser/SDK -volcano projects keys service list # backend service-key metadata for the active project -volcano projects usage # current-month and all-time usage totals -volcano projects delete my-app # delete -``` - -When your account has no projects, `volcano projects list` says so and -suggests `volcano projects create `. - -Inside a directory linked with `volcano connect`, commands use the linked -project. See [connect.md](connect.md#linked-directories). - -To run one `volcano cloud` command against another project, pass -`--project `. Every `volcano cloud` subcommand accepts it, and it -leaves the active project and any link unchanged: - -```bash -volcano cloud functions list --project my-app -volcano cloud lavaflow status --project eac37d5a-5f6f-42d8-acf6-0f2ae9c7a550 -``` - -`--project` takes an exact project name or ID, like `volcano use`. A project -it does not find fails the command before it runs, and exits `4`. Local -commands refuse `--project`: local development has one project. - -### Create a project from a cloud template - -Use `--template` to install a complete app in a new cloud project: - -```bash -volcano projects create my-board --template trellini -volcano projects create my-pixels --template pixel-board -volcano projects create my-pad --template collab-pad -``` - -To create a project as a copy of a shared project, use `--from`, or -`volcano fork`; see [share.md](share.md). - -The supported templates are `trellini`, `pixel-board`, and `collab-pad`. -An account token is required. Hosting creates a fresh database and deploys the -app's functions and frontends. These cloud installations do not write local -starter files like `volcano init`. - -Installation runs asynchronously. Project creation does not mean the app is -ready. Use the project ID printed by the create command to check progress: - -```bash -volcano projects get -``` - -Project details show the template status (`pending`, `running`, `ready`, or -`failed`) and phase (`database`, `restore`, `configure`, `deploy`, `verify`, or -`ready`). Wait for template status `ready` before using the app. If installation -fails, the project remains available for inspection or deletion: - -```bash -volcano projects delete -``` - -### Project details - -`volcano projects list` and `volcano projects get` show the project plan as -`HOBBY` or `SUPERAGENT` when the API provides it. - -`VOLCANO_PROJECT_ID` overrides the active project for a single invocation. -It is deprecated and will be removed in a future release, and a command that -uses it prints a warning on stderr. Select the project with `volcano use -`, or `volcano login --token --project ` in CI. -See [access-tokens.md](access-tokens.md#use-a-token). - -### Project keys - -`volcano projects keys` requires an explicit key type. -`volcano projects keys anon list [project-id]` lists publishable anon keys. -`volcano projects keys anon create [project-id]` creates a publishable -auth-only key using the server default. - -### Backend service keys - -Service keys are privileged backend credentials that bypass row-level security. -Never expose their values in frontend code, logs, shell history, or other -untrusted output. `list` and `get` show metadata by default. Use `--show-key` -only when you need the plaintext. `create` prints the new key; use `--json` -to script it: - -```bash -volcano projects keys service list --page 1 --limit 100 -volcano projects keys service create worker --permission functions.invoke --json -volcano projects keys service get --show-key -``` - -`--permission` is repeatable; `--permissions` is an equivalent spelling and -the two can be combined. Omitting both gives the key full access. Empty or blank -permission values are rejected so an intended restricted key cannot silently -fall back to full access. - -An explicit `[project-id]` takes precedence over the active project. Without -it, the deprecated `VOLCANO_PROJECT_ID` takes precedence over the active -project. Paginated list output includes a next-page command that retains -an explicit project ID. - -### Project usage - -`volcano projects usage [project-id]` prints each metric's current-month total -and all-time total. It does not print the hourly or daily time series returned -by the API. Project selection follows the same explicit ID, environment, then -active-project precedence described above. - -## Starting a project - -```bash -volcano init javascript # scaffold a local project (js/nextjs/python/ruby) -volcano start # start the local dev environment -volcano status # check it -volcano deploy --with-migrations # deploy the whole project to it -``` - -See [deploy.md](deploy.md) for what `volcano deploy` and `volcano cloud deploy` -read and the order they deploy in. - -`volcano start`, `stop`, and `restart` need a Docker-compatible engine with the -Docker Compose v2 plugin (the `docker compose` subcommand). Run `volcano doctor` -to check both. - -`volcano start` runs the local stack from a bundled default server image. -Override it with `--image` or `VOLCANO_IMAGE`; an explicitly selected image must -already exist locally, since the CLI never pulls an unpublished local-mode image. - -```bash -volcano start --image kong/volcano:local-nightly -VOLCANO_IMAGE=kong/volcano:local-nightly volcano start -``` - -- [Sandboxes](sandboxes.md): isolated commands, sessions, files, and templates. diff --git a/docs/access-tokens.md b/docs/access-tokens.md deleted file mode 100644 index e91e7b3e..00000000 --- a/docs/access-tokens.md +++ /dev/null @@ -1,212 +0,0 @@ ---- -title: "Access tokens" -description: "Project-scoped credentials for CI and automation, minted and revoked from the CLI." ---- - -## What it is - -A project access token (prefix `pt-`) is a credential that authenticates the -CLI against one project. It is the credential to put in CI: it reaches the -project it was minted in and nothing else, it carries a scope, and you can -revoke it without touching the rest of your account. - -Your own account token (prefix `pk-`), the one `volcano login` saves, reaches -every project you own. Only an account token can manage access tokens. - -## How it relates - -- Belongs to a **project**, and authenticates that project's commands: - functions, frontends, variables, databases, logs, and deploys. -- Cannot create, inspect, or revoke tokens, and cannot run account-wide - commands: `volcano projects list`, `volcano projects create`, `volcano - projects rename`, `volcano projects delete`, selecting a project by name, or - `volcano git connect`. `volcano cloud access-tokens usage` is the exception: - a token can report its own project's consumption, and its own day-by-day - series by ID, so a CI job needs nothing but the credential it already runs - with. `get --usage` is not, because reading one token's record is itself a - token operation. -- Carries one of two scopes: `full` matches your own access to that project; - `read_only` rejects writes. - -## CLI operations - -| Operation | Command | -|---|---| -| Create | `volcano cloud access-tokens create [--scope ] [--expires-at ] [--json]` | -| List | `volcano cloud access-tokens list [--search ] [--include-revoked] [--json]` | -| Get | `volcano cloud access-tokens get [--usage] [--days ] [--json]` | -| Usage | `volcano cloud access-tokens usage [] [--days ] [--json]` | -| Revoke | `volcano cloud access-tokens revoke [--yes]` | - -`tokens` is an alias for `access-tokens`. These are cloud commands: local -development issues no credentials. - -## Create a token - -```bash -volcano cloud access-tokens create ci-deploy -``` - -```text -✓ Access token 'ci-deploy' created -ID: 7f1c2e94-2a6b-4c17-9a42-1b0c8f5d3e77 -Scope: full -Expires: never - -Token: pt-xxxxxxxxxxxxxxxxxxxxxxxx -Warning: Copy this token now. It is shown once and cannot be retrieved again. -``` - -The secret is returned only by `create`. Read commands show the token's prefix, -never the secret, so store it when you create it. - -Scope the token down and give it an expiry when you can: - -```bash -volcano cloud access-tokens create ci-audit \ - --scope read_only \ - --expires-at 2027-01-31T00:00:00Z -``` - -`--expires-at` takes an RFC3339 timestamp. Without it the token never expires. - -The secret is printed once and never again. For a script, take it from `--json` -rather than parsing the human output: - -```bash -secret=$(volcano cloud access-tokens create ci-deploy --json | jq -r .token) -``` - -## Set the right project - -A project access token only works on the project it was created in, and the -token and the project are resolved separately: setting `VOLCANO_TOKEN` on a -machine that has already logged in leaves the project as whatever -`volcano use` selected last. If that is a different project, every command -returns a permission error — the CLI names the project it ran against so you -can tell that apart from a genuine permission problem. - -## Use a token - -Log in with it, naming the project once: - -```bash -volcano login --token pt-xxxxxxxxxxxxxxxxxxxxxxxx --project eac37d5a-5f6f-42d8-acf6-0f2ae9c7a550 -volcano cloud functions deploy --all -``` - -Or set it as `VOLCANO_TOKEN` and select the project it belongs to: - -```bash -export VOLCANO_TOKEN=pt-xxxxxxxxxxxxxxxxxxxxxxxx -volcano use eac37d5a-5f6f-42d8-acf6-0f2ae9c7a550 -volcano cloud functions deploy --all -``` - -`volcano use` saves the project to `~/.volcano/config.json`, or, inside a -[linked directory](connect.md#linked-directories), updates the link. -`volcano login --token pt-… --project` inside a linked directory does both. A -repository that commits its `.volcano/project.json` needs only `VOLCANO_TOKEN`: -commands run there use the linked project. `volcano connect` gitignores the -link, so remove that entry to commit it. - -A project access token cannot list projects, so nothing can work out which -project it belongs to, and nothing can turn a project name into an ID — name it -by ID. - -`VOLCANO_PROJECT_ID` still selects the project, but it is deprecated and will -be removed in a future release. A command that uses it prints a warning on -stderr. - -Without `--project`, `login` uses the deprecated `VOLCANO_PROJECT_ID` when it -is set, else the project this directory is linked to in -`.volcano/project.json`, else the project `volcano use` last selected, which -belongs to whatever credential was logged in before. If that is not the -token's project, the failure says where the project came from. - -Run an account-wide command with one and the CLI says what is missing rather -than failing with a permission error: - -```bash -volcano projects list -``` - -```text -Error: this command needs an account token (pk-) but the current credential is a -project access token (pt-), which only reaches the project it was minted in. Run -'volcano login', or set VOLCANO_TOKEN to an account token -``` - -## Inspect and revoke - -```bash -volcano cloud access-tokens list -volcano cloud access-tokens get ci-deploy --usage --days 7 -volcano cloud access-tokens revoke ci-deploy -``` - -`list` shows the tokens that can still authenticate. A token that stopped — -revoked, or past its `--expires-at` — is hidden until you ask for it, and then -reports which it was in the `Status` column: - -```bash -volcano cloud access-tokens list --include-revoked -``` - -```text -Name Prefix Scope Status Last used Requests -ci-deploy pt-xxxxxxxx full active 3h ago 42 -ci-audit pt-4bN7sK1p read_only expired 20d ago 3 -ci-old pt-Zx8c5Vt2 full revoked 41d ago 77 -``` - -`--usage` adds the token's daily request counts, zero-filled and oldest first, -so every day in the window is present: - -```text -Day Requests ------------------------- -2026-09-14 18 -2026-09-15 0 -2026-09-16 24 - -42 request(s) over 3 day(s) -``` - -To compare tokens instead of days, `usage` totals the window for each one, -revoked tokens included: - -```bash -volcano cloud access-tokens usage --days 7 -``` - -```text -Name Requests --------------------------------------- -ci-deploy 42 -ci-audit 3 - -45 request(s) across 2 token(s) over 7 day(s) -``` - -Both take `--days`, up to 60, defaulting to 30. - -The `usage` reads are the ones a project access token can run for itself, so a -CI job can report what it consumed with nothing but the credential it already -holds — the whole project, or one token's day-by-day series: - -```bash -export VOLCANO_TOKEN=pt-xxxxxxxxxxxxxxxxxxxxxxxx -volcano use eac37d5a-5f6f-42d8-acf6-0f2ae9c7a550 -volcano cloud access-tokens usage --days 7 -volcano cloud access-tokens usage 7f1c2e94-2a6b-4c17-9a42-1b0c8f5d3e77 --days 7 -``` - -The series is addressed by token ID, the one `create` printed, because turning -a name into an ID needs the token list — an account operation. `get --usage` -reads the token's record first for the same reason, so it needs an account -token even for the running token's own counts. - -Revoking takes effect immediately and breaks every pipeline still using the -token. The record is kept with status `revoked`, so the token keeps its history -and still appears under `--include-revoked` and in `usage`. diff --git a/docs/agent-detection.md b/docs/agent-detection.md deleted file mode 100644 index a8a4ecbc..00000000 --- a/docs/agent-detection.md +++ /dev/null @@ -1,88 +0,0 @@ ---- -title: "Agent detection" -description: "How the Volcano CLI detects which coding agent ran a command, what it reports to the Volcano API, and how to set VOLCANO_AGENT." ---- - -## What it is - -When a coding agent runs a `volcano` command, the CLI works out which agent it -was and reports the name to the Volcano API with each request. This tells the -Volcano team which agents people build with. It is never used to allow or -block a request. The one thing it changes is the output of a failed command: -when a coding agent ran it and feedback can be sent, the CLI adds a line that -points the agent to `volcano feedback` (see [feedback.md](feedback.md)). An -agent found only by step 5 below does not count, since a person may be typing -in that terminal. - -Detection reads environment variables only. It does not read files or inspect -other processes, and the headers below carry no command arguments. The usage -event sends more, such as resource names and whether the Volcano plugin is -installed; see [telemetry.md](telemetry.md). - -The agent name is also part of the CLI's usage telemetry. The headers below are -not sent before the first-run telemetry notice, and turning telemetry off stops -them. See [telemetry.md](telemetry.md). - -## How the agent is detected - -Most coding agents set marker environment variables in the shell they run -commands in. The CLI checks these steps in order and uses the first that names -an agent: - -1. `AI_AGENT`, then `AGENT`. These are generic variables an agent can set to - its own name, such as `AI_AGENT=claude-code`. A value of `1`, `true`, `yes`, - or `on` means "an agent is running" without naming it, so the CLI keeps - looking for a name. A value of `0`, `false`, `no`, or `off` is ignored. -2. A variable set by one specific agent. If several are set, the first row in - this table wins: - - | Agent | Variables | - |---|---| - | Claude Cowork | `CLAUDE_CODE_IS_COWORK` | - | Claude Code | `CLAUDECODE`, `CLAUDE_CODE_ENTRYPOINT` | - | Codex | `CODEX_THREAD_ID`, `CODEX_SANDBOX`, `CODEX_CI` | - | Gemini CLI | `GEMINI_CLI` | - | Cursor CLI | `CURSOR_AGENT` | - | Cursor | `CURSOR_EXTENSION_HOST_ROLE=agent-exec` | - | OpenCode | `OPENCODE_CLIENT` | - | Augment | `AUGMENT_AGENT` | - | Antigravity | `ANTIGRAVITY_AGENT` | - -3. `VOLCANO_AGENT`, for agents that set none of the variables above. -4. `AI_AGENT` or `AGENT` set to `1`, `true`, `yes`, or `on`, with no name found - in the steps above. The CLI reports the agent as `unknown`. -5. A weak signal: a variable that shows the terminal or workspace the command - ran in, `CURSOR_TRACE_ID` (Cursor) or `REPL_ID` (Replit), or a GitHub Copilot - CLI setting people can export in their own shell profile, `COPILOT_MODEL` or - `COPILOT_ALLOW_ALL` (GitHub Copilot). A person typing in that terminal, or - with those settings, matches too. - -If nothing matches, the CLI reports nothing. - -## Set VOLCANO_AGENT - -The Volcano skills tell agents to set `VOLCANO_AGENT` on each command. You can -also set it yourself, for example in a custom agent or script: - -```sh -VOLCANO_AGENT=my-agent volcano functions deploy --all -``` - -`VOLCANO_AGENT` is ignored when step 1 or step 2 finds the agent. - -## What is sent - -Each API request carries these headers when an agent is detected: - -| Header | Example | Meaning | -|---|---|---| -| `X-Volcano-Agent` | `claude-code` | The agent name | -| `X-Volcano-Agent-Source` | `ai_agent` | Which step found it: `ai_agent` or `agent` (steps 1 and 4), `marker` (step 2), `volcano_agent` (step 3), or `host` (step 5) | -| `X-Volcano-Agent-Raw` | `claude-code_2-1-299_agent` | The original value of `AI_AGENT`, `AGENT`, or `VOLCANO_AGENT`, when it differs from the name | -| `X-Volcano-Agent-Markers` | `claude-code,cursor` | Every agent whose step 2 or step 5 variables are set. More than one means one agent ran inside another, for example Claude Code run from a Cursor terminal | - -The name and raw values are limited to letters, digits, and `._-/@+:`, and to -64 characters. The markers header is a comma-separated list of names from the -table above, so it is not free text. - -To see the headers the CLI sends, run any command with `--debug`. diff --git a/docs/authentication.md b/docs/authentication.md deleted file mode 100644 index 52586a42..00000000 --- a/docs/authentication.md +++ /dev/null @@ -1,115 +0,0 @@ ---- -title: "Authentication" -description: "Sign up, log in, and manage your Volcano credentials from the CLI." ---- - -To sign in, create a project, and set up a directory for it in one step, use -`volcano connect`. See [connect.md](connect.md). - -Local development needs no account: `volcano init`, `volcano start`, and the -local deploy commands work without signing in. A command that needs an -account, such as a `volcano cloud` command, fails with exit code `2` until you -run `volcano login`, or `volcano signup` for a new account. See -[scripting.md](scripting.md). - -New to Volcano? Create an account from the CLI: - -```bash -volcano signup -``` - -`volcano signup` prefills your email from `git config --global user.email` -when it is a usable address (press Enter to accept, or type a different -address). Private relay addresses, such as GitHub or GitLab `noreply` -addresses, and local or test addresses are not prefilled. The command then -opens Volcano's web signup flow in your browser. Once you finish in the -browser, the CLI completes the device-authorization handshake and saves your -credentials to `~/.volcano/config.json`, so a single command signs you up -and logs you in. - -The CLI ends up signed in as the account the browser uses. If you were already -signed in to Volcano in that browser, signup does not create an account: it -signs the CLI in to that account. When the login finishes, the CLI prints -`Logged in as ` with the account it signed in, which can differ from -the email you gave signup. If the CLI cannot read the account, it prints -`Logged in successfully` instead. - -Already have an account? Authenticate with `volcano login`: - -```bash -# Browser-based login (default); prints "Logged in as " -volcano login - -# Token-based login (for CI/CD) -volcano login --token pk-xxxxxxxxxx - -# With the code in the dashboard's prompt -volcano login --device-code - -# Or skip login entirely with an environment variable -export VOLCANO_TOKEN=pk-xxxxxxxxxx -``` - -## Account tokens and project access tokens - -The CLI accepts two kinds of credential: - -| Credential | Reaches | Get one with | -|---|---|---| -| Account token (`pk-`) | Every project you own | `volcano login` | -| Project access token (`pt-`) | One project | `volcano cloud access-tokens create` | - -Both work with `volcano login --token` and with `VOLCANO_TOKEN`. - -The prompt on the dashboard's Projects page holds a device code instead of a -token. It works with `--device-code` on `volcano login` or `volcano connect`: -it can be used once, within 10 minutes, and the CLI saves the account token it -signs in with. It saves that token before any other check, so a failure after -sign-in, such as a wrong `--project`, leaves you signed in. See -[Device codes from the dashboard](connect.md#device-codes-from-the-dashboard). - -A project access token is the one to give CI: it is scoped to a single project, carries -`full` or `read_only` access, and can be revoked on its own. Because it cannot -list projects, tell the CLI which project it belongs to, by ID: - -```bash -volcano login --token pt-xxxxxxxxxx --project - -# Or keep the token in VOLCANO_TOKEN and save only the project -export VOLCANO_TOKEN=pt-xxxxxxxxxx -volcano use -``` - -`VOLCANO_PROJECT_ID` still selects the project, but it is deprecated and will -be removed in a future release. A command that uses it prints a warning on -stderr. - -`--project` also selects the project for an account token, and there it takes a -name as well as an ID, the same as `volcano use`: - -```bash -volcano login --token pk-xxxxxxxxxx --project my-app -``` - -Inside a [linked directory](connect.md#linked-directories), `--project` updates -the link, the same as `volcano use`. For a project access token, login also -saves the project to `~/.volcano/config.json`. If the link named another project, login -warns and prints the command that links it back. If the deprecated -`VOLCANO_PROJECT_ID` names a different project there, login fails and leaves -the link as it was. - -Commands that reach past one project — `volcano projects list`, `volcano -projects create`, `volcano projects rename`, `volcano projects delete`, -selecting a project by name — need an account token, and say so when run with a -project access token. See -[access-tokens.md](access-tokens.md). - -Log out at any time: - -```bash -volcano logout -``` - -This removes local credentials, the selected project, and function aliases, -but does not revoke the token. Revoke it in the Volcano dashboard to fully cut -off access. diff --git a/docs/connect.md b/docs/connect.md deleted file mode 100644 index 8dd7d125..00000000 --- a/docs/connect.md +++ /dev/null @@ -1,245 +0,0 @@ ---- -title: "Connect a directory" -description: "Sign in, create a cloud project, and set up a directory for it with one command, ready for a coding agent to build on." ---- - -## What it does - -`volcano connect` goes from no login to a new cloud project and a directory -linked to it, in one command. Install the CLI first, because you keep using it -to build and deploy after `connect`. See [installation.md](installation.md) -for other ways to install. - -```bash -npm install -g @volcano.dev/cli -volcano connect -``` - -Run it yourself, or paste both lines into a coding agent. - -It runs these steps. A rerun inside the linked directory, or with the same -directory argument, keeps the project and updates the files in place. A rerun -with no directory argument outside a linked directory creates another project. -If `connect` stops after it creates a project but before it links the -directory, the error names the project and the -`volcano connect --project ` command that sets it up. -Commands `connect` prints put a directory with spaces or other shell -characters in single quotes, so you can paste them as they are. - -1. **Signs in.** It signs in with `--device-code` when given. - Otherwise it reuses a login that still works, or runs browser login. - Browser login prints a code and a link. Open the link and approve, and the - command continues. See - [Device codes from the dashboard](#device-codes-from-the-dashboard). -2. **Creates a project and its directory.** Unless `--project` names one, or - the directory is already linked, it creates a new project. - With no directory argument, it uses `--name` or a generated name such as - `fuji-amber-42`, and creates a directory with the same name in the current - directory. With a directory argument, the project is named after that - directory. If the name is taken by one of your projects or an existing - directory, it adds `-2`, `-3`, and so on. With `--project ` it - uses that project instead, in a directory named after it. If that - directory already exists with files in it and isn't linked to the - project, connect stops and prints the command to use it on purpose. - Without `--project`, run inside a directory that is already linked, it - keeps the linked project. - It doesn't link your home directory, whose `.volcano` directory holds the - CLI's own config. -3. **Links the directory.** It writes `.volcano/project.json`. CLI commands - run inside the directory use this project. Right after the link, it - gitignores `volcano/*.env` and, for a new link, `.volcano/project.json`, - unless `.gitignore` already has the entry or its negation. See - [Linked directories](#linked-directories). -4. **Creates the scaffold.** If `volcano/` is missing, it creates the same - scaffold as `volcano init`. With `--template` it adds that starter, also - to a directory set up before. It keeps the scaffold files already there - and adds the starter's missing lines to an existing `.gitignore`. When - every starter file is already there, as on a rerun, it keeps the ones you - changed and names them. Otherwise, if a starter file is already there with - different content, `connect` fails before it creates a project or changes - a file, and names the file. -5. **Writes the env file.** It writes the project's API URL and anon key to - `volcano/cloud.env`, as `VOLCANO_API_URL`, `VOLCANO_ANON_KEY`, and the - `NEXT_PUBLIC_` copies a Next.js frontend reads. The API URL is written - without a user name, password, query, or fragment, because a frontend build - makes it public. Other lines in the file are kept. -6. **Updates `AGENTS.md`.** It adds a Volcano section to `AGENTS.md` that - tells the agent where the project link is, which skills to - use, and how to deploy. The section names no project, so teammates can - share it. A rerun replaces the section instead of adding another. The - section sits between `` and - `` lines. If the start line is there without an - end line after it, `connect` fails and names `AGENTS.md` instead of - guessing where the section ends. The section's dashboard link, like the one - `connect` prints, drops any user name, password, query, or fragment from - the dashboard's base address. -7. **Installs skills.** It installs the Volcano skills for every coding agent - it finds on the machine, as `volcano setup --yes` does. See - [setup.md](setup.md). - -It ends with the project's name, its directory, and its dashboard link: - -```text -Project: fuji-amber-42 -Directory: ./fuji-amber-42 -Dashboard: https://volcano.dev/dashboard/overview?project= - -Next: cd ./fuji-amber-42, read AGENTS.md there, and use the Volcano skills to build. -``` - -## Usage - -```bash -volcano connect # new project in a new directory -volcano connect --name shop # new project and directory named shop -volcano connect . # link this directory to a new project -volcano connect my-app # create ./my-app and link it -volcano connect --project # set up an existing project -volcano connect --template nextjs # also add the Next.js starter -volcano connect --signup # new to Volcano: create an account first -volcano connect --device-code # sign in with the code in the dashboard's prompt -volcano connect --json # print the result as JSON -``` - -| Flag | Meaning | -|---|---| -| `--project` | Use the existing project with this ID instead of creating one | -| `--name` | Name for the new project. Defaults to the directory argument's name, else a generated name. Fails in a linked directory, which keeps its project | -| `--template` | Starter to add: `nextjs`, `javascript`, `python`, `ruby` | -| `--signup` | Create an account in the browser first. Uses `--email`, else `git config --global user.email` when it is a usable address. Private relay addresses (such as `noreply.github.com`) and local or test addresses are skipped. Without a usable address, connect stops and asks you to run it again with `--email`. Fails when `VOLCANO_TOKEN` is set | -| `--device-code` | Sign in with the code in the dashboard's prompt instead of the browser. Fails when `VOLCANO_TOKEN` is set | -| `--skip-skills` | Don't install skills | -| `--json` | Print the result as JSON on stdout. Progress goes to stderr | - -## Device codes from the dashboard - -When you have no projects, the dashboard's Projects page shows a prompt to -paste into your coding agent. Each time you copy it, the dashboard starts a -new CLI login, approves it for the account you are signed in with, and puts -its device code in the prompt: - -```bash -volcano connect --device-code -``` - -`connect` signs in with the code without opening the browser, and saves the -login, so later commands stay signed in. The code works once and expires 10 -minutes after you copy the prompt. Until then it signs in as you, so don't -share the prompt. If the code has expired, was already used, or is refused, -`connect` warns and runs browser login instead. Copy the prompt again for a -new code. - -The login is saved as soon as the code is used. If a later step fails, the -CLI is still signed in: run the command again without `--device-code`. - -`volcano login --device-code ` signs in the same way. When the code is -refused it fails with exit code `2` instead of running browser login. - -## New accounts and the project limit - -Run `volcano connect --signup` if you don't have an account yet. It opens -the signup page, and the CLI is signed in when you finish. `connect` prints -`Logged in as ` with the account it signed in, or `Logged in successfully` -when it cannot read the account. If you were already signed in to Volcano in the -browser, signup does not create an account: the CLI signs in to that account, -which can differ from the `--email` you gave. - -`--signup` needs an email address. It uses `--email`, else your global git -email when that is a usable address. When neither is available, `connect` -stops before it signs in and changes nothing. Run the same command again with -the address you want to sign up with: - -```bash -volcano connect --signup --email you@company.com -``` - -An AI agent running `connect` should ask the user for the address, using its -native input tool (such as `AskUserQuestion`) when it has one, and then -finish `connect` with `--email`. - -When your plan's project limit is reached, `connect` fails and lists your -projects with the command to set up each one: - -```bash -volcano connect --project -``` - -## Linked directories - -`.volcano/project.json` links a directory to a project. CLI commands run in -that directory or below it use the linked project. The CLI looks for the file -in the current directory and its parents. It stops at the repository root, or -before your home directory, whichever comes first. Outside both, it looks up -to `/`. - -The project a command uses comes from, in order: - -1. `--project `, on `volcano cloud` commands. It applies to that - one command and changes neither the link nor the saved project. -2. `VOLCANO_PROJECT_ID`, which is deprecated and will be removed in a future - release. A command that uses it prints a warning on stderr. -3. The directory's link -4. The project `volcano use` saved - -`volcano use` run inside a linked directory updates the link. Elsewhere it -saves the project for every directory without a link. Inside a linked -directory, if `VOLCANO_PROJECT_ID` names a different project, `volcano use` -fails and changes nothing, because commands would keep using the project the -variable names. Unset it and run `volcano use` again. - -`volcano login --token --project ` run inside a linked -directory updates the link the same way, with the same `VOLCANO_PROJECT_ID` -check. If the link named another project, it warns and prints the command that -links it back. `volcano connect --project ` does the -same when it relinks a directory linked to another project. - -`volcano connect` fails when `VOLCANO_PROJECT_ID` is set, whatever project it -names, before it signs in or changes anything, and exits `1`. Unset it, and -pass `--project ` to set up an existing project. - -If the linked directory already has a `volcano/cloud.env` with an anon key, -`volcano use` and `volcano login --project` also rewrite the values `connect` -wrote there for the new project. They never create an anon key: if the new -project has none, or the update fails, they warn, and `volcano connect .` -refreshes the file. - -If the link can't be read, or its `project_id` isn't a project ID, `volcano login` and `volcano signup` warn and -ignore it. `volcano docs` and local commands, such as -`volcano functions deploy`, ignore it because they never use a project. Other commands fail and name the file. `volcano connect` ignores -one in a parent of the directory it sets up. For one in that directory, it -stops unless `--project ` or `--name ` (for a new project) -says what replaces it. - -The CLI doesn't write through a symlink, which could change a file outside -the directory, such as your CLI login. If `.volcano/project.json`, -`volcano/cloud.env`, `.gitignore`, or `AGENTS.md`, or the `.volcano` or -`volcano` directory, is a symlink, `connect` fails and names it. For -`.volcano/project.json`, `volcano use` fails too, and `volcano login` warns, -ignores the link, and saves the project to `~/.volcano/config.json`. For a `volcano/cloud.env` with an anon key, they switch the project and -warn that the file was not refreshed. Replace the symlink with a regular file or directory and -run the command again. - -With no directory argument, `connect` doesn't follow a symlink to the -directory it names after the project. With `--project`, it fails if that -directory is a symlink. A generated name skips one, as it skips an existing -directory. A directory you pass as an argument may be a symlink. - -The link is gitignored because each developer usually has their own project. -Remove the `.gitignore` entry to share it with your team. `volcano connect` -adds the entry only when it creates a new link, so a rerun in a directory -that already has one doesn't add it back. - -## Running from an agent - -`connect` never waits on a prompt when stdin is not a terminal, or when `CI`, -`VOLCANO_NONINTERACTIVE`, or `TERM=dumb` is set. When it would ask for a -project name, it uses the default name. - -Without a directory argument, `connect` sets up a new directory below the -current one. The agent should `cd` into the `Directory:` it prints (`directory` -in `--json`) before running other `volcano` commands, and read the -`AGENTS.md` there. - -Browser login waits until you approve in the browser. An agent should show you -the code and link it prints, then wait for the command to finish. See -[scripting.md](scripting.md) for exit codes. diff --git a/docs/databases.md b/docs/databases.md deleted file mode 100644 index 099f48e5..00000000 --- a/docs/databases.md +++ /dev/null @@ -1,329 +0,0 @@ ---- -title: "Databases" -description: "A managed PostgreSQL database provisioned for your project. Functions connect to it using its connection string." ---- - -## What it is - -A managed PostgreSQL database provisioned for your project. Functions connect to -it using its connection string. - -## How it relates - -- Belongs to a **project**. -- **Functions** read and write it via its connection string. -- Its schema is evolved by **migrations** — SQL files in `volcano/migrations` - applied to a named database. -- Database *requirements* can also be declared in the - [declarative config](project-configuration.md) (the manifest updates - settings but never creates or deletes databases). - -## CLI operations - -| Operation | Command | -|---|---| -| Create | `volcano databases create [--type …] [--region ] [--pg-version …]` | -| List | `volcano databases list` | -| Get | `volcano databases get [--show-connection-string]` | -| Delete | `volcano databases delete ` | -| List regions and PostgreSQL versions | `volcano cloud databases regions`, `volcano databases versions` | -| Change size (cloud) | `volcano cloud databases resize --type ` | -| Compare migration files with the history | `volcano databases migration status -d ` | -| Apply pending migrations | `volcano databases migration apply -d ` | -| Record files that already ran | `volcano databases migration baseline -d --all` | -| List or show migration runs | `volcano databases migration runs list -d ` | -| Run migration files without tracking | `volcano databases migration up --all -d ` | - -Every migration command works in both trees: prefix it with `cloud` for a cloud -project. Local development also keeps `volcano migrations deploy --all -d `, -the untracked `up`. - -## Migrations - -Migrations are SQL files in `volcano/migrations`. With one database, put them in -`volcano/migrations` itself. With several, put each database's files in -`volcano/migrations//`, and put nothing at the top level. Names that -start with `_` or `.` are skipped, and files run in byte order of their names. -Tracked runs take only names that end in lowercase `.sql`. -Git deploy reads the directory the same way, so a layout the CLI refuses is one -a push would refuse too. - -### Tracked runs - -`migration apply` sends a database's files to a tracked migration run. Volcano -compares them with the database's migration history and applies only the files -the history does not record, then records them. A file runs once, however many -times you apply. - -```bash -volcano cloud databases migration apply -d app -``` - -```text -Starting a migration run of 3 file(s) from volcano/migrations on database 'app' -Run 7f3a1c2e-5d4b-4a91-8c6f-2b1e9d0a4c73 queued - running: rehearse - running: apply -✓ Migration run 7f3a1c2e-5d4b-4a91-8c6f-2b1e9d0a4c73 succeeded: 1 applied, 2 already applied -``` - -Before it changes the database, a cloud run rehearses the pending files on a -short-lived branch, and takes a backup where the plan includes backups. A file -that fails in the rehearsal fails the run without touching the database. Local -development has no branches or backups, so a local run applies directly and -reports `rehearsal_skipped` and `backup_skipped` warnings. - -A file may hold several statements and runs in one transaction. It cannot -`COMMIT`, `ROLLBACK`, or use savepoints. A statement that cannot run in a -transaction, such as `CREATE INDEX CONCURRENTLY`, goes alone in a file whose -first line is `-- volcano:no-transaction`. That file runs outside a -transaction, so nothing rolls it back, and a retried run runs it again from its -start: write it to be safe to repeat, such as with `IF NOT EXISTS`. A run refuses a file whose content changed after -it was applied (`checksum_mismatch`): put the recorded content back and make the -change in a new file. One database runs one migration run at a time; a second -`apply` while one is queued or running names the run to wait for. - -`migration apply --no-wait` returns once the run is queued. `migration runs list` -shows a database's 50 most recent runs, including the ones Git deploys start, -and `migration runs get ` shows one run's files and why it failed. - -### Adopt a database migrated without tracking - -A database migrated with `migration up`, `migrations deploy`, or a -`--with-migrations` deploy from a CLI before tracked runs already reflects its -files, but its history records none of them. Record them first, or the first -run applies them again: - -```bash -volcano cloud databases migration status -d app # every file is pending -volcano cloud databases migration baseline -d app --all -volcano cloud databases migration apply -d app # applies only new files -``` - -`baseline` records files as applied without running them. Use `-f `, -repeatable, to record only some of them. It asks for confirmation; pass `--yes` -to skip it. - -### Availability - -Tracked runs need the `databases.migrations` capability, which the CLI reads -from the API's `GET /capabilities` before it starts one. Where the API does not -offer it, -`migration apply`, `migration baseline`, and `deploy --with-migrations` refuse -before sending anything and name the untracked command instead. `migration -status` and `migration runs` keep working, so you can still read what earlier -runs did. Local development always offers tracked runs. - -### Run files without tracking - -`migration up` connects through the managed database proxy and runs each file -as a single query, whether or not it ran before. The proxy refuses a query with -more than one statement, so put one SQL statement in each file. - -## Regions and versions - -`databases create` in the cloud requires `--region` and `--pg-version`. List the -values they accept: - -```bash -volcano cloud databases regions -volcano cloud databases versions -``` - -```text -Version Name Notes --------------------------------------------- -18 PostgreSQL 18 default, recommended -17 PostgreSQL 17 -``` - -Both lists are public, so they work before you sign in. Pass `--json` to read -them from a script. In local development a database runs on your machine: -`databases create` needs no `--region`, `databases regions` is refused, and -`databases versions` lists only the version the local server runs. - -## Change a database's size - -```bash -volcano cloud databases resize app --type volcano-db-m -``` - -Sizes, smallest first: `volcano-db-xs`, `volcano-db-s`, `volcano-db-m`, -`volcano-db-l`, `volcano-db-xl`, `volcano-db-2xl`. The database must be active, -and active connections may drop briefly while it changes. The command asks for -confirmation; pass `--yes` to skip it and `--json` to print the updated -database, without its connection string. A plan can limit the sizes it allows. In local development a database -runs on your machine and has no size to change. - -The manifest's `database_type` asserts a database's size but does not change -it; resize it with this command. - -## Branches - -A branch is a short-lived copy-on-write fork of a database you can develop and -test against. It starts as a copy of the parent and diverges from there: writes -to a branch never reach the parent. - -Every branch expires — the default lifetime is 7 days, and `--ttl` accepts -anything between `1h` and `720h`. Only the data a branch has diverged by counts -against the parent database's storage allowance, so a fresh branch is free. - -Every plan includes branching: a database may hold 10 branches on `HOBBY` and -25 on `SUPERAGENT`, counting branches in every state. Local development projects -have no branching backend, so unlike the commands above these live under the `cloud` -group and the prefix is required rather than optional. - -| Operation | Command | -|---|---| -| Create | `volcano cloud databases branches create [--ttl 24h]` | -| List | `volcano cloud databases branches list ` | -| Get | `volcano cloud databases branches get [--show-connection-string]` | -| Extend | `volcano cloud databases branches extend --ttl ` | -| Reset | `volcano cloud databases branches reset ` | -| Rotate password | `volcano cloud databases branches rotate-password ` | -| Delete | `volcano cloud databases branches delete ` | - -Branch names are lowercase letters, numbers, and underscores, up to 64 -characters, and unique within their parent database. - -A branch has its own connection string with its own credentials, separate from -the parent's. It is returned before it is ready, so fetch the branch until it -reports `active`: - -```bash -# Fork "app" into a branch that lives for a day -volcano cloud databases branches create app feature_x --ttl 24h - -# Poll until it is connectable, then read its connection string -volcano cloud databases branches get app feature_x --show-connection-string -``` - -`reset` discards everything the branch has diverged by and re-forks it from the -parent's current state, keeping the branch's name and credentials. It rewinds in -the background, so the branch goes back to `provisioning` and stops serving -connections until it reports `active` again — poll it with `get` the same way you -would after a `create`. `extend` replaces a branch's lifetime rather than adding -to it, counting from now. - -## Backups and restore - -A backup is a point-in-time copy of a database, kept by the platform and -restorable in place. Backups cover the database itself, not its branches. - -Backups require `SUPERAGENT`. On `HOBBY`, every command below fails with `403`, -reads included: - -```console -$ volcano cloud databases backups list app -Error: backups are not available on this plan -``` - -Like branching, backups have no local backend, so these commands live under the -`cloud` group and the prefix is required. Dropping it points you back at the -cloud path rather than running anything: - -```console -$ volcano databases backups list app -Error: "backups" is a cloud command: local development has no storage provider -behind it, so run 'volcano cloud databases backups' against a cloud project -``` - -| Operation | Command | -|---|---| -| Create | `volcano cloud databases backups create ` | -| List | `volcano cloud databases backups list ` | -| Get | `volcano cloud databases backups get ` | -| Delete | `volcano cloud databases backups delete [--yes]` | -| Restore | `volcano cloud databases restore --backup [--yes]` | -| Restore to a point in time | `volcano cloud databases restore --to [--yes]` | -| List restores | `volcano cloud databases restores list ` | -| Show one restore | `volcano cloud databases restores get ` | -| Show the schedule | `volcano cloud databases backup-schedule get ` | -| Set the schedule | `volcano cloud databases backup-schedule set --frequency [--hour 3] [--day 1] [--retention 168h]` | -| Stop scheduled backups | `volcano cloud databases backup-schedule set --clear` | - -`backups` is also spelled `backup`. `delete` and `restore` ask for confirmation -first; pass `--yes` (`-y`) to skip the prompt in a script. `--day` is the day of -the week for a weekly schedule (`1`-`7`, Monday to Sunday) and the day of the -month for a monthly one (`1`-`28`); it is required for both and ignored by a -daily schedule. - -Whether a database may be backed up at all, how many backups it may keep, how -long they are kept, and how far back a point-in-time restore reaches all come -from the project's plan. `backups list` reports the window a point-in-time -restore may target. - -What the backups hold counts against the parent database's storage allowance, -and a backup you take is charged as a full copy of the database as it was then. -A schedule's first backup is charged the same way and each one after it only for -the storage it adds, so the `Size` column — how much data a backup holds — runs -ahead of what the backup costs to keep. Deleting a backup releases its storage -straight away. A plan without backups is charged nothing for the ones it still -holds after a downgrade. - -```bash -# Back up before a risky migration -volcano cloud databases backups create app before_migration - -# See what there is to restore, and how far back a point-in-time restore reaches -volcano cloud databases backups list app - -# Put the database back the way that backup found it -volcano cloud databases restore app --backup before_migration - -# Or rewind to an arbitrary moment inside the window, without the prompt -volcano cloud databases restore app --to 2026-01-15T09:30:00Z --yes - -# Watch it, using the id the restore printed -volcano cloud databases restores get app 6f1c… -``` - -Restoring is destructive and in place: everything written after the point being -restored is discarded, and there is no way to restore into a second database. -The restore runs in the background, so the command returns while the database is -still `restoring` and serving no connections. Its connection string never -changes, so nothing holding it needs updating. - -Watch it with `restores get`, which the restore command prints the id for. A -`pending` or `running` restore is still going, and an attempt that fails with -tries left goes back to `pending`; `failed` and `exhausted` both mean the platform -gave up. Either leaves the database `failed` if an attempt had already begun -replacing its data, and `active` if none had — a backup that no longer exists at -the provider ends the restore without touching the database. Only the restore -carries the reason — -the database itself reports the status and nothing more. `restores list` shows -the 50 most recent restores of a database, newest first. - -While a restore runs, the commands that would race it are refused: another -`restore`, `backups create`, `backups delete`, `backup-schedule set`, `databases -delete`, and `branches create` or `branches reset`. Wait for the database to -report `active` and retry. - -Branches are not restored. They keep serving their own data, but resetting a -branch from a database that was just restored is refused for up to 24 hours -afterwards. - -`backup-schedule set` replaces the schedule rather than adding to it, and -scheduled backups do not count against the plan's backup allowance. Their -retention is clamped to the plan's, so the schedule printed back can keep -backups for less time than asked for. Scheduled backups are listed alongside the -ones you took, with a source of `scheduled`, and are restored and deleted the -same way. - -## Examples - -```bash -# Create a database (defaults to type volcano-db-xs) -volcano databases create app -volcano databases create app --type volcano-db-s --region us-east-1 - -# Show the connection string -volcano databases get app --show-connection-string - -# Apply pending migration files from volcano/migrations to the local "app" database -volcano databases migration apply -d app - -# Apply them to the cloud database named "app", and see what is recorded -volcano cloud databases migration apply -d app -volcano cloud databases migration status -d app -``` diff --git a/docs/deploy.md b/docs/deploy.md deleted file mode 100644 index 62c07010..00000000 --- a/docs/deploy.md +++ /dev/null @@ -1,376 +0,0 @@ ---- -title: "Deploy a project" -description: "Deploy variables, migrations, functions, durable functions, frontends, and configuration with one command, in the order Volcano needs." ---- - -`volcano deploy` deploys everything the project directory describes to the -local development server. `volcano cloud deploy` does the same for the selected -cloud project. - -```bash -volcano start -volcano deploy --with-migrations -``` - -```text -Deploying to local project "my-app" - 1. variables volcano/volcano.env - 2. migrations volcano/migrations -> database app - 3. functions volcano/functions - 4. durable skipped: volcano/volcano-config.yaml declares no durable functions - 5. frontends web (.volcano/source-layout.json) - 6. config volcano/volcano-config.yaml - -[1/6] variables -... -Waiting for 2 deployment(s)... - ✓ notes-summary active - ✓ web active - -Frontends: - web http://3f9c1d2e-....frontends.localhost:8080 - -✓ Deployed in 1m42s -``` - -## What it deploys - -The steps run in this order. A step with nothing to deploy is skipped. - -| Step | Reads | Same as | -|---|---|---| -| variables | the env file, or the variable sections of the manifests | `variables deploy` | -| migrations | `volcano/migrations`, only with `--with-migrations` | `databases migration apply -d ` | -| functions | the standard functions in `volcano/functions` | `functions deploy --all` | -| durable | the functions the first manifest declares `kind: durable` | `durable deploy --all` | -| frontends | the frontends listed in `.volcano/source-layout.json` | `frontends deploy` | -| config | each manifest, in the order given | `config deploy` | - -Then the command waits until every deployment it started has finished, prints -each result, and prints the frontend URLs. It exits non-zero when a deployment -fails, and prints the command that shows that deployment's build log. Pass -`--no-wait` to return as soon as the config step is done. - -Before anything changes, the command reads and checks the env file, the -manifests, and `.volcano/source-layout.json`. A missing file named by a flag, a -broken manifest, or one of the refusals below stops the run with the project -untouched. Function sources and frontend directories are packaged later, in -their own steps. The run stops at the first step that fails, names the steps -that already ran, and lists the commands that finish the rest by hand. When -the first manifest isn't the default one, it only says to run it again: -`functions deploy` and `durable deploy` read the default manifest, so run by -hand they could deploy a durable function as a standard one. - -New functions start `private`, and the config step then applies the -`visibility` the first manifest declares for them. The functions and durable -steps say so instead of telling you to run `config deploy`. A new function the -manifest gives no visibility stays `private`, and the run prints the commands -that open it. - -The server only adds or changes a scheduler on an active function, and a -function the run just deployed is usually still building when the config step -runs. When a manifest adds or changes a scheduler on such a function, the config -step leaves out that function's schedulers and applies the rest of the manifest. -After the wait, the command applies just those schedulers, so values a later -manifest set stay in place. Schedulers that don't change apply in the config -step as usual. With `--no-wait`, or when the wait fails because any deployment -fails or times out, it prints the `config deploy` commands that apply the -schedulers later. - -A deployment can be redeployed while the run waits, for example when the config -step changes a function's regions. The run then waits for the newer deployment, -since that is the one that serves. A durable function also has to accept -executions before the run counts it as deployed, so the run also waits while -its status is `provisioning`. - -## Flags - -| Flag | Description | -|---|---| -| `--with-migrations` | Apply `volcano/migrations` in tracked migration runs. | -| `-d, --database` | Database to migrate. With a directory per database in `volcano/migrations`, the default is every database that has one. Otherwise local mode defaults to `app`, and the cloud defaults to the database the manifests' `databases:` sections declare, if they declare exactly one. | -| `--env-file` | Env file to deploy. Default: `volcano/volcano.env` or `./volcano.env`. | -| `--no-env-file` | Deploy no env file, even when `volcano/volcano.env` exists. Use it when a manifest's `variables` section holds the project's variables. | -| `-c, --config` | Manifest to apply. Repeat it to apply several, in order. Passing any `-c` replaces default lookup: `./volcano-config.yaml` first, then `volcano/volcano-config.yaml` only when the root file is absent. | -| `--no-frontends` | Skip frontends. Useful while `npm run dev` is your edit loop, or when only function code changed. | -| `--no-wait` | Return without waiting for deployments to finish. | - -`-d` without `--with-migrations` is refused, since it would do nothing. - -The first manifest is the primary one. Function kinds, variable scopes, and -each frontend's variable selection come from it. A later manifest that declares -`kind: durable` or a frontend's `variable_scope` or `variables` is refused: -deployed from the wrong manifest, a durable function would be created as a -standard one, and a function's kind can't change. For the same reason, when -the project has a `volcano/functions` directory and `-c` leaves out the -default manifest while it declares durable functions the first manifest -doesn't, the run is refused. - -```bash -volcano deploy --with-migrations --env-file volcano/volcano.local.env \ - -c volcano/volcano-config.yaml -c volcano/auth.local.yaml -``` - -## Variables - -`volcano/volcano.env` holds the values for the local development server. Keep -the cloud project's values in another file and name it on every cloud deploy: - -```bash -volcano cloud deploy --env-file volcano/cloud.env -``` - -Projects that `volcano init` creates use the same names in both files. A -Next.js frontend reads its public copies, such as `NEXT_PUBLIC_VOLCANO_API_URL` -and `NEXT_PUBLIC_VOLCANO_ANON_KEY`, because builds never see `VOLCANO_*` names. -`volcano cloud deploy` refuses an env file that holds the local server's keys -or a `VOLCANO_API_URL` on `localhost`, which a cloud frontend would compile in. - -Variables come from the env file or from a manifest's `variables` section, -never both. Applying a `variables` section deletes every variable it does not -list, so it would delete the ones only the env file sets. When an env file is -found and a manifest declares `variables`, the command refuses and names both -files. Pass `--no-env-file` to deploy only the manifest's variables, for -example in a project whose `volcano/volcano.env` serves local runs. - -For the same reason, only one manifest may declare each of `variables`, -`shared_variables`, and `frontend_shared_variables`. Two `-c` manifests that -declare the same section are refused. - -Variables are deployed first, before any function or frontend that selects -them. The variables step deploys the env file, then applies just the -`variables`, `shared_variables`, and `frontend_shared_variables` sections of -each manifest that has them. The config step applies the full manifests later. - -## Migrations - -Migrations run only with `--with-migrations`. The step starts a tracked -migration run for each database, the same run -[`databases migration apply`](databases.md#tracked-runs) starts, and waits for -it to end, even with `--no-wait`. The database's migration history records each -file it applies, so a file runs once: running the deploy again after a later -step failed applies nothing new. - -```text -Starting a migration run of 3 file(s) from volcano/migrations on database 'app' -Run 7f3a1c2e-5d4b-4a91-8c6f-2b1e9d0a4c73 queued - running: apply -✓ Migration run 7f3a1c2e-5d4b-4a91-8c6f-2b1e9d0a4c73 succeeded: 1 applied, 2 already applied -``` - -A run that fails stops the deploy before the functions step. With one database, -put its files in `volcano/migrations`; with several, put each database's files -in `volcano/migrations//`, and the step migrates each of them. - -A database that an earlier CLI migrated with `--with-migrations` already -reflects its files, but its history records none of them. Record them once -before the next deploy, or the run applies them again: - -```bash -volcano cloud databases migration baseline -d app --all -``` - -Tracked runs need the `databases.migrations` capability. Where the API does not -offer it, `--with-migrations` refuses before anything changes and names -`databases migration up --all`, which runs every file again without tracking. - -## Frontends - -Frontends are listed in `.volcano/source-layout.json` at the project root. A -connected Git repository reads the same file, so the CLI and Git deploy the -same frontends. - -```json -{ - "version": 1, - "frontends": [ - { "name": "web", "workspace": "", "app_root": "web" } - ] -} -``` - -| Field | Description | -|---|---| -| `name` | Frontend name: lowercase letters, digits, and inner hyphens. | -| `workspace` | Directory to upload, relative to the project root. `""` is the root. Omitted means `frontends/`. | -| `app_root` | The Next.js app inside `workspace`. `""` is the workspace itself. | - -`app_root` must contain the app's `package.json`, or be the directory that a -parent `package.json` builds with `next build `, as in projects that -`volcano init nextjs` creates. The upload skips what the workspace's root -`.gitignore` lists, `node_modules`, `.next`, `.env*.local` files, the Volcano -env files (`volcano/*.env` and `volcano.env`), and the env file the run -deployed, wherever it is. - -Each frontend is built with the variable selection its entry under -`frontends:` in the primary manifest declares: - -```yaml -frontends: - - name: web - variable_scope: scoped - variables: [NEXT_PUBLIC_API_URL] -``` - -`NEXT_PUBLIC_*` values are compiled into the build, so the selection has to be -in place when the frontend builds, not only when config applies. A frontend -deploy can set `all` or `scoped` with its `variables`. A frontend with -`variable_scope: shared`, or an entry that leaves out either field, builds -with the selection it already has (none for a new frontend), and the config -step applies the entry afterwards. The run warns about each such frontend; run -the deploy again to rebuild it with the selection. - -In the cloud, a declared frontend entry without `custom_domain` or -`custom_domains` leaves the frontend's domains alone. `custom_domain: null` -removes its domain, and `custom_domains` replaces the whole set. A server that -predates these rules refuses `custom_domain: null` in the dry run, and removes -the domain of an entry without `custom_domain`. Deploying a manifest written by -`volcano config pull` keeps every domain on either server, and the dry run -lists any domain it would delete. - -## Source commit - -A cloud frontend, function, or durable function deploy reports the commit its -source came from, so Volcano can tie the deployment to your repository. The CLI sends the GitHub repository as -`owner/name`, the commit ID, and whether the uploaded files differ from that -commit. A frontend deploy also sends the uploaded directory's path in the -repository, which is empty when it's the repository's top level. The CLI never -sends the remote URL or any credentials in it, local paths, branch names, or -diffs. - -The CLI reads the commit checked out where the deploy reads its files, the -directory `--path` names for a frontend and the working directory for -functions: the `origin` remote and `HEAD`, the same in GitHub Actions as -anywhere else. It sends nothing, and the deploy goes ahead, when git isn't -available, the repository isn't on github.com or has no commit yet, the -uploaded files are outside the repository, or any part is missing. Local -deploys never send it. - -### Frontend uploads - -The upload matches the commit when each file in it is in the commit at the -same path with the same content and executable bit, and it holds every file -the commit has in the uploaded directory. Files every upload leaves out, such -as `node_modules`, `dist`, `build`, `.vscode`, `.gitignore`, and `*.log`, don't -count. Line endings count as the same where git converts them, as -`core.autocrlf` and the `text`, `eol`, and `crlf` attributes decide, and a file -whose `filter=lfs` attribute has Git LFS store it matches its pointer. The CLI -runs no other git filter, so a file another filter changes counts as changed. - -Anything else counts as changed: - -- An edited, moved, or deleted file. -- A file the commit doesn't have that the upload includes, such as an untracked - file. -- A committed file the upload lacks, such as one replaced by a symlink or a - directory, one in a directory a symlink replaced, one the root `.gitignore` - lists, or the env file that `volcano deploy` deploys as variables instead of - uploading. The upload never holds a symlink, so a committed symlink counts - too. - -The upload skips what the `.gitignore` at the root of the uploaded directory -lists, not what a `.gitignore` in a subdirectory or outside it lists, so a file -only those ignore is uploaded and counts as changed. Windows has no executable -bit, so a frontend deployed from Windows doesn't match a commit that holds an -executable file. - -### Function uploads - -Function and durable function deploys send the commit only for a clean -function, and nothing for one that has changed. A function is clean when -every committed file its upload is made from is in the upload as the commit -holds it, none of them is staged, and the upload holds no file the commit -doesn't have unless git ignores it. Those files are: - -- The function's file, or the files in its directory that the upload keeps. -- The dependency manifests the upload picks up, such as a `package.json` next - to the function or in a directory above it. -- Shared libraries: entries under `volcano/` whose names start with `_`. -- The `volcano-config.yaml` the deploy reads declarations from, and the root - `.gitignore`, which decides what the upload leaves out. - -A committed file the upload lacks counts as changed, such as one that was -deleted or replaced by a symlink or a directory, or one in a directory a -symlink replaced. So does a committed file that another file or a shared -library takes the place of, unless the commit or the upload holds that -replacement: an empty `volcano/functions/_shared/` left behind still replaces -a committed `volcano/_shared/`, and a checkout of the commit would upload the -committed one. - -In a directory function's directory and in each shared library, a file git -neither tracks nor ignores counts as changed even when the upload leaves it -out, such as a `*.log` file or a `node_modules` directory that no -`.gitignore` lists. Changes anywhere else don't count, such as to another -function or to a file beside a single-file function that its upload doesn't -read. `functions deploy --all` checks each function on its own, so a batch -can send the commit for some functions and not for others. - -A file git ignores is build output, such as a bundle your build writes to an -ignored `volcano/functions/`. The CLI can't tell which sources made it, so a -function whose upload holds one gets the commit only when the whole repository -matches `HEAD`: every tracked file has the content and, where git tracks it, -the executable bit that `HEAD` holds, nothing is staged, no file is untracked -unless git ignores it, and there's no submodule. Deploy from a clean checkout, -and commit any generated file the build changes. - -Line endings and Git LFS pointers count as they do for frontends, and the CLI -runs no other git filter. A function with a submodule among its files, or one -whose files or `volcano-config.yaml` are reached through a symlink or are -outside the working directory, gets no commit. - -### Verification - -Volcano checks the commit against the project's connected repository and -records what it confirmed as `verification`. LavaFlow reads source at a commit -with either level below, never the uploaded files, so commit your changes -before you deploy: - -- `files`, for frontend deploys: the commit is on the production branch, and - the upload [matches it](#frontend-uploads). LavaFlow reads the commit for - the deployment and for each redeploy of its build. -- `repository`, for function and durable function deploys: the commit is on - the production branch. Volcano doesn't compare a function upload's files - with the commit. LavaFlow reads the commit for that deployment only, not - for a redeploy, such as one a variable change starts, and only while the - project's repository link is unchanged since Volcano checked it. Relinking, - even to the same repository, reinstalling the GitHub App, renaming the - repository, or changing the production branch or root directory ends it. A - fix opens only while the production branch still holds the commit, and a - deployment at this level never counts as deploying a merged fix, so - LavaFlow doesn't resolve the issue from it. - -A reported commit Volcano can't confirm is recorded with `verification: none`, -and LavaFlow diagnoses that deployment from the logs alone. That includes a -frontend upload that doesn't match its commit, and a workflow run for a pull -request, which deploys GitHub's merge commit on no branch. At autonomy -`merge`, LavaFlow holds a fix built on a reported commit, at either level, for -a person to merge. A fix built on a commit that a -[push to the repository deployed](#cloud-projects-that-deploy-from-git) has no -such hold. `frontends deploy --from` keeps the commit of the build it -publishes. A frontend redeploy reports no commit of its own, and LavaFlow -reads it as the commit of the build that made its artifact. - -To send nothing, set: - -```bash -export VOLCANO_DEPLOY_COMMIT=off -``` - -## Cloud projects that deploy from Git - -When a cloud project's code deploys from its connected repository, functions -and frontends can't be deployed directly. `volcano cloud deploy` refuses before -it changes anything. Push to the repository to deploy code, and use -`volcano cloud variables deploy -f volcano/cloud.env` and -`volcano cloud config deploy -f `, once per manifest, for the rest. -The refusal prints those commands for the files the run read. Name the env -file: without `-f`, -`variables deploy` reads `volcano/volcano.env`, the local server's values. - -## Related - -- [Variables](variables.md) -- [Functions](functions.md) -- [Durable functions](durable-functions.md) -- [Frontends](frontends.md) -- [Declarative configuration](project-configuration.md) diff --git a/docs/deployments.md b/docs/deployments.md deleted file mode 100644 index af8e2447..00000000 --- a/docs/deployments.md +++ /dev/null @@ -1,119 +0,0 @@ ---- -title: "Deployments" -description: "List, inspect and summarize the deployments of a project's functions, durable functions and frontends from the CLI." ---- - -`volcano deployments` reads the project's deployment history: every deploy of -a function, durable function or frontend, whatever started it — the CLI, a Git -push, the dashboard or the API. - -```bash -volcano cloud deployments list --since 1d -volcano cloud deployments get 8f0c2a1e-5b7d-4c6e-9a3f-2d1b0e4c7a91 -volcano cloud deployments summary --type frontend --since 7d -``` - -Without `cloud`, the commands read the local environment's deployments. - -## List deployments - -`deployments list` prints the newest deployments first: - -```bash -volcano cloud deployments list -``` - -```text -Created Resource Op Status Source Duration ID -12m ago function checkout deploy active cli 1m32s 8f0c2a1e-5b7d-4c6e-9a3f-2d1b0e4c7a91 -31m ago durable function pipeline deploy failed git 48s 0b6d9e2f-7c1a-4f3b-8d5e-6a2c4b1f9e07 -16h ago frontend web deploy active api 2m5s c41e8a3b-2d6f-4e9c-a1b7-5f3d0c8e2a64 - -Total: 3 deployment(s) -``` - -| Flag | Effect | -|---|---| -| `--type function\|frontend` | Only one resource type. Both by default. | -| `--kind standard\|durable` | Only standard or durable functions. Implies `--type function`. | -| `--name ` | Only resources whose name contains the text. | -| `--since ` | Only deployments newer than this, such as `2h` or `7d`. | -| `--after