diff --git a/README.md b/README.md index e3764f4..6e5a20e 100644 --- a/README.md +++ b/README.md @@ -1,41 +1,60 @@ # 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 @@ -43,7 +62,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. @@ -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/`. 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 ` -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..fe425c2 --- /dev/null +++ b/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 +``` + +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.