Deploy

Three commands, all run in the directory that holds your compose file and arc.yaml: check on your machine, sync to keep arc.yaml in step with compose, and deploy.

# Check

omniarc check

The checks a deploy runs, on your machine, with nothing uploaded and no key needed. Every error says what is wrong and links to its page in the list of errors:

error    application `db` holds personal data and may be branched, with no anonymize rules — ...
         see https://docs.omniarc.eu/errors/pii-without-anonymize

An error stops a deploy. A warning deserves a look but does not. Notes, what the checks did on the way, are counted at the end and shown with --verbose. With OMNIARC_KEY set, a variable your compose files use without a default is checked against the names in your arc's .env; without it, against this directory's .env, as a warning.

With docker compose installed it also checks arc.yaml against your compose services, and your compose file against what an arc supports. Without it, those checks run when you deploy.

# Sync

omniarc sync --write

Run it after you add or remove a compose service. It adds an entry for each new service (one that keeps data is assumed to hold personal data and to start empty in a branch, until you say otherwise), drops the entries compose no longer defines, and never changes a decision already in arc.yaml. Without --write it only prints the draft. See Write arc.yaml.

# Deploy

omniarc deploy

It runs the same checks, uploads the project, and follows the deploy until it ends. The first deploy of an arc creates it:

  bundle  9cad…8753  3 files  0.0 MiB
  checks  ok — 0 notes
  created arc shop
  deploy  <id>  revision 1
  upload  done
  checks  …
  build   …
  up      …
  up      db healthy · web running
  revision 1  healthy

Images are pulled, and services with a build: are built, on OmniArc rather than on your machine. Then compose starts your services and OmniArc waits for each one to be up and, where it has a health check, healthy, for up to ready_timeout_secs.

If a deploy fails, it prints why and the last lines of the failing service's log, and exits non-zero. That, and needing nothing but OMNIARC_KEY, makes it a CI step as it is: install the CLI, set OMNIARC_KEY from your CI's secrets, and run omniarc deploy.

# What is uploaded

What you would commit. In a Git work tree that is your tracked files and the untracked ones no ignore rule excludes; anywhere else, every file but .git. Add a .omniarcignore at the top of the project, in .gitignore syntax, to leave more out.

Never uploaded: .env files, which the arc has its own of (see Env and secrets), and files shaped like secrets, such as private keys, .envrc and registry credentials, which the CLI names as it skips them. A project can be at most 20,000 files and 512 MiB, and 256 MiB once compressed. Over a limit, omniarc check suggests .omniarcignore lines that leave only what compose reads.

# If you stop following

Ctrl-C stops the CLI, not the deploy. Re-attach with the id it printed on the deploy line:

omniarc deploy --follow <id>

# Revisions

Every deploy is a revision, numbered across the whole arc. The dashboard's arc page lists them under Deploys. To go back to one, redeploy it, here to production:

omniarc deploy --revision 3

--revision current redeploys what the branch runs now, with the arc's current .env: the way to apply a changed .env without changing the code.

--pull pulls every image again even when it is already there, for an image tag such as latest that has moved.

# Deploy to a branch

omniarc deploy deploys to production. To deploy your working copy to a branch instead, one you created with omniarc arc branch create:

omniarc deploy --branch preview

The branch keeps its own data; only the code and configuration change. See Branches.

# For scripts and agents

omniarc commands prints every command, its arguments and what it returns as JSON, for the CLI you have installed. Every command but deploy also takes --json, for output a script can read.