From 7f7d3316b2658542632de1760696ef1dc75db9b7 Mon Sep 17 00:00:00 2001 From: Ted Kim Date: Wed, 8 Jul 2026 11:22:14 -0400 Subject: [PATCH 1/2] docs(readme): move details into docs --- README.md | 112 +++------------------------------- docs/authentication.md | 42 +++++++++++++ docs/installation.md | 28 +++++++++ docs/project-configuration.md | 63 +++++++++++++++++++ 4 files changed, 143 insertions(+), 102 deletions(-) create mode 100644 docs/authentication.md create mode 100644 docs/installation.md create mode 100644 docs/project-configuration.md diff --git a/README.md b/README.md index 7814eec..c8192d1 100644 --- a/README.md +++ b/README.md @@ -19,11 +19,6 @@ npm install -g @volcano.dev/cli volcano --help ``` -The npm package is a thin wrapper: its `postinstall` step downloads the -platform-specific binary from the matching GitHub Release and verifies it -against that release's `SHA256SUMS`. Set `VOLCANO_SKIP_DOWNLOAD=1` to skip the -download (it is fetched on first run instead). - Build from source: ```bash @@ -52,109 +47,22 @@ files, migrations directory, and README). Use a template to add language-specific files: `javascript` (aliases: `js`, `node`, `nodejs`), `nextjs`, `python`, or `ruby`. -## Authentication - -New to Volcano? Create an account from the CLI: - -```bash -volcano signup -``` - -`volcano signup` prefills your email from `git config --global user.email` -when available (press Enter to accept, or type a different address), 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. - -Already have an account? Authenticate with `volcano login`: - -```bash -# Browser-based login (default) -volcano login - -# Token-based login (for CI/CD) -volcano login --token pk-xxxxxxxxxx - -# Or skip login entirely with an environment variable -export VOLCANO_TOKEN=pk-xxxxxxxxxx -``` - -Log out at any time (this deletes local credentials but does not revoke the -token — revoke it in the Volcano dashboard to fully cut off access): - -```bash -volcano logout -``` - -To target a non-production environment, set `VOLCANO_API_URL` to that backend's -API endpoint. `volcano signup` then opens the signup page on the **same** -environment the API points at — it follows the device-flow verification URL, -just like `volcano login` — so you normally don't need anything else. Set -`VOLCANO_WEB_URL` only to force a specific web origin. - -## Project configuration (`volcano-config.yaml`) - -`volcano config deploy` uploads a declarative manifest -(`volcano/volcano-config.yaml` or `./volcano-config.yaml`) to the server, which -validates and reconciles the full project configuration — project settings, -database assertions, variables, buckets and policies, realtime, the complete -auth configuration (providers, email, templates, managed pages), function -visibility and schedulers, and frontend custom domains. The same manifest -applies to local mode and cloud. `volcano config pull` downloads the current -configuration as a canonical manifest rendered by the server. - -```yaml -version: 1 -variables: - - name: STRIPE_SECRET_KEY - value: ${STRIPE_SECRET_KEY} # interpolated from the CLI environment -realtime: - enabled: true -functions: - - name: hello - public: false - schedulers: - - name: refresh-cache # required, unique per function (the reconcile key) - cron: "*/5 * * * *" - enabled: true - payload: { job: refresh } -``` +More detail lives in `docs/`: -Key semantics (see the hosted manifest reference for the full schema): - -- **Declared config sections are the source of truth.** Variables, bucket - policies, OAuth providers, email templates, and function schedulers are - fully synced when declared: entries absent from the manifest are deleted. - Omitted sections and fields keep their server values. -- **Functions, frontends, databases, and buckets are never created or deleted - through the manifest** — only their configuration is updated. A manifest - entry for a resource that does not exist is skipped with a warning; a - deployed resource missing from a declared section is reported too. -- `${ENV_VAR}` references are interpolated before upload; a reference to an - unset variable is an error, and `$$` produces a literal `$`. -- `volcano config deploy --dry-run` prints the projected actions without - changing anything. Validation failures (including plan-gate violations) - exit non-zero with the server's error list, and nothing is applied. -- Write-only secrets (SMTP password, OAuth client secrets, TLS material) are - omitted from `config pull` exports; keep them in your environment and set - them via `${ENV_VAR}` interpolation. - -Behavior changes from older CLI releases: buckets are no longer auto-created, -an omitted `policies` key now leaves a bucket's policies untouched (previously -it deleted them all), schedulers are now deleted by omission within a declared -`schedulers` list, and the scheduler `regions` field is no longer supported -(placement is managed by the server). +- [Installation details](docs/installation.md) +- [Authentication](docs/authentication.md) +- [Project configuration](docs/project-configuration.md) ## Contributing -See `CONTRIBUTING.md` for local workflows, generated-code guidance, release -notes, and pull request expectations. Participation is governed by -`CODE_OF_CONDUCT.md`. +See [CONTRIBUTING.md](CONTRIBUTING.md) for local workflows, generated-code +guidance, release notes, and pull request expectations. Participation is +governed by [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md). If you believe you have found a security vulnerability, do not open a public -issue. Follow `SECURITY.md` instead. +issue. Follow [SECURITY.md](SECURITY.md) instead. ## License -Volcano CLI is licensed under the Apache License, Version 2.0. See `LICENSE`. +Volcano CLI is licensed under the Apache License, Version 2.0. See +[LICENSE](LICENSE). diff --git a/docs/authentication.md b/docs/authentication.md new file mode 100644 index 0000000..dd5da35 --- /dev/null +++ b/docs/authentication.md @@ -0,0 +1,42 @@ +# Authentication + +New to Volcano? Create an account from the CLI: + +```bash +volcano signup +``` + +`volcano signup` prefills your email from `git config --global user.email` +when available (press Enter to accept, or type a different address), 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. + +Already have an account? Authenticate with `volcano login`: + +```bash +# Browser-based login (default) +volcano login + +# Token-based login (for CI/CD) +volcano login --token pk-xxxxxxxxxx + +# Or skip login entirely with an environment variable +export VOLCANO_TOKEN=pk-xxxxxxxxxx +``` + +Log out at any time: + +```bash +volcano logout +``` + +This deletes local credentials but does not revoke the token. Revoke it in the +Volcano dashboard to fully cut off access. + +To target a non-production environment, set `VOLCANO_API_URL` to that backend's +API endpoint. `volcano signup` then opens the signup page on the same +environment the API points at. It follows the device-flow verification URL, +just like `volcano login`, so you normally do not need anything else. Set +`VOLCANO_WEB_URL` only to force a specific web origin. diff --git a/docs/installation.md b/docs/installation.md new file mode 100644 index 0000000..e369362 --- /dev/null +++ b/docs/installation.md @@ -0,0 +1,28 @@ +# Installation + +Install the latest published release: + +```bash +curl -fsSL https://github.com/Kong/volcano-cli/releases/latest/download/install.sh | bash +``` + +Or install from npm: + +```bash +npm install -g @volcano.dev/cli +volcano --help +``` + +The npm package is a thin wrapper: its `postinstall` step downloads the +platform-specific binary from the matching GitHub Release and verifies it +against that release's `SHA256SUMS`. Set `VOLCANO_SKIP_DOWNLOAD=1` to skip the +download; the binary is fetched on first run instead. + +Build from source: + +```bash +make build +./volcano --help +./volcano --version +make test +``` diff --git a/docs/project-configuration.md b/docs/project-configuration.md new file mode 100644 index 0000000..24edbd2 --- /dev/null +++ b/docs/project-configuration.md @@ -0,0 +1,63 @@ +# Project configuration + +`volcano config deploy` uploads a declarative manifest +(`volcano/volcano-config.yaml` or `./volcano-config.yaml`) to the server, which +validates and reconciles the full project configuration: + +- Project settings +- Database assertions +- Variables +- Buckets and policies +- Realtime +- Auth configuration, including providers, email, templates, and managed pages +- Function visibility and schedulers +- Frontend custom domains + +The same manifest applies to local mode and cloud. `volcano config pull` +downloads the current configuration as a canonical manifest rendered by the +server. + +```yaml +version: 1 +variables: + - name: STRIPE_SECRET_KEY + value: ${STRIPE_SECRET_KEY} # interpolated from the CLI environment +realtime: + enabled: true +functions: + - name: hello + public: false + schedulers: + - name: refresh-cache # required, unique per function (the reconcile key) + cron: "*/5 * * * *" + enabled: true + payload: { job: refresh } +``` + +Key semantics: + +- Declared config sections are the source of truth. Variables, bucket policies, + OAuth providers, email templates, and function schedulers are fully synced + when declared: entries absent from the manifest are deleted. Omitted sections + and fields keep their server values. +- Functions, frontends, databases, and buckets are never created or deleted + through the manifest; only their configuration is updated. A manifest entry + for a resource that does not exist is skipped with a warning. A deployed + resource missing from a declared section is reported too. +- `${ENV_VAR}` references are interpolated before upload. A reference to an + unset variable is an error, and `$$` produces a literal `$`. +- `volcano config deploy --dry-run` prints the projected actions without + changing anything. Validation failures, including plan-gate violations, exit + non-zero with the server's error list, and nothing is applied. +- Write-only secrets, such as SMTP passwords, OAuth client secrets, and TLS + material, are omitted from `config pull` exports. Keep them in your + environment and set them via `${ENV_VAR}` interpolation. + +Behavior changes from older CLI releases: + +- Buckets are no longer auto-created. +- An omitted `policies` key now leaves a bucket's policies untouched; older + releases deleted them all. +- Schedulers are now deleted by omission within a declared `schedulers` list. +- The scheduler `regions` field is no longer supported. Placement is managed by + the server. From 422d6ad7e760098a9140f65805e1955aa52e7328 Mon Sep 17 00:00:00 2001 From: Ted Kim Date: Wed, 8 Jul 2026 13:46:43 -0400 Subject: [PATCH 2/2] docs(readme): focus docs on end users --- README.md | 39 +++++++++++++---------------------- docs/authentication.md | 6 ------ docs/installation.md | 9 -------- docs/project-configuration.md | 20 +++++++++--------- 4 files changed, 24 insertions(+), 50 deletions(-) diff --git a/README.md b/README.md index c8192d1..14bbd6f 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,7 @@ -# volcano-cli +# Volcano CLI -`volcano` is the command-line client for Volcano, Kong's hosting platform. -It provides local development workflows and hosted API commands from a -standalone Go CLI. +`volcano` is the command-line client for Volcano, Kong's hosting platform. It +helps you scaffold, run, and manage Volcano projects from your terminal. ## Quickstart @@ -19,27 +18,17 @@ npm install -g @volcano.dev/cli volcano --help ``` -Build from source: +Create a project directory and start local development: ```bash -make build -./volcano --help -./volcano --version -make test -``` - -From the CLI checkout, create an empty sibling project directory and run it: - -```bash -VOLCANO_CLI="$(pwd)/volcano" -mkdir ../volcano-quickstart -cd ../volcano-quickstart -"$VOLCANO_CLI" init javascript -"$VOLCANO_CLI" start -"$VOLCANO_CLI" variables deploy -"$VOLCANO_CLI" functions deploy --all -"$VOLCANO_CLI" config deploy -"$VOLCANO_CLI" migrations deploy --all -d app +mkdir volcano-quickstart +cd volcano-quickstart +volcano init javascript +volcano start +volcano variables deploy +volcano functions deploy --all +volcano config deploy +volcano migrations deploy --all -d app ``` `volcano init` without a template creates a base scaffold (environment @@ -56,8 +45,8 @@ More detail lives in `docs/`: ## Contributing See [CONTRIBUTING.md](CONTRIBUTING.md) for local workflows, generated-code -guidance, release notes, and pull request expectations. Participation is -governed by [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md). +guidance, building from source, release notes, and pull request expectations. +Participation is governed by [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md). If you believe you have found a security vulnerability, do not open a public issue. Follow [SECURITY.md](SECURITY.md) instead. diff --git a/docs/authentication.md b/docs/authentication.md index dd5da35..19fb831 100644 --- a/docs/authentication.md +++ b/docs/authentication.md @@ -34,9 +34,3 @@ volcano logout This deletes local credentials but does not revoke the token. Revoke it in the Volcano dashboard to fully cut off access. - -To target a non-production environment, set `VOLCANO_API_URL` to that backend's -API endpoint. `volcano signup` then opens the signup page on the same -environment the API points at. It follows the device-flow verification URL, -just like `volcano login`, so you normally do not need anything else. Set -`VOLCANO_WEB_URL` only to force a specific web origin. diff --git a/docs/installation.md b/docs/installation.md index e369362..2d5fa30 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -17,12 +17,3 @@ The npm package is a thin wrapper: its `postinstall` step downloads the platform-specific binary from the matching GitHub Release and verifies it against that release's `SHA256SUMS`. Set `VOLCANO_SKIP_DOWNLOAD=1` to skip the download; the binary is fetched on first run instead. - -Build from source: - -```bash -make build -./volcano --help -./volcano --version -make test -``` diff --git a/docs/project-configuration.md b/docs/project-configuration.md index 24edbd2..fe9af96 100644 --- a/docs/project-configuration.md +++ b/docs/project-configuration.md @@ -1,11 +1,11 @@ # Project configuration `volcano config deploy` uploads a declarative manifest -(`volcano/volcano-config.yaml` or `./volcano-config.yaml`) to the server, which -validates and reconciles the full project configuration: +(`volcano/volcano-config.yaml` or `./volcano-config.yaml`) to Volcano, which +validates and applies the full project configuration: - Project settings -- Database assertions +- Database requirements - Variables - Buckets and policies - Realtime @@ -13,9 +13,9 @@ validates and reconciles the full project configuration: - Function visibility and schedulers - Frontend custom domains -The same manifest applies to local mode and cloud. `volcano config pull` -downloads the current configuration as a canonical manifest rendered by the -server. +The same manifest applies to local development and cloud projects. +`volcano config pull` downloads the current configuration as a canonical +manifest rendered by Volcano. ```yaml version: 1 @@ -39,7 +39,7 @@ Key semantics: - Declared config sections are the source of truth. Variables, bucket policies, OAuth providers, email templates, and function schedulers are fully synced when declared: entries absent from the manifest are deleted. Omitted sections - and fields keep their server values. + and fields keep their existing values. - Functions, frontends, databases, and buckets are never created or deleted through the manifest; only their configuration is updated. A manifest entry for a resource that does not exist is skipped with a warning. A deployed @@ -47,8 +47,8 @@ Key semantics: - `${ENV_VAR}` references are interpolated before upload. A reference to an unset variable is an error, and `$$` produces a literal `$`. - `volcano config deploy --dry-run` prints the projected actions without - changing anything. Validation failures, including plan-gate violations, exit - non-zero with the server's error list, and nothing is applied. + changing anything. Validation failures exit non-zero with Volcano's error + list, and nothing is applied. - Write-only secrets, such as SMTP passwords, OAuth client secrets, and TLS material, are omitted from `config pull` exports. Keep them in your environment and set them via `${ENV_VAR}` interpolation. @@ -60,4 +60,4 @@ Behavior changes from older CLI releases: releases deleted them all. - Schedulers are now deleted by omission within a declared `schedulers` list. - The scheduler `regions` field is no longer supported. Placement is managed by - the server. + Volcano.