Update doc to make composectl registry neutral

README.md

@@ -1,49 +1,69 @@
 # 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.
+
+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.
+
+For FoundriesFactory authentication and target discovery, see
+[Using composectl with FoundriesFactory](docs/foundriesfactory.md).
 
 ## Installation
 
+Running apps requires Docker Engine and Docker Compose v2, with the `docker`
+command available on your host.
+
 ### Install From APT (Debian/Ubuntu)
 
-1. Update the `apt` package index and install packages needed to use the fioup `apt` repository:
+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
    ```
 
-1. Download the public signing key for the package repositories:
+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
    ```
 
-1. Add the appropriate `apt` repository.
+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
    ```
 
-1. Install composectl
+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).
+
 ### Install The Development Version (from source)
 
 ```commandline
 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.
@@ -54,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/<app name>`.
 3. The Docker engine store — a few sub-directories in the Docker engine data root, by default in `/var/lib/docker`.
 
 ### Configuration
@@ -65,25 +89,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 <FoundriesFactory token>`
-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 <https://app.foundries.io/settings/tokens/>.
+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:<digest>`. 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 <version> <app name>`.
-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:<digest>`, rather than just a tag.
 
 ```commandline
 composectl pull <app URI> [<app URI>]

docs/foundriesfactory.md

@@ -0,0 +1,53 @@
+# 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 `composectl` using the [installation instructions](../README.md#installation).
+
+## 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 <version> <app name>
+```
+
+The second command outputs the app URI, including its manifest digest. Use it
+to pull the app:
+
+```sh
+composectl pull <app URI>
+```
+
+Then follow the [app management instructions](../README.md#managing-app) to check,
+install, run, stop, uninstall, or remove it.