From db13c67b7d3a1bb382f95ed280abdb9b3c5cf3fb Mon Sep 17 00:00:00 2001 From: Mike Sul Date: Wed, 7 Oct 2026 12:26:40 +0200 Subject: [PATCH 1/3] docs(readme): make composeapp guidance registry neutral The user guide assumed a FoundriesFactory workflow, obscuring how composectl can serve projects using other registries. Explain generic app publishing and credentials, and keep the FoundriesFactory setup discoverable through a dedicated guide. Validation was limited to source/document review because the required container images were absent and external downloads are prohibited by AGENTS.md. Signed-off-by: Mike Sul Assisted-by: Codex:GPT-6 --- README.md | 99 +++++++++++++++++++++++----------------- docs/foundriesfactory.md | 81 ++++++++++++++++++++++++++++++++ 2 files changed, 139 insertions(+), 41 deletions(-) create mode 100644 docs/foundriesfactory.md diff --git a/README.md b/README.md index e3764f4..b293e4d 100644 --- a/README.md +++ b/README.md @@ -1,40 +1,31 @@ # Utility To Manage Compose Apps -This package provides both a library and a CLI utility to manage Compose Apps built by [FoundriesFactory](https://foundries.io/). -For more detailed information about the FoundriesFactory® Compose App, please refer to [the user documentation](https://docs.foundries.io/latest/tutorials/compose-app/compose-app.html). -Essentially, a FoundriesFactory Compose App adheres to [the Compose specification](https://github.com/compose-spec/compose-spec/blob/master/spec.md). -FoundriesFactory offers mechanisms for building, packaging, and distributing Compose Apps in the form of [OCI images](https://github.com/opencontainers/image-spec/blob/main/spec.md). -This utility enables users to pull Compose Apps from the [FoundriesFactory® App Hub](https://hub.foundries.io/) and manage them on a device or a local host. -This includes tasks such as installation, running, stopping, etc. +composeapp provides a Go library and the `composectl` CLI to package, distribute, +and manage Docker Compose applications through compatible OCI container registries. +It can be used for local development, CI/CD delivery, and deploying applications +on servers or devices using a public registry or a private registry you operate. -## Installation - -### Install From APT (Debian/Ubuntu) - -1. Update the `apt` package index and install packages needed to use the fioup `apt` repository: - - ``` - sudo apt update - sudo apt install -y apt-transport-https ca-certificates curl gnupg - ``` +A Compose App packages a project defined using the +[Compose specification](https://github.com/compose-spec/compose-spec/blob/master/spec.md) +as an [OCI artifact](https://github.com/opencontainers/image-spec/blob/main/spec.md). +It contains a bundle of the Compose project and supporting files, with references to +the service images pinned by digest. `composectl` pulls and checks the app's +blobs, installs its files and images, and manages its services through Docker Compose. -1. Download the public signing key for the package repositories: +For FoundriesFactory authentication, target discovery, and APT installation, see +[Using composectl with FoundriesFactory](docs/foundriesfactory.md). - ``` - curl -L https://fioup.foundries.io/pkg/deb/dists/stable/Release.gpg | sudo gpg --dearmor -o /etc/apt/trusted.gpg.d/fioup-stable.gpg - ``` - -1. Add the appropriate `apt` repository. +## Installation - ``` - echo 'deb [signed-by=/etc/apt/trusted.gpg.d/fioup-stable.gpg] https://fioup.foundries.io/pkg/deb stable main' | sudo tee /etc/apt/sources.list.d/fioup.list - ``` +Running apps requires Docker Engine and Docker Compose v2, with the `docker` +command available on your host. -1. Install composectl +### Install A Release - ``` - sudo apt update && sudo apt install composectl - ``` +Linux binaries and Debian packages for amd64 and arm64 are available from the +[project releases](https://github.com/foundriesio/composeapp/releases). +For the Foundries-maintained APT repository, follow the +[APT installation instructions](docs/foundriesfactory.md#install-from-apt-debianubuntu). ### Install The Development Version (from source) @@ -43,7 +34,8 @@ git clone https://github.com/foundriesio/composeapp.git ``` ```commandline -cd composeapp && make +cd composeapp +./dev-shell.sh make ``` As a result, the `composectl` binary should appear in the `./bin` directory. @@ -65,25 +57,50 @@ The Docker engine store is determined by the Docker daemon instance that the uti By default, the utility talks to the Docker daemon through `unix:///var/run/docker.sock`, which in turn stores image layers and containers data under `/var/lib/docker`. -The Docker daemon socket can be specified in the `--host/-H` parameter. -Also, the `composectl` utility respects `DOCKER_HOST` environment variable, which is another way to specify the Docker daemon socket. +Set `DOCKER_HOST` to select a different daemon for both `composectl` and the +Docker Compose commands it launches. The `--host/-H` parameter selects the daemon +for operations using the Docker API. ### Authentication -Prior to communicating with the [FoundriesFactory App Hub](https://hub.foundries.io/) authentication should be set. -It can be done either by logging at the hub `docker login hub.foundries.io -u "doesnotmatter" -p ` -or setting the Docker credential helper by running `fioctl configure-docker` command. +For a registry that requires authentication, log in using its hostname and the +credentials or token provided by its operator: + +```sh +docker login registry.example.com +``` + +`composectl` uses Docker's credential configuration, including configured +credential helpers. Back up your Docker configuration (usually +`~/.docker/config.json`) before changing it. Configure credentials for the app +registry and any other registries hosting its service images. Public repositories +may allow pulling without authentication. + +### Publishing An App + +If you already have a published app URI, proceed to [Pulling App](#pulling-app). +Otherwise, run the following from your project directory, containing +`docker-compose.yml` and its supporting files: + +```sh +composectl publish registry.example.com/apps/myapp:1.0 +``` -The `FoundriesFactory token` can be obtained at . +Replace `registry.example.com/apps/myapp:1.0` with a repository and tag you can +write to. Each service must reference an image already published in a registry, +using a tag or digest. Publishing resolves service image references to digests +and uploads the Compose bundle; it does not build or upload your service images. +Use `.composeappignores` to exclude files from the bundle. -The both methods updates a Docker configuration file on a local host (e.g. `~/.docker/config.json`). -Make sure to backup it before running the aforementioned commands. +The command prints the app URI as +`registry.example.com/apps/myapp@sha256:`. Save this URI to identify the +exact app version when pulling it on another host. ### Pulling App -Once the authentication is set, Compose App can be pulled for the hub. At first, the App's URI should be found. -To do so, a user can run `fioctl targets list` and `fioctl targets show compose-app `. -The last command outputs the target's app URI. +Use the app URI from `composectl publish` or from the app's publisher. It must +include the manifest digest, for example +`registry.example.com/apps/myapp@sha256:`, rather than just a tag. ```commandline composectl pull [] diff --git a/docs/foundriesfactory.md b/docs/foundriesfactory.md new file mode 100644 index 0000000..83bafcb --- /dev/null +++ b/docs/foundriesfactory.md @@ -0,0 +1,81 @@ +# Using composectl with FoundriesFactory + +[FoundriesFactory](https://foundries.io/) builds and distributes Compose Apps +through its App Hub. `composectl` can pull these apps and manage them on a device +or local host using the same workflow described in the [main documentation](../README.md). + +For details about creating Compose Apps in FoundriesFactory, see the +[FoundriesFactory Compose App documentation](https://docs.foundries.io/latest/tutorials/compose-app/compose-app.html). + +## Install From APT (Debian/Ubuntu) + +Foundries maintains an APT repository containing the `composectl` package. +These packages can be used with any compatible registry. + +1. Update the package index and install the prerequisites: + + ```sh + sudo apt update + sudo apt install -y apt-transport-https ca-certificates curl gnupg + ``` + +2. Download the public signing key for the repository: + + ```sh + curl -L https://fioup.foundries.io/pkg/deb/dists/stable/Release.gpg | sudo gpg --dearmor -o /etc/apt/trusted.gpg.d/fioup-stable.gpg + ``` + +3. Add the repository: + + ```sh + echo 'deb [signed-by=/etc/apt/trusted.gpg.d/fioup-stable.gpg] https://fioup.foundries.io/pkg/deb stable main' | sudo tee /etc/apt/sources.list.d/fioup.list + ``` + +4. Install `composectl`: + + ```sh + sudo apt update && sudo apt install composectl + ``` + +## Authenticate To The App Hub + +Before pulling private apps from [the App Hub](https://hub.foundries.io/), +configure authentication using either a FoundriesFactory token or the Docker +credential helper provided by `fioctl`. + +You can obtain a token from the +[FoundriesFactory token settings](https://app.foundries.io/settings/tokens/). +Log in with the following command and enter the token at the password prompt: + +```sh +docker login hub.foundries.io -u doesnotmatter +``` + +Alternatively, configure the credential helper: + +```sh +fioctl configure-docker +``` + +Both methods update your Docker configuration, usually `~/.docker/config.json`. +Back it up before changing it. `composectl` uses this configuration to authenticate +to the App Hub. + +## Find And Pull An App + +List your factory's targets and inspect an app in a selected target: + +```sh +fioctl targets list +fioctl targets show compose-app +``` + +The second command outputs the app URI, including its manifest digest. Use it +to pull the app: + +```sh +composectl pull +``` + +Then follow the [app management instructions](../README.md#managing-app) to check, +install, run, stop, uninstall, or remove it. From 328a0e1bc2388919ef32bc12ae9e833ff69b81d5 Mon Sep 17 00:00:00 2001 From: Mike Sul Date: Wed, 7 Oct 2026 13:11:19 +0200 Subject: [PATCH 2/3] docs(readme): keep apt installation in generic guide The APT package works independently of FoundriesFactory. Hosting its instructions in the Factory guide incorrectly suggested that installation required that platform. Keep installation in the main guide and link to it from the FoundriesFactory documentation. Signed-off-by: Mike Sul Assisted-by: Codex:GPT-6 --- README.md | 34 +++++++++++++++++++++++++++++++--- docs/foundriesfactory.md | 30 +----------------------------- 2 files changed, 32 insertions(+), 32 deletions(-) diff --git a/README.md b/README.md index b293e4d..6503a99 100644 --- a/README.md +++ b/README.md @@ -12,7 +12,7 @@ It contains a bundle of the Compose project and supporting files, with reference the service images pinned by digest. `composectl` pulls and checks the app's blobs, installs its files and images, and manages its services through Docker Compose. -For FoundriesFactory authentication, target discovery, and APT installation, see +For FoundriesFactory authentication and target discovery, see [Using composectl with FoundriesFactory](docs/foundriesfactory.md). ## Installation @@ -20,12 +20,40 @@ For FoundriesFactory authentication, target discovery, and APT installation, see Running apps requires Docker Engine and Docker Compose v2, with the `docker` command available on your host. +### Install From APT (Debian/Ubuntu) + +Foundries maintains an APT repository containing the `composectl` package. +These packages can be used with any compatible registry. + +1. Update the package index and install the prerequisites: + + ```sh + sudo apt update + sudo apt install -y apt-transport-https ca-certificates curl gnupg + ``` + +2. Download the public signing key for the repository: + + ```sh + curl -L https://fioup.foundries.io/pkg/deb/dists/stable/Release.gpg | sudo gpg --dearmor -o /etc/apt/trusted.gpg.d/fioup-stable.gpg + ``` + +3. Add the repository: + + ```sh + echo 'deb [signed-by=/etc/apt/trusted.gpg.d/fioup-stable.gpg] https://fioup.foundries.io/pkg/deb stable main' | sudo tee /etc/apt/sources.list.d/fioup.list + ``` + +4. Install `composectl`: + + ```sh + sudo apt update && sudo apt install composectl + ``` + ### Install A Release Linux binaries and Debian packages for amd64 and arm64 are available from the [project releases](https://github.com/foundriesio/composeapp/releases). -For the Foundries-maintained APT repository, follow the -[APT installation instructions](docs/foundriesfactory.md#install-from-apt-debianubuntu). ### Install The Development Version (from source) diff --git a/docs/foundriesfactory.md b/docs/foundriesfactory.md index 83bafcb..fe425c2 100644 --- a/docs/foundriesfactory.md +++ b/docs/foundriesfactory.md @@ -7,35 +7,7 @@ or local host using the same workflow described in the [main documentation](../R For details about creating Compose Apps in FoundriesFactory, see the [FoundriesFactory Compose App documentation](https://docs.foundries.io/latest/tutorials/compose-app/compose-app.html). -## Install From APT (Debian/Ubuntu) - -Foundries maintains an APT repository containing the `composectl` package. -These packages can be used with any compatible registry. - -1. Update the package index and install the prerequisites: - - ```sh - sudo apt update - sudo apt install -y apt-transport-https ca-certificates curl gnupg - ``` - -2. Download the public signing key for the repository: - - ```sh - curl -L https://fioup.foundries.io/pkg/deb/dists/stable/Release.gpg | sudo gpg --dearmor -o /etc/apt/trusted.gpg.d/fioup-stable.gpg - ``` - -3. Add the repository: - - ```sh - echo 'deb [signed-by=/etc/apt/trusted.gpg.d/fioup-stable.gpg] https://fioup.foundries.io/pkg/deb stable main' | sudo tee /etc/apt/sources.list.d/fioup.list - ``` - -4. Install `composectl`: - - ```sh - sudo apt update && sudo apt install composectl - ``` +Install `composectl` using the [installation instructions](../README.md#installation). ## Authenticate To The App Hub From 1f50096846097a80072fbb34e7ef830a6e8398f3 Mon Sep 17 00:00:00 2001 From: Mike Sul Date: Wed, 7 Oct 2026 19:20:30 +0200 Subject: [PATCH 3/3] docs(readme): clarify app storage and runtime directories The store and project directory descriptions were easy to confuse. Explain their roles and identify the stored image objects so readers can distinguish downloaded blobs from the extracted files Docker Compose uses to run an installed app. Signed-off-by: Mike Sul Assisted-by: Codex:gpt-6 --- README.md | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 6503a99..6e5a20e 100644 --- a/README.md +++ b/README.md @@ -74,8 +74,12 @@ As a result, the `composectl` binary should appear in the `./bin` directory. Compose Apps' data are spread across three locations on a local file system: -1. The App store directory — all app blobs are stored in this location, by default it is `~/.composeapps/store`. -2. The App project or compose directory — where the Docker compose YAML along with its complementary files are stored, by default in `~/.composeapps/projects`. +1. The App store directory — stores downloaded app blobs, including the Compose + bundle and service image content (manifests, configs, image layer blobs). + Defaults to `~/.composeapps/store`. +2. The App project directory (Compose runtime directory) — contains each installed + app's extracted Compose YAML and supporting files. Docker Compose runs from + the app's subdirectory, by default `~/.composeapps/projects/`. 3. The Docker engine store — a few sub-directories in the Docker engine data root, by default in `/var/lib/docker`. ### Configuration