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
28 changes: 23 additions & 5 deletions .agents/skills/compoza/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -70,6 +70,20 @@ relative to deploy.yaml after destination selection. Credentials stay in Caddy e
placeholders, never literal template text. Shared config templates apply only during
provisioning; they do not overwrite operator-managed configuration.

## Roles

Each key under `roles` in deploy.yaml is a Compose service. `targets` and the
`${<TARGET>_IMAGE}` variables no longer exist: a config that still has `targets` fails
until it is migrated. A role with `build` is built as `<name>-<role>:<tag>`, and compoza
sets that service's `image`. Its `target`, `workingDirectory`, `dockerfile` and
`context` fall back to the top-level fields. A role's `environment` holds literal
values and its `secrets` names variables from the secret source; both reach only that
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.

## Recover with a known image tag

```sh
Expand All @@ -79,13 +93,17 @@ compoza status infra
```

`--tag` skips Git/builds and reuses images with the current local configuration and
currently selected secret source. A missing source checkout is allowed for `--tag`,
`targets: []`, 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.
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.

SSH stacks contain `compose.yaml`, private `.env`, declared assets and one nonsecret
`.compoza.json` lifecycle metadata file. A live host overlay may also be present.
`.compoza.json` lifecycle metadata file, which records each role's tag. The roles
override is merged into the flat `compose.yaml`. A live host overlay may also be present.
Runtime scripts and filters are sent with each CLI operation, not installed on the host.
Upload and validation failures leave deployed files unchanged. Later replacement,
Compose, routing or health failures can leave changed files or containers; recover
Expand Down
17 changes: 11 additions & 6 deletions .agents/skills/deploy/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -49,9 +49,13 @@ compoza logs infra --tail 50
- Explain the target, image transport, and proposed changes from the preview. An SSH
dry run does not stage files, build images, lock the stack, or validate the full host
candidate. Do not present it as proof that deployment will succeed.
- Built targets normally require a clean committed checkout in the resolved source directory. Do not commit changes or
add `--allow-dirty` without authorization. `targets: []` and `--tag` need no source checkout or Dockerfile.
Status, logs and lifecycle operations also work without that source directory.
- Each role with `build` normally requires a clean committed checkout of its source
repository, and is tagged with that repository's commit. Do not commit changes or add
`--allow-dirty` without authorization. Stacks whose roles build nothing, and `--tag`
deploys, need no source checkout or Dockerfile. Status, logs and lifecycle operations
also work without that source directory.
- A config that still has `targets` fails to load. Propose the migration to `roles`
(docs/configuration.md, "Migrating from 0.6.0") instead of editing it unasked.
- Once deployment is authorized, continue through verification; do not request the
same permission again. Report phase failures rather than retrying blindly.
- Success requires the final `Deployed` message and expected service state. Only
Expand Down Expand Up @@ -94,15 +98,16 @@ Never overwrite operator data to bypass an ownership error.

Upload and validation failure preserve deployed files. Replacement is in place, and
later failure can leave changed files, containers or routes. Recover using
`deploy --tag <known-image-tag>` with current local configuration and the current
credential source. There is no saved release configuration or rollback command.
`deploy --tag <known-image-tag>`, adding `--tag <role>=<tag>` where roles differ, with
the current local configuration and credential source. There is no saved release configuration or rollback command.
Do not promise automatic recovery or reversal of database changes. Lifecycle uses the
deployed files without fetching a provider. Do not remove a lock without establishing
that its owner has exited.

## Handoff

Report the destination, image tag, verification result, and URL when configured.
Report the destination, image tag (per role when they differ), verification result,
and URL when configured.
Identify any remaining action, such as publishing a content section. Do not claim
success when a phase failed or cleanup is still required.

Expand Down
28 changes: 23 additions & 5 deletions .claude/skills/compoza/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -70,6 +70,20 @@ relative to deploy.yaml after destination selection. Credentials stay in Caddy e
placeholders, never literal template text. Shared config templates apply only during
provisioning; they do not overwrite operator-managed configuration.

## Roles

Each key under `roles` in deploy.yaml is a Compose service. `targets` and the
`${<TARGET>_IMAGE}` variables no longer exist: a config that still has `targets` fails
until it is migrated. A role with `build` is built as `<name>-<role>:<tag>`, and compoza
sets that service's `image`. Its `target`, `workingDirectory`, `dockerfile` and
`context` fall back to the top-level fields. A role's `environment` holds literal
values and its `secrets` names variables from the secret source; both reach only that
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.

## Recover with a known image tag

```sh
Expand All @@ -79,13 +93,17 @@ compoza status infra
```

`--tag` skips Git/builds and reuses images with the current local configuration and
currently selected secret source. A missing source checkout is allowed for `--tag`,
`targets: []`, 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.
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.

