.dockerignore

@@ -0,0 +1,8 @@
+*.swo
+*.swp
+.dockerignore
+Dockerfile
+abra
+dist
+kadabra
+tags

.drone.yml

@@ -1,49 +1,118 @@
 ---
 kind: pipeline
-name: linters
+name: coopcloud.tech/abra
 steps:
-  - name: run shellcheck
+  - name: make check
-    image: koalaman/shellcheck-alpine:v0.7.1
+    image: golang:1.24
     commands:
-      - shellcheck abra
+      - make check
-      - shellcheck bin/*.sh
 
-  - name: run flake8
+  - name: make test
-    image: alpine/flake8:3.9.0
+    image: golang:1.24
+    environment:
+      CATL_URL: https://git.coopcloud.tech/toolshed/recipes-catalogue-json.git
     commands:
-      - flake8 --max-line-length 100 bin/app-json.py
+      - mkdir -p $HOME/.abra
+      - git clone $CATL_URL $HOME/.abra/catalogue
+      - make test
+    depends_on:
+      - make check
 
-  - name: run unit tests
+  - name: fetch
-    image: decentral1se/docker-dind-bats-kcov
+    image: docker:git
     commands:
-      - bats tests
+      - git fetch --tags
-
+    depends_on:
-  - name: collect code coverage
+      - make check
-    failure: ignore # until we fix this
+      - make test
-    image: decentral1se/docker-dind-bats-kcov
-    commands:
-      - kcov . bats tests || true
-
-  - name: send code coverage report to codecov
-    failure: ignore # until we fix this
-    image: plugins/codecov
-    settings:
-      token:
-        from_secret: codecov_token
-        required: true
-
-  - name: notify rocket chat
-    image: plugins/slack
-    settings:
-      webhook:
-        from_secret: rc_builds_url
-      username: comradebritney
-      channel: "internal.builds"
-      template: "{{repo.owner}}/{{repo.name}} build failed: {{build.link}}"
     when:
-      status:
+      event: tag
-        - failure
+
+  - name: release
+    image: goreleaser/goreleaser:v2.5.1
+    environment:
+      GITEA_TOKEN:
+        from_secret: goreleaser_gitea_token
+    volumes:
+      - name: deps
+        path: /go
+    commands:
+      - goreleaser release
+    depends_on:
+      - fetch
+    when:
+      event: tag
+
+  - name: publish image
+    image: plugins/docker
+    settings:
+      auto_tag: true
+      username: abra-bot
+      password:
+        from_secret: git_coopcloud_tech_token_abra_bot
+      repo: git.coopcloud.tech/toolshed/abra
+      tags: dev
+      registry: git.coopcloud.tech
+    when:
+      branch:
+        - main
+    depends_on:
+      - make check
+      - make test
+
+  - name: on-demand integration test
+    image: appleboy/drone-ssh
+    settings:
+      host:
+        - int.coopcloud.tech
+      username: abra
+      key:
+        from_secret: abra_int_private_key
+      port: 22
+      command_timeout: 60m
+      script_stop: true
+      request_pty: true
+      script:
+        - |
+          wget https://git.coopcloud.tech/toolshed/abra/raw/branch/main/scripts/tests/run-ci-int -O run-ci-int
+          chmod +x run-ci-int
+          sh run-ci-int
+    when:
+      ref:
+        - refs/heads/int-*
+    depends_on:
+      - make check
+      - make test
+
+  - name: nightly integration test
+    image: appleboy/drone-ssh
+    settings:
+      host:
+        - int.coopcloud.tech
+      username: abra
+      key:
+        from_secret: abra_int_private_key
+      port: 22
+      command_timeout: 60m
+      script_stop: true
+      request_pty: true
+      script:
+        - |
+          wget https://git.coopcloud.tech/toolshed/abra/raw/branch/main/scripts/tests/run-ci-int -O run-ci-int
+          chmod +x run-ci-int
+          sh run-ci-int
+    when:
+      event:
+        - cron:
+      cron:
+        # @daily https://docs.drone.io/cron/
+        - integration 
+
+volumes:
+  - name: deps
+    temp: {}
 
 trigger:
-  branch:
+  action:
-    - main
+    exclude:
+      - synchronized

.envrc.sample

@@ -0,0 +1,7 @@
+# integration test suite
+# export ABRA_DIR="$HOME/.abra_test"
+# export ABRA_TEST_DOMAIN=test.example.com
+# export ABRA_CI=1
+
+# release automation
+# export GITEA_TOKEN=

.gitignore

@@ -1,2 +1,8 @@
-/.venv
+*fmtcoverage.html
-coverage/
+.e2e.env
+.envrc
+.vscode/
+/abra
+/kadabra
+dist/
+tests/integration/.bats

.goreleaser.yml

@@ -0,0 +1,76 @@
+---
+gitea_urls:
+  api: https://git.coopcloud.tech/api/v1
+  download: https://git.coopcloud.tech/
+  skip_tls_verify: false
+
+before:
+  hooks:
+    - go mod tidy
+
+builds:
+  - id: abra
+    binary: abra
+    dir: cmd/abra
+    env:
+      - CGO_ENABLED=0
+    goos:
+      - linux
+      - darwin
+    goarch:
+      - 386
+      - amd64
+      - arm
+      - arm64
+    goarm:
+      - 5
+      - 6
+      - 7
+    ldflags:
+      - "-X 'main.Commit={{ .Commit }}'"
+      - "-X 'main.Version={{ .Version }}'"
+      - "-s"
+      - "-w"
+
+  - id: kadabra
+    binary: kadabra
+    dir: cmd/kadabra
+    env:
+      - CGO_ENABLED=0
+    goos:
+      - linux
+      - darwin
+    goarch:
+      - 386
+      - amd64
+      - arm
+      - arm64
+    goarm:
+      - 5
+      - 6
+      - 7
+    gcflags:
+      - "all=-l -B"
+    ldflags:
+      - "-X 'main.Commit={{ .Commit }}'"
+      - "-X 'main.Version={{ .Version }}'"
+      - "-s"
+      - "-w"
+
+checksum:
+  name_template: "checksums.txt"
+
+snapshot:
+  name_template: "{{ incpatch .Version }}-next"
+
+changelog:
+  sort: desc
+  filters:
+    exclude:
+      - "^Merge"
+      - "^Revert"
+      - "^WIP:"
+      - "^chore(deps):"
+      - "^style:"
+      - "^test:"
+      - "^tests:"

AUTHORS.md

@@ -0,0 +1,22 @@
+# authors
+
+> If you're looking at this and you hack on `abra` and you're not listed here,
+> please do add yourself! This is a community project, let's show some 💞
+
+- 3wordchant
+- ammaratef45
+- cassowary
+- codegod100
+- decentral1se
+- fauno
+- frando
+- kawaiipunk
+- knoflook
+- moritz
+- p4u1
+- rix
+- roxxers
+- vera
+- yksflip
+- basebuilder
+- mayel

CHANGELOG.md

@@ -1,132 +0,0 @@
-> 🔥 🔥 🔥 Please note, while we are still in
-> [public alpha](https://docs.cloud.autonomic.zone/roadmap/), the `abra` release
-> versioning scheme is not following [semver](https://semver.org/) conventions
-> because we are still in the exploratory phases of building this tool. Please
-> read the changes before upgrading your `abra` installation as there are
-> **most likely** breaking changes coming each release. Sorry for any
-> inconvenience caused, we're working hard to make this tool stable. Semver
-> will be respected when we reach public beta. 🔥 🔥 🔥
-
-# abra x.x.x (UNRELEASED)
-
-# abra 0.7.3 (2021-04-28)
-
-- Only check for pw(q)gen if we're actually trying to use them ([#147](https://git.autonomic.zone/coop-cloud/abra/issues/147))
-- Use apps.coopcloud.tech for app data hosting & download ([75bd599](https://git.autonomic.zone/coop-cloud/abra/commit/75bd599))
-- Choose latest commit messages for new tags ([#144](https://git.autonomic.zone/coop-cloud/abra/issues/144))
-- Handle recipes without an `app` service in `recipe .. release` ([#151](https://git.autonomic.zone/coop-cloud/abra/issues/151))
-
-# abra 0.7.2 (2021-04-07)
-
-- Fix installation script development installs (again! Thanks Bash!) ([4747d9b7](https://git.autonomic.zone/coop-cloud/abra/commit/4747d9b7fb5fba914f210b6570bfe2db0b53da23))
-
-# abra 0.7.1 (2021-04-07)
-
-- Fix installation script development installs ([8f2fadb3c](https://git.autonomic.zone/coop-cloud/abra/commit/8f2fadb3c43c5915520f5ea531ea3815c2ba8531))
-
-# abra 0.7.0 (2021-04-07)
-
-- Add `--force` to the `deploy` command to allow overriding deployment logic ([#105](https://git.autonomic.zone/coop-cloud/abra/issues/105))
-- Handle undeployed apps in version summaries when deploying ([#104](https://git.autonomic.zone/coop-cloud/abra/issues/104))
-- Add `--force` to `undeploy` command ([e5e98d5](https://git.autonomic.zone/coop-cloud/abra/commit/e5e98d5))
-- Rename "app type" back to "stack" in the deployment overview ([54b6acc](https://git.autonomic.zone/coop-cloud/abra/commit/54b6acc))
-- Show context connection details on `abra server ls` ([#110](https://git.autonomic.zone/coop-cloud/abra/issues/110))
-- Allow to debug the SSH connection details on swarm init ([#109](https://git.autonomic.zone/coop-cloud/abra/issues/109))
-- Show correct status for apps deployed on servers with missing context ([#99](https://git.autonomic.zone/coop-cloud/abra/issues/99))
-- Search for subcommands in descending order of how many components there are ([#108](https://git.autonomic.zone/coop-cloud/abra/issues/108))
-- Add specific app version checking command (`abra app <app> version`) ([#108](https://git.autonomic.zone/coop-cloud/abra/issues/108))
-- Add docker version check (guestimating < v19 is a bad idea) ([#15](https://git.autonomic.zone/coop-cloud/abra/issues/15))
-- Fix git branch handling when not passing `-b <branch>` ([#122](https://git.autonomic.zone/coop-cloud/abra/issues/122))
-- Add work-around to correctly git clone non-master default branch app repositories ([#122](https://git.autonomic.zone/coop-cloud/abra/issues/122))
-- Replace `--force` (except for the `deploy` command) with a global `--no-prompt` for avoiding interactive questions ([#118](https://git.autonomic.zone/coop-cloud/abra/issues/118))
-- Use [docker-stack-wait-deploy](https://github.com/vitalets/docker-stack-wait-deploy) inspired logic to deploy apps ([#116](https://git.autonomic.zone/coop-cloud/abra/issues/116))
-- Add a domain polling check when deploying apps ([#113](https://git.autonomic.zone/coop-cloud/abra/issues/113))
-- Recognise when apps are already undeployed with `abra app <app> undeploy` ([#123](https://git.autonomic.zone/coop-cloud/abra/issues/123))
-- Add `abra doctor` command to help diagnose setup issues ([#119](https://git.autonomic.zone/coop-cloud/abra/issues/119))
-- Add apps version and feature catalogue generation script ([#121](https://git.autonomic.zone/coop-cloud/abra/issues/121))
-- New `--skip-version-check` option to `deploy` ([df4e504](https://git.autonomic.zone/coop-cloud/abra/commit/df4e504))
-- Look up local available version from compose files instead of `abra.sh` ([#131](https://git.autonomic.zone/coop-cloud/abra/issues/131))
-- Improve domain polling logging and allow to skip the check altogether with `--no-domain-poll` ([#140](https://git.autonomic.zone/coop-cloud/abra/issues/140), [#141](https://git.autonomic.zone/coop-cloud/abra/issues/141))
-- Support `ABRA_DIR` in the installer script ([4e94a424e94a42](https://git.autonomic.zone/coop-cloud/abra/commit/4e94a424e94a42))
-- Support [abra-hetzner](https://git.autonomic.zone/coop-cloud/abra-hetzner) plugin ([#88](https://git.autonomic.zone/coop-cloud/abra/issues/88))
-
-# abra 0.6.0 (2021-03-17)
-
-- Show version and digest of app if labelled ([98e674b8e8](https://git.autonomic.zone/coop-cloud/abra/commit/98e674b8e83458a83dcbf331e8e34c7188559c4a))
-- Implement basic version checking on deployment ([#82](https://git.autonomic.zone/coop-cloud/abra/issues/82))
-- New `app-catalogue.sh` script to auto-generate app list for documentation ([f163d4b](https://git.autonomic.zone/coop-cloud/abra/commit/f163d4b0fa920232e9d995a22d20fe78b174b3a9))
-- Support app service rollbacks with `abra <app> rollback <service>` ([#76](https://git.autonomic.zone/coop-cloud/abra/issues/76))
-- Detect when latest version is deployed and perform a no-op ([#87](https://git.autonomic.zone/coop-cloud/abra/issues/87))
-- Allow cloning of app repos with different main branches using `-b, --branch=<branch>` ([#80](https://git.autonomic.zone/coop-cloud/abra/issues/80))
-- Protect against lengthy app names which gives Docker trouble later on ([#83](https://git.autonomic.zone/coop-cloud/abra/issues/83))
-- Support removal of secrets and volumes when `rm`'ing apps ([#44](https://git.autonomic.zone/coop-cloud/abra/issues/44))
-- Always choose the default IPv4 address with `abra server <host> init` ([#91](https://git.autonomic.zone/coop-cloud/abra/issues/91))
-- Add `--type=<type>` filtering option to `abra <app> ls` ([0828189](https://git.autonomic.zone/coop-cloud/abra/commit/0828189))
-- Check for bash 4+ ([#96](https://git.autonomic.zone/coop-cloud/abra/commit/0828189))
-- Add `--dev` option to installer using `git clone` ([88d2a75](https://git.autonomic.zone/coop-cloud/abra/commit/88d2a75))
-- Support `--dev` on the `abra upgrade` command also ([bcc15ec](https://git.autonomic.zone/coop-cloud/abra/commit/bcc15ec))
-- Vendor [yq](https://github.com/mikefarah/yq/releases) automatically ([3b59adf](https://git.autonomic.zone/coop-cloud/abra/commit/3b59adf))
-- Extend version handling logic to support all underlying services ([#90](https://git.autonomic.zone/coop-cloud/abra/issues/90))
-- Fix development installation script symlink issue ([#98](https://git.autonomic.zone/coop-cloud/abra/issues/98))
-- Add `app-version.sh` script to help packagers version apps ([28618bd](https://git.autonomic.zone/coop-cloud/abra/commit/28618bd))
-- Add git digest to `abra version` output ([8b41416](https://git.autonomic.zone/coop-cloud/abra/commit/8b41416))
-
-# abra 0.5.0 (2021-03-01)
-
-- `secret auto` merged into `secret generate` and `app new --auto` is now `app new --secrets` ([#64](https://git.autonomic.zone/coop-cloud/abra/pulls/64))
-- Avoid outputting length during secret generation when not in use ([#67](https://git.autonomic.zone/coop-cloud/abra/issues/67))
-- Support graceful failure when missing secret generation commands ([44d3ac3](https://git.autonomic.zone/coop-cloud/abra/commit/44d3ac3a1cb86edc9b9e91eea1a00e70eae14965))
-- Fix secret detection when using new `.env` file format in apps ([5532452](https://git.autonomic.zone/coop-cloud/abra/commit/55324524ca77141666ffe6cc41b62cc71cf89ace))
-- Support choosing an `$EDITOR` when editing configs ([29cc392](https://git.autonomic.zone/coop-cloud/abra/commit/29cc392dff3e93e48e0e2edd3ce11b405c66a95a))
-- "server" shell completion fixed ([8839bd4](https://git.autonomic.zone/coop-cloud/abra/commit/8839bd45951d00dccf4ef81ece445bcc49e13ee6))
-- Drop `multilogs` command ([#56](https://git.autonomic.zone/coop-cloud/abra/pulls/56))
-- Remove `server use` command ([#51](https://git.autonomic.zone/coop-cloud/abra/issues/51))
-- `new <app>` becomes `new <type>` ([#48](https://git.autonomic.zone/coop-cloud/abra/issues/48))
-- `check` is run on `deploy` now and configurable ([77ba565](https://git.autonomic.zone/coop-cloud/abra/commit/77ba5652b2fe15820f5edfa0f642636f7b8eae7e))
-- App configurations are always updated now ([#42](https://git.autonomic.zone/coop-cloud/abra/issues/42))
-- We use docker format `.env` files (no "export" syntax) from now now ([#55](https://git.autonomic.zone/coop-cloud/abra/pulls/55))
-- Rename `<domain>` option to `<app>` and `APP` variable to `TYPE`, see ([#47](https://git.autonomic.zone/coop-cloud/abra/issues/47))
-- Use Docker-in-Docker (dind), and `dind-bats-kcov` Docker image, for `make test` ([1600b62](https://git.autonomic.zone/coop-cloud/abra/commit/1600b6277fbbffc4c6de1e4ba799c7bbe72ec6a0))
-- Add built-in documentation using `abra help <subcommand>...`, see ([#50](https://git.autonomic.zone/coop-cloud/abra/issues/50))
-- `version` subcommand ([e6b24fe](https://git.autonomic.zone/coop-cloud/abra/commit/e6b24fe))
-- Use `# length=x` comments to generate passwords with `pwgen` and drop `KEY`/`PASSWORD` logic ([#68](https://git.autonomic.zone/coop-cloud/abra/issues/68))
-- Global `--skip-update|-U` / `--skip-check|-C` options to make things quicker ([37e8b00](https://git.autonomic.zone/coop-cloud/abra/commit/37e8b00))
-- `app backup` and `app restore` commands; requires per-app definition ([#70](https://git.autonomic.zone/coop-cloud/abra/issues/70))
-- Rename per-type `abra-commands.sh` to `abra.sh`, and include config versions as type-level instead of app-level config ([#43](https://git.autonomic.zone/coop-cloud/abra/issues/43))
-- Show per-subcommand help by adding `-h/--help` to a command line ([#38](https://git.autonomic.zone/coop-cloud/abra/issues/78))
-
-# abra 0.4.1 (2020-12-24)
-
-- Bug-fixes on `app ls --status` & custom commands
-- Add `app ls --server=...` and alias
-
-# abra 0.4.0 (2020-12-24)
-
-- New command-line interface based on docopt
-- `~/.abra` directory instead of expecting local `.env` files
-- Integration tests & code coverage
-
-# abra 0.3.1 (2020-09-27)
-
-- Fix installer version
-
-# abra 0.3.0 (2020-09-27)
-
-- Add multilogs stack logs implementation ([#8](https://git.autonomic.zone/compose-stacks/abra/issues/8))
-- Add beginnings of "monorepo" functionality
-
-# abra 0.2.0 (2020-09-24)
-
-- Prepare for swarm install script using script.d ([#12](https://git.autonomic.zone/compose-stacks/planning/issues/12))
-
-# abra 0.1.2 (2020-09-22)
-
-- Add upgrade command ([#10](https://git.autonomic.zone/autonomic-cooperative/abra/issues/10))
-
-# abra 0.1.1 (2020-09-22)
-
-- Add installer script ([#9](https://git.autonomic.zone/autonomic-cooperative/abra/issues/9))
-
-# abra 0.1.0 (2020-09-22)
-
-- Initial pre-alpha release

Dockerfile

@@ -0,0 +1,30 @@
+# Build image
+FROM golang:1.24-alpine AS build
+
+ENV GOPRIVATE=coopcloud.tech
+
+RUN apk add --no-cache \
+  gcc \
+  git \
+  make \
+  musl-dev
+
+COPY . /app
+
+WORKDIR /app
+
+RUN CGO_ENABLED=0 make build
+
+# Release image ("slim")
+FROM alpine:3.19.1
+
+RUN apk add --no-cache \
+  ca-certificates \
+  git \
+  openssh
+
+RUN update-ca-certificates
+
+COPY --from=build /app/abra /abra
+
+ENTRYPOINT ["/abra"]

LICENSE

@@ -0,0 +1,15 @@
+Abra: The Co-op Cloud utility belt
+Copyright (C) 2022 Co-op Cloud <helo@coopcloud.tech>
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation, either version 3 of the License, or
+(at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with this program.  If not, see <https://www.gnu.org/licenses/>.

Makefile

@@ -0,0 +1,61 @@
+ABRA         := ./cmd/abra
+KADABRA      := ./cmd/kadabra
+COMMIT       := $(shell git rev-list -1 HEAD)
+GOPATH       := $(shell go env GOPATH)
+GOVERSION    := 1.24
+LDFLAGS      := "-X 'main.Commit=$(COMMIT)'"
+DIST_LDFLAGS := $(LDFLAGS)" -s -w"
+GCFLAGS      := "all=-l -B"
+
+export GOPRIVATE=coopcloud.tech
+
+# NOTE(d1): default `make` optimised for Abra hacking
+all: format check build-abra test
+
+run-abra:
+	@go run -gcflags=$(GCFLAGS) -ldflags=$(LDFLAGS) $(ABRA)
+
+run-kadabra:
+	@go run -gcflags=$(GCFLAGS) -ldflags=$(LDFLAGS) $(KADABRA)
+
+install-abra:
+	@go install -gcflags=$(GCFLAGS) -ldflags=$(LDFLAGS) $(ABRA)
+
+install-kadabra:
+	@go install -gcflags=$(GCFLAGS) -ldflags=$(LDFLAGS) $(KADABRA)
+
+install: install-abra install-kadabra
+
+build-abra:
+	@go build -v -gcflags=$(GCFLAGS) -ldflags=$(DIST_LDFLAGS) $(ABRA)
+
+build-kadabra:
+	@go build -v -gcflags=$(GCFLAGS) -ldflags=$(DIST_LDFLAGS) $(KADABRA)
+
+build: build-abra build-kadabra
+
+build-docker-abra:
+	@docker run -it -v $(PWD):/abra golang:$(GOVERSION) \
+		bash -c 'cd /abra; ./scripts/docker/build.sh'
+
+build-docker: build-docker-abra
+
+clean:
+	@rm '$(GOPATH)/bin/abra'
+	@rm '$(GOPATH)/bin/kadabra'
+
+format:
+	@gofmt -s -w $$(find . -type f -name '*.go' | grep -v "/vendor/")
+
+check:
+	@test -z $$(gofmt -l $$(find . -type f -name '*.go' | grep -v "/vendor/")) || \
+	(echo "gofmt: formatting issue - run 'make format' to resolve" && exit 1)
+
+test:
+	@go test ./... -cover -v
+
+loc:
+	@find . -name "*.go" | xargs wc -l
+
+deps:
+	@go get -t -u ./...

README.md

@@ -1,93 +1,13 @@
-# abra
+# `abra`
 
-[![Build Status](https://drone.autonomic.zone/api/badges/coop-cloud/abra/status.svg)](https://drone.autonomic.zone/coop-cloud/abra)
+[![Build Status](https://build.coopcloud.tech/api/badges/toolshed/abra/status.svg?ref=refs/heads/main)](https://build.coopcloud.tech/toolshed/abra)
-[![codecov](https://codecov.io/gh/Autonomic-Cooperative/abra/branch/main/graph/badge.svg?token=aX3I5NMRsj)](undefined)
+[![Go Report Card](https://goreportcard.com/badge/git.coopcloud.tech/toolshed/abra)](https://goreportcard.com/report/git.coopcloud.tech/toolshed/abra)
+[![Go Reference](https://pkg.go.dev/badge/coopcloud.tech/abra.svg)](https://pkg.go.dev/coopcloud.tech/abra)
 
-> https://coopcloud.tech
+The Co-op Cloud utility belt 🎩🐇
 
-The cooperative cloud utility belt 🎩🐇
+<a href="https://github.com/egonelbre/gophers"><img align="right" width="150" src="https://github.com/egonelbre/gophers/raw/master/.thumb/sketch/adventure/poking-fire.png"/></a>
 
-`abra` is a command-line tool for managing your own [Co-op Cloud](https://coopcloud.tech). It can provision new servers, create applications, deploy them, run backup and restore operations and a whole lot of other things. It is the go-to tool for day-to-day operations when managing a Co-op Cloud instance.
+`abra` is the flagship client & command-line tool for Co-op Cloud. It has been developed specifically for the purpose of making the day-to-day operations of [operators](https://docs.coopcloud.tech/operators/) and [maintainers](https://docs.coopcloud.tech/maintainers/) pleasant & convenient. It is libre software, written in [Go](https://go.dev) and maintained and extended by the community 💖
 
-## Change log
+Please see [docs.coopcloud.tech/abra](https://docs.coopcloud.tech/abra) for help on install, upgrade, hacking, troubleshooting & more!
-
-> 🔥 🔥 🔥 Please note, while we are still in [public
-> alpha](https://docs.coopcloud.tech/roadmap/), the `abra` release
-> versioning scheme is not following [semver](https://semver.org/) conventions
-> because we are still in the exploratory phases of building this tool. Please
-> read the changes before upgrading your `abra` installation as there are
-> **most likely** breaking changes coming each release. Sorry for any
-> inconvenience caused, we're working hard to make this tool stable. Semver
-> will be respected when we reach public beta. 🔥 🔥 🔥
-
-See [CHANGELOG.md](./CHANGELOG.md).
-
-## Documentation
-
-> [docs.coopcloud.tech](https://docs.coopcloud.tech)
-
-## Install
-
-Install the latest stable release:
-
-```sh
-curl https://install.abra.autonomic.zone | bash
-```
-
-or the bleeding-edge development version:
-
-```sh
-curl https://install.abra.autonomic.zone | bash -s -- --dev
-```
-
-The source for this script is [here](./deploy/install.abra.autonomic.zone/installer).
-
-## Update
-
-Run `abra upgrade` to automatically download and install the latest release
-version.
-
-To update the development version, run `abra upgrade --dev`.
-
-## Hack
-
-It's written in Bash version 4 or greater!
-
-Install it via `curl https://install.abra.autonomic.zone | bash -s -- --dev`, then you can hack on the source in `~/.abra/src`.
-
-The command-line interface is generated via [docopt](http://docopt.org/). If you add arguments then you need to run `make docopt` ro regenerate the parser.
-
-Please remember to update the [CHANGELOG](./CHANGELOG.md) when you make a change.
-
-## Generating a new apps.json
-
-You'll need to install the following requirements:
-
-- [requests](https://docs.python-requests.org/en/master/) (`apt install python3-requests` / `pip install requests`)
-- [skopeo](https://github.com/containers/skopeo) (check [the install docs](https://github.com/containers/skopeo/blob/master/install.md))
-- [jq](https://stedolan.github.io/jq/tutorial/) (`sudo apt-get install jq` or see [the install docs](https://stedolan.github.io/jq/download/))
-- [yq](https://mikefarah.gitbook.io/yq/) (see [the install docs](https://mikefarah.gitbook.io/yq/#install))
-
-Then run `./bin/app-json.py` ([source](./bin/app-json.py)) and it will spit out the JSON file into [deploy/apps.coopcloud.tech/apps.json](./deploy/apps.coopcloud.tech/apps.json).
-
-## Releasing
-
-### `abra`
-
-> [install.abra.autonomic.zone](https://install.abra.autonomic.zone)
-
-- Change the `x.x.x` header in [CHANGELOG.md](./CHANGELOG.md) to reflect new version and mark date
-- Update the version in [abra](./abra)
-- Update the version in [deploy/install.abra.autonomic.zone/installer](./deploy/install.abra.autonomic.zone/installer)
-- `git commit` the above changes and then tag it with `git tag <your-new-version>`
-- `git push` and `git push --tags`
-- Deploy a new installer script `make release-installer`
-- Tell the world (CoTech forum, Matrix public channel, Autonomic mastodon, etc.)
-
-### apps.coopcloud.tech
-
-> [apps.coopcloud.tech](https://apps.coopcloud.tech)
-
-```bash
-$ make release-apps
-```

bin/app-catalogue.sh

@@ -1,103 +0,0 @@
-#!/bin/bash
-
-# shellcheck disable=SC2119
-
-# Usage: ./app-catalogue.sh
-#
-# Gather metadata from Co-op Cloud apps in $ABRA_DIR/apps (default
-# ~/.abra/apps), and format it as a Markdown table for this page:
-# https://docs.cloud.autonomic.zone/apps/
-
-stack_dir="${ABRA_DIR:-$HOME/.abra}/apps/"
-
-cd "$stack_dir" || exit
-
-# load all README files into ENV_FILES array
-mapfile -t readmes < <(find -L . -name "README.md")
-# FIXME 3wc: requires bash 4, use for loop instead
-
-base_url="https://git.autonomic.zone/coop-cloud"
-
-cat_apps=()
-cat_development=()
-cat_utilities=()
-cat_graveyard=()
-
-get_var() {
-	echo "$1" | grep "$2" | sed 's/^[^:]*: //'
-}
-
-# shellcheck disable=SC2120
-trim() {
-	# accept input as argument or from STDIN, see here:
-	# https://zwbetz.com/passing-input-to-a-bash-function-via-arguments-or-stdin/
-	# shellcheck disable=SC2155
-	local input="$([[ -p /dev/stdin ]] && cat - || echo "$@")"
-	[[ -z "$input" ]] && return 1
-	echo "$input" | tr -d ' '
-}
-
-# shellcheck disable=SC2120
-prettify() {
-	# as above
-	# shellcheck disable=SC2155
-	local input="$([[ -p /dev/stdin ]] && cat - || echo "$@")"
-	[[ -z "$input" ]] && return 1
-
-	echo "$input" | sed -e 's/Yes/✅/' -e 's/No/❌/' -e 's/N\/A/⛔/'
-}
-
-for readme in "${readmes[@]}"; do
-	type="$(basename "${readme%README.md}")"
-	if [ "$type" = "example" ]; then
-		continue
-	fi
-	title="$(grep '^# ' "$type/README.md" | sed 's/^# //' )"
-	# find section between 'metadata' and 'endmetadata' comments
-	metadata="$(awk '/-- metadata --/,/-- endmetadata --/' "$type/README.md")"
-	status="$(get_var "$metadata" "Status")"
-	category="$(get_var "$metadata" "Category" | cut -d',' -f2 | trim)"
-
-	if [ -z "$category" ]; then
-		echo "ERROR: missing category for $type"
-		continue
-	fi
-
-	image="$(get_var "$metadata" "Image" | cut -d',' -f2 | trim)"
-	healthcheck="$(get_var "$metadata" "Healthcheck" | prettify)"
-	backups="$(get_var "$metadata" "Backups" | prettify)"
-	email="$(get_var "$metadata" "Email" | prettify)"
-	tests="$(get_var "$metadata" "Tests" | prettify)"
-	sso="$(get_var "$metadata" "SSO" | prettify)"
-
-	row="| [$title]($base_url/$type) | $status | $image | $healthcheck | $backups | $email | $tests | $sso |"
-
-	category_lower="$(echo "$category" | tr '[:upper:]' '[:lower:]')"
-	eval "cat_$category_lower+=( '$row' )"
-done
-
-headers="
-| **Name** | **Status** | **Image** | **Healtcheck** | **Backups** | **Email** | **CI** | **Single-Sign-On** |
-| --- | --- | --- | --- | --- | --- | --- | --- |"
-
-echo "## Applications"
-echo "$headers"
-printf '%s\n' "${cat_apps[@]}" | sort
-
-echo
-
-echo "## Developer tools"
-echo "$headers"
-printf '%s\n' "${cat_development[@]}" | sort
-
-echo
-
-echo "## Utilities"
-echo "$headers"
-printf '%s\n' "${cat_utilities[@]}" | sort
-
-echo
-
-echo "## Graveyard"
-echo "$headers"
-printf '%s\n' "${cat_graveyard[@]}" | sort

bin/app-json.py

@@ -1,284 +0,0 @@
-#!/usr/bin/env python3
-
-# Usage: ./app-json.py
-#
-# Gather metadata from Co-op Cloud apps in $ABRA_DIR/apps (default
-# ~/.abra/apps), and format it as JSON so that it can be hosted here:
-# https://apps.coopcloud.tech
-
-from json import dump
-from logging import DEBUG, basicConfig, getLogger
-from os import chdir, listdir, mkdir
-from os.path import basename, exists, expanduser
-from pathlib import Path
-from re import findall, search
-from shlex import split
-from subprocess import DEVNULL, check_output
-from sys import exit
-
-from requests import get
-
-HOME_PATH = expanduser("~/")
-CLONES_PATH = Path(f"{HOME_PATH}/.abra/apps").absolute()
-YQ_PATH = Path(f"{HOME_PATH}/.abra/vendor/yq")
-SCRIPT_PATH = Path(__file__).absolute().parent
-REPOS_TO_SKIP = (
-    "abra",
-    "abra-apps",
-    "backup-bot",
-    "cloud.autonomic.zone",
-    "docs.cloud.autonomic.zone",
-    "example",
-    "organising",
-    "pyabra",
-    "stack-ssh-deploy",
-    "radicle-seed-node",
-    "coturn",
-)
-
-log = getLogger(__name__)
-basicConfig()
-log.setLevel(DEBUG)
-
-
-def _run_cmd(cmd, shell=False, **kwargs):
-    """Run a shell command."""
-    args = [split(cmd)]
-
-    if shell:
-        args = [cmd]
-        kwargs = {"shell": shell}
-
-    try:
-        return check_output(*args, **kwargs).decode("utf-8").strip()
-    except Exception as exception:
-        log.error(f"Failed to run {cmd}, saw {str(exception)}")
-        exit(1)
-
-
-def get_repos_json():
-    """ Retrieve repo list from Gitea """
-
-    url = "https://git.autonomic.zone/api/v1/orgs/coop-cloud/repos"
-
-    log.info(f"Retrieving {url}")
-
-    repos = []
-    response = True
-    page = 1
-
-    try:
-        while response:
-            log.info(f"Trying to fetch page {page}")
-            response = get(url + f"?page={page}", timeout=10).json()
-            repos.extend(response)
-            page += 1
-
-        return repos
-    except Exception as exception:
-        log.error(f"Failed to retrieve {url}, saw {str(exception)}")
-        exit(1)
-
-
-def get_published_apps_json():
-    """Retrieve already published apps json."""
-    url = "https://apps.coopcloud.tech"
-
-    log.info(f"Retrieving {url}")
-
-    try:
-        return get(url, timeout=5).json()
-    except Exception as exception:
-        log.error(f"Failed to retrieve {url}, saw {str(exception)}")
-        return {}
-
-
-def clone_all_apps(repos_json):
-    """Clone all Co-op Cloud apps to ~/.abra/apps."""
-    if not exists(CLONES_PATH):
-        mkdir(CLONES_PATH)
-
-    repos = [[p["name"], p["ssh_url"]] for p in repos_json]
-
-    for name, url in repos:
-        continue
-        if name in REPOS_TO_SKIP:
-            continue
-
-        if not exists(f"{CLONES_PATH}/{name}"):
-            log.info(f"Retrieving {url}")
-            _run_cmd(f"git clone {url} {CLONES_PATH}/{name}")
-
-            chdir(f"{CLONES_PATH}/{name}")
-            if not int(_run_cmd("git branch --list | wc -l", shell=True)):
-                log.info(f"Guessing main branch is HEAD for {name}")
-                _run_cmd("git checkout main")
-        else:
-            log.info(f"Updating {name}")
-            chdir(f"{CLONES_PATH}/{name}")
-            _run_cmd("git fetch -a")
-
-
-def generate_apps_json(repos_json):
-    """Generate the abra-apps.json application versions file."""
-    apps_json = {}
-    cached_apps_json = get_published_apps_json()
-
-    for app in listdir(CLONES_PATH):
-        if app in REPOS_TO_SKIP:
-            log.info(f"Skipping {app}")
-            continue
-
-        repo_details = next(filter(lambda x: x["name"] == app, repos_json), {})
-
-        app_path = f"{CLONES_PATH}/{app}"
-        chdir(app_path)
-
-        metadata = get_app_metadata(app_path)
-        name = metadata.pop("name", "")
-
-        log.info(f"Processing {app}")
-        apps_json[app] = {
-            "name": name,
-            "category": metadata.get("category", ""),
-            "repository": repo_details.get("clone_url", ""),
-            "default_branch": repo_details.get("default_branch", ""),
-            "description": repo_details.get("description", ""),
-            "website": repo_details.get("website", ""),
-            # Note(decentral1se): please note that the app metadata do not
-            # correspond to version tags. We simply parse the latest metadata
-            # list from HEAD. This may lead to unexpected situations where
-            # users believe X feature is available under Y version but it is
-            # not.
-            "features": metadata,
-            "versions": get_app_versions(app_path, cached_apps_json),
-            "icon": repo_details.get("avatar_url", ""),
-        }
-
-    return apps_json
-
-
-def get_app_metadata(app_path):
-    """Parse metadata from app repo README files."""
-    metadata = {}
-
-    chdir(app_path)
-
-    with open(f"{app_path}/README.md", "r") as handle:
-        log.info(f"{app_path}/README.md")
-        contents = handle.read()
-
-    try:
-        for match in findall(r"\*\*.*\s\*", contents):
-            title = search(r"(?<=\*\*).*(?=\*\*)", match).group().lower()
-
-            if title == "image":
-                value = {
-                    "image": search(r"(?<=`).*(?=`)", match).group(),
-                    "url": search(r"(?<=\().*(?=\))", match).group(),
-                    "rating": match.split(",")[1].strip(),
-                    "source": match.split(",")[-1].replace("*", "").strip(),
-                }
-            else:
-                value = match.split(":")[-1].replace("*", "").strip()
-
-            metadata[title] = value
-        metadata["name"] = findall(r"^# (.*)", contents)[0]
-    except (IndexError, AttributeError):
-        log.info(f"Can't parse {app_path}/README.md")
-        return {}
-    finally:
-        _run_cmd("git checkout HEAD")
-
-    log.info(f"Parsed {metadata}")
-
-    return metadata
-
-
-def get_app_versions(app_path, cached_apps_json):
-    versions = {}
-
-    chdir(app_path)
-
-    tags = _run_cmd("git tag --list").split()
-
-    if not tags:
-        log.info("No tags discovered, moving on")
-        return {}
-
-    initial_branch = _run_cmd("git rev-parse --abbrev-ref HEAD")
-
-    app_name = basename(app_path)
-
-    try:
-        existing_tags = cached_apps_json[app_name]["versions"].keys()
-    except KeyError:
-        existing_tags = []
-
-    for tag in tags:
-        _run_cmd(f"git checkout {tag}", stderr=DEVNULL)
-
-        services_cmd = f"{YQ_PATH} e '.services | keys | .[]' compose*.yml"
-        services = _run_cmd(services_cmd, shell=True).split()
-
-        parsed_services = []
-        service_versions = {}
-        for service in services:
-            if service in ("null", "---"):
-                continue
-
-            if (
-                tag in existing_tags
-                and service in cached_apps_json[app_name]["versions"][tag]
-            ):
-                log.info(f"Skipping {tag} because we've already processed it")
-                existing_versions = cached_apps_json[app_name]["versions"][tag][service]
-                service_versions[service] = existing_versions
-                _run_cmd(f"git checkout {initial_branch}")
-                continue
-
-            if service in parsed_services:
-                log.info(f"Skipped {service}, we've already parsed it locally")
-                continue
-
-            services_cmd = f"{YQ_PATH} e '.services.{service}.image' compose*.yml"
-            images = _run_cmd(services_cmd, shell=True).split()
-
-            for image in images:
-                if image in ("null", "---"):
-                    continue
-
-                images_cmd = f"skopeo inspect docker://{image} | jq '.Digest'"
-                output = _run_cmd(images_cmd, shell=True)
-
-                service_version_info = {
-                    "image": image.split(":")[0],
-                    "tag": image.split(":")[-1],
-                    "digest": output.split(":")[-1][:8],
-                }
-
-                log.info(f"Parsed {service_version_info}")
-                service_versions[service] = service_version_info
-
-            parsed_services.append(service)
-
-        versions[tag] = service_versions
-
-    _run_cmd(f"git checkout {initial_branch}")
-
-    return versions
-
-
-def main():
-    """Run the script."""
-    repos_json = get_repos_json()
-    clone_all_apps(repos_json)
-
-    target = f"{SCRIPT_PATH}/../deploy/apps.coopcloud.tech/apps.json"
-    with open(target, "w", encoding="utf-8") as handle:
-        dump(generate_apps_json(repos_json), handle, ensure_ascii=False, indent=4)
-
-    log.info(f"Successfully generated {target}")
-
-
-main()

cli/app/app.go

@@ -0,0 +1,11 @@
+package app
+
+import (
+	"github.com/spf13/cobra"
+)
+
+var AppCommand = &cobra.Command{
+	Use:     "app [cmd] [args] [flags]",
+	Aliases: []string{"a"},
+	Short:   "Manage apps",
+}

cli/app/backup.go

@@ -0,0 +1,307 @@
+package app
+
+import (
+	"fmt"
+
+	"coopcloud.tech/abra/cli/internal"
+	"coopcloud.tech/abra/pkg/autocomplete"
+	"coopcloud.tech/abra/pkg/client"
+	"coopcloud.tech/abra/pkg/log"
+	"github.com/spf13/cobra"
+)
+
+var AppBackupListCommand = &cobra.Command{
+	Use:     "list <domain> [flags]",
+	Aliases: []string{"ls"},
+	Short:   "List the contents of a snapshot",
+	Args:    cobra.ExactArgs(1),
+	ValidArgsFunction: func(
+		cmd *cobra.Command,
+		args []string,
+		toComplete string) ([]string, cobra.ShellCompDirective) {
+		return autocomplete.AppNameComplete()
+	},
+	Run: func(cmd *cobra.Command, args []string) {
+		app := internal.ValidateApp(args)
+
+		cl, err := client.New(app.Server)
+		if err != nil {
+			log.Fatal(err)
+		}
+
+		targetContainer, err := internal.RetrieveBackupBotContainer(cl)
+		if err != nil {
+			log.Fatal(err)
+		}
+
+		execEnv := []string{
+			fmt.Sprintf("SERVICE=%s", app.Domain),
+			"MACHINE_LOGS=true",
+		}
+
+		if snapshot != "" {
+			log.Debugf("including SNAPSHOT=%s in backupbot exec invocation", snapshot)
+			execEnv = append(execEnv, fmt.Sprintf("SNAPSHOT=%s", snapshot))
+		}
+
+		if showAllPaths {
+			log.Debugf("including SHOW_ALL=%v in backupbot exec invocation", showAllPaths)
+			execEnv = append(execEnv, fmt.Sprintf("SHOW_ALL=%v", showAllPaths))
+		}
+
+		if timestamps {
+			log.Debugf("including TIMESTAMPS=%v in backupbot exec invocation", timestamps)
+			execEnv = append(execEnv, fmt.Sprintf("TIMESTAMPS=%v", timestamps))
+		}
+
+		if _, err = internal.RunBackupCmdRemote(cl, "ls", targetContainer.ID, execEnv); err != nil {
+			log.Fatal(err)
+		}
+	},
+}
+
+var AppBackupDownloadCommand = &cobra.Command{
+	Use:     "download <domain> [flags]",
+	Aliases: []string{"d"},
+	Short:   "Download a snapshot",
+	Long: `Downloads a backup.tar.gz to the current working directory.
+
+"--volumes/-v" includes data contained in volumes alongide paths specified in
+"backupbot.backup.path" labels.`,
+	Args: cobra.ExactArgs(1),
+	ValidArgsFunction: func(
+		cmd *cobra.Command,
+		args []string,
+		toComplete string) ([]string, cobra.ShellCompDirective) {
+		return autocomplete.AppNameComplete()
+	},
+	Run: func(cmd *cobra.Command, args []string) {
+		app := internal.ValidateApp(args)
+
+		if err := app.Recipe.Ensure(internal.GetEnsureContext()); err != nil {
+			log.Fatal(err)
+		}
+
+		cl, err := client.New(app.Server)
+		if err != nil {
+			log.Fatal(err)
+		}
+
+		targetContainer, err := internal.RetrieveBackupBotContainer(cl)
+		if err != nil {
+			log.Fatal(err)
+		}
+
+		execEnv := []string{
+			fmt.Sprintf("SERVICE=%s", app.Domain),
+			"MACHINE_LOGS=true",
+		}
+
+		if snapshot != "" {
+			log.Debugf("including SNAPSHOT=%s in backupbot exec invocation", snapshot)
+			execEnv = append(execEnv, fmt.Sprintf("SNAPSHOT=%s", snapshot))
+		}
+
+		if includePath != "" {
+			log.Debugf("including INCLUDE_PATH=%s in backupbot exec invocation", includePath)
+			execEnv = append(execEnv, fmt.Sprintf("INCLUDE_PATH=%s", includePath))
+		}
+
+		if includeSecrets {
+			log.Debugf("including SECRETS=%v in backupbot exec invocation", includeSecrets)
+			execEnv = append(execEnv, fmt.Sprintf("SECRETS=%v", includeSecrets))
+		}
+
+		if includeVolumes {
+			log.Debugf("including VOLUMES=%v in backupbot exec invocation", includeVolumes)
+			execEnv = append(execEnv, fmt.Sprintf("VOLUMES=%v", includeVolumes))
+		}
+
+		if _, err := internal.RunBackupCmdRemote(cl, "download", targetContainer.ID, execEnv); err != nil {
+			log.Fatal(err)
+		}
+
+		remoteBackupDir := "/tmp/backup.tar.gz"
+		currentWorkingDir := "."
+		if err = CopyFromContainer(cl, targetContainer.ID, remoteBackupDir, currentWorkingDir); err != nil {
+			log.Fatal(err)
+		}
+	},
+}
+
+var AppBackupCreateCommand = &cobra.Command{
+	Use:     "create <domain> [flags]",
+	Aliases: []string{"c"},
+	Short:   "Create a new snapshot",
+	Args:    cobra.ExactArgs(1),
+	ValidArgsFunction: func(
+		cmd *cobra.Command,
+		args []string,
+		toComplete string) ([]string, cobra.ShellCompDirective) {
+		return autocomplete.AppNameComplete()
+	},
+	Run: func(cmd *cobra.Command, args []string) {
+		app := internal.ValidateApp(args)
+
+		if err := app.Recipe.Ensure(internal.GetEnsureContext()); err != nil {
+			log.Fatal(err)
+		}
+
+		cl, err := client.New(app.Server)
+		if err != nil {
+			log.Fatal(err)
+		}
+
+		targetContainer, err := internal.RetrieveBackupBotContainer(cl)
+		if err != nil {
+			log.Fatal(err)
+		}
+
+		execEnv := []string{
+			fmt.Sprintf("SERVICE=%s", app.Domain),
+			"MACHINE_LOGS=true",
+		}
+
+		if retries != "" {
+			log.Debugf("including RETRIES=%s in backupbot exec invocation", retries)
+			execEnv = append(execEnv, fmt.Sprintf("RETRIES=%s", retries))
+		}
+
+		if _, err := internal.RunBackupCmdRemote(cl, "create", targetContainer.ID, execEnv); err != nil {
+			log.Fatal(err)
+		}
+	},
+}
+
+var AppBackupSnapshotsCommand = &cobra.Command{
+	Use:     "snapshots <domain> [flags]",
+	Aliases: []string{"s"},
+	Short:   "List all snapshots",
+	Args:    cobra.ExactArgs(1),
+	ValidArgsFunction: func(
+		cmd *cobra.Command,
+		args []string,
+		toComplete string) ([]string, cobra.ShellCompDirective) {
+		return autocomplete.AppNameComplete()
+	},
+	Run: func(cmd *cobra.Command, args []string) {
+		app := internal.ValidateApp(args)
+
+		cl, err := client.New(app.Server)
+		if err != nil {
+			log.Fatal(err)
+		}
+
+		targetContainer, err := internal.RetrieveBackupBotContainer(cl)
+		if err != nil {
+			log.Fatal(err)
+		}
+
+		execEnv := []string{
+			fmt.Sprintf("SERVICE=%s", app.Domain),
+			"MACHINE_LOGS=true",
+		}
+
+		if _, err = internal.RunBackupCmdRemote(cl, "snapshots", targetContainer.ID, execEnv); err != nil {
+			log.Fatal(err)
+		}
+	},
+}
+
+var AppBackupCommand = &cobra.Command{
+	Use:     "backup [cmd] [args] [flags]",
+	Aliases: []string{"b"},
+	Short:   "Manage app backups",
+}
+
+var (
+	snapshot       string
+	retries        string
+	includePath    string
+	showAllPaths   bool
+	timestamps     bool
+	includeSecrets bool
+	includeVolumes bool
+)
+
+func init() {
+	AppBackupListCommand.Flags().StringVarP(
+		&snapshot,
+		"snapshot",
+		"s",
+		"",
+		"list specific snapshot",
+	)
+
+	AppBackupListCommand.Flags().BoolVarP(
+		&showAllPaths,
+		"all",
+		"a",
+		false,
+		"show all paths",
+	)
+
+	AppBackupListCommand.Flags().BoolVarP(
+		&timestamps,
+		"timestamps",
+		"t",
+		false,
+		"include timestamps",
+	)
+
+	AppBackupDownloadCommand.Flags().StringVarP(
+		&snapshot,
+		"snapshot",
+		"s",
+		"",
+		"list specific snapshot",
+	)
+
+	AppBackupDownloadCommand.Flags().StringVarP(
+		&includePath,
+		"path",
+		"p",
+		"",
+		"volumes path",
+	)
+
+	AppBackupDownloadCommand.Flags().BoolVarP(
+		&includeSecrets,
+		"secrets",
+		"S",
+		false,
+		"include secrets",
+	)
+
+	AppBackupDownloadCommand.Flags().BoolVarP(
+		&includeVolumes,
+		"volumes",
+		"v",
+		false,
+		"include volumes",
+	)
+
+	AppBackupDownloadCommand.Flags().BoolVarP(
+		&internal.Chaos,
+		"chaos",
+		"C",
+		false,
+		"ignore uncommitted recipes changes",
+	)
+
+	AppBackupCreateCommand.Flags().StringVarP(
+		&retries,
+		"retries",
+		"r",
+		"1",
+		"number of retry attempts",
+	)
+
+	AppBackupCreateCommand.Flags().BoolVarP(
+		&internal.Chaos,
+		"chaos",
+		"C",
+		false,
+		"ignore uncommitted recipes changes",
+	)
+}

cli/app/check.go

@@ -0,0 +1,91 @@
+package app
+
+import (
+	"fmt"
+
+	"coopcloud.tech/abra/cli/internal"
+	appPkg "coopcloud.tech/abra/pkg/app"
+	"coopcloud.tech/abra/pkg/autocomplete"
+	"coopcloud.tech/abra/pkg/formatter"
+	"coopcloud.tech/abra/pkg/log"
+	"github.com/charmbracelet/lipgloss"
+	"github.com/spf13/cobra"
+)
+
+var AppCheckCommand = &cobra.Command{
+	Use:     "check <domain> [flags]",
+	Aliases: []string{"chk"},
+	Short:   "Ensure an app is well configured",
+	Long: `Compare env vars in both the app ".env" and recipe ".env.sample" file.
+
+The goal is to ensure that recipe ".env.sample" env vars are defined in your
+app ".env" file. Only env var definitions in the ".env.sample" which are
+uncommented, e.g. "FOO=bar" are checked. If an app ".env" file does not include
+these env vars, then "check" will complain.
+
+Recipe maintainers may or may not provide defaults for env vars within their
+recipes regardless of commenting or not (e.g. through the use of
+${FOO:<default>} syntax). "check" does not confirm or deny this for you.`,
+	Args: cobra.ExactArgs(1),
+	ValidArgsFunction: func(
+		cmd *cobra.Command,
+		args []string,
+		toComplete string) ([]string, cobra.ShellCompDirective) {
+		return autocomplete.AppNameComplete()
+	},
+	Run: func(cmd *cobra.Command, args []string) {
+		app := internal.ValidateApp(args)
+
+		if err := app.Recipe.Ensure(internal.GetEnsureContext()); err != nil {
+			log.Fatal(err)
+		}
+
+		table, err := formatter.CreateTable()
+		if err != nil {
+			log.Fatal(err)
+		}
+
+		table.
+			Headers(
+				fmt.Sprintf("%s .env.sample", app.Recipe.Name),
+				fmt.Sprintf("%s.env", app.Name),
+			).
+			StyleFunc(func(row, col int) lipgloss.Style {
+				switch {
+				case col == 1:
+					return lipgloss.NewStyle().Padding(0, 1, 0, 1).Align(lipgloss.Center)
+				default:
+					return lipgloss.NewStyle().Padding(0, 1, 0, 1)
+				}
+			})
+
+		envVars, err := appPkg.CheckEnv(app)
+		if err != nil {
+			log.Fatal(err)
+		}
+
+		for _, envVar := range envVars {
+			if envVar.Present {
+				val := []string{envVar.Name, "✅"}
+				table.Row(val...)
+			} else {
+				val := []string{envVar.Name, "❌"}
+				table.Row(val...)
+			}
+		}
+
+		if err := formatter.PrintTable(table); err != nil {
+			log.Fatal(err)
+		}
+	},
+}
+
+func init() {
+	AppCheckCommand.Flags().BoolVarP(
+		&internal.Chaos,
+		"chaos",
+		"C",
+		false,
+		"ignore uncommitted recipes changes",
+	)
+}

cli/app/cmd.go

@@ -0,0 +1,276 @@
+package app
+
+import (
+	"errors"
+	"fmt"
+	"os"
+	"os/exec"
+	"slices"
+	"sort"
+	"strings"
+
+	"coopcloud.tech/abra/cli/internal"
+	appPkg "coopcloud.tech/abra/pkg/app"
+	"coopcloud.tech/abra/pkg/autocomplete"
+	"coopcloud.tech/abra/pkg/client"
+	"coopcloud.tech/abra/pkg/log"
+	"github.com/spf13/cobra"
+)
+
+var AppCmdCommand = &cobra.Command{
+	Use:     "command <domain> [service | --local] <cmd> [[args] [flags] | [flags] -- [args]]",
+	Aliases: []string{"cmd"},
+	Short:   "Run app commands",
+	Long: `Run an app specific command.
+
+These commands are bash functions, defined in the abra.sh of the recipe itself.
+They can be run within the context of a service (e.g. app) or locally on your
+work station by passing "--local/-l".
+
+N.B. If using the "--" style to pass arguments, flags (e.g. "--local/-l") must
+be passed *before* the "--". It is possible to pass arguments without the "--"
+as long as no dashes are present (i.e. "foo" works without "--", "-foo"
+does not).`,
+	Example: `  # pass <cmd> args/flags without "--"
+  abra app cmd 1312.net app my_cmd_arg foo --user bar
+
+  # pass <cmd> args/flags with "--"
+  abra app cmd 1312.net app my_cmd_args --user bar -- foo -vvv
+
+  # drop the [service] arg if using "--local/-l"
+  abra app cmd 1312.net my_cmd --local`,
+	Args: func(cmd *cobra.Command, args []string) error {
+		if local {
+			if !(len(args) >= 2) {
+				return errors.New("requires at least 2 arguments with --local/-l")
+			}
+
+			if slices.Contains(os.Args, "--") {
+				if cmd.ArgsLenAtDash() > 2 {
+					return errors.New("accepts at most 2 args with --local/-l")
+				}
+			}
+
+			// NOTE(d1): it is unclear how to correctly validate this case
+			//
+			// abra app cmd 1312.net app test_cmd_args foo --local
+			// FATAL <recipe> doesn't have a app function
+			//
+			// "app" should not be there, but there is no reliable way to detect arg
+			// count when the user can pass an arbitrary amount of recipe command
+			// arguments
+			return nil
+		}
+
+		if !(len(args) >= 3) {
+			return errors.New("requires at least 3 arguments")
+		}
+
+		return nil
+	},
+	ValidArgsFunction: func(
+		cmd *cobra.Command,
+		args []string,
+		toComplete string) ([]string, cobra.ShellCompDirective) {
+		switch l := len(args); l {
+		case 0:
+			return autocomplete.AppNameComplete()
+		case 1:
+			if !local {
+				return autocomplete.ServiceNameComplete(args[0])
+			}
+			return autocomplete.CommandNameComplete(args[0])
+		case 2:
+			if !local {
+				return autocomplete.CommandNameComplete(args[0])
+			}
+			return nil, cobra.ShellCompDirectiveDefault
+		default:
+			return nil, cobra.ShellCompDirectiveError
+		}
+	},
+	Run: func(cmd *cobra.Command, args []string) {
+		app := internal.ValidateApp(args)
+
+		if err := app.Recipe.Ensure(internal.GetEnsureContext()); err != nil {
+			log.Fatal(err)
+		}
+
+		if local && remoteUser != "" {
+			log.Fatal("cannot use --local & --user together")
+		}
+
+		hasCmdArgs, parsedCmdArgs := parseCmdArgs(args, local)
+
+		if _, err := os.Stat(app.Recipe.AbraShPath); err != nil {
+			if os.IsNotExist(err) {
+				log.Fatalf("%s does not exist for %s?", app.Recipe.AbraShPath, app.Name)
+			}
+			log.Fatal(err)
+		}
+
+		if local {
+			cmdName := args[1]
+			if err := internal.EnsureCommand(app.Recipe.AbraShPath, app.Recipe.Name, cmdName); err != nil {
+				log.Fatal(err)
+			}
+
+			log.Debugf("--local detected, running %s on local work station", cmdName)
+
+			var exportEnv string
+			for k, v := range app.Env {
+				exportEnv = exportEnv + fmt.Sprintf("%s='%s'; ", k, v)
+			}
+
+			var sourceAndExec string
+			if hasCmdArgs {
+				log.Debugf("parsed following command arguments: %s", parsedCmdArgs)
+				sourceAndExec = fmt.Sprintf("TARGET=local; APP_NAME=%s; STACK_NAME=%s; %s . %s; %s %s", app.Name, app.StackName(), exportEnv, app.Recipe.AbraShPath, cmdName, parsedCmdArgs)
+			} else {
+				log.Debug("did not detect any command arguments")
+				sourceAndExec = fmt.Sprintf("TARGET=local; APP_NAME=%s; STACK_NAME=%s; %s . %s; %s", app.Name, app.StackName(), exportEnv, app.Recipe.AbraShPath, cmdName)
+			}
+
+			shell := "/bin/bash"
+			if _, err := os.Stat(shell); errors.Is(err, os.ErrNotExist) {
+				log.Debugf("%s does not exist locally, use /bin/sh as fallback", shell)
+				shell = "/bin/sh"
+			}
+			cmd := exec.Command(shell, "-c", sourceAndExec)
+
+			if err := internal.RunCmd(cmd); err != nil {
+				log.Fatal(err)
+			}
+
+			return
+		}
+
+		cmdName := args[2]
+		if err := internal.EnsureCommand(app.Recipe.AbraShPath, app.Recipe.Name, cmdName); err != nil {
+			log.Fatal(err)
+		}
+
+		serviceNames, err := appPkg.GetAppServiceNames(app.Name)
+		if err != nil {
+			log.Fatal(err)
+		}
+
+		matchingServiceName := false
+		targetServiceName := args[1]
+		for _, serviceName := range serviceNames {
+			if serviceName == targetServiceName {
+				matchingServiceName = true
+			}
+		}
+
+		if !matchingServiceName {
+			log.Fatalf("no service %s for %s?", targetServiceName, app.Name)
+		}
+
+		log.Debugf("running command %s within the context of %s_%s", cmdName, app.StackName(), targetServiceName)
+
+		if hasCmdArgs {
+			log.Debugf("parsed following command arguments: %s", parsedCmdArgs)
+		} else {
+			log.Debug("did not detect any command arguments")
+		}
+
+		cl, err := client.New(app.Server)
+		if err != nil {
+			log.Fatal(err)
+		}
+
+		if err := internal.RunCmdRemote(
+			cl,
+			app,
+			disableTTY,
+			app.Recipe.AbraShPath,
+			targetServiceName, cmdName, parsedCmdArgs, remoteUser); err != nil {
+			log.Fatal(err)
+		}
+	},
+}
+
+var AppCmdListCommand = &cobra.Command{
+	Use:     "list <domain> [flags]",
+	Aliases: []string{"ls"},
+	Short:   "List all available commands",
+	Args:    cobra.MinimumNArgs(1),
+	Run: func(cmd *cobra.Command, args []string) {
+		app := internal.ValidateApp(args)
+
+		if err := app.Recipe.Ensure(internal.GetEnsureContext()); err != nil {
+			log.Fatal(err)
+		}
+
+		cmdNames, err := appPkg.ReadAbraShCmdNames(app.Recipe.AbraShPath)
+		if err != nil {
+			log.Fatal(err)
+		}
+
+		sort.Strings(cmdNames)
+
+		for _, cmdName := range cmdNames {
+			fmt.Println(cmdName)
+		}
+	},
+}
+
+func parseCmdArgs(args []string, isLocal bool) (bool, string) {
+	var (
+		parsedCmdArgs string
+		hasCmdArgs    bool
+	)
+
+	if isLocal {
+		if len(args) > 2 {
+			return true, fmt.Sprintf("%s ", strings.Join(args[2:], " "))
+		}
+	} else {
+		if len(args) > 3 {
+			return true, fmt.Sprintf("%s ", strings.Join(args[3:], " "))
+		}
+	}
+
+	return hasCmdArgs, parsedCmdArgs
+}
+
+var (
+	local      bool
+	remoteUser string
+	disableTTY bool
+)
+
+func init() {
+	AppCmdCommand.Flags().BoolVarP(
+		&local,
+		"local",
+		"l",
+		false,
+		"run command locally",
+	)
+
+	AppCmdCommand.Flags().StringVarP(
+		&remoteUser,
+		"user",
+		"u",
+		"",
+		"request remote user",
+	)
+
+	AppCmdCommand.Flags().BoolVarP(
+		&disableTTY,
+		"tty",
+		"T",
+		false,
+		"disable remote TTY",
+	)
+
+	AppCmdCommand.Flags().BoolVarP(
+		&internal.Chaos,
+		"chaos",
+		"C",
+		false,
+		"ignore uncommitted recipes changes",
+	)
+}

cli/app/cmd_test.go

@@ -0,0 +1,31 @@
+package app
+
+import (
+	"strings"
+	"testing"
+)
+
+func TestParseCmdArgs(t *testing.T) {
+	tests := []struct {
+		input          []string
+		shouldParse    bool
+		expectedOutput string
+	}{
+		// `--` is not parsed when passed in from the command-line e.g. -- foo bar baz
+		// so we need to eumlate that as missing when testing if bash args are passed in
+		// see https://git.coopcloud.tech/toolshed/organising/issues/336 for more
+		{[]string{"foo.com", "app", "test"}, false, ""},
+		{[]string{"foo.com", "app", "test", "foo"}, true, "foo "},
+		{[]string{"foo.com", "app", "test", "foo", "bar", "baz"}, true, "foo bar baz "},
+	}
+
+	for _, test := range tests {
+		ok, parsed := parseCmdArgs(test.input, false)
+		if ok != test.shouldParse {
+			t.Fatalf("[%s] should not parse", strings.Join(test.input, " "))
+		}
+		if parsed != test.expectedOutput {
+			t.Fatalf("%s does not match %s", parsed, test.expectedOutput)
+		}
+	}
+}

cli/app/config.go

@@ -0,0 +1,57 @@
+package app
+
+import (
+	"os"
+	"os/exec"
+
+	appPkg "coopcloud.tech/abra/pkg/app"
+	"coopcloud.tech/abra/pkg/autocomplete"
+	"coopcloud.tech/abra/pkg/log"
+	"github.com/AlecAivazis/survey/v2"
+	"github.com/spf13/cobra"
+)
+
+var AppConfigCommand = &cobra.Command{
+	Use:     "config <domain> [flags]",
+	Aliases: []string{"cfg"},
+	Short:   "Edit app config",
+	Example: "  abra config 1312.net",
+	Args:    cobra.ExactArgs(1),
+	ValidArgsFunction: func(
+		cmd *cobra.Command,
+		args []string,
+		toComplete string) ([]string, cobra.ShellCompDirective) {
+		return autocomplete.AppNameComplete()
+	},
+	Run: func(cmd *cobra.Command, args []string) {
+		files, err := appPkg.LoadAppFiles("")
+		if err != nil {
+			log.Fatal(err)
+		}
+
+		appName := args[0]
+		appFile, exists := files[appName]
+		if !exists {
+			log.Fatalf("cannot find app with name %s", appName)
+		}
+
+		ed, ok := os.LookupEnv("EDITOR")
+		if !ok {
+			edPrompt := &survey.Select{
+				Message: "which editor do you wish to use?",
+				Options: []string{"vi", "vim", "nvim", "nano", "pico", "emacs"},
+			}
+			if err := survey.AskOne(edPrompt, &ed); err != nil {
+				log.Fatal(err)
+			}
+		}
+
+		c := exec.Command(ed, appFile.Path)
+		c.Stdin = os.Stdin
+		c.Stdout = os.Stdout
+		c.Stderr = os.Stderr
+		if err := c.Run(); err != nil {
+			log.Fatal(err)
+		}
+	},
+}

cli/app/cp.go

@@ -0,0 +1,383 @@
+package app
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"io"
+	"os"
+	"path"
+	"path/filepath"
+	"strings"
+
+	"coopcloud.tech/abra/cli/internal"
+	"coopcloud.tech/abra/pkg/autocomplete"
+	"coopcloud.tech/abra/pkg/client"
+	containerPkg "coopcloud.tech/abra/pkg/container"
+	"coopcloud.tech/abra/pkg/formatter"
+	"coopcloud.tech/abra/pkg/log"
+	"coopcloud.tech/abra/pkg/upstream/container"
+	"github.com/docker/cli/cli/command"
+	containertypes "github.com/docker/docker/api/types/container"
+	dockerClient "github.com/docker/docker/client"
+	"github.com/docker/docker/errdefs"
+	"github.com/docker/docker/pkg/archive"
+	"github.com/spf13/cobra"
+)
+
+var AppCpCommand = &cobra.Command{
+	Use:     "cp <domain> <src> <dst> [flags]",
+	Aliases: []string{"c"},
+	Short:   "Copy files to/from a deployed app service",
+	Example: `  # copy myfile.txt to the root of the app service
+  abra app cp 1312.net myfile.txt app:/
+
+  # copy that file back to your current working directory locally
+  abra app cp 1312.net app:/myfile.txt ./`,
+	Args: cobra.ExactArgs(3),
+	ValidArgsFunction: func(
+		cmd *cobra.Command,
+		args []string,
+		toComplete string) ([]string, cobra.ShellCompDirective) {
+		switch l := len(args); l {
+		case 0:
+			return autocomplete.AppNameComplete()
+		default:
+			return nil, cobra.ShellCompDirectiveDefault
+		}
+	},
+	Run: func(cmd *cobra.Command, args []string) {
+		app := internal.ValidateApp(args)
+
+		if err := app.Recipe.Ensure(internal.GetEnsureContext()); err != nil {
+			log.Fatal(err)
+		}
+
+		src := args[1]
+		dst := args[2]
+		srcPath, dstPath, service, toContainer, err := parseSrcAndDst(src, dst)
+		if err != nil {
+			log.Fatal(err)
+		}
+
+		cl, err := client.New(app.Server)
+		if err != nil {
+			log.Fatal(err)
+		}
+
+		container, err := containerPkg.GetContainerFromStackAndService(cl, app.StackName(), service)
+		if err != nil {
+			log.Fatal(err)
+		}
+		log.Debugf("retrieved %s as target container on %s", formatter.ShortenID(container.ID), app.Server)
+
+		if toContainer {
+			err = CopyToContainer(cl, container.ID, srcPath, dstPath)
+		} else {
+			err = CopyFromContainer(cl, container.ID, srcPath, dstPath)
+		}
+		if err != nil {
+			log.Fatal(err)
+		}
+	},
+}
+
+var errServiceMissing = errors.New("one of <src>/<dest> arguments must take $SERVICE:$PATH form")
+
+// parseSrcAndDst parses src and dest string. One of src or dst must be of the form $SERVICE:$PATH
+func parseSrcAndDst(src, dst string) (srcPath string, dstPath string, service string, toContainer bool, err error) {
+	parsedSrc := strings.SplitN(src, ":", 2)
+	parsedDst := strings.SplitN(dst, ":", 2)
+	if len(parsedSrc)+len(parsedDst) != 3 {
+		return "", "", "", false, errServiceMissing
+	}
+	if len(parsedSrc) == 2 {
+		return parsedSrc[1], dst, parsedSrc[0], false, nil
+	}
+	if len(parsedDst) == 2 {
+		return src, parsedDst[1], parsedDst[0], true, nil
+	}
+	return "", "", "", false, errServiceMissing
+}
+
+// CopyToContainer copies a file or directory from the local file system to the container.
+// See the possible copy modes and their documentation.
+func CopyToContainer(cl *dockerClient.Client, containerID, srcPath, dstPath string) error {
+	srcStat, err := os.Stat(srcPath)
+	if err != nil {
+		return fmt.Errorf("local %s ", err)
+	}
+
+	dstStat, err := cl.ContainerStatPath(context.Background(), containerID, dstPath)
+	dstExists := true
+	if err != nil {
+		if errdefs.IsNotFound(err) {
+			dstExists = false
+		} else {
+			return fmt.Errorf("remote path: %s", err)
+		}
+	}
+
+	mode, err := copyMode(srcPath, dstPath, srcStat.Mode(), dstStat.Mode, dstExists)
+	if err != nil {
+		return err
+	}
+	movePath := ""
+	switch mode {
+	case CopyModeDirToDir:
+		// Add the src directory to the destination path
+		_, srcDir := path.Split(srcPath)
+		dstPath = path.Join(dstPath, srcDir)
+
+		// Make sure the dst directory exits.
+		dcli, err := command.NewDockerCli()
+		if err != nil {
+			return err
+		}
+		if _, err := container.RunExec(dcli, cl, containerID, &containertypes.ExecOptions{
+			AttachStderr: true,
+			AttachStdin:  true,
+			AttachStdout: true,
+			Cmd:          []string{"mkdir", "-p", dstPath},
+			Detach:       false,
+			Tty:          true,
+		}); err != nil {
+			return fmt.Errorf("create remote directory: %s", err)
+		}
+	case CopyModeFileToFile:
+		// Remove the file component from the path, since docker can only copy
+		// to a directory.
+		dstPath, _ = path.Split(dstPath)
+	case CopyModeFileToFileRename:
+		// Copy the file to the temp directory and move it to its dstPath
+		// afterwards.
+		movePath = dstPath
+		dstPath = "/tmp"
+	}
+
+	toTarOpts := &archive.TarOptions{IncludeSourceDir: true, NoOverwriteDirNonDir: true, Compression: archive.Gzip}
+	content, err := archive.TarWithOptions(srcPath, toTarOpts)
+	if err != nil {
+		return err
+	}
+
+	log.Debugf("copy %s from local to %s on container", srcPath, dstPath)
+	copyOpts := containertypes.CopyToContainerOptions{AllowOverwriteDirWithFile: false, CopyUIDGID: false}
+	if err := cl.CopyToContainer(context.Background(), containerID, dstPath, content, copyOpts); err != nil {
+		return err
+	}
+
+	if movePath != "" {
+		_, srcFile := path.Split(srcPath)
+		dcli, err := command.NewDockerCli()
+		if err != nil {
+			return err
+		}
+		if _, err := container.RunExec(dcli, cl, containerID, &containertypes.ExecOptions{
+			AttachStderr: true,
+			AttachStdin:  true,
+			AttachStdout: true,
+			Cmd:          []string{"mv", path.Join("/tmp", srcFile), movePath},
+			Detach:       false,
+			Tty:          true,
+		}); err != nil {
+			return fmt.Errorf("create remote directory: %s", err)
+		}
+	}
+
+	return nil
+}
+
+// CopyFromContainer copies a file or directory from the given container to the local file system.
+// See the possible copy modes and their documentation.
+func CopyFromContainer(cl *dockerClient.Client, containerID, srcPath, dstPath string) error {
+	srcStat, err := cl.ContainerStatPath(context.Background(), containerID, srcPath)
+	if err != nil {
+		if errdefs.IsNotFound(err) {
+			return fmt.Errorf("remote: %s does not exist", srcPath)
+		} else {
+			return fmt.Errorf("remote path: %s", err)
+		}
+	}
+
+	dstStat, err := os.Stat(dstPath)
+	dstExists := true
+	var dstMode os.FileMode
+	if err != nil {
+		if os.IsNotExist(err) {
+			dstExists = false
+		} else {
+			return fmt.Errorf("remote path: %s", err)
+		}
+	} else {
+		dstMode = dstStat.Mode()
+	}
+
+	mode, err := copyMode(srcPath, dstPath, srcStat.Mode, dstMode, dstExists)
+	if err != nil {
+		return err
+	}
+
+	moveDstDir := ""
+	moveDstFile := ""
+	switch mode {
+	case CopyModeFileToFile:
+		// Remove the file component from the path, since docker can only copy
+		// to a directory.
+		dstPath, _ = path.Split(dstPath)
+	case CopyModeFileToFileRename:
+		// Copy the file to the temp directory and move it to its dstPath
+		// afterwards.
+		moveDstFile = dstPath
+		dstPath = "/tmp"
+	case CopyModeFilesToDir:
+		// Copy the directory to the temp directory and move it to its
+		// dstPath afterwards.
+		moveDstDir = path.Join(dstPath, "/")
+		dstPath = "/tmp"
+
+		// Make sure the temp directory always gets removed
+		defer os.Remove(path.Join("/tmp"))
+	}
+
+	content, _, err := cl.CopyFromContainer(context.Background(), containerID, srcPath)
+	if err != nil {
+		return fmt.Errorf("copy: %s", err)
+	}
+	defer content.Close()
+	if err := archive.Untar(content, dstPath, &archive.TarOptions{
+		NoOverwriteDirNonDir: true,
+		Compression:          archive.Gzip,
+		NoLchown:             true,
+	}); err != nil {
+		return fmt.Errorf("untar: %s", err)
+	}
+
+	if moveDstFile != "" {
+		_, srcFile := path.Split(strings.TrimSuffix(srcPath, "/"))
+		if err := moveFile(path.Join("/tmp", srcFile), moveDstFile); err != nil {
+			return err
+		}
+	}
+	if moveDstDir != "" {
+		_, srcDir := path.Split(strings.TrimSuffix(srcPath, "/"))
+		if err := moveDir(path.Join("/tmp", srcDir), moveDstDir); err != nil {
+			return err
+		}
+	}
+	return nil
+}
+
+var (
+	ErrCopyDirToFile  = fmt.Errorf("can't copy dir to file")
+	ErrDstDirNotExist = fmt.Errorf("destination directory does not exist")
+)
+
+type CopyMode int
+
+const (
+	// Copy a src file to a dest file. The src and dest file names are the same.
+	//  <dir_src>/<file> + <dir_dst>/<file> -> <dir_dst>/<file>
+	CopyModeFileToFile = CopyMode(iota)
+	// Copy a src file to a dest file. The src and dest file names are  not the same.
+	//  <dir_src>/<file_src> + <dir_dst>/<file_dst> -> <dir_dst>/<file_dst>
+	CopyModeFileToFileRename
+	// Copy a src file to dest directory. The dest file gets created in the dest
+	// folder with the src filename.
+	//  <dir_src>/<file> + <dir_dst> -> <dir_dst>/<file>
+	CopyModeFileToDir
+	// Copy a src directory to dest directory.
+	//  <dir_src> + <dir_dst> -> <dir_dst>/<dir_src>
+	CopyModeDirToDir
+	// Copy all files in the src directory to the dest directory. This works recursively.
+	//  <dir_src>/ + <dir_dst> -> <dir_dst>/<files_from_dir_src>
+	CopyModeFilesToDir
+)
+
+// copyMode takes a src and dest path and file mode to determine the copy mode.
+// See the possible copy modes and their documentation.
+func copyMode(srcPath, dstPath string, srcMode os.FileMode, dstMode os.FileMode, dstExists bool) (CopyMode, error) {
+	_, srcFile := path.Split(srcPath)
+	_, dstFile := path.Split(dstPath)
+	if srcMode.IsDir() {
+		if !dstExists {
+			return -1, ErrDstDirNotExist
+		}
+		if dstMode.IsDir() {
+			if strings.HasSuffix(srcPath, "/") {
+				return CopyModeFilesToDir, nil
+			}
+			return CopyModeDirToDir, nil
+		}
+		return -1, ErrCopyDirToFile
+	}
+
+	if dstMode.IsDir() {
+		return CopyModeFileToDir, nil
+	}
+
+	if srcFile != dstFile {
+		return CopyModeFileToFileRename, nil
+	}
+
+	return CopyModeFileToFile, nil
+}
+
+// moveDir moves all files from a source path to the destination path recursively.
+func moveDir(sourcePath, destPath string) error {
+	return filepath.Walk(sourcePath, func(p string, info os.FileInfo, err error) error {
+		if err != nil {
+			return err
+		}
+		newPath := path.Join(destPath, strings.TrimPrefix(p, sourcePath))
+		if info.IsDir() {
+			err := os.Mkdir(newPath, info.Mode())
+			if err != nil {
+				if os.IsExist(err) {
+					return nil
+				}
+				return err
+			}
+		}
+		if info.Mode().IsRegular() {
+			return moveFile(p, newPath)
+		}
+		return nil
+	})
+}
+
+// moveFile moves a file from a source path to a destination path.
+func moveFile(sourcePath, destPath string) error {
+	inputFile, err := os.Open(sourcePath)
+	if err != nil {
+		return err
+	}
+	outputFile, err := os.Create(destPath)
+	if err != nil {
+		inputFile.Close()
+		return err
+	}
+	defer outputFile.Close()
+	_, err = io.Copy(outputFile, inputFile)
+	inputFile.Close()
+	if err != nil {
+		return err
+	}
+
+	// Remove file after succesfull copy.
+	err = os.Remove(sourcePath)
+	if err != nil {
+		return err
+	}
+	return nil
+}
+
+func init() {
+	AppCpCommand.Flags().BoolVarP(
+		&internal.Chaos,
+		"chaos",
+		"C",
+		false,
+		"ignore uncommitted recipes changes",
+	)
+}

cli/app/cp_test.go

@@ -0,0 +1,113 @@
+package app
+
+import (
+	"os"
+	"testing"
+)
+
+func TestParse(t *testing.T) {
+	tests := []struct {
+		src         string
+		dst         string
+		srcPath     string
+		dstPath     string
+		service     string
+		toContainer bool
+		err         error
+	}{
+		{src: "foo", dst: "bar", err: errServiceMissing},
+		{src: "app:foo", dst: "app:bar", err: errServiceMissing},
+		{src: "app:foo", dst: "bar", srcPath: "foo", dstPath: "bar", service: "app", toContainer: false},
+		{src: "foo", dst: "app:bar", srcPath: "foo", dstPath: "bar", service: "app", toContainer: true},
+	}
+
+	for i, tc := range tests {
+		srcPath, dstPath, service, toContainer, err := parseSrcAndDst(tc.src, tc.dst)
+		if srcPath != tc.srcPath {
+			t.Errorf("[%d] srcPath: want (%s), got(%s)", i, tc.srcPath, srcPath)
+		}
+		if dstPath != tc.dstPath {
+			t.Errorf("[%d] dstPath: want (%s), got(%s)", i, tc.dstPath, dstPath)
+		}
+		if service != tc.service {
+			t.Errorf("[%d] service: want (%s), got(%s)", i, tc.service, service)
+		}
+		if toContainer != tc.toContainer {
+			t.Errorf("[%d] toConainer: want (%t), got(%t)", i, tc.toContainer, toContainer)
+		}
+		if err == nil && tc.err != nil && err.Error() != tc.err.Error() {
+			t.Errorf("[%d] err: want (%s), got(%s)", i, tc.err, err)
+		}
+	}
+}
+
+func TestCopyMode(t *testing.T) {
+	tests := []struct {
+		srcPath   string
+		dstPath   string
+		srcMode   os.FileMode
+		dstMode   os.FileMode
+		dstExists bool
+		mode      CopyMode
+		err       error
+	}{
+		{
+			srcPath:   "foo.txt",
+			dstPath:   "foo.txt",
+			srcMode:   os.ModePerm,
+			dstMode:   os.ModePerm,
+			dstExists: true,
+			mode:      CopyModeFileToFile,
+		},
+		{
+			srcPath:   "foo.txt",
+			dstPath:   "bar.txt",
+			srcMode:   os.ModePerm,
+			dstExists: true,
+			mode:      CopyModeFileToFileRename,
+		},
+		{
+			srcPath:   "foo",
+			dstPath:   "foo",
+			srcMode:   os.ModeDir,
+			dstMode:   os.ModeDir,
+			dstExists: true,
+			mode:      CopyModeDirToDir,
+		},
+		{
+			srcPath:   "foo/",
+			dstPath:   "foo",
+			srcMode:   os.ModeDir,
+			dstMode:   os.ModeDir,
+			dstExists: true,
+			mode:      CopyModeFilesToDir,
+		},
+		{
+			srcPath:   "foo",
+			dstPath:   "foo",
+			srcMode:   os.ModeDir,
+			dstExists: false,
+			mode:      -1,
+			err:       ErrDstDirNotExist,
+		},
+		{
+			srcPath:   "foo",
+			dstPath:   "foo",
+			srcMode:   os.ModeDir,
+			dstMode:   os.ModePerm,
+			dstExists: true,
+			mode:      -1,
+			err:       ErrCopyDirToFile,
+		},
+	}
+
+	for i, tc := range tests {
+		mode, err := copyMode(tc.srcPath, tc.dstPath, tc.srcMode, tc.dstMode, tc.dstExists)
+		if mode != tc.mode {
+			t.Errorf("[%d] mode: want (%d), got(%d)", i, tc.mode, mode)
+		}
+		if err != tc.err {
+			t.Errorf("[%d] err: want (%s), got(%s)", i, tc.err, err)
+		}
+	}
+}

cli/app/deploy.go

@@ -0,0 +1,350 @@
+package app
+
+import (
+	"context"
+	"fmt"
+	"strings"
+
+	"coopcloud.tech/abra/cli/internal"
+	"coopcloud.tech/abra/pkg/app"
+	"coopcloud.tech/abra/pkg/autocomplete"
+	"coopcloud.tech/abra/pkg/config"
+	"coopcloud.tech/abra/pkg/envfile"
+	"coopcloud.tech/abra/pkg/secret"
+
+	appPkg "coopcloud.tech/abra/pkg/app"
+	"coopcloud.tech/abra/pkg/client"
+	"coopcloud.tech/abra/pkg/dns"
+	"coopcloud.tech/abra/pkg/formatter"
+	"coopcloud.tech/abra/pkg/lint"
+	"coopcloud.tech/abra/pkg/log"
+	"coopcloud.tech/abra/pkg/upstream/stack"
+	dockerClient "github.com/docker/docker/client"
+	"github.com/spf13/cobra"
+)
+
+var AppDeployCommand = &cobra.Command{
+	Use:     "deploy <domain> [version] [flags]",
+	Aliases: []string{"d"},
+	Short:   "Deploy an app",
+	Long: `Deploy an app.
+
+This command supports chaos operations. Use "--chaos/-C" to deploy your recipe
+checkout as-is. Recipe commit hashes are also supported as values for
+"[version]". Please note, "upgrade"/"rollback" do not support chaos operations.`,
+	Example: `  # standard deployment
+  abra app deploy 1312.net
+
+  # chaos deployment
+  abra app deploy 1312.net --chaos
+  
+  # deploy specific version
+  abra app deploy 1312.net 2.0.0+1.2.3
+
+  # deploy a specific git hash
+  abra app deploy 1312.net 886db76d`,
+	Args: cobra.RangeArgs(1, 2),
+	ValidArgsFunction: func(
+		cmd *cobra.Command,
+		args []string,
+		toComplete string,
+	) ([]string, cobra.ShellCompDirective) {
+		switch l := len(args); l {
+		case 0:
+			return autocomplete.AppNameComplete()
+		case 1:
+			app, err := appPkg.Get(args[0])
+			if err != nil {
+				errMsg := fmt.Sprintf("autocomplete failed: %s", err)
+				return []string{errMsg}, cobra.ShellCompDirectiveError
+			}
+			return autocomplete.RecipeVersionComplete(app.Recipe.Name)
+		default:
+			return nil, cobra.ShellCompDirectiveDefault
+		}
+	},
+	Run: func(cmd *cobra.Command, args []string) {
+		var (
+			deployWarnMessages []string
+			toDeployVersion    string
+		)
+
+		app := internal.ValidateApp(args)
+
+		if err := validateArgsAndFlags(args); err != nil {
+			log.Fatal(err)
+		}
+
+		if err := app.Recipe.Ensure(internal.GetEnsureContext()); err != nil {
+			log.Fatal(err)
+		}
+
+		cl, err := client.New(app.Server)
+		if err != nil {
+			log.Fatal(err)
+		}
+
+		log.Debugf("checking whether %s is already deployed", app.StackName())
+
+		deployMeta, err := stack.IsDeployed(context.Background(), cl, app.StackName())
+		if err != nil {
+			log.Fatal(err)
+		}
+
+		if deployMeta.IsDeployed && !(internal.Force || internal.Chaos) {
+			log.Fatalf("%s is already deployed", app.Name)
+		}
+
+		toDeployVersion, err = getDeployVersion(args, deployMeta, app)
+		if err != nil {
+			log.Fatal(fmt.Errorf("get deploy version: %s", err))
+		}
+
+		if !internal.Chaos {
+			_, err = app.Recipe.EnsureVersion(toDeployVersion)
+			if err != nil {
+				log.Fatalf("ensure recipe: %s", err)
+			}
+		}
+
+		if err := lint.LintForErrors(app.Recipe); err != nil {
+			log.Fatal(err)
+		}
+
+		if err := validateSecrets(cl, app); err != nil {
+			log.Fatal(err)
+		}
+
+		abraShEnv, err := envfile.ReadAbraShEnvVars(app.Recipe.AbraShPath)
+		if err != nil {
+			log.Fatal(err)
+		}
+		for k, v := range abraShEnv {
+			app.Env[k] = v
+		}
+
+		composeFiles, err := app.Recipe.GetComposeFiles(app.Env)
+		if err != nil {
+			log.Fatal(err)
+		}
+
+		stackName := app.StackName()
+		deployOpts := stack.Deploy{
+			Composefiles: composeFiles,
+			Namespace:    stackName,
+			Prune:        false,
+			ResolveImage: stack.ResolveImageAlways,
+			Detach:       false,
+		}
+		compose, err := appPkg.GetAppComposeConfig(app.Name, deployOpts, app.Env)
+		if err != nil {
+			log.Fatal(err)
+		}
+
+		appPkg.ExposeAllEnv(stackName, compose, app.Env)
+		appPkg.SetRecipeLabel(compose, stackName, app.Recipe.Name)
+		appPkg.SetChaosLabel(compose, stackName, internal.Chaos)
+		if internal.Chaos {
+			appPkg.SetChaosVersionLabel(compose, stackName, toDeployVersion)
+		}
+		appPkg.SetUpdateLabel(compose, stackName, app.Env)
+		appPkg.SetVersionLabel(compose, stackName, toDeployVersion)
+
+		envVars, err := appPkg.CheckEnv(app)
+		if err != nil {
+			log.Fatal(err)
+		}
+
+		for _, envVar := range envVars {
+			if !envVar.Present {
+				deployWarnMessages = append(deployWarnMessages,
+					fmt.Sprintf("%s missing from %s.env", envVar.Name, app.Domain),
+				)
+			}
+		}
+
+		if !internal.NoDomainChecks {
+			if domainName, ok := app.Env["DOMAIN"]; ok {
+				if _, err = dns.EnsureDomainsResolveSameIPv4(domainName, app.Server); err != nil {
+					log.Fatal(err)
+				}
+			} else {
+				log.Debug("skipping domain checks, no DOMAIN=... configured")
+			}
+		} else {
+			log.Debug("skipping domain checks")
+		}
+
+		deployedVersion := config.NO_VERSION_DEFAULT
+		if deployMeta.IsDeployed {
+			deployedVersion = deployMeta.Version
+		}
+
+		if err := internal.DeployOverview(
+			app,
+			deployedVersion,
+			toDeployVersion,
+			"",
+			deployWarnMessages,
+		); err != nil {
+			log.Fatal(err)
+		}
+
+		stack.WaitTimeout, err = appPkg.GetTimeoutFromLabel(compose, stackName)
+		if err != nil {
+			log.Fatal(err)
+		}
+
+		log.Debugf("set waiting timeout to %d second(s)", stack.WaitTimeout)
+
+		serviceNames, err := appPkg.GetAppServiceNames(app.Name)
+		if err != nil {
+			log.Fatal(err)
+		}
+
+		f, err := app.Filters(true, false, serviceNames...)
+		if err != nil {
+			log.Fatal(err)
+		}
+
+		if err := stack.RunDeploy(
+			cl,
+			deployOpts,
+			compose,
+			app.Name,
+			app.Server,
+			internal.DontWaitConverge,
+			f,
+		); err != nil {
+			log.Fatal(err)
+		}
+
+		postDeployCmds, ok := app.Env["POST_DEPLOY_CMDS"]
+		if ok && !internal.DontWaitConverge {
+			log.Debugf("run the following post-deploy commands: %s", postDeployCmds)
+			if err := internal.PostCmds(cl, app, postDeployCmds); err != nil {
+				log.Fatalf("attempting to run post deploy commands, saw: %s", err)
+			}
+		}
+
+		if err := app.WriteRecipeVersion(toDeployVersion, false); err != nil {
+			log.Fatalf("writing recipe version failed: %s", err)
+		}
+	},
+}
+
+func getLatestVersionOrCommit(app app.App) (string, error) {
+	versions, err := app.Recipe.Tags()
+	if err != nil {
+		return "", err
+	}
+
+	if len(versions) > 0 && !internal.Chaos {
+		return versions[len(versions)-1], nil
+	}
+
+	head, err := app.Recipe.Head()
+	if err != nil {
+		return "", err
+	}
+
+	return formatter.SmallSHA(head.String()), nil
+}
+
+// validateArgsAndFlags ensures compatible args/flags.
+func validateArgsAndFlags(args []string) error {
+	if len(args) == 2 && args[1] != "" && internal.Chaos {
+		return fmt.Errorf("cannot use [version] and --chaos together")
+	}
+
+	return nil
+}
+
+func validateSecrets(cl *dockerClient.Client, app app.App) error {
+	secStats, err := secret.PollSecretsStatus(cl, app)
+	if err != nil {
+		return err
+	}
+
+	for _, secStat := range secStats {
+		if !secStat.CreatedOnRemote {
+			return fmt.Errorf("secret not generated: %s", secStat.LocalName)
+		}
+	}
+
+	return nil
+}
+
+func getDeployVersion(cliArgs []string, deployMeta stack.DeployMeta, app app.App) (string, error) {
+	// Chaos mode overrides everything
+	if internal.Chaos {
+		v, err := app.Recipe.ChaosVersion()
+		if err != nil {
+			return "", err
+		}
+		log.Debugf("version: taking chaos version: %s", v)
+		return v, nil
+	}
+
+	// Check if the deploy version is set with a cli argument
+	if len(cliArgs) == 2 && cliArgs[1] != "" {
+		log.Debugf("version: taking version from cli arg: %s", cliArgs[1])
+		return cliArgs[1], nil
+	}
+
+	// Check if the recipe has a version in the .env file
+	if app.Recipe.EnvVersion != "" && !internal.IgnoreEnvVersion {
+		if strings.HasSuffix(app.Recipe.EnvVersionRaw, "+U") {
+			return "", fmt.Errorf("version: can not redeploy chaos version %s", app.Recipe.EnvVersionRaw)
+		}
+		log.Debugf("version: taking version from .env file: %s", app.Recipe.EnvVersion)
+		return app.Recipe.EnvVersion, nil
+	}
+
+	// Take deployed version
+	if deployMeta.IsDeployed {
+		log.Debugf("version: taking deployed version: %s", deployMeta.Version)
+		return deployMeta.Version, nil
+	}
+
+	v, err := getLatestVersionOrCommit(app)
+	log.Debugf("version: taking new recipe version: %s", v)
+	if err != nil {
+		return "", err
+	}
+	return v, nil
+}
+
+func init() {
+	AppDeployCommand.Flags().BoolVarP(
+		&internal.Chaos,
+		"chaos",
+		"C",
+		false,
+		"ignore uncommitted recipes changes",
+	)
+
+	AppDeployCommand.Flags().BoolVarP(
+		&internal.Force,
+		"force",
+		"f",
+		false,
+		"perform action without further prompt",
+	)
+
+	AppDeployCommand.Flags().BoolVarP(
+		&internal.NoDomainChecks,
+		"no-domain-checks",
+		"D",
+		false,
+		"disable public DNS checks",
+	)
+
+	AppDeployCommand.Flags().BoolVarP(
+		&internal.DontWaitConverge,
+		"no-converge-checks",
+		"c",
+		false,
+		"disable converge logic checks",
+	)
+}

cli/app/env.go

@@ -0,0 +1,43 @@
+package app
+
+import (
+	"fmt"
+	"sort"
+
+	"coopcloud.tech/abra/cli/internal"
+	"coopcloud.tech/abra/pkg/autocomplete"
+	"coopcloud.tech/abra/pkg/formatter"
+	"github.com/spf13/cobra"
+)
+
+var AppEnvCommand = &cobra.Command{
+	Use:     "env <domain> [flags]",
+	Aliases: []string{"e"},
+	Short:   "Show app .env values",
+	Example: "  abra app env 1312.net",
+	Args:    cobra.ExactArgs(1),
+	ValidArgsFunction: func(
+		cmd *cobra.Command,
+		args []string,
+		toComplete string) ([]string, cobra.ShellCompDirective) {
+		return autocomplete.AppNameComplete()
+	},
+	Run: func(cmd *cobra.Command, args []string) {
+		app := internal.ValidateApp(args)
+
+		var envKeys []string
+		for k := range app.Env {
+			envKeys = append(envKeys, k)
+		}
+
+		sort.Strings(envKeys)
+
+		var rows [][]string
+		for _, k := range envKeys {
+			rows = append(rows, []string{k, app.Env[k]})
+		}
+
+		overview := formatter.CreateOverview("ENV OVERVIEW", rows)
+		fmt.Println(overview)
+	},
+}

cli/app/labels.go

@@ -0,0 +1,139 @@
+package app
+
+import (
+	"context"
+	"fmt"
+	"sort"
+
+	"coopcloud.tech/abra/cli/internal"
+	"coopcloud.tech/abra/pkg/autocomplete"
+	"coopcloud.tech/abra/pkg/client"
+	"coopcloud.tech/abra/pkg/formatter"
+	"coopcloud.tech/abra/pkg/log"
+	"coopcloud.tech/abra/pkg/upstream/convert"
+	composetypes "github.com/docker/cli/cli/compose/types"
+	"github.com/docker/docker/api/types"
+	"github.com/docker/docker/api/types/filters"
+	dockerClient "github.com/docker/docker/client"
+	"github.com/spf13/cobra"
+)
+
+var AppLabelsCommand = &cobra.Command{
+	Use:     "labels <domain> [flags]",
+	Aliases: []string{"lb"},
+	Short:   "Show deployment labels",
+	Long:    "Both local recipe and live deployment labels are shown.",
+	Example: "  abra app labels 1312.net",
+	Args:    cobra.ExactArgs(1),
+	ValidArgsFunction: func(
+		cmd *cobra.Command,
+		args []string,
+		toComplete string) ([]string, cobra.ShellCompDirective) {
+		return autocomplete.AppNameComplete()
+	},
+	Run: func(cmd *cobra.Command, args []string) {
+		app := internal.ValidateApp(args)
+
+		if err := app.Recipe.Ensure(internal.GetEnsureContext()); err != nil {
+			log.Fatal(err)
+		}
+
+		cl, err := client.New(app.Server)
+		if err != nil {
+			log.Fatal(err)
+		}
+
+		remoteLabels, err := getLabels(cl, app.StackName())
+		if err != nil {
+			log.Fatal(err)
+		}
+
+		rows := [][]string{
+			{"DEPLOYED LABELS", "---"},
+		}
+
+		remoteLabelKeys := make([]string, 0, len(remoteLabels))
+		for k := range remoteLabels {
+			remoteLabelKeys = append(remoteLabelKeys, k)
+		}
+
+		sort.Strings(remoteLabelKeys)
+
+		for _, k := range remoteLabelKeys {
+			rows = append(rows, []string{
+				k,
+				remoteLabels[k],
+			})
+		}
+
+		if len(remoteLabelKeys) == 0 {
+			rows = append(rows, []string{"unknown"})
+		}
+
+		rows = append(rows, []string{"RECIPE LABELS", "---"})
+
+		config, err := app.Recipe.GetComposeConfig(app.Env)
+		if err != nil {
+			log.Fatal(err)
+		}
+
+		var localLabelKeys []string
+		var appServiceConfig composetypes.ServiceConfig
+		for _, service := range config.Services {
+			if service.Name == "app" {
+				appServiceConfig = service
+
+				for k := range service.Deploy.Labels {
+					localLabelKeys = append(localLabelKeys, k)
+				}
+			}
+		}
+
+		sort.Strings(localLabelKeys)
+
+		for _, k := range localLabelKeys {
+			rows = append(rows, []string{
+				k,
+				appServiceConfig.Deploy.Labels[k],
+			})
+		}
+
+		overview := formatter.CreateOverview("LABELS OVERVIEW", rows)
+		fmt.Println(overview)
+	},
+}
+
+// getLabels reads docker labels from running services in the format of "coop-cloud.${STACK_NAME}.${LABEL}".
+func getLabels(cl *dockerClient.Client, stackName string) (map[string]string, error) {
+	labels := make(map[string]string)
+
+	filter := filters.NewArgs()
+	filter.Add("label", fmt.Sprintf("%s=%s", convert.LabelNamespace, stackName))
+
+	services, err := cl.ServiceList(context.Background(), types.ServiceListOptions{Filters: filter})
+	if err != nil {
+		return labels, err
+	}
+
+	for _, service := range services {
+		if service.Spec.Name != fmt.Sprintf("%s_app", stackName) {
+			continue
+		}
+
+		for k, v := range service.Spec.Labels {
+			labels[k] = v
+		}
+	}
+
+	return labels, nil
+}
+
+func init() {
+	AppLabelsCommand.Flags().BoolVarP(
+		&internal.Chaos,
+		"chaos",
+		"C",
+		false,
+		"ignore uncommitted recipes changes",
+	)
+}

cli/app/list.go

@@ -0,0 +1,329 @@
+package app
+
+import (
+	"encoding/json"
+	"fmt"
+	"sort"
+	"strconv"
+	"strings"
+
+	"coopcloud.tech/abra/cli/internal"
+	appPkg "coopcloud.tech/abra/pkg/app"
+	"coopcloud.tech/abra/pkg/autocomplete"
+	"coopcloud.tech/abra/pkg/formatter"
+	"coopcloud.tech/abra/pkg/log"
+	"coopcloud.tech/tagcmp"
+	"github.com/spf13/cobra"
+)
+
+type appStatus struct {
+	Server       string `json:"server"`
+	Recipe       string `json:"recipe"`
+	AppName      string `json:"appName"`
+	Domain       string `json:"domain"`
+	Status       string `json:"status"`
+	Chaos        string `json:"chaos"`
+	ChaosVersion string `json:"chaosVersion"`
+	AutoUpdate   string `json:"autoUpdate"`
+	Version      string `json:"version"`
+	Upgrade      string `json:"upgrade"`
+}
+
+type serverStatus struct {
+	Apps             []appStatus `json:"apps"`
+	AppCount         int         `json:"appCount"`
+	VersionCount     int         `json:"versionCount"`
+	UnversionedCount int         `json:"unversionedCount"`
+	LatestCount      int         `json:"latestCount"`
+	UpgradeCount     int         `json:"upgradeCount"`
+}
+
+var AppListCommand = &cobra.Command{
+	Use:     "list [flags]",
+	Aliases: []string{"ls"},
+	Short:   "List all managed apps",
+	Long: `Generate a report of all managed apps.
+
+Use "--status/-S" flag to query all servers for the live deployment status.`,
+	Example: `  # list apps of all servers without live status
+  abra app ls
+
+  # list apps of a specific server with live status
+  abra app ls -s 1312.net -S
+
+  # list apps of all servers which match a specific recipe
+  abra app ls -r gitea`,
+	Args: cobra.NoArgs,
+	Run: func(cmd *cobra.Command, args []string) {
+		appFiles, err := appPkg.LoadAppFiles(listAppServer)
+		if err != nil {
+			log.Fatal(err)
+		}
+
+		apps, err := appPkg.GetApps(appFiles, recipeFilter)
+		if err != nil {
+			log.Fatal(err)
+		}
+
+		sort.Sort(appPkg.ByServerAndRecipe(apps))
+
+		statuses := make(map[string]map[string]string)
+		if status {
+			alreadySeen := make(map[string]bool)
+			for _, app := range apps {
+				if _, ok := alreadySeen[app.Server]; !ok {
+					alreadySeen[app.Server] = true
+				}
+			}
+
+			statuses, err = appPkg.GetAppStatuses(apps, internal.MachineReadable)
+			if err != nil {
+				log.Fatal(err)
+			}
+		}
+
+		var totalServersCount int
+		var totalAppsCount int
+		allStats := make(map[string]serverStatus)
+		for _, app := range apps {
+			var stats serverStatus
+			var ok bool
+			if stats, ok = allStats[app.Server]; !ok {
+				stats = serverStatus{}
+				if recipeFilter == "" {
+					// count server, no filtering
+					totalServersCount++
+				}
+			}
+
+			if app.Recipe.Name == recipeFilter || recipeFilter == "" {
+				if recipeFilter != "" {
+					// only count server if matches filter
+					totalServersCount++
+				}
+
+				appStats := appStatus{}
+				stats.AppCount++
+				totalAppsCount++
+
+				if status {
+					status := "unknown"
+					version := "unknown"
+					chaos := "unknown"
+					chaosVersion := "unknown"
+					autoUpdate := "unknown"
+					if statusMeta, ok := statuses[app.StackName()]; ok {
+						if currentVersion, exists := statusMeta["version"]; exists {
+							if currentVersion != "" {
+								version = currentVersion
+							}
+						}
+						if chaosDeploy, exists := statusMeta["chaos"]; exists {
+							chaos = chaosDeploy
+						}
+						if chaosDeployVersion, exists := statusMeta["chaosVersion"]; exists {
+							chaosVersion = chaosDeployVersion
+						}
+						if autoUpdateState, exists := statusMeta["autoUpdate"]; exists {
+							autoUpdate = autoUpdateState
+						}
+						if statusMeta["status"] != "" {
+							status = statusMeta["status"]
+						}
+						stats.VersionCount++
+					} else {
+						stats.UnversionedCount++
+					}
+
+					appStats.Status = status
+					appStats.Chaos = chaos
+					appStats.ChaosVersion = chaosVersion
+					appStats.Version = version
+					appStats.AutoUpdate = autoUpdate
+
+					var newUpdates []string
+					if version != "unknown" && chaosVersion == "unknown" {
+						if err := app.Recipe.EnsureExists(); err != nil {
+							log.Fatalf("unable to clone %s: %s", app.Name, err)
+						}
+
+						updates, err := app.Recipe.Tags()
+						if err != nil {
+							log.Fatalf("unable to retrieve tags for %s: %s", app.Name, err)
+						}
+
+						parsedVersion, err := tagcmp.Parse(version)
+						if err != nil {
+							log.Fatal(err)
+						}
+
+						for _, update := range updates {
+							parsedUpdate, err := tagcmp.Parse(update)
+							if err != nil {
+								log.Fatal(err)
+							}
+
+							if update != version && parsedUpdate.IsGreaterThan(parsedVersion) {
+								newUpdates = append(newUpdates, update)
+							}
+						}
+					}
+
+					if len(newUpdates) == 0 {
+						if version == "unknown" {
+							appStats.Upgrade = "unknown"
+						} else {
+							appStats.Upgrade = "latest"
+							stats.LatestCount++
+						}
+					} else {
+						newUpdates = internal.SortVersionsDesc(newUpdates)
+						appStats.Upgrade = strings.Join(newUpdates, "\n")
+						stats.UpgradeCount++
+					}
+				}
+
+				appStats.Server = app.Server
+				appStats.Recipe = app.Recipe.Name
+				appStats.AppName = app.Name
+				appStats.Domain = app.Domain
+
+				stats.Apps = append(stats.Apps, appStats)
+			}
+			allStats[app.Server] = stats
+		}
+
+		if internal.MachineReadable {
+			jsonstring, err := json.Marshal(allStats)
+			if err != nil {
+				log.Fatal(err)
+			} else {
+				fmt.Println(string(jsonstring))
+			}
+
+			return
+		}
+
+		alreadySeen := make(map[string]bool)
+		for _, app := range apps {
+			if _, ok := alreadySeen[app.Server]; ok {
+				continue
+			}
+
+			serverStat := allStats[app.Server]
+
+			headers := []string{"RECIPE", "DOMAIN", "SERVER"}
+			if status {
+				headers = append(headers, []string{
+					"STATUS",
+					"CHAOS",
+					"VERSION",
+					"UPGRADE",
+					"AUTOUPDATE"}...,
+				)
+			}
+
+			table, err := formatter.CreateTable()
+			if err != nil {
+				log.Fatal(err)
+			}
+
+			table.Headers(headers...)
+
+			var rows [][]string
+			for _, appStat := range serverStat.Apps {
+				row := []string{appStat.Recipe, appStat.Domain, appStat.Server}
+				if status {
+					chaosStatus := appStat.Chaos
+					if chaosStatus != "unknown" {
+						chaosEnabled, err := strconv.ParseBool(chaosStatus)
+						if err != nil {
+							log.Fatal(err)
+						}
+						if chaosEnabled && appStat.ChaosVersion != "unknown" {
+							chaosStatus = appStat.ChaosVersion
+						}
+					}
+
+					row = append(row, []string{
+						appStat.Status,
+						chaosStatus,
+						appStat.Version,
+						appStat.Upgrade,
+						appStat.AutoUpdate}...,
+					)
+				}
+
+				rows = append(rows, row)
+			}
+
+			table.Rows(rows...)
+
+			if len(rows) > 0 {
+				if err := formatter.PrintTable(table); err != nil {
+					log.Fatal(err)
+				}
+
+				if len(allStats) > 1 && len(rows) > 0 {
+					fmt.Println() // newline separator for multiple servers
+				}
+			}
+
+			alreadySeen[app.Server] = true
+		}
+	},
+}
+
+var (
+	status        bool
+	recipeFilter  string
+	listAppServer string
+)
+
+func init() {
+	AppListCommand.Flags().BoolVarP(
+		&status,
+		"status",
+		"S",
+		false,
+		"show app deployment status",
+	)
+
+	AppListCommand.Flags().StringVarP(
+		&recipeFilter,
+		"recipe",
+		"r",
+		"",
+		"show apps of a specific recipe",
+	)
+
+	AppListCommand.RegisterFlagCompletionFunc(
+		"recipe",
+		func(cmd *cobra.Command, args []string, toComplete string) ([]string, cobra.ShellCompDirective) {
+			return autocomplete.RecipeNameComplete()
+		},
+	)
+
+	AppListCommand.Flags().BoolVarP(
+		&internal.MachineReadable,
+		"machine",
+		"m",
+		false,
+		"print machine-readable output",
+	)
+
+	AppListCommand.Flags().StringVarP(
+		&listAppServer,
+		"server",
+		"s",
+		"",
+		"show apps of a specific server",
+	)
+
+	AppListCommand.RegisterFlagCompletionFunc(
+		"server",
+		func(cmd *cobra.Command, args []string, toComplete string) ([]string, cobra.ShellCompDirective) {
+			return autocomplete.ServerNameComplete()
+		},
+	)
+}

cli/app/logs.go

@@ -0,0 +1,107 @@
+package app
+
+import (
+	"context"
+	"fmt"
+
+	"coopcloud.tech/abra/cli/internal"
+	appPkg "coopcloud.tech/abra/pkg/app"
+	"coopcloud.tech/abra/pkg/autocomplete"
+	"coopcloud.tech/abra/pkg/client"
+	"coopcloud.tech/abra/pkg/log"
+	"coopcloud.tech/abra/pkg/logs"
+	"coopcloud.tech/abra/pkg/upstream/stack"
+	"github.com/spf13/cobra"
+)
+
+var AppLogsCommand = &cobra.Command{
+	Use:     "logs <domain> [service] [flags]",
+	Aliases: []string{"l"},
+	Short:   "Tail app logs",
+	Args:    cobra.RangeArgs(1, 2),
+	ValidArgsFunction: func(
+		cmd *cobra.Command,
+		args []string,
+		toComplete string) ([]string, cobra.ShellCompDirective) {
+		switch l := len(args); l {
+		case 0:
+			return autocomplete.AppNameComplete()
+		case 1:
+			app, err := appPkg.Get(args[0])
+			if err != nil {
+				errMsg := fmt.Sprintf("autocomplete failed: %s", err)
+				return []string{errMsg}, cobra.ShellCompDirectiveError
+			}
+			return autocomplete.ServiceNameComplete(app.Name)
+		default:
+			return nil, cobra.ShellCompDirectiveDefault
+		}
+	},
+	Run: func(cmd *cobra.Command, args []string) {
+		app := internal.ValidateApp(args)
+		stackName := app.StackName()
+
+		if err := app.Recipe.EnsureExists(); err != nil {
+			log.Fatal(err)
+		}
+
+		cl, err := client.New(app.Server)
+		if err != nil {
+			log.Fatal(err)
+		}
+
+		deployMeta, err := stack.IsDeployed(context.Background(), cl, stackName)
+		if err != nil {
+			log.Fatal(err)
+		}
+
+		if !deployMeta.IsDeployed {
+			log.Fatalf("%s is not deployed?", app.Name)
+		}
+
+		var serviceNames []string
+		if len(args) == 2 {
+			serviceNames = []string{args[1]}
+		}
+
+		f, err := app.Filters(true, false, serviceNames...)
+		if err != nil {
+			log.Fatal(err)
+		}
+
+		opts := logs.TailOpts{
+			AppName:  app.Name,
+			Services: serviceNames,
+			StdErr:   stdErr,
+			Since:    sinceLogs,
+			Filters:  f,
+		}
+
+		if err := logs.TailLogs(cl, opts); err != nil {
+			log.Fatal(err)
+		}
+	},
+}
+
+var (
+	stdErr    bool
+	sinceLogs string
+)
+
+func init() {
+	AppLogsCommand.Flags().BoolVarP(
+		&stdErr,
+		"stderr",
+		"s",
+		false,
+		"only tail stderr",
+	)
+
+	AppLogsCommand.Flags().StringVarP(
+		&sinceLogs,
+		"since",
+		"S",
+		"",
+		"tail logs since YYYY-MM-DDTHH:MM:SSZ",
+	)
+}

cli/app/new.go

@@ -0,0 +1,383 @@
+package app
+
+import (
+	"fmt"
+
+	"coopcloud.tech/abra/cli/internal"
+	"coopcloud.tech/abra/pkg/app"
+	appPkg "coopcloud.tech/abra/pkg/app"
+	"coopcloud.tech/abra/pkg/autocomplete"
+	"coopcloud.tech/abra/pkg/client"
+	"coopcloud.tech/abra/pkg/config"
+	"coopcloud.tech/abra/pkg/formatter"
+	"coopcloud.tech/abra/pkg/log"
+	recipePkg "coopcloud.tech/abra/pkg/recipe"
+	"coopcloud.tech/abra/pkg/secret"
+	"github.com/AlecAivazis/survey/v2"
+	"github.com/charmbracelet/lipgloss/table"
+	dockerClient "github.com/docker/docker/client"
+	"github.com/spf13/cobra"
+)
+
+var appNewDescription = `Creates a new app from a default recipe.
+
+This new app configuration is stored in your $ABRA_DIR directory under the
+appropriate server.
+
+This command does not deploy your app for you. You will need to run "abra app
+deploy <domain>" to do so.
+
+You can see what recipes are available (i.e. values for the [recipe] argument)
+by running "abra recipe ls".
+
+Recipe commit hashes are supported values for "[version]".
+
+Passing the "--secrets/-S" flag will automatically generate secrets for your
+app and store them encrypted at rest on the chosen target server. These
+generated secrets are only visible at generation time, so please take care to
+store them somewhere safe.
+
+You can use the "--pass/-P" to store these generated passwords locally in a
+pass store (see passwordstore.org for more). The pass command must be available
+on your $PATH.`
+
+var AppNewCommand = &cobra.Command{
+	Use:     "new [recipe] [version] [flags]",
+	Aliases: []string{"n"},
+	Short:   "Create a new app",
+	Long:    appNewDescription,
+	Args:    cobra.RangeArgs(0, 2),
+	ValidArgsFunction: func(
+		cmd *cobra.Command,
+		args []string,
+		toComplete string) ([]string, cobra.ShellCompDirective) {
+		switch l := len(args); l {
+		case 0:
+			return autocomplete.RecipeNameComplete()
+		case 1:
+			recipe := internal.ValidateRecipe(args, cmd.Name())
+			return autocomplete.RecipeVersionComplete(recipe.Name)
+		default:
+			return nil, cobra.ShellCompDirectiveDefault
+		}
+	},
+	Run: func(cmd *cobra.Command, args []string) {
+		recipe := internal.ValidateRecipe(args, cmd.Name())
+
+		if len(args) == 2 && internal.Chaos {
+			log.Fatal("cannot use [version] and --chaos together")
+		}
+
+		var recipeVersion string
+		if len(args) == 2 {
+			recipeVersion = args[1]
+		}
+
+		chaosVersion := config.CHAOS_DEFAULT
+		if internal.Chaos {
+			var err error
+			chaosVersion, err = recipe.ChaosVersion()
+			if err != nil {
+				log.Fatal(err)
+			}
+
+			recipeVersion = chaosVersion
+		} else {
+			if err := recipe.EnsureIsClean(); err != nil {
+				log.Fatal(err)
+			}
+
+			var recipeVersions recipePkg.RecipeVersions
+			if recipeVersion == "" {
+				var err error
+				recipeVersions, _, err = recipe.GetRecipeVersions()
+				if err != nil {
+					log.Fatal(err)
+				}
+			}
+
+			if len(recipeVersions) > 0 {
+				latest := recipeVersions[len(recipeVersions)-1]
+				for tag := range latest {
+					recipeVersion = tag
+				}
+
+				if _, err := recipe.EnsureVersion(recipeVersion); err != nil {
+					log.Fatal(err)
+				}
+			} else {
+				if err := recipe.EnsureLatest(); err != nil {
+					log.Fatal(err)
+				}
+
+				if recipeVersion == "" {
+					head, err := recipe.Head()
+					if err != nil {
+						log.Fatalf("failed to retrieve latest commit for %s: %s", recipe.Name, err)
+					}
+
+					recipeVersion = formatter.SmallSHA(head.String())
+				}
+			}
+		}
+
+		if err := ensureServerFlag(); err != nil {
+			log.Fatal(err)
+		}
+
+		if err := ensureDomainFlag(recipe, newAppServer); err != nil {
+			log.Fatal(err)
+		}
+
+		sanitisedAppName := appPkg.SanitiseAppName(appDomain)
+		log.Debugf("%s sanitised as %s for new app", appDomain, sanitisedAppName)
+
+		if err := appPkg.TemplateAppEnvSample(
+			recipe,
+			appDomain,
+			newAppServer,
+			appDomain,
+		); err != nil {
+			log.Fatal(err)
+		}
+
+		var appSecrets AppSecrets
+		var secretsTable *table.Table
+		if generateSecrets {
+			sampleEnv, err := recipe.SampleEnv()
+			if err != nil {
+				log.Fatal(err)
+			}
+
+			composeFiles, err := recipe.GetComposeFiles(sampleEnv)
+			if err != nil {
+				log.Fatal(err)
+			}
+
+			secretsConfig, err := secret.ReadSecretsConfig(
+				recipe.SampleEnvPath,
+				composeFiles,
+				appPkg.StackName(appDomain),
+			)
+			if err != nil {
+				log.Fatal(err)
+			}
+
+			if err := promptForSecrets(recipe.Name, secretsConfig); err != nil {
+				log.Fatal(err)
+			}
+
+			cl, err := client.New(newAppServer)
+			if err != nil {
+				log.Fatal(err)
+			}
+
+			appSecrets, err = createSecrets(cl, secretsConfig, sanitisedAppName)
+			if err != nil {
+				log.Fatal(err)
+			}
+
+			secretsTable, err = formatter.CreateTable()
+			if err != nil {
+				log.Fatal(err)
+			}
+
+			headers := []string{"NAME", "VALUE"}
+			secretsTable.Headers(headers...)
+
+			for name, val := range appSecrets {
+				secretsTable.Row(name, val)
+			}
+		}
+
+		if newAppServer == "default" {
+			newAppServer = "local"
+		}
+
+		log.Infof("%s created (version: %s)", appDomain, recipeVersion)
+
+		if len(appSecrets) > 0 {
+			rows := [][]string{}
+			for k, v := range appSecrets {
+				rows = append(rows, []string{k, v})
+			}
+
+			overview := formatter.CreateOverview("SECRETS OVERVIEW", rows)
+
+			fmt.Println(overview)
+
+			log.Warnf(
+				"secrets are %s shown again, please save them %s",
+				formatter.BoldUnderlineStyle.Render("NOT"),
+				formatter.BoldUnderlineStyle.Render("NOW"),
+			)
+		}
+
+		app, err := app.Get(appDomain)
+		if err != nil {
+			log.Fatal(err)
+		}
+
+		if err := app.WriteRecipeVersion(recipeVersion, false); err != nil {
+			log.Fatalf("writing recipe version failed: %s", err)
+		}
+	},
+}
+
+// AppSecrets represents all app secrest
+type AppSecrets map[string]string
+
+// createSecrets creates all secrets for a new app.
+func createSecrets(cl *dockerClient.Client, secretsConfig map[string]secret.Secret, sanitisedAppName string) (AppSecrets, error) {
+	// NOTE(d1): trim to match app.StackName() implementation
+	if len(sanitisedAppName) > config.MAX_SANITISED_APP_NAME_LENGTH {
+		log.Debugf("trimming %s to %s to avoid runtime limits", sanitisedAppName, sanitisedAppName[:config.MAX_SANITISED_APP_NAME_LENGTH])
+		sanitisedAppName = sanitisedAppName[:config.MAX_SANITISED_APP_NAME_LENGTH]
+	}
+
+	secrets, err := secret.GenerateSecrets(cl, secretsConfig, newAppServer)
+	if err != nil {
+		return nil, err
+	}
+
+	if saveInPass {
+		for secretName := range secrets {
+			secretValue := secrets[secretName]
+			if err := secret.PassInsertSecret(
+				secretValue,
+				secretName,
+				appDomain,
+				newAppServer,
+			); err != nil {
+				return nil, err
+			}
+		}
+	}
+
+	return secrets, nil
+}
+
+// ensureDomainFlag checks if the domain flag was used. if not, asks the user for it/
+func ensureDomainFlag(recipe recipePkg.Recipe, server string) error {
+	if appDomain == "" && !internal.NoInput {
+		prompt := &survey.Input{
+			Message: "Specify app domain",
+			Default: fmt.Sprintf("%s.%s", recipe.Name, server),
+		}
+		if err := survey.AskOne(prompt, &appDomain); err != nil {
+			return err
+		}
+	}
+
+	if appDomain == "" {
+		return fmt.Errorf("no domain provided")
+	}
+
+	return nil
+}
+
+// promptForSecrets asks if we should generate secrets for a new app.
+func promptForSecrets(recipeName string, secretsConfig map[string]secret.Secret) error {
+	if len(secretsConfig) == 0 {
+		log.Debugf("%s has no secrets to generate, skipping...", recipeName)
+		return nil
+	}
+
+	if !generateSecrets && !internal.NoInput {
+		prompt := &survey.Confirm{
+			Message: "Generate app secrets?",
+		}
+		if err := survey.AskOne(prompt, &generateSecrets); err != nil {
+			return err
+		}
+	}
+
+	return nil
+}
+
+// ensureServerFlag checks if the server flag was used. if not, asks the user for it.
+func ensureServerFlag() error {
+	servers, err := config.GetServers()
+	if err != nil {
+		return err
+	}
+
+	if len(servers) == 1 {
+		newAppServer = servers[0]
+		log.Infof("single server detected, choosing %s automatically", newAppServer)
+		return nil
+	}
+
+	if newAppServer == "" && !internal.NoInput {
+		prompt := &survey.Select{
+			Message: "Select app server:",
+			Options: servers,
+		}
+		if err := survey.AskOne(prompt, &newAppServer); err != nil {
+			return err
+		}
+	}
+
+	if newAppServer == "" {
+		return fmt.Errorf("no server provided")
+	}
+
+	return nil
+}
+
+var (
+	newAppServer    string
+	appDomain       string
+	saveInPass      bool
+	generateSecrets bool
+)
+
+func init() {
+	AppNewCommand.Flags().StringVarP(
+		&newAppServer,
+		"server",
+		"s",
+		"",
+		"specify server for new app",
+	)
+
+	AppNewCommand.RegisterFlagCompletionFunc(
+		"server",
+		func(cmd *cobra.Command, args []string, toComplete string) ([]string, cobra.ShellCompDirective) {
+			return autocomplete.ServerNameComplete()
+		},
+	)
+
+	AppNewCommand.Flags().StringVarP(
+		&appDomain,
+		"domain",
+		"D",
+		"",
+		"domain name for app",
+	)
+
+	AppNewCommand.Flags().BoolVarP(
+		&saveInPass,
+		"pass",
+		"p",
+		false,
+		"store secrets in a local pass store",
+	)
+
+	AppNewCommand.Flags().BoolVarP(
+		&generateSecrets,
+		"secrets",
+		"S",
+		false,
+		"automatically generate secrets",
+	)
+
+	AppNewCommand.Flags().BoolVarP(
+		&internal.Chaos,
+		"chaos",
+		"C",
+		false,
+		"ignore uncommitted recipes changes",
+	)
+
+}

cli/app/ps.go

@@ -0,0 +1,210 @@
+package app
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"sort"
+	"strings"
+
+	"coopcloud.tech/abra/cli/internal"
+	appPkg "coopcloud.tech/abra/pkg/app"
+	"coopcloud.tech/abra/pkg/autocomplete"
+	"coopcloud.tech/abra/pkg/client"
+	"coopcloud.tech/abra/pkg/config"
+	"coopcloud.tech/abra/pkg/formatter"
+	"coopcloud.tech/abra/pkg/log"
+	abraService "coopcloud.tech/abra/pkg/service"
+	stack "coopcloud.tech/abra/pkg/upstream/stack"
+	dockerFormatter "github.com/docker/cli/cli/command/formatter"
+	containerTypes "github.com/docker/docker/api/types/container"
+	"github.com/docker/docker/api/types/filters"
+	dockerClient "github.com/docker/docker/client"
+	"github.com/spf13/cobra"
+)
+
+var AppPsCommand = &cobra.Command{
+	Use:     "ps <domain> [flags]",
+	Aliases: []string{"p"},
+	Short:   "Check app deployment status",
+	Args:    cobra.ExactArgs(1),
+	ValidArgsFunction: func(
+		cmd *cobra.Command,
+		args []string,
+		toComplete string) ([]string, cobra.ShellCompDirective) {
+		return autocomplete.AppNameComplete()
+	},
+	Run: func(cmd *cobra.Command, args []string) {
+		app := internal.ValidateApp(args)
+
+		if err := app.Recipe.Ensure(internal.GetEnsureContext()); err != nil {
+			log.Fatal(err)
+		}
+
+		cl, err := client.New(app.Server)
+		if err != nil {
+			log.Fatal(err)
+		}
+
+		deployMeta, err := stack.IsDeployed(context.Background(), cl, app.StackName())
+		if err != nil {
+			log.Fatal(err)
+		}
+
+		if !deployMeta.IsDeployed {
+			log.Fatalf("%s is not deployed?", app.Name)
+		}
+
+		chaosVersion := config.CHAOS_DEFAULT
+		statuses, err := appPkg.GetAppStatuses([]appPkg.App{app}, true)
+		if statusMeta, ok := statuses[app.StackName()]; ok {
+			if isChaos, exists := statusMeta["chaos"]; exists && isChaos == "true" {
+				if cVersion, exists := statusMeta["chaosVersion"]; exists {
+					chaosVersion = cVersion
+					if strings.HasSuffix(chaosVersion, config.DIRTY_DEFAULT) {
+						chaosVersion = formatter.BoldDirtyDefault(chaosVersion)
+					}
+				}
+			}
+		}
+
+		showPSOutput(app, cl, deployMeta.Version, chaosVersion)
+	},
+}
+
+// showPSOutput renders ps output.
+func showPSOutput(app appPkg.App, cl *dockerClient.Client, deployedVersion, chaosVersion string) {
+	composeFiles, err := app.Recipe.GetComposeFiles(app.Env)
+	if err != nil {
+		log.Fatal(err)
+		return
+	}
+
+	deployOpts := stack.Deploy{
+		Composefiles: composeFiles,
+		Namespace:    app.StackName(),
+		Prune:        false,
+		ResolveImage: stack.ResolveImageAlways,
+	}
+	compose, err := appPkg.GetAppComposeConfig(app.Name, deployOpts, app.Env)
+	if err != nil {
+		log.Fatal(err)
+		return
+	}
+
+	services := compose.Services
+	sort.Slice(services, func(i, j int) bool {
+		return services[i].Name < services[j].Name
+	})
+
+	var rows [][]string
+	allContainerStats := make(map[string]map[string]string)
+	for _, service := range services {
+		filters := filters.NewArgs()
+		filters.Add("name", fmt.Sprintf("^%s_%s", app.StackName(), service.Name))
+
+		containers, err := cl.ContainerList(context.Background(), containerTypes.ListOptions{Filters: filters})
+		if err != nil {
+			log.Fatal(err)
+			return
+		}
+
+		var containerStats map[string]string
+		if len(containers) == 0 {
+			containerStats = map[string]string{
+				"version": deployedVersion,
+				"chaos":   chaosVersion,
+				"service": service.Name,
+				"image":   "unknown",
+				"created": "unknown",
+				"status":  "unknown",
+				"state":   "unknown",
+				"ports":   "unknown",
+			}
+		} else {
+			container := containers[0]
+			containerStats = map[string]string{
+				"version": deployedVersion,
+				"chaos":   chaosVersion,
+				"service": abraService.ContainerToServiceName(container.Names, app.StackName()),
+				"image":   formatter.RemoveSha(container.Image),
+				"created": formatter.HumanDuration(container.Created),
+				"status":  container.Status,
+				"state":   container.State,
+				"ports":   dockerFormatter.DisplayablePorts(container.Ports),
+			}
+		}
+
+		allContainerStats[containerStats["service"]] = containerStats
+
+		// NOTE(d1): don't clobber these variables for --machine output
+		dVersion := deployedVersion
+		cVersion := chaosVersion
+
+		if containerStats["service"] != "app" {
+			// NOTE(d1): don't repeat info which only relevant for the "app" service
+			dVersion = ""
+			cVersion = ""
+		}
+
+		row := []string{
+			containerStats["service"],
+			containerStats["status"],
+			containerStats["image"],
+			dVersion,
+			cVersion,
+		}
+
+		rows = append(rows, row)
+	}
+
+	if internal.MachineReadable {
+		rendered, err := json.Marshal(allContainerStats)
+		if err != nil {
+			log.Fatal("unable to convert to JSON: %s", err)
+		}
+
+		fmt.Println(string(rendered))
+
+		return
+	}
+
+	table, err := formatter.CreateTable()
+	if err != nil {
+		log.Fatal(err)
+	}
+
+	headers := []string{
+		"SERVICE",
+		"STATUS",
+		"IMAGE",
+		"VERSION",
+		"CHAOS",
+	}
+
+	table.
+		Headers(headers...).
+		Rows(rows...)
+
+	if err := formatter.PrintTable(table); err != nil {
+		log.Fatal(err)
+	}
+}
+
+func init() {
+	AppPsCommand.Flags().BoolVarP(
+		&internal.MachineReadable,
+		"machine",
+		"m",
+		false,
+		"print machine-readable output",
+	)
+
+	AppPsCommand.Flags().BoolVarP(
+		&internal.Chaos,
+		"chaos",
+		"C",
+		false,
+		"ignore uncommitted recipes changes",
+	)
+}

cli/app/remove.go

@@ -0,0 +1,144 @@
+package app
+
+import (
+	"context"
+	"fmt"
+	"os"
+
+	"coopcloud.tech/abra/cli/internal"
+	"coopcloud.tech/abra/pkg/autocomplete"
+	"coopcloud.tech/abra/pkg/client"
+	"coopcloud.tech/abra/pkg/log"
+	stack "coopcloud.tech/abra/pkg/upstream/stack"
+	"github.com/AlecAivazis/survey/v2"
+	"github.com/docker/docker/api/types"
+	"github.com/spf13/cobra"
+)
+
+var AppRemoveCommand = &cobra.Command{
+	Use:     "remove <domain> [flags]",
+	Aliases: []string{"rm"},
+	Short:   "Remove all app data, locally and remotely",
+	Long: `Remove everything related to an app which is already undeployed.
+
+By default, it will prompt for confirmation before proceeding. All secrets,
+volumes and the local app env file will be deleted.
+
+Only run this command when you are sure you want to completely remove the app
+and all associated app data. This is a destructive action, Be Careful!
+
+If you would like to delete specific volumes or secrets, please use removal
+sub-commands under "app volume" and "app secret" instead.
+
+Please note, if you delete the local app env file without removing volumes and
+secrets first, Abra will *not* be able to help you remove them afterwards.
+
+To delete everything without prompt, use the "--force/-f" or the "--no-input/n"
+flag.`,
+	Example: "  abra app remove 1312.net",
+	Args:    cobra.ExactArgs(1),
+	ValidArgsFunction: func(
+		cmd *cobra.Command,
+		args []string,
+		toComplete string) ([]string, cobra.ShellCompDirective) {
+		return autocomplete.AppNameComplete()
+	},
+	Run: func(cmd *cobra.Command, args []string) {
+		app := internal.ValidateApp(args)
+
+		if !internal.Force && !internal.NoInput {
+			log.Warnf("ALERTA ALERTA: deleting %s data and config (local/remote)", app.Name)
+
+			response := false
+			prompt := &survey.Confirm{Message: "are you sure?"}
+			if err := survey.AskOne(prompt, &response); err != nil {
+				log.Fatal(err)
+			}
+
+			if !response {
+				log.Fatal("aborting as requested")
+			}
+		}
+
+		cl, err := client.New(app.Server)
+		if err != nil {
+			log.Fatal(err)
+		}
+
+		deployMeta, err := stack.IsDeployed(context.Background(), cl, app.StackName())
+		if err != nil {
+			log.Fatal(err)
+		}
+		if deployMeta.IsDeployed {
+			log.Fatalf("%s is still deployed. Run \"abra app undeploy %s\"", app.Name, app.Name)
+		}
+
+		fs, err := app.Filters(false, false)
+		if err != nil {
+			log.Fatal(err)
+		}
+
+		secretList, err := cl.SecretList(context.Background(), types.SecretListOptions{Filters: fs})
+		if err != nil {
+			log.Fatal(err)
+		}
+
+		secrets := make(map[string]string)
+		var secretNames []string
+
+		for _, cont := range secretList {
+			secrets[cont.Spec.Annotations.Name] = cont.ID // we have to map the names to ID's
+			secretNames = append(secretNames, cont.Spec.Annotations.Name)
+		}
+
+		if len(secrets) > 0 {
+			for _, name := range secretNames {
+				err := cl.SecretRemove(context.Background(), secrets[name])
+				if err != nil {
+					log.Fatal(err)
+				}
+				log.Info(fmt.Sprintf("secret: %s removed", name))
+			}
+		} else {
+			log.Info("no secrets to remove")
+		}
+
+		fs, err = app.Filters(false, true)
+		if err != nil {
+			log.Fatal(err)
+		}
+
+		volumeList, err := client.GetVolumes(cl, context.Background(), app.Server, fs)
+		if err != nil {
+			log.Fatal(err)
+		}
+		volumeNames := client.GetVolumeNames(volumeList)
+
+		if len(volumeNames) > 0 {
+			err := client.RemoveVolumes(cl, context.Background(), volumeNames, internal.Force, 5)
+			if err != nil {
+				log.Fatalf("removing volumes failed: %s", err)
+			}
+
+			log.Infof("%d volumes removed successfully", len(volumeNames))
+		} else {
+			log.Info("no volumes to remove")
+		}
+
+		if err = os.Remove(app.Path); err != nil {
+			log.Fatal(err)
+		}
+
+		log.Info(fmt.Sprintf("file: %s removed", app.Path))
+	},
+}
+
+func init() {
+	AppRemoveCommand.Flags().BoolVarP(
+		&internal.Force,
+		"force",
+		"f",
+		false,
+		"perform action without further prompt",
+	)
+}

cli/app/restart.go

@@ -0,0 +1,165 @@
+package app
+
+import (
+	"context"
+	"fmt"
+
+	"coopcloud.tech/abra/cli/internal"
+	appPkg "coopcloud.tech/abra/pkg/app"
+	"coopcloud.tech/abra/pkg/autocomplete"
+	"coopcloud.tech/abra/pkg/client"
+	"coopcloud.tech/abra/pkg/log"
+	"coopcloud.tech/abra/pkg/ui"
+	upstream "coopcloud.tech/abra/pkg/upstream/service"
+	stack "coopcloud.tech/abra/pkg/upstream/stack"
+	"github.com/docker/docker/api/types"
+	"github.com/spf13/cobra"
+)
+
+var AppRestartCommand = &cobra.Command{
+	Use:     "restart <domain> [[service] | --all-services] [flags]",
+	Aliases: []string{"re"},
+	Short:   "Restart an app",
+	Long: `This command restarts services within a deployed app.
+
+Run "abra app ps <domain>" to see a list of service names.
+
+Pass "--all-services/-a" to restart all services.`,
+	Example: `  # restart a single app service
+  abra app restart 1312.net app
+
+  # restart all app services
+  abra app restart 1312.net -a`,
+	Args: cobra.RangeArgs(1, 2),
+	ValidArgsFunction: func(
+		cmd *cobra.Command,
+		args []string,
+		toComplete string) ([]string, cobra.ShellCompDirective) {
+		switch l := len(args); l {
+		case 0:
+			return autocomplete.AppNameComplete()
+		case 1:
+			if !allServices {
+				return autocomplete.ServiceNameComplete(args[0])
+			}
+			return nil, cobra.ShellCompDirectiveDefault
+		default:
+			return nil, cobra.ShellCompDirectiveError
+		}
+	},
+	Run: func(cmd *cobra.Command, args []string) {
+		app := internal.ValidateApp(args)
+
+		if err := app.Recipe.Ensure(internal.GetEnsureContext()); err != nil {
+			log.Fatal(err)
+		}
+
+		var serviceName string
+		if len(args) == 2 {
+			serviceName = args[1]
+		}
+
+		if serviceName == "" && !allServices {
+			log.Fatal("missing [service]")
+		}
+
+		if serviceName != "" && allServices {
+			log.Fatal("cannot use [service] and --all-services/-a together")
+		}
+
+		var serviceNames []string
+		if allServices {
+			var err error
+			serviceNames, err = appPkg.GetAppServiceNames(app.Name)
+			if err != nil {
+				log.Fatal(err)
+			}
+		} else {
+			serviceNames = append(serviceNames, serviceName)
+		}
+
+		cl, err := client.New(app.Server)
+		if err != nil {
+			log.Fatal(err)
+		}
+
+		deployMeta, err := stack.IsDeployed(context.Background(), cl, app.StackName())
+		if err != nil {
+			log.Fatal(err)
+		}
+
+		if !deployMeta.IsDeployed {
+			log.Fatalf("%s is not deployed?", app.Name)
+		}
+
+		for _, serviceName := range serviceNames {
+			stackServiceName := fmt.Sprintf("%s_%s", app.StackName(), serviceName)
+
+			service, _, err := cl.ServiceInspectWithRaw(
+				context.Background(),
+				stackServiceName,
+				types.ServiceInspectOptions{},
+			)
+			if err != nil {
+				log.Fatal(err)
+			}
+
+			log.Debugf("attempting to scale %s to 0", stackServiceName)
+
+			if err := upstream.RunServiceScale(context.Background(), cl, stackServiceName, 0); err != nil {
+				log.Fatal(err)
+			}
+
+			f, err := app.Filters(true, false, serviceName)
+			if err != nil {
+				log.Fatal(err)
+			}
+
+			waitOpts := stack.WaitOpts{
+				Services:   []ui.ServiceMeta{{Name: stackServiceName, ID: service.ID}},
+				AppName:    app.Name,
+				ServerName: app.Server,
+				Filters:    f,
+				NoLog:      true,
+				Quiet:      true,
+			}
+
+			if err := stack.WaitOnServices(cmd.Context(), cl, waitOpts); err != nil {
+				log.Fatal(err)
+			}
+
+			log.Debugf("%s has been scaled to 0", stackServiceName)
+			log.Debugf("attempting to scale %s to 1", stackServiceName)
+
+			if err := upstream.RunServiceScale(context.Background(), cl, stackServiceName, 1); err != nil {
+				log.Fatal(err)
+			}
+
+			if err := stack.WaitOnServices(cmd.Context(), cl, waitOpts); err != nil {
+				log.Fatal(err)
+			}
+
+			log.Debugf("%s has been scaled to 1", stackServiceName)
+			log.Infof("%s service successfully restarted", serviceName)
+		}
+	},
+}
+
+var allServices bool
+
+func init() {
+	AppRestartCommand.Flags().BoolVarP(
+		&internal.Chaos,
+		"chaos",
+		"C",
+		false,
+		"ignore uncommitted recipes changes",
+	)
+	AppRestartCommand.Flags().BoolVarP(
+		&allServices,
+		"all-services",
+		"a",
+		false,
+		"restart all services",
+	)
+}

cli/app/restore.go

@@ -0,0 +1,135 @@
+package app
+
+import (
+	"fmt"
+	"strings"
+
+	"coopcloud.tech/abra/cli/internal"
+	"coopcloud.tech/abra/pkg/autocomplete"
+	"coopcloud.tech/abra/pkg/client"
+	"coopcloud.tech/abra/pkg/log"
+	"github.com/spf13/cobra"
+)
+
+var AppRestoreCommand = &cobra.Command{
+	Use:     "restore <domain> [flags]",
+	Aliases: []string{"rs"},
+	Short:   "Restore a snapshot",
+	Long: `Snapshots are restored while apps are deployed.
+
+Some restore scenarios may require service / app restarts.`,
+	Args: cobra.ExactArgs(1),
+	ValidArgsFunction: func(
+		cmd *cobra.Command,
+		args []string,
+		toComplete string) ([]string, cobra.ShellCompDirective) {
+		return autocomplete.AppNameComplete()
+	},
+	Run: func(cmd *cobra.Command, args []string) {
+		app := internal.ValidateApp(args)
+
+		if err := app.Recipe.Ensure(internal.GetEnsureContext()); err != nil {
+			log.Fatal(err)
+		}
+
+		cl, err := client.New(app.Server)
+		if err != nil {
+			log.Fatal(err)
+		}
+
+		targetContainer, err := internal.RetrieveBackupBotContainer(cl)
+		if err != nil {
+			log.Fatal(err)
+		}
+
+		execEnv := []string{
+			fmt.Sprintf("SERVICE=%s", app.Domain),
+			"MACHINE_LOGS=true",
+		}
+
+		if snapshot != "" {
+			log.Debugf("including SNAPSHOT=%s in backupbot exec invocation", snapshot)
+			execEnv = append(execEnv, fmt.Sprintf("SNAPSHOT=%s", snapshot))
+		}
+
+		if targetPath != "" {
+			log.Debugf("including TARGET=%s in backupbot exec invocation", targetPath)
+			execEnv = append(execEnv, fmt.Sprintf("TARGET=%s", targetPath))
+		}
+
+		if internal.NoInput {
+			log.Debugf("including NONINTERACTIVE=%v in backupbot exec invocation", internal.NoInput)
+			execEnv = append(execEnv, fmt.Sprintf("NONINTERACTIVE=%v", internal.NoInput))
+		}
+
+		if len(volumes) > 0 {
+			allVolumes := strings.Join(volumes, ",")
+			log.Debugf("including VOLUMES=%s in backupbot exec invocation", allVolumes)
+			execEnv = append(execEnv, fmt.Sprintf("VOLUMES=%s", allVolumes))
+		}
+
+		if len(services) > 0 {
+			allServices := strings.Join(services, ",")
+			log.Debugf("including CONTAINER=%s in backupbot exec invocation", allServices)
+			execEnv = append(execEnv, fmt.Sprintf("CONTAINER=%s", allServices))
+		}
+
+		if hooks {
+			log.Debugf("including NO_COMMANDS=%v in backupbot exec invocation", false)
+			execEnv = append(execEnv, fmt.Sprintf("NO_COMMANDS=%v", false))
+		}
+
+		if _, err := internal.RunBackupCmdRemote(cl, "restore", targetContainer.ID, execEnv); err != nil {
+			log.Fatal(err)
+		}
+	},
+}
+
+var (
+	targetPath string
+	hooks      bool
+	services   []string
+	volumes    []string
+)
+
+func init() {
+	AppRestoreCommand.Flags().StringVarP(
+		&targetPath,
+		"target",
+		"t",
+		"/",
+		"target path",
+	)
+
+	AppRestoreCommand.Flags().StringArrayVarP(
+		&services,
+		"services",
+		"s",
+		[]string{},
+		"restore specific services",
+	)
+
+	AppRestoreCommand.Flags().StringArrayVarP(
+		&volumes,
+		"volumes",
+		"v",
+		[]string{},
+		"restore specific volumes",
+	)
+
+	AppRestoreCommand.Flags().BoolVarP(
+		&hooks,
+		"hooks",
+		"H",
+		false,
+		"enable pre/post-hook command execution",
+	)
+
+	AppRestoreCommand.Flags().BoolVarP(
+		&internal.Chaos,
+		"chaos",
+		"C",
+		false,
+		"ignore uncommitted recipes changes",
+	)
+}

cli/app/rollback.go

@@ -0,0 +1,343 @@
+package app
+
+import (
+	"fmt"
+
+	"coopcloud.tech/abra/pkg/app"
+	appPkg "coopcloud.tech/abra/pkg/app"
+	"coopcloud.tech/abra/pkg/autocomplete"
+	"coopcloud.tech/abra/pkg/config"
+	"coopcloud.tech/abra/pkg/envfile"
+	"coopcloud.tech/abra/pkg/formatter"
+	"coopcloud.tech/abra/pkg/lint"
+	stack "coopcloud.tech/abra/pkg/upstream/stack"
+	"coopcloud.tech/tagcmp"
+
+	"coopcloud.tech/abra/cli/internal"
+	"coopcloud.tech/abra/pkg/client"
+	"coopcloud.tech/abra/pkg/log"
+	"github.com/AlecAivazis/survey/v2"
+	"github.com/spf13/cobra"
+)
+
+var AppRollbackCommand = &cobra.Command{
+	Use:     "rollback <domain> [version] [flags]",
+	Aliases: []string{"rl"},
+	Short:   "Roll an app back to a previous version",
+	Long: `This command rolls an app back to a previous version.
+
+Unlike "abra app deploy", chaos operations are not supported here. Only recipe
+versions are supported values for "[version]".
+
+It is possible to "--force/-f" an downgrade if you want to re-deploy a specific
+version.
+
+Only the deployed version is consulted when trying to determine what downgrades
+are available. The live deployment version is the "source of truth" in this
+case. The stored .env version is not consulted.
+
+A downgrade can be destructive, please ensure you have a copy of your app data
+beforehand. See "abra app backup" for more.`,
+	Example: ` # standard rollback
+  abra app rollback 1312.net
+
+  # rollback to specific version
+  abra app rollback 1312.net 2.0.0+1.2.3`,
+	Args: cobra.RangeArgs(1, 2),
+	ValidArgsFunction: func(
+		cmd *cobra.Command,
+		args []string,
+		toComplete string) ([]string, cobra.ShellCompDirective) {
+		switch l := len(args); l {
+		case 0:
+			return autocomplete.AppNameComplete()
+		case 1:
+			app, err := appPkg.Get(args[0])
+			if err != nil {
+				errMsg := fmt.Sprintf("autocomplete failed: %s", err)
+				return []string{errMsg}, cobra.ShellCompDirectiveError
+			}
+			return autocomplete.RecipeVersionComplete(app.Recipe.Name)
+		default:
+			return nil, cobra.ShellCompDirectiveError
+		}
+	},
+	Run: func(cmd *cobra.Command, args []string) {
+		var (
+			downgradeWarnMessages []string
+			chosenDowngrade       string
+			availableDowngrades   []string
+		)
+
+		app := internal.ValidateApp(args)
+
+		if err := app.Recipe.Ensure(internal.GetEnsureContext()); err != nil {
+			log.Fatal(err)
+		}
+
+		cl, err := client.New(app.Server)
+		if err != nil {
+			log.Fatal(err)
+		}
+
+		deployMeta, err := ensureDeployed(cl, app)
+		if err != nil {
+			log.Fatal(err)
+		}
+
+		if err := lint.LintForErrors(app.Recipe); err != nil {
+			log.Fatal(err)
+		}
+
+		versions, err := app.Recipe.Tags()
+		if err != nil {
+			log.Fatal(err)
+		}
+
+		// NOTE(d1): we've no idea what the live deployment version is, so every
+		// possible downgrade can be shown. it's up to the user to make the choice
+		if deployMeta.Version == config.UNKNOWN_DEFAULT {
+			availableDowngrades = versions
+		}
+
+		if len(args) == 2 && args[1] != "" {
+			chosenDowngrade = args[1]
+
+			if err := validateDowngradeVersionArg(chosenDowngrade, app, deployMeta); err != nil {
+				log.Fatal(err)
+			}
+
+			availableDowngrades = append(availableDowngrades, chosenDowngrade)
+		}
+
+		if deployMeta.Version != config.UNKNOWN_DEFAULT && chosenDowngrade == "" {
+			downgradeAvailable, err := ensureDowngradesAvailable(versions, &availableDowngrades, deployMeta)
+			if err != nil {
+				log.Fatal(err)
+			}
+
+			if !downgradeAvailable {
+				log.Info("no available downgrades")
+				return
+			}
+		}
+
+		if internal.Force || internal.NoInput || chosenDowngrade != "" {
+			if len(availableDowngrades) > 0 {
+				chosenDowngrade = availableDowngrades[len(availableDowngrades)-1]
+			}
+		} else {
+			if err := chooseDowngrade(availableDowngrades, deployMeta, &chosenDowngrade); err != nil {
+				log.Fatal(err)
+			}
+		}
+
+		if internal.Force &&
+			chosenDowngrade == "" &&
+			deployMeta.Version != config.UNKNOWN_DEFAULT {
+			chosenDowngrade = deployMeta.Version
+		}
+
+		if chosenDowngrade == "" {
+			log.Fatal("unknown deployed version, unable to downgrade")
+		}
+
+		log.Debugf("choosing %s as version to rollback", chosenDowngrade)
+
+		if _, err := app.Recipe.EnsureVersion(chosenDowngrade); err != nil {
+			log.Fatal(err)
+		}
+
+		abraShEnv, err := envfile.ReadAbraShEnvVars(app.Recipe.AbraShPath)
+		if err != nil {
+			log.Fatal(err)
+		}
+		for k, v := range abraShEnv {
+			app.Env[k] = v
+		}
+
+		composeFiles, err := app.Recipe.GetComposeFiles(app.Env)
+		if err != nil {
+			log.Fatal(err)
+		}
+
+		stackName := app.StackName()
+		deployOpts := stack.Deploy{
+			Composefiles: composeFiles,
+			Namespace:    stackName,
+			Prune:        false,
+			ResolveImage: stack.ResolveImageAlways,
+			Detach:       false,
+		}
+
+		compose, err := appPkg.GetAppComposeConfig(app.Name, deployOpts, app.Env)
+		if err != nil {
+			log.Fatal(err)
+		}
+
+		appPkg.ExposeAllEnv(stackName, compose, app.Env)
+		appPkg.SetRecipeLabel(compose, stackName, app.Recipe.Name)
+		appPkg.SetChaosLabel(compose, stackName, internal.Chaos)
+		if internal.Chaos {
+			appPkg.SetChaosVersionLabel(compose, stackName, chosenDowngrade)
+		}
+		appPkg.SetUpdateLabel(compose, stackName, app.Env)
+
+		// NOTE(d1): no release notes implemeneted for rolling back
+		if err := internal.DeployOverview(
+			app,
+			deployMeta.Version,
+			chosenDowngrade,
+			"",
+			downgradeWarnMessages,
+		); err != nil {
+			log.Fatal(err)
+		}
+
+		stack.WaitTimeout, err = appPkg.GetTimeoutFromLabel(compose, stackName)
+		if err != nil {
+			log.Fatal(err)
+		}
+
+		log.Debugf("set waiting timeout to %d second(s)", stack.WaitTimeout)
+
+		serviceNames, err := appPkg.GetAppServiceNames(app.Name)
+		if err != nil {
+			log.Fatal(err)
+		}
+
+		f, err := app.Filters(true, false, serviceNames...)
+		if err != nil {
+			log.Fatal(err)
+		}
+
+		if err := stack.RunDeploy(
+			cl,
+			deployOpts,
+			compose,
+			stackName,
+			app.Server,
+			internal.DontWaitConverge,
+			f,
+		); err != nil {
+			log.Fatal(err)
+		}
+
+		if err := app.WriteRecipeVersion(chosenDowngrade, false); err != nil {
+			log.Fatalf("writing recipe version failed: %s", err)
+		}
+	},
+}
+
+// chooseDowngrade prompts the user to choose an downgrade interactively.
+func chooseDowngrade(
+	availableDowngrades []string,
+	deployMeta stack.DeployMeta,
+	chosenDowngrade *string,
+) error {
+	msg := fmt.Sprintf("please select a downgrade (version: %s):", deployMeta.Version)
+
+	if deployMeta.IsChaos {
+		chaosVersion := formatter.BoldDirtyDefault(deployMeta.ChaosVersion)
+
+		msg = fmt.Sprintf(
+			"please select a downgrade (version: %s, chaos: %s):",
+			deployMeta.Version,
+			chaosVersion,
+		)
+	}
+
+	prompt := &survey.Select{
+		Message: msg,
+		Options: internal.SortVersionsDesc(availableDowngrades),
+	}
+
+	if err := survey.AskOne(prompt, chosenDowngrade); err != nil {
+		return err
+	}
+
+	return nil
+}
+
+// validateDownpgradeVersionArg validates the specific version.
+func validateDowngradeVersionArg(
+	specificVersion string,
+	app app.App,
+	deployMeta stack.DeployMeta,
+) error {
+	parsedDeployedVersion, err := tagcmp.Parse(deployMeta.Version)
+	if err != nil {
+		return fmt.Errorf("current deployment '%s' is not a known version for %s", deployMeta.Version, app.Recipe.Name)
+	}
+
+	parsedSpecificVersion, err := tagcmp.Parse(specificVersion)
+	if err != nil {
+		return fmt.Errorf("'%s' is not a known version for %s", specificVersion, app.Recipe.Name)
+	}
+
+	if parsedSpecificVersion.IsGreaterThan(parsedDeployedVersion) &&
+		!parsedSpecificVersion.Equals(parsedDeployedVersion) {
+		return fmt.Errorf("%s is not a downgrade for %s?", deployMeta.Version, specificVersion)
+	}
+
+	if parsedSpecificVersion.Equals(parsedDeployedVersion) && !internal.Force {
+		return fmt.Errorf("%s is not a downgrade for %s?", deployMeta.Version, specificVersion)
+	}
+
+	return nil
+}
+
+// ensureDowngradesAvailable ensures that there are available downgrades.
+func ensureDowngradesAvailable(
+	versions []string,
+	availableDowngrades *[]string,
+	deployMeta stack.DeployMeta,
+) (bool, error) {
+	parsedDeployedVersion, err := tagcmp.Parse(deployMeta.Version)
+	if err != nil {
+		return false, err
+	}
+
+	for _, version := range versions {
+		parsedVersion, err := tagcmp.Parse(version)
+		if err != nil {
+			return false, err
+		}
+
+		if parsedVersion.IsLessThan(parsedDeployedVersion) &&
+			!(parsedVersion.Equals(parsedDeployedVersion)) {
+			*availableDowngrades = append(*availableDowngrades, version)
+		}
+	}
+
+	if len(*availableDowngrades) == 0 && !internal.Force {
+		return false, nil
+	}
+
+	return true, nil
+}
+
+func init() {
+	AppRollbackCommand.Flags().BoolVarP(
+		&internal.Force,
+		"force",
+		"f",
+		false,
+		"perform action without further prompt",
+	)
+
+	AppRollbackCommand.Flags().BoolVarP(
+		&internal.NoDomainChecks,
+		"no-domain-checks",
+		"D",
+		false,
+		"disable public DNS checks",
+	)
+
+	AppRollbackCommand.Flags().BoolVarP(
+		&internal.DontWaitConverge, "no-converge-checks",
+		"c",
+		false,
+		"disable converge logic checks",
+	)
+}

cli/app/run.go

@@ -0,0 +1,114 @@
+package app
+
+import (
+	"context"
+	"fmt"
+
+	"coopcloud.tech/abra/cli/internal"
+	"coopcloud.tech/abra/pkg/autocomplete"
+	"coopcloud.tech/abra/pkg/client"
+	containerPkg "coopcloud.tech/abra/pkg/container"
+	"coopcloud.tech/abra/pkg/log"
+	"coopcloud.tech/abra/pkg/upstream/container"
+	"github.com/docker/cli/cli/command"
+	containertypes "github.com/docker/docker/api/types/container"
+	"github.com/docker/docker/api/types/filters"
+	"github.com/spf13/cobra"
+)
+
+var AppRunCommand = &cobra.Command{
+	Use:     "run <domain> <service> <cmd> [[args] [flags] | [flags] -- [args]]",
+	Aliases: []string{"r"},
+	Short:   "Run a command inside a service container",
+	Example: `  # run <cmd> with args/flags
+  abra app run 1312.net app -- ls -lha
+
+  # run <cmd> without args/flags
+  abra app run 1312.net app bash --user nobody
+
+  # run <cmd> with both kinds of args/flags 
+  abra app run 1312.net app --user nobody -- ls -lha`,
+	Args: cobra.MinimumNArgs(3),
+	ValidArgsFunction: func(
+		cmd *cobra.Command,
+		args []string,
+		toComplete string) ([]string, cobra.ShellCompDirective) {
+		switch l := len(args); l {
+		case 0:
+			return autocomplete.AppNameComplete()
+		case 1:
+			return autocomplete.ServiceNameComplete(args[0])
+		case 2:
+			return autocomplete.CommandNameComplete(args[0])
+		default:
+			return nil, cobra.ShellCompDirectiveError
+		}
+	},
+	Run: func(cmd *cobra.Command, args []string) {
+		app := internal.ValidateApp(args)
+
+		cl, err := client.New(app.Server)
+		if err != nil {
+			log.Fatal(err)
+		}
+
+		serviceName := args[1]
+		stackAndServiceName := fmt.Sprintf("^%s_%s", app.StackName(), serviceName)
+
+		filters := filters.NewArgs()
+		filters.Add("name", stackAndServiceName)
+
+		targetContainer, err := containerPkg.GetContainer(context.Background(), cl, filters, false)
+		if err != nil {
+			log.Fatal(err)
+		}
+
+		userCmd := args[2:]
+		execCreateOpts := containertypes.ExecOptions{
+			AttachStderr: true,
+			AttachStdin:  true,
+			AttachStdout: true,
+			Cmd:          userCmd,
+			Detach:       false,
+			Tty:          true,
+		}
+
+		if runAsUser != "" {
+			execCreateOpts.User = runAsUser
+		}
+		if noTTY {
+			execCreateOpts.Tty = false
+		}
+
+		dcli, err := command.NewDockerCli()
+		if err != nil {
+			log.Fatal(err)
+		}
+
+		if _, err := container.RunExec(dcli, cl, targetContainer.ID, &execCreateOpts); err != nil {
+			log.Fatal(err)
+		}
+	},
+}
+
+var (
+	noTTY     bool
+	runAsUser string
+)
+
+func init() {
+	AppRunCommand.Flags().BoolVarP(&noTTY,
+		"no-tty",
+		"t",
+		false,
+		"do not request a TTY",
+	)
+
+	AppRunCommand.Flags().StringVarP(
+		&runAsUser,
+		"user",
+		"u",
+		"",
+		"run command as user",
+	)
+}

cli/app/secret.go

@@ -0,0 +1,529 @@
+package app
+
+import (
+	"context"
+	"fmt"
+	"os"
+	"strconv"
+	"strings"
+
+	"coopcloud.tech/abra/cli/internal"
+	appPkg "coopcloud.tech/abra/pkg/app"
+	"coopcloud.tech/abra/pkg/autocomplete"
+	"coopcloud.tech/abra/pkg/client"
+	"coopcloud.tech/abra/pkg/formatter"
+	"coopcloud.tech/abra/pkg/log"
+	"coopcloud.tech/abra/pkg/secret"
+	"github.com/docker/docker/api/types"
+	dockerClient "github.com/docker/docker/client"
+	"github.com/spf13/cobra"
+)
+
+var AppSecretGenerateCommand = &cobra.Command{
+	Use:     "generate <domain> [[secret] [version] | --all] [flags]",
+	Aliases: []string{"g"},
+	Short:   "Generate secrets",
+	Args:    cobra.RangeArgs(1, 3),
+	ValidArgsFunction: func(
+		cmd *cobra.Command,
+		args []string,
+		toComplete string) ([]string, cobra.ShellCompDirective) {
+		switch l := len(args); l {
+		case 0:
+			return autocomplete.AppNameComplete()
+		case 1:
+			app, err := appPkg.Get(args[0])
+			if err != nil {
+				errMsg := fmt.Sprintf("autocomplete failed: %s", err)
+				return []string{errMsg}, cobra.ShellCompDirectiveError
+			}
+			return autocomplete.SecretComplete(app.Recipe.Name)
+		default:
+			return nil, cobra.ShellCompDirectiveDefault
+		}
+	},
+	Run: func(cmd *cobra.Command, args []string) {
+		app := internal.ValidateApp(args)
+
+		if err := app.Recipe.Ensure(internal.GetEnsureContext()); err != nil {
+			log.Fatal(err)
+		}
+
+		if len(args) <= 2 && !generateAllSecrets {
+			log.Fatal("missing arguments [secret]/[version] or '--all'")
+		}
+
+		if len(args) > 2 && generateAllSecrets {
+			log.Fatal("cannot use '[secret] [version]' and '--all' together")
+		}
+
+		composeFiles, err := app.Recipe.GetComposeFiles(app.Env)
+		if err != nil {
+			log.Fatal(err)
+		}
+
+		secrets, err := secret.ReadSecretsConfig(app.Path, composeFiles, app.StackName())
+		if err != nil {
+			log.Fatal(err)
+		}
+
+		if !generateAllSecrets {
+			secretName := args[1]
+			secretVersion := args[2]
+			s, ok := secrets[secretName]
+			if !ok {
+				log.Fatalf("%s doesn't exist in the env config?", secretName)
+			}
+			s.Version = secretVersion
+			secrets = map[string]secret.Secret{
+				secretName: s,
+			}
+		}
+
+		cl, err := client.New(app.Server)
+		if err != nil {
+			log.Fatal(err)
+		}
+
+		secretVals, err := secret.GenerateSecrets(cl, secrets, app.Server)
+		if err != nil {
+			log.Fatal(err)
+		}
+
+		if storeInPass {
+			for name, data := range secretVals {
+				if err := secret.PassInsertSecret(data, name, app.Name, app.Server); err != nil {
+					log.Fatal(err)
+				}
+			}
+		}
+
+		if len(secretVals) == 0 {
+			log.Warn("no secrets generated")
+			os.Exit(1)
+		}
+
+		headers := []string{"NAME", "VALUE"}
+		table, err := formatter.CreateTable()
+		if err != nil {
+			log.Fatal(err)
+		}
+
+		table.Headers(headers...)
+
+		var rows [][]string
+		for name, val := range secretVals {
+			row := []string{name, val}
+			rows = append(rows, row)
+			table.Row(row...)
+		}
+
+		if internal.MachineReadable {
+			out, err := formatter.ToJSON(headers, rows)
+			if err != nil {
+				log.Fatal("unable to render to JSON: %s", err)
+			}
+			fmt.Println(out)
+			return
+		}
+
+		if err := formatter.PrintTable(table); err != nil {
+			log.Fatal(err)
+		}
+
+		log.Warnf(
+			"generated secrets %s shown again, please take note of them %s",
+			formatter.BoldStyle.Render("NOT"),
+			formatter.BoldStyle.Render("NOW"),
+		)
+	},
+}
+
+var AppSecretInsertCommand = &cobra.Command{
+	Use:     "insert <domain> <secret> <version> <data> [flags]",
+	Aliases: []string{"i"},
+	Short:   "Insert secret",
+	Long: `This command inserts a secret into an app environment.
+
+This can be useful when you want to manually generate secrets for an app
+environment. Typically, you can let Abra generate them for you on app creation
+(see "abra app new --secrets/-S" for more).`,
+	Args: cobra.MinimumNArgs(4),
+	ValidArgsFunction: func(
+		cmd *cobra.Command,
+		args []string,
+		toComplete string) ([]string, cobra.ShellCompDirective) {
+		switch l := len(args); l {
+		case 0:
+			return autocomplete.AppNameComplete()
+		case 1:
+			app, err := appPkg.Get(args[0])
+			if err != nil {
+				errMsg := fmt.Sprintf("autocomplete failed: %s", err)
+				return []string{errMsg}, cobra.ShellCompDirectiveError
+			}
+			return autocomplete.SecretComplete(app.Recipe.Name)
+		default:
+			return nil, cobra.ShellCompDirectiveDefault
+		}
+	},
+	Run: func(cmd *cobra.Command, args []string) {
+		app := internal.ValidateApp(args)
+
+		if err := app.Recipe.Ensure(internal.GetEnsureContext()); err != nil {
+			log.Fatal(err)
+		}
+
+		cl, err := client.New(app.Server)
+		if err != nil {
+			log.Fatal(err)
+		}
+
+		name := args[1]
+		version := args[2]
+		data := args[3]
+
+		if insertFromFile {
+			raw, err := os.ReadFile(data)
+			if err != nil {
+				log.Fatalf("reading secret from file: %s", err)
+			}
+			data = string(raw)
+		}
+
+		if trimInput {
+			data = strings.TrimSpace(data)
+		}
+
+		secretName := fmt.Sprintf("%s_%s_%s", app.StackName(), name, version)
+		if err := client.StoreSecret(cl, secretName, data, app.Server); err != nil {
+			log.Fatal(err)
+		}
+
+		log.Infof("%s successfully stored on server", secretName)
+
+		if storeInPass {
+			if err := secret.PassInsertSecret(data, name, app.Name, app.Server); err != nil {
+				log.Fatal(err)
+			}
+		}
+	},
+}
+
+// secretRm removes a secret.
+func secretRm(cl *dockerClient.Client, app appPkg.App, secretName, parsed string) error {
+	if err := cl.SecretRemove(context.Background(), secretName); err != nil {
+		return err
+	}
+
+	log.Infof("deleted %s successfully from server", secretName)
+
+	if removeFromPass {
+		if err := secret.PassRmSecret(parsed, app.StackName(), app.Server); err != nil {
+			return err
+		}
+
+		log.Infof("deleted %s successfully from local pass store", secretName)
+	}
+
+	return nil
+}
+
+var AppSecretRmCommand = &cobra.Command{
+	Use:     "remove <domain> [[secret] | --all] [flags]",
+	Aliases: []string{"rm"},
+	Short:   "Remove a secret",
+	Args:    cobra.RangeArgs(1, 2),
+	ValidArgsFunction: func(
+		cmd *cobra.Command,
+		args []string,
+		toComplete string) ([]string, cobra.ShellCompDirective) {
+		switch l := len(args); l {
+		case 0:
+			return autocomplete.AppNameComplete()
+		case 1:
+			if !rmAllSecrets {
+				app, err := appPkg.Get(args[0])
+				if err != nil {
+					errMsg := fmt.Sprintf("autocomplete failed: %s", err)
+					return []string{errMsg}, cobra.ShellCompDirectiveError
+				}
+				return autocomplete.SecretComplete(app.Recipe.Name)
+			}
+			return nil, cobra.ShellCompDirectiveDefault
+		default:
+			return nil, cobra.ShellCompDirectiveError
+		}
+	},
+	Run: func(cmd *cobra.Command, args []string) {
+		app := internal.ValidateApp(args)
+
+		if err := app.Recipe.Ensure(internal.GetEnsureContext()); err != nil {
+			log.Fatal(err)
+		}
+
+		composeFiles, err := app.Recipe.GetComposeFiles(app.Env)
+		if err != nil {
+			log.Fatal(err)
+		}
+
+		secrets, err := secret.ReadSecretsConfig(app.Path, composeFiles, app.StackName())
+		if err != nil {
+			log.Fatal(err)
+		}
+
+		if len(args) == 2 && rmAllSecrets {
+			log.Fatal("cannot use [secret] and --all/-a together")
+		}
+
+		if len(args) != 2 && !rmAllSecrets {
+			log.Fatal("no secret(s) specified?")
+		}
+
+		cl, err := client.New(app.Server)
+		if err != nil {
+			log.Fatal(err)
+		}
+
+		filters, err := app.Filters(false, false)
+		if err != nil {
+			log.Fatal(err)
+		}
+
+		secretList, err := cl.SecretList(context.Background(), types.SecretListOptions{Filters: filters})
+		if err != nil {
+			log.Fatal(err)
+		}
+
+		remoteSecretNames := make(map[string]bool)
+		for _, cont := range secretList {
+			remoteSecretNames[cont.Spec.Annotations.Name] = true
+		}
+
+		var secretToRm string
+		if len(args) == 2 {
+			secretToRm = args[1]
+		}
+
+		match := false
+		for secretName, val := range secrets {
+			secretRemoteName := fmt.Sprintf("%s_%s_%s", app.StackName(), secretName, val.Version)
+			if _, ok := remoteSecretNames[secretRemoteName]; ok {
+				if secretToRm != "" {
+					if secretName == secretToRm {
+						if err := secretRm(cl, app, secretRemoteName, secretName); err != nil {
+							log.Fatal(err)
+						}
+
+						return
+					}
+				} else {
+					match = true
+
+					if err := secretRm(cl, app, secretRemoteName, secretName); err != nil {
+						log.Fatal(err)
+					}
+				}
+			}
+		}
+
+		if !match && secretToRm != "" {
+			log.Fatalf("%s doesn't exist on server?", secretToRm)
+		}
+
+		if !match {
+			log.Fatal("no secrets to remove?")
+		}
+	},
+}
+
+var AppSecretLsCommand = &cobra.Command{
+	Use:     "list <domain>",
+	Aliases: []string{"ls"},
+	Short:   "List all secrets",
+	Args:    cobra.MinimumNArgs(1),
+	ValidArgsFunction: func(
+		cmd *cobra.Command,
+		args []string,
+		toComplete string) ([]string, cobra.ShellCompDirective) {
+		return autocomplete.AppNameComplete()
+	},
+	Run: func(cmd *cobra.Command, args []string) {
+		app := internal.ValidateApp(args)
+
+		if err := app.Recipe.Ensure(internal.GetEnsureContext()); err != nil {
+			log.Fatal(err)
+		}
+
+		cl, err := client.New(app.Server)
+		if err != nil {
+			log.Fatal(err)
+		}
+
+		headers := []string{"NAME", "VERSION", "GENERATED NAME", "CREATED ON SERVER"}
+		table, err := formatter.CreateTable()
+		if err != nil {
+			log.Fatal(err)
+		}
+
+		table.Headers(headers...)
+
+		secStats, err := secret.PollSecretsStatus(cl, app)
+		if err != nil {
+			log.Fatal(err)
+		}
+
+		var rows [][]string
+		for _, secStat := range secStats {
+			row := []string{
+				secStat.LocalName,
+				secStat.Version,
+				secStat.RemoteName,
+				strconv.FormatBool(secStat.CreatedOnRemote),
+			}
+
+			rows = append(rows, row)
+			table.Row(row...)
+		}
+
+		if len(rows) > 0 {
+			if internal.MachineReadable {
+				out, err := formatter.ToJSON(headers, rows)
+				if err != nil {
+					log.Fatal("unable to render to JSON: %s", err)
+				}
+				fmt.Println(out)
+				return
+			}
+
+			if err := formatter.PrintTable(table); err != nil {
+				log.Fatal(err)
+			}
+
+			return
+		}
+
+		log.Warnf("no secrets stored for %s", app.Name)
+	},
+}
+
+var AppSecretCommand = &cobra.Command{
+	Use:     "secret [cmd] [args] [flags]",
+	Aliases: []string{"s"},
+	Short:   "Manage app secrets",
+}
+
+var (
+	storeInPass        bool
+	insertFromFile     bool
+	trimInput          bool
+	rmAllSecrets       bool
+	generateAllSecrets bool
+	removeFromPass     bool
+)
+
+func init() {
+	AppSecretGenerateCommand.Flags().BoolVarP(
+		&internal.MachineReadable,
+		"machine",
+		"m",
+		false,
+		"print machine-readable output",
+	)
+
+	AppSecretGenerateCommand.Flags().BoolVarP(
+		&storeInPass,
+		"pass",
+		"p",
+		false,
+		"store generated secrets in a local pass store",
+	)
+
+	AppSecretGenerateCommand.Flags().BoolVarP(
+		&internal.Chaos,
+		"chaos",
+		"C",
+		false,
+		"ignore uncommitted recipes changes",
+	)
+
+	AppSecretGenerateCommand.Flags().BoolVarP(
+		&generateAllSecrets,
+		"all",
+		"a",
+		false,
+		"generate all secrets",
+	)
+
+	AppSecretInsertCommand.Flags().BoolVarP(
+		&storeInPass,
+		"pass",
+		"p",
+		false,
+		"store generated secrets in a local pass store",
+	)
+
+	AppSecretInsertCommand.Flags().BoolVarP(
+		&insertFromFile,
+		"file",
+		"f",
+		false,
+		"treat input as a file",
+	)
+
+	AppSecretInsertCommand.Flags().BoolVarP(
+		&trimInput,
+		"trim",
+		"t",
+		false,
+		"trim input",
+	)
+
+	AppSecretInsertCommand.Flags().BoolVarP(
+		&internal.Chaos,
+		"chaos",
+		"C",
+		false,
+		"ignore uncommitted recipes changes",
+	)
+
+	AppSecretRmCommand.Flags().BoolVarP(
+		&rmAllSecrets,
+		"all",
+		"a",
+		false,
+		"remove all secrets",
+	)
+
+	AppSecretRmCommand.Flags().BoolVarP(
+		&removeFromPass,
+		"pass",
+		"p",
+		false,
+		"remove generated secrets from a local pass store",
+	)
+
+	AppSecretRmCommand.Flags().BoolVarP(
+		&internal.Chaos,
+		"chaos",
+		"C",
+		false,
+		"ignore uncommitted recipes changes",
+	)
+
+	AppSecretLsCommand.Flags().BoolVarP(
+		&internal.Chaos,
+		"chaos",
+		"C",
+		false,
+		"ignore uncommitted recipes changes",
+	)
+
+	AppSecretLsCommand.Flags().BoolVarP(
+		&internal.MachineReadable,
+		"machine",
+		"m",
+		false,
+		"print machine-readable output",
+	)
+}

cli/app/services.go

@@ -0,0 +1,96 @@
+package app
+
+import (
+	"context"
+	"fmt"
+	"strings"
+
+	"coopcloud.tech/abra/cli/internal"
+	"coopcloud.tech/abra/pkg/autocomplete"
+	"coopcloud.tech/abra/pkg/client"
+	"coopcloud.tech/abra/pkg/formatter"
+	"coopcloud.tech/abra/pkg/log"
+	"coopcloud.tech/abra/pkg/service"
+	stack "coopcloud.tech/abra/pkg/upstream/stack"
+	containerTypes "github.com/docker/docker/api/types/container"
+	"github.com/spf13/cobra"
+)
+
+var AppServicesCommand = &cobra.Command{
+	Use:     "services <domain> [flags]",
+	Aliases: []string{"sr"},
+	Short:   "Display all services of an app",
+	Args:    cobra.ExactArgs(1),
+	ValidArgsFunction: func(
+		cmd *cobra.Command,
+		args []string,
+		toComplete string) ([]string, cobra.ShellCompDirective) {
+		return autocomplete.AppNameComplete()
+	},
+	Run: func(cmd *cobra.Command, args []string) {
+		app := internal.ValidateApp(args)
+
+		if err := app.Recipe.Ensure(internal.GetEnsureContext()); err != nil {
+			log.Fatal(err)
+		}
+
+		cl, err := client.New(app.Server)
+		if err != nil {
+			log.Fatal(err)
+		}
+
+		deployMeta, err := stack.IsDeployed(context.Background(), cl, app.StackName())
+		if err != nil {
+			log.Fatal(err)
+		}
+
+		if !deployMeta.IsDeployed {
+			log.Fatalf("%s is not deployed?", app.Name)
+		}
+
+		filters, err := app.Filters(true, true)
+		if err != nil {
+			log.Fatal(err)
+		}
+
+		containers, err := cl.ContainerList(context.Background(), containerTypes.ListOptions{Filters: filters})
+		if err != nil {
+			log.Fatal(err)
+		}
+
+		table, err := formatter.CreateTable()
+		if err != nil {
+			log.Fatal(err)
+		}
+
+		headers := []string{"SERVICE (SHORT)", "SERVICE (LONG)"}
+		table.Headers(headers...)
+
+		var rows [][]string
+		for _, container := range containers {
+			var containerNames []string
+			for _, containerName := range container.Names {
+				trimmed := strings.TrimPrefix(containerName, "/")
+				containerNames = append(containerNames, trimmed)
+			}
+
+			serviceShortName := service.ContainerToServiceName(container.Names, app.StackName())
+			serviceLongName := fmt.Sprintf("%s_%s", app.StackName(), serviceShortName)
+
+			row := []string{
+				serviceShortName,
+				serviceLongName,
+			}
+
+			rows = append(rows, row)
+		}
+
+		table.Rows(rows...)
+
+		if len(rows) > 0 {
+			if err := formatter.PrintTable(table); err != nil {
+				log.Fatal(err)
+			}
+		}
+	},
+}

cli/app/undeploy.go

@@ -0,0 +1,155 @@
+package app
+
+import (
+	"context"
+	"fmt"
+
+	"coopcloud.tech/abra/cli/internal"
+	appPkg "coopcloud.tech/abra/pkg/app"
+	"coopcloud.tech/abra/pkg/autocomplete"
+	"coopcloud.tech/abra/pkg/client"
+	"coopcloud.tech/abra/pkg/config"
+	"coopcloud.tech/abra/pkg/formatter"
+	"coopcloud.tech/abra/pkg/log"
+	stack "coopcloud.tech/abra/pkg/upstream/stack"
+	"github.com/docker/docker/api/types/filters"
+	dockerClient "github.com/docker/docker/client"
+	"github.com/spf13/cobra"
+)
+
+var AppUndeployCommand = &cobra.Command{
+	Use:     "undeploy <domain> [flags]",
+	Aliases: []string{"un"},
+	Short:   "Undeploy an app",
+	Long: `This does not destroy any application data.
+
+However, you should remain vigilant, as your swarm installation will consider
+any previously attached volumes as eligible for pruning once undeployed.
+
+Passing "--prune/-p" does not remove those volumes.`,
+	Args: cobra.ExactArgs(1),
+	ValidArgsFunction: func(
+		cmd *cobra.Command,
+		args []string,
+		toComplete string) ([]string, cobra.ShellCompDirective) {
+		return autocomplete.AppNameComplete()
+	},
+	Run: func(cmd *cobra.Command, args []string) {
+		app := internal.ValidateApp(args)
+		stackName := app.StackName()
+
+		cl, err := client.New(app.Server)
+		if err != nil {
+			log.Fatal(err)
+		}
+
+		log.Debugf("checking whether %s is already deployed", stackName)
+
+		deployMeta, err := stack.IsDeployed(context.Background(), cl, stackName)
+		if err != nil {
+			log.Fatal(err)
+		}
+
+		if !deployMeta.IsDeployed {
+			log.Fatalf("%s is not deployed?", app.Name)
+		}
+
+		if err := internal.DeployOverview(
+			app,
+			deployMeta.Version,
+			config.NO_DOMAIN_DEFAULT,
+			"",
+			nil,
+		); err != nil {
+			log.Fatal(err)
+		}
+
+		composeFiles, err := app.Recipe.GetComposeFiles(app.Env)
+		if err != nil {
+			log.Fatal(err)
+		}
+
+		opts := stack.Deploy{Composefiles: composeFiles, Namespace: stackName}
+		compose, err := appPkg.GetAppComposeConfig(app.Name, opts, app.Env)
+		if err != nil {
+			log.Fatal(err)
+		}
+
+		stack.WaitTimeout, err = appPkg.GetTimeoutFromLabel(compose, stackName)
+		if err != nil {
+			log.Fatal(err)
+		}
+
+		log.Info("initialising undeploy")
+
+		rmOpts := stack.Remove{
+			Namespaces: []string{stackName},
+			Detach:     false,
+		}
+		if err := stack.RunRemove(context.Background(), cl, rmOpts); err != nil {
+			log.Fatal(err)
+		}
+
+		if prune {
+			if err := pruneApp(cl, app); err != nil {
+				log.Fatal(err)
+			}
+		}
+
+		log.Info("undeploy succeeded 🟢")
+
+		if err := app.WriteRecipeVersion(deployMeta.Version, false); err != nil {
+			log.Fatalf("writing recipe version failed: %s", err)
+		}
+	},
+}
+
+// pruneApp runs the equivalent of a "docker system prune" but only filtering
+// against resources connected with the app deployment. It is not a system wide
+// prune. Volumes are not pruned to avoid unwated data loss.
+func pruneApp(cl *dockerClient.Client, app appPkg.App) error {
+	stackName := app.StackName()
+	ctx := context.Background()
+
+	pruneFilters := filters.NewArgs()
+	stackSearch := fmt.Sprintf("%s*", stackName)
+	pruneFilters.Add("label", stackSearch)
+	cr, err := cl.ContainersPrune(ctx, pruneFilters)
+	if err != nil {
+		return err
+	}
+
+	cntSpaceReclaimed := formatter.ByteCountSI(cr.SpaceReclaimed)
+	log.Infof("containers pruned: %d; space reclaimed: %s", len(cr.ContainersDeleted), cntSpaceReclaimed)
+
+	nr, err := cl.NetworksPrune(ctx, pruneFilters)
+	if err != nil {
+		return err
+	}
+
+	log.Infof("networks pruned: %d", len(nr.NetworksDeleted))
+
+	ir, err := cl.ImagesPrune(ctx, pruneFilters)
+	if err != nil {
+		return err
+	}
+
+	imgSpaceReclaimed := formatter.ByteCountSI(ir.SpaceReclaimed)
+	log.Infof("images pruned: %d; space reclaimed: %s", len(ir.ImagesDeleted), imgSpaceReclaimed)
+
+	return nil
+}
+
+var (
+	prune bool
+)
+
+func init() {
+	AppUndeployCommand.Flags().BoolVarP(
+		&prune,
+		"prune",
+		"p",
+		false,
+		"prune unused containers, networks, and dangling images",
+	)
+}

cli/app/upgrade.go

@@ -0,0 +1,460 @@
+package app
+
+import (
+	"context"
+	"fmt"
+	"strings"
+
+	"coopcloud.tech/abra/cli/internal"
+	"coopcloud.tech/abra/pkg/app"
+	appPkg "coopcloud.tech/abra/pkg/app"
+	"coopcloud.tech/abra/pkg/autocomplete"
+	"coopcloud.tech/abra/pkg/client"
+	"coopcloud.tech/abra/pkg/config"
+	"coopcloud.tech/abra/pkg/envfile"
+	"coopcloud.tech/abra/pkg/formatter"
+	"coopcloud.tech/abra/pkg/lint"
+	"coopcloud.tech/abra/pkg/log"
+	"coopcloud.tech/abra/pkg/recipe"
+	stack "coopcloud.tech/abra/pkg/upstream/stack"
+	"coopcloud.tech/tagcmp"
+	"github.com/AlecAivazis/survey/v2"
+	dockerClient "github.com/docker/docker/client"
+	"github.com/spf13/cobra"
+)
+
+var AppUpgradeCommand = &cobra.Command{
+	Use:     "upgrade <domain> [version] [flags]",
+	Aliases: []string{"up"},
+	Short:   "Upgrade an app",
+	Long: `Upgrade an app.
+
+Unlike "abra app deploy", chaos operations are not supported here. Only recipe
+versions are supported values for "[version]".
+
+It is possible to "--force/-f" an upgrade if you want to re-deploy a specific
+version.
+
+Only the deployed version is consulted when trying to determine what upgrades
+are available. The live deployment version is the "source of truth" in this
+case. The stored .env version is not consulted.
+
+An upgrade can be destructive, please ensure you have a copy of your app data
+beforehand. See "abra app backup" for more.`,
+	Args: cobra.RangeArgs(1, 2),
+	ValidArgsFunction: func(
+		cmd *cobra.Command,
+		args []string,
+		toComplete string,
+	) ([]string, cobra.ShellCompDirective) {
+		switch l := len(args); l {
+		case 0:
+			return autocomplete.AppNameComplete()
+		case 1:
+			app, err := appPkg.Get(args[0])
+			if err != nil {
+				errMsg := fmt.Sprintf("autocomplete failed: %s", err)
+				return []string{errMsg}, cobra.ShellCompDirectiveError
+			}
+			return autocomplete.RecipeVersionComplete(app.Recipe.Name)
+		default:
+			return nil, cobra.ShellCompDirectiveError
+		}
+	},
+	Run: func(cmd *cobra.Command, args []string) {
+		var (
+			upgradeWarnMessages []string
+			chosenUpgrade       string
+			availableUpgrades   []string
+			upgradeReleaseNotes string
+		)
+
+		app := internal.ValidateApp(args)
+
+		if err := app.Recipe.Ensure(recipe.EnsureContext{
+			Chaos:   internal.Chaos,
+			Offline: internal.Offline,
+			// Ignore the env version for now, to make sure we are at the latest commit.
+			// This enables us to get release notes, that were added after a release.
+			IgnoreEnvVersion: true,
+		}); err != nil {
+			log.Fatal(err)
+		}
+
+		cl, err := client.New(app.Server)
+		if err != nil {
+			log.Fatal(err)
+		}
+
+		deployMeta, err := ensureDeployed(cl, app)
+		if err != nil {
+			log.Fatal(err)
+		}
+
+		if err := lint.LintForErrors(app.Recipe); err != nil {
+			log.Fatal(err)
+		}
+
+		versions, err := app.Recipe.Tags()
+		if err != nil {
+			log.Fatal(err)
+		}
+
+		// NOTE(d1): we've no idea what the live deployment version is, so every
+		// possible upgrade can be shown. it's up to the user to make the choice
+		if deployMeta.Version == config.UNKNOWN_DEFAULT {
+			availableUpgrades = versions
+		}
+
+		if len(args) == 2 && args[1] != "" {
+			chosenUpgrade = args[1]
+
+			if err := validateUpgradeVersionArg(chosenUpgrade, app, deployMeta); err != nil {
+				log.Fatal(err)
+			}
+
+			availableUpgrades = append(availableUpgrades, chosenUpgrade)
+		}
+
+		if deployMeta.Version != config.UNKNOWN_DEFAULT && chosenUpgrade == "" {
+			upgradeAvailable, err := ensureUpgradesAvailable(versions, &availableUpgrades, deployMeta)
+			if err != nil {
+				log.Fatal(err)
+			}
+
+			if !upgradeAvailable {
+				log.Info("no available upgrades")
+				return
+			}
+		}
+
+		if internal.Force || internal.NoInput || chosenUpgrade != "" {
+			if len(availableUpgrades) > 0 {
+				chosenUpgrade = availableUpgrades[len(availableUpgrades)-1]
+			}
+		} else {
+			if err := chooseUpgrade(availableUpgrades, deployMeta, &chosenUpgrade); err != nil {
+				log.Fatal(err)
+			}
+		}
+
+		if internal.Force &&
+			chosenUpgrade == "" &&
+			deployMeta.Version != config.UNKNOWN_DEFAULT {
+			chosenUpgrade = deployMeta.Version
+		}
+
+		if chosenUpgrade == "" {
+			log.Fatal("unknown deployed version, unable to upgrade")
+		}
+
+		log.Debugf("choosing %s as version to upgrade", chosenUpgrade)
+
+		// Get the release notes before checking out the new version in the
+		// recipe. This enables us to get release notes, that were added after
+		// a release.
+		if err := getReleaseNotes(app, versions, chosenUpgrade, deployMeta, &upgradeReleaseNotes); err != nil {
+			log.Fatal(err)
+		}
+
+		if _, err := app.Recipe.EnsureVersion(chosenUpgrade); err != nil {
+			log.Fatal(err)
+		}
+
+		abraShEnv, err := envfile.ReadAbraShEnvVars(app.Recipe.AbraShPath)
+		if err != nil {
+			log.Fatal(err)
+		}
+		for k, v := range abraShEnv {
+			app.Env[k] = v
+		}
+
+		composeFiles, err := app.Recipe.GetComposeFiles(app.Env)
+		if err != nil {
+			log.Fatal(err)
+		}
+
+		stackName := app.StackName()
+		deployOpts := stack.Deploy{
+			Composefiles: composeFiles,
+			Namespace:    stackName,
+			Prune:        false,
+			ResolveImage: stack.ResolveImageAlways,
+			Detach:       false,
+		}
+
+		compose, err := appPkg.GetAppComposeConfig(app.Name, deployOpts, app.Env)
+		if err != nil {
+			log.Fatal(err)
+		}
+
+		appPkg.ExposeAllEnv(stackName, compose, app.Env)
+		appPkg.SetRecipeLabel(compose, stackName, app.Recipe.Name)
+		appPkg.SetChaosLabel(compose, stackName, internal.Chaos)
+		if internal.Chaos {
+			appPkg.SetChaosVersionLabel(compose, stackName, chosenUpgrade)
+		}
+		appPkg.SetUpdateLabel(compose, stackName, app.Env)
+
+		envVars, err := appPkg.CheckEnv(app)
+		if err != nil {
+			log.Fatal(err)
+		}
+
+		for _, envVar := range envVars {
+			if !envVar.Present {
+				upgradeWarnMessages = append(upgradeWarnMessages,
+					fmt.Sprintf("%s missing from %s.env", envVar.Name, app.Domain),
+				)
+			}
+		}
+
+		if showReleaseNotes {
+			fmt.Print(upgradeReleaseNotes)
+			return
+		}
+
+		if upgradeReleaseNotes == "" {
+			upgradeWarnMessages = append(
+				upgradeWarnMessages,
+				fmt.Sprintf("no release notes available for %s", chosenUpgrade),
+			)
+		}
+
+		if err := internal.DeployOverview(
+			app,
+			deployMeta.Version,
+			chosenUpgrade,
+			upgradeReleaseNotes,
+			upgradeWarnMessages,
+		); err != nil {
+			log.Fatal(err)
+		}
+
+		stack.WaitTimeout, err = appPkg.GetTimeoutFromLabel(compose, stackName)
+		if err != nil {
+			log.Fatal(err)
+		}
+
+		log.Debugf("set waiting timeout to %d second(s)", stack.WaitTimeout)
+
+		serviceNames, err := appPkg.GetAppServiceNames(app.Name)
+		if err != nil {
+			log.Fatal(err)
+		}
+
+		f, err := app.Filters(true, false, serviceNames...)
+		if err != nil {
+			log.Fatal(err)
+		}
+
+		if err := stack.RunDeploy(
+			cl,
+			deployOpts,
+			compose,
+			stackName,
+			app.Server,
+			internal.DontWaitConverge,
+			f,
+		); err != nil {
+			log.Fatal(err)
+		}
+
+		postDeployCmds, ok := app.Env["POST_UPGRADE_CMDS"]
+		if ok && !internal.DontWaitConverge {
+			log.Debugf("run the following post-deploy commands: %s", postDeployCmds)
+
+			if err := internal.PostCmds(cl, app, postDeployCmds); err != nil {
+				log.Fatalf("attempting to run post deploy commands, saw: %s", err)
+			}
+		}
+
+		if err := app.WriteRecipeVersion(chosenUpgrade, false); err != nil {
+			log.Fatalf("writing recipe version failed: %s", err)
+		}
+	},
+}
+
+// chooseUpgrade prompts the user to choose an upgrade interactively.
+func chooseUpgrade(
+	availableUpgrades []string,
+	deployMeta stack.DeployMeta,
+	chosenUpgrade *string,
+) error {
+	msg := fmt.Sprintf("please select an upgrade (version: %s):", deployMeta.Version)
+
+	if deployMeta.IsChaos {
+		chaosVersion := formatter.BoldDirtyDefault(deployMeta.ChaosVersion)
+
+		msg = fmt.Sprintf(
+			"please select an upgrade (version: %s, chaos: %s):",
+			deployMeta.Version,
+			chaosVersion,
+		)
+	}
+
+	prompt := &survey.Select{
+		Message: msg,
+		Options: internal.SortVersionsDesc(availableUpgrades),
+	}
+
+	if err := survey.AskOne(prompt, chosenUpgrade); err != nil {
+		return err
+	}
+
+	return nil
+}
+
+func getReleaseNotes(
+	app app.App,
+	versions []string,
+	chosenUpgrade string,
+	deployMeta stack.DeployMeta,
+	upgradeReleaseNotes *string,
+) error {
+	parsedChosenUpgrade, err := tagcmp.Parse(chosenUpgrade)
+	if err != nil {
+		return err
+	}
+
+	parsedDeployedVersion, err := tagcmp.Parse(deployMeta.Version)
+	if err != nil {
+		return err
+	}
+
+	for _, version := range internal.SortVersionsDesc(versions) {
+		parsedVersion, err := tagcmp.Parse(version)
+		if err != nil {
+			return err
+		}
+
+		if parsedVersion.IsGreaterThan(parsedDeployedVersion) &&
+			parsedVersion.IsLessThan(parsedChosenUpgrade) {
+			note, err := app.Recipe.GetReleaseNotes(version)
+			if err != nil {
+				return err
+			}
+
+			if note != "" {
+				// NOTE(d1): trim any final newline on the end of the note itself before
+				//           we manually handle newlines (for multiple release notes and
+				//           ensuring space between the warning messages)
+				note = strings.TrimSuffix(note, "\n")
+
+				*upgradeReleaseNotes += fmt.Sprintf("%s\n", note)
+			}
+		}
+	}
+
+	return nil
+}
+
+// ensureUpgradesAvailable ensures that there are available upgrades.
+func ensureUpgradesAvailable(
+	versions []string,
+	availableUpgrades *[]string,
+	deployMeta stack.DeployMeta,
+) (bool, error) {
+	parsedDeployedVersion, err := tagcmp.Parse(deployMeta.Version)
+	if err != nil {
+		return false, err
+	}
+
+	for _, version := range versions {
+		parsedVersion, err := tagcmp.Parse(version)
+		if err != nil {
+			return false, err
+		}
+
+		if parsedVersion.IsGreaterThan(parsedDeployedVersion) &&
+			!(parsedVersion.Equals(parsedDeployedVersion)) {
+			*availableUpgrades = append(*availableUpgrades, version)
+		}
+	}
+
+	if len(*availableUpgrades) == 0 && !internal.Force {
+		return false, nil
+	}
+
+	return true, nil
+}
+
+// validateUpgradeVersionArg validates the specific version.
+func validateUpgradeVersionArg(
+	specificVersion string,
+	app app.App,
+	deployMeta stack.DeployMeta,
+) error {
+	parsedSpecificVersion, err := tagcmp.Parse(specificVersion)
+	if err != nil {
+		return fmt.Errorf("'%s' is not a known version for %s", specificVersion, app.Recipe.Name)
+	}
+
+	parsedDeployedVersion, err := tagcmp.Parse(deployMeta.Version)
+	if err != nil {
+		return fmt.Errorf("'%s' is not a known version", deployMeta.Version)
+	}
+
+	if parsedSpecificVersion.IsLessThan(parsedDeployedVersion) &&
+		!parsedSpecificVersion.Equals(parsedDeployedVersion) {
+		return fmt.Errorf("%s is not an upgrade for %s?", deployMeta.Version, specificVersion)
+	}
+
+	if parsedSpecificVersion.Equals(parsedDeployedVersion) && !internal.Force {
+		return fmt.Errorf("%s is not an upgrade for %s?", deployMeta.Version, specificVersion)
+	}
+
+	return nil
+}
+
+// ensureDeployed ensures the app is deployed and if so, returns deployment
+// meta info.
+func ensureDeployed(cl *dockerClient.Client, app app.App) (stack.DeployMeta, error) {
+	log.Debugf("checking whether %s is already deployed", app.StackName())
+
+	deployMeta, err := stack.IsDeployed(context.Background(), cl, app.StackName())
+	if err != nil {
+		return stack.DeployMeta{}, err
+	}
+
+	if !deployMeta.IsDeployed {
+		return stack.DeployMeta{}, fmt.Errorf("%s is not deployed?", app.Name)
+	}
+
+	return deployMeta, nil
+}
+
+var showReleaseNotes bool
+
+func init() {
+	AppUpgradeCommand.Flags().BoolVarP(
+		&internal.Force,
+		"force",
+		"f",
+		false,
+		"perform action without further prompt",
+	)
+
+	AppUpgradeCommand.Flags().BoolVarP(
+		&internal.NoDomainChecks,
+		"no-domain-checks",
+		"D",
+		false,
+		"disable public DNS checks",
+	)
+
+	AppUpgradeCommand.Flags().BoolVarP(
+		&internal.DontWaitConverge, "no-converge-checks",
+		"c",
+		false,
+		"disable converge logic checks",
+	)
+
+	AppUpgradeCommand.Flags().BoolVarP(
+		&showReleaseNotes,
+		"releasenotes",
+		"r",
+		false,
+		"only show release notes",
+	)
+}

cli/app/volume.go

@@ -0,0 +1,167 @@
+package app
+
+import (
+	"context"
+
+	"coopcloud.tech/abra/cli/internal"
+	"coopcloud.tech/abra/pkg/autocomplete"
+	"coopcloud.tech/abra/pkg/client"
+	"coopcloud.tech/abra/pkg/formatter"
+	"coopcloud.tech/abra/pkg/log"
+	"coopcloud.tech/abra/pkg/upstream/stack"
+	"github.com/AlecAivazis/survey/v2"
+	"github.com/spf13/cobra"
+)
+
+var AppVolumeListCommand = &cobra.Command{
+	Use:     "list <domain> [flags]",
+	Aliases: []string{"ls"},
+	Short:   "List volumes associated with an app",
+	Args:    cobra.ExactArgs(1),
+	ValidArgsFunction: func(
+		cmd *cobra.Command,
+		args []string,
+		toComplete string) ([]string, cobra.ShellCompDirective) {
+		return autocomplete.AppNameComplete()
+	},
+	Run: func(cmd *cobra.Command, args []string) {
+		app := internal.ValidateApp(args)
+
+		cl, err := client.New(app.Server)
+		if err != nil {
+			log.Fatal(err)
+		}
+
+		filters, err := app.Filters(false, true)
+		if err != nil {
+			log.Fatal(err)
+		}
+
+		volumes, err := client.GetVolumes(cl, context.Background(), app.Server, filters)
+		if err != nil {
+			log.Fatal(err)
+		}
+
+		headers := []string{"NAME", "ON SERVER"}
+
+		table, err := formatter.CreateTable()
+		if err != nil {
+			log.Fatal(err)
+		}
+
+		table.Headers(headers...)
+
+		var rows [][]string
+		for _, volume := range volumes {
+			row := []string{volume.Name, volume.Mountpoint}
+			rows = append(rows, row)
+		}
+
+		table.Rows(rows...)
+
+		if len(rows) > 0 {
+			if err := formatter.PrintTable(table); err != nil {
+				log.Fatal(err)
+			}
+			return
+		}
+
+		log.Warnf("no volumes created for %s", app.Name)
+	},
+}
+
+var AppVolumeRemoveCommand = &cobra.Command{
+	Use:   "remove <domain> [flags]",
+	Short: "Remove volume(s) associated with an app",
+	Long: `Remove volumes associated with an app.
+
+The app in question must be undeployed before you try to remove volumes. See
+"abra app undeploy <domain>" for more.
+
+The command is interactive and will show a multiple select input which allows
+you to make a seclection. Use the "?" key to see more help on navigating this
+interface.
+
+Passing "--force/-f" will select all volumes for removal. Be careful.`,
+	Aliases: []string{"rm"},
+	Args:    cobra.MinimumNArgs(1),
+	ValidArgsFunction: func(
+		cmd *cobra.Command,
+		args []string,
+		toComplete string) ([]string, cobra.ShellCompDirective) {
+		return autocomplete.AppNameComplete()
+	},
+	Run: func(cmd *cobra.Command, args []string) {
+		app := internal.ValidateApp(args)
+
+		cl, err := client.New(app.Server)
+		if err != nil {
+			log.Fatal(err)
+		}
+
+		deployMeta, err := stack.IsDeployed(context.Background(), cl, app.StackName())
+		if err != nil {
+			log.Fatal(err)
+		}
+
+		if deployMeta.IsDeployed {
+			log.Fatalf("%s is still deployed. Run \"abra app undeploy %s\"", app.Name, app.Name)
+		}
+
+		filters, err := app.Filters(false, true)
+		if err != nil {
+			log.Fatal(err)
+		}
+
+		volumeList, err := client.GetVolumes(cl, context.Background(), app.Server, filters)
+		if err != nil {
+			log.Fatal(err)
+		}
+		volumeNames := client.GetVolumeNames(volumeList)
+
+		var volumesToRemove []string
+		if !internal.Force && !internal.NoInput {
+			volumesPrompt := &survey.MultiSelect{
+				Message: "which volumes do you want to remove?",
+				Help:    "'x' indicates selected, enter / return to confirm, ctrl-c to exit, vim mode is enabled",
+				VimMode: true,
+				Options: volumeNames,
+				Default: volumeNames,
+			}
+			if err := survey.AskOne(volumesPrompt, &volumesToRemove); err != nil {
+				log.Fatal(err)
+			}
+		}
+
+		if internal.Force || internal.NoInput {
+			volumesToRemove = volumeNames
+		}
+
+		if len(volumesToRemove) > 0 {
+			err := client.RemoveVolumes(cl, context.Background(), volumesToRemove, internal.Force, 5)
+			if err != nil {
+				log.Fatalf("removing volumes failed: %s", err)
+			}
+
+			log.Infof("%d volumes removed successfully", len(volumesToRemove))
+		} else {
+			log.Info("no volumes removed")
+		}
+	},
+}
+
+var AppVolumeCommand = &cobra.Command{
+	Use:     "volume [cmd] [args] [flags]",
+	Aliases: []string{"vl"},
+	Short:   "Manage app volumes",
+}
+
+func init() {
+	AppVolumeRemoveCommand.Flags().BoolVarP(
+		&internal.Force,
+		"force",
+		"f",
+		false,
+		"perform action without further prompt",
+	)
+}

cli/catalogue/catalogue.go

@@ -0,0 +1,275 @@
+package catalogue
+
+import (
+	"encoding/json"
+	"fmt"
+	"io/ioutil"
+	"path"
+	"slices"
+
+	"coopcloud.tech/abra/cli/internal"
+	"coopcloud.tech/abra/pkg/autocomplete"
+	"coopcloud.tech/abra/pkg/catalogue"
+	"coopcloud.tech/abra/pkg/config"
+	"coopcloud.tech/abra/pkg/formatter"
+	gitPkg "coopcloud.tech/abra/pkg/git"
+	"coopcloud.tech/abra/pkg/log"
+	"coopcloud.tech/abra/pkg/recipe"
+	"github.com/go-git/go-git/v5"
+	"github.com/spf13/cobra"
+)
+
+var CatalogueGenerateCommand = &cobra.Command{
+	Use:     "generate [recipe] [flags]",
+	Aliases: []string{"g"},
+	Short:   "Generate the recipe catalogue",
+	Long: `Generate a new copy of the recipe catalogue.
+
+N.B. this command **will** wipe local unstaged changes from your local recipes
+if present. "--chaos/-C" on this command refers to the catalogue repository
+("$ABRA_DIR/catalogue") and not the recipes. Please take care not to lose your
+changes.
+
+It is possible to generate new metadata for a single recipe by passing
+[recipe]. The existing local catalogue will be updated, not overwritten.
+
+It is quite easy to get rate limited by Docker Hub when running this command.
+If you have a Hub account you can "docker login" and Abra will automatically
+use those details.
+
+Push your new release to git.coopcloud.tech with "--publish/-p". This requires
+that you have permission to git push to these repositories and have your SSH
+keys configured on your account.`,
+	Args: cobra.RangeArgs(0, 1),
+	ValidArgsFunction: func(
+		cmd *cobra.Command,
+		args []string,
+		toComplete string) ([]string, cobra.ShellCompDirective) {
+		return autocomplete.RecipeNameComplete()
+	},
+	Run: func(cmd *cobra.Command, args []string) {
+		var recipeName string
+		if len(args) > 0 {
+			recipeName = args[0]
+		}
+
+		if recipeName != "" {
+			internal.ValidateRecipe(args, cmd.Name())
+		}
+
+		if err := catalogue.EnsureCatalogue(); err != nil {
+			log.Fatal(err)
+		}
+
+		if !internal.Chaos {
+			if err := catalogue.EnsureIsClean(); err != nil {
+				log.Fatal(err)
+			}
+		}
+
+		repos, err := recipe.ReadReposMetadata(internal.Debug)
+		if err != nil {
+			log.Fatal(err)
+		}
+
+		barLength := len(repos)
+		if recipeName != "" {
+			barLength = 1
+		}
+
+		if !skipUpdates {
+			if err := recipe.UpdateRepositories(repos, recipeName, internal.Debug); err != nil {
+				log.Fatal(err)
+			}
+		}
+
+		var warnings []string
+		catl := make(recipe.RecipeCatalogue)
+		catlBar := formatter.CreateProgressbar(barLength, "collecting catalogue metadata")
+		for _, recipeMeta := range repos {
+			if recipeName != "" && recipeName != recipeMeta.Name {
+				if !internal.Debug {
+					catlBar.Add(1)
+				}
+				continue
+			}
+
+			r := recipe.Get(recipeMeta.Name)
+			versions, warnMsgs, err := r.GetRecipeVersions()
+			if err != nil {
+				warnings = append(warnings, err.Error())
+			}
+			if len(warnMsgs) > 0 {
+				warnings = append(warnings, warnMsgs...)
+			}
+
+			features, category, warnMsgs, err := recipe.GetRecipeFeaturesAndCategory(r)
+			if err != nil {
+				warnings = append(warnings, err.Error())
+			}
+			if len(warnMsgs) > 0 {
+				warnings = append(warnings, warnMsgs...)
+			}
+
+			catl[recipeMeta.Name] = recipe.RecipeMeta{
+				Name:          recipeMeta.Name,
+				Repository:    recipeMeta.CloneURL,
+				SSHURL:        recipeMeta.SSHURL,
+				Icon:          recipeMeta.AvatarURL,
+				DefaultBranch: recipeMeta.DefaultBranch,
+				Description:   recipeMeta.Description,
+				Website:       recipeMeta.Website,
+				Versions:      versions,
+				Category:      category,
+				Features:      features,
+			}
+
+			if !internal.Debug {
+				catlBar.Add(1)
+			}
+		}
+
+		if err := catlBar.Close(); err != nil {
+			log.Fatal(err)
+		}
+
+		var uniqueWarnings []string
+		for _, w := range warnings {
+			if !slices.Contains(uniqueWarnings, w) {
+				uniqueWarnings = append(uniqueWarnings, w)
+			}
+		}
+
+		for _, warnMsg := range uniqueWarnings {
+			log.Warn(warnMsg)
+		}
+
+		recipesJSON, err := json.MarshalIndent(catl, "", "    ")
+		if err != nil {
+			log.Fatal(err)
+		}
+
+		if recipeName == "" {
+			if err := ioutil.WriteFile(config.RECIPES_JSON, recipesJSON, 0764); err != nil {
+				log.Fatal(err)
+			}
+		} else {
+			catlFS, err := recipe.ReadRecipeCatalogue(internal.Offline)
+			if err != nil {
+				log.Fatal(err)
+			}
+
+			catlFS[recipeName] = catl[recipeName]
+
+			updatedRecipesJSON, err := json.MarshalIndent(catlFS, "", "    ")
+			if err != nil {
+				log.Fatal(err)
+			}
+
+			if err := ioutil.WriteFile(config.RECIPES_JSON, updatedRecipesJSON, 0764); err != nil {
+				log.Fatal(err)
+			}
+		}
+
+		log.Infof("generated recipe catalogue: %s", config.RECIPES_JSON)
+
+		cataloguePath := path.Join(config.ABRA_DIR, "catalogue")
+		if publishChanges {
+
+			isClean, err := gitPkg.IsClean(cataloguePath)
+			if err != nil {
+				log.Fatal(err)
+			}
+
+			if isClean {
+				if !internal.Dry {
+					log.Fatalf("no changes discovered in %s, nothing to publish?", cataloguePath)
+				}
+			}
+
+			msg := "chore: publish new catalogue release changes"
+			if err := gitPkg.Commit(cataloguePath, msg, internal.Dry); err != nil {
+				log.Fatal(err)
+			}
+
+			repo, err := git.PlainOpen(cataloguePath)
+			if err != nil {
+				log.Fatal(err)
+			}
+
+			sshURL := fmt.Sprintf(config.TOOLSHED_SSH_URL_TEMPLATE, config.CATALOGUE_JSON_REPO_NAME)
+			if err := gitPkg.CreateRemote(repo, "origin-ssh", sshURL, internal.Dry); err != nil {
+				log.Fatal(err)
+			}
+
+			if err := gitPkg.Push(cataloguePath, "origin-ssh", false, internal.Dry); err != nil {
+				log.Fatal(err)
+			}
+		}
+
+		repo, err := git.PlainOpen(cataloguePath)
+		if err != nil {
+			log.Fatal(err)
+		}
+
+		head, err := repo.Head()
+		if err != nil {
+			log.Fatal(err)
+		}
+
+		if !internal.Dry && publishChanges {
+			url := fmt.Sprintf("%s/%s/commit/%s", config.REPOS_BASE_URL, config.CATALOGUE_JSON_REPO_NAME, head.Hash())
+			log.Infof("new changes published: %s", url)
+		}
+
+		if internal.Dry {
+			log.Info("dry run: no changes published")
+		}
+	},
+}
+
+// CatalogueCommand defines the `abra catalogue` command and sub-commands.
+var CatalogueCommand = &cobra.Command{
+	Use:     "catalogue [cmd] [args] [flags]",
+	Short:   "Manage the recipe catalogue",
+	Aliases: []string{"c"},
+}
+
+var (
+	publishChanges bool
+	skipUpdates    bool
+)
+
+func init() {
+	CatalogueGenerateCommand.Flags().BoolVarP(
+		&publishChanges,
+		"publish",
+		"p",
+		false,
+		"publish changes to git.coopcloud.tech",
+	)
+
+	CatalogueGenerateCommand.Flags().BoolVarP(
+		&internal.Dry,
+		"dry-run",
+		"r",
+		false,
+		"report changes that would be made",
+	)
+
+	CatalogueGenerateCommand.Flags().BoolVarP(
+		&skipUpdates,
+		"skip-updates",
+		"s",
+		false,
+		"skip updating recipe repositories",
+	)
+
+	CatalogueGenerateCommand.Flags().BoolVarP(
+		&internal.Chaos,
+		"chaos",
+		"C",
+		false,
+		"ignore uncommitted recipes changes",
+	)
+}

cli/complete.go

@@ -0,0 +1,62 @@
+package cli
+
+import (
+	"os"
+
+	"github.com/spf13/cobra"
+)
+
+var AutocompleteCommand = &cobra.Command{
+	Use:   "autocomplete [bash|zsh|fish|powershell]",
+	Short: "Generate autocompletion script",
+	Long: `To load completions:
+
+Bash:
+  # Load autocompletion for the current Bash session
+  $ source <(abra autocomplete bash)
+
+  # To load autocompletion for each session, execute once:
+  # Linux:
+  $ abra autocomplete bash | sudo tee /etc/bash_completion.d/abra
+  # macOS:
+  $ abra autocomplete bash | sudo tee $(brew --prefix)/etc/bash_completion.d/abra
+
+Zsh:
+  # If shell autocompletion is not already enabled in your environment,
+  # you will need to enable it.  You can execute the following once:
+
+  $ echo "autoload -U compinit; compinit" >> ~/.zshrc
+
+  # To load autocompletions for each session, execute once:
+  $ abra autocomplete zsh > "${fpath[1]}/_abra"
+
+  # You will need to start a new shell for this setup to take effect.
+
+fish:
+  $ abra autocomplete fish | source
+
+  # To load autocompletions for each session, execute once:
+  $ abra autocomplete fish > ~/.config/fish/completions/abra.fish
+
+PowerShell:
+  PS> abra autocomplete powershell | Out-String | Invoke-Expression
+
+  # To load autocompletions for every new session, run:
+  PS> abra autocomplete powershell > abra.ps1
+  # and source this file from your PowerShell profile.`,
+	DisableFlagsInUseLine: true,
+	ValidArgs:             []string{"bash", "zsh", "fish", "powershell"},
+	Args:                  cobra.MatchAll(cobra.ExactArgs(1), cobra.OnlyValidArgs),
+	Run: func(cmd *cobra.Command, args []string) {
+		switch args[0] {
+		case "bash":
+			cmd.Root().GenBashCompletion(os.Stdout)
+		case "zsh":
+			cmd.Root().GenZshCompletion(os.Stdout)
+		case "fish":
+			cmd.Root().GenFishCompletion(os.Stdout, true)
+		case "powershell":
+			cmd.Root().GenPowerShellCompletionWithDesc(os.Stdout)
+		}
+	},
+}

cli/internal/backup.go

@@ -0,0 +1,75 @@
+package internal
+
+import (
+	"context"
+	"fmt"
+	"io"
+
+	"coopcloud.tech/abra/pkg/config"
+	containerPkg "coopcloud.tech/abra/pkg/container"
+	"coopcloud.tech/abra/pkg/log"
+	"coopcloud.tech/abra/pkg/service"
+	"coopcloud.tech/abra/pkg/upstream/container"
+	"github.com/docker/cli/cli/command"
+	"github.com/docker/docker/api/types"
+	containertypes "github.com/docker/docker/api/types/container"
+	"github.com/docker/docker/api/types/filters"
+	dockerClient "github.com/docker/docker/client"
+)
+
+// RetrieveBackupBotContainer gets the deployed backupbot container.
+func RetrieveBackupBotContainer(cl *dockerClient.Client) (types.Container, error) {
+	ctx := context.Background()
+	chosenService, err := service.GetServiceByLabel(ctx, cl, config.BackupbotLabel, NoInput)
+	if err != nil {
+		return types.Container{}, fmt.Errorf("no backupbot discovered, is it deployed?")
+	}
+
+	log.Debugf("retrieved %s as backup enabled service", chosenService.Spec.Name)
+
+	filters := filters.NewArgs()
+	filters.Add("name", chosenService.Spec.Name)
+	targetContainer, err := containerPkg.GetContainer(
+		ctx,
+		cl,
+		filters,
+		NoInput,
+	)
+	if err != nil {
+		return types.Container{}, err
+	}
+
+	return targetContainer, nil
+}
+
+// RunBackupCmdRemote runs a backup related command on a remote backupbot container.
+func RunBackupCmdRemote(
+	cl *dockerClient.Client,
+	backupCmd string,
+	containerID string,
+	execEnv []string) (io.Writer, error) {
+	execBackupListOpts := containertypes.ExecOptions{
+		AttachStderr: true,
+		AttachStdin:  true,
+		AttachStdout: true,
+		Cmd:          []string{"/usr/bin/backup", "--", backupCmd},
+		Detach:       false,
+		Env:          execEnv,
+		Tty:          true,
+	}
+
+	log.Debugf("running backup %s on %s with exec config %v", backupCmd, containerID, execBackupListOpts)
+
+	// FIXME: avoid instantiating a new CLI
+	dcli, err := command.NewDockerCli()
+	if err != nil {
+		return nil, err
+	}
+
+	out, err := container.RunExec(dcli, cl, containerID, &execBackupListOpts)
+	if err != nil {
+		return nil, err
+	}
+
+	return out, nil
+}

cli/internal/cli.go

@@ -0,0 +1,20 @@
+package internal
+
+var (
+	// NOTE(d1): global
+	Debug            bool
+	NoInput          bool
+	Offline          bool
+	IgnoreEnvVersion bool
+
+	// NOTE(d1): sub-command specific
+	Chaos            bool
+	DontWaitConverge bool
+	Dry              bool
+	Force            bool
+	MachineReadable  bool
+	Major            bool
+	Minor            bool
+	NoDomainChecks   bool
+	Patch            bool
+)

cli/internal/command.go

@@ -0,0 +1,144 @@
+package internal
+
+import (
+	"bufio"
+	"context"
+	"fmt"
+	"io/ioutil"
+	"os/exec"
+	"strings"
+
+	appPkg "coopcloud.tech/abra/pkg/app"
+	containerPkg "coopcloud.tech/abra/pkg/container"
+	"coopcloud.tech/abra/pkg/formatter"
+	"coopcloud.tech/abra/pkg/log"
+	"coopcloud.tech/abra/pkg/upstream/container"
+	"github.com/docker/cli/cli/command"
+	containertypes "github.com/docker/docker/api/types/container"
+	"github.com/docker/docker/api/types/filters"
+	dockerClient "github.com/docker/docker/client"
+	"github.com/docker/docker/pkg/archive"
+)
+
+// RunCmdRemote executes an abra.sh command in the target service
+func RunCmdRemote(
+	cl *dockerClient.Client,
+	app appPkg.App,
+	disableTTY bool,
+	abraSh, serviceName, cmdName, cmdArgs, remoteUser string) error {
+	filters := filters.NewArgs()
+	filters.Add("name", fmt.Sprintf("^%s_%s", app.StackName(), serviceName))
+
+	targetContainer, err := containerPkg.GetContainer(context.Background(), cl, filters, false)
+	if err != nil {
+		return err
+	}
+
+	log.Debugf("retrieved %s as target container on %s", formatter.ShortenID(targetContainer.ID), app.Server)
+
+	toTarOpts := &archive.TarOptions{NoOverwriteDirNonDir: true, Compression: archive.Gzip}
+	content, err := archive.TarWithOptions(abraSh, toTarOpts)
+	if err != nil {
+		return err
+	}
+
+	copyOpts := containertypes.CopyToContainerOptions{AllowOverwriteDirWithFile: false, CopyUIDGID: false}
+	if err := cl.CopyToContainer(context.Background(), targetContainer.ID, "/tmp", content, copyOpts); err != nil {
+		return err
+	}
+
+	// FIXME: avoid instantiating a new CLI
+	dcli, err := command.NewDockerCli()
+	if err != nil {
+		return err
+	}
+
+	shell := "/bin/bash"
+	findShell := []string{"test", "-e", shell}
+	execCreateOpts := containertypes.ExecOptions{
+		AttachStderr: true,
+		AttachStdin:  true,
+		AttachStdout: true,
+		Cmd:          findShell,
+		Detach:       false,
+		Tty:          false,
+	}
+
+	if _, err := container.RunExec(dcli, cl, targetContainer.ID, &execCreateOpts); err != nil {
+		log.Infof("%s does not exist for %s, use /bin/sh as fallback", shell, app.Name)
+		shell = "/bin/sh"
+	}
+
+	var cmd []string
+	if cmdArgs != "" {
+		cmd = []string{shell, "-c", fmt.Sprintf("TARGET=%s; APP_NAME=%s; STACK_NAME=%s; . /tmp/abra.sh; %s %s", serviceName, app.Name, app.StackName(), cmdName, cmdArgs)}
+	} else {
+		cmd = []string{shell, "-c", fmt.Sprintf("TARGET=%s; APP_NAME=%s; STACK_NAME=%s; . /tmp/abra.sh; %s", serviceName, app.Name, app.StackName(), cmdName)}
+	}
+
+	log.Debugf("running command: %s", strings.Join(cmd, " "))
+
+	if remoteUser != "" {
+		log.Debugf("running command with user %s", remoteUser)
+		execCreateOpts.User = remoteUser
+	}
+
+	execCreateOpts.Cmd = cmd
+
+	execCreateOpts.Tty = true
+	if disableTTY {
+		execCreateOpts.Tty = false
+		log.Debugf("not requesting a remote TTY")
+	}
+
+	if _, err := container.RunExec(dcli, cl, targetContainer.ID, &execCreateOpts); err != nil {
+		return err
+	}
+
+	return nil
+}
+
+func EnsureCommand(abraSh, recipeName, execCmd string) error {
+	bytes, err := ioutil.ReadFile(abraSh)
+	if err != nil {
+		return err
+	}
+
+	if !strings.Contains(string(bytes), execCmd) {
+		return fmt.Errorf("%s doesn't have a %s function", recipeName, execCmd)
+	}
+
+	return nil
+}
+
+// RunCmd runs a shell command and streams stdout/stderr in real-time.
+func RunCmd(cmd *exec.Cmd) error {
+	r, err := cmd.StdoutPipe()
+	if err != nil {
+		return err
+	}
+
+	cmd.Stderr = cmd.Stdout
+	done := make(chan struct{})
+	scanner := bufio.NewScanner(r)
+
+	go func() {
+		for scanner.Scan() {
+			line := scanner.Text()
+			fmt.Println(line)
+		}
+		done <- struct{}{}
+	}()
+
+	if err := cmd.Start(); err != nil {
+		return err
+	}
+
+	<-done
+
+	if err := cmd.Wait(); err != nil {
+		return err
+	}
+
+	return nil
+}

cli/internal/deploy.go

@@ -0,0 +1,218 @@
+package internal
+
+import (
+	"fmt"
+	"os"
+	"sort"
+	"strings"
+
+	appPkg "coopcloud.tech/abra/pkg/app"
+	"coopcloud.tech/abra/pkg/config"
+	"coopcloud.tech/abra/pkg/formatter"
+	"coopcloud.tech/abra/pkg/log"
+	"coopcloud.tech/tagcmp"
+	"github.com/AlecAivazis/survey/v2"
+	"github.com/charmbracelet/lipgloss"
+	dockerClient "github.com/docker/docker/client"
+)
+
+var borderStyle = lipgloss.NewStyle().
+	BorderStyle(lipgloss.ThickBorder()).
+	Padding(0, 1, 0, 1).
+	MaxWidth(79).
+	BorderForeground(lipgloss.Color("63"))
+
+var headerStyle = lipgloss.NewStyle().
+	Underline(true).
+	Bold(true).
+	PaddingBottom(1)
+
+var leftStyle = lipgloss.NewStyle().
+	Bold(true)
+
+var rightStyle = lipgloss.NewStyle()
+
+// horizontal is a JoinHorizontal helper function.
+func horizontal(left, mid, right string) string {
+	return lipgloss.JoinHorizontal(lipgloss.Left, left, mid, right)
+}
+
+func formatComposeFiles(composeFiles string) string {
+	return strings.ReplaceAll(composeFiles, ":", "\n")
+}
+
+// DeployOverview shows a deployment overview
+func DeployOverview(
+	app appPkg.App,
+	deployedVersion string,
+	toDeployVersion string,
+	releaseNotes string,
+	warnMessages []string,
+) error {
+	deployConfig := "compose.yml"
+	if composeFiles, ok := app.Env["COMPOSE_FILE"]; ok {
+		deployConfig = formatComposeFiles(composeFiles)
+	}
+
+	server := app.Server
+	if app.Server == "default" {
+		server = "local"
+	}
+
+	domain := app.Domain
+	if domain == "" {
+		domain = config.NO_DOMAIN_DEFAULT
+	}
+
+	envVersion := app.Recipe.EnvVersionRaw
+	if envVersion == "" {
+		envVersion = config.NO_VERSION_DEFAULT
+	}
+
+	rows := [][]string{
+		{"DOMAIN", domain},
+		{"RECIPE", app.Recipe.Name},
+		{"SERVER", server},
+		{"CONFIG", deployConfig},
+		{"", ""},
+		{"CURRENT DEPLOYMENT", formatter.BoldDirtyDefault(deployedVersion)},
+		{"ENV VERSION", formatter.BoldDirtyDefault(envVersion)},
+		{"NEW DEPLOYMENT", formatter.BoldDirtyDefault(toDeployVersion)},
+	}
+
+	deployType := getDeployType(deployedVersion, toDeployVersion)
+	overview := formatter.CreateOverview(fmt.Sprintf("%s OVERVIEW", deployType), rows)
+
+	fmt.Println(overview)
+
+	if releaseNotes != "" {
+		fmt.Print(releaseNotes)
+	}
+
+	for _, msg := range warnMessages {
+		log.Warn(msg)
+	}
+
+	if NoInput {
+		return nil
+	}
+
+	response := false
+	prompt := &survey.Confirm{Message: "proceed?"}
+	if err := survey.AskOne(prompt, &response); err != nil {
+		return err
+	}
+
+	if !response {
+		log.Fatal("deployment cancelled")
+	}
+
+	return nil
+}
+
+func getDeployType(currentVersion, newVersion string) string {
+	if newVersion == config.NO_DOMAIN_DEFAULT {
+		return "UNDEPLOY"
+	}
+	if strings.Contains(newVersion, "+U") {
+		return "CHAOS DEPLOY"
+	}
+	if strings.Contains(currentVersion, "+U") {
+		return "UNCHAOS DEPLOY"
+	}
+	if currentVersion == newVersion {
+		return "REDEPLOY"
+	}
+	if currentVersion == config.NO_VERSION_DEFAULT {
+		return "NEW DEPLOY"
+	}
+	currentParsed, err := tagcmp.Parse(currentVersion)
+	if err != nil {
+		return "DEPLOY"
+	}
+	newParsed, err := tagcmp.Parse(newVersion)
+	if err != nil {
+		return "DEPLOY"
+	}
+	if currentParsed.IsLessThan(newParsed) {
+		return "UPGRADE"
+	}
+	return "DOWNGRADE"
+}
+
+// PostCmds parses a string of commands and executes them inside of the respective services
+// the commands string must have the following format:
+// "<service> <command> <arguments>|<service> <command> <arguments>|... "
+func PostCmds(cl *dockerClient.Client, app appPkg.App, commands string) error {
+	if _, err := os.Stat(app.Recipe.AbraShPath); err != nil {
+		if os.IsNotExist(err) {
+			return fmt.Errorf(fmt.Sprintf("%s does not exist for %s?", app.Recipe.AbraShPath, app.Name))
+		}
+		return err
+	}
+
+	for _, command := range strings.Split(commands, "|") {
+		commandParts := strings.Split(command, " ")
+		if len(commandParts) < 2 {
+			return fmt.Errorf(fmt.Sprintf("not enough arguments: %s", command))
+		}
+		targetServiceName := commandParts[0]
+		cmdName := commandParts[1]
+		parsedCmdArgs := ""
+		if len(commandParts) > 2 {
+			parsedCmdArgs = fmt.Sprintf("%s ", strings.Join(commandParts[2:], " "))
+		}
+		log.Infof("running post-command '%s %s' in container %s", cmdName, parsedCmdArgs, targetServiceName)
+
+		if err := EnsureCommand(app.Recipe.AbraShPath, app.Recipe.Name, cmdName); err != nil {
+			return err
+		}
+
+		serviceNames, err := appPkg.GetAppServiceNames(app.Name)
+		if err != nil {
+			return err
+		}
+
+		matchingServiceName := false
+		for _, serviceName := range serviceNames {
+			if serviceName == targetServiceName {
+				matchingServiceName = true
+			}
+		}
+
+		if !matchingServiceName {
+			return fmt.Errorf(fmt.Sprintf("no service %s for %s?", targetServiceName, app.Name))
+		}
+
+		log.Debugf("running command %s %s within the context of %s_%s", cmdName, parsedCmdArgs, app.StackName(), targetServiceName)
+
+		requestTTY := true
+		if err := RunCmdRemote(
+			cl,
+			app,
+			requestTTY,
+			app.Recipe.AbraShPath, targetServiceName, cmdName, parsedCmdArgs, ""); err != nil {
+			return err
+		}
+	}
+	return nil
+}
+
+// SortVersionsDesc sorts versions in descending order.
+func SortVersionsDesc(versions []string) []string {
+	var tags []tagcmp.Tag
+
+	for _, v := range versions {
+		parsed, _ := tagcmp.Parse(v) // skips unsupported tags
+		tags = append(tags, parsed)
+	}
+
+	sort.Sort(tagcmp.ByTagDesc(tags))
+
+	var desc []string
+	for _, t := range tags {
+		desc = append(desc, t.String())
+	}
+
+	return desc
+}

cli/internal/deploy_test.go

@@ -0,0 +1,17 @@
+package internal
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+)
+
+func TestSortVersionsDesc(t *testing.T) {
+	versions := SortVersionsDesc([]string{
+		"0.2.3+1.2.2",
+		"1.0.0+2.2.2",
+	})
+
+	assert.Equal(t, "1.0.0+2.2.2", versions[0])
+	assert.Equal(t, "0.2.3+1.2.2", versions[1])
+}

cli/internal/ensure.go

@@ -0,0 +1,11 @@
+package internal
+
+import "coopcloud.tech/abra/pkg/recipe"
+
+func GetEnsureContext() recipe.EnsureContext {
+	return recipe.EnsureContext{
+		Chaos,
+		Offline,
+		IgnoreEnvVersion,
+	}
+}

cli/internal/recipe.go

@@ -0,0 +1,114 @@
+package internal
+
+import (
+	"fmt"
+
+	"coopcloud.tech/abra/pkg/formatter"
+	"coopcloud.tech/abra/pkg/log"
+	"coopcloud.tech/abra/pkg/recipe"
+	"github.com/AlecAivazis/survey/v2"
+	"github.com/distribution/reference"
+)
+
+// PromptBumpType prompts for version bump type
+func PromptBumpType(tagString, latestRelease string) error {
+	if (!Major && !Minor && !Patch) && tagString == "" {
+		fmt.Printf(`
+You need to make a decision about what kind of an update this new recipe
+version is. If someone else performs this upgrade, do they have to do some
+migration work or take care of some breaking changes? This can be signaled in
+the version you specify on the recipe deploy label and is called a semantic
+version.
+
+The latest published version is %s.
+
+Here is a semver cheat sheet (more on https://semver.org):
+
+    major: new features/bug fixes, backwards incompatible (e.g 1.0.0 -> 2.0.0).
+           the upgrade won't work without some preparation work and others need
+           to take care when performing it. "it could go wrong".
+
+    minor: new features/bug fixes, backwards compatible (e.g. 0.1.0 -> 0.2.0).
+           the upgrade should Just Work and there are no breaking changes in
+           the app and the recipe config. "it should go fine".
+
+    patch: bug fixes, backwards compatible (e.g. 0.0.1 -> 0.0.2). this upgrade
+           should also Just Work and is mostly to do with minor bug fixes
+           and/or security patches. "nothing to worry about".
+
+`, latestRelease)
+
+		var chosenBumpType string
+		prompt := &survey.Select{
+			Message: fmt.Sprintf("select recipe version increment type"),
+			Options: []string{"major", "minor", "patch"},
+		}
+
+		if err := survey.AskOne(prompt, &chosenBumpType); err != nil {
+			return err
+		}
+
+		SetBumpType(chosenBumpType)
+	}
+
+	return nil
+}
+
+// GetBumpType figures out which bump type is specified
+func GetBumpType() string {
+	var bumpType string
+
+	if Major {
+		bumpType = "major"
+	} else if Minor {
+		bumpType = "minor"
+	} else if Patch {
+		bumpType = "patch"
+	} else {
+		log.Fatal("no version bump type specififed?")
+	}
+
+	return bumpType
+}
+
+// SetBumpType figures out which bump type is specified
+func SetBumpType(bumpType string) {
+	if bumpType == "major" {
+		Major = true
+	} else if bumpType == "minor" {
+		Minor = true
+	} else if bumpType == "patch" {
+		Patch = true
+	} else {
+		log.Fatal("no version bump type specififed?")
+	}
+}
+
+// GetMainAppImage retrieves the main 'app' image name
+func GetMainAppImage(recipe recipe.Recipe) (string, error) {
+	var path string
+
+	config, err := recipe.GetComposeConfig(nil)
+	if err != nil {
+		return "", err
+	}
+	for _, service := range config.Services {
+		if service.Name == "app" {
+			img, err := reference.ParseNormalizedNamed(service.Image)
+			if err != nil {
+				return "", err
+			}
+
+			path = reference.Path(img)
+			path = formatter.StripTagMeta(path)
+
+			return path, nil
+		}
+	}
+
+	if path == "" {
+		return path, fmt.Errorf("%s has no main 'app' service?", recipe.Name)
+	}
+
+	return path, nil
+}

cli/internal/validate.go

@@ -0,0 +1,170 @@
+package internal
+
+import (
+	"strings"
+
+	"coopcloud.tech/abra/pkg/app"
+	"coopcloud.tech/abra/pkg/config"
+	"coopcloud.tech/abra/pkg/log"
+	"coopcloud.tech/abra/pkg/recipe"
+	"github.com/AlecAivazis/survey/v2"
+)
+
+// ValidateRecipe ensures the recipe arg is valid.
+func ValidateRecipe(args []string, cmdName string) recipe.Recipe {
+	var recipeName string
+	if len(args) > 0 {
+		recipeName = args[0]
+	}
+
+	if recipeName == "" && !NoInput {
+		var recipes []string
+
+		catl, err := recipe.ReadRecipeCatalogue(Offline)
+		if err != nil {
+			log.Fatal(err)
+		}
+
+		knownRecipes := make(map[string]bool)
+		for name := range catl {
+			knownRecipes[name] = true
+		}
+
+		localRecipes, err := recipe.GetRecipesLocal()
+		if err != nil {
+			log.Fatal(err)
+		}
+
+		for _, recipeLocal := range localRecipes {
+			if _, ok := knownRecipes[recipeLocal]; !ok {
+				knownRecipes[recipeLocal] = true
+			}
+		}
+
+		for recipeName := range knownRecipes {
+			recipes = append(recipes, recipeName)
+		}
+
+		prompt := &survey.Select{
+			Message: "Select recipe",
+			Options: recipes,
+		}
+		if err := survey.AskOne(prompt, &recipeName); err != nil {
+			log.Fatal(err)
+		}
+	}
+
+	if recipeName == "" {
+		log.Fatal("no recipe name provided")
+	}
+
+	chosenRecipe := recipe.Get(recipeName)
+	err := chosenRecipe.EnsureExists()
+	if err != nil {
+		log.Fatal(err)
+	}
+	_, err = chosenRecipe.GetComposeConfig(nil)
+	if err != nil {
+		if cmdName == "generate" {
+			if strings.Contains(err.Error(), "missing a compose") {
+				log.Fatal(err)
+			}
+			log.Warn(err)
+		} else {
+			if strings.Contains(err.Error(), "template_driver is not allowed") {
+				log.Warnf("ensure %s recipe compose.* files include \"version: '3.8'\"", recipeName)
+			}
+			log.Fatalf("unable to validate recipe: %s", err)
+		}
+	}
+
+	log.Debugf("validated %s as recipe argument", recipeName)
+
+	return chosenRecipe
+}
+
+// ValidateApp ensures the app name arg is valid.
+func ValidateApp(args []string) app.App {
+	if len(args) == 0 {
+		log.Fatal("no app provided")
+	}
+
+	appName := args[0]
+
+	app, err := app.Get(appName)
+	if err != nil {
+		log.Fatal(err)
+	}
+
+	log.Debugf("validated %s as app argument", appName)
+
+	return app
+}
+
+// ValidateDomain ensures the domain name arg is valid.
+func ValidateDomain(args []string) string {
+	var domainName string
+	if len(args) > 0 {
+		domainName = args[0]
+	}
+
+	if domainName == "" && !NoInput {
+		prompt := &survey.Input{
+			Message: "Specify a domain name",
+			Default: "example.com",
+		}
+		if err := survey.AskOne(prompt, &domainName); err != nil {
+			log.Fatal(err)
+		}
+	}
+
+	if domainName == "" {
+		log.Fatal("no domain provided")
+	}
+
+	log.Debugf("validated %s as domain argument", domainName)
+
+	return domainName
+}
+
+// ValidateServer ensures the server name arg is valid.
+func ValidateServer(args []string) string {
+	var serverName string
+	if len(args) > 0 {
+		serverName = args[0]
+	}
+
+	serverNames, err := config.ReadServerNames()
+	if err != nil {
+		log.Fatal(err)
+	}
+
+	if serverName == "" && !NoInput {
+		prompt := &survey.Select{
+			Message: "Specify a server name",
+			Options: serverNames,
+		}
+		if err := survey.AskOne(prompt, &serverName); err != nil {
+			log.Fatal(err)
+		}
+	}
+
+	matched := false
+	for _, name := range serverNames {
+		if name == serverName {
+			matched = true
+		}
+	}
+
+	if serverName == "" {
+		log.Fatal("no server provided")
+	}
+
+	if !matched {
+		log.Fatal("server doesn't exist?")
+	}
+
+	log.Debugf("validated %s as server argument", serverName)
+
+	return serverName
+}

cli/recipe/diff.go

@@ -0,0 +1,29 @@
+package recipe
+
+import (
+	"coopcloud.tech/abra/cli/internal"
+	"coopcloud.tech/abra/pkg/autocomplete"
+	gitPkg "coopcloud.tech/abra/pkg/git"
+	"coopcloud.tech/abra/pkg/log"
+	"github.com/spf13/cobra"
+)
+
+var RecipeDiffCommand = &cobra.Command{
+	Use:     "diff <recipe> [flags]",
+	Aliases: []string{"d"},
+	Short:   "Show unstaged changes in recipe config",
+	Long:    "This command requires /usr/bin/git.",
+	Args:    cobra.MinimumNArgs(1),
+	ValidArgsFunction: func(
+		cmd *cobra.Command,
+		args []string,
+		toComplete string) ([]string, cobra.ShellCompDirective) {
+		return autocomplete.RecipeNameComplete()
+	},
+	Run: func(cmd *cobra.Command, args []string) {
+		r := internal.ValidateRecipe(args, cmd.Name())
+		if err := gitPkg.DiffUnstaged(r.Dir); err != nil {
+			log.Fatal(err)
+		}
+	},
+}

cli/recipe/fetch.go

@@ -0,0 +1,134 @@
+package recipe
+
+import (
+	"os"
+
+	"coopcloud.tech/abra/cli/internal"
+	"coopcloud.tech/abra/pkg/autocomplete"
+	"coopcloud.tech/abra/pkg/formatter"
+	"coopcloud.tech/abra/pkg/log"
+	"coopcloud.tech/abra/pkg/recipe"
+	"github.com/go-git/go-git/v5"
+	gitCfg "github.com/go-git/go-git/v5/config"
+	"github.com/spf13/cobra"
+)
+
+var RecipeFetchCommand = &cobra.Command{
+	Use:     "fetch [recipe | --all] [flags]",
+	Aliases: []string{"f"},
+	Short:   "Clone recipe(s) locally",
+	Long:    `Using "--force/-f" Git syncs an existing recipe. It does not erase unstaged changes.`,
+	Args:    cobra.RangeArgs(0, 1),
+	Example: `  # fetch from recipe catalogue
+  abra recipe fetch gitea
+
+  # fetch from remote recipe
+  abra recipe fetch git.foo.org/recipes/myrecipe
+
+  # fetch with ssh remote for hacking
+  abra recipe fetch gitea --ssh`,
+	ValidArgsFunction: func(
+		cmd *cobra.Command,
+		args []string,
+		toComplete string) ([]string, cobra.ShellCompDirective) {
+		return autocomplete.RecipeNameComplete()
+	},
+	Run: func(cmd *cobra.Command, args []string) {
+		var recipeName string
+		if len(args) > 0 {
+			recipeName = args[0]
+		}
+
+		if recipeName == "" && !fetchAllRecipes {
+			log.Fatal("missing [recipe] or --all/-a")
+		}
+
+		if recipeName != "" && fetchAllRecipes {
+			log.Fatal("cannot use [recipe] and --all/-a together")
+		}
+
+		ensureCtx := internal.GetEnsureContext()
+		if recipeName != "" {
+			r := recipe.Get(recipeName)
+			if _, err := os.Stat(r.Dir); !os.IsNotExist(err) {
+				if !force {
+					log.Warnf("%s is already fetched", r.Name)
+					return
+				}
+			}
+
+			r = internal.ValidateRecipe(args, cmd.Name())
+
+			if sshRemote {
+				if r.SSHURL == "" {
+					log.Warnf("unable to discover SSH remote for %s", r.Name)
+					return
+				}
+
+				repo, err := git.PlainOpen(r.Dir)
+				if err != nil {
+					log.Fatalf("unable to open %s: %s", r.Dir, err)
+				}
+
+				if err = repo.DeleteRemote("origin"); err != nil {
+					log.Fatalf("unable to remove default remote in %s: %s", r.Dir, err)
+				}
+
+				if _, err := repo.CreateRemote(&gitCfg.RemoteConfig{
+					Name: "origin",
+					URLs: []string{r.SSHURL},
+				}); err != nil {
+					log.Fatalf("unable to set SSH remote in %s: %s", r.Dir, err)
+				}
+			}
+
+			return
+		}
+
+		catalogue, err := recipe.ReadRecipeCatalogue(internal.Offline)
+		if err != nil {
+			log.Fatal(err)
+		}
+
+		catlBar := formatter.CreateProgressbar(len(catalogue), "fetching latest recipes...")
+		for recipeName := range catalogue {
+			r := recipe.Get(recipeName)
+			if err := r.Ensure(ensureCtx); err != nil {
+				log.Error(err)
+			}
+			catlBar.Add(1)
+		}
+	},
+}
+
+var (
+	fetchAllRecipes bool
+	sshRemote       bool
+	force           bool
+)
+
+func init() {
+	RecipeFetchCommand.Flags().BoolVarP(
+		&fetchAllRecipes,
+		"all",
+		"a",
+		false,
+		"fetch all recipes",
+	)
+
+	RecipeFetchCommand.Flags().BoolVarP(
+		&sshRemote,
+		"ssh",
+		"s",
+		false,
+		"automatically set ssh remote",
+	)
+
+	RecipeFetchCommand.Flags().BoolVarP(
+		&force,
+		"force",
+		"f",
+		false,
+		"force re-fetch",
+	)
+}

cli/recipe/lint.go

@@ -0,0 +1,140 @@
+package recipe
+
+import (
+	"coopcloud.tech/abra/cli/internal"
+	"coopcloud.tech/abra/pkg/autocomplete"
+	"coopcloud.tech/abra/pkg/formatter"
+	"coopcloud.tech/abra/pkg/lint"
+	"coopcloud.tech/abra/pkg/log"
+	"github.com/spf13/cobra"
+)
+
+var RecipeLintCommand = &cobra.Command{
+	Use:     "lint <recipe> [flags]",
+	Short:   "Lint a recipe",
+	Aliases: []string{"l"},
+	Args:    cobra.MinimumNArgs(1),
+	ValidArgsFunction: func(
+		cmd *cobra.Command,
+		args []string,
+		toComplete string) ([]string, cobra.ShellCompDirective) {
+		return autocomplete.RecipeNameComplete()
+	},
+	Run: func(cmd *cobra.Command, args []string) {
+		recipe := internal.ValidateRecipe(args, cmd.Name())
+
+		if err := recipe.Ensure(internal.GetEnsureContext()); err != nil {
+			log.Fatal(err)
+		}
+
+		headers := []string{
+			"ref",
+			"rule",
+			"severity",
+			"satisfied",
+			"skipped",
+			"resolve",
+		}
+
+		table, err := formatter.CreateTable()
+		if err != nil {
+			log.Fatal(err)
+		}
+
+		table.Headers(headers...)
+
+		hasError := false
+		var rows [][]string
+		var warnMessages []string
+		for level := range lint.LintRules {
+			for _, rule := range lint.LintRules[level] {
+				if onlyError && rule.Level != "error" {
+					log.Debugf("skipping %s, does not have level \"error\"", rule.Ref)
+					continue
+				}
+
+				skipped := false
+				if rule.Skip(recipe) {
+					skipped = true
+				}
+
+				skippedOutput := "-"
+				if skipped {
+					skippedOutput = "✅"
+				}
+
+				satisfied := false
+				if !skipped {
+					ok, err := rule.Function(recipe)
+					if err != nil {
+						warnMessages = append(warnMessages, err.Error())
+					}
+
+					if !ok && rule.Level == "error" {
+						hasError = true
+					}
+
+					if ok {
+						satisfied = true
+					}
+				}
+
+				satisfiedOutput := "✅"
+				if !satisfied {
+					satisfiedOutput = "❌"
+					if skipped {
+						satisfiedOutput = "-"
+					}
+				}
+
+				row := []string{
+					rule.Ref,
+					rule.Description,
+					rule.Level,
+					satisfiedOutput,
+					skippedOutput,
+					rule.HowToResolve,
+				}
+
+				rows = append(rows, row)
+				table.Row(row...)
+			}
+		}
+
+		if len(rows) > 0 {
+			if err := formatter.PrintTable(table); err != nil {
+				log.Fatal(err)
+			}
+
+			for _, warnMsg := range warnMessages {
+				log.Warn(warnMsg)
+			}
+
+			if hasError {
+				log.Warnf("critical errors present in %s config", recipe.Name)
+			}
+		}
+	},
+}
+
+var (
+	onlyError bool
+)
+
+func init() {
+	RecipeLintCommand.Flags().BoolVarP(
+		&internal.Chaos,
+		"chaos",
+		"C",
+		false,
+		"ignore uncommitted recipes changes",
+	)
+
+	RecipeLintCommand.Flags().BoolVarP(
+		&onlyError,
+		"error",
+		"e",
+		false,
+		"only show errors",
+	)
+}

cli/recipe/list.go

@@ -0,0 +1,109 @@
+package recipe
+
+import (
+	"fmt"
+	"sort"
+	"strconv"
+	"strings"
+
+	"coopcloud.tech/abra/cli/internal"
+	"coopcloud.tech/abra/pkg/formatter"
+	"coopcloud.tech/abra/pkg/log"
+	"coopcloud.tech/abra/pkg/recipe"
+	"github.com/spf13/cobra"
+)
+
+var RecipeListCommand = &cobra.Command{
+	Use:     "list",
+	Short:   "List recipes",
+	Aliases: []string{"ls"},
+	Args:    cobra.NoArgs,
+	Run: func(cmd *cobra.Command, args []string) {
+		catl, err := recipe.ReadRecipeCatalogue(internal.Offline)
+		if err != nil {
+			log.Fatal(err)
+		}
+
+		recipes := catl.Flatten()
+		sort.Sort(recipe.ByRecipeName(recipes))
+
+		table, err := formatter.CreateTable()
+		if err != nil {
+			log.Fatal(err)
+		}
+
+		headers := []string{
+			"name",
+			"category",
+			"status",
+			"healthcheck",
+			"backups",
+			"email",
+			"tests",
+			"SSO",
+		}
+
+		table.Headers(headers...)
+
+		var rows [][]string
+		for _, recipe := range recipes {
+			row := []string{
+				recipe.Name,
+				recipe.Category,
+				strconv.Itoa(recipe.Features.Status),
+				recipe.Features.Healthcheck,
+				recipe.Features.Backups,
+				recipe.Features.Email,
+				recipe.Features.Tests,
+				recipe.Features.SSO,
+			}
+
+			if pattern != "" {
+				if strings.Contains(recipe.Name, pattern) {
+					table.Row(row...)
+					rows = append(rows, row)
+				}
+			} else {
+				table.Row(row...)
+				rows = append(rows, row)
+			}
+		}
+
+		if len(rows) > 0 {
+			if internal.MachineReadable {
+				out, err := formatter.ToJSON(headers, rows)
+				if err != nil {
+					log.Fatal("unable to render to JSON: %s", err)
+				}
+				fmt.Println(out)
+				return
+			}
+
+			if err := formatter.PrintTable(table); err != nil {
+				log.Fatal(err)
+			}
+		}
+	},
+}
+
+var (
+	pattern string
+)
+
+func init() {
+	RecipeListCommand.Flags().BoolVarP(
+		&internal.MachineReadable,
+		"machine",
+		"m",
+		false,
+		"print machine-readable output",
+	)
+
+	RecipeListCommand.Flags().StringVarP(
+		&pattern,
+		"pattern",
+		"p",
+		"",
+		"filter by recipe",
+	)
+}

cli/recipe/new.go

@@ -0,0 +1,127 @@
+package recipe
+
+import (
+	"bytes"
+	"fmt"
+	"os"
+	"path"
+	"text/template"
+
+	"coopcloud.tech/abra/pkg/autocomplete"
+	"coopcloud.tech/abra/pkg/config"
+	"coopcloud.tech/abra/pkg/git"
+	"coopcloud.tech/abra/pkg/log"
+	"coopcloud.tech/abra/pkg/recipe"
+	"github.com/spf13/cobra"
+)
+
+// recipeMetadata is the recipe metadata for the README.md
+type recipeMetadata struct {
+	Name        string
+	Description string
+	Category    string
+	Status      string
+	Image       string
+	Healthcheck string
+	Backups     string
+	Email       string
+	Tests       string
+	SSO         string
+}
+
+var RecipeNewCommand = &cobra.Command{
+	Use:     "new <recipe> [flags]",
+	Aliases: []string{"n"},
+	Short:   "Create a new recipe",
+	Long:    `A community managed recipe template is used.`,
+	Args:    cobra.ExactArgs(1),
+	ValidArgsFunction: func(
+		cmd *cobra.Command,
+		args []string,
+		toComplete string) ([]string, cobra.ShellCompDirective) {
+		return autocomplete.RecipeNameComplete()
+	},
+	Run: func(cmd *cobra.Command, args []string) {
+		recipeName := args[0]
+
+		r := recipe.Get(recipeName)
+		if _, err := os.Stat(r.Dir); !os.IsNotExist(err) {
+			log.Fatalf("%s recipe directory already exists?", r.Dir)
+		}
+
+		url := fmt.Sprintf("%s/example.git", config.REPOS_BASE_URL)
+		if err := git.Clone(r.Dir, url); err != nil {
+			log.Fatal(err)
+		}
+
+		gitRepo := path.Join(r.Dir, ".git")
+		if err := os.RemoveAll(gitRepo); err != nil {
+			log.Fatal(err)
+		}
+		log.Debugf("removed .git repo in %s", gitRepo)
+
+		meta := newRecipeMeta(recipeName)
+
+		for _, path := range []string{r.ReadmePath, r.SampleEnvPath} {
+			tpl, err := template.ParseFiles(path)
+			if err != nil {
+				log.Fatal(err)
+			}
+
+			var templated bytes.Buffer
+			if err := tpl.Execute(&templated, meta); err != nil {
+				log.Fatal(err)
+			}
+
+			if err := os.WriteFile(path, templated.Bytes(), 0o644); err != nil {
+				log.Fatal(err)
+			}
+		}
+
+		if err := git.Init(r.Dir, true, gitName, gitEmail); err != nil {
+			log.Fatal(err)
+		}
+
+		log.Infof("new recipe '%s' created: %s", recipeName, path.Join(r.Dir))
+		log.Info("happy hacking 🎉")
+	},
+}
+
+// newRecipeMeta creates a new recipeMetadata instance with defaults
+func newRecipeMeta(recipeName string) recipeMetadata {
+	return recipeMetadata{
+		Name:        recipeName,
+		Description: "> One line description of the recipe",
+		Category:    "Apps",
+		Status:      "0",
+		Image:       fmt.Sprintf("[`%s`](https://hub.docker.com/r/%s), 4, upstream", recipeName, recipeName),
+		Healthcheck: "No",
+		Backups:     "No",
+		Email:       "No",
+		Tests:       "No",
+		SSO:         "No",
+	}
+}
+
+var (
+	gitName  string
+	gitEmail string
+)
+
+func init() {
+	RecipeNewCommand.Flags().StringVarP(
+		&gitName,
+		"git-name",
+		"N",
+		"",
+		"Git (user) name to do commits with",
+	)
+
+	RecipeNewCommand.Flags().StringVarP(
+		&gitEmail,
+		"git-email",
+		"e",
+		"",
+		"Git email name to do commits with",
+	)
+}

cli/recipe/recipe.go

@@ -0,0 +1,19 @@
+package recipe
+
+import "github.com/spf13/cobra"
+
+// RecipeCommand defines all recipe related sub-commands.
+var RecipeCommand = &cobra.Command{
+	Use:     "recipe [cmd] [args] [flags]",
+	Aliases: []string{"r"},
+	Short:   "Manage recipes",
+	Long: `A recipe is a blueprint for an app.
+
+It is a bunch of config files which describe how to deploy and maintain an app.
+Recipes are maintained by the Co-op Cloud community and you can use Abra to
+read them, deploy them and create apps for you.
+
+Anyone who uses a recipe can become a maintainer. Maintainers typically make
+sure the recipe is in good working order and the config upgraded in a timely
+manner.`,
+}

cli/recipe/release.go

@@ -0,0 +1,613 @@
+package recipe
+
+import (
+	"errors"
+	"fmt"
+	"os"
+	"path"
+	"strconv"
+	"strings"
+
+	"coopcloud.tech/abra/cli/internal"
+	"coopcloud.tech/abra/pkg/autocomplete"
+	"coopcloud.tech/abra/pkg/formatter"
+	gitPkg "coopcloud.tech/abra/pkg/git"
+	"coopcloud.tech/abra/pkg/log"
+	"coopcloud.tech/abra/pkg/recipe"
+	"coopcloud.tech/tagcmp"
+	"github.com/AlecAivazis/survey/v2"
+	"github.com/distribution/reference"
+	"github.com/go-git/go-git/v5"
+	"github.com/spf13/cobra"
+)
+
+var RecipeReleaseCommand = &cobra.Command{
+	Use:     "release <recipe> [version] [flags]",
+	Aliases: []string{"rl"},
+	Short:   "Release a new recipe version",
+	Long: `Create a new version of a recipe.
+
+These versions are then published on the Co-op Cloud recipe catalogue. These
+versions take the following form:
+
+    a.b.c+x.y.z
+
+Where the "a.b.c" part is a semantic version determined by the maintainer. The
+"x.y.z" part is the image tag of the recipe "app" service (the main container
+which contains the software to be used, by naming convention).
+
+We maintain a semantic versioning scheme ("a.b.c") alongside the recipe
+versioning scheme ("x.y.z") in order to maximise the chances that the nature of
+recipe updates are properly communicated. I.e. developers of an app might
+publish a minor version but that might lead to changes in the recipe which are
+major and therefore require intervention while doing the upgrade work.
+
+Publish your new release to git.coopcloud.tech with "--publish/-p". This
+requires that you have permission to git push to these repositories and have
+your SSH keys configured on your account.`,
+	Args: cobra.RangeArgs(1, 2),
+	ValidArgsFunction: func(
+		cmd *cobra.Command,
+		args []string,
+		toComplete string) ([]string, cobra.ShellCompDirective) {
+		switch l := len(args); l {
+		case 0:
+			return autocomplete.RecipeNameComplete()
+		case 1:
+			return autocomplete.RecipeVersionComplete(args[0])
+		default:
+			return nil, cobra.ShellCompDirectiveDefault
+		}
+	},
+	Run: func(cmd *cobra.Command, args []string) {
+		recipe := internal.ValidateRecipe(args, cmd.Name())
+
+		imagesTmp, err := getImageVersions(recipe)
+		if err != nil {
+			log.Fatal(err)
+		}
+
+		mainApp, err := internal.GetMainAppImage(recipe)
+		if err != nil {
+			log.Fatal(err)
+		}
+
+		mainAppVersion := imagesTmp[mainApp]
+		if mainAppVersion == "" {
+			log.Fatalf("main app service version for %s is empty?", recipe.Name)
+		}
+
+		var tagString string
+		if len(args) == 2 {
+			tagString = args[1]
+		}
+
+		if tagString != "" {
+			if _, err := tagcmp.Parse(tagString); err != nil {
+				log.Fatalf("cannot parse %s, invalid tag specified?", tagString)
+			}
+		}
+
+		if (internal.Major || internal.Minor || internal.Patch) && tagString != "" {
+			log.Fatal("cannot specify tag and bump type at the same time")
+		}
+
+		if tagString != "" {
+			if err := createReleaseFromTag(recipe, tagString, mainAppVersion); err != nil {
+				log.Fatal(err)
+			}
+		}
+
+		tags, err := recipe.Tags()
+		if err != nil {
+			log.Fatal(err)
+		}
+
+		if tagString == "" && (!internal.Major && !internal.Minor && !internal.Patch) {
+			var err error
+			tagString, err = getLabelVersion(recipe, false)
+			if err != nil {
+				log.Fatal(err)
+			}
+		}
+
+		isClean, err := gitPkg.IsClean(recipe.Dir)
+		if err != nil {
+			log.Fatal(err)
+		}
+
+		if !isClean {
+			log.Infof("%s currently has these unstaged changes 👇", recipe.Name)
+			if err := gitPkg.DiffUnstaged(recipe.Dir); err != nil {
+				log.Fatal(err)
+			}
+		}
+
+		if len(tags) > 0 {
+			log.Warnf("previous git tags detected, assuming this is a new semver release")
+			if err := createReleaseFromPreviousTag(tagString, mainAppVersion, recipe, tags); err != nil {
+				log.Fatal(err)
+			}
+		} else {
+			log.Warnf("no tag specified and no previous tag available for %s, assuming this is the initial release", recipe.Name)
+
+			if err := createReleaseFromTag(recipe, tagString, mainAppVersion); err != nil {
+				if cleanUpErr := cleanUpTag(recipe, tagString); err != nil {
+					log.Fatal(cleanUpErr)
+				}
+				log.Fatal(err)
+			}
+		}
+
+		return
+	},
+}
+
+// getImageVersions retrieves image versions for a recipe
+func getImageVersions(recipe recipe.Recipe) (map[string]string, error) {
+	services := make(map[string]string)
+
+	config, err := recipe.GetComposeConfig(nil)
+	if err != nil {
+		return nil, err
+	}
+	missingTag := false
+	for _, service := range config.Services {
+		if service.Image == "" {
+			continue
+		}
+
+		img, err := reference.ParseNormalizedNamed(service.Image)
+		if err != nil {
+			return services, err
+		}
+
+		path := reference.Path(img)
+
+		path = formatter.StripTagMeta(path)
+
+		var tag string
+		switch img.(type) {
+		case reference.NamedTagged:
+			tag = img.(reference.NamedTagged).Tag()
+		case reference.Named:
+			if service.Name == "app" {
+				missingTag = true
+			}
+			continue
+		}
+
+		services[path] = tag
+	}
+
+	if missingTag {
+		return services, fmt.Errorf("app service is missing image tag?")
+	}
+
+	return services, nil
+}
+
+// createReleaseFromTag creates a new release based on a supplied recipe version string
+func createReleaseFromTag(recipe recipe.Recipe, tagString, mainAppVersion string) error {
+	var err error
+
+	repo, err := git.PlainOpen(recipe.Dir)
+	if err != nil {
+		return err
+	}
+
+	tag, err := tagcmp.Parse(tagString)
+	if err != nil {
+		return err
+	}
+
+	if tag.MissingMinor {
+		tag.Minor = "0"
+		tag.MissingMinor = false
+	}
+
+	if tag.MissingPatch {
+		tag.Patch = "0"
+		tag.MissingPatch = false
+	}
+
+	if tagString == "" {
+		tagString = fmt.Sprintf("%s+%s", tag.String(), mainAppVersion)
+	}
+
+	if err := addReleaseNotes(recipe, tagString); err != nil {
+		log.Fatal(err)
+	}
+
+	if err := commitRelease(recipe, tagString); err != nil {
+		log.Fatal(err)
+	}
+
+	if err := tagRelease(tagString, repo); err != nil {
+		log.Fatal(err)
+	}
+
+	if err := pushRelease(recipe, tagString); err != nil {
+		log.Fatal(err)
+	}
+
+	return nil
+}
+
+// btoi converts a boolean value into an integer
+func btoi(b bool) int {
+	if b {
+		return 1
+	}
+
+	return 0
+}
+
+// getTagCreateOptions constructs git tag create options
+func getTagCreateOptions(tag string) (git.CreateTagOptions, error) {
+	msg := fmt.Sprintf("chore: publish %s release", tag)
+	return git.CreateTagOptions{Message: msg}, nil
+}
+
+// addReleaseNotes checks if the release/next release note exists and moves the
+// file to release/<tag>.
+func addReleaseNotes(recipe recipe.Recipe, tag string) error {
+	releaseDir := path.Join(recipe.Dir, "release")
+	if _, err := os.Stat(releaseDir); errors.Is(err, os.ErrNotExist) {
+		if err := os.Mkdir(releaseDir, 0755); err != nil {
+			return err
+		}
+	}
+
+	tagReleaseNotePath := path.Join(releaseDir, tag)
+	if _, err := os.Stat(tagReleaseNotePath); err == nil {
+		// Release note for current tag already exist exists.
+		return nil
+	} else if !errors.Is(err, os.ErrNotExist) {
+		return err
+	}
+
+	var addNextAsReleaseNotes bool
+
+	nextReleaseNotePath := path.Join(releaseDir, "next")
+	if _, err := os.Stat(nextReleaseNotePath); err == nil {
+		// release/next note exists. Move it to release/<tag>
+		if internal.Dry {
+			log.Debugf("dry run: move release note from 'next' to %s", tag)
+			return nil
+		}
+
+		if !internal.NoInput {
+			prompt := &survey.Confirm{
+				Message: "Use release note in release/next?",
+			}
+
+			if err := survey.AskOne(prompt, &addNextAsReleaseNotes); err != nil {
+				return err
+			}
+
+			if !addNextAsReleaseNotes {
+				return nil
+			}
+		}
+
+		if err := os.Rename(nextReleaseNotePath, tagReleaseNotePath); err != nil {
+			return err
+		}
+
+		if err := gitPkg.Add(recipe.Dir, path.Join("release", "next"), internal.Dry); err != nil {
+			return err
+		}
+
+		if err := gitPkg.Add(recipe.Dir, path.Join("release", tag), internal.Dry); err != nil {
+			return err
+		}
+	} else if !errors.Is(err, os.ErrNotExist) {
+		return err
+	}
+
+	// NOTE(d1): No release note exists for the current release. Or, we've
+	// already used release/next as the release note
+	if internal.NoInput || addNextAsReleaseNotes {
+		return nil
+	}
+
+	prompt := &survey.Input{
+		Message: "Release Note (leave empty for no release note)",
+	}
+
+	var releaseNote string
+	if err := survey.AskOne(prompt, &releaseNote); err != nil {
+		return err
+	}
+
+	if releaseNote == "" {
+		return nil
+	}
+
+	if err := os.WriteFile(tagReleaseNotePath, []byte(releaseNote), 0o644); err != nil {
+		return err
+	}
+
+	if err := gitPkg.Add(recipe.Dir, path.Join("release", tag), internal.Dry); err != nil {
+		return err
+	}
+
+	return nil
+}
+
+func commitRelease(recipe recipe.Recipe, tag string) error {
+	if internal.Dry {
+		log.Debugf("dry run: no changes committed")
+		return nil
+	}
+
+	isClean, err := gitPkg.IsClean(recipe.Dir)
+	if err != nil {
+		return err
+	}
+
+	if isClean {
+		if !internal.Dry {
+			return fmt.Errorf("no changes discovered in %s, nothing to publish?", recipe.Dir)
+		}
+	}
+
+	msg := fmt.Sprintf("chore: publish %s release", tag)
+	if err := gitPkg.Commit(recipe.Dir, msg, internal.Dry); err != nil {
+		return err
+	}
+
+	return nil
+}
+
+func tagRelease(tagString string, repo *git.Repository) error {
+	if internal.Dry {
+		log.Debugf("dry run: no git tag created (%s)", tagString)
+		return nil
+	}
+
+	head, err := repo.Head()
+	if err != nil {
+		return err
+	}
+
+	createTagOptions, err := getTagCreateOptions(tagString)
+	if err != nil {
+		return err
+	}
+
+	_, err = repo.CreateTag(tagString, head.Hash(), &createTagOptions)
+	if err != nil {
+		return err
+	}
+
+	hash := formatter.SmallSHA(head.Hash().String())
+	log.Debugf(fmt.Sprintf("created tag %s at %s", tagString, hash))
+
+	return nil
+}
+
+func pushRelease(recipe recipe.Recipe, tagString string) error {
+	if internal.Dry {
+		log.Info("dry run: no changes published")
+		return nil
+	}
+
+	if !publish && !internal.NoInput {
+		prompt := &survey.Confirm{
+			Message: "publish new release?",
+		}
+
+		if err := survey.AskOne(prompt, &publish); err != nil {
+			return err
+		}
+	}
+
+	if publish {
+		if err := recipe.Push(internal.Dry); err != nil {
+			return err
+		}
+		url := fmt.Sprintf("%s/src/tag/%s", recipe.GitURL, tagString)
+		log.Infof("new release published: %s", url)
+	} else {
+		log.Info("no -p/--publish passed, not publishing")
+	}
+
+	return nil
+}
+
+func createReleaseFromPreviousTag(tagString, mainAppVersion string, recipe recipe.Recipe, tags []string) error {
+	repo, err := git.PlainOpen(recipe.Dir)
+	if err != nil {
+		return err
+	}
+
+	bumpType := btoi(internal.Major)*4 + btoi(internal.Minor)*2 + btoi(internal.Patch)
+	if bumpType != 0 {
+		if (bumpType & (bumpType - 1)) != 0 {
+			return fmt.Errorf("you can only use one of: --major, --minor, --patch")
+		}
+	}
+
+	var lastGitTag tagcmp.Tag
+	for _, tag := range tags {
+		parsed, err := tagcmp.Parse(tag)
+		if err != nil {
+			return err
+		}
+
+		if (lastGitTag == tagcmp.Tag{}) {
+			lastGitTag = parsed
+		} else if parsed.IsGreaterThan(lastGitTag) {
+			lastGitTag = parsed
+		}
+	}
+
+	newTag := lastGitTag
+	if internal.Patch {
+		now, err := strconv.Atoi(newTag.Patch)
+		if err != nil {
+			return err
+		}
+
+		newTag.Patch = strconv.Itoa(now + 1)
+	} else if internal.Minor {
+		now, err := strconv.Atoi(newTag.Minor)
+		if err != nil {
+			return err
+		}
+
+		newTag.Patch = "0"
+		newTag.Minor = strconv.Itoa(now + 1)
+	} else if internal.Major {
+		now, err := strconv.Atoi(newTag.Major)
+		if err != nil {
+			return err
+		}
+
+		newTag.Patch = "0"
+		newTag.Minor = "0"
+		newTag.Major = strconv.Itoa(now + 1)
+	}
+
+	if tagString == "" {
+		if err := internal.PromptBumpType(tagString, lastGitTag.String()); err != nil {
+			return err
+		}
+	}
+
+	if internal.Major || internal.Minor || internal.Patch {
+		newTag.Metadata = mainAppVersion
+		tagString = newTag.String()
+	}
+
+	if lastGitTag.String() == tagString {
+		log.Fatalf("latest git tag (%s) and synced label (%s) are the same?", lastGitTag, tagString)
+	}
+
+	if !internal.NoInput {
+		prompt := &survey.Confirm{
+			Message: fmt.Sprintf("current: %s, new: %s, correct?", lastGitTag, tagString),
+		}
+
+		var ok bool
+		if err := survey.AskOne(prompt, &ok); err != nil {
+			log.Fatal(err)
+		}
+
+		if !ok {
+			log.Fatal("exiting as requested")
+		}
+	}
+
+	if err := addReleaseNotes(recipe, tagString); err != nil {
+		log.Fatal(err)
+	}
+
+	if err := commitRelease(recipe, tagString); err != nil {
+		log.Fatalf("failed to commit changes: %s", err.Error())
+	}
+
+	if err := tagRelease(tagString, repo); err != nil {
+		log.Fatalf("failed to tag release: %s", err.Error())
+	}
+
+	if err := pushRelease(recipe, tagString); err != nil {
+		log.Fatalf("failed to publish new release: %s", err.Error())
+	}
+
+	return nil
+}
+
+// cleanUpTag removes a freshly created tag
+func cleanUpTag(recipe recipe.Recipe, tag string) error {
+	repo, err := git.PlainOpen(recipe.Dir)
+	if err != nil {
+		return err
+	}
+
+	if err := repo.DeleteTag(tag); err != nil {
+		if !strings.Contains(err.Error(), "not found") {
+			return err
+		}
+	}
+
+	log.Debugf("removed freshly created tag %s", tag)
+
+	return nil
+}
+
+func getLabelVersion(recipe recipe.Recipe, prompt bool) (string, error) {
+	initTag, err := recipe.GetVersionLabelLocal()
+	if err != nil {
+		return "", err
+	}
+
+	if initTag == "" {
+		log.Fatalf("unable to read version for %s from synced label. Did you try running \"abra recipe sync %s\" already?", recipe.Name, recipe.Name)
+	}
+
+	log.Warnf("discovered %s as currently synced recipe label", initTag)
+
+	if prompt && !internal.NoInput {
+		var response bool
+		prompt := &survey.Confirm{Message: fmt.Sprintf("use %s as the new version?", initTag)}
+		if err := survey.AskOne(prompt, &response); err != nil {
+			return "", err
+		}
+
+		if !response {
+			return "", fmt.Errorf("please fix your synced label for %s and re-run this command", recipe.Name)
+		}
+	}
+
+	return initTag, nil
+}
+
+var (
+	publish bool
+)
+
+func init() {
+	RecipeReleaseCommand.Flags().BoolVarP(
+		&internal.Dry,
+		"dry-run",
+		"r",
+		false,
+		"report changes that would be made",
+	)
+
+	RecipeReleaseCommand.Flags().BoolVarP(
+		&internal.Major,
+		"major",
+		"x",
+		false,
+		"increase the major part of the version",
+	)
+
+	RecipeReleaseCommand.Flags().BoolVarP(
+		&internal.Minor,
+		"minor",
+		"y",
+		false,
+		"increase the minor part of the version",
+	)
+
+	RecipeReleaseCommand.Flags().BoolVarP(
+		&internal.Patch,
+		"patch",
+		"z",
+		false,
+		"increase the patch part of the version",
+	)
+
+	RecipeReleaseCommand.Flags().BoolVarP(
+		&publish,
+		"publish",
+		"p",
+		false,
+		"publish changes to git.coopcloud.tech",
+	)
+
+}

cli/recipe/reset.go

@@ -0,0 +1,46 @@
+package recipe
+
+import (
+	"coopcloud.tech/abra/cli/internal"
+	"coopcloud.tech/abra/pkg/autocomplete"
+	"coopcloud.tech/abra/pkg/log"
+	"github.com/go-git/go-git/v5"
+	"github.com/spf13/cobra"
+)
+
+var RecipeResetCommand = &cobra.Command{
+	Use:     "reset <recipe> [flags]",
+	Aliases: []string{"rs"},
+	Short:   "Remove all unstaged changes from recipe config",
+	Long:    "WARNING: this will delete your changes. Be Careful.",
+	Args:    cobra.ExactArgs(1),
+	ValidArgsFunction: func(
+		cmd *cobra.Command,
+		args []string,
+		toComplete string) ([]string, cobra.ShellCompDirective) {
+		return autocomplete.RecipeNameComplete()
+	},
+	Run: func(cmd *cobra.Command, args []string) {
+		r := internal.ValidateRecipe(args, cmd.Name())
+
+		repo, err := git.PlainOpen(r.Dir)
+		if err != nil {
+			log.Fatal(err)
+		}
+
+		ref, err := repo.Head()
+		if err != nil {
+			log.Fatal(err)
+		}
+
+		worktree, err := repo.Worktree()
+		if err != nil {
+			log.Fatal(err)
+		}
+
+		opts := &git.ResetOptions{Commit: ref.Hash(), Mode: git.HardReset}
+		if err := worktree.Reset(opts); err != nil {
+			log.Fatal(err)
+		}
+	},
+}

cli/recipe/sync.go

@@ -0,0 +1,250 @@
+package recipe
+
+import (
+	"fmt"
+	"strconv"
+
+	"coopcloud.tech/abra/cli/internal"
+	"coopcloud.tech/abra/pkg/autocomplete"
+	gitPkg "coopcloud.tech/abra/pkg/git"
+	"coopcloud.tech/abra/pkg/log"
+	"coopcloud.tech/tagcmp"
+	"github.com/AlecAivazis/survey/v2"
+	"github.com/go-git/go-git/v5"
+	"github.com/go-git/go-git/v5/plumbing"
+	"github.com/spf13/cobra"
+)
+
+var RecipeSyncCommand = &cobra.Command{
+	Use:     "sync <recipe> [version] [flags]",
+	Aliases: []string{"s"},
+	Short:   "Sync recipe version label",
+	Long: `Generate labels for the main recipe service.
+
+By convention, the service named "app" using the following format:
+
+    coop-cloud.${STACK_NAME}.version=<version>
+
+Where [version] can be specifed on the command-line or Abra can attempt to
+auto-generate it for you. The <recipe> configuration will be updated on the
+local file system.`,
+	Args: cobra.RangeArgs(1, 2),
+	ValidArgsFunction: func(
+		cmd *cobra.Command,
+		args []string,
+		toComplete string) ([]string, cobra.ShellCompDirective) {
+		switch l := len(args); l {
+		case 0:
+			return autocomplete.RecipeNameComplete()
+		case 1:
+			return autocomplete.RecipeVersionComplete(args[0])
+		default:
+			return nil, cobra.ShellCompDirectiveError
+		}
+	},
+	Run: func(cmd *cobra.Command, args []string) {
+		recipe := internal.ValidateRecipe(args, cmd.Name())
+
+		mainApp, err := internal.GetMainAppImage(recipe)
+		if err != nil {
+			log.Fatal(err)
+		}
+
+		imagesTmp, err := getImageVersions(recipe)
+		if err != nil {
+			log.Fatal(err)
+		}
+
+		mainAppVersion := imagesTmp[mainApp]
+
+		tags, err := recipe.Tags()
+		if err != nil {
+			log.Fatal(err)
+		}
+
+		var nextTag string
+		if len(args) == 2 {
+			nextTag = args[1]
+		}
+
+		if len(tags) == 0 && nextTag == "" {
+			log.Warnf("no git tags found for %s", recipe.Name)
+			if internal.NoInput {
+				log.Fatalf("unable to continue, input required for initial version")
+			}
+			fmt.Println(fmt.Sprintf(`
+The following options are two types of initial semantic version that you can
+pick for %s that will be published in the recipe catalogue. This follows the
+semver convention (more on https://semver.org), here is a short cheatsheet
+
+    0.1.0: development release, still hacking. when you make a major upgrade
+           you increment the "y" part (i.e. 0.1.0 -> 0.2.0) and only move to
+           using the "x" part when things are stable.
+
+    1.0.0: public release, assumed to be working. you already have a stable
+           and reliable deployment of this app and feel relatively confident
+           about it.
+
+If you want people to be able alpha test your current config for %s but don't
+think it is quite reliable, go with 0.1.0 and people will know that things are
+likely to change.
+
+`, recipe.Name, recipe.Name))
+			var chosenVersion string
+			edPrompt := &survey.Select{
+				Message: "which version do you want to begin with?",
+				Options: []string{"0.1.0", "1.0.0"},
+			}
+
+			if err := survey.AskOne(edPrompt, &chosenVersion); err != nil {
+				log.Fatal(err)
+			}
+
+			nextTag = fmt.Sprintf("%s+%s", chosenVersion, mainAppVersion)
+		}
+
+		if nextTag == "" && (!internal.Major && !internal.Minor && !internal.Patch) {
+			latestRelease := tags[len(tags)-1]
+			if err := internal.PromptBumpType("", latestRelease); err != nil {
+				log.Fatal(err)
+			}
+		}
+
+		if nextTag == "" {
+			repo, err := git.PlainOpen(recipe.Dir)
+			if err != nil {
+				log.Fatal(err)
+			}
+
+			var lastGitTag tagcmp.Tag
+			iter, err := repo.Tags()
+			if err != nil {
+				log.Fatal(err)
+			}
+
+			if err := iter.ForEach(func(ref *plumbing.Reference) error {
+				obj, err := repo.TagObject(ref.Hash())
+				if err != nil {
+					log.Fatal("Tag at commit ", ref.Hash(), " is unannotated or otherwise broken. Please fix it.")
+					return err
+				}
+
+				tagcmpTag, err := tagcmp.Parse(obj.Name)
+				if err != nil {
+					return err
+				}
+
+				if (lastGitTag == tagcmp.Tag{}) {
+					lastGitTag = tagcmpTag
+				} else if tagcmpTag.IsGreaterThan(lastGitTag) {
+					lastGitTag = tagcmpTag
+				}
+
+				return nil
+			}); err != nil {
+				log.Fatal(err)
+			}
+
+			// bumpType is used to decide what part of the tag should be incremented
+			bumpType := btoi(internal.Major)*4 + btoi(internal.Minor)*2 + btoi(internal.Patch)
+			if bumpType != 0 {
+				// a bitwise check if the number is a power of 2
+				if (bumpType & (bumpType - 1)) != 0 {
+					log.Fatal("you can only use one version flag: --major, --minor or --patch")
+				}
+			}
+
+			newTag := lastGitTag
+			if bumpType > 0 {
+				if internal.Patch {
+					now, err := strconv.Atoi(newTag.Patch)
+					if err != nil {
+						log.Fatal(err)
+					}
+
+					newTag.Patch = strconv.Itoa(now + 1)
+				} else if internal.Minor {
+					now, err := strconv.Atoi(newTag.Minor)
+					if err != nil {
+						log.Fatal(err)
+					}
+
+					newTag.Patch = "0"
+					newTag.Minor = strconv.Itoa(now + 1)
+				} else if internal.Major {
+					now, err := strconv.Atoi(newTag.Major)
+					if err != nil {
+						log.Fatal(err)
+					}
+
+					newTag.Patch = "0"
+					newTag.Minor = "0"
+					newTag.Major = strconv.Itoa(now + 1)
+				}
+			}
+
+			newTag.Metadata = mainAppVersion
+			log.Debugf("choosing %s as new version for %s", newTag.String(), recipe.Name)
+			nextTag = newTag.String()
+		}
+
+		if _, err := tagcmp.Parse(nextTag); err != nil {
+			log.Fatalf("invalid version %s specified", nextTag)
+		}
+
+		mainService := "app"
+		label := fmt.Sprintf("coop-cloud.${STACK_NAME}.version=%s", nextTag)
+		if !internal.Dry {
+			if err := recipe.UpdateLabel("compose.y*ml", mainService, label); err != nil {
+				log.Fatal(err)
+			}
+		} else {
+			log.Infof("dry run: not syncing label %s for recipe %s", nextTag, recipe.Name)
+		}
+
+		isClean, err := gitPkg.IsClean(recipe.Dir)
+		if err != nil {
+			log.Fatal(err)
+		}
+		if !isClean {
+			log.Infof("%s currently has these unstaged changes 👇", recipe.Name)
+			if err := gitPkg.DiffUnstaged(recipe.Dir); err != nil {
+				log.Fatal(err)
+			}
+		}
+	},
+}
+
+func init() {
+	RecipeSyncCommand.Flags().BoolVarP(
+		&internal.Dry,
+		"dry-run",
+		"r",
+		false,
+		"report changes that would be made",
+	)
+
+	RecipeSyncCommand.Flags().BoolVarP(
+		&internal.Major,
+		"major",
+		"x",
+		false,
+		"increase the major part of the version",
+	)
+
+	RecipeSyncCommand.Flags().BoolVarP(
+		&internal.Minor,
+		"minor",
+		"y",
+		false,
+		"increase the minor part of the version",
+	)
+
+	RecipeSyncCommand.Flags().BoolVarP(
+		&internal.Patch,
+		"patch",
+		"z",
+		false,
+		"increase the patch part of the version",
+	)
+}

cli/recipe/upgrade.go

@@ -0,0 +1,381 @@
+package recipe
+
+import (
+	"bufio"
+	"encoding/json"
+	"fmt"
+	"os"
+	"path"
+	"sort"
+	"strings"
+
+	"coopcloud.tech/abra/cli/internal"
+	"coopcloud.tech/abra/pkg/autocomplete"
+	"coopcloud.tech/abra/pkg/client"
+	"coopcloud.tech/abra/pkg/formatter"
+	gitPkg "coopcloud.tech/abra/pkg/git"
+	"coopcloud.tech/abra/pkg/log"
+	recipePkg "coopcloud.tech/abra/pkg/recipe"
+	"coopcloud.tech/tagcmp"
+	"github.com/AlecAivazis/survey/v2"
+	"github.com/distribution/reference"
+	"github.com/spf13/cobra"
+)
+
+type imgPin struct {
+	image   string
+	version tagcmp.Tag
+}
+
+// anUpgrade represents a single service upgrade (as within a recipe), and the
+// list of tags that it can be upgraded to, for serialization purposes.
+type anUpgrade struct {
+	Service     string   `json:"service"`
+	Image       string   `json:"image"`
+	Tag         string   `json:"tag"`
+	UpgradeTags []string `json:"upgrades"`
+}
+
+var RecipeUpgradeCommand = &cobra.Command{
+	Use:     "upgrade <recipe> [flags]",
+	Aliases: []string{"u"},
+	Short:   "Upgrade recipe image tags",
+	Long: `Upgrade a given <recipe> configuration.
+
+It will update the relevant compose file tags on the local file system.
+
+Some image tags cannot be parsed because they do not follow some sort of
+semver-like convention. In this case, all possible tags will be listed and it
+is up to the end-user to decide.
+
+The command is interactive and will show a select input which allows you to
+make a seclection. Use the "?" key to see more help on navigating this
+interface.
+
+You may invoke this command in "wizard" mode and be prompted for input.`,
+	Args: cobra.RangeArgs(0, 1),
+	ValidArgsFunction: func(
+		cmd *cobra.Command,
+		args []string,
+		toComplete string) ([]string, cobra.ShellCompDirective) {
+		return autocomplete.RecipeNameComplete()
+	},
+	Run: func(cmd *cobra.Command, args []string) {
+		recipe := internal.ValidateRecipe(args, cmd.Name())
+
+		if err := recipe.Ensure(internal.GetEnsureContext()); err != nil {
+			log.Fatal(err)
+		}
+
+		bumpType := btoi(internal.Major)*4 + btoi(internal.Minor)*2 + btoi(internal.Patch)
+		if bumpType != 0 {
+			// a bitwise check if the number is a power of 2
+			if (bumpType & (bumpType - 1)) != 0 {
+				log.Fatal("you can only use one of: --major, --minor, --patch.")
+			}
+		}
+
+		if internal.MachineReadable {
+			// -m implies -n in this case
+			internal.NoInput = true
+		}
+
+		upgradeList := make(map[string]anUpgrade)
+
+		// check for versions file and load pinned versions
+		versionsPresent := false
+		versionsPath := path.Join(recipe.Dir, "versions")
+		servicePins := make(map[string]imgPin)
+		if _, err := os.Stat(versionsPath); err == nil {
+			log.Debugf("found versions file for %s", recipe.Name)
+			file, err := os.Open(versionsPath)
+			if err != nil {
+				log.Fatal(err)
+			}
+			scanner := bufio.NewScanner(file)
+			for scanner.Scan() {
+				line := scanner.Text()
+				splitLine := strings.Split(line, " ")
+				if splitLine[0] != "pin" || len(splitLine) != 3 {
+					log.Fatalf("malformed version pin specification: %s", line)
+				}
+				pinSlice := strings.Split(splitLine[2], ":")
+				pinTag, err := tagcmp.Parse(pinSlice[1])
+				if err != nil {
+					log.Fatal(err)
+				}
+				pin := imgPin{
+					image:   pinSlice[0],
+					version: pinTag,
+				}
+				servicePins[splitLine[1]] = pin
+			}
+			if err := scanner.Err(); err != nil {
+				log.Error(err)
+			}
+			versionsPresent = true
+		} else {
+			log.Debugf("did not find versions file for %s", recipe.Name)
+		}
+
+		config, err := recipe.GetComposeConfig(nil)
+		if err != nil {
+			log.Fatal(err)
+		}
+
+		for _, service := range config.Services {
+			img, err := reference.ParseNormalizedNamed(service.Image)
+			if err != nil {
+				log.Fatal(err)
+			}
+
+			regVersions, err := client.GetRegistryTags(img)
+			if err != nil {
+				log.Fatal(err)
+			}
+
+			image := reference.Path(img)
+			log.Debugf("retrieved %s from remote registry for %s", regVersions, image)
+			image = formatter.StripTagMeta(image)
+
+			switch img.(type) {
+			case reference.NamedTagged:
+				if !tagcmp.IsParsable(img.(reference.NamedTagged).Tag()) {
+					log.Debugf("%s not considered semver-like", img.(reference.NamedTagged).Tag())
+				}
+			default:
+				log.Warnf("unable to read tag for image %s, is it missing? skipping upgrade for %s", image, service.Name)
+				continue
+			}
+
+			tag, err := tagcmp.Parse(img.(reference.NamedTagged).Tag())
+			if err != nil {
+				log.Warnf("unable to parse %s, error was: %s, skipping upgrade for %s", image, err.Error(), service.Name)
+				continue
+			}
+
+			log.Debugf("parsed %s for %s", tag, service.Name)
+
+			var compatible []tagcmp.Tag
+			for _, regVersion := range regVersions {
+				other, err := tagcmp.Parse(regVersion)
+				if err != nil {
+					continue // skip tags that cannot be parsed
+				}
+
+				if tag.IsCompatible(other) && tag.IsLessThan(other) && !tag.Equals(other) {
+					compatible = append(compatible, other)
+				}
+			}
+
+			log.Debugf("detected potential upgradable tags %s for %s", compatible, service.Name)
+
+			sort.Sort(tagcmp.ByTagDesc(compatible))
+
+			if len(compatible) == 0 && !allTags {
+				log.Info(fmt.Sprintf("no new versions available for %s, assuming %s is the latest (use -a/--all-tags to see all anyway)", image, tag))
+				continue // skip on to the next tag and don't update any compose files
+			}
+
+			catlVersions, err := recipePkg.VersionsOfService(recipe.Name, service.Name, internal.Offline)
+			if err != nil {
+				log.Fatal(err)
+			}
+
+			compatibleStrings := []string{"skip"}
+			for _, compat := range compatible {
+				skip := false
+				for _, catlVersion := range catlVersions {
+					if compat.String() == catlVersion {
+						skip = true
+					}
+				}
+				if !skip {
+					compatibleStrings = append(compatibleStrings, compat.String())
+				}
+			}
+
+			log.Debugf("detected compatible upgradable tags %s for %s", compatibleStrings, service.Name)
+
+			var upgradeTag string
+			_, ok := servicePins[service.Name]
+			if versionsPresent && ok {
+				pinnedTag := servicePins[service.Name].version
+				if tag.IsLessThan(pinnedTag) {
+					pinnedTagString := pinnedTag.String()
+					contains := false
+					for _, v := range compatible {
+						if pinnedTag.IsUpgradeCompatible(v) {
+							contains = true
+							upgradeTag = v.String()
+							break
+						}
+					}
+					if contains {
+						log.Infof("upgrading service %s from %s to %s (pinned tag: %s)", service.Name, tag.String(), upgradeTag, pinnedTagString)
+					} else {
+						log.Infof("service %s, image %s pinned to %s, no compatible upgrade found", service.Name, servicePins[service.Name].image, pinnedTagString)
+						continue
+					}
+				} else {
+					log.Fatalf("service %s is at version %s, but pinned to %s, please correct your compose.yml file manually!", service.Name, tag.String(), pinnedTag.String())
+					continue
+				}
+			} else {
+				if bumpType != 0 {
+					for _, upTag := range compatible {
+						upElement, err := tag.UpgradeDelta(upTag)
+						if err != nil {
+							return
+						}
+						delta := upElement.UpgradeType()
+						if delta <= bumpType {
+							upgradeTag = upTag.String()
+							break
+						}
+					}
+					if upgradeTag == "" {
+						log.Warnf("not upgrading from %s to %s for %s, because the upgrade type is more serious than what user wants", tag.String(), compatible[0].String(), image)
+						continue
+					}
+				} else {
+					msg := fmt.Sprintf("upgrade to which tag? (service: %s, image: %s, tag: %s)", service.Name, image, tag)
+					if !tagcmp.IsParsable(img.(reference.NamedTagged).Tag()) || allTags {
+						tag := img.(reference.NamedTagged).Tag()
+						if !allTags {
+							log.Warn(fmt.Sprintf("unable to determine versioning semantics of %s, listing all tags", tag))
+						}
+						msg = fmt.Sprintf("upgrade to which tag? (service: %s, tag: %s)", service.Name, tag)
+						compatibleStrings = []string{"skip"}
+						for _, regVersion := range regVersions {
+							compatibleStrings = append(compatibleStrings, regVersion)
+						}
+					}
+
+					// there is always at least the item "skip" in compatibleStrings (a list of
+					// possible upgradable tags) and at least one other tag.
+					upgradableTags := compatibleStrings[1:]
+					upgrade := anUpgrade{
+						Service:     service.Name,
+						Image:       image,
+						Tag:         tag.String(),
+						UpgradeTags: make([]string, len(upgradableTags)),
+					}
+
+					for n, s := range upgradableTags {
+						var sb strings.Builder
+						if _, err := sb.WriteString(s); err != nil {
+						}
+						upgrade.UpgradeTags[n] = sb.String()
+					}
+
+					upgradeList[upgrade.Service] = upgrade
+
+					if internal.NoInput {
+						upgradeTag = "skip"
+					} else {
+						prompt := &survey.Select{
+							Message: msg,
+							Help:    "enter / return to confirm, choose 'skip' to not upgrade this tag, vim mode is enabled",
+							VimMode: true,
+							Options: compatibleStrings,
+						}
+						if err := survey.AskOne(prompt, &upgradeTag); err != nil {
+							log.Fatal(err)
+						}
+					}
+				}
+			}
+			if upgradeTag != "skip" {
+				ok, err := recipe.UpdateTag(image, upgradeTag)
+				if err != nil {
+					log.Fatal(err)
+				}
+				if ok {
+					log.Infof("tag upgraded from %s to %s for %s", tag.String(), upgradeTag, image)
+				}
+			} else {
+				if !internal.NoInput {
+					log.Warnf("not upgrading %s, skipping as requested", image)
+				}
+			}
+		}
+
+		if internal.NoInput {
+			if internal.MachineReadable {
+				jsonstring, err := json.Marshal(upgradeList)
+				if err != nil {
+					log.Fatal(err)
+				}
+
+				fmt.Println(string(jsonstring))
+
+				return
+			}
+
+			for _, upgrade := range upgradeList {
+				log.Infof("can upgrade service: %s, image: %s, tag: %s ::", upgrade.Service, upgrade.Image, upgrade.Tag)
+				for _, utag := range upgrade.UpgradeTags {
+					log.Infof("    %s", utag)
+				}
+			}
+		}
+
+		isClean, err := gitPkg.IsClean(recipe.Dir)
+		if err != nil {
+			log.Fatal(err)
+		}
+		if !isClean {
+			log.Infof("%s currently has these unstaged changes 👇", recipe.Name)
+			if err := gitPkg.DiffUnstaged(recipe.Dir); err != nil {
+				log.Fatal(err)
+			}
+		}
+	},
+}
+
+var (
+	allTags bool
+)
+
+func init() {
+	RecipeUpgradeCommand.Flags().BoolVarP(
+		&internal.Major,
+		"major",
+		"x",
+		false,
+		"increase the major part of the version",
+	)
+
+	RecipeUpgradeCommand.Flags().BoolVarP(
+		&internal.Minor,
+		"minor",
+		"y",
+		false,
+		"increase the minor part of the version",
+	)
+
+	RecipeUpgradeCommand.Flags().BoolVarP(
+		&internal.Patch,
+		"patch",
+		"z",
+		false,
+		"increase the patch part of the version",
+	)
+
+	RecipeUpgradeCommand.Flags().BoolVarP(
+		&internal.MachineReadable,
+		"machine",
+		"m",
+		false,
+		"print machine-readable output",
+	)
+
+	RecipeUpgradeCommand.Flags().BoolVarP(
+		&allTags,
+		"all-tags",
+		"a",
+		false,
+		"list all tags, not just upgrades",
+	)
+}

cli/recipe/version.go

@@ -0,0 +1,135 @@
+package recipe
+
+import (
+	"fmt"
+	"sort"
+
+	"coopcloud.tech/abra/cli/internal"
+	"coopcloud.tech/abra/pkg/autocomplete"
+	"coopcloud.tech/abra/pkg/formatter"
+	"coopcloud.tech/abra/pkg/log"
+	recipePkg "coopcloud.tech/abra/pkg/recipe"
+	"github.com/spf13/cobra"
+)
+
+var RecipeVersionCommand = &cobra.Command{
+	Use:     "versions <recipe> [flags]",
+	Aliases: []string{"v"},
+	Short:   "List recipe versions",
+	Args:    cobra.ExactArgs(1),
+	ValidArgsFunction: func(
+		cmd *cobra.Command,
+		args []string,
+		toComplete string) ([]string, cobra.ShellCompDirective) {
+		return autocomplete.RecipeNameComplete()
+	},
+	Run: func(cmd *cobra.Command, args []string) {
+		var warnMessages []string
+
+		recipe := internal.ValidateRecipe(args, cmd.Name())
+
+		catl, err := recipePkg.ReadRecipeCatalogue(internal.Offline)
+		if err != nil {
+			log.Fatal(err)
+		}
+
+		recipeMeta, ok := catl[recipe.Name]
+		if !ok {
+			warnMessages = append(warnMessages, "retrieved versions from local recipe repository")
+
+			recipeVersions, warnMsg, err := recipe.GetRecipeVersions()
+			if err != nil {
+				warnMessages = append(warnMessages, err.Error())
+			}
+			if len(warnMsg) > 0 {
+				warnMessages = append(warnMessages, warnMsg...)
+			}
+
+			recipeMeta = recipePkg.RecipeMeta{Versions: recipeVersions}
+		}
+
+		if len(recipeMeta.Versions) == 0 {
+			log.Fatalf("%s has no published versions?", recipe.Name)
+		}
+
+		for i := len(recipeMeta.Versions) - 1; i >= 0; i-- {
+			table, err := formatter.CreateTable()
+			if err != nil {
+				log.Fatal(err)
+			}
+
+			table.Headers("SERVICE", "IMAGE", "TAG", "VERSION")
+
+			for version, meta := range recipeMeta.Versions[i] {
+				var allRows [][]string
+				var rows [][]string
+
+				for service, serviceMeta := range meta {
+					recipeVersion := version
+					if service != "app" {
+						recipeVersion = ""
+					}
+
+					rows = append(rows, []string{
+						service,
+						serviceMeta.Image,
+						serviceMeta.Tag,
+						recipeVersion,
+					})
+
+					allRows = append(allRows, []string{
+						version,
+						service,
+						serviceMeta.Image,
+						serviceMeta.Tag,
+						recipeVersion,
+					})
+				}
+
+				sort.Slice(rows, sortServiceByName(rows))
+
+				table.Rows(rows...)
+
+				if !internal.MachineReadable {
+					if err := formatter.PrintTable(table); err != nil {
+						log.Fatal(err)
+					}
+					continue
+				}
+
+				if internal.MachineReadable {
+					sort.Slice(allRows, sortServiceByName(allRows))
+					headers := []string{"VERSION", "SERVICE", "NAME", "TAG"}
+					out, err := formatter.ToJSON(headers, allRows)
+					if err != nil {
+						log.Fatal("unable to render to JSON: %s", err)
+					}
+					fmt.Println(out)
+					continue
+				}
+			}
+		}
+
+		if !internal.MachineReadable {
+			for _, warnMsg := range warnMessages {
+				log.Warn(warnMsg)
+			}
+		}
+	},
+}
+
+func sortServiceByName(versions [][]string) func(i, j int) bool {
+	return func(i, j int) bool {
+		return versions[i][0] < versions[j][0]
+	}
+}
+
+func init() {
+	RecipeVersionCommand.Flags().BoolVarP(
+		&internal.MachineReadable,
+		"machine",
+		"m",
+		false,
+		"print machine-readable output",
+	)
+}

cli/run.go

@@ -0,0 +1,219 @@
+package cli
+
+import (
+	"fmt"
+	"os"
+
+	"coopcloud.tech/abra/cli/app"
+	"coopcloud.tech/abra/cli/catalogue"
+	"coopcloud.tech/abra/cli/internal"
+	"coopcloud.tech/abra/cli/recipe"
+	"coopcloud.tech/abra/cli/server"
+	"coopcloud.tech/abra/pkg/config"
+	"coopcloud.tech/abra/pkg/log"
+	charmLog "github.com/charmbracelet/log"
+	"github.com/spf13/cobra"
+	"github.com/spf13/cobra/doc"
+)
+
+func Run(version, commit string) {
+	rootCmd := &cobra.Command{
+		Use:     "abra [cmd] [args] [flags]",
+		Short:   "The Co-op Cloud command-line utility belt 🎩🐇",
+		Version: fmt.Sprintf("%s-%s", version, commit[:7]),
+		ValidArgs: []string{
+			"app",
+			"autocomplete",
+			"catalogue",
+			"man",
+			"recipe",
+			"server",
+			"upgrade",
+		},
+		PersistentPreRun: func(cmd *cobra.Command, args []string) {
+			paths := []string{
+				config.ABRA_DIR,
+				config.SERVERS_DIR,
+				config.RECIPES_DIR,
+				config.LOGS_DIR,
+				config.VENDOR_DIR, // TODO(d1): remove > 0.9.x
+				config.BACKUP_DIR, // TODO(d1): remove > 0.9.x
+			}
+
+			for _, path := range paths {
+				if err := os.Mkdir(path, 0764); err != nil {
+					if !os.IsExist(err) {
+						log.Fatal(err)
+					}
+					continue
+				}
+			}
+
+			log.Logger.SetStyles(charmLog.DefaultStyles())
+			charmLog.SetDefault(log.Logger)
+
+			if internal.MachineReadable {
+				log.SetOutput(os.Stderr)
+			}
+
+			if internal.Debug {
+				log.SetLevel(log.DebugLevel)
+				log.SetOutput(os.Stderr)
+				log.SetReportCaller(true)
+			}
+
+			log.Debugf("abra version %s, commit %s", version, commit)
+		},
+	}
+
+	rootCmd.CompletionOptions.DisableDefaultCmd = true
+
+	manCommand := &cobra.Command{
+		Use:     "man [flags]",
+		Aliases: []string{"m"},
+		Short:   "Generate manpage",
+		Example: `  # generate the man pages into /usr/local/share/man/man1
+  sudo abra man
+  sudo mandb
+
+  # read the man pages
+  man abra
+  man abra-app-deploy`,
+		Run: func(cmd *cobra.Command, args []string) {
+			header := &doc.GenManHeader{
+				Title:   "ABRA",
+				Section: "1",
+			}
+
+			manDir := "/usr/local/share/man/man1"
+			if _, err := os.Stat(manDir); os.IsNotExist(err) {
+				log.Fatalf("unable to proceed, '%s' does not exist?")
+			}
+
+			err := doc.GenManTree(rootCmd, header, manDir)
+			if err != nil {
+				log.Fatal(err)
+			}
+
+			log.Info("don't forget to run 'sudo mandb'")
+		},
+	}
+
+	rootCmd.PersistentFlags().BoolVarP(
+		&internal.Debug,
+		"debug",
+		"d",
+		false,
+		"show debug messages",
+	)
+
+	rootCmd.PersistentFlags().BoolVarP(
+		&internal.NoInput,
+		"no-input",
+		"n",
+		false,
+		"toggle non-interactive mode",
+	)
+
+	rootCmd.PersistentFlags().BoolVarP(
+		&internal.Offline,
+		"offline",
+		"o",
+		false,
+		"prefer offline & filesystem access",
+	)
+
+	rootCmd.PersistentFlags().BoolVarP(
+		&internal.IgnoreEnvVersion,
+		"ignore-env-version",
+		"i",
+		false,
+		"ignore .env version checkout",
+	)
+
+	catalogue.CatalogueCommand.AddCommand(
+		catalogue.CatalogueGenerateCommand,
+	)
+
+	server.ServerCommand.AddCommand(
+		server.ServerAddCommand,
+		server.ServerListCommand,
+		server.ServerPruneCommand,
+		server.ServerRemoveCommand,
+	)
+
+	recipe.RecipeCommand.AddCommand(
+		recipe.RecipeDiffCommand,
+		recipe.RecipeFetchCommand,
+		recipe.RecipeLintCommand,
+		recipe.RecipeListCommand,
+		recipe.RecipeNewCommand,
+		recipe.RecipeReleaseCommand,
+		recipe.RecipeResetCommand,
+		recipe.RecipeSyncCommand,
+		recipe.RecipeUpgradeCommand,
+		recipe.RecipeVersionCommand,
+	)
+
+	rootCmd.AddCommand(
+		UpgradeCommand,
+		AutocompleteCommand,
+		manCommand,
+		app.AppCommand,
+		catalogue.CatalogueCommand,
+		server.ServerCommand,
+		recipe.RecipeCommand,
+	)
+
+	app.AppCmdCommand.AddCommand(
+		app.AppCmdListCommand,
+	)
+
+	app.AppSecretCommand.AddCommand(
+		app.AppSecretGenerateCommand,
+		app.AppSecretInsertCommand,
+		app.AppSecretRmCommand,
+		app.AppSecretLsCommand,
+	)
+
+	app.AppVolumeCommand.AddCommand(
+		app.AppVolumeListCommand,
+		app.AppVolumeRemoveCommand,
+	)
+
+	app.AppBackupCommand.AddCommand(
+		app.AppBackupListCommand,
+		app.AppBackupDownloadCommand,
+		app.AppBackupCreateCommand,
+		app.AppBackupSnapshotsCommand,
+	)
+
+	app.AppCommand.AddCommand(
+		app.AppBackupCommand,
+		app.AppCheckCommand,
+		app.AppCmdCommand,
+		app.AppConfigCommand,
+		app.AppCpCommand,
+		app.AppDeployCommand,
+		app.AppListCommand,
+		app.AppLogsCommand,
+		app.AppNewCommand,
+		app.AppPsCommand,
+		app.AppRemoveCommand,
+		app.AppRestartCommand,
+		app.AppRestoreCommand,
+		app.AppRollbackCommand,
+		app.AppRunCommand,
+		app.AppSecretCommand,
+		app.AppServicesCommand,
+		app.AppUndeployCommand,
+		app.AppUpgradeCommand,
+		app.AppVolumeCommand,
+		app.AppLabelsCommand,
+		app.AppEnvCommand,
+	)
+
+	if err := rootCmd.Execute(); err != nil {
+		os.Exit(1)
+	}
+}

cli/server/add.go

@@ -0,0 +1,203 @@
+package server
+
+import (
+	"os"
+	"path/filepath"
+
+	"coopcloud.tech/abra/cli/internal"
+	"coopcloud.tech/abra/pkg/autocomplete"
+	"coopcloud.tech/abra/pkg/client"
+	"coopcloud.tech/abra/pkg/config"
+	contextPkg "coopcloud.tech/abra/pkg/context"
+	"coopcloud.tech/abra/pkg/dns"
+	"coopcloud.tech/abra/pkg/log"
+	"coopcloud.tech/abra/pkg/server"
+	sshPkg "coopcloud.tech/abra/pkg/ssh"
+	"github.com/spf13/cobra"
+)
+
+var ServerAddCommand = &cobra.Command{
+	Use:     "add [[server] | --local] [flags]",
+	Aliases: []string{"a"},
+	Short:   "Add a new server",
+	Long: `Add a new server to your configuration so that it can be managed by Abra.
+
+Abra relies on the standard SSH command-line and ~/.ssh/config for client
+connection details. You must configure an entry per-host in your ~/.ssh/config
+for each server:
+
+  Host 1312.net 1312
+    Hostname 1312.net
+    User antifa
+    Port 12345
+    IdentityFile ~/.ssh/antifa@somewhere
+
+If "--local" is passed, then Abra assumes that the current local server is
+intended as the target server. This is useful when you want to have your entire
+Co-op Cloud config located on the server itself, and not on your local
+developer machine. The domain is then set to "default".`,
+	Example: "  abra server add 1312.net",
+	Args:    cobra.RangeArgs(0, 1),
+	ValidArgsFunction: func(
+		cmd *cobra.Command,
+		args []string,
+		toComplete string) ([]string, cobra.ShellCompDirective) {
+		if !local {
+			return autocomplete.ServerNameComplete()
+		}
+		return nil, cobra.ShellCompDirectiveDefault
+	},
+	Run: func(cmd *cobra.Command, args []string) {
+		if len(args) > 0 && local {
+			log.Fatal("cannot use [server] and --local together")
+		}
+
+		if len(args) == 0 && !local {
+			log.Fatal("missing argument or --local/-l flag")
+		}
+
+		name := "default"
+		if !local {
+			name = internal.ValidateDomain(args)
+		}
+
+		// NOTE(d1): reasonable 5 second timeout for connections which can't
+		// succeed. The connection is attempted twice, so this results in 10
+		// seconds.
+		timeout := client.WithTimeout(5)
+
+		if local {
+			created, err := createServerDir(name)
+			if err != nil {
+				log.Fatal(err)
+			}
+
+			log.Debugf("attempting to create client for %s", name)
+
+			if _, err := client.New(name, timeout); err != nil {
+				cleanUp(name)
+				log.Fatal(err)
+			}
+
+			if created {
+				log.Info("local server successfully added")
+			} else {
+				log.Warn("local server already exists")
+			}
+
+			return
+		}
+
+		_, err := createServerDir(name)
+		if err != nil {
+			log.Fatal(err)
+		}
+
+		created, err := newContext(name)
+		if err != nil {
+			cleanUp(name)
+			log.Fatalf("unable to create local context: %s", err)
+		}
+
+		log.Debugf("attempting to create client for %s", name)
+
+		if _, err := client.New(name, timeout); err != nil {
+			cleanUp(name)
+			log.Fatalf("ssh %s error: %s", name, sshPkg.Fatal(name, err))
+		}
+
+		if created {
+			log.Infof("%s successfully added", name)
+
+			if _, err := dns.EnsureIPv4(name); err != nil {
+				log.Warnf("unable to resolve IPv4 for %s", name)
+			}
+
+			return
+		}
+
+		log.Warnf("%s already exists", name)
+	},
+}
+
+// cleanUp cleans up the partially created context/client details for a failed
+// "server add" attempt.
+func cleanUp(name string) {
+	if name != "default" {
+		log.Debugf("serverAdd: cleanUp: cleaning up context for %s", name)
+		if err := client.DeleteContext(name); err != nil {
+			log.Fatal(err)
+		}
+	}
+
+	serverDir := filepath.Join(config.SERVERS_DIR, name)
+	files, err := config.GetAllFilesInDirectory(serverDir)
+	if err != nil {
+		log.Fatalf("serverAdd: cleanUp: unable to list files in %s: %s", serverDir, err)
+	}
+
+	if len(files) > 0 {
+		log.Debugf("serverAdd: cleanUp: %s is not empty, aborting cleanup", serverDir)
+		return
+	}
+
+	if err := os.RemoveAll(serverDir); err != nil {
+		log.Fatalf("serverAdd: cleanUp: failed to remove %s: %s", serverDir, err)
+	}
+}
+
+// newContext creates a new internal Docker context for a server. This is how
+// Docker manages SSH connection details. These are stored to disk in
+// ~/.docker. Abra can manage this completely for the user, so it's an
+// implementation detail.
+func newContext(name string) (bool, error) {
+	store := contextPkg.NewDefaultDockerContextStore()
+	contexts, err := store.Store.List()
+	if err != nil {
+		return false, err
+	}
+
+	for _, context := range contexts {
+		if context.Name == name {
+			log.Debugf("context for %s already exists", name)
+			return false, nil
+		}
+	}
+
+	log.Debugf("creating context with domain %s", name)
+
+	if err := client.CreateContext(name); err != nil {
+		return false, nil
+	}
+
+	return true, nil
+}
+
+// createServerDir creates the ~/.abra/servers/... directory for a new server.
+func createServerDir(name string) (bool, error) {
+	if err := server.CreateServerDir(name); err != nil {
+		if !os.IsExist(err) {
+			return false, err
+		}
+
+		log.Debugf("server dir for %s already created", name)
+
+		return false, nil
+	}
+
+	return true, nil
+}
+
+var (
+	local bool
+)
+
+func init() {
+	ServerAddCommand.Flags().BoolVarP(
+		&local,
+		"local",
+		"l",
+		false,
+		"use local server",
+	)
+}

cli/server/list.go

@@ -0,0 +1,103 @@
+package server
+
+import (
+	"fmt"
+	"strings"
+
+	"coopcloud.tech/abra/cli/internal"
+	"coopcloud.tech/abra/pkg/config"
+	contextPkg "coopcloud.tech/abra/pkg/context"
+	"coopcloud.tech/abra/pkg/formatter"
+	"coopcloud.tech/abra/pkg/log"
+	"github.com/docker/cli/cli/connhelper/ssh"
+	"github.com/spf13/cobra"
+)
+
+var ServerListCommand = &cobra.Command{
+	Use:     "list [flags]",
+	Aliases: []string{"ls"},
+	Short:   "List managed servers",
+	Args:    cobra.NoArgs,
+	Run: func(cmd *cobra.Command, args []string) {
+		dockerContextStore := contextPkg.NewDefaultDockerContextStore()
+		contexts, err := dockerContextStore.Store.List()
+		if err != nil {
+			log.Fatal(err)
+		}
+
+		table, err := formatter.CreateTable()
+		if err != nil {
+			log.Fatal(err)
+		}
+
+		headers := []string{"NAME", "HOST"}
+		table.Headers(headers...)
+
+		serverNames, err := config.ReadServerNames()
+		if err != nil {
+			log.Fatal(err)
+		}
+
+		var rows [][]string
+		for _, serverName := range serverNames {
+			var row []string
+			for _, dockerCtx := range contexts {
+				endpoint, err := contextPkg.GetContextEndpoint(dockerCtx)
+				if err != nil && strings.Contains(err.Error(), "does not exist") {
+					// No local context found, we can continue safely
+					continue
+				}
+
+				if dockerCtx.Name == serverName {
+					sp, err := ssh.ParseURL(endpoint)
+					if err != nil {
+						log.Fatal(err)
+					}
+
+					if sp.Host == "" {
+						sp.Host = "unknown"
+					}
+
+					row = []string{serverName, sp.Host}
+					rows = append(rows, row)
+				}
+			}
+
+			if len(row) == 0 {
+				if serverName == "default" {
+					row = []string{serverName, "local"}
+				} else {
+					row = []string{serverName, "unknown"}
+				}
+				rows = append(rows, row)
+			}
+
+			table.Row(row...)
+		}
+
+		if internal.MachineReadable {
+			out, err := formatter.ToJSON(headers, rows)
+			if err != nil {
+				log.Fatal("unable to render to JSON: %s", err)
+			}
+
+			fmt.Println(out)
+
+			return
+		}
+
+		if err := formatter.PrintTable(table); err != nil {
+			log.Fatal(err)
+		}
+	},
+}
+
+func init() {
+	ServerListCommand.Flags().BoolVarP(
+		&internal.MachineReadable,
+		"machine",
+		"m",
+		false,
+		"print machine-readable output",
+	)
+}

cli/server/prune.go

@@ -0,0 +1,102 @@
+package server
+
+import (
+	"coopcloud.tech/abra/cli/internal"
+	"coopcloud.tech/abra/pkg/autocomplete"
+	"coopcloud.tech/abra/pkg/client"
+	"coopcloud.tech/abra/pkg/formatter"
+	"coopcloud.tech/abra/pkg/log"
+	"github.com/docker/docker/api/types/filters"
+	"github.com/spf13/cobra"
+)
+
+var ServerPruneCommand = &cobra.Command{
+	Use:     "prune <server> [flags]",
+	Aliases: []string{"p"},
+	Short:   "Prune resources on a server",
+	Long: `Prunes unused containers, networks, and dangling images.
+
+Use "--volumes/-v" to remove volumes that are not associated with a deployed
+app. This can result in unwanted data loss if not used carefully.`,
+	Args: cobra.ExactArgs(1),
+	ValidArgsFunction: func(
+		cmd *cobra.Command,
+		args []string,
+		toComplete string) ([]string, cobra.ShellCompDirective) {
+		return autocomplete.ServerNameComplete()
+	},
+	Run: func(cmd *cobra.Command, args []string) {
+		serverName := internal.ValidateServer(args)
+
+		cl, err := client.New(serverName)
+		if err != nil {
+			log.Fatal(err)
+		}
+
+		var filterArgs filters.Args
+
+		cr, err := cl.ContainersPrune(cmd.Context(), filterArgs)
+		if err != nil {
+			log.Fatal(err)
+		}
+
+		cntSpaceReclaimed := formatter.ByteCountSI(cr.SpaceReclaimed)
+		log.Infof("containers pruned: %d; space reclaimed: %s", len(cr.ContainersDeleted), cntSpaceReclaimed)
+
+		nr, err := cl.NetworksPrune(cmd.Context(), filterArgs)
+		if err != nil {
+			log.Fatal(err)
+		}
+
+		log.Infof("networks pruned: %d", len(nr.NetworksDeleted))
+
+		pruneFilters := filters.NewArgs()
+		if allFilter {
+			log.Debugf("removing all images, not only dangling ones")
+			pruneFilters.Add("dangling", "false")
+		}
+
+		ir, err := cl.ImagesPrune(cmd.Context(), pruneFilters)
+		if err != nil {
+			log.Fatal(err)
+		}
+
+		imgSpaceReclaimed := formatter.ByteCountSI(ir.SpaceReclaimed)
+		log.Infof("images pruned: %d; space reclaimed: %s", len(ir.ImagesDeleted), imgSpaceReclaimed)
+
+		if volumesFilter {
+			vr, err := cl.VolumesPrune(cmd.Context(), filterArgs)
+			if err != nil {
+				log.Fatal(err)
+			}
+
+			volSpaceReclaimed := formatter.ByteCountSI(vr.SpaceReclaimed)
+			log.Infof("volumes pruned: %d; space reclaimed: %s", len(vr.VolumesDeleted), volSpaceReclaimed)
+		}
+
+		return
+	},
+}
+
+var (
+	allFilter     bool
+	volumesFilter bool
+)
+
+func init() {
+	ServerPruneCommand.Flags().BoolVarP(
+		&allFilter,
+		"all",
+		"a",
+		false,
+		"remove all unused images",
+	)
+
+	ServerPruneCommand.Flags().BoolVarP(
+		&volumesFilter,
+		"volumes",
+		"v",
+		false,
+		"remove volumes",
+	)
+}

cli/server/remove.go

@@ -0,0 +1,46 @@
+package server
+
+import (
+	"os"
+	"path/filepath"
+
+	"coopcloud.tech/abra/cli/internal"
+	"coopcloud.tech/abra/pkg/autocomplete"
+	"coopcloud.tech/abra/pkg/client"
+	"coopcloud.tech/abra/pkg/config"
+	"coopcloud.tech/abra/pkg/log"
+	"github.com/spf13/cobra"
+)
+
+var ServerRemoveCommand = &cobra.Command{
+	Use:     "remove <server> [flags]",
+	Aliases: []string{"rm"},
+	Short:   "Remove a managed server",
+	Long: `Remove a managed server.
+
+Abra will remove the internal bookkeeping ($ABRA_DIR/servers/...) and
+underlying client connection context. This server will then be lost in time,
+like tears in rain.`,
+	Args: cobra.ExactArgs(1),
+	ValidArgsFunction: func(
+		cmd *cobra.Command,
+		args []string,
+		toComplete string) ([]string, cobra.ShellCompDirective) {
+		return autocomplete.ServerNameComplete()
+	},
+	Run: func(cmd *cobra.Command, args []string) {
+		serverName := internal.ValidateServer(args)
+
+		if err := client.DeleteContext(serverName); err != nil {
+			log.Fatal(err)
+		}
+
+		if err := os.RemoveAll(filepath.Join(config.SERVERS_DIR, serverName)); err != nil {
+			log.Fatal(err)
+		}
+
+		log.Infof("%s is now lost in time, like tears in rain", serverName)
+
+		return
+	},
+}

cli/server/server.go

@@ -0,0 +1,10 @@
+package server
+
+import "github.com/spf13/cobra"
+
+// ServerCommand defines the `abra server` command and its subcommands
+var ServerCommand = &cobra.Command{
+	Use:     "server [cmd] [args] [flags]",
+	Aliases: []string{"s"},
+	Short:   "Manage servers",
+}

cli/updater/updater.go

@@ -0,0 +1,550 @@
+package updater
+
+import (
+	"context"
+	"fmt"
+	"os"
+	"strconv"
+	"strings"
+
+	"coopcloud.tech/abra/cli/internal"
+	appPkg "coopcloud.tech/abra/pkg/app"
+	"coopcloud.tech/abra/pkg/client"
+	"coopcloud.tech/abra/pkg/envfile"
+	"coopcloud.tech/abra/pkg/lint"
+	"coopcloud.tech/abra/pkg/recipe"
+	"coopcloud.tech/abra/pkg/upstream/convert"
+	"coopcloud.tech/abra/pkg/upstream/stack"
+	"coopcloud.tech/tagcmp"
+	charmLog "github.com/charmbracelet/log"
+	composetypes "github.com/docker/cli/cli/compose/types"
+	"github.com/docker/docker/api/types"
+	"github.com/docker/docker/api/types/filters"
+	dockerclient "github.com/docker/docker/client"
+	"github.com/spf13/cobra"
+
+	"coopcloud.tech/abra/pkg/log"
+)
+
+const SERVER = "localhost"
+
+// NotifyCommand checks for available upgrades.
+var NotifyCommand = &cobra.Command{
+	Use:     "notify [flags]",
+	Aliases: []string{"n"},
+	Short:   "Check for available upgrades",
+	Long: `Notify on new versions for deployed apps.
+
+If a new patch/minor version is available, a notification is printed.
+
+Use "--major/-m" to include new major versions.`,
+	Args: cobra.NoArgs,
+	Run: func(cmd *cobra.Command, args []string) {
+		cl, err := client.New("default")
+		if err != nil {
+			log.Fatal(err)
+		}
+
+		stacks, err := stack.GetStacks(cl)
+		if err != nil {
+			log.Fatal(err)
+		}
+
+		for _, stackInfo := range stacks {
+			stackName := stackInfo.Name
+			recipeName, err := getLabel(cl, stackName, "recipe")
+			if err != nil {
+				log.Fatal(err)
+			}
+
+			if recipeName != "" {
+				_, err = getLatestUpgrade(cl, stackName, recipeName)
+				if err != nil {
+					log.Fatal(err)
+				}
+			}
+		}
+	},
+}
+
+// UpgradeCommand upgrades apps.
+var UpgradeCommand = &cobra.Command{
+	Use:     "upgrade [[stack] [recipe] | --all] [flags]",
+	Aliases: []string{"u"},
+	Short:   "Upgrade apps",
+	Long: `Upgrade an app by specifying stack name and recipe. 
+
+Use "--all" to upgrade every deployed app.
+
+For each app with auto updates enabled, the deployed version is compared with
+the current recipe catalogue version. If a new patch/minor version is
+available, the app is upgraded.
+
+To include major versions use the "--major/-m" flag. You probably don't want
+that as it will break things. Only apps that are not deployed with "--chaos/-C"
+are upgraded, to update chaos deployments use the "--chaos/-C" flag. Use it
+with care.`,
+	Args: cobra.RangeArgs(0, 2),
+	// TODO(d1): complete stack/recipe
+	// ValidArgsFunction: func(
+	// 	cmd *cobra.Command,
+	// 	args []string,
+	// 	toComplete string) ([]string, cobra.ShellCompDirective) {
+	// },
+	Run: func(cmd *cobra.Command, args []string) {
+		cl, err := client.New("default")
+		if err != nil {
+			log.Fatal(err)
+		}
+
+		if !updateAll && len(args) != 2 {
+			log.Fatal("missing arguments or --all/-a flag")
+		}
+
+		if !updateAll {
+			stackName := args[0]
+			recipeName := args[1]
+
+			err = tryUpgrade(cl, stackName, recipeName)
+			if err != nil {
+				log.Fatal(err)
+			}
+
+			return
+		}
+
+		stacks, err := stack.GetStacks(cl)
+		if err != nil {
+			log.Fatal(err)
+		}
+
+		for _, stackInfo := range stacks {
+			stackName := stackInfo.Name
+			recipeName, err := getLabel(cl, stackName, "recipe")
+			if err != nil {
+				log.Fatal(err)
+			}
+
+			err = tryUpgrade(cl, stackName, recipeName)
+			if err != nil {
+				log.Fatal(err)
+			}
+		}
+	},
+}
+
+// getLabel reads docker labels from running services in the format of "coop-cloud.${STACK_NAME}.${LABEL}".
+func getLabel(cl *dockerclient.Client, stackName string, label string) (string, error) {
+	filter := filters.NewArgs()
+	filter.Add("label", fmt.Sprintf("%s=%s", convert.LabelNamespace, stackName))
+
+	services, err := cl.ServiceList(context.Background(), types.ServiceListOptions{Filters: filter})
+	if err != nil {
+		return "", err
+	}
+
+	for _, service := range services {
+		labelKey := fmt.Sprintf("coop-cloud.%s.%s", stackName, label)
+		if labelValue, ok := service.Spec.Labels[labelKey]; ok {
+			return labelValue, nil
+		}
+	}
+
+	log.Debugf("no %s label found for %s", label, stackName)
+
+	return "", nil
+}
+
+// getBoolLabel reads a boolean docker label from running services
+func getBoolLabel(cl *dockerclient.Client, stackName string, label string) (bool, error) {
+	lableValue, err := getLabel(cl, stackName, label)
+	if err != nil {
+		return false, err
+	}
+
+	if lableValue != "" {
+		value, err := strconv.ParseBool(lableValue)
+		if err != nil {
+			return false, err
+		}
+
+		return value, nil
+	}
+
+	log.Debugf("boolean label %s could not be found for %s, set default to false.", label, stackName)
+
+	return false, nil
+}
+
+// getEnv reads env variables from docker services.
+func getEnv(cl *dockerclient.Client, stackName string) (envfile.AppEnv, error) {
+	envMap := make(map[string]string)
+	filter := filters.NewArgs()
+	filter.Add("label", fmt.Sprintf("%s=%s", convert.LabelNamespace, stackName))
+
+	services, err := cl.ServiceList(context.Background(), types.ServiceListOptions{Filters: filter})
+	if err != nil {
+		return nil, err
+	}
+
+	for _, service := range services {
+		envList := service.Spec.TaskTemplate.ContainerSpec.Env
+		for _, envString := range envList {
+			splitString := strings.SplitN(envString, "=", 2)
+			if len(splitString) != 2 {
+				log.Debugf("can't separate key from value: %s (this variable is probably unset)", envString)
+				continue
+			}
+			k := splitString[0]
+			v := splitString[1]
+			log.Debugf("for %s read env %s with value: %s from docker service", stackName, k, v)
+			envMap[k] = v
+		}
+	}
+
+	return envMap, nil
+}
+
+// getLatestUpgrade returns the latest available version for an app respecting
+// the "--major" flag if it is newer than the currently deployed version.
+func getLatestUpgrade(cl *dockerclient.Client, stackName string, recipeName string) (string, error) {
+	deployedVersion, err := getDeployedVersion(cl, stackName, recipeName)
+	if err != nil {
+		return "", err
+	}
+
+	availableUpgrades, err := getAvailableUpgrades(cl, stackName, recipeName, deployedVersion)
+	if err != nil {
+		return "", err
+	}
+
+	if len(availableUpgrades) == 0 {
+		log.Debugf("no available upgrades for %s", stackName)
+		return "", nil
+	}
+
+	var chosenUpgrade string
+	if len(availableUpgrades) > 0 {
+		chosenUpgrade = availableUpgrades[len(availableUpgrades)-1]
+		log.Infof("%s (%s) can be upgraded from version %s to %s", stackName, recipeName, deployedVersion, chosenUpgrade)
+	}
+
+	return chosenUpgrade, nil
+}
+
+// getDeployedVersion returns the currently deployed version of an app.
+func getDeployedVersion(cl *dockerclient.Client, stackName string, recipeName string) (string, error) {
+	log.Debugf("retrieve deployed version whether %s is already deployed", stackName)
+
+	deployMeta, err := stack.IsDeployed(context.Background(), cl, stackName)
+	if err != nil {
+		return "", err
+	}
+
+	if !deployMeta.IsDeployed {
+		return "", fmt.Errorf("%s is not deployed?", stackName)
+	}
+
+	if deployMeta.Version == "unknown" {
+		return "", fmt.Errorf("failed to determine deployed version of %s", stackName)
+	}
+
+	return deployMeta.Version, nil
+}
+
+// getAvailableUpgrades returns all available versions of an app that are newer
+// than the deployed version. It only includes major upgrades if the "--major"
+// flag is set.
+func getAvailableUpgrades(cl *dockerclient.Client, stackName string, recipeName string,
+	deployedVersion string) ([]string, error) {
+	catl, err := recipe.ReadRecipeCatalogue(internal.Offline)
+	if err != nil {
+		return nil, err
+	}
+
+	versions, err := recipe.GetRecipeCatalogueVersions(recipeName, catl)
+	if err != nil {
+		return nil, err
+	}
+
+	if len(versions) == 0 {
+		log.Warnf("no published releases for %s in the recipe catalogue?", recipeName)
+		return nil, nil
+	}
+
+	var availableUpgrades []string
+	for _, version := range versions {
+		parsedDeployedVersion, err := tagcmp.Parse(deployedVersion)
+		if err != nil {
+			return nil, err
+		}
+
+		parsedVersion, err := tagcmp.Parse(version)
+		if err != nil {
+			return nil, err
+		}
+
+		versionDelta, err := parsedDeployedVersion.UpgradeDelta(parsedVersion)
+		if err != nil {
+			return nil, err
+		}
+
+		if 0 < versionDelta.UpgradeType() && (versionDelta.UpgradeType() < 4 || includeMajorUpdates) {
+			availableUpgrades = append(availableUpgrades, version)
+		}
+	}
+
+	log.Debugf("available updates for %s: %s", stackName, availableUpgrades)
+
+	return availableUpgrades, nil
+}
+
+// processRecipeRepoVersion clones, pulls, checks out the version and lints the
+// recipe repository.
+func processRecipeRepoVersion(r recipe.Recipe, version string) error {
+	if err := r.EnsureExists(); err != nil {
+		return err
+	}
+
+	if err := r.EnsureUpToDate(); err != nil {
+		return err
+	}
+
+	if _, err := r.EnsureVersion(version); err != nil {
+		return err
+	}
+
+	if err := lint.LintForErrors(r); err != nil {
+		return err
+	}
+
+	return nil
+}
+
+// mergeAbraShEnv merges abra.sh env vars into the app env vars.
+func mergeAbraShEnv(recipe recipe.Recipe, env envfile.AppEnv) error {
+	abraShEnv, err := envfile.ReadAbraShEnvVars(recipe.AbraShPath)
+	if err != nil {
+		return err
+	}
+
+	for k, v := range abraShEnv {
+		log.Debugf("read v:%s k: %s", v, k)
+		env[k] = v
+	}
+
+	return nil
+}
+
+// createDeployConfig merges and enriches the compose config for the deployment.
+func createDeployConfig(r recipe.Recipe, stackName string, env envfile.AppEnv) (*composetypes.Config, stack.Deploy, error) {
+	env["STACK_NAME"] = stackName
+
+	deployOpts := stack.Deploy{
+		Namespace:    stackName,
+		Prune:        false,
+		ResolveImage: stack.ResolveImageAlways,
+		Detach:       false,
+	}
+
+	composeFiles, err := r.GetComposeFiles(env)
+	if err != nil {
+		return nil, deployOpts, err
+	}
+
+	deployOpts.Composefiles = composeFiles
+	compose, err := appPkg.GetAppComposeConfig(stackName, deployOpts, env)
+	if err != nil {
+		return nil, deployOpts, err
+	}
+
+	appPkg.ExposeAllEnv(stackName, compose, env)
+
+	// after the upgrade the deployment won't be in chaos state anymore
+	appPkg.SetChaosLabel(compose, stackName, false)
+	appPkg.SetRecipeLabel(compose, stackName, r.Name)
+	appPkg.SetUpdateLabel(compose, stackName, env)
+
+	return compose, deployOpts, nil
+}
+
+// tryUpgrade performs the upgrade if all the requirements are fulfilled.
+func tryUpgrade(cl *dockerclient.Client, stackName, recipeName string) error {
+	if recipeName == "" {
+		log.Debugf("don't update %s due to missing recipe name", stackName)
+		return nil
+	}
+
+	chaos, err := getBoolLabel(cl, stackName, "chaos")
+	if err != nil {
+		return err
+	}
+
+	if chaos && !internal.Chaos {
+		log.Debugf("don't update %s due to chaos deployment", stackName)
+		return nil
+	}
+
+	updatesEnabled, err := getBoolLabel(cl, stackName, "autoupdate")
+	if err != nil {
+		return err
+	}
+
+	if !updatesEnabled {
+		log.Debugf("don't update %s due to disabled auto updates or missing ENABLE_AUTO_UPDATE env", stackName)
+		return nil
+	}
+
+	upgradeVersion, err := getLatestUpgrade(cl, stackName, recipeName)
+	if err != nil {
+		return err
+	}
+
+	if upgradeVersion == "" {
+		log.Debugf("don't update %s due to no new version", stackName)
+		return nil
+	}
+
+	err = upgrade(cl, stackName, recipeName, upgradeVersion)
+
+	return err
+}
+
+// upgrade performs all necessary steps to upgrade an app.
+func upgrade(cl *dockerclient.Client, stackName, recipeName, upgradeVersion string) error {
+	env, err := getEnv(cl, stackName)
+	if err != nil {
+		return err
+	}
+
+	app := appPkg.App{
+		Name:   stackName,
+		Recipe: recipe.Get(recipeName),
+		Server: SERVER,
+		Env:    env,
+	}
+
+	r := recipe.Get(recipeName)
+
+	if err = processRecipeRepoVersion(r, upgradeVersion); err != nil {
+		return err
+	}
+
+	if err = mergeAbraShEnv(app.Recipe, app.Env); err != nil {
+		return err
+	}
+
+	compose, deployOpts, err := createDeployConfig(r, stackName, app.Env)
+	if err != nil {
+		return err
+	}
+
+	log.Infof("upgrade %s (%s) to version %s", stackName, recipeName, upgradeVersion)
+
+	serviceNames, err := appPkg.GetAppServiceNames(app.Name)
+	if err != nil {
+		return err
+	}
+
+	f, err := app.Filters(true, false, serviceNames...)
+	if err != nil {
+		return err
+	}
+
+	err = stack.RunDeploy(
+		cl,
+		deployOpts,
+		compose,
+		stackName,
+		app.Server,
+		true,
+		f,
+	)
+
+	return err
+}
+
+func newKadabraApp(version, commit string) *cobra.Command {
+	rootCmd := &cobra.Command{
+		Use:     "kadabra [cmd] [flags]",
+		Version: fmt.Sprintf("%s-%s", version, commit[:7]),
+		Short:   "The Co-op Cloud auto-updater 🤖 🚀",
+		PersistentPreRun: func(cmd *cobra.Command, args []string) {
+			log.Logger.SetStyles(charmLog.DefaultStyles())
+			charmLog.SetDefault(log.Logger)
+
+			if internal.Debug {
+				log.SetLevel(log.DebugLevel)
+				log.SetOutput(os.Stderr)
+				log.SetReportCaller(true)
+			}
+
+			log.Debugf("kadabra version %s, commit %s", version, commit)
+		},
+	}
+
+	rootCmd.PersistentFlags().BoolVarP(
+		&internal.Debug, "debug", "d", false,
+		"show debug messages",
+	)
+
+	rootCmd.PersistentFlags().BoolVarP(
+		&internal.NoInput, "no-input", "n", false,
+		"toggle non-interactive mode",
+	)
+
+	rootCmd.AddCommand(
+		NotifyCommand,
+		UpgradeCommand,
+	)
+
+	return rootCmd
+}
+
+// RunApp runs CLI abra app.
+func RunApp(version, commit string) {
+	app := newKadabraApp(version, commit)
+
+	if err := app.Execute(); err != nil {
+		log.Fatal(err)
+	}
+}
+
+var (
+	includeMajorUpdates bool
+	updateAll           bool
+)
+
+func init() {
+	NotifyCommand.Flags().BoolVarP(
+		&includeMajorUpdates,
+		"major",
+		"m",
+		false,
+		"check for major updates",
+	)
+
+	UpgradeCommand.Flags().BoolVarP(
+		&internal.Chaos,
+		"chaos",
+		"C",
+		false,
+		"ignore uncommitted recipes changes",
+	)
+
+	UpgradeCommand.Flags().BoolVarP(
+		&includeMajorUpdates,
+		"major",
+		"m",
+		false,
+		"check for major updates",
+	)
+
+	UpgradeCommand.Flags().BoolVarP(
+		&updateAll,
+		"all",
+		"a",
+		false,
+		"update all deployed apps",
+	)
+}

cli/upgrade.go

@@ -0,0 +1,56 @@
+// Package cli provides the interface for the command-line.
+package cli
+
+import (
+	"fmt"
+	"os/exec"
+
+	"coopcloud.tech/abra/cli/internal"
+	"coopcloud.tech/abra/pkg/log"
+	"github.com/spf13/cobra"
+)
+
+// UpgradeCommand upgrades abra in-place.
+var UpgradeCommand = &cobra.Command{
+	Use:     "upgrade [flags]",
+	Aliases: []string{"u"},
+	Short:   "Upgrade abra",
+	Long: `Upgrade abra in-place with the latest stable or release candidate.
+
+By default, the latest stable release is downloaded.
+
+Use "--rc/-r" to install the latest release candidate. Please bear in mind that
+it may contain absolutely catastrophic deal-breaker bugs. Thank you very much
+for the testing efforts 💗`,
+	Example: "  abra upgrade --rc",
+	Args:    cobra.NoArgs,
+	Run: func(cmd *cobra.Command, args []string) {
+		mainURL := "https://install.abra.coopcloud.tech"
+		c := exec.Command("bash", "-c", fmt.Sprintf("wget -q -O- %s | bash", mainURL))
+
+		if releaseCandidate {
+			releaseCandidateURL := "https://git.coopcloud.tech/coop-cloud/abra/raw/branch/main/scripts/installer/installer"
+			c = exec.Command("bash", "-c", fmt.Sprintf("wget -q -O- %s | bash -s -- --rc", releaseCandidateURL))
+		}
+
+		log.Debugf("attempting to run %s", c)
+
+		if err := internal.RunCmd(c); err != nil {
+			log.Fatal(err)
+		}
+	},
+}
+
+var (
+	releaseCandidate bool
+)
+
+func init() {
+	UpgradeCommand.Flags().BoolVarP(
+		&releaseCandidate,
+		"rc",
+		"r",
+		false,
+		"install release candidate (may contain bugs)",
+	)
+}

cmd/abra/main.go

@@ -0,0 +1,23 @@
+// Package main provides the command-line entrypoint.
+package main
+
+import (
+	"coopcloud.tech/abra/cli"
+)
+
+// Version is the current version of Abra.
+var Version string
+
+// Commit is the current git commit of Abra.
+var Commit string
+
+func main() {
+	if Version == "" {
+		Version = "dev"
+	}
+	if Commit == "" {
+		Commit = "       "
+	}
+
+	cli.Run(Version, Commit)
+}

cmd/kadabra/main.go

@@ -0,0 +1,23 @@
+// Package main provides the command-line entrypoint.
+package main
+
+import (
+	"coopcloud.tech/abra/cli/updater"
+)
+
+// Version is the current version of Kadabra.
+var Version string
+
+// Commit is the current git commit of Kadabra.
+var Commit string
+
+func main() {
+	if Version == "" {
+		Version = "dev"
+	}
+	if Commit == "" {
+		Commit = "       "
+	}
+
+	updater.RunApp(Version, Commit)
+}

completion/_abra

@@ -1,52 +0,0 @@
-#compdef abra
-
-_abra () {
-	local context state line curcontext="$curcontext" ret=1
-	_arguments -n : \
-		{-h,--help}'[Help message]' \
-		'1:commands:(app server)' \
-		'*::arguments:->arguments' \
-		&& ret=0
-
-	case $state in
-		(arguments)
-			curcontext="${curcontext%:*:*}:abra-arguments-$words[1]:"
-			case $words[1] in
-				(app)
-					_arguments \
-						'1: :_abra_apps' \
-					&& ret=0
-				;;
-				(server)
-					_arguments \
-						'1:servers:_abra_servers' \
-					&& ret=0
-				;;
-			esac
-		;;
-	esac
-
-	return ret
-}
-
-_abra_servers() {
-	_path_files -/W $HOME/.abra/servers
-}
-
-_abra_apps()
-{
-	local newapps apps=($HOME/.abra/servers/*/*.env)
-	typeset -a apps
-	newapps=()
-	for app in $apps; do
-		newapps+=($(_abra_basename "${app}"))
-	done
-	_describe -t apps 'app' newapps
-}
-
-_abra_basename()
-{
-    printf -- "${1##*/}"
-}
-
-_abra "$@"

completion/abra.bash

@@ -1,117 +0,0 @@
-#!/usr/bin/env bash
-
-_abra_basename()
-{
-    echo "${1##*/}"
-}
-
-_abra_servers()
-{
-    # FIXME 3wc: copied from abra/get_servers()
-    shopt -s nullglob dotglob
-    local SERVERS=(~/.abra/servers/*)
-    shopt -u nullglob dotglob
-
-    for SERVER in "${SERVERS[@]}"; do
-        _abra_basename "${SERVER}"
-    done
-}
-
-_abra_complete_servers()
-{
-    mapfile -t COMPREPLY < <(compgen -W "$(_abra_servers)" -- "$1")
-}
-
-_abra_apps()
-{
-    shopt -s nullglob dotglob
-    local APPS=(~/.abra/servers/*/*.env)
-    shopt -u nullglob dotglob
-
-    for APP in "${APPS[@]}"; do
-        _abra_basename "${APP%.env}"
-    done
-}
-
-_abra_complete_apps()
-{
-    mapfile -t COMPREPLY < <(compgen -W "$(_abra_apps)" -- "$1")
-}
-
-_abra_complete()
-{
-    compopt +o default +o nospace
-    COMPREPLY=()
-
-    local -r cmds='
-        app
-        server
-    '
-    local -r short_opts='-e      -h     -s      -v'
-    local -r long_opts='--env --help --stack --version'
-
-    # Scan through the command line and find the abra command
-    # (if present), as well as its expected position.
-    local cmd
-    local cmd_index=1 # Expected index of the command token.
-    local i
-    for (( i = 1; i < ${#COMP_WORDS[@]}; i++ )); do
-        local word="${COMP_WORDS[i]}"
-        case "$word" in
-            -*)
-                ((cmd_index++))
-                ;;
-            *)
-                cmd="$word"
-                break
-                ;;
-        esac
-    done
-
-    local cur="${COMP_WORDS[COMP_CWORD]}"
-
-    if (( COMP_CWORD < cmd_index )); then
-        # Offer option completions.
-        case "$cur" in
-            --*)
-                mapfile -t COMPREPLY < <(compgen -W "$long_opts" -- "$cur")
-                ;;
-            -*)
-                mapfile -t COMPREPLY < <(compgen -W "$short_opts" -- "$cur")
-                ;;
-            *)
-                # Skip completion; we should never get here.
-                ;;
-        esac
-    elif (( COMP_CWORD == cmd_index )); then
-        # Offer command name completions.
-        mapfile -t COMPREPLY < <(compgen -W "$cmds" -- "$cur")
-    else
-        # Offer command argument completions.
-        case "$cmd" in
-            server)
-                # Offer exactly one server name completion.
-                if (( COMP_CWORD == cmd_index + 1 )); then
-                    _abra_complete_servers "$cur"
-                fi
-                ;;
-            app)
-                # Offer exactly one app completion.
-                if (( COMP_CWORD == cmd_index + 1 )); then
-                    _abra_complete_apps "$cur"
-                fi
-                ;;
-            #help)
-            #    # Offer exactly one command name completion.
-            #    if (( COMP_CWORD == cmd_index + 1 )); then
-            #        COMPREPLY=($(compgen -W "$cmds" -- "$cur"))
-            #    fi
-            #    ;;
-            *)
-                # Unknown command or unknowable argument.
-                ;;
-        esac
-    fi
-}
-
-complete -o default -F _abra_complete abra

deploy/apps.coopcloud.tech/compose.yml

@@ -1,41 +0,0 @@
----
-version: "3.8"
-
-services:
-  app:
-    image: "nginx:stable"
-    configs:
-      - source: abra_conf
-        target: /etc/nginx/conf.d/abra.conf
-      - source: abra_apps_json
-        target: /var/www/abra-apps/apps.json
-    volumes:
-      - "public:/var/www/abra-apps"
-    networks:
-      - proxy
-    deploy:
-      update_config:
-        failure_action: rollback
-        order: start-first
-      labels:
-        - "traefik.enable=true"
-        - "traefik.http.services.abra-apps.loadbalancer.server.port=80"
-        - "traefik.http.routers.abra-apps.rule=Host(`apps.coopcloud.tech`, `abra-apps.cloud.autonomic.zone`)"
-        - "traefik.http.routers.abra-apps.entrypoints=web-secure"
-        - "traefik.http.routers.abra-apps.tls.certresolver=production"
-        - "traefik.http.routers.abra-apps.middlewares=abra-apps-redirect"
-        - "traefik.http.middlewares.abra-apps-redirect.headers.SSLForceHost=true"
-        - "traefik.http.middlewares.abra-apps-redirect.headers.SSLHost=apps.coopcloud.tech"
-
-configs:
-  abra_apps_json:
-    file: apps.json
-  abra_conf:
-    file: nginx.conf
-
-networks:
-  proxy:
-    external: true
-
-volumes:
-  public:

deploy/apps.coopcloud.tech/nginx.conf

@@ -1,10 +0,0 @@
-server {
-  listen         80 default_server;
-  server_name    apps.coopcloud.tech;
-
-  location / {
-    root /var/www/abra-apps;
-    add_header Content-Type application/json;
-    index apps.json;
-  }
-}

deploy/install.abra.autonomic.zone/installer

@@ -1,35 +0,0 @@
-#!/bin/bash
-
-ABRA_VERSION="0.7.3"
-GIT_URL="https://git.autonomic.zone/coop-cloud/abra"
-ABRA_SRC="$GIT_URL/raw/tag/$ABRA_VERSION/abra"
-ABRA_DIR="${ABRA_DIR:-$HOME/.abra/}"
-
-function install_abra_release {
-  mkdir -p "$HOME/.local/bin"
-  curl "$ABRA_SRC" > "$HOME/.local/bin/abra"
-  chmod +x "$HOME/.local/bin/abra"
-  echo "abra installed to $HOME/.local/bin/abra"
-}
-
-function install_abra_dev {
-  mkdir -p "$ABRA_DIR/"
-  if [[ ! -d "$ABRA_DIR/src" ]]; then
-    git clone "$GIT_URL" "$ABRA_DIR/src"
-  fi
-  (cd "$ABRA_DIR/src" && git pull origin main && cd - || exit)
-  mkdir -p "$HOME/.local/bin"
-  ln -sf "$ABRA_DIR/src/abra" "$HOME/.local/bin/abra"
-  echo "abra installed to $HOME/.local/bin/abra (development bleeding edge)"
-}
-
-function run_installation {
-  if [ "$1" = "--dev" ]; then
-    install_abra_dev
-  else
-    install_abra_release
-  fi
-}
-
-run_installation "$@"
-exit 0

go.mod

@@ -0,0 +1,156 @@
+module coopcloud.tech/abra
+
+go 1.23.0
+
+toolchain go1.23.1
+
+require (
+	coopcloud.tech/tagcmp v0.0.0-20230809071031-eb3e7758d4eb
+	git.coopcloud.tech/toolshed/godotenv v1.5.2-0.20250103171850-4d0ca41daa5c
+	github.com/AlecAivazis/survey/v2 v2.3.7
+	github.com/charmbracelet/bubbletea v1.3.4
+	github.com/charmbracelet/lipgloss v1.1.0
+	github.com/charmbracelet/log v0.4.1
+	github.com/distribution/reference v0.6.0
+	github.com/docker/cli v28.0.1+incompatible
+	github.com/docker/docker v28.0.1+incompatible
+	github.com/docker/go-units v0.5.0
+	github.com/go-git/go-git/v5 v5.14.0
+	github.com/google/go-cmp v0.7.0
+	github.com/moby/sys/signal v0.7.1
+	github.com/moby/term v0.5.2
+	github.com/pkg/errors v0.9.1
+	github.com/schollz/progressbar/v3 v3.18.0
+	golang.org/x/term v0.30.0
+	gopkg.in/yaml.v3 v3.0.1
+	gotest.tools/v3 v3.5.2
+)
+
+require (
+	dario.cat/mergo v1.0.1 // indirect
+	github.com/AdaLogics/go-fuzz-headers v0.0.0-20230811130428-ced1acdcaa24 // indirect
+	github.com/Azure/go-ansiterm v0.0.0-20250102033503-faa5f7b0171c // indirect
+	github.com/BurntSushi/toml v1.4.0 // indirect
+	github.com/Microsoft/go-winio v0.6.2 // indirect
+	github.com/ProtonMail/go-crypto v1.1.6 // indirect
+	github.com/aymanbagabas/go-osc52/v2 v2.0.1 // indirect
+	github.com/beorn7/perks v1.0.1 // indirect
+	github.com/cenkalti/backoff/v4 v4.3.0 // indirect
+	github.com/cespare/xxhash/v2 v2.3.0 // indirect
+	github.com/charmbracelet/colorprofile v0.2.3-0.20250311203215-f60798e515dc // indirect
+	github.com/charmbracelet/x/ansi v0.8.0 // indirect
+	github.com/charmbracelet/x/cellbuf v0.0.13 // indirect
+	github.com/charmbracelet/x/term v0.2.1 // indirect
+	github.com/cloudflare/circl v1.6.0 // indirect
+	github.com/containerd/log v0.1.0 // indirect
+	github.com/cpuguy83/go-md2man/v2 v2.0.6 // indirect
+	github.com/cyphar/filepath-securejoin v0.4.1 // indirect
+	github.com/davecgh/go-spew v1.1.1 // indirect
+	github.com/docker/distribution v2.8.3+incompatible // indirect
+	github.com/docker/go v1.5.1-1.0.20160303222718-d30aec9fd63c // indirect
+	github.com/docker/go-connections v0.5.0 // indirect
+	github.com/docker/go-metrics v0.0.1 // indirect
+	github.com/docker/libtrust v0.0.0-20160708172513-aabc10ec26b7 // indirect
+	github.com/emirpasic/gods v1.18.1 // indirect
+	github.com/erikgeiser/coninput v0.0.0-20211004153227-1c3628e74d0f // indirect
+	github.com/felixge/httpsnoop v1.0.4 // indirect
+	github.com/fsnotify/fsnotify v1.6.0 // indirect
+	github.com/ghodss/yaml v1.0.0 // indirect
+	github.com/go-git/gcfg v1.5.1-0.20230307220236-3a3c6141e376 // indirect
+	github.com/go-git/go-billy/v5 v5.6.2 // indirect
+	github.com/go-logfmt/logfmt v0.6.0 // indirect
+	github.com/go-logr/logr v1.4.2 // indirect
+	github.com/go-logr/stdr v1.2.2 // indirect
+	github.com/go-viper/mapstructure/v2 v2.2.1 // indirect
+	github.com/gogo/protobuf v1.3.2 // indirect
+	github.com/golang/groupcache v0.0.0-20241129210726-2c02b8208cf8 // indirect
+	github.com/google/uuid v1.6.0 // indirect
+	github.com/grpc-ecosystem/grpc-gateway/v2 v2.26.3 // indirect
+	github.com/hashicorp/go-cleanhttp v0.5.2 // indirect
+	github.com/inconshreveable/mousetrap v1.1.0 // indirect
+	github.com/jbenet/go-context v0.0.0-20150711004518-d14ea06fba99 // indirect
+	github.com/kballard/go-shellquote v0.0.0-20180428030007-95032a82bc51 // indirect
+	github.com/kevinburke/ssh_config v1.2.0 // indirect
+	github.com/klauspost/compress v1.18.0 // indirect
+	github.com/lucasb-eyer/go-colorful v1.2.0 // indirect
+	github.com/mattn/go-colorable v0.1.14 // indirect
+	github.com/mattn/go-isatty v0.0.20 // indirect
+	github.com/mattn/go-localereader v0.0.1 // indirect
+	github.com/mattn/go-runewidth v0.0.16 // indirect
+	github.com/mgutz/ansi v0.0.0-20200706080929-d51e80ef957d // indirect
+	github.com/miekg/pkcs11 v1.1.1 // indirect
+	github.com/mitchellh/colorstring v0.0.0-20190213212951-d06e56a500db // indirect
+	github.com/mitchellh/mapstructure v1.5.0 // indirect
+	github.com/moby/docker-image-spec v1.3.1 // indirect
+	github.com/moby/sys/mountinfo v0.6.2 // indirect
+	github.com/moby/sys/user v0.3.0 // indirect
+	github.com/moby/sys/userns v0.1.0 // indirect
+	github.com/morikuni/aec v1.0.0 // indirect
+	github.com/muesli/ansi v0.0.0-20230316100256-276c6243b2f6 // indirect
+	github.com/muesli/cancelreader v0.2.2 // indirect
+	github.com/muesli/termenv v0.16.0 // indirect
+	github.com/munnerz/goautoneg v0.0.0-20191010083416-a7dc8b61c822 // indirect
+	github.com/opencontainers/go-digest v1.0.0 // indirect
+	github.com/opencontainers/runc v1.1.13 // indirect
+	github.com/opencontainers/runtime-spec v1.1.0 // indirect
+	github.com/pelletier/go-toml v1.9.5 // indirect
+	github.com/pjbgf/sha1cd v0.3.2 // indirect
+	github.com/pmezard/go-difflib v1.0.0 // indirect
+	github.com/prometheus/client_model v0.6.1 // indirect
+	github.com/prometheus/common v0.63.0 // indirect
+	github.com/prometheus/procfs v0.15.1 // indirect
+	github.com/rivo/uniseg v0.4.7 // indirect
+	github.com/russross/blackfriday/v2 v2.1.0 // indirect
+	github.com/sirupsen/logrus v1.9.3 // indirect
+	github.com/skeema/knownhosts v1.3.1 // indirect
+	github.com/spf13/pflag v1.0.6 // indirect
+	github.com/xanzy/ssh-agent v0.3.3 // indirect
+	github.com/xeipuuv/gojsonreference v0.0.0-20180127040603-bd5ef7bd5415 // indirect
+	github.com/xeipuuv/gojsonschema v1.2.0 // indirect
+	github.com/xo/terminfo v0.0.0-20220910002029-abceb7e1c41e // indirect
+	go.opentelemetry.io/auto/sdk v1.1.0 // indirect
+	go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp v0.60.0 // indirect
+	go.opentelemetry.io/otel v1.35.0 // indirect
+	go.opentelemetry.io/otel/exporters/otlp/otlpmetric/otlpmetricgrpc v1.35.0 // indirect
+	go.opentelemetry.io/otel/exporters/otlp/otlptrace v1.35.0 // indirect
+	go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracegrpc v1.35.0 // indirect
+	go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracehttp v1.19.0 // indirect
+	go.opentelemetry.io/otel/metric v1.35.0 // indirect
+	go.opentelemetry.io/otel/sdk v1.35.0 // indirect
+	go.opentelemetry.io/otel/sdk/metric v1.35.0 // indirect
+	go.opentelemetry.io/otel/trace v1.35.0 // indirect
+	go.opentelemetry.io/proto/otlp v1.5.0 // indirect
+	golang.org/x/crypto v0.36.0 // indirect
+	golang.org/x/exp v0.0.0-20250305212735-054e65f0b394 // indirect
+	golang.org/x/net v0.37.0 // indirect
+	golang.org/x/sync v0.12.0 // indirect
+	golang.org/x/text v0.23.0 // indirect
+	golang.org/x/time v0.11.0 // indirect
+	google.golang.org/genproto/googleapis/api v0.0.0-20250313205543-e70fdf4c4cb4 // indirect
+	google.golang.org/genproto/googleapis/rpc v0.0.0-20250313205543-e70fdf4c4cb4 // indirect
+	google.golang.org/grpc v1.71.0 // indirect
+	google.golang.org/protobuf v1.36.5 // indirect
+	gopkg.in/warnings.v0 v0.1.2 // indirect
+	gopkg.in/yaml.v2 v2.4.0 // indirect
+)
+
+require (
+	github.com/containers/image v3.0.2+incompatible
+	github.com/containers/storage v1.38.2 // indirect
+	github.com/decentral1se/passgen v1.0.1
+	github.com/docker/docker-credential-helpers v0.9.3 // indirect
+	github.com/fvbommel/sortorder v1.1.0 // indirect
+	github.com/google/shlex v0.0.0-20191202100458-e7afc7fbc510 // indirect
+	github.com/gorilla/mux v1.8.1 // indirect
+	github.com/hashicorp/go-retryablehttp v0.7.7
+	github.com/moby/patternmatcher v0.6.0 // indirect
+	github.com/moby/sys/sequential v0.6.0 // indirect
+	github.com/opencontainers/image-spec v1.1.1 // indirect
+	github.com/prometheus/client_golang v1.21.1 // indirect
+	github.com/sergi/go-diff v1.3.2-0.20230802210424-5b0b94c5c0d3 // indirect
+	github.com/spf13/cobra v1.9.1
+	github.com/stretchr/testify v1.10.0
+	github.com/theupdateframework/notary v0.7.0 // indirect
+	github.com/xeipuuv/gojsonpointer v0.0.0-20190905194746-02993c407bfb // indirect
+	golang.org/x/sys v0.31.0
+)

makefile

@@ -1,58 +0,0 @@
-.PHONY: test shellcheck docopt kcov codecov release-installer
-
-test:
-	@sudo DOCKER_CONTEXT=default docker run \
-		-v $$(pwd):/workdir \
-		--privileged \
-		-d \
-		--name=abra-test-dind \
-		-e DOCKER_TLS_CERTDIR="" \
-		decentral1se/docker-dind-bats-kcov
-	@DOCKER_CONTEXT=default docker exec \
-		-it \
-		abra-test-dind \
-		sh -c "cd /workdir && bats /workdir/tests"
-	@DOCKER_CONTEXT=default docker stop abra-test-dind
-	@DOCKER_CONTEXT=default docker rm abra-test-dind
-
-shellcheck:
-	@docker run \
-		-it \
-		--rm \
-		-v $$(pwd):/workdir \
-		koalaman/shellcheck-alpine \
-		shellcheck /workdir/abra && \
-		shellcheck /workdir/bin/*.sh
-
-docopt:
-	@if [ ! -d ".venv" ]; then \
-		python3 -m venv .venv && \
-		.venv/bin/pip install -U pip setuptools wheel && \
-		.venv/bin/pip install docopt-sh; \
-	fi
-	.venv/bin/docopt.sh abra
-
-kcov:
-	@docker run \
-		-it \
-		--rm \
-		-v $$(pwd):/workdir \
-		kcov/kcov:latest \
-		sh -c "kcov /workdir/coverage /workdir/abra || true"
-
-codecov: SHELL:=/bin/bash
-codecov:
-	@bash <(curl -s https://codecov.io/bash) \
-		-s coverage -t $$(pass show hosts/swarm.autonomic.zone/drone/codecov/token)
-
-release-installer:
-	@DOCKER_CONTEXT=swarm.autonomic.zone \
-		docker stack rm abra-installer-script && \
-		cd deploy/install.abra.autonomic.zone && \
-		DOCKER_CONTEXT=swarm.autonomic.zone docker stack deploy -c compose.yml abra-installer-script
-
-release-apps:
-	@DOCKER_CONTEXT=swarm.autonomic.zone \
-		docker stack rm abra-apps-json && \
-		cd deploy/apps.coopcloud.tech && \
-		DOCKER_CONTEXT=swarm.autonomic.zone docker stack deploy -c compose.yml abra-apps-json

pkg/app/app.go

@@ -0,0 +1,685 @@
+package app
+
+import (
+	"bufio"
+	"fmt"
+	"os"
+	"path"
+	"regexp"
+	"sort"
+	"strings"
+
+	"coopcloud.tech/abra/pkg/client"
+	"coopcloud.tech/abra/pkg/config"
+	"coopcloud.tech/abra/pkg/envfile"
+	"coopcloud.tech/abra/pkg/formatter"
+	"coopcloud.tech/abra/pkg/recipe"
+	"coopcloud.tech/abra/pkg/upstream/convert"
+	"coopcloud.tech/abra/pkg/upstream/stack"
+
+	"coopcloud.tech/abra/pkg/log"
+	loader "coopcloud.tech/abra/pkg/upstream/stack"
+	composetypes "github.com/docker/cli/cli/compose/types"
+	"github.com/docker/docker/api/types/filters"
+	"github.com/schollz/progressbar/v3"
+)
+
+// Get retrieves an app
+func Get(appName string) (App, error) {
+	files, err := LoadAppFiles("")
+	if err != nil {
+		return App{}, err
+	}
+
+	app, err := GetApp(files, appName)
+	if err != nil {
+		return App{}, err
+	}
+
+	log.Debugf("loaded app %s: %s", appName, app)
+
+	return app, nil
+}
+
+// GetApp loads an apps settings, reading it from file, in preparation to use
+// it. It should only be used when ready to use the env file to keep IO
+// operations down.
+func GetApp(apps AppFiles, name AppName) (App, error) {
+	appFile, exists := apps[name]
+	if !exists {
+		return App{}, fmt.Errorf("cannot find app with name %s", name)
+	}
+
+	app, err := ReadAppEnvFile(appFile, name)
+	if err != nil {
+		return App{}, err
+	}
+
+	return app, nil
+}
+
+// GetApps returns a slice of Apps with their env files read from a given
+// slice of AppFiles.
+func GetApps(appFiles AppFiles, recipeFilter string) ([]App, error) {
+	var apps []App
+
+	for name := range appFiles {
+		app, err := GetApp(appFiles, name)
+		if err != nil {
+			return nil, err
+		}
+
+		if recipeFilter != "" {
+			if app.Recipe.Name == recipeFilter {
+				apps = append(apps, app)
+			}
+		} else {
+			apps = append(apps, app)
+		}
+	}
+
+	return apps, nil
+}
+
+// App reprents an app with its env file read into memory
+type App struct {
+	Name   AppName
+	Recipe recipe.Recipe
+	Domain string
+	Env    envfile.AppEnv
+	Server string
+	Path   string
+}
+
+// String outputs a human-friendly string representation.
+func (a App) String() string {
+	out := fmt.Sprintf("{name: %s, ", a.Name)
+	out += fmt.Sprintf("recipe: %s, ", a.Recipe)
+	out += fmt.Sprintf("domain: %s, ", a.Domain)
+	out += fmt.Sprintf("env %s, ", a.Env)
+	out += fmt.Sprintf("server %s, ", a.Server)
+	out += fmt.Sprintf("path %s}", a.Path)
+	return out
+}
+
+// Type aliases to make code hints easier to understand
+
+// AppName is AppName
+type AppName = string
+
+// AppFile represents app env files on disk without reading the contents
+type AppFile struct {
+	Path   string
+	Server string
+}
+
+// AppFiles is a slice of appfiles
+type AppFiles map[AppName]AppFile
+
+// See documentation of config.StackName
+func (a App) StackName() string {
+	if _, exists := a.Env["STACK_NAME"]; exists {
+		return a.Env["STACK_NAME"]
+	}
+
+	stackName := StackName(a.Name)
+
+	a.Env["STACK_NAME"] = stackName
+
+	return stackName
+}
+
+// StackName gets whatever the docker safe (uses the right delimiting
+// character, e.g. "_") stack name is for the app. In general, you don't want
+// to use this to show anything to end-users, you want use a.Name instead.
+func StackName(appName string) string {
+	stackName := SanitiseAppName(appName)
+
+	if len(stackName) > config.MAX_SANITISED_APP_NAME_LENGTH {
+		log.Debugf("trimming %s to %s to avoid runtime limits", stackName, stackName[:config.MAX_SANITISED_APP_NAME_LENGTH])
+		stackName = stackName[:config.MAX_SANITISED_APP_NAME_LENGTH]
+	}
+
+	return stackName
+}
+
+// Filters retrieves app filters for querying the container runtime. By default
+// it filters on all services in the app. It is also possible to pass an
+// otional list of service names, which get filtered instead.
+//
+// Due to upstream issues, filtering works different depending on what you're
+// querying. So, for example, secrets don't work with regex! The caller needs
+// to implement their own validation that the right secrets are matched. In
+// order to handle these cases, we provide the `appendServiceNames` /
+// `exactMatch` modifiers.
+func (a App) Filters(appendServiceNames, exactMatch bool, services ...string) (filters.Args, error) {
+	filters := filters.NewArgs()
+	if len(services) > 0 {
+		for _, serviceName := range services {
+			filters.Add("name", ServiceFilter(a.StackName(), serviceName, exactMatch))
+		}
+		return filters, nil
+	}
+
+	// When not appending the service name, just add one filter for the whole
+	// stack.
+	if !appendServiceNames {
+		f := fmt.Sprintf("%s", a.StackName())
+		if exactMatch {
+			f = fmt.Sprintf("^%s", f)
+		}
+		filters.Add("name", f)
+		return filters, nil
+	}
+
+	composeFiles, err := a.Recipe.GetComposeFiles(a.Env)
+	if err != nil {
+		return filters, err
+	}
+
+	opts := stack.Deploy{Composefiles: composeFiles}
+	compose, err := GetAppComposeConfig(a.Recipe.Name, opts, a.Env)
+	if err != nil {
+		return filters, err
+	}
+
+	for _, service := range compose.Services {
+		f := ServiceFilter(a.StackName(), service.Name, exactMatch)
+		filters.Add("name", f)
+	}
+
+	return filters, nil
+}
+
+// ServiceFilter creates a filter string for filtering a service in the docker
+// container runtime. When exact match is true, it uses regex to match the
+// string exactly.
+func ServiceFilter(stack, service string, exact bool) string {
+	if exact {
+		return fmt.Sprintf("^%s_%s", stack, service)
+	}
+	return fmt.Sprintf("%s_%s", stack, service)
+}
+
+// ByServer sort a slice of Apps
+type ByServer []App
+
+func (a ByServer) Len() int      { return len(a) }
+func (a ByServer) Swap(i, j int) { a[i], a[j] = a[j], a[i] }
+func (a ByServer) Less(i, j int) bool {
+	return strings.ToLower(a[i].Server) < strings.ToLower(a[j].Server)
+}
+
+// ByServerAndRecipe sort a slice of Apps
+type ByServerAndRecipe []App
+
+func (a ByServerAndRecipe) Len() int      { return len(a) }
+func (a ByServerAndRecipe) Swap(i, j int) { a[i], a[j] = a[j], a[i] }
+func (a ByServerAndRecipe) Less(i, j int) bool {
+	if a[i].Server == a[j].Server {
+		return strings.ToLower(a[i].Recipe.Name) < strings.ToLower(a[j].Recipe.Name)
+	}
+	return strings.ToLower(a[i].Server) < strings.ToLower(a[j].Server)
+}
+
+// ByRecipe sort a slice of Apps
+type ByRecipe []App
+
+func (a ByRecipe) Len() int      { return len(a) }
+func (a ByRecipe) Swap(i, j int) { a[i], a[j] = a[j], a[i] }
+func (a ByRecipe) Less(i, j int) bool {
+	return strings.ToLower(a[i].Recipe.Name) < strings.ToLower(a[j].Recipe.Name)
+}
+
+// ByName sort a slice of Apps
+type ByName []App
+
+func (a ByName) Len() int      { return len(a) }
+func (a ByName) Swap(i, j int) { a[i], a[j] = a[j], a[i] }
+func (a ByName) Less(i, j int) bool {
+	return strings.ToLower(a[i].Name) < strings.ToLower(a[j].Name)
+}
+
+func ReadAppEnvFile(appFile AppFile, name AppName) (App, error) {
+	env, err := envfile.ReadEnv(appFile.Path)
+	if err != nil {
+		return App{}, fmt.Errorf("env file for %s couldn't be read: %s", name, err.Error())
+	}
+
+	app, err := NewApp(env, name, appFile)
+	if err != nil {
+		return App{}, fmt.Errorf("env file for %s has issues: %s", name, err.Error())
+	}
+
+	return app, nil
+}
+
+// NewApp creates new App object
+func NewApp(env envfile.AppEnv, name string, appFile AppFile) (App, error) {
+	domain := env["DOMAIN"]
+
+	recipeName, exists := env["RECIPE"]
+	if !exists {
+		recipeName, exists = env["TYPE"]
+		if !exists {
+			return App{}, fmt.Errorf("%s is missing the TYPE env var?", name)
+		}
+	}
+
+	return App{
+		Name:   name,
+		Domain: domain,
+		Recipe: recipe.Get(recipeName),
+		Env:    env,
+		Server: appFile.Server,
+		Path:   appFile.Path,
+	}, nil
+}
+
+// LoadAppFiles gets all app files for a given set of servers or all servers.
+func LoadAppFiles(servers ...string) (AppFiles, error) {
+	appFiles := make(AppFiles)
+	if len(servers) == 1 {
+		if servers[0] == "" {
+			// Empty servers flag, one string will always be passed
+			var err error
+			servers, err = config.GetAllFoldersInDirectory(config.SERVERS_DIR)
+			if err != nil {
+				return appFiles, err
+			}
+		}
+	}
+
+	log.Debugf("collecting metadata from %v servers: %s", len(servers), strings.Join(servers, ", "))
+
+	for _, server := range servers {
+		serverDir := path.Join(config.SERVERS_DIR, server)
+		files, err := config.GetAllFilesInDirectory(serverDir)
+		if err != nil {
+			return appFiles, fmt.Errorf("server %s doesn't exist? Run \"abra server ls\" to check", server)
+		}
+
+		for _, file := range files {
+			appName := strings.TrimSuffix(file.Name(), ".env")
+			appFilePath := path.Join(config.SERVERS_DIR, server, file.Name())
+			appFiles[appName] = AppFile{
+				Path:   appFilePath,
+				Server: server,
+			}
+		}
+	}
+
+	return appFiles, nil
+}
+
+// GetAppServiceNames retrieves a list of app service names.
+func GetAppServiceNames(appName string) ([]string, error) {
+	var serviceNames []string
+
+	appFiles, err := LoadAppFiles("")
+	if err != nil {
+		return serviceNames, err
+	}
+
+	app, err := GetApp(appFiles, appName)
+	if err != nil {
+		return serviceNames, err
+	}
+
+	composeFiles, err := app.Recipe.GetComposeFiles(app.Env)
+	if err != nil {
+		return serviceNames, err
+	}
+
+	opts := stack.Deploy{Composefiles: composeFiles}
+	compose, err := GetAppComposeConfig(app.Recipe.Name, opts, app.Env)
+	if err != nil {
+		return serviceNames, err
+	}
+
+	for _, service := range compose.Services {
+		serviceNames = append(serviceNames, service.Name)
+	}
+
+	return serviceNames, nil
+}
+
+// GetAppNames retrieves a list of app names.
+func GetAppNames() ([]string, error) {
+	var appNames []string
+
+	appFiles, err := LoadAppFiles("")
+	if err != nil {
+		return appNames, err
+	}
+
+	apps, err := GetApps(appFiles, "")
+	if err != nil {
+		return appNames, err
+	}
+
+	for _, app := range apps {
+		appNames = append(appNames, app.Name)
+	}
+
+	return appNames, nil
+}
+
+// TemplateAppEnvSample copies the example env file for the app into the users
+// env files.
+func TemplateAppEnvSample(r recipe.Recipe, appName, server, domain string) error {
+	envSample, err := os.ReadFile(r.SampleEnvPath)
+	if err != nil {
+		return err
+	}
+
+	appEnvPath := path.Join(config.ABRA_DIR, "servers", server, fmt.Sprintf("%s.env", appName))
+	if _, err := os.Stat(appEnvPath); !os.IsNotExist(err) {
+		return fmt.Errorf("%s already exists?", appEnvPath)
+	}
+
+	err = os.WriteFile(appEnvPath, envSample, 0o664)
+	if err != nil {
+		return err
+	}
+
+	read, err := os.ReadFile(appEnvPath)
+	if err != nil {
+		return err
+	}
+
+	newContents := strings.Replace(string(read), r.Name+".example.com", domain, -1)
+
+	err = os.WriteFile(appEnvPath, []byte(newContents), 0)
+	if err != nil {
+		return err
+	}
+
+	log.Debugf("copied & templated %s to %s", r.SampleEnvPath, appEnvPath)
+
+	return nil
+}
+
+// SanitiseAppName makes a app name usable with Docker by replacing illegal
+// characters.
+func SanitiseAppName(name string) string {
+	return strings.ReplaceAll(name, ".", "_")
+}
+
+// GetAppStatuses queries servers to check the deployment status of given apps.
+func GetAppStatuses(apps []App, MachineReadable bool) (map[string]map[string]string, error) {
+	statuses := make(map[string]map[string]string)
+
+	servers := make(map[string]struct{})
+	for _, app := range apps {
+		if _, ok := servers[app.Server]; !ok {
+			servers[app.Server] = struct{}{}
+		}
+	}
+
+	var bar *progressbar.ProgressBar
+	if !MachineReadable {
+		bar = formatter.CreateProgressbar(len(servers), "querying remote servers...")
+	}
+
+	ch := make(chan stack.StackStatus, len(servers))
+	for server := range servers {
+		cl, err := client.New(server)
+		if err != nil {
+			return statuses, err
+		}
+
+		go func(s string) {
+			ch <- stack.GetAllDeployedServices(cl, s)
+			if !MachineReadable {
+				bar.Add(1)
+			}
+		}(server)
+	}
+
+	for range servers {
+		status := <-ch
+		if status.Err != nil {
+			return statuses, status.Err
+		}
+
+		for _, service := range status.Services {
+			result := make(map[string]string)
+			name := service.Spec.Labels[convert.LabelNamespace]
+
+			if _, ok := statuses[name]; !ok {
+				result["status"] = "deployed"
+			}
+
+			labelKey := fmt.Sprintf("coop-cloud.%s.chaos", name)
+			chaos, ok := service.Spec.Labels[labelKey]
+			if ok {
+				result["chaos"] = chaos
+			}
+
+			labelKey = fmt.Sprintf("coop-cloud.%s.chaos-version", name)
+			if chaosVersion, ok := service.Spec.Labels[labelKey]; ok {
+				result["chaosVersion"] = chaosVersion
+			}
+
+			labelKey = fmt.Sprintf("coop-cloud.%s.autoupdate", name)
+			if autoUpdate, ok := service.Spec.Labels[labelKey]; ok {
+				result["autoUpdate"] = autoUpdate
+			} else {
+				result["autoUpdate"] = "false"
+			}
+
+			labelKey = fmt.Sprintf("coop-cloud.%s.version", name)
+			if version, ok := service.Spec.Labels[labelKey]; ok {
+				result["version"] = version
+			} else {
+				continue
+			}
+
+			statuses[name] = result
+		}
+	}
+
+	log.Debugf("retrieved app statuses: %s", statuses)
+
+	return statuses, nil
+}
+
+// GetAppComposeConfig retrieves a compose specification for a recipe. This
+// specification is the result of a merge of all the compose.**.yml files in
+// the recipe repository.
+func GetAppComposeConfig(recipe string, opts stack.Deploy, appEnv envfile.AppEnv) (*composetypes.Config, error) {
+	compose, err := loader.LoadComposefile(opts, appEnv)
+	if err != nil {
+		return &composetypes.Config{}, err
+	}
+
+	log.Debugf("retrieved %s for %s", compose.Filename, recipe)
+
+	return compose, nil
+}
+
+// ExposeAllEnv exposes all env variables to the app container
+func ExposeAllEnv(stackName string, compose *composetypes.Config, appEnv envfile.AppEnv) {
+	for _, service := range compose.Services {
+		if service.Name == "app" {
+			log.Debugf("adding env vars to %s service config", stackName)
+			for k, v := range appEnv {
+				_, exists := service.Environment[k]
+				if !exists {
+					value := v
+					service.Environment[k] = &value
+					log.Debugf("%s: %s: %s", stackName, k, value)
+				}
+			}
+		}
+	}
+}
+
+func CheckEnv(app App) ([]envfile.EnvVar, error) {
+	var envVars []envfile.EnvVar
+
+	envSample, err := app.Recipe.SampleEnv()
+	if err != nil {
+		return envVars, err
+	}
+
+	var keys []string
+	for key := range envSample {
+		keys = append(keys, key)
+	}
+
+	sort.Strings(keys)
+
+	for _, key := range keys {
+		if _, ok := app.Env[key]; ok {
+			envVars = append(envVars, envfile.EnvVar{Name: key, Present: true})
+		} else {
+			envVars = append(envVars, envfile.EnvVar{Name: key, Present: false})
+		}
+	}
+
+	return envVars, nil
+}
+
+// ReadAbraShCmdNames reads the names of commands.
+func ReadAbraShCmdNames(abraSh string) ([]string, error) {
+	var cmdNames []string
+
+	file, err := os.Open(abraSh)
+	if err != nil {
+		if os.IsNotExist(err) {
+			return cmdNames, nil
+		}
+		return cmdNames, err
+	}
+	defer file.Close()
+
+	cmdNameRegex, err := regexp.Compile(`(\w+)(\(\).*\{)`)
+	if err != nil {
+		return cmdNames, err
+	}
+
+	scanner := bufio.NewScanner(file)
+	for scanner.Scan() {
+		line := scanner.Text()
+		matches := cmdNameRegex.FindStringSubmatch(line)
+		if len(matches) > 0 {
+			cmdNames = append(cmdNames, matches[1])
+		}
+	}
+
+	if len(cmdNames) > 0 {
+		log.Debugf("read %s from %s", strings.Join(cmdNames, " "), abraSh)
+	} else {
+		log.Debugf("read 0 command names from %s", abraSh)
+	}
+
+	return cmdNames, nil
+}
+
+// Wipe removes the version from the app .env file.
+func (a App) WipeRecipeVersion() error {
+	file, err := os.Open(a.Path)
+	if err != nil {
+		return err
+	}
+	defer file.Close()
+
+	var (
+		lines   []string
+		scanner = bufio.NewScanner(file)
+	)
+
+	for scanner.Scan() {
+		line := scanner.Text()
+		if !strings.HasPrefix(line, "RECIPE=") && !strings.HasPrefix(line, "TYPE=") {
+			lines = append(lines, line)
+			continue
+		}
+
+		if strings.HasPrefix(line, "#") {
+			lines = append(lines, line)
+			continue
+		}
+
+		splitted := strings.Split(line, ":")
+		lines = append(lines, splitted[0])
+	}
+
+	if err := scanner.Err(); err != nil {
+		log.Fatal(err)
+	}
+
+	if err := os.WriteFile(a.Path, []byte(strings.Join(lines, "\n")), os.ModePerm); err != nil {
+		log.Fatal(err)
+	}
+
+	log.Debugf("version wiped from %s.env", a.Domain)
+
+	return nil
+}
+
+// WriteRecipeVersion writes the recipe version to the app .env file.
+func (a App) WriteRecipeVersion(version string, dryRun bool) error {
+	file, err := os.Open(a.Path)
+	if err != nil {
+		return err
+	}
+	defer file.Close()
+
+	var (
+		dirtyVersion string
+		skipped      bool
+		lines        []string
+		scanner      = bufio.NewScanner(file)
+	)
+
+	for scanner.Scan() {
+		line := scanner.Text()
+		if !strings.HasPrefix(line, "RECIPE=") && !strings.HasPrefix(line, "TYPE=") {
+			lines = append(lines, line)
+			continue
+		}
+
+		if strings.HasPrefix(line, "#") {
+			lines = append(lines, line)
+			continue
+		}
+
+		if strings.Contains(line, version) && !a.Recipe.Dirty && !strings.HasSuffix(line, config.DIRTY_DEFAULT) {
+			skipped = true
+			lines = append(lines, line)
+			continue
+		}
+
+		splitted := strings.Split(line, ":")
+
+		line = fmt.Sprintf("%s:%s", splitted[0], version)
+		lines = append(lines, line)
+	}
+
+	if err := scanner.Err(); err != nil {
+		log.Fatal(err)
+	}
+
+	if a.Recipe.Dirty && dirtyVersion != "" {
+		version = dirtyVersion
+	}
+
+	if !dryRun {
+		if err := os.WriteFile(a.Path, []byte(strings.Join(lines, "\n")), os.ModePerm); err != nil {
+			log.Fatal(err)
+		}
+	} else {
+		log.Debugf("skipping writing version %s because dry run", version)
+	}
+
+	if !skipped {
+		log.Debugf("version %s saved to %s.env", version, a.Domain)
+	} else {
+		log.Debugf("skipping version %s write as already exists in %s.env", version, a.Domain)
+	}
+
+	return nil
+}

pkg/app/app_test.go

@@ -0,0 +1,226 @@
+package app_test
+
+import (
+	"encoding/json"
+	"fmt"
+	"reflect"
+	"testing"
+
+	appPkg "coopcloud.tech/abra/pkg/app"
+	"coopcloud.tech/abra/pkg/config"
+	"coopcloud.tech/abra/pkg/envfile"
+	"coopcloud.tech/abra/pkg/recipe"
+	testPkg "coopcloud.tech/abra/pkg/test"
+	"github.com/docker/docker/api/types/filters"
+	"github.com/google/go-cmp/cmp"
+	"github.com/stretchr/testify/assert"
+)
+
+func TestNewApp(t *testing.T) {
+	app, err := appPkg.NewApp(testPkg.ExpectedAppEnv, testPkg.AppName, testPkg.ExpectedAppFile)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !reflect.DeepEqual(app, testPkg.ExpectedApp) {
+		t.Fatalf("did not get expected app type. Expected: %s; Got: %s", app, testPkg.ExpectedApp)
+	}
+}
+
+func TestReadAppEnvFile(t *testing.T) {
+	app, err := appPkg.ReadAppEnvFile(testPkg.ExpectedAppFile, testPkg.AppName)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !reflect.DeepEqual(app, testPkg.ExpectedApp) {
+		t.Fatalf("did not get expected app type. Expected: %s; Got: %s", app, testPkg.ExpectedApp)
+	}
+}
+
+func TestGetApp(t *testing.T) {
+	app, err := appPkg.GetApp(testPkg.ExpectedAppFiles, testPkg.AppName)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !reflect.DeepEqual(app, testPkg.ExpectedApp) {
+		t.Fatalf("did not get expected app type. Expected: %s; Got: %s", app, testPkg.ExpectedApp)
+	}
+}
+
+func TestGetComposeFiles(t *testing.T) {
+	r := recipe.Get("abra-test-recipe")
+	err := r.EnsureExists()
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	tests := []struct {
+		appEnv       map[string]string
+		composeFiles []string
+	}{
+		{
+			map[string]string{},
+			[]string{
+				fmt.Sprintf("%s/compose.yml", r.Dir),
+			},
+		},
+		{
+			map[string]string{"COMPOSE_FILE": "compose.yml"},
+			[]string{
+				fmt.Sprintf("%s/compose.yml", r.Dir),
+			},
+		},
+		{
+			map[string]string{"COMPOSE_FILE": "compose.extra_secret.yml"},
+			[]string{
+				fmt.Sprintf("%s/compose.extra_secret.yml", r.Dir),
+			},
+		},
+		{
+			map[string]string{"COMPOSE_FILE": "compose.yml:compose.extra_secret.yml"},
+			[]string{
+				fmt.Sprintf("%s/compose.yml", r.Dir),
+				fmt.Sprintf("%s/compose.extra_secret.yml", r.Dir),
+			},
+		},
+	}
+
+	for _, test := range tests {
+		composeFiles, err := r.GetComposeFiles(test.appEnv)
+		if err != nil {
+			t.Fatal(err)
+		}
+		assert.Equal(t, composeFiles, test.composeFiles)
+	}
+}
+
+func TestGetComposeFilesError(t *testing.T) {
+	r := recipe.Get("abra-test-recipe")
+	err := r.EnsureExists()
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	tests := []struct{ appEnv map[string]string }{
+		{map[string]string{"COMPOSE_FILE": "compose.yml::compose.foo.yml"}},
+		{map[string]string{"COMPOSE_FILE": "doesnt.exist.yml"}},
+	}
+
+	for _, test := range tests {
+		_, err := r.GetComposeFiles(test.appEnv)
+		if err == nil {
+			t.Fatalf("should have failed: %v", test.appEnv)
+		}
+	}
+}
+
+func TestFilters(t *testing.T) {
+	oldDir := config.RECIPES_DIR
+	config.RECIPES_DIR = "./testdata"
+	defer func() {
+		config.RECIPES_DIR = oldDir
+	}()
+
+	app, err := appPkg.NewApp(envfile.AppEnv{
+		"DOMAIN": "test.example.com",
+		"RECIPE": "test-recipe",
+	}, "test_example_com", appPkg.AppFile{
+		Path:   "./testdata/filtertest.end",
+		Server: "local",
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	f, err := app.Filters(false, false)
+	if err != nil {
+		t.Error(err)
+	}
+	compareFilter(t, f, map[string]map[string]bool{
+		"name": {
+			"test_example_com": true,
+		},
+	})
+
+	f2, err := app.Filters(false, true)
+	if err != nil {
+		t.Error(err)
+	}
+	compareFilter(t, f2, map[string]map[string]bool{
+		"name": {
+			"^test_example_com": true,
+		},
+	})
+
+	f3, err := app.Filters(true, false)
+	if err != nil {
+		t.Error(err)
+	}
+	compareFilter(t, f3, map[string]map[string]bool{
+		"name": {
+			"test_example_com_bar": true,
+			"test_example_com_foo": true,
+		},
+	})
+
+	f4, err := app.Filters(true, true)
+	if err != nil {
+		t.Error(err)
+	}
+	compareFilter(t, f4, map[string]map[string]bool{
+		"name": {
+			"^test_example_com_bar": true,
+			"^test_example_com_foo": true,
+		},
+	})
+
+	f5, err := app.Filters(false, false, "foo")
+	if err != nil {
+		t.Error(err)
+	}
+	compareFilter(t, f5, map[string]map[string]bool{
+		"name": {
+			"test_example_com_foo": true,
+		},
+	})
+}
+
+func compareFilter(t *testing.T, f1 filters.Args, f2 map[string]map[string]bool) {
+	t.Helper()
+	j1, err := f1.MarshalJSON()
+	if err != nil {
+		t.Error(err)
+	}
+	j2, err := json.Marshal(f2)
+	if err != nil {
+		t.Error(err)
+	}
+	if diff := cmp.Diff(string(j2), string(j1)); diff != "" {
+		t.Errorf("filters mismatch (-want +got):\n%s", diff)
+	}
+}
+
+func TestWriteRecipeVersionOverwrite(t *testing.T) {
+	app, err := appPkg.GetApp(testPkg.ExpectedAppFiles, testPkg.AppName)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	defer t.Cleanup(func() {
+		if err := app.WipeRecipeVersion(); err != nil {
+			t.Fatal(err)
+		}
+	})
+
+	assert.Equal(t, "", app.Recipe.EnvVersion)
+
+	if err := app.WriteRecipeVersion("foo", false); err != nil {
+		t.Fatal(err)
+	}
+
+	app, err = appPkg.GetApp(testPkg.ExpectedAppFiles, testPkg.AppName)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	assert.Equal(t, "foo", app.Recipe.EnvVersion)
+}

pkg/app/compose.go

@@ -0,0 +1,98 @@
+package app
+
+import (
+	"fmt"
+	"strconv"
+
+	"coopcloud.tech/abra/pkg/envfile"
+	"coopcloud.tech/abra/pkg/log"
+	composetypes "github.com/docker/cli/cli/compose/types"
+)
+
+// SetRecipeLabel adds the label 'coop-cloud.${STACK_NAME}.recipe=${RECIPE}' to the app container
+// to signal which recipe is connected to the deployed app
+func SetRecipeLabel(compose *composetypes.Config, stackName string, recipe string) {
+	for _, service := range compose.Services {
+		if service.Name == "app" {
+			log.Debugf("set recipe label 'coop-cloud.%s.recipe' to %s for %s", stackName, recipe, stackName)
+			labelKey := fmt.Sprintf("coop-cloud.%s.recipe", stackName)
+			service.Deploy.Labels[labelKey] = recipe
+		}
+	}
+}
+
+// SetChaosLabel adds the label 'coop-cloud.${STACK_NAME}.chaos=true/false' to the app container
+// to signal if the app is deployed in chaos mode
+func SetChaosLabel(compose *composetypes.Config, stackName string, chaos bool) {
+	for _, service := range compose.Services {
+		if service.Name == "app" {
+			log.Debugf("set label 'coop-cloud.%s.chaos' to %v for %s", stackName, chaos, stackName)
+			labelKey := fmt.Sprintf("coop-cloud.%s.chaos", stackName)
+			service.Deploy.Labels[labelKey] = strconv.FormatBool(chaos)
+		}
+	}
+}
+
+// SetChaosVersionLabel adds the label 'coop-cloud.${STACK_NAME}.chaos-version=$(GIT_COMMIT)' to the app container
+func SetChaosVersionLabel(compose *composetypes.Config, stackName string, chaosVersion string) {
+	for _, service := range compose.Services {
+		if service.Name == "app" {
+			log.Debugf("set label 'coop-cloud.%s.chaos-version' to %v for %s", stackName, chaosVersion, stackName)
+			labelKey := fmt.Sprintf("coop-cloud.%s.chaos-version", stackName)
+			service.Deploy.Labels[labelKey] = chaosVersion
+		}
+	}
+}
+
+func SetVersionLabel(compose *composetypes.Config, stackName string, version string) {
+	for _, service := range compose.Services {
+		if service.Name == "app" {
+			log.Debugf("set label 'coop-cloud.%s.version' to %v for %s", stackName, version, stackName)
+			labelKey := fmt.Sprintf("coop-cloud.%s.version", stackName)
+			service.Deploy.Labels[labelKey] = version
+		}
+	}
+}
+
+// SetUpdateLabel adds env ENABLE_AUTO_UPDATE as label to enable/disable the
+// auto update process for this app. The default if this variable is not set is to disable
+// the auto update process.
+func SetUpdateLabel(compose *composetypes.Config, stackName string, appEnv envfile.AppEnv) {
+	for _, service := range compose.Services {
+		if service.Name == "app" {
+			enable_auto_update, exists := appEnv["ENABLE_AUTO_UPDATE"]
+			if !exists {
+				enable_auto_update = "false"
+			}
+			log.Debugf("set label 'coop-cloud.%s.autoupdate' to %s for %s", stackName, enable_auto_update, stackName)
+			labelKey := fmt.Sprintf("coop-cloud.%s.autoupdate", stackName)
+			service.Deploy.Labels[labelKey] = enable_auto_update
+		}
+	}
+}
+
+// GetLabel reads docker labels in the format of "coop-cloud.${STACK_NAME}.${LABEL}" from the local compose files
+func GetLabel(compose *composetypes.Config, stackName string, label string) string {
+	for _, service := range compose.Services {
+		if service.Name == "app" {
+			labelKey := fmt.Sprintf("coop-cloud.%s.%s", stackName, label)
+			log.Debugf("get label '%s'", labelKey)
+			if labelValue, ok := service.Deploy.Labels[labelKey]; ok {
+				return labelValue
+			}
+		}
+	}
+	log.Debugf("no %s label found for %s", label, stackName)
+	return ""
+}
+
+// GetTimeoutFromLabel reads the timeout value from docker label "coop-cloud.${STACK_NAME}.TIMEOUT" and returns 50 as default value
+func GetTimeoutFromLabel(compose *composetypes.Config, stackName string) (int, error) {
+	timeout := 50 // Default Timeout
+	var err error = nil
+	if timeoutLabel := GetLabel(compose, stackName, "timeout"); timeoutLabel != "" {
+		log.Debugf("timeout label: %s", timeoutLabel)
+		timeout, err = strconv.Atoi(timeoutLabel)
+	}
+	return timeout, err
+}

pkg/app/testdata/filtertest.env

@@ -0,0 +1,2 @@
+RECIPE=test-recipe
+DOMAIN=test.example.com

pkg/app/testdata/test-recipe/compose.yml

@@ -0,0 +1,6 @@
+version: "3.8"
+services:
+  foo:
+    image: debian
+  bar:
+    image: debian

pkg/autocomplete/autocomplete.go

@@ -0,0 +1,124 @@
+package autocomplete
+
+import (
+	"fmt"
+	"sort"
+
+	"coopcloud.tech/abra/pkg/app"
+	appPkg "coopcloud.tech/abra/pkg/app"
+	"coopcloud.tech/abra/pkg/recipe"
+	"github.com/spf13/cobra"
+)
+
+// AppNameComplete copletes app names.
+func AppNameComplete() ([]string, cobra.ShellCompDirective) {
+	appFiles, err := app.LoadAppFiles("")
+	if err != nil {
+		err := fmt.Sprintf("autocomplete failed: %s", err)
+		return []string{err}, cobra.ShellCompDirectiveError
+	}
+
+	var appNames []string
+	for appName := range appFiles {
+		appNames = append(appNames, appName)
+	}
+
+	return appNames, cobra.ShellCompDirectiveDefault
+}
+
+func ServiceNameComplete(appName string) ([]string, cobra.ShellCompDirective) {
+	serviceNames, err := app.GetAppServiceNames(appName)
+	if err != nil {
+		err := fmt.Sprintf("autocomplete failed: %s", err)
+		return []string{err}, cobra.ShellCompDirectiveError
+	}
+
+	return serviceNames, cobra.ShellCompDirectiveDefault
+}
+
+// RecipeNameComplete completes recipe names.
+func RecipeNameComplete() ([]string, cobra.ShellCompDirective) {
+	catl, err := recipe.ReadRecipeCatalogue(false)
+	if err != nil {
+		err := fmt.Sprintf("autocomplete failed: %s", err)
+		return []string{err}, cobra.ShellCompDirectiveError
+	}
+
+	var recipeNames []string
+	for name := range catl {
+		recipeNames = append(recipeNames, name)
+	}
+
+	return recipeNames, cobra.ShellCompDirectiveDefault
+}
+
+// RecipeVersionComplete completes versions for the recipe.
+func RecipeVersionComplete(recipeName string) ([]string, cobra.ShellCompDirective) {
+	catl, err := recipe.ReadRecipeCatalogue(true)
+	if err != nil {
+		err := fmt.Sprintf("autocomplete failed: %s", err)
+		return []string{err}, cobra.ShellCompDirectiveError
+	}
+
+	var recipeVersions []string
+	for _, v := range catl[recipeName].Versions {
+		for v2 := range v {
+			recipeVersions = append(recipeVersions, v2)
+		}
+	}
+
+	return recipeVersions, cobra.ShellCompDirectiveDefault
+}
+
+// ServerNameComplete completes server names.
+func ServerNameComplete() ([]string, cobra.ShellCompDirective) {
+	files, err := app.LoadAppFiles("")
+	if err != nil {
+		err := fmt.Sprintf("autocomplete failed: %s", err)
+		return []string{err}, cobra.ShellCompDirectiveError
+	}
+
+	var serverNames []string
+	for _, appFile := range files {
+		serverNames = append(serverNames, appFile.Server)
+	}
+
+	return serverNames, cobra.ShellCompDirectiveDefault
+}
+
+// CommandNameComplete completes recipe commands.
+func CommandNameComplete(appName string) ([]string, cobra.ShellCompDirective) {
+	app, err := app.Get(appName)
+	if err != nil {
+		err := fmt.Sprintf("autocomplete failed: %s", err)
+		return []string{err}, cobra.ShellCompDirectiveError
+	}
+
+	cmdNames, err := appPkg.ReadAbraShCmdNames(app.Recipe.AbraShPath)
+	if err != nil {
+		err := fmt.Sprintf("autocomplete failed: %s", err)
+		return []string{err}, cobra.ShellCompDirectiveError
+	}
+
+	sort.Strings(cmdNames)
+
+	return cmdNames, cobra.ShellCompDirectiveDefault
+}
+
+// SecretsComplete completes recipe secrets.
+func SecretComplete(recipeName string) ([]string, cobra.ShellCompDirective) {
+	r := recipe.Get(recipeName)
+
+	config, err := r.GetComposeConfig(nil)
+	if err != nil {
+		err := fmt.Sprintf("autocomplete failed: %s", err)
+		return []string{err}, cobra.ShellCompDirectiveError
+	}
+
+	var secretNames []string
+	for name := range config.Secrets {
+		secretNames = append(secretNames, name)
+	}
+
+	return secretNames, cobra.ShellCompDirectiveDefault
+}

pkg/catalogue/catalogue.go

@@ -0,0 +1,87 @@
+package catalogue
+
+import (
+	"fmt"
+	"os"
+	"path"
+	"strings"
+
+	"coopcloud.tech/abra/pkg/config"
+	gitPkg "coopcloud.tech/abra/pkg/git"
+	"coopcloud.tech/abra/pkg/log"
+	"github.com/go-git/go-git/v5"
+)
+
+// EnsureCatalogue ensures that the catalogue is cloned locally & present.
+func EnsureCatalogue() error {
+	catalogueDir := path.Join(config.ABRA_DIR, "catalogue")
+	if _, err := os.Stat(catalogueDir); err != nil && os.IsNotExist(err) {
+		log.Debugf("catalogue is missing, retrieving now")
+
+		url := fmt.Sprintf("%s/%s.git", config.REPOS_BASE_URL, config.CATALOGUE_JSON_REPO_NAME)
+		if err := gitPkg.Clone(catalogueDir, url); err != nil {
+			return err
+		}
+	}
+
+	return nil
+}
+
+// EnsureIsClean makes sure that the catalogue has no unstaged changes.
+func EnsureIsClean() error {
+	isClean, err := gitPkg.IsClean(config.CATALOGUE_DIR)
+	if err != nil {
+		return err
+	}
+
+	if !isClean {
+		msg := "%s has locally unstaged changes? please commit/remove your changes before proceeding"
+		return fmt.Errorf(msg, config.CATALOGUE_DIR)
+	}
+
+	return nil
+}
+
+// EnsureUpToDate ensures that the local catalogue is up to date.
+func EnsureUpToDate() error {
+	repo, err := git.PlainOpen(config.CATALOGUE_DIR)
+	if err != nil {
+		return err
+	}
+
+	remotes, err := repo.Remotes()
+	if err != nil {
+		return err
+	}
+
+	if len(remotes) == 0 {
+		msg := "cannot ensure %s is up-to-date, no git remotes configured"
+		log.Debugf(msg, config.CATALOGUE_DIR)
+		return nil
+	}
+
+	worktree, err := repo.Worktree()
+	if err != nil {
+		return err
+	}
+
+	branch, err := gitPkg.CheckoutDefaultBranch(repo, config.CATALOGUE_DIR)
+	if err != nil {
+		return err
+	}
+
+	opts := &git.PullOptions{
+		Force:         true,
+		ReferenceName: branch,
+	}
+
+	if err := worktree.Pull(opts); err != nil {
+		if !strings.Contains(err.Error(), "already up-to-date") {
+			return err
+		}
+	}
+
+	log.Debugf("fetched latest git changes for %s", config.CATALOGUE_DIR)
+
+	return nil
+}

pkg/client/client.go

@@ -0,0 +1,104 @@
+// Package client provides Docker client initiatialisation functions.
+package client
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"net/http"
+	"os"
+	"time"
+
+	contextPkg "coopcloud.tech/abra/pkg/context"
+	"coopcloud.tech/abra/pkg/log"
+	sshPkg "coopcloud.tech/abra/pkg/ssh"
+	commandconnPkg "coopcloud.tech/abra/pkg/upstream/commandconn"
+	"github.com/docker/docker/client"
+)
+
+// Conf is a Docker client configuration.
+type Conf struct {
+	Timeout int
+}
+
+// Opt is a Docker client option.
+type Opt func(c *Conf)
+
+// WithTimeout specifies a timeout for a Docker client.
+func WithTimeout(timeout int) Opt {
+	return func(c *Conf) {
+		c.Timeout = timeout
+	}
+}
+
+// New initiates a new Docker client. New client connections are validated so
+// that we ensure connections via SSH to the daemon can succeed. It takes into
+// account that you may only want the local client and not communicate via SSH.
+// For this use-case, please pass "default" as the contextName.
+func New(serverName string, opts ...Opt) (*client.Client, error) {
+	var clientOpts []client.Opt
+
+	if serverName != "default" {
+		context, err := GetContext(serverName)
+		if err != nil {
+			return nil, fmt.Errorf("unknown server, run \"abra server add %s\"?", serverName)
+		}
+
+		ctxEndpoint, err := contextPkg.GetContextEndpoint(context)
+		if err != nil {
+			return nil, err
+		}
+
+		conf := &Conf{}
+		for _, opt := range opts {
+			opt(conf)
+		}
+
+		helper, err := commandconnPkg.NewConnectionHelper(ctxEndpoint, conf.Timeout)
+		if err != nil {
+			return nil, err
+		}
+
+		httpClient := &http.Client{
+			Transport: &http.Transport{
+				DialContext:     helper.Dialer,
+				IdleConnTimeout: 30 * time.Second,
+			},
+		}
+
+		clientOpts = append(clientOpts,
+			client.WithHTTPClient(httpClient),
+			client.WithHost(helper.Host),
+			client.WithDialContext(helper.Dialer),
+		)
+	}
+
+	version := os.Getenv("DOCKER_API_VERSION")
+	if version != "" {
+		clientOpts = append(clientOpts, client.WithVersion(version))
+	} else {
+		clientOpts = append(clientOpts, client.WithAPIVersionNegotiation())
+	}
+
+	cl, err := client.NewClientWithOpts(clientOpts...)
+	if err != nil {
+		return nil, err
+	}
+
+	log.Debugf("created client for %s", serverName)
+
+	info, err := cl.Info(context.Background())
+	if err != nil {
+		return cl, sshPkg.Fatal(serverName, err)
+	}
+
+	if info.Swarm.LocalNodeState == "inactive" {
+		if serverName != "default" {
+			return cl, fmt.Errorf("swarm mode not enabled on %s?", serverName)
+		}
+
+		return cl, errors.New("swarm mode not enabled on local server?")
+	}
+
+	return cl, nil
+}

pkg/client/context.go

@@ -0,0 +1,88 @@
+package client
+
+import (
+	"errors"
+	"fmt"
+
+	"coopcloud.tech/abra/pkg/context"
+	"coopcloud.tech/abra/pkg/log"
+	commandconnPkg "coopcloud.tech/abra/pkg/upstream/commandconn"
+	dConfig "github.com/docker/cli/cli/config"
+	"github.com/docker/cli/cli/context/docker"
+	contextStore "github.com/docker/cli/cli/context/store"
+)
+
+type Context = contextStore.Metadata
+
+// CreateContext creates a new Docker context.
+func CreateContext(contextName string) error {
+	host := fmt.Sprintf("ssh://%s", contextName)
+
+	if err := createContext(contextName, host); err != nil {
+		return err
+	}
+
+	log.Debugf("created the %s context", contextName)
+
+	return nil
+}
+
+// createContext interacts with Docker Context to create a Docker context config
+func createContext(name string, host string) error {
+	s := context.NewDefaultDockerContextStore()
+	contextMetadata := contextStore.Metadata{
+		Endpoints: make(map[string]interface{}),
+		Name:      name,
+	}
+
+	contextTLSData := contextStore.ContextTLSData{
+		Endpoints: make(map[string]contextStore.EndpointTLSData),
+	}
+
+	dockerEP, dockerTLS, err := commandconnPkg.GetDockerEndpointMetadataAndTLS(host)
+	if err != nil {
+		return err
+	}
+
+	contextMetadata.Endpoints[docker.DockerEndpoint] = dockerEP
+	if dockerTLS != nil {
+		contextTLSData.Endpoints[docker.DockerEndpoint] = *dockerTLS
+	}
+
+	if err := s.CreateOrUpdate(contextMetadata); err != nil {
+		return err
+	}
+
+	if err := s.ResetTLSMaterial(name, &contextTLSData); err != nil {
+		return err
+	}
+
+	return nil
+}
+
+func DeleteContext(name string) error {
+	if name == "default" {
+		return errors.New("context 'default' cannot be removed")
+	}
+
+	if _, err := GetContext(name); err != nil {
+		return err
+	}
+
+	cfg := dConfig.LoadDefaultConfigFile(nil)
+	cfg.CurrentContext = ""
+	if err := cfg.Save(); err != nil {
+		return err
+	}
+
+	return context.NewDefaultDockerContextStore().Remove(name)
+}
+
+func GetContext(contextName string) (contextStore.Metadata, error) {
+	ctx, err := context.NewDefaultDockerContextStore().GetMetadata(contextName)
+	if err != nil {
+		return contextStore.Metadata{}, err
+	}
+
+	return ctx, nil
+}

pkg/client/registry.go

@@ -0,0 +1,28 @@
+package client
+
+import (
+	"context"
+	"fmt"
+
+	"github.com/containers/image/docker"
+	"github.com/containers/image/types"
+	"github.com/distribution/reference"
+)
+
+// GetRegistryTags retrieves all tags of an image from a container registry.
+func GetRegistryTags(img reference.Named) ([]string, error) {
+	var tags []string
+
+	ref, err := docker.ParseReference(fmt.Sprintf("//%s", img))
+	if err != nil {
+		return tags, fmt.Errorf("failed to parse image %s, saw: %s", img, err.Error())
+	}
+
+	ctx := context.Background()
+	tags, err = docker.GetRepositoryTags(ctx, &types.SystemContext{}, ref)
+	if err != nil {
+		return tags, err
+	}
+
+	return tags, nil
+}

pkg/client/secret.go

@@ -0,0 +1,19 @@
+package client
+
+import (
+	"context"
+
+	"github.com/docker/docker/api/types/swarm"
+	"github.com/docker/docker/client"
+)
+
+func StoreSecret(cl *client.Client, secretName, secretValue, server string) error {
+	ann := swarm.Annotations{Name: secretName}
+	spec := swarm.SecretSpec{Annotations: ann, Data: []byte(secretValue)}
+
+	if _, err := cl.SecretCreate(context.Background(), spec); err != nil {
+		return err
+	}
+
+	return nil
+}

pkg/client/volumes.go

@@ -0,0 +1,62 @@
+package client
+
+import (
+	"context"
+	"fmt"
+	"time"
+
+	"coopcloud.tech/abra/pkg/log"
+	"github.com/docker/docker/api/types/filters"
+	"github.com/docker/docker/api/types/volume"
+	"github.com/docker/docker/client"
+)
+
+func GetVolumes(cl *client.Client, ctx context.Context, server string, fs filters.Args) ([]*volume.Volume, error) {
+	volumeListOKBody, err := cl.VolumeList(ctx, volume.ListOptions{Filters: fs})
+	volumeList := volumeListOKBody.Volumes
+	if err != nil {
+		return volumeList, err
+	}
+
+	return volumeList, nil
+}
+
+func GetVolumeNames(volumes []*volume.Volume) []string {
+	var volumeNames []string
+
+	for _, vol := range volumes {
+		volumeNames = append(volumeNames, vol.Name)
+	}
+
+	return volumeNames
+}
+
+func RemoveVolumes(cl *client.Client, ctx context.Context, volumeNames []string, force bool, retries int) error {
+	for _, volName := range volumeNames {
+		err := retryFunc(5, func() error {
+			return cl.VolumeRemove(context.Background(), volName, force)
+		})
+		if err != nil {
+			return fmt.Errorf("volume %s: %s", volName, err)
+		}
+	}
+	return nil
+}
+
+// retryFunc retries the given function for the given retries. After the nth
+// retry it waits (n + 1)^2 seconds before the next retry (starting with n=0).
+// It returns an error if the function still failed after the last retry.
+func retryFunc(retries int, fn func() error) error {
+	for i := 0; i < retries; i++ {
+		err := fn()
+		if err == nil {
+			return nil
+		}
+		if i+1 < retries {
+			sleep := time.Duration(i+1) * time.Duration(i+1)
+			log.Infof("%s: waiting %d seconds before next retry", err, sleep)
+			time.Sleep(sleep * time.Second)
+		}
+	}
+	return fmt.Errorf("%d retries failed", retries)
+}

pkg/client/volumes_test.go

@@ -0,0 +1,26 @@
+package client
+
+import (
+	"fmt"
+	"testing"
+)
+
+func TestRetryFunc(t *testing.T) {
+	err := retryFunc(1, func() error { return nil })
+	if err != nil {
+		t.Errorf("should not return an error: %s", err)
+	}
+
+	i := 0
+	fn := func() error {
+		i++
+		return fmt.Errorf("oh no, something went wrong!")
+	}
+	err = retryFunc(2, fn)
+	if err == nil {
+		t.Error("should return an error")
+	}
+	if i != 2 {
+		t.Errorf("The function should have been called 1 times, got %d", i)
+	}
+}

pkg/config/abra.go

@@ -0,0 +1,126 @@
+package config
+
+import (
+	"os"
+	"path"
+	"path/filepath"
+
+	"coopcloud.tech/abra/pkg/log"
+	"gopkg.in/yaml.v3"
+)
+
+// LoadAbraConfig returns the abra configuration. It tries to find a abra
+// configuration file (see findAbraConfig for lookup logic). When no
+// configuration was found it returns the default config.
+func LoadAbraConfig() Abra {
+	wd, _ := os.Getwd()
+	configFile := findAbraConfig(wd)
+	if configFile == "" {
+		log.Debugf("no config file found")
+		return Abra{}
+	}
+	data, err := os.ReadFile(configFile)
+	if err != nil {
+		// Do nothing, when an error occurs
+		log.Debugf("error reading config file: %s", err)
+		return Abra{}
+	}
+
+	config := Abra{}
+	err = yaml.Unmarshal(data, &config)
+	if err != nil {
+		// Do nothing, when an error occurs
+		log.Debugf("error loading config file: %s", err)
+		return Abra{}
+	}
+	log.Debugf("config file loaded from: %s", configFile)
+	config.configPath = filepath.Dir(configFile)
+	return config
+}
+
+// findAbraConfig recursively looks for a abra.y(a)ml file in the given directory.
+// When the file was not found it calls the function again with the parent
+// directory until the home directory is hit. When no abra config was found it
+// returns an empty string.
+func findAbraConfig(dir string) string {
+	dir, err := filepath.Abs(dir)
+	if err != nil {
+		return ""
+	}
+	if dir == os.ExpandEnv("$HOME") || dir == "/" {
+		return ""
+	}
+	p := path.Join(dir, "abra.yaml")
+	if _, err := os.Stat(p); err == nil {
+		return p
+	}
+	p = path.Join(dir, "abra.yml")
+	if _, err := os.Stat(p); err == nil {
+		return p
+	}
+	return findAbraConfig(filepath.Dir(dir))
+}
+
+// Abra defines the configuration file for abra.
+type Abra struct {
+	configPath string
+	AbraDir    string `yaml:"abraDir"`
+}
+
+// GetAbraDir returns the abra dir. It has the following logic:
+// 1. check if $ABRA_DIR is set
+// 2. check if abraDir was set in a config file
+// 3. use $HOME/.abra when above two options failed
+func (a Abra) GetAbraDir() string {
+	if dir, exists := os.LookupEnv("ABRA_DIR"); exists && dir != "" {
+		log.Debug("read abra dir from $ABRA_DIR")
+		return dir
+	}
+	if a.AbraDir != "" {
+		log.Debug("read abra dir from config file")
+		if path.IsAbs(a.AbraDir) {
+			return a.AbraDir
+		}
+		// Make the path absolute
+		return path.Join(a.configPath, a.AbraDir)
+	}
+	log.Debug("using default abra dir")
+	return os.ExpandEnv("$HOME/.abra")
+}
+
+func (a Abra) GetServersDir() string   { return path.Join(a.GetAbraDir(), "servers") }
+func (a Abra) GetRecipesDir() string   { return path.Join(a.GetAbraDir(), "recipes") }
+func (a Abra) GetLogsDir() string      { return path.Join(a.GetAbraDir(), "logs") }
+func (a Abra) GetVendorDir() string    { return path.Join(a.GetAbraDir(), "vendor") }
+func (a Abra) GetBackupDir() string    { return path.Join(a.GetAbraDir(), "backups") }
+func (a Abra) GetCatalogueDir() string { return path.Join(a.GetAbraDir(), "catalogue") }
+
+var config = LoadAbraConfig()
+
+var (
+	ABRA_DIR                  = config.GetAbraDir()
+	SERVERS_DIR               = config.GetServersDir()
+	RECIPES_DIR               = config.GetRecipesDir()
+	LOGS_DIR                  = config.GetLogsDir()
+	VENDOR_DIR                = config.GetVendorDir()
+	BACKUP_DIR                = config.GetBackupDir()
+	CATALOGUE_DIR             = config.GetCatalogueDir()
+	RECIPES_JSON              = path.Join(config.GetCatalogueDir(), "recipes.json")
+	REPOS_BASE_URL            = "https://git.coopcloud.tech/coop-cloud"
+	CATALOGUE_JSON_REPO_NAME  = "recipes-catalogue-json"
+	TOOLSHED_SSH_URL_TEMPLATE = "ssh://git@git.coopcloud.tech:2222/toolshed/%s.git"
+	RECIPES_SSH_URL_TEMPLATE  = "ssh://git@git.coopcloud.tech:2222/coop-cloud/%s.git"
+
+	// NOTE(d1): please note, this was done purely out of laziness on our part
+	// AFAICR. it's easy to punt the value into the label because that is what is
+	// expects. it's not particularly useful in terms of UI/UX but hey, nobody
+	// complained yet!
+	CHAOS_DEFAULT = "false"
+
+	DIRTY_DEFAULT = "+U"
+
+	NO_DOMAIN_DEFAULT  = "N/A"
+	NO_VERSION_DEFAULT = "N/A"
+
+	UNKNOWN_DEFAULT = "unknown"
+)

pkg/config/abra_test.go

@@ -0,0 +1,133 @@
+package config
+
+import (
+	"log"
+	"os"
+	"path/filepath"
+	"testing"
+)
+
+func TestFindAbraConfig(t *testing.T) {
+	wd, err := os.Getwd()
+	if err != nil {
+		log.Fatal(err)
+	}
+	tests := []struct {
+		Dir    string
+		Config string
+	}{
+		{
+			Dir:    "testdata/abraconfig1",
+			Config: filepath.Join(wd, "testdata/abraconfig1/abra.yaml"),
+		},
+		{
+			Dir:    "testdata/abraconfig1/subdir",
+			Config: filepath.Join(wd, "testdata/abraconfig1/abra.yaml"),
+		},
+		{
+			Dir:    "testdata/abraconfig2",
+			Config: filepath.Join(wd, "testdata/abraconfig2/abra.yml"),
+		},
+		{
+			Dir:    "testdata/abraconfig2/subdir",
+			Config: filepath.Join(wd, "testdata/abraconfig2/abra.yml"),
+		},
+		{
+			Dir:    "testdata",
+			Config: "",
+		},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.Dir, func(t *testing.T) {
+			config := findAbraConfig(tc.Dir)
+			if config != tc.Config {
+				t.Errorf("\nwant: %s\ngot:  %s", tc.Config, config)
+			}
+		})
+	}
+}
+
+func TestLoadAbraConfigGetAbraDir(t *testing.T) {
+	wd, err := os.Getwd()
+	if err != nil {
+		log.Fatal(err)
+	}
+	t.Setenv("ABRA_DIR", "")
+
+	t.Run("default", func(t *testing.T) {
+		cfg := LoadAbraConfig()
+		wantAbraDir := os.ExpandEnv("$HOME/.abra")
+		if cfg.GetAbraDir() != wantAbraDir {
+			t.Errorf("\nwant: %s\ngot:  %s", wantAbraDir, cfg.GetAbraDir())
+		}
+	})
+
+	t.Run("from config file", func(t *testing.T) {
+		t.Cleanup(func() { os.Chdir(wd) })
+		err = os.Chdir(filepath.Join(wd, "testdata/abraconfig1"))
+		if err != nil {
+			log.Fatal(err)
+		}
+
+		cfg := LoadAbraConfig()
+		wantAbraDir := filepath.Join(wd, "testdata/abraconfig1/foobar")
+		if cfg.GetAbraDir() != wantAbraDir {
+			t.Errorf("\nwant: %s\ngot:  %s", wantAbraDir, cfg.GetAbraDir())
+		}
+	})
+
+	t.Run("default when config file is empty", func(t *testing.T) {
+		t.Cleanup(func() { os.Chdir(wd) })
+		err := os.Chdir(filepath.Join(wd, "testdata/abraconfig2"))
+		if err != nil {
+			log.Fatal(err)
+		}
+
+		cfg := LoadAbraConfig()
+		wantAbraDir := os.ExpandEnv("$HOME/.abra")
+		if cfg.GetAbraDir() != wantAbraDir {
+			t.Errorf("\nwant: %s\ngot:  %s", wantAbraDir, cfg.GetAbraDir())
+		}
+	})
+
+	t.Run("from env variable", func(t *testing.T) {
+		t.Setenv("ABRA_DIR", "foo")
+		cfg := LoadAbraConfig()
+		wantAbraDir := "foo"
+		if cfg.GetAbraDir() != wantAbraDir {
+			t.Errorf("\nwant: %s\ngot:  %s", wantAbraDir, cfg.GetAbraDir())
+		}
+	})
+}
+
+func TestLoadAbraConfigServersDir(t *testing.T) {
+	wd, err := os.Getwd()
+	if err != nil {
+		log.Fatal(err)
+	}
+	t.Setenv("ABRA_DIR", "")
+
+	t.Run("default", func(t *testing.T) {
+		cfg := LoadAbraConfig()
+		wantServersDir := os.ExpandEnv("$HOME/.abra/servers")
+		if cfg.GetServersDir() != wantServersDir {
+			t.Errorf("\nwant: %s\ngot:  %s", wantServersDir, cfg.GetServersDir())
+		}
+	})
+
+	t.Run("from config file", func(t *testing.T) {
+		t.Cleanup(func() { os.Chdir(wd) })
+		err = os.Chdir(filepath.Join(wd, "testdata/abraconfig1"))
+		if err != nil {
+			log.Fatal(err)
+		}
+
+		cfg := LoadAbraConfig()
+		log.Println(cfg)
+		wantServersDir := filepath.Join(wd, "testdata/abraconfig1/foobar/servers")
+		if cfg.GetServersDir() != wantServersDir {
+			t.Errorf("\nwant: %s\ngot:  %s", wantServersDir, cfg.GetServersDir())
+		}
+	})
+}

pkg/config/env.go

@@ -0,0 +1,115 @@
+package config
+
+import (
+	"fmt"
+	"io/fs"
+	"io/ioutil"
+	"os"
+	"path"
+	"path/filepath"
+	"strings"
+
+	"coopcloud.tech/abra/pkg/log"
+)
+
+const MAX_SANITISED_APP_NAME_LENGTH = 45
+const MAX_DOCKER_SECRET_LENGTH = 64
+
+var BackupbotLabel = "coop-cloud.backupbot.enabled"
+
+// GetServers retrieves all servers.
+func GetServers() ([]string, error) {
+	var servers []string
+
+	servers, err := GetAllFoldersInDirectory(SERVERS_DIR)
+	if err != nil {
+		return servers, err
+	}
+
+	var filtered []string
+	for _, s := range servers {
+		if !strings.HasPrefix(s, ".") {
+			filtered = append(filtered, s)
+		}
+	}
+
+	log.Debugf("retrieved %v servers: %s", len(filtered), filtered)
+
+	return filtered, nil
+}
+
+// ReadServerNames retrieves all server names.
+func ReadServerNames() ([]string, error) {
+	serverNames, err := GetAllFoldersInDirectory(SERVERS_DIR)
+
+	if err != nil {
+		return nil, err
+	}
+
+	log.Debugf("read %s from %s", strings.Join(serverNames, ","), SERVERS_DIR)
+
+	return serverNames, nil
+}
+
+// GetAllFilesInDirectory returns filenames of all files in directory
+func GetAllFilesInDirectory(directory string) ([]fs.FileInfo, error) {
+	var realFiles []fs.FileInfo
+
+	files, err := ioutil.ReadDir(directory)
+	if err != nil {
+		return nil, err
+	}
+
+	for _, file := range files {
+		// Follow any symlinks
+		filePath := path.Join(directory, file.Name())
+
+		if filepath.Ext(strings.TrimSpace(filePath)) != ".env" {
+			continue
+		}
+
+		realPath, err := filepath.EvalSymlinks(filePath)
+		if err != nil {
+			log.Warnf("broken symlink in your abra config folders: %s", filePath)
+		} else {
+			realFile, err := os.Stat(realPath)
+			if err != nil {
+				return nil, err
+			}
+			if !realFile.IsDir() {
+				realFiles = append(realFiles, file)
+			}
+		}
+	}
+
+	return realFiles, nil
+}
+
+// GetAllFoldersInDirectory returns both folder and symlink paths
+func GetAllFoldersInDirectory(directory string) ([]string, error) {
+	var folders []string
+
+	files, err := ioutil.ReadDir(directory)
+	if err != nil {
+		return nil, err
+	}
+	if len(files) == 0 {
+		return nil, fmt.Errorf("directory is empty: %s", directory)
+	}
+
+	for _, file := range files {
+		// Check if file is directory or symlink
+		if file.IsDir() || file.Mode()&fs.ModeSymlink != 0 {
+			filePath := path.Join(directory, file.Name())
+			realDir, err := filepath.EvalSymlinks(filePath)
+			if err != nil {
+				log.Warnf("broken symlink in your abra config folders: %s", filePath)
+			} else if stat, err := os.Stat(realDir); err == nil && stat.IsDir() {
+				// path is a directory
+				folders = append(folders, file.Name())
+			}
+		}
+	}
+
+	return folders, nil
+}

pkg/config/testdata/abraconfig1/abra.yaml

@@ -0,0 +1 @@
+abraDir: foobar

pkg/container/container.go

@@ -0,0 +1,83 @@
+package container
+
+import (
+	"context"
+	"fmt"
+	"strings"
+
+	"coopcloud.tech/abra/pkg/formatter"
+	"coopcloud.tech/abra/pkg/log"
+	"github.com/AlecAivazis/survey/v2"
+	"github.com/docker/docker/api/types"
+	containerTypes "github.com/docker/docker/api/types/container"
+	"github.com/docker/docker/api/types/filters"
+	"github.com/docker/docker/client"
+)
+
+// GetContainer retrieves a container. If noInput is false and the retrievd
+// count of containers does not match 1, then a prompt is presented to let the
+// user choose. A count of 0 is handled gracefully.
+func GetContainer(c context.Context, cl *client.Client, filters filters.Args, noInput bool) (types.Container, error) {
+	containerOpts := containerTypes.ListOptions{Filters: filters}
+	containers, err := cl.ContainerList(c, containerOpts)
+	if err != nil {
+		return types.Container{}, err
+	}
+
+	if len(containers) == 0 {
+		filter := filters.Get("name")[0]
+		return types.Container{}, fmt.Errorf("no containers matching the %v filter found?", filter)
+	}
+
+	if len(containers) > 1 {
+		var containersRaw []string
+		for _, container := range containers {
+			containerName := strings.Join(container.Names, " ")
+			trimmed := strings.TrimPrefix(containerName, "/")
+			created := formatter.HumanDuration(container.Created)
+			containersRaw = append(containersRaw, fmt.Sprintf("%s (created %v)", trimmed, created))
+		}
+
+		if noInput {
+			err := fmt.Errorf("expected 1 container but found %v: %s", len(containers), strings.Join(containersRaw, " "))
+			return types.Container{}, err
+		}
+
+		log.Warnf("ambiguous container list received, prompting for input")
+
+		var response string
+		prompt := &survey.Select{
+			Message: "which container are you looking for?",
+			Options: containersRaw,
+		}
+
+		if err := survey.AskOne(prompt, &response); err != nil {
+			return types.Container{}, err
+		}
+
+		chosenContainer := strings.TrimSpace(strings.Split(response, " ")[0])
+		for _, container := range containers {
+			containerName := strings.TrimSpace(strings.Join(container.Names, " "))
+			trimmed := strings.TrimPrefix(containerName, "/")
+			if trimmed == chosenContainer {
+				return container, nil
+			}
+		}
+
+		log.Fatal("failed to match chosen container")
+	}
+
+	return containers[0], nil
+}
+
+// GetContainerFromStackAndService retrieves the container for the given stack and service.
+func GetContainerFromStackAndService(cl *client.Client, stack, service string) (types.Container, error) {
+	filters := filters.NewArgs()
+	filters.Add("name", fmt.Sprintf("^%s_%s", stack, service))
+
+	container, err := GetContainer(context.Background(), cl, filters, true)
+	if err != nil {
+		return types.Container{}, err
+	}
+	return container, nil
+}