Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
21 changes: 13 additions & 8 deletions .agents/skills/compoza/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -82,7 +82,9 @@ service's container. The top-level `environment` and `secrets` stay Compose
interpolation inputs. A name set in a role must not also be in the service's Compose
`environment:`, and role secrets need a secret source other than `none`. `check`
reports these problems without fetching secrets. The generated override,
`compoza.roles.yaml`, holds `${NAME}` references, never secret values.
`compoza.roles.yaml`, holds `${NAME}` references, never secret values. A destination
or `local.roles` can change a role's `environment` and `secrets`, or remove the role
for that run with `null`; it cannot change `build`.

## Recover with a known image tag

Expand All @@ -95,11 +97,11 @@ compoza status infra
`--tag` skips Git/builds and reuses images with the current local configuration and
currently selected secret source. `--tag <tag>` applies to every role with `build`, and
`--tag <role>=<tag>` overrides it for one role; repeat the flag as needed. Every role
with `build` needs a tag. A missing source checkout is allowed for `--tag`, stacks whose
roles build nothing, status, logs and lifecycle commands. There is no release rollback
command, saved configuration history or backup folder. Check out an earlier app
revision separately when its configuration is required. Never imply that database
changes are reversed.
with `build` needs a tag, and `--tag` fails when no role builds. A missing source
checkout is allowed for `--tag`, stacks whose roles build nothing, status, logs and
lifecycle commands. There is no release rollback command, saved configuration history
or backup folder. Check out an earlier app revision separately when its configuration
is required. Never imply that database changes are reversed.

SSH stacks contain `compose.yaml`, private `.env`, declared assets and one nonsecret
`.compoza.json` lifecycle metadata file, which records each role's tag. The roles
Expand Down Expand Up @@ -141,8 +143,11 @@ authorized before publishing. Do not change section paths to work around a failu
desktop account may be saved with `compoza config set 1password.account`. Leave changing
it, and `hosts link`/`unlink`, to the user unless asked: they affect every later run.
Do not fetch a personal vault just to validate implementation changes.
- Do not print resolved Compose config, dotenv contents or provider exceptions. Managed status omits command/image/container-name
fields; requested application logs can still contain secrets and need care.
- Do not print resolved Compose config, dotenv contents or provider exceptions. Managed
status shows only service, image, state, health and exit code, with secret values redacted
(all dotenv values for stacks deployed by an earlier version; `.compoza.json` records
the secret variable names); requested application logs can still contain secrets and
need care.

## Diagnose and report

Expand Down
21 changes: 13 additions & 8 deletions .claude/skills/compoza/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -82,7 +82,9 @@ service's container. The top-level `environment` and `secrets` stay Compose
interpolation inputs. A name set in a role must not also be in the service's Compose
`environment:`, and role secrets need a secret source other than `none`. `check`
reports these problems without fetching secrets. The generated override,
`compoza.roles.yaml`, holds `${NAME}` references, never secret values.
`compoza.roles.yaml`, holds `${NAME}` references, never secret values. A destination
or `local.roles` can change a role's `environment` and `secrets`, or remove the role
for that run with `null`; it cannot change `build`.

## Recover with a known image tag

Expand All @@ -95,11 +97,11 @@ compoza status infra
`--tag` skips Git/builds and reuses images with the current local configuration and
currently selected secret source. `--tag <tag>` applies to every role with `build`, and
`--tag <role>=<tag>` overrides it for one role; repeat the flag as needed. Every role
with `build` needs a tag. A missing source checkout is allowed for `--tag`, stacks whose
roles build nothing, status, logs and lifecycle commands. There is no release rollback
command, saved configuration history or backup folder. Check out an earlier app
revision separately when its configuration is required. Never imply that database
changes are reversed.
with `build` needs a tag, and `--tag` fails when no role builds. A missing source
checkout is allowed for `--tag`, stacks whose roles build nothing, status, logs and
lifecycle commands. There is no release rollback command, saved configuration history
or backup folder. Check out an earlier app revision separately when its configuration
is required. Never imply that database changes are reversed.

SSH stacks contain `compose.yaml`, private `.env`, declared assets and one nonsecret
`.compoza.json` lifecycle metadata file, which records each role's tag. The roles
Expand Down Expand Up @@ -141,8 +143,11 @@ authorized before publishing. Do not change section paths to work around a failu
desktop account may be saved with `compoza config set 1password.account`. Leave changing
it, and `hosts link`/`unlink`, to the user unless asked: they affect every later run.
Do not fetch a personal vault just to validate implementation changes.
- Do not print resolved Compose config, dotenv contents or provider exceptions. Managed status omits command/image/container-name
fields; requested application logs can still contain secrets and need care.
- Do not print resolved Compose config, dotenv contents or provider exceptions. Managed
status shows only service, image, state, health and exit code, with secret values redacted
(all dotenv values for stacks deployed by an earlier version; `.compoza.json` records
the secret variable names); requested application logs can still contain secrets and
need care.

