Deploy a project

volcano deploy deploys everything the project directory describes to the local development server. volcano cloud deploy does the same for the selected cloud project.

volcano start
volcano deploy --with-migrations

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.

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.

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

-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.

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:

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, and without tracking: every file runs again on each run. Write migrations that are safe to re-run, for example with create table if not exists, and put one SQL statement in each file. When a later step fails, run the command again without --with-migrations and -d, since the migrations already ran.

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.

{
  "version": 1,
  "frontends": [
    { "name": "web", "workspace": "", "app_root": "web" }
  ]
}

app_root must contain the app's package.json, or be the directory that a parent package.json builds with next build <dir>, 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:

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 deploy reports the commit its source came from, so Volcano can tie the deployment to your repository. The CLI sends four things: the GitHub repository as owner/name, the commit ID, whether the uploaded files differ from that commit, and the uploaded directory's path in the repository, which is empty when it's the repository's top level. It never sends the remote URL or any credentials in it, local paths, branch names, or diffs. Function and durable function deploys don't report a commit for now.

The CLI reads the commit checked out in the directory --path names: 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, the uploaded directory is outside the repository, or any part is missing. Local deploys never send it.

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.

Volcano verifies the commit against the project's connected repository: a commit on its production branch is verified. LavaFlow reads source and opens fix pull requests only for a deployment whose commit is verified and whose upload matched it, so commit your changes before you deploy. Of the deploys the CLI runs, only frontend deploys can get LavaFlow fix pull requests for now. A workflow run for a pull request deploys GitHub's merge commit, which is on no branch, so that deployment is recorded unverified. frontends deploy --from keeps the commit of the build it publishes. A 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:

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 <manifest>, 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
• Functions
• Durable functions
• Frontends
• Declarative configuration