SSH stacks contain `compose.yaml`, private `.env`, declared assets and one nonsecret
`.compoza.json` lifecycle metadata file. A live host overlay may also be present.
`.compoza.json` lifecycle metadata file, which records each role's tag. The roles
override is merged into the flat `compose.yaml`. A live host overlay may also be present.
Runtime scripts and filters are sent with each CLI operation, not installed on the host.
Upload and validation failures leave deployed files unchanged. Later replacement,
Compose, routing or health failures can leave changed files or containers; recover
Expand Down
17 changes: 11 additions & 6 deletions .claude/skills/deploy/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -50,9 +50,13 @@ compoza logs infra --tail 50
- Explain the target, image transport, and proposed changes from the preview. An SSH
dry run does not stage files, build images, lock the stack, or validate the full host
candidate. Do not present it as proof that deployment will succeed.
- Built targets normally require a clean committed checkout in the resolved source directory. Do not commit changes or
add `--allow-dirty` without authorization. `targets: []` and `--tag` need no source checkout or Dockerfile.
Status, logs and lifecycle operations also work without that source directory.
- Each role with `build` normally requires a clean committed checkout of its source
repository, and is tagged with that repository's commit. Do not commit changes or add
`--allow-dirty` without authorization. Stacks whose roles build nothing, and `--tag`
deploys, need no source checkout or Dockerfile. Status, logs and lifecycle operations
also work without that source directory.
- A config that still has `targets` fails to load. Propose the migration to `roles`
(docs/configuration.md, "Migrating from 0.6.0") instead of editing it unasked.
- Once deployment is authorized, continue through verification; do not request the
same permission again. Report phase failures rather than retrying blindly.
- Success requires the final `Deployed` message and expected service state. Only
Expand Down Expand Up @@ -95,15 +99,16 @@ Never overwrite operator data to bypass an ownership error.

Upload and validation failure preserve deployed files. Replacement is in place, and
later failure can leave changed files, containers or routes. Recover using
`deploy --tag <known-image-tag>` with current local configuration and the current
credential source. There is no saved release configuration or rollback command.
`deploy --tag <known-image-tag>`, adding `--tag <role>=<tag>` where roles differ, with
the current local configuration and credential source. There is no saved release configuration or rollback command.
Do not promise automatic recovery or reversal of database changes. Lifecycle uses the
deployed files without fetching a provider. Do not remove a lock without establishing
that its owner has exited.

## Handoff

Report the destination, image tag, verification result, and URL when configured.
Report the destination, image tag (per role when they differ), verification result,
and URL when configured.
Identify any remaining action, such as publishing a content section. Do not claim
success when a phase failed or cleanup is still required.

Expand Down
31 changes: 15 additions & 16 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -80,7 +80,6 @@ my-app/
```yaml
name: hello-web # the Compose project name on the server
host: juniper # a host from hosts.yaml
targets: [] # images to build; none, because nginx is pulled as is
execution: ssh # run Compose on the server from a stack folder
composeFiles:
- compose.yaml
Expand Down Expand Up @@ -146,7 +145,7 @@ Stack deployment complete
Deployed hello-web third-party to juniper; stack folder updated.
```

The deploy writes `compose.yaml`, `.env` and a small metadata file into `stackDir`, runs `docker compose up --wait` on the server, and succeeds only once `health.url` answers. `third-party` is the image tag of an app that builds nothing; apps with `targets` are tagged with the commit.
The deploy writes `compose.yaml`, `.env` and a small metadata file into `stackDir`, runs `docker compose up --wait` on the server, and succeeds only once `health.url` answers. `third-party` is the image tag of an app that builds nothing; each role with a `build` is tagged with the commit of its repository.

### 5. Look at it

Expand All @@ -159,7 +158,7 @@ hello-web-web-1 nginx:alpine "/docker-entrypoint.…" web 2 seconds
$ compoza logs infra --tail 20 --follow
$ ssh deploy@juniper.example.com <logs deployed stack>
web-1 | 2026/11/03 10:06:20 [notice] 1#1: start worker process 40
web-1 | 192.168.158.1 - - [03/Nov/2026:10:06:21 +0000] "GET / HTTP/1.1" 200 896 "-" "curl/8.7.1" "-"
web-1 | 192.0.2.1 - - [03/Nov/2026:10:06:21 +0000] "GET / HTTP/1.1" 200 896 "-" "curl/8.7.1" "-"
```

`--follow` keeps printing new lines until you press Ctrl-C, each prefixed with the container that wrote it. To see the page itself, ask the server: `ssh deploy@juniper.example.com curl -s http://127.0.0.1:8080/`.
Expand All @@ -179,12 +178,12 @@ Deleted hello-web; data, secrets and stack files stay
### Next steps