## Diagnose and report

Expand Down
4 changes: 2 additions & 2 deletions docs/commands.md
Original file line number Diff line number Diff line change
Expand Up @@ -112,7 +112,7 @@ compoza deploy infra --tag 1a2b3c4d5e6f
compoza deploy infra --tag 1a2b3c4d5e6f --tag worker=9f8e7d6c5b4a
```

Every role with a `build` must end up with a tag. Naming an unknown role, a role without `build` or the same role twice fails, and so does a second bare tag. A tag follows Docker's rules: letters, digits, underscores, dots and dashes, at most 128 characters, not starting with a dot or dash. That rejects `--tag web:abc`, a likely typo for `--tag web=abc`. The **current local configuration** is used; there is no saved configuration history.
Every role with a `build` must end up with a tag. Naming an unknown role, a role without `build` or the same role twice fails, and so does a second bare tag. A tag follows Docker's rules: letters, digits, underscores, dots and dashes, at most 128 characters, not starting with a dot or dash. That rejects `--tag web:abc`, a likely typo for `--tag web=abc`. On a stack where no role has a `build`, any `--tag` fails, because there are no images to reuse. The **current local configuration** is used; there is no saved configuration history.

A failed deploy can leave new containers or routes running: there is no automatic rollback. Inspect `status` and `logs`, then deploy a known tag. See [Images and tags](configuration.md#images-and-tags), [Local runs](configuration.md#local-runs) and, for SSH execution, the [deploy transaction](ssh-deployment.md#deploy-transaction).

Expand All @@ -129,7 +129,7 @@ NAME IMAGE COMMAND SERVICE CREATED
hello-web-web-1 nginx:alpine "/docker-entrypoint.…" web 2 seconds ago Up 1 second 127.0.0.1:8080->80/tcp
```

With `execution: ssh` and a managed secret source, status shows only the service, state, health and exit code, with dotenv values redacted.
With `execution: ssh` and a managed secret source, status prints one JSON object per container with only its service, image, state, health and exit code, with managed secret values redacted (all dotenv values for a stack deployed by an earlier version). An image that does not look like an image reference shows as `(image)`.

## logs

Expand Down
14 changes: 12 additions & 2 deletions docs/configuration.md
Original file line number Diff line number Diff line change
Expand Up @@ -410,7 +410,7 @@ Without `roles` there is no extra file and nothing changes.

