Env and secrets

An arc has one .env. Compose reads it the way it reads a .env beside your compose file: for each ${VARIABLE} in docker-compose.yml, and for env_file: .env. Every branch of the arc uses the same one.

Its values are write-only. No command prints one, and a deploy's output hides any value it would show. OmniArc stores the file encrypted, and keeps it apart from the arc's data, so no copy of that data carries it. Your local .env is never uploaded with your project.

# Set a variable

The shop's database password is ${POSTGRES_PASSWORD:-shop}: the arc's value if it has one, shop if not. To set it:

omniarc env set POSTGRES_PASSWORD

It asks for the value and does not show what you type. It never takes the value on the command line, so it stays out of your shell history. From a script, pipe it in:

printf %s "$POSTGRES_PASSWORD" | omniarc env set POSTGRES_PASSWORD

Names take letters, digits and _, and do not start with a digit. A value with a quote or a line break in it needs omniarc env push, below.

Every omniarc env command acts on the arc named in ./arc.yaml, so run them in your project directory, or name the arc with --arc shop.

# Set it before the first deploy

Some images read a variable only once. Postgres sets its password from POSTGRES_PASSWORD when it creates its database, the first time it starts, and never again. If you deployed the shop from Get started, its database already has the password shop: set a new one now and, at the next deploy, web would connect with it to a database that still has the old one.

So set such secrets before the first deploy. The arc has to exist for that, so create it first:

omniarc arc create shop
omniarc env set POSTGRES_PASSWORD
omniarc deploy

To change one afterwards, change it inside the service too: for Postgres, with ALTER USER.

# A change applies at the next deploy

Setting a variable changes no running service. Each branch picks it up at its next deploy. To apply it to production without changing the code, redeploy what it runs:

omniarc deploy --revision current

omniarc env list shows which branches are behind, and the command for each.

# Upload a whole file

omniarc env push

Replaces the arc's .env with your local .env, byte for byte (--file names another file). It is refused, and nothing is sent, if the arc does not exist; --create creates it. Up to 256 KiB.

A project that keeps its values in several files sends them as one:

omniarc env push --file .env --file apps/api/.env

The files are merged in order: a later file's value for a name replaces an earlier one's. Only the names are printed.

# See and remove

omniarc env list
omniarc env unset POSTGRES_PASSWORD

list prints the names, never the values, and the branches whose last deploy predates the current .env.

# A variable nobody set

A deploy stops on a ${VARIABLE} that has no default in compose and is not in the arc's .env, with unset-variable. Set it, or give it a default with ${VARIABLE:-value}.

# Compose secrets and env files

An env_file named like a .env file (env_file: ./apps/api/.env, config/app.env) reads the arc's one .env, exactly as env_file: .env does: on the node each such path is a link to it. Send the values those files hold with omniarc env push (several files merge into one, above).

Compose secrets: read from a file in your project, and any other env_file (vars.txt, a path outside the project), are refused. Put the values in the arc's .env and read them with ${VARIABLE} or env_file: .env. See Compose support.

Templates such as .env.example stay on your machine, and omniarc check says nothing about them.