- **Serve it on a domain** through a shared [Caddy proxy or a Cloudflare Tunnel](docs/ingress.md): configure the provider on the host, run `compoza setup-proxy juniper` once, and add `ingress` with the app's domain to `deploy.yaml`.
- **Build your own images** by listing Dockerfile `targets`; each is built, tagged with the commit and shipped to the server. See [Apps](docs/configuration.md#apps) and [Image transports](docs/configuration.md#image-transports).
- **Build your own images** by giving a Compose service a [role](docs/configuration.md#roles) with `build`; compoza builds it, tags it with the commit, ships it to the server and sets the service's `image`. Roles also carry per-service environment and secrets. See [Image transports](docs/configuration.md#image-transports).
- **Add secrets** from a dotenv file or 1Password without putting values in configuration. For 1Password, save your desktop account once with `compoza config set 1password.account "<account>"`. See [Secrets](docs/secrets.md).
- **Share hosts across machines or teammates** by keeping a `hosts.yaml` in an infrastructure repository and running `compoza hosts link <folder>`. See [Linked hosts files](docs/configuration.md#linked-hosts-files).
- **Run Compose from your machine instead** by leaving `execution` out: the default, client execution, runs Compose locally against `docker --host ssh://<host>` and needs Docker on your machine. See [Execution and image transport](#execution-and-image-transport).
- **Keep deployment configuration out of the app repository.** For `Repositories/deployments/foo/deploy.yaml`, set `workingDirectory: ../../foo`; Git checks and builds then use `Repositories/foo`, while Compose files, assets and templates stay beside `deploy.yaml`. See [separate source and deployment folders](docs/configuration.md#separate-source-and-deployment-folders).
- **Recover** from a bad deploy with `compoza deploy infra --tag <earlier-tag>`.
- **Recover** from a bad deploy with `compoza deploy infra --tag <earlier-tag>`, or `--tag <role>=<tag>` for one role.

## Execution and image transport

Expand All @@ -199,17 +198,17 @@ Two independent settings decide how a deploy runs:

## Commands

| Task | Command |
| ---------------------- | ----------------------------------------------------------------------------- |
| Check readiness | `compoza check <folder> [--json] [--secrets]` |
| Preview / deploy | `compoza deploy <folder> [--dry-run]` |
| Reuse an earlier image | `compoza deploy <folder> --tag <image-tag>` |
| Inspect services | `compoza status <folder>` |
| Read or follow logs | `compoza logs <folder> [--service <name>] [--tail <lines>] [--follow]` |
| Stop / resume | `compoza stop <folder>` / `compoza start <folder>` |
| Remove a stack | `compoza delete <folder> [--volumes]` |
| Mirror content | `compoza publish <folder> <section> <source>` |
| Set up host ingress | `compoza setup-proxy <host> [--ingress caddy\|cloudflare-tunnel] [--dry-run]` |
| Task | Command |
| -------------------- | ----------------------------------------------------------------------------- |
| Check readiness | `compoza check <folder> [--json] [--secrets]` |
| Preview / deploy | `compoza deploy <folder> [--dry-run]` |
| Reuse earlier images | `compoza deploy <folder> --tag <tag> [--tag <role>=<tag>]` |
| Inspect services | `compoza status <folder>` |
| Read or follow logs | `compoza logs <folder> [--service <name>] [--tail <lines>] [--follow]` |
| Stop / resume | `compoza stop <folder>` / `compoza start <folder>` |
| Remove a stack | `compoza delete <folder> [--volumes]` |
| Mirror content | `compoza publish <folder> <section> <source>` |
| Set up host ingress | `compoza setup-proxy <host> [--ingress caddy\|cloudflare-tunnel] [--dry-run]` |

`<folder>` holds `deploy.yaml` (or is the file itself) and defaults to the working directory, except for `publish`, which requires it. Every app command accepts `--destination <name>`, and `stop`, `start`, `delete`, `publish` and `setup-proxy` accept `--dry-run`. `delete` is also available as `down`.

Expand Down
2 changes: 1 addition & 1 deletion docs/caddy-production.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

[README](../README.md) · [Commands](commands.md) · [Ingress](ingress.md) · [Caddy templates](caddy-templates.md)

This guide covers a hardened **single-host** Caddy deployment. A host, Docker engine or network outage still interrupts every app on that host. The extension does not provide automatic failover, capacity planning, backups or an external monitoring service.
These defaults harden Caddy on a **single host**. A host, Docker engine or network outage still interrupts every app on that host. The extension does not provide automatic failover, capacity planning, backups or an external monitoring service.

## Defaults and their purpose

Expand Down
2 changes: 1 addition & 1 deletion docs/caddy-templates.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

[README](../README.md) · [Commands](commands.md) · [Configuration](configuration.md) · [Ingress](ingress.md) · [Secrets](secrets.md) · [SSH deployment](ssh-deployment.md) · [Development](development.md)

Use templates when a shared Caddyfile or an app route needs custom directives. This guide covers file locations, placeholders and overrides; see [Ingress](ingress.md#shared-caddy-proxy) for host setup and provisioning.
Use templates when a shared Caddyfile or an app route needs custom directives. Host setup and provisioning are in [Ingress](ingress.md#shared-caddy-proxy).

- [Select template sources](#select-template-sources)
- [Shared Caddyfile template](#shared-caddyfile-template)
Expand Down
Loading
Loading