- The image of a role with `build` is `<name>-<role>:<tag>`, prefixed with the registry for registry transport. compoza sets it as the service's `image`.
- A build requires a clean checkout with at least one commit in each role's repository. Each repository is checked once, and its roles are tagged with the first twelve characters of its commit. `--allow-dirty` permits a dirty checkout and tags `<commit>-dirty`.
- `--tag` reuses images built earlier and skips Git and builds, so it works from a deploy folder outside any checkout. `--tag <tag>` applies to every role with `build`, and `--tag <role>=<tag>` overrides it for one role; repeat the flag as needed. Every role with `build` must end up with a tag. `--tag` always uses the **current local configuration**; there is no saved Compose configuration history.
- `--tag` reuses images built earlier and skips Git and builds, so it works from a deploy folder outside any checkout. `--tag <tag>` applies to every role with `build`, and `--tag <role>=<tag>` overrides it for one role; repeat the flag as needed. Every role with `build` must end up with a tag. A stack where no role has `build` (after any [role removal](#destinations)) has no images to reuse, so any `--tag` fails. Naming a role that a destination or `local.roles` removed fails and says the role is removed for the run. `--tag` always uses the **current local configuration**; there is no saved Compose configuration history.
- Progress messages show the single tag when all roles share it, and `web=abc worker=def` otherwise.
- Without any role that has `build` there is no Git, Dockerfile or build-context requirement, and no build or application-registry authentication check. Compose still pulls missing third-party images, and the deploy is tagged `third-party`.

Expand All @@ -431,7 +431,7 @@ Compose resolves relative bind mounts on the host, so host paths must be absolut

### Local runs

`local` overrides `composeFiles`, `environment` and the complete secret source for `--local` runs. `local.roles` sets `environment` and `secrets` per role and merges over the app's roles the way [destinations](#destinations) do; `build` cannot be changed. When the app declares a production secret source, an explicit `local.secrets` is required, including `none: {}` when local Compose needs no secrets.
`local` overrides `composeFiles`, `environment` and the complete secret source for `--local` runs. `local.roles` sets `environment` and `secrets` per role and merges over the app's roles the way [destinations](#destinations) do; `build` cannot be changed. Setting a role to `null` removes it from local runs (no build, image, environment, secrets or Compose validation), for a stack whose local Compose files leave a service out: `local: { roles: { worker: null } }`. The removal is checked when the config loads (see [Destinations](#destinations)). If the Compose files still declare the service, it runs as they define it, without compoza's image or role settings. When the app declares a production secret source, an explicit `local.secrets` is required, including `none: {}` when local Compose needs no secrets.

`--local` builds into this machine's Docker and starts the stack here, without remote readiness checks, transport or routes. It keeps this client build-and-run behavior regardless of `execution`.

Expand Down Expand Up @@ -465,6 +465,16 @@ destinations:
- When supplied, a destination **replaces** `host`, `projectName`, `composeFiles`, `execution`, the entire `remote` object, `profiles`, `ingress`, `health`, `directories`, `content` and the complete `secrets` source.
- A destination's `environment` **merges** over the app defaults.
- A destination's `roles` take `environment` and `secrets` per role, without `build`: destinations share the source. For each role, `environment` merges key by key over the app role's, and `secrets` replaces the app role's list. A role named only in the destination is allowed and sets environment only.
- A destination removes a role with `null`, for a destination whose Compose files have no such service. The role gets no build, image, environment or secrets, is not checked against the Compose files, is not Git-checked or tagged, and its secrets are no longer added to a 1Password `variables` allowlist. If the selected Compose files still declare the service, it runs as they define it, without compoza's image or role settings. Every `null` in every destination and in `local.roles` is checked when the config loads, including destinations you do not select, and must name a role in the top-level `roles`; otherwise loading fails with the file name and a message such as `Destination "staging" removes role "wrker", which is not a role; roles: web, worker`. A role removed by the selected destination stays removed in a `--local` run: `local.roles` entries for it are ignored. `null` is accepted only under `destinations.<name>.roles` and `local.roles`, not in the top-level `roles`.

```yaml
destinations:
staging:
composeFiles: [compose.yaml] # has no worker service
roles:
worker: null
```

- `name` remains the image prefix; `projectName` selects the Compose project and the Caddy site-file key.
- Unknown destination names fail.

Expand Down
2 changes: 1 addition & 1 deletion docs/secrets.md
Original file line number Diff line number Diff line change
Expand Up @@ -162,7 +162,7 @@ roles:
- Only services whose role lists a secret receive it. Any other service that needs the value still maps it in Compose.
- The override holds a `${NAME}` reference, never the value. The value stays in the interpolation pool: the stack `.env` over SSH, the process environment for client execution.
- With `variables: []` as above, the 1Password read returns exactly the role secrets.
- `destinations.<name>.roles.<role>.secrets` replaces that role's list, and `local.roles` does the same for `--local` runs, which read the local source.
- `destinations.<name>.roles.<role>.secrets` replaces that role's list, and `local.roles` does the same for `--local` runs, which read the local source. A role set to `null` in either place is removed for that run, so its secrets are no longer added to a 1Password `variables` allowlist.

A role secret that is missing from the source, reserved, or also set in the service's Compose `environment:` fails validation before anything is built. See [Environment and secrets](configuration.md#environment-and-secrets) for every rule.

Expand Down
2 changes: 1 addition & 1 deletion docs/ssh-deployment.md
Original file line number Diff line number Diff line change
Expand Up @@ -189,7 +189,7 @@ With [roles](configuration.md#how-roles-reach-services), the generated `compoza.

Before replacing the deployed files or running `up`, Compose validates the normalized file with the selected env and overlay. A private JSON model check rejects undeclared relative files, unsafe writable asset binds and relative secret/env paths. Resolved Compose configuration and third-party diagnostics are suppressed because they can contain secrets; no validation log is left in the stack.

Managed status projects only service/state/health/exit-code fields and redacts selected dotenv values. Requested application logs can still contain secrets; applications are responsible for their logging policy.
Managed status projects only service/image/state/health/exit-code fields (the image only when it is a well-formed reference, otherwise `(image)`) and redacts the values of the managed secret variables. `.compoza.json` records those variable names, never their values; a stack deployed by an earlier version has no list, so all dotenv values are redacted until it is redeployed. Requested application logs can still contain secrets; applications are responsible for their logging policy.

## Deploy transaction

Expand Down
4 changes: 2 additions & 2 deletions src/cli.ts
Original file line number Diff line number Diff line change
Expand Up @@ -490,8 +490,8 @@ const status = Command.make(
helpText([
"Lists the app's containers on its host with docker compose ps --all, so a stopped stack " +
'shows as stopped instead of missing. It changes nothing.',
'With execution: ssh and a managed secret source, only the service, state, health and ' +
'exit code are shown, with dotenv values redacted.',
'With execution: ssh and a managed secret source, only the service, image, state, health ' +
'and exit code are shown, with secret values redacted.',
]),
),
Command.withExamples([{ command: 'compoza status infra' }]),
Expand Down
Loading
Loading