Skip to main content
How-to

Run the StoreFront CLI in Docker, Fly.io and CI

Containers and CI machines have no keychain, so the CLI keeps the sign-in in an encrypted file under its configuration directory, unlocked by a credential key from the platform's secrets. Status: Documented. Hosted agents, containers and CI explains the mechanism; this page has the platform steps.

Prerequisites​

  • An image with Node.js 24 or newer and npm.
  • A persistent volume for the CLI's configuration directory.
  • A person with access to the platform's secrets, to create the key. An agent never creates, reads or types it.

Install the CLI and skill in the image​

Install the CLI and create the workspace when you build the image, naming the agent that will run in it:

npm install -g @ultracart/storefront-cli@beta
uc-storefront init /workspace/my-storefront --target codex --no-input
uc-storefront --workspace /workspace/my-storefront skills status --check

Use --target claude for Claude Code, and --target codex for Codex and OpenClaw. Never bake the credential key, the configuration directory or a sign-in into the image. See Bake the CLI and skill into the image.

Docker​

Create the key​

Choose one:

  • A variables file outside any project. This creates and stores the key without displaying it:

    umask 077; openssl rand -base64 32 | sed 's/^/ULTRACART_STOREFRONT_CREDENTIAL_KEY=/' > ~/.uc-storefront-key.vars

    Run the container with --env-file ~/.uc-storefront-key.vars.

  • A Docker or Kubernetes secret mounted as a file. This keeps the key out of every shell's environment. Set ULTRACART_STOREFRONT_CREDENTIAL_KEY_FILE to the mounted path. The file must be owned by the container's user with mode 0400 or 0600; in Compose, set uid, gid and mode on the secret. It must be on different storage from the configuration volume.

Set only one of the two variables. Setting both is refused with credential_key_conflict.

Keep the configuration on a volume​

Mount a named volume and point ULTRACART_STOREFRONT_CONFIG_DIR at it, the same path in every container run. Profiles, the refresh lock and the encrypted sign-in (credentials/*.enc) live there.

docker run --env-file ~/.uc-storefront-key.vars \
-v uc-storefront-config:/data/uc-storefront \
-e ULTRACART_STOREFRONT_CONFIG_DIR=/data/uc-storefront \
YOUR_IMAGE # <- your image

The volume name and mount path are examples; use your own.

Fly.io​

Create and store the key without displaying it:

openssl rand -base64 32 | sed 's/^/ULTRACART_STOREFRONT_CREDENTIAL_KEY=/' | fly secrets import

fly secrets set ULTRACART_STOREFRONT_CREDENTIAL_KEY="$(openssl rand -base64 32)" also works. Then mount a Fly volume on the machine and set ULTRACART_STOREFRONT_CONFIG_DIR to a folder on it. Restart the machine so the CLI sees the secret.

Check the key and sign in​

Inside the container:

uc-storefront auth status
uc-storefront profile create my-store
uc-storefront auth login --profile my-store --no-wait
uc-storefront auth login --profile my-store --continue --wait
uc-storefront profile bind my-store
uc-storefront auth status
  1. The first auth status should show credential store: encrypted-file (durable, available) and credential key: set. Before a profile exists it also refuses and exits 1; that is expected.
  2. auth login --no-wait prints a URL and a code and exits at once. The agent relays them; you approve in your own browser.
  3. auth login --continue --wait waits up to 45 seconds. Exit 3 means still waiting; run it again until it exits 0.
  4. The last auth status shows credential store: encrypted-file and local grant: present.

If credential key shows absent, the secret is not reaching the container: check the variable name and restart. invalid means the value is not a 32-byte base64 key; unsafe_file means the key file is not a private regular file.

When the container's address changes​

A sign-in works only from the IPv4 addresses you approved; the first is where it signed in. After a redeploy that changes the outgoing address, commands stop with location_approval_required. Run uc-storefront auth approve-location, and approve the request from the link and code it prints (UltraCart also emails you). Exit 3 means still waiting: run uc-storefront sf approvals wait <id>, then uc-storefront auth approve-location --approval <id>. Deny any request you did not expect.

To avoid an approval after every redeploy, give the container a stable outgoing address, such as a static outbound address from your platform or a Tailscale exit node. See Approved addresses and a stable IP.

CI runners​

In CI, use the CLI for checks that need no sign-in: skills status --check for skill drift, and offline commands such as cjson validate. Pin the CLI as an exact project dependency and run it through npm exec -- uc-storefront; see Pin the CLI for a team and Script it.

Signed-in commands (anything that reads or changes your store) are not supported on CI runners that start fresh for each job. A sign-in needs a person to approve it, belongs to one machine, and works only from addresses that person approved, while a fresh runner has none of these: a new sign-in each run, and often a new address. Copying the configuration folder into a runner is not a workaround; a renewal by one copy signs the other out.

Run remote commands from a long-lived machine with a persistent configuration folder and a stable outgoing address instead. That is a hosted agent, set up as described above.

Caveats​

  • One sign-in per container. Never copy the configuration folder to another machine: a renewal by one copy signs the other out.
  • A new key makes the saved sign-in unreadable. Run auth login again.
  • Anything with both the files and the key can use the sign-in, so keep the key in the secret store and the files on the volume.

Next steps​

Was this page helpful?