proper env modifiers support

This implements proper modifier support in the env file using this new fork of the godotenv library. The modifier implementation is quite basic for but can be improved later if needed. See this commit for the actual implementation.

Because we are now using proper modifer parsing, it does not affect the parsing of value, so this is possible again:
```
MY_VAR="#foo"
```
Closes coop-cloud/organising#535

.chglog/CHANGELOG.tpl.md

@@ -1,40 +0,0 @@
-{{ range .Versions }}
-<a name="{{ .Tag.Name }}"></a>
-## {{ if .Tag.Previous }}[{{ .Tag.Name }}]({{ $.Info.RepositoryURL }}/compare/{{ .Tag.Previous.Name }}...{{ .Tag.Name }}){{ else }}{{ .Tag.Name }}{{ end }}
-
-> {{ datetime "2006-01-02" .Tag.Date }}
-
-{{ range .CommitGroups -}}
-### {{ .Title }}
-
-{{ range .Commits -}}
-* {{ .Subject }}
-{{ end }}
-{{ end -}}
-
-{{- if .RevertCommits -}}
-### Reverts
-
-{{ range .RevertCommits -}}
-* {{ .Revert.Header }}
-{{ end }}
-{{ end -}}
-
-{{- if .MergeCommits -}}
-### Pull Requests
-
-{{ range .MergeCommits -}}
-* {{ .Header }}
-{{ end }}
-{{ end -}}
-
-{{- if .NoteGroups -}}
-{{ range .NoteGroups -}}
-### {{ .Title }}
-
-{{ range .Notes }}
-{{ .Body }}
-{{ end }}
-{{ end -}}
-{{ end -}}
-{{ end -}}

.chglog/config.yml

@@ -1,27 +0,0 @@
-style: github
-template: CHANGELOG.tpl.md
-info:
-  title: CHANGELOG
-  repository_url: https://git.autonomic.zone:2222/coop-cloud/go-abra
-options:
-  commits:
-    # filters:
-    #   Type:
-    #     - feat
-    #     - fix
-    #     - perf
-    #     - refactor
-  commit_groups:
-    # title_maps:
-    #   feat: Features
-    #   fix: Bug Fixes
-    #   perf: Performance Improvements
-    #   refactor: Code Refactoring
-  header:
-    pattern: "^(\\w*)\\:\\s(.*)$"
-    pattern_maps:
-      - Type
-      - Subject
-  notes:
-    keywords:
-      - BREAKING CHANGE

.dockerignore

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

.drone.yml

@@ -3,45 +3,20 @@ kind: pipeline
 name: coopcloud.tech/abra
 steps:
   - name: make check
-    image: golang:1.17
+    image: golang:1.21
     commands:
       - make check
 
-  - name: make static
-    image: golang:1.17
-    ignore: true # until we decide we all want this check
-    environment:
-      STATIC_CHECK_URL: honnef.co/go/tools/cmd/staticcheck
-      STATIC_CHECK_VERSION: v0.2.0
-    commands:
-      - go install $STATIC_CHECK_URL@$STATIC_CHECK_VERSION
-      - make static
-
-  - name: make build
-    image: golang:1.17
-    commands:
-      - make build
-
   - name: make test
-    image: golang:1.17
+    image: golang:1.21
+    environment:
+      ABRA_DIR: "/root/.abra"
     commands:
+      - make build-abra
+      - ./abra help # show version, initialise $ABRA_DIR
       - make test
-
-  - name: notify on failure
-    image: plugins/matrix
-    settings:
-      homeserver: https://matrix.autonomic.zone
-      roomid: "IFazIpLtxiScqbHqoa:autonomic.zone"
-      userid: "@autono-bot:autonomic.zone"
-      accesstoken:
-        from_secret: autono_bot_access_token
     depends_on:
       - make check
-      - make build
-      - make test
-    when:
-      status:
-        - failure
 
   - name: fetch
     image: docker:git
@@ -49,13 +24,12 @@ steps:
       - git fetch --tags
     depends_on:
       - make check
-      - make build
       - make test
     when:
       event: tag
 
   - name: release
-    image: golang:1.17
+    image: goreleaser/goreleaser:v1.18.2
     environment:
       GITEA_TOKEN:
         from_secret: goreleaser_gitea_token
@@ -63,12 +37,29 @@ steps:
       - name: deps
         path: /go
     commands:
-      - curl -sL https://git.io/goreleaser | bash
+      - goreleaser release
     depends_on:
       - fetch
     when:
       event: tag
 
+  - name: publish image
+    image: plugins/docker
+    settings:
+      auto_tag: true
+      username: 3wordchant
+      password:
+        from_secret: git_coopcloud_tech_token_3wc
+      repo: git.coopcloud.tech/coop-cloud/abra
+      tags: dev
+      registry: git.coopcloud.tech
+    when:
+      event:
+        exclude:
+          - pull_request
+    depends_on:
+      - make check
+
 volumes:
   - name: deps
     temp: {}

.envrc.sample

@@ -1,6 +1,7 @@
 go env -w GOPRIVATE=coopcloud.tech
 
 # export PASSWORD_STORE_DIR=$(pwd)/../../autonomic/passwords/passwords/
-# export HCLOUD_TOKEN=$(pass show logins/hetzner/cicd/api_key)
+
-# export CAPSUL_TOKEN=...
+# export ABRA_DIR="$HOME/.abra_test"
-# export GITEA_TOKEN=...
+# export ABRA_TEST_DOMAIN=test.example.com
+# export ABRA_SKIP_TEARDOWN=1 # for faster feedback when developing tests

.gitignore

@@ -1,5 +1,9 @@
-abra
+*fmtcoverage.html
-.vscode/
+.e2e.env
-vendor/
 .envrc
+.vscode/
+/kadabra
+abra
 dist/
+tests/integration/.bats
+vendor/

.goreleaser.yml

@@ -1,40 +1,76 @@
 ---
-project_name: abra
 gitea_urls:
   api: https://git.coopcloud.tech/api/v1
   download: https://git.coopcloud.tech/
   skip_tls_verify: false
+
 before:
   hooks:
     - go mod tidy
-    - go generate ./...
+
 builds:
-  - env:
+  - id: abra
-      - CGO_ENABLED=0
+    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 }}'"
+
+  - id: kadabra
+    binary: kadabra
+    dir: cmd/kadabra
+    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 }}'"
+
 archives:
   - replacements:
       386: i386
       amd64: x86_64
     format: binary
+
 checksum:
   name_template: "checksums.txt"
+
 snapshot:
   name_template: "{{ incpatch .Version }}-next"
+
 changelog:
   sort: desc
   filters:
     exclude:
+      - "^Merge"
+      - "^Revert"
       - "^WIP:"
-      - "^chore:"
+      - "^chore(deps):"
-      - "^docs:"
-      - "^refactor:"
       - "^style:"
       - "^test:"
       - "^tests:"

AUTHORS.md

@@ -0,0 +1,18 @@
+# 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
+- cassowary
+- codegod100
+- decentral1se
+- frando
+- kawaiipunk
+- knoflook
+- moritz
+- p4u1
+- rix
+- roxxers
+- vera
+- yksflip

Dockerfile

@@ -0,0 +1,24 @@
+FROM golang:1.21-alpine AS build
+
+ENV GOPRIVATE coopcloud.tech
+
+RUN apk add --no-cache \
+  ca-certificates \
+  gcc \
+  git \
+  make \
+  musl-dev
+
+RUN update-ca-certificates
+
+COPY . /app
+
+WORKDIR /app
+
+RUN CGO_ENABLED=0 make build
+
+FROM scratch
+
+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

@@ -1,38 +1,55 @@
 ABRA         := ./cmd/abra
+KADABRA      := ./cmd/kadabra
 COMMIT       := $(shell git rev-list -1 HEAD)
 GOPATH       := $(shell go env GOPATH)
+GOVERSION    := 1.21
 LDFLAGS      := "-X 'main.Commit=$(COMMIT)'"
 DIST_LDFLAGS := $(LDFLAGS)" -s -w"
+
 export GOPRIVATE=coopcloud.tech
 
-all: run test install build clean format check static
+# NOTE(d1): default `make` optimised for Abra hacking
+all: format check build-abra test
 
-run:
+run-abra:
 	@go run -ldflags=$(LDFLAGS) $(ABRA)
 
-install:
+run-kadabra:
+	@go run -ldflags=$(LDFLAGS) $(KADABRA)
+
+install-abra:
 	@go install -ldflags=$(LDFLAGS) $(ABRA)
 
-build-dev:
+install-kadabra:
-	@go build -ldflags=$(LDFLAGS) $(ABRA)
+	@go install -ldflags=$(LDFLAGS) $(KADABRA)
 
-build:
+build-abra:
-	@go build -ldflags=$(DIST_LDFLAGS) $(ABRA)
+	@go build -v -ldflags=$(DIST_LDFLAGS) $(ABRA)
+
+build-kadabra:
+	@go build -v -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 .
 
 check:
-	@test -z $$(gofmt -l .) || (echo "gofmt: formatting issue - run 'make format' to resolve" && exit 1)
+	@test -z $$(gofmt -l .) || \
-
+	(echo "gofmt: formatting issue - run 'make format' to resolve" && exit 1)
-static:
-	@staticcheck $(ABRA)
 
 test:
-	@go test ./... -cover
+	@go test ./... -cover -v
 
 loc:
 	@find . -name "*.go" | xargs wc -l

README.md

@@ -1,104 +1,13 @@
-# abra
+# `abra`
-
-> https://coopcloud.tech
 
 [![Build Status](https://build.coopcloud.tech/api/badges/coop-cloud/abra/status.svg?ref=refs/heads/main)](https://build.coopcloud.tech/coop-cloud/abra)
 [![Go Report Card](https://goreportcard.com/badge/git.coopcloud.tech/coop-cloud/abra)](https://goreportcard.com/report/git.coopcloud.tech/coop-cloud/abra)
+[![Go Reference](https://pkg.go.dev/badge/coopcloud.tech/abra.svg)](https://pkg.go.dev/coopcloud.tech/abra)
 
 The Co-op Cloud utility belt 🎩🐇
 
-`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.
+<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>
 
-## Install
+`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 💖
 
-### Arch-based Linux Distros
+Please see [docs.coopcloud.tech/abra](https://docs.coopcloud.tech/abra) for help on install, upgrade, hacking, troubleshooting & more!
-
-[abra (coming-soon)](https://aur.archlinux.org/packages/abra/) or for the latest version on git [abra-git](https://aur.archlinux.org/packages/abra-git/)
-
-```sh
-yay -S abra-git # or abra
-```
-
-### Debian-based Linux Distros
-
-**Coming Soon**
-
-### Homebrew
-
-**Coming Soon**
-
-### Build from source
-
-```sh
-git clone https://git.coopcloud.tech/coop-cloud/abra
-cd abra
-go env -w GOPRIVATE=coopcloud.tech
-make install
-```
-
-The abra binary will be in `$GOPATH/bin`.
-
-## Autocompletion
-
-**bash**
-
-Copy `scripts/autocomplete/bash` into `/etc/bash_completion.d/` and rename
-it to abra.
-
-```
-sudo cp scripts/autocomplete/bash /etc/bash_completion.d/abra
-source /etc/bash_completion.d/abra
-```
-
-**(fi)zsh**
-
-(fi)zsh doesn't have an autocompletion folder by default but you can create one, then copy `scripts/autocomplete/zsh` into it and add a couple lines to your `~/.zshrc` or `~/.fizsh/.fizshrc`
-
-```
-sudo mkdir /etc/zsh/completion.d/
-sudo cp scripts/autocomplete/zsh /etc/zsh/completion.d/abra
-echo "PROG=abra\n_CLI_ZSH_AUTOCOMPLETE_HACK=1\nsource /etc/zsh/completion.d/abra" >> ~/.zshrc
-```
-
-(replace .zshrc with ~/.fizsh/.fizshrc if you use fizsh)
-
-## Hacking
-
-Install direnv, run `cp .envrc.sample .envrc`, then run `direnv allow` in this directory. This will set coopcloud repos as private due to [this bug.](https://git.coopcloud.tech/coop-cloud/coopcloud.tech/issues/20#issuecomment-8201). Or you can run `go env -w GOPRIVATE=coopcloud.tech` but I'm not sure how persistent this is.
-
-Install [Go >= 1.16](https://golang.org/doc/install) and then:
-
-- `make build` to build
-- `./abra` to run commands
-- `make test` will run tests
-
-Our [Drone CI configuration](.drone.yml) runs a number of sanity on each pushed commit. See the [Makefile](./Makefile) for more handy targets.
-
-Please use the [conventional commit format](https://www.conventionalcommits.org/en/v1.0.0/) for your commits so we can automate our change log.
-
-## Versioning
-
-We use [goreleaser](https://goreleaser.com) to help us automate releases. We use [semver](https://semver.org) for versioning all releases of the tool. While we are still in the public alpha release phase, we will maintain a `0.y.z-alpha` format. Change logs are generated from our commit logs. We are still working this out and aim to refine our release praxis as we go.
-
-For developers, while using this `-alpha` format, the `y` part is the "major" version part. So, if you make breaking changes, you increment that and _not_ the `x` part. So, if you're on `0.1.0-alpha`, then you'd go to `0.1.1-alpha` for a backwards compatible change and `0.2.0-alpha` for a backwards incompatible change.
-
-## Making a new release
-
-- Change `ABRA_VERSION` to match the new tag in [`scripts`](./scripts/installer/installer) (use [semver](https://semver.org))
-- Commit that change (e.g. `git commit -m 'chore: publish next tag 0.3.1-alpha'`)
-- Make a new tag (e.g. `git tag 0.y.z-alpha`)
-- Push the new tag (e.g. `git push && git push --tags`)
-- Wait until the build finishes on [build.coopcloud.tech](https://build.coopcloud.tech/coop-cloud/abra)
-- Deploy the new installer script (e.g. `cd ./scripts/installer && make`)
-- Check the release worked, (e.g. `abra upgrade; abra version`)
-
-## Fork maintenance
-
-We maintain a fork of [godotenv](https://github.com/Autonomic-Cooperative/godotenv) for two features:
-
-1. multi-line env var support
-2. inline comment parsing
-
-You can upgrade the version here by running `go get github.com/Autonomic-Cooperative/godotenv@<commit>` where `<commit>` is the
-latest commit you want to pin to. We are aiming to migrate to YAML format for the environment configuration, so this should only
-be a temporary thing.

cli/app/app.go

@@ -1,37 +1,37 @@
 package app
 
 import (
-	"github.com/urfave/cli/v2"
+	"github.com/urfave/cli"
 )
 
-// AppCommand defines the `abra app` command and ets subcommands
+var AppCommand = cli.Command{
-var AppCommand = &cli.Command{
 	Name:        "app",
-	Usage:     "Manage apps",
 	Aliases:     []string{"a"},
-	ArgsUsage: "<app>",
+	Usage:       "Manage apps",
-	Description: `
+	ArgsUsage:   "<domain>",
-This command provides all the functionality you need to manage the life cycle
+	Description: "Functionality for managing the life cycle of your apps",
-of your apps. From initial deployment, day-2 operations (e.g. backup/restore)
+	Subcommands: []cli.Command{
-to scaling apps up and spinning them down.
-`,
-	Subcommands: []*cli.Command{
-		appNewCommand,
-		appConfigCommand,
-		appDeployCommand,
-		appUndeployCommand,
 		appBackupCommand,
-		appRestoreCommand,
-		appRemoveCommand,
 		appCheckCommand,
-		appListCommand,
+		appCmdCommand,
-		appPsCommand,
+		appConfigCommand,
-		appLogsCommand,
 		appCpCommand,
-		appRunCommand,
+		appDeployCommand,
+		appErrorsCommand,
+		appListCommand,
+		appLogsCommand,
+		appNewCommand,
+		appPsCommand,
+		appRemoveCommand,
+		appRestartCommand,
+		appRestoreCommand,
 		appRollbackCommand,
+		appRunCommand,
 		appSecretCommand,
-		appVolumeCommand,
+		appServicesCommand,
+		appUndeployCommand,
+		appUpgradeCommand,
 		appVersionCommand,
+		appVolumeCommand,
 	},
 }

cli/app/backup.go

@@ -1,87 +1,414 @@
 package app
 
 import (
-	"errors"
+	"archive/tar"
+	"context"
 	"fmt"
-	"io/ioutil"
+	"io"
 	"os"
-	"os/exec"
+	"path/filepath"
-	"path"
 	"strings"
+	"time"
 
 	"coopcloud.tech/abra/cli/internal"
+	"coopcloud.tech/abra/pkg/autocomplete"
+	"coopcloud.tech/abra/pkg/client"
 	"coopcloud.tech/abra/pkg/config"
+	containerPkg "coopcloud.tech/abra/pkg/container"
+	recipePkg "coopcloud.tech/abra/pkg/recipe"
+	"coopcloud.tech/abra/pkg/upstream/container"
+	"github.com/docker/cli/cli/command"
+	"github.com/docker/docker/api/types"
+	"github.com/docker/docker/api/types/filters"
+	dockerClient "github.com/docker/docker/client"
+	"github.com/docker/docker/pkg/archive"
+	"github.com/klauspost/pgzip"
 	"github.com/sirupsen/logrus"
-	"github.com/urfave/cli/v2"
+	"github.com/urfave/cli"
 )
 
-var backupAllServices bool
+type backupConfig struct {
-var backupAllServicesFlag = &cli.BoolFlag{
+	preHookCmd  string
-	Name:        "all",
+	postHookCmd string
-	Value:       false,
+	backupPaths []string
-	Destination: &backupAllServices,
-	Aliases:     []string{"a"},
-	Usage:       "Backup all services",
 }
 
-var appBackupCommand = &cli.Command{
+var appBackupCommand = cli.Command{
 	Name:      "backup",
-	Usage:     "Backup an app",
+	Aliases:   []string{"bk"},
-	Aliases:   []string{"b"},
+	Usage:     "Run app backup",
-	Flags:     []cli.Flag{backupAllServicesFlag},
+	ArgsUsage: "<domain> [<service>]",
-	ArgsUsage: "<service>",
+	Flags: []cli.Flag{
+		internal.DebugFlag,
+		internal.OfflineFlag,
+		internal.ChaosFlag,
+	},
+	Before:       internal.SubCommandBefore,
+	BashComplete: autocomplete.AppNameComplete,
+	Description: `
+Run an app backup.
+
+A backup command and pre/post hook commands are defined in the recipe
+configuration. Abra reads this configuration and run the comands in the context
+of the deployed services. Pass <service> if you only want to back up a single
+service. All backups are placed in the ~/.abra/backups directory.
+
+A single backup file is produced for all backup paths specified for a service.
+If we have the following backup configuration:
+
+    - "backupbot.backup.path=/var/lib/foo,/var/lib/bar"
+
+And we run "abra app backup example.com app", Abra will produce a file that
+looks like:
+
+    ~/.abra/backups/example_com_app_609341138.tar.gz
+
+This file is a compressed archive which contains all backup paths. To see paths, run:
+
+    tar -tf ~/.abra/backups/example_com_app_609341138.tar.gz
+
+(Make sure to change the name of the backup file)
+
+This single file can be used to restore your app. See "abra app restore" for more.
+`,
 	Action: func(c *cli.Context) error {
 		app := internal.ValidateApp(c)
 
-		if c.Args().Get(1) != "" && backupAllServices {
+		recipe, err := recipePkg.Get(app.Recipe, internal.Offline)
-			internal.ShowSubcommandHelpAndError(c, errors.New("cannot use '<service>' and '--all' together"))
-		}
-
-		abraSh := path.Join(config.ABRA_DIR, "apps", app.Type, "abra.sh")
-		if _, err := os.Stat(abraSh); err != nil {
-			if os.IsNotExist(err) {
-				logrus.Fatalf("'%s' does not exist?", abraSh)
-			}
-			logrus.Fatal(err)
-		}
-
-		sourceCmd := fmt.Sprintf("source %s", abraSh)
-
-		execCmd := "abra_backup"
-		if !backupAllServices {
-			serviceName := c.Args().Get(1)
-			if serviceName == "" {
-				internal.ShowSubcommandHelpAndError(c, errors.New("no service(s) target provided"))
-			}
-			execCmd = fmt.Sprintf("abra_backup_%s", serviceName)
-		}
-
-		bytes, err := ioutil.ReadFile(abraSh)
 		if err != nil {
 			logrus.Fatal(err)
 		}
-		if !strings.Contains(string(bytes), execCmd) {
+
-			logrus.Fatalf("%s doesn't have a '%s' function", app.Type, execCmd)
+		if !internal.Chaos {
+			if err := recipePkg.EnsureIsClean(app.Recipe); err != nil {
+				logrus.Fatal(err)
 			}
 
-		sourceAndExec := fmt.Sprintf("%s; %s", sourceCmd, execCmd)
+			if !internal.Offline {
-		cmd := exec.Command("bash", "-c", sourceAndExec)
+				if err := recipePkg.EnsureUpToDate(app.Recipe); err != nil {
-		if err := internal.RunCmd(cmd); err != nil {
 					logrus.Fatal(err)
 				}
+			}
+
+			if err := recipePkg.EnsureLatest(app.Recipe); err != nil {
+				logrus.Fatal(err)
+			}
+		}
+
+		backupConfigs := make(map[string]backupConfig)
+		for _, service := range recipe.Config.Services {
+			if backupsEnabled, ok := service.Deploy.Labels["backupbot.backup"]; ok {
+				if backupsEnabled == "true" {
+					fullServiceName := fmt.Sprintf("%s_%s", app.StackName(), service.Name)
+					bkConfig := backupConfig{}
+
+					logrus.Debugf("backup config detected for %s", fullServiceName)
+
+					if paths, ok := service.Deploy.Labels["backupbot.backup.path"]; ok {
+						logrus.Debugf("detected backup paths for %s: %s", fullServiceName, paths)
+						bkConfig.backupPaths = strings.Split(paths, ",")
+					}
+
+					if preHookCmd, ok := service.Deploy.Labels["backupbot.backup.pre-hook"]; ok {
+						logrus.Debugf("detected pre-hook command for %s: %s", fullServiceName, preHookCmd)
+						bkConfig.preHookCmd = preHookCmd
+					}
+
+					if postHookCmd, ok := service.Deploy.Labels["backupbot.backup.post-hook"]; ok {
+						logrus.Debugf("detected post-hook command for %s: %s", fullServiceName, postHookCmd)
+						bkConfig.postHookCmd = postHookCmd
+					}
+
+					backupConfigs[service.Name] = bkConfig
+				}
+			}
+		}
+
+		cl, err := client.New(app.Server)
+		if err != nil {
+			logrus.Fatal(err)
+		}
+
+		serviceName := c.Args().Get(1)
+		if serviceName != "" {
+			backupConfig, ok := backupConfigs[serviceName]
+			if !ok {
+				logrus.Fatalf("no backup config for %s? does %s exist?", serviceName, serviceName)
+			}
+
+			logrus.Infof("running backup for the %s service", serviceName)
+
+			if err := runBackup(cl, app, serviceName, backupConfig); err != nil {
+				logrus.Fatal(err)
+			}
+		} else {
+			if len(backupConfigs) == 0 {
+				logrus.Fatalf("no backup configs discovered for %s?", app.Name)
+			}
+
+			for serviceName, backupConfig := range backupConfigs {
+				logrus.Infof("running backup for the %s service", serviceName)
+
+				if err := runBackup(cl, app, serviceName, backupConfig); err != nil {
+					logrus.Fatal(err)
+				}
+			}
+		}
 
 		return nil
 	},
-	BashComplete: func(c *cli.Context) {
-		appNames, err := config.GetAppNames()
-		if err != nil {
-			logrus.Warn(err)
 }
-		if c.NArg() > 0 {
+
+// TimeStamp generates a file name friendly timestamp.
+func TimeStamp() string {
+	ts := time.Now().UTC().Format(time.RFC3339)
+	return strings.Replace(ts, ":", "-", -1)
+}
+
+// runBackup does the actual backup logic.
+func runBackup(cl *dockerClient.Client, app config.App, serviceName string, bkConfig backupConfig) error {
+	if len(bkConfig.backupPaths) == 0 {
+		return fmt.Errorf("backup paths are empty for %s?", serviceName)
+	}
+
+	// FIXME: avoid instantiating a new CLI
+	dcli, err := command.NewDockerCli()
+	if err != nil {
+		return err
+	}
+
+	filters := filters.NewArgs()
+	filters.Add("name", fmt.Sprintf("^%s_%s", app.StackName(), serviceName))
+
+	targetContainer, err := containerPkg.GetContainer(context.Background(), cl, filters, true)
+	if err != nil {
+		return err
+	}
+
+	fullServiceName := fmt.Sprintf("%s_%s", app.StackName(), serviceName)
+	if bkConfig.preHookCmd != "" {
+		splitCmd := internal.SafeSplit(bkConfig.preHookCmd)
+
+		logrus.Debugf("split pre-hook command for %s into %s", fullServiceName, splitCmd)
+
+		preHookExecOpts := types.ExecConfig{
+			AttachStderr: true,
+			AttachStdin:  true,
+			AttachStdout: true,
+			Cmd:          splitCmd,
+			Detach:       false,
+			Tty:          true,
+		}
+
+		if err := container.RunExec(dcli, cl, targetContainer.ID, &preHookExecOpts); err != nil {
+			return fmt.Errorf("failed to run %s on %s: %s", bkConfig.preHookCmd, targetContainer.ID, err.Error())
+		}
+
+		logrus.Infof("succesfully ran %s pre-hook command: %s", fullServiceName, bkConfig.preHookCmd)
+	}
+
+	var tempBackupPaths []string
+	for _, remoteBackupPath := range bkConfig.backupPaths {
+		sanitisedPath := strings.ReplaceAll(remoteBackupPath, "/", "_")
+		localBackupPath := filepath.Join(config.BACKUP_DIR, fmt.Sprintf("%s%s_%s.tar.gz", fullServiceName, sanitisedPath, TimeStamp()))
+		logrus.Debugf("temporarily backing up %s:%s to %s", fullServiceName, remoteBackupPath, localBackupPath)
+
+		logrus.Infof("backing up %s:%s", fullServiceName, remoteBackupPath)
+
+		content, _, err := cl.CopyFromContainer(context.Background(), targetContainer.ID, remoteBackupPath)
+		if err != nil {
+			logrus.Debugf("failed to copy %s from container: %s", remoteBackupPath, err.Error())
+			if err := cleanupTempArchives(tempBackupPaths); err != nil {
+				return fmt.Errorf("failed to clean up temporary archives: %s", err.Error())
+			}
+			return fmt.Errorf("failed to copy %s from container: %s", remoteBackupPath, err.Error())
+		}
+		defer content.Close()
+
+		_, srcBase := archive.SplitPathDirEntry(remoteBackupPath)
+		preArchive := archive.RebaseArchiveEntries(content, srcBase, remoteBackupPath)
+		if err := copyToFile(localBackupPath, preArchive); err != nil {
+			logrus.Debugf("failed to create tar archive (%s): %s", localBackupPath, err.Error())
+			if err := cleanupTempArchives(tempBackupPaths); err != nil {
+				return fmt.Errorf("failed to clean up temporary archives: %s", err.Error())
+			}
+			return fmt.Errorf("failed to create tar archive (%s): %s", localBackupPath, err.Error())
+		}
+
+		tempBackupPaths = append(tempBackupPaths, localBackupPath)
+	}
+
+	logrus.Infof("compressing and merging archives...")
+
+	if err := mergeArchives(tempBackupPaths, fullServiceName); err != nil {
+		logrus.Debugf("failed to merge archive files: %s", err.Error())
+		if err := cleanupTempArchives(tempBackupPaths); err != nil {
+			return fmt.Errorf("failed to clean up temporary archives: %s", err.Error())
+		}
+		return fmt.Errorf("failed to merge archive files: %s", err.Error())
+	}
+
+	if err := cleanupTempArchives(tempBackupPaths); err != nil {
+		return fmt.Errorf("failed to clean up temporary archives: %s", err.Error())
+	}
+
+	if bkConfig.postHookCmd != "" {
+		splitCmd := internal.SafeSplit(bkConfig.postHookCmd)
+
+		logrus.Debugf("split post-hook command for %s into %s", fullServiceName, splitCmd)
+
+		postHookExecOpts := types.ExecConfig{
+			AttachStderr: true,
+			AttachStdin:  true,
+			AttachStdout: true,
+			Cmd:          splitCmd,
+			Detach:       false,
+			Tty:          true,
+		}
+
+		if err := container.RunExec(dcli, cl, targetContainer.ID, &postHookExecOpts); err != nil {
+			return err
+		}
+
+		logrus.Infof("succesfully ran %s post-hook command: %s", fullServiceName, bkConfig.postHookCmd)
+	}
+
+	return nil
+}
+
+func copyToFile(outfile string, r io.Reader) error {
+	tmpFile, err := os.CreateTemp(filepath.Dir(outfile), ".tar_temp")
+	if err != nil {
+		return err
+	}
+
+	tmpPath := tmpFile.Name()
+
+	_, err = io.Copy(tmpFile, r)
+	tmpFile.Close()
+
+	if err != nil {
+		os.Remove(tmpPath)
+		return err
+	}
+
+	if err = os.Rename(tmpPath, outfile); err != nil {
+		os.Remove(tmpPath)
+		return err
+	}
+
+	return nil
+}
+
+func cleanupTempArchives(tarPaths []string) error {
+	for _, tarPath := range tarPaths {
+		if err := os.RemoveAll(tarPath); err != nil {
+			return err
+		}
+
+		logrus.Debugf("remove temporary archive file %s", tarPath)
+	}
+
+	return nil
+}
+
+func mergeArchives(tarPaths []string, serviceName string) error {
+	var out io.Writer
+	var cout *pgzip.Writer
+
+	localBackupPath := filepath.Join(config.BACKUP_DIR, fmt.Sprintf("%s_%s.tar.gz", serviceName, TimeStamp()))
+
+	fout, err := os.Create(localBackupPath)
+	if err != nil {
+		return fmt.Errorf("Failed to open %s: %s", localBackupPath, err)
+	}
+
+	defer fout.Close()
+	out = fout
+
+	cout = pgzip.NewWriter(out)
+	out = cout
+
+	tw := tar.NewWriter(out)
+
+	for _, tarPath := range tarPaths {
+		if err := addTar(tw, tarPath); err != nil {
+			return fmt.Errorf("failed to merge %s: %v", tarPath, err)
+		}
+	}
+
+	if err := tw.Close(); err != nil {
+		return fmt.Errorf("failed to close tar writer %v", err)
+	}
+
+	if cout != nil {
+		if err := cout.Flush(); err != nil {
+			return fmt.Errorf("failed to flush: %s", err)
+		} else if err = cout.Close(); err != nil {
+			return fmt.Errorf("failed to close compressed writer: %s", err)
+		}
+	}
+
+	logrus.Infof("backed up %s to %s", serviceName, localBackupPath)
+
+	return nil
+}
+
+func addTar(tw *tar.Writer, pth string) (err error) {
+	var tr *tar.Reader
+	var rc io.ReadCloser
+	var hdr *tar.Header
+
+	if tr, rc, err = openTarFile(pth); err != nil {
 		return
 	}
-		for _, a := range appNames {
+
-			fmt.Println(a)
+	for {
+		if hdr, err = tr.Next(); err != nil {
+			if err == io.EOF {
+				err = nil
 			}
-	},
+			break
+		}
+		if err = tw.WriteHeader(hdr); err != nil {
+			break
+		} else if _, err = io.Copy(tw, tr); err != nil {
+			break
+		}
+	}
+	if err == nil {
+		err = rc.Close()
+	} else {
+		rc.Close()
+	}
+	return
+}
+
+func openTarFile(pth string) (tr *tar.Reader, rc io.ReadCloser, err error) {
+	var fin *os.File
+	var n int
+	buff := make([]byte, 1024)
+
+	if fin, err = os.Open(pth); err != nil {
+		return
+	}
+
+	if n, err = fin.Read(buff); err != nil {
+		fin.Close()
+		return
+	} else if n == 0 {
+		fin.Close()
+		err = fmt.Errorf("%s is empty", pth)
+		return
+	}
+
+	if _, err = fin.Seek(0, 0); err != nil {
+		fin.Close()
+		return
+	}
+
+	rc = fin
+	tr = tar.NewReader(rc)
+
+	return tr, rc, nil
 }

cli/app/check.go

@@ -1,64 +1,81 @@
 package app
 
 import (
-	"fmt"
-	"os"
-	"path"
-	"strings"
-
 	"coopcloud.tech/abra/cli/internal"
+	"coopcloud.tech/abra/pkg/autocomplete"
 	"coopcloud.tech/abra/pkg/config"
+	"coopcloud.tech/abra/pkg/formatter"
+	"coopcloud.tech/abra/pkg/recipe"
+	recipePkg "coopcloud.tech/abra/pkg/recipe"
 	"github.com/sirupsen/logrus"
-	"github.com/urfave/cli/v2"
+	"github.com/urfave/cli"
 )
 
-var appCheckCommand = &cli.Command{
+var appCheckCommand = cli.Command{
 	Name:    "check",
-	Usage:     "Check if app is configured correctly",
+	Aliases: []string{"chk"},
-	Aliases:   []string{"c"},
+	Usage:   "Ensure an app is well configured",
-	ArgsUsage: "<service>",
+	Description: `
+This command compares 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.`,
+	ArgsUsage: "<domain>",
+	Flags: []cli.Flag{
+		internal.DebugFlag,
+		internal.ChaosFlag,
+		internal.OfflineFlag,
+	},
+	Before:       internal.SubCommandBefore,
+	BashComplete: autocomplete.AppNameComplete,
 	Action: func(c *cli.Context) error {
 		app := internal.ValidateApp(c)
 
-		envSamplePath := path.Join(config.ABRA_DIR, "apps", app.Type, ".env.sample")
+		if err := recipe.EnsureExists(app.Recipe); err != nil {
-		if _, err := os.Stat(envSamplePath); err != nil {
-			if os.IsNotExist(err) {
-				logrus.Fatalf("'%s' does not exist?", envSamplePath)
-			}
 			logrus.Fatal(err)
 		}
 
-		envSample, err := config.ReadEnv(envSamplePath)
+		if !internal.Chaos {
+			if err := recipePkg.EnsureIsClean(app.Recipe); err != nil {
+				logrus.Fatal(err)
+			}
+
+			if !internal.Offline {
+				if err := recipePkg.EnsureUpToDate(app.Recipe); err != nil {
+					logrus.Fatal(err)
+				}
+			}
+
+			if err := recipePkg.EnsureLatest(app.Recipe); err != nil {
+				logrus.Fatal(err)
+			}
+		}
+
+		tableCol := []string{"recipe env sample", "app env"}
+		table := formatter.CreateTable(tableCol)
+
+		envVars, err := config.CheckEnv(app)
 		if err != nil {
 			logrus.Fatal(err)
 		}
 
-		var missing []string
+		for _, envVar := range envVars {
-		for k := range envSample {
+			if envVar.Present {
-			if _, ok := app.Env[k]; !ok {
+				table.Append([]string{envVar.Name, "✅"})
-				missing = append(missing, k)
+			} else {
+				table.Append([]string{envVar.Name, "❌"})
 			}
 		}
 
-		if len(missing) > 0 {
+		table.Render()
-			missingEnvVars := strings.Join(missing, ", ")
-			logrus.Fatalf("%s is missing %s", app.Path, missingEnvVars)
-		}
-
-		logrus.Infof("all necessary environment variables defined for '%s'", app.Name)
 
 		return nil
 	},
-	BashComplete: func(c *cli.Context) {
-		appNames, err := config.GetAppNames()
-		if err != nil {
-			logrus.Warn(err)
-		}
-		if c.NArg() > 0 {
-			return
-		}
-		for _, a := range appNames {
-			fmt.Println(a)
-		}
-	},
 }

cli/app/cmd.go

@@ -0,0 +1,273 @@
+package app
+
+import (
+	"errors"
+	"fmt"
+	"os"
+	"os/exec"
+	"path"
+	"sort"
+	"strings"
+
+	"coopcloud.tech/abra/cli/internal"
+	"coopcloud.tech/abra/pkg/app"
+	"coopcloud.tech/abra/pkg/autocomplete"
+	"coopcloud.tech/abra/pkg/client"
+	"coopcloud.tech/abra/pkg/config"
+	"coopcloud.tech/abra/pkg/recipe"
+	recipePkg "coopcloud.tech/abra/pkg/recipe"
+	"github.com/sirupsen/logrus"
+	"github.com/urfave/cli"
+)
+
+var appCmdCommand = cli.Command{
+	Name:    "command",
+	Aliases: []string{"cmd"},
+	Usage:   "Run app commands",
+	Description: `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". Arguments can be passed into these functions
+using the "-- <args>" syntax.
+
+Example:
+
+  abra app cmd example.com app create_user -- me@example.com
+`,
+	ArgsUsage: "<domain> [<service>] <command> [-- <args>]",
+	Flags: []cli.Flag{
+		internal.DebugFlag,
+		internal.LocalCmdFlag,
+		internal.RemoteUserFlag,
+		internal.TtyFlag,
+		internal.OfflineFlag,
+		internal.ChaosFlag,
+	},
+	Before:      internal.SubCommandBefore,
+	Subcommands: []cli.Command{appCmdListCommand},
+	BashComplete: func(ctx *cli.Context) {
+		args := ctx.Args()
+		switch len(args) {
+		case 0:
+			autocomplete.AppNameComplete(ctx)
+		case 1:
+			autocomplete.ServiceNameComplete(args.Get(0))
+		case 2:
+			cmdNameComplete(args.Get(0))
+		}
+	},
+	Action: func(c *cli.Context) error {
+		app := internal.ValidateApp(c)
+
+		if err := recipe.EnsureExists(app.Recipe); err != nil {
+			logrus.Fatal(err)
+		}
+
+		if !internal.Chaos {
+			if err := recipePkg.EnsureIsClean(app.Recipe); err != nil {
+				logrus.Fatal(err)
+			}
+
+			if !internal.Offline {
+				if err := recipePkg.EnsureUpToDate(app.Recipe); err != nil {
+					logrus.Fatal(err)
+				}
+			}
+
+			if err := recipePkg.EnsureLatest(app.Recipe); err != nil {
+				logrus.Fatal(err)
+			}
+		}
+
+		if internal.LocalCmd && internal.RemoteUser != "" {
+			internal.ShowSubcommandHelpAndError(c, errors.New("cannot use --local & --user together"))
+		}
+
+		hasCmdArgs, parsedCmdArgs := parseCmdArgs(c.Args(), internal.LocalCmd)
+
+		abraSh := path.Join(config.RECIPES_DIR, app.Recipe, "abra.sh")
+		if _, err := os.Stat(abraSh); err != nil {
+			if os.IsNotExist(err) {
+				logrus.Fatalf("%s does not exist for %s?", abraSh, app.Name)
+			}
+			logrus.Fatal(err)
+		}
+
+		if internal.LocalCmd {
+			if !(len(c.Args()) >= 2) {
+				internal.ShowSubcommandHelpAndError(c, errors.New("missing arguments"))
+			}
+
+			cmdName := c.Args().Get(1)
+			if err := internal.EnsureCommand(abraSh, app.Recipe, cmdName); err != nil {
+				logrus.Fatal(err)
+			}
+
+			logrus.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 {
+				logrus.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, abraSh, cmdName, parsedCmdArgs)
+			} else {
+				logrus.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, abraSh, cmdName)
+			}
+
+			shell := "/bin/bash"
+			if _, err := os.Stat(shell); errors.Is(err, os.ErrNotExist) {
+				logrus.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 {
+				logrus.Fatal(err)
+			}
+		} else {
+			if !(len(c.Args()) >= 3) {
+				internal.ShowSubcommandHelpAndError(c, errors.New("missing arguments"))
+			}
+
+			targetServiceName := c.Args().Get(1)
+
+			cmdName := c.Args().Get(2)
+			if err := internal.EnsureCommand(abraSh, app.Recipe, cmdName); err != nil {
+				logrus.Fatal(err)
+			}
+
+			serviceNames, err := config.GetAppServiceNames(app.Name)
+			if err != nil {
+				logrus.Fatal(err)
+			}
+
+			matchingServiceName := false
+			for _, serviceName := range serviceNames {
+				if serviceName == targetServiceName {
+					matchingServiceName = true
+				}
+			}
+
+			if !matchingServiceName {
+				logrus.Fatalf("no service %s for %s?", targetServiceName, app.Name)
+			}
+
+			logrus.Debugf("running command %s within the context of %s_%s", cmdName, app.StackName(), targetServiceName)
+
+			if hasCmdArgs {
+				logrus.Debugf("parsed following command arguments: %s", parsedCmdArgs)
+			} else {
+				logrus.Debug("did not detect any command arguments")
+			}
+
+			cl, err := client.New(app.Server)
+			if err != nil {
+				logrus.Fatal(err)
+			}
+
+			if err := internal.RunCmdRemote(cl, app, abraSh, targetServiceName, cmdName, parsedCmdArgs); err != nil {
+				logrus.Fatal(err)
+			}
+		}
+
+		return nil
+	},
+}
+
+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
+}
+
+func cmdNameComplete(appName string) {
+	app, err := app.Get(appName)
+	if err != nil {
+		return
+	}
+	cmdNames, _ := getShCmdNames(app)
+	if err != nil {
+		return
+	}
+	for _, n := range cmdNames {
+		fmt.Println(n)
+	}
+}
+
+var appCmdListCommand = cli.Command{
+	Name:      "list",
+	Aliases:   []string{"ls"},
+	Usage:     "List all available commands",
+	ArgsUsage: "<domain>",
+	Flags: []cli.Flag{
+		internal.DebugFlag,
+		internal.OfflineFlag,
+		internal.ChaosFlag,
+	},
+	BashComplete: autocomplete.AppNameComplete,
+	Before:       internal.SubCommandBefore,
+	Action: func(c *cli.Context) error {
+		app := internal.ValidateApp(c)
+
+		if err := recipe.EnsureExists(app.Recipe); err != nil {
+			logrus.Fatal(err)
+		}
+
+		if !internal.Chaos {
+			if err := recipePkg.EnsureIsClean(app.Recipe); err != nil {
+				logrus.Fatal(err)
+			}
+
+			if !internal.Offline {
+				if err := recipePkg.EnsureUpToDate(app.Recipe); err != nil {
+					logrus.Fatal(err)
+				}
+			}
+
+			if err := recipePkg.EnsureLatest(app.Recipe); err != nil {
+				logrus.Fatal(err)
+			}
+		}
+
+		cmdNames, err := getShCmdNames(app)
+		if err != nil {
+			logrus.Fatal(err)
+		}
+
+		for _, cmdName := range cmdNames {
+			fmt.Println(cmdName)
+		}
+
+		return nil
+	},
+}
+
+func getShCmdNames(app config.App) ([]string, error) {
+	abraShPath := fmt.Sprintf("%s/%s/%s", config.RECIPES_DIR, app.Recipe, "abra.sh")
+	cmdNames, err := config.ReadAbraShCmdNames(abraShPath)
+	if err != nil {
+		return nil, err
+	}
+
+	sort.Strings(cmdNames)
+	return cmdNames, nil
+}

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/coop-cloud/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

@@ -1,23 +1,44 @@
 package app
 
 import (
-	"fmt"
+	"errors"
 	"os"
 	"os/exec"
 
 	"coopcloud.tech/abra/cli/internal"
+	"coopcloud.tech/abra/pkg/autocomplete"
 	"coopcloud.tech/abra/pkg/config"
 	"github.com/AlecAivazis/survey/v2"
 	"github.com/sirupsen/logrus"
-	"github.com/urfave/cli/v2"
+	"github.com/urfave/cli"
 )
 
-var appConfigCommand = &cli.Command{
+var appConfigCommand = cli.Command{
 	Name:      "config",
-	Aliases: []string{"c"},
+	Aliases:   []string{"cfg"},
 	Usage:     "Edit app config",
+	ArgsUsage: "<domain>",
+	Flags: []cli.Flag{
+		internal.DebugFlag,
+	},
+	Before:       internal.SubCommandBefore,
+	BashComplete: autocomplete.AppNameComplete,
 	Action: func(c *cli.Context) error {
-		app := internal.ValidateApp(c)
+		appName := c.Args().First()
+
+		if appName == "" {
+			internal.ShowSubcommandHelpAndError(c, errors.New("no app provided"))
+		}
+
+		files, err := config.LoadAppFiles("")
+		if err != nil {
+			logrus.Fatal(err)
+		}
+
+		appFile, exists := files[appName]
+		if !exists {
+			logrus.Fatalf("cannot find app with name %s", appName)
+		}
 
 		ed, ok := os.LookupEnv("EDITOR")
 		if !ok {
@@ -30,7 +51,7 @@ var appConfigCommand = &cli.Command{
 			}
 		}
 
-		cmd := exec.Command(ed, app.Path)
+		cmd := exec.Command(ed, appFile.Path)
 		cmd.Stdin = os.Stdin
 		cmd.Stdout = os.Stdout
 		cmd.Stderr = os.Stderr
@@ -40,16 +61,4 @@ var appConfigCommand = &cli.Command{
 
 		return nil
 	},
-	BashComplete: func(c *cli.Context) {
-		appNames, err := config.GetAppNames()
-		if err != nil {
-			logrus.Warn(err)
-		}
-		if c.NArg() > 0 {
-			return
-		}
-		for _, a := range appNames {
-			fmt.Println(a)
-		}
-	},
 }

cli/app/cp.go

@@ -1,26 +1,47 @@
 package app
 
 import (
+	"context"
 	"fmt"
 	"os"
 	"strings"
 
-	"coopcloud.tech/abra/cli/formatter"
 	"coopcloud.tech/abra/cli/internal"
+	"coopcloud.tech/abra/pkg/autocomplete"
 	"coopcloud.tech/abra/pkg/client"
 	"coopcloud.tech/abra/pkg/config"
+	"coopcloud.tech/abra/pkg/container"
+	"coopcloud.tech/abra/pkg/formatter"
 	"github.com/docker/docker/api/types"
 	"github.com/docker/docker/api/types/filters"
+	dockerClient "github.com/docker/docker/client"
 	"github.com/docker/docker/pkg/archive"
 	"github.com/sirupsen/logrus"
-	"github.com/urfave/cli/v2"
+	"github.com/urfave/cli"
 )
 
-var appCpCommand = &cli.Command{
+var appCpCommand = cli.Command{
 	Name:      "cp",
 	Aliases:   []string{"c"},
-	ArgsUsage: "<src> <dst>",
+	ArgsUsage: "<domain> <src> <dst>",
-	Usage:     "Copy files to/from a running app service",
+	Flags: []cli.Flag{
+		internal.DebugFlag,
+		internal.NoInputFlag,
+	},
+	Before: internal.SubCommandBefore,
+	Usage:  "Copy files to/from a deployed app service",
+	Description: `
+Copy files to and from any app service file system.
+
+If you want to copy a myfile.txt to the root of the app service:
+
+    abra app cp <domain> myfile.txt app:/
+
+And if you want to copy that file back to your current working directory locally:
+
+    abra app cp <domain> app:/myfile.txt .
+`,
+	BashComplete: autocomplete.AppNameComplete,
 	Action: func(c *cli.Context) error {
 		app := internal.ValidateApp(c)
 
@@ -64,14 +85,10 @@ var appCpCommand = &cli.Command{
 			logrus.Debugf("assuming transfer is going TO the container")
 		}
 
-		appFiles, err := config.LoadAppFiles("")
+		if isToContainer {
-		if err != nil {
+			if _, err := os.Stat(srcPath); os.IsNotExist(err) {
-			logrus.Fatal(err)
+				logrus.Fatalf("%s does not exist locally?", srcPath)
 			}
-
-		appEnv, err := config.GetApp(appFiles, app.Name)
-		if err != nil {
-			logrus.Fatal(err)
 		}
 
 		cl, err := client.New(app.Server)
@@ -79,25 +96,33 @@ var appCpCommand = &cli.Command{
 			logrus.Fatal(err)
 		}
 
+		if err := configureAndCp(c, cl, app, srcPath, dstPath, service, isToContainer); err != nil {
+			logrus.Fatal(err)
+		}
+
+		return nil
+	},
+}
+
+func configureAndCp(
+	c *cli.Context,
+	cl *dockerClient.Client,
+	app config.App,
+	srcPath string,
+	dstPath string,
+	service string,
+	isToContainer bool) error {
 	filters := filters.NewArgs()
-		filters.Add("name", fmt.Sprintf("%s_%s", appEnv.StackName(), service))
+	filters.Add("name", fmt.Sprintf("^%s_%s", app.StackName(), service))
-		containers, err := cl.ContainerList(c.Context, types.ContainerListOptions{Filters: filters})
+
+	container, err := container.GetContainer(context.Background(), cl, filters, internal.NoInput)
 	if err != nil {
 		logrus.Fatal(err)
 	}
 
-		if len(containers) != 1 {
+	logrus.Debugf("retrieved %s as target container on %s", formatter.ShortenID(container.ID), app.Server)
-			logrus.Fatalf("expected 1 container but got %v", len(containers))
-		}
-		container := containers[0]
-
-		logrus.Debugf("retrieved '%s' as target container on '%s'", formatter.ShortenID(container.ID), app.Server)
 
 	if isToContainer {
-			if _, err := os.Stat(srcPath); err != nil {
-				logrus.Fatalf("'%s' does not exist?", srcPath)
-			}
-
 		toTarOpts := &archive.TarOptions{NoOverwriteDirNonDir: true, Compression: archive.Gzip}
 		content, err := archive.TarWithOptions(srcPath, toTarOpts)
 		if err != nil {
@@ -105,11 +130,11 @@ var appCpCommand = &cli.Command{
 		}
 
 		copyOpts := types.CopyToContainerOptions{AllowOverwriteDirWithFile: false, CopyUIDGID: false}
-			if err := cl.CopyToContainer(c.Context, container.ID, dstPath, content, copyOpts); err != nil {
+		if err := cl.CopyToContainer(context.Background(), container.ID, dstPath, content, copyOpts); err != nil {
 			logrus.Fatal(err)
 		}
 	} else {
-			content, _, err := cl.CopyFromContainer(c.Context, container.ID, srcPath)
+		content, _, err := cl.CopyFromContainer(context.Background(), container.ID, srcPath)
 		if err != nil {
 			logrus.Fatal(err)
 		}
@@ -119,6 +144,6 @@ var appCpCommand = &cli.Command{
 			logrus.Fatal(err)
 		}
 	}
+
 	return nil
-	},
 }

cli/app/deploy.go

@@ -1,29 +1,179 @@
 package app
 
 import (
+	"context"
 	"fmt"
 
 	"coopcloud.tech/abra/cli/internal"
+	"coopcloud.tech/abra/pkg/autocomplete"
+	"coopcloud.tech/abra/pkg/secret"
+
 	"coopcloud.tech/abra/pkg/client"
-	stack "coopcloud.tech/abra/pkg/client/stack"
 	"coopcloud.tech/abra/pkg/config"
+	"coopcloud.tech/abra/pkg/dns"
+	"coopcloud.tech/abra/pkg/formatter"
+	"coopcloud.tech/abra/pkg/git"
+	"coopcloud.tech/abra/pkg/lint"
+	"coopcloud.tech/abra/pkg/recipe"
+	"coopcloud.tech/abra/pkg/upstream/stack"
 	"github.com/sirupsen/logrus"
-	"github.com/urfave/cli/v2"
+	"github.com/urfave/cli"
 )
 
-var appDeployCommand = &cli.Command{
+var appDeployCommand = cli.Command{
 	Name:      "deploy",
 	Aliases:   []string{"d"},
 	Usage:     "Deploy an app",
+	ArgsUsage: "<domain> [<version>]",
+	Flags: []cli.Flag{
+		internal.DebugFlag,
+		internal.NoInputFlag,
+		internal.ForceFlag,
+		internal.ChaosFlag,
+		internal.NoDomainChecksFlag,
+		internal.DontWaitConvergeFlag,
+		internal.OfflineFlag,
+	},
+	Before: internal.SubCommandBefore,
+	Description: `
+Deploy an app. It does not support incrementing the version of a deployed app,
+for this you need to look at the "abra app upgrade <domain>" command.
+
+You may pass "--force" to re-deploy the same version again. This can be useful
+if the container runtime has gotten into a weird state.
+
+Chaos mode ("--chaos") will deploy your local checkout of a recipe as-is,
+including unstaged changes and can be useful for live hacking and testing new
+recipes.
+`,
+	BashComplete: autocomplete.AppNameComplete,
 	Action: func(c *cli.Context) error {
 		app := internal.ValidateApp(c)
+		stackName := app.StackName()
+
+		specificVersion := c.Args().Get(1)
+		if specificVersion != "" && internal.Chaos {
+			logrus.Fatal("cannot use <version> and --chaos together")
+		}
+
+		if err := recipe.EnsureExists(app.Recipe); err != nil {
+			logrus.Fatal(err)
+		}
+
+		if !internal.Chaos {
+			if err := recipe.EnsureIsClean(app.Recipe); err != nil {
+				logrus.Fatal(err)
+			}
+
+			if !internal.Offline {
+				if err := recipe.EnsureUpToDate(app.Recipe); err != nil {
+					logrus.Fatal(err)
+				}
+			}
+
+			if err := recipe.EnsureLatest(app.Recipe); err != nil {
+				logrus.Fatal(err)
+			}
+		}
+
+		r, err := recipe.Get(app.Recipe, internal.Offline)
+		if err != nil {
+			logrus.Fatal(err)
+		}
+
+		if err := lint.LintForErrors(r); err != nil {
+			logrus.Fatal(err)
+		}
+
+		logrus.Debugf("checking whether %s is already deployed", stackName)
 
 		cl, err := client.New(app.Server)
 		if err != nil {
 			logrus.Fatal(err)
 		}
 
-		abraShPath := fmt.Sprintf("%s/%s/%s", config.APPS_DIR, app.Type, "abra.sh")
+		isDeployed, deployedVersion, err := stack.IsDeployed(context.Background(), cl, stackName)
+		if err != nil {
+			logrus.Fatal(err)
+		}
+
+		secStats, err := secret.PollSecretsStatus(cl, app)
+		if err != nil {
+			logrus.Fatal(err)
+		}
+
+		for _, secStat := range secStats {
+			if !secStat.CreatedOnRemote {
+				logrus.Fatalf("unable to deploy, secrets not generated (%s)?", secStat.LocalName)
+			}
+		}
+
+		if isDeployed {
+			if internal.Force || internal.Chaos {
+				logrus.Warnf("%s is already deployed but continuing (--force/--chaos)", app.Name)
+			} else {
+				logrus.Fatalf("%s is already deployed", app.Name)
+			}
+		}
+
+		version := deployedVersion
+		if specificVersion != "" {
+			version = specificVersion
+			logrus.Debugf("choosing %s as version to deploy", version)
+			if err := recipe.EnsureVersion(app.Recipe, version); err != nil {
+				logrus.Fatal(err)
+			}
+		}
+
+		if !internal.Chaos && specificVersion == "" {
+			catl, err := recipe.ReadRecipeCatalogue(internal.Offline)
+			if err != nil {
+				logrus.Fatal(err)
+			}
+			versions, err := recipe.GetRecipeCatalogueVersions(app.Recipe, catl)
+			if err != nil {
+				logrus.Fatal(err)
+			}
+
+			if len(versions) == 0 && !internal.Chaos {
+				logrus.Warn("no published versions in catalogue, trying local recipe repository")
+				recipeVersions, err := recipe.GetRecipeVersions(app.Recipe, internal.Offline)
+				if err != nil {
+					logrus.Warn(err)
+				}
+				for _, recipeVersion := range recipeVersions {
+					for version := range recipeVersion {
+						versions = append(versions, version)
+					}
+				}
+			}
+
+			if len(versions) > 0 && !internal.Chaos {
+				version = versions[len(versions)-1]
+				logrus.Debugf("choosing %s as version to deploy", version)
+				if err := recipe.EnsureVersion(app.Recipe, version); err != nil {
+					logrus.Fatal(err)
+				}
+			} else {
+				head, err := git.GetRecipeHead(app.Recipe)
+				if err != nil {
+					logrus.Fatal(err)
+				}
+				version = formatter.SmallSHA(head.String())
+				logrus.Warn("no versions detected, using latest commit")
+			}
+		}
+
+		if internal.Chaos {
+			logrus.Warnf("chaos mode engaged")
+			var err error
+			version, err = recipe.ChaosVersion(app.Recipe)
+			if err != nil {
+				logrus.Fatal(err)
+			}
+		}
+
+		abraShPath := fmt.Sprintf("%s/%s/%s", config.RECIPES_DIR, app.Recipe, "abra.sh")
 		abraShEnv, err := config.ReadAbraShEnvVars(abraShPath)
 		if err != nil {
 			logrus.Fatal(err)
@@ -32,13 +182,14 @@ var appDeployCommand = &cli.Command{
 			app.Env[k] = v
 		}
 
-		composeFiles, err := config.GetAppComposeFiles(app.Type, app.Env)
+		composeFiles, err := config.GetComposeFiles(app.Recipe, app.Env)
 		if err != nil {
 			logrus.Fatal(err)
 		}
+
 		deployOpts := stack.Deploy{
 			Composefiles: composeFiles,
-			Namespace:    app.StackName(),
+			Namespace:    stackName,
 			Prune:        false,
 			ResolveImage: stack.ResolveImageAlways,
 		}
@@ -47,22 +198,57 @@ var appDeployCommand = &cli.Command{
 			logrus.Fatal(err)
 		}
 
-		if err := stack.RunDeploy(cl, deployOpts, compose); err != nil {
+		config.ExposeAllEnv(stackName, compose, app.Env)
+		config.SetRecipeLabel(compose, stackName, app.Recipe)
+		config.SetChaosLabel(compose, stackName, internal.Chaos)
+		config.SetChaosVersionLabel(compose, stackName, version)
+		config.SetUpdateLabel(compose, stackName, app.Env)
+
+		envVars, err := config.CheckEnv(app)
+		if err != nil {
 			logrus.Fatal(err)
 		}
 
+		for _, envVar := range envVars {
+			if !envVar.Present {
+				logrus.Warnf("env var %s missing from %s.env, present in recipe .env.sample", envVar.Name, app.Domain)
+			}
+		}
+
+		if err := internal.DeployOverview(app, version, "continue with deployment?"); err != nil {
+			logrus.Fatal(err)
+		}
+
+		if !internal.NoDomainChecks {
+			domainName, ok := app.Env["DOMAIN"]
+			if ok {
+				if _, err = dns.EnsureDomainsResolveSameIPv4(domainName, app.Server); err != nil {
+					logrus.Fatal(err)
+				}
+			} else {
+				logrus.Warn("skipping domain checks as no DOMAIN=... configured for app")
+			}
+		} else {
+			logrus.Warn("skipping domain checks as requested")
+		}
+
+		stack.WaitTimeout, err = config.GetTimeoutFromLabel(compose, stackName)
+		if err != nil {
+			logrus.Fatal(err)
+		}
+		logrus.Debugf("set waiting timeout to %d s", stack.WaitTimeout)
+
+		if err := stack.RunDeploy(cl, deployOpts, compose, app.Name, internal.DontWaitConverge); err != nil {
+			logrus.Fatal(err)
+		}
+
+		postDeployCmds, ok := app.Env["POST_DEPLOY_CMDS"]
+		if ok && !internal.DontWaitConverge {
+			logrus.Debugf("run the following post-deploy commands: %s", postDeployCmds)
+			if err := internal.PostCmds(cl, app, postDeployCmds); err != nil {
+				logrus.Fatalf("attempting to run post deploy commands, saw: %s", err)
+			}
+		}
 		return nil
 	},
-	BashComplete: func(c *cli.Context) {
-		appNames, err := config.GetAppNames()
-		if err != nil {
-			logrus.Warn(err)
-		}
-		if c.NArg() > 0 {
-			return
-		}
-		for _, a := range appNames {
-			fmt.Println(a)
-		}
-	},
 }

cli/app/errors.go

@@ -0,0 +1,142 @@
+package app
+
+import (
+	"context"
+	"fmt"
+	"strconv"
+	"strings"
+	"time"
+
+	"coopcloud.tech/abra/cli/internal"
+	"coopcloud.tech/abra/pkg/autocomplete"
+	"coopcloud.tech/abra/pkg/client"
+	"coopcloud.tech/abra/pkg/config"
+	"coopcloud.tech/abra/pkg/recipe"
+	stack "coopcloud.tech/abra/pkg/upstream/stack"
+	"github.com/docker/docker/api/types"
+	"github.com/docker/docker/api/types/filters"
+	dockerClient "github.com/docker/docker/client"
+	"github.com/sirupsen/logrus"
+	"github.com/urfave/cli"
+)
+
+var appErrorsCommand = cli.Command{
+	Name:      "errors",
+	Usage:     "List errors for a deployed app",
+	ArgsUsage: "<domain>",
+	Description: `
+List errors for a deployed app.
+
+This is a best-effort implementation and an attempt to gather a number of tips
+& tricks for finding errors together into one convenient command. When an app
+is failing to deploy or having issues, it could be a lot of things.
+
+This command currently takes into account:
+
+    Is the service deployed?
+    Is the service killed by an OOM error?
+    Is the service reporting an error (like in "ps --no-trunc" output)
+    Is the service healthcheck failing? what are the healthcheck logs?
+
+Got any more ideas? Please let us know:
+
+    https://git.coopcloud.tech/coop-cloud/organising/issues/new/choose
+
+This command is best accompanied by "abra app logs <domain>" which may reveal
+further information which can help you debug the cause of an app failure via
+the logs.
+`,
+	Aliases: []string{"e"},
+	Flags: []cli.Flag{
+		internal.DebugFlag,
+		internal.WatchFlag,
+		internal.OfflineFlag,
+	},
+	Before:       internal.SubCommandBefore,
+	BashComplete: autocomplete.AppNameComplete,
+	Action: func(c *cli.Context) error {
+		app := internal.ValidateApp(c)
+
+		cl, err := client.New(app.Server)
+		if err != nil {
+			logrus.Fatal(err)
+		}
+
+		isDeployed, _, err := stack.IsDeployed(context.Background(), cl, app.StackName())
+		if err != nil {
+			logrus.Fatal(err)
+		}
+
+		if !isDeployed {
+			logrus.Fatalf("%s is not deployed?", app.Name)
+		}
+
+		if !internal.Watch {
+			if err := checkErrors(c, cl, app); err != nil {
+				logrus.Fatal(err)
+			}
+			return nil
+		}
+
+		for {
+			if err := checkErrors(c, cl, app); err != nil {
+				logrus.Fatal(err)
+			}
+			time.Sleep(2 * time.Second)
+		}
+	},
+}
+
+func checkErrors(c *cli.Context, cl *dockerClient.Client, app config.App) error {
+	recipe, err := recipe.Get(app.Recipe, internal.Offline)
+	if err != nil {
+		return err
+	}
+
+	for _, service := range recipe.Config.Services {
+		filters := filters.NewArgs()
+		filters.Add("name", fmt.Sprintf("^%s_%s", app.StackName(), service.Name))
+
+		containers, err := cl.ContainerList(context.Background(), types.ContainerListOptions{Filters: filters})
+		if err != nil {
+			return err
+		}
+
+		if len(containers) == 0 {
+			logrus.Warnf("%s is not up, something seems wrong", service.Name)
+			continue
+		}
+
+		container := containers[0]
+		containerState, err := cl.ContainerInspect(context.Background(), container.ID)
+		if err != nil {
+			logrus.Fatal(err)
+		}
+
+		if containerState.State.OOMKilled {
+			logrus.Warnf("%s has been killed due to an out of memory error", service.Name)
+		}
+
+		if containerState.State.Error != "" {
+			logrus.Warnf("%s reports this error: %s", service.Name, containerState.State.Error)
+		}
+
+		if containerState.State.Health != nil {
+			if containerState.State.Health.Status != "healthy" {
+				logrus.Warnf("%s healthcheck status is %s", service.Name, containerState.State.Health.Status)
+				logrus.Warnf("%s healthcheck has failed %s times", service.Name, strconv.Itoa(containerState.State.Health.FailingStreak))
+				for _, log := range containerState.State.Health.Log {
+					logrus.Warnf("%s healthcheck logs: %s", service.Name, strings.TrimSpace(log.Output))
+				}
+			}
+		}
+	}
+
+	return nil
+}
+
+func getServiceName(names []string) string {
+	containerName := strings.Join(names, " ")
+	trimmed := strings.TrimPrefix(containerName, "/")
+	return strings.Split(trimmed, ".")[0]
+}

cli/app/list.go

@@ -1,110 +1,183 @@
 package app
 
 import (
+	"encoding/json"
+	"fmt"
 	"sort"
+	"strconv"
 	"strings"
 
-	abraFormatter "coopcloud.tech/abra/cli/formatter"
+	"coopcloud.tech/abra/cli/internal"
-	"coopcloud.tech/abra/pkg/catalogue"
 	"coopcloud.tech/abra/pkg/config"
+	"coopcloud.tech/abra/pkg/formatter"
+	"coopcloud.tech/abra/pkg/recipe"
 	"coopcloud.tech/tagcmp"
 	"github.com/sirupsen/logrus"
-	"github.com/urfave/cli/v2"
+	"github.com/urfave/cli"
 )
 
 var status bool
 var statusFlag = &cli.BoolFlag{
-	Name:        "status",
+	Name:        "status, S",
-	Aliases:     []string{"S"},
-	Value:       false,
 	Usage:       "Show app deployment status",
 	Destination: &status,
 }
 
-var appType string
+var recipeFilter string
-var typeFlag = &cli.StringFlag{
+var recipeFlag = &cli.StringFlag{
-	Name:        "type",
+	Name:        "recipe, r",
-	Aliases:     []string{"t"},
 	Value:       "",
-	Usage:       "Show apps of a specific type",
+	Usage:       "Show apps of a specific recipe",
-	Destination: &appType,
+	Destination: &recipeFilter,
 }
 
 var listAppServer string
 var listAppServerFlag = &cli.StringFlag{
-	Name:        "server",
+	Name:        "server, s",
-	Aliases:     []string{"s"},
 	Value:       "",
 	Usage:       "Show apps of a specific server",
 	Destination: &listAppServer,
 }
 
-var appListCommand = &cli.Command{
+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 = cli.Command{
 	Name:    "list",
+	Aliases: []string{"ls"},
 	Usage:   "List all managed apps",
 	Description: `
-This command looks at your local file system listing of apps and servers (e.g.
+Read the local file system listing of apps and servers (e.g. ~/.abra/) to
-in ~/.abra/) to generate a report of all your apps.
+generate a report of all your apps.
 
 By passing the "--status/-S" flag, you can query all your servers for the
 actual live deployment status. Depending on how many servers you manage, this
 can take some time.
 `,
-	Aliases: []string{"ls"},
 	Flags: []cli.Flag{
+		internal.DebugFlag,
+		internal.MachineReadableFlag,
 		statusFlag,
 		listAppServerFlag,
-		typeFlag,
+		recipeFlag,
+		internal.OfflineFlag,
 	},
+	Before: internal.SubCommandBefore,
 	Action: func(c *cli.Context) error {
 		appFiles, err := config.LoadAppFiles(listAppServer)
 		if err != nil {
 			logrus.Fatal(err)
 		}
 
-		apps, err := config.GetApps(appFiles)
+		apps, err := config.GetApps(appFiles, recipeFilter)
 		if err != nil {
 			logrus.Fatal(err)
 		}
-		sort.Sort(config.ByServerAndType(apps))
+
+		sort.Sort(config.ByServerAndRecipe(apps))
 
 		statuses := make(map[string]map[string]string)
-		tableCol := []string{"Server", "Type", "Domain"}
+		var catl recipe.RecipeCatalogue
 		if status {
-			tableCol = append(tableCol, "Status", "Version", "Updates")
+			alreadySeen := make(map[string]bool)
-			statuses, err = config.GetAppStatuses(appFiles)
+			for _, app := range apps {
+				if _, ok := alreadySeen[app.Server]; !ok {
+					alreadySeen[app.Server] = true
+				}
+			}
+
+			statuses, err = config.GetAppStatuses(apps, internal.MachineReadable)
+			if err != nil {
+				logrus.Fatal(err)
+			}
+
+			catl, err = recipe.ReadRecipeCatalogue(internal.Offline)
 			if err != nil {
 				logrus.Fatal(err)
 			}
 		}
 
-		table := abraFormatter.CreateTable(tableCol)
+		var totalServersCount int
-		table.SetAutoMergeCellsByColumnIndex([]int{0})
+		var totalAppsCount int
-
+		allStats := make(map[string]serverStatus)
 		for _, app := range apps {
-			var tableRow []string
+			var stats serverStatus
-			if app.Type == appType || appType == "" {
+			var ok bool
-				// If type flag is set, check for it, if not, Type == ""
+			if stats, ok = allStats[app.Server]; !ok {
-				tableRow = []string{app.Server, app.Type, app.Domain}
+				stats = serverStatus{}
+				if recipeFilter == "" {
+					// count server, no filtering
+					totalServersCount++
+				}
+			}
+
+			if app.Recipe == recipeFilter || recipeFilter == "" {
+				if recipeFilter != "" {
+					// only count server if matches filter
+					totalServersCount++
+				}
+
+				appStats := appStatus{}
+				stats.AppCount++
+				totalAppsCount++
+
 				if status {
-					stackName := app.StackName()
 					status := "unknown"
 					version := "unknown"
-					if statusMeta, ok := statuses[stackName]; ok {
+					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"]
 						}
-						tableRow = append(tableRow, status, version)
+						stats.VersionCount++
 					} else {
-						tableRow = append(tableRow, status, version)
+						stats.UnversionedCount++
 					}
 
+					appStats.Status = status
+					appStats.Chaos = chaos
+					appStats.ChaosVersion = chaosVersion
+					appStats.Version = version
+					appStats.AutoUpdate = autoUpdate
+
 					var newUpdates []string
 					if version != "unknown" {
-						updates, err := catalogue.GetRecipeCatalogueVersions(app.Type)
+						updates, err := recipe.GetRecipeCatalogueVersions(app.Recipe, catl)
 						if err != nil {
 							logrus.Fatal(err)
 						}
@@ -128,24 +201,100 @@ can take some time.
 
 					if len(newUpdates) == 0 {
 						if version == "unknown" {
-							tableRow = append(tableRow, "unknown")
+							appStats.Upgrade = "unknown"
 						} else {
-							tableRow = append(tableRow, "on latest")
+							appStats.Upgrade = "latest"
+							stats.LatestCount++
 						}
 					} else {
-						// FIXME: jeezus golang why do you not have a list reverse function
+						newUpdates = internal.ReverseStringList(newUpdates)
-						for i, j := 0, len(newUpdates)-1; i < j; i, j = i+1, j-1 {
+						appStats.Upgrade = strings.Join(newUpdates, "\n")
-							newUpdates[i], newUpdates[j] = newUpdates[j], newUpdates[i]
+						stats.UpgradeCount++
-						}
-						tableRow = append(tableRow, strings.Join(newUpdates, "\n"))
 					}
 				}
+
+				appStats.Server = app.Server
+				appStats.Recipe = app.Recipe
+				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 {
+				logrus.Fatal(err)
+			} else {
+				fmt.Println(string(jsonstring))
+			}
+			return nil
+		}
+
+		alreadySeen := make(map[string]bool)
+		for _, app := range apps {
+			if _, ok := alreadySeen[app.Server]; ok {
+				continue
+			}
+
+			serverStat := allStats[app.Server]
+
+			tableCol := []string{"recipe", "domain"}
+			if status {
+				tableCol = append(tableCol, []string{"status", "chaos", "version", "upgrade", "autoupdate"}...)
+			}
+
+			table := formatter.CreateTable(tableCol)
+
+			for _, appStat := range serverStat.Apps {
+				tableRow := []string{appStat.Recipe, appStat.Domain}
+				if status {
+					chaosStatus := appStat.Chaos
+					if chaosStatus != "unknown" {
+						chaosEnabled, err := strconv.ParseBool(chaosStatus)
+						if err != nil {
+							logrus.Fatal(err)
+						}
+						if chaosEnabled && appStat.ChaosVersion != "unknown" {
+							chaosStatus = appStat.ChaosVersion
+						}
+					}
+					tableRow = append(tableRow, []string{appStat.Status, chaosStatus, appStat.Version, appStat.Upgrade, appStat.AutoUpdate}...)
 				}
 				table.Append(tableRow)
 			}
 
+			if table.NumLines() > 0 {
 				table.Render()
 
+				if status {
+					fmt.Println(fmt.Sprintf(
+						"server: %s | total apps: %v | versioned: %v | unversioned: %v | latest: %v | upgrade: %v",
+						app.Server,
+						serverStat.AppCount,
+						serverStat.VersionCount,
+						serverStat.UnversionedCount,
+						serverStat.LatestCount,
+						serverStat.UpgradeCount,
+					))
+				} else {
+					fmt.Println(fmt.Sprintf("server: %s | total apps: %v", app.Server, serverStat.AppCount))
+				}
+			}
+
+			if len(allStats) > 1 && table.NumLines() > 0 {
+				fmt.Println() // newline separator for multiple servers
+			}
+
+			alreadySeen[app.Server] = true
+		}
+
+		if len(allStats) > 1 {
+			fmt.Println(fmt.Sprintf("total servers: %v | total apps: %v ", totalServersCount, totalAppsCount))
+		}
+
 		return nil
 	},
 }

cli/app/logs.go

@@ -1,27 +1,46 @@
 package app
 
 import (
+	"context"
 	"fmt"
 	"io"
 	"os"
 	"sync"
 
 	"coopcloud.tech/abra/cli/internal"
+	"coopcloud.tech/abra/pkg/autocomplete"
 	"coopcloud.tech/abra/pkg/client"
 	"coopcloud.tech/abra/pkg/config"
+	"coopcloud.tech/abra/pkg/recipe"
+	"coopcloud.tech/abra/pkg/service"
+	"coopcloud.tech/abra/pkg/upstream/stack"
 	"github.com/docker/docker/api/types"
 	"github.com/docker/docker/api/types/filters"
 	dockerClient "github.com/docker/docker/client"
 	"github.com/sirupsen/logrus"
-	"github.com/urfave/cli/v2"
+	"github.com/urfave/cli"
 )
 
+var logOpts = types.ContainerLogsOptions{
+	ShowStderr: true,
+	ShowStdout: true,
+	Since:      "",
+	Until:      "",
+	Timestamps: true,
+	Follow:     true,
+	Tail:       "20",
+	Details:    false,
+}
+
 // stackLogs lists logs for all stack services
-func stackLogs(c *cli.Context, stackName string, client *dockerClient.Client) {
+func stackLogs(c *cli.Context, app config.App, client *dockerClient.Client) {
-	filters := filters.NewArgs()
+	filters, err := app.Filters(true, false)
-	filters.Add("name", stackName)
+	if err != nil {
+		logrus.Fatal(err)
+	}
+
 	serviceOpts := types.ServiceListOptions{Filters: filters}
-	services, err := client.ServiceList(c.Context, serviceOpts)
+	services, err := client.ServiceList(context.Background(), serviceOpts)
 	if err != nil {
 		logrus.Fatal(err)
 	}
@@ -30,19 +49,14 @@ func stackLogs(c *cli.Context, stackName string, client *dockerClient.Client) {
 	for _, service := range services {
 		wg.Add(1)
 		go func(s string) {
-			logOpts := types.ContainerLogsOptions{
+			if internal.StdErrOnly {
-				Details:    true,
+				logOpts.ShowStdout = false
-				Follow:     true,
-				ShowStderr: true,
-				ShowStdout: true,
-				Tail:       "20",
-				Timestamps: true,
 			}
-			logs, err := client.ServiceLogs(c.Context, s, logOpts)
+
+			logs, err := client.ServiceLogs(context.Background(), s, logOpts)
 			if err != nil {
 				logrus.Fatal(err)
 			}
-			// defer after err check as any err returns a nil io.ReadCloser
 			defer logs.Close()
 
 			_, err = io.Copy(os.Stdout, logs)
@@ -51,55 +65,80 @@ func stackLogs(c *cli.Context, stackName string, client *dockerClient.Client) {
 			}
 		}(service.ID)
 	}
+
 	wg.Wait()
+
 	os.Exit(0)
 }
 
-var appLogsCommand = &cli.Command{
+var appLogsCommand = cli.Command{
 	Name:      "logs",
 	Aliases:   []string{"l"},
-	ArgsUsage: "[<service>]",
+	ArgsUsage: "<domain> [<service>]",
 	Usage:     "Tail app logs",
+	Flags: []cli.Flag{
+		internal.StdErrOnlyFlag,
+		internal.SinceLogsFlag,
+		internal.DebugFlag,
+	},
+	Before:       internal.SubCommandBefore,
+	BashComplete: autocomplete.AppNameComplete,
 	Action: func(c *cli.Context) error {
 		app := internal.ValidateApp(c)
+		stackName := app.StackName()
+
+		if err := recipe.EnsureExists(app.Recipe); err != nil {
+			logrus.Fatal(err)
+		}
 
 		cl, err := client.New(app.Server)
 		if err != nil {
 			logrus.Fatal(err)
 		}
 
+		isDeployed, _, err := stack.IsDeployed(context.Background(), cl, stackName)
+		if err != nil {
+			logrus.Fatal(err)
+		}
+
+		if !isDeployed {
+			logrus.Fatalf("%s is not deployed?", app.Name)
+		}
+
+		logOpts.Since = internal.SinceLogs
+
 		serviceName := c.Args().Get(1)
 		if serviceName == "" {
-			logrus.Debug("tailing logs for all app services")
+			logrus.Debugf("tailing logs for all %s services", app.Recipe)
-			stackLogs(c, app.StackName(), cl)
+			stackLogs(c, app, cl)
+		} else {
+			logrus.Debugf("tailing logs for %s", serviceName)
+			if err := tailServiceLogs(c, cl, app, serviceName); err != nil {
+				logrus.Fatal(err)
+			}
 		}
-		logrus.Debugf("tailing logs for '%s'", serviceName)
 
-		service := fmt.Sprintf("%s_%s", app.StackName(), serviceName)
+		return nil
+	},
+}
+
+func tailServiceLogs(c *cli.Context, cl *dockerClient.Client, app config.App, serviceName string) error {
 	filters := filters.NewArgs()
-		filters.Add("name", service)
+	filters.Add("name", fmt.Sprintf("%s_%s", app.StackName(), serviceName))
-		serviceOpts := types.ServiceListOptions{Filters: filters}
+
-		services, err := cl.ServiceList(c.Context, serviceOpts)
+	chosenService, err := service.GetService(context.Background(), cl, filters, internal.NoInput)
 	if err != nil {
 		logrus.Fatal(err)
 	}
-		if len(services) != 1 {
-			logrus.Fatalf("expected 1 service but got %v", len(services))
-		}
 
-		logOpts := types.ContainerLogsOptions{
+	if internal.StdErrOnly {
-			Details:    true,
+		logOpts.ShowStdout = false
-			Follow:     true,
-			ShowStderr: true,
-			ShowStdout: true,
-			Tail:       "20",
-			Timestamps: true,
 	}
-		logs, err := cl.ServiceLogs(c.Context, services[0].ID, logOpts)
+
+	logs, err := cl.ServiceLogs(context.Background(), chosenService.ID, logOpts)
 	if err != nil {
 		logrus.Fatal(err)
 	}
-		// defer after err check as any err returns a nil io.ReadCloser
 	defer logs.Close()
 
 	_, err = io.Copy(os.Stdout, logs)
@@ -108,17 +147,4 @@ var appLogsCommand = &cli.Command{
 	}
 
 	return nil
-	},
-	BashComplete: func(c *cli.Context) {
-		appNames, err := config.GetAppNames()
-		if err != nil {
-			logrus.Warn(err)
-		}
-		if c.NArg() > 0 {
-			return
-		}
-		for _, a := range appNames {
-			fmt.Println(a)
-		}
-	},
 }

cli/app/new.go

@@ -4,51 +4,27 @@ import (
 	"fmt"
 	"path"
 
-	abraFormatter "coopcloud.tech/abra/cli/formatter"
 	"coopcloud.tech/abra/cli/internal"
-	"coopcloud.tech/abra/pkg/catalogue"
+	"coopcloud.tech/abra/pkg/autocomplete"
+	"coopcloud.tech/abra/pkg/client"
 	"coopcloud.tech/abra/pkg/config"
+	"coopcloud.tech/abra/pkg/formatter"
+	"coopcloud.tech/abra/pkg/jsontable"
+	"coopcloud.tech/abra/pkg/recipe"
+	recipePkg "coopcloud.tech/abra/pkg/recipe"
 	"coopcloud.tech/abra/pkg/secret"
 	"github.com/AlecAivazis/survey/v2"
+	dockerClient "github.com/docker/docker/client"
 	"github.com/sirupsen/logrus"
-	"github.com/urfave/cli/v2"
+	"github.com/urfave/cli"
 )
 
-type secrets map[string]string
-
-var domain string
-var domainFlag = &cli.StringFlag{
-	Name:        "domain",
-	Aliases:     []string{"d"},
-	Value:       "",
-	Usage:       "Choose a domain name",
-	Destination: &domain,
-}
-
-var newAppServer string
-var newAppServerFlag = &cli.StringFlag{
-	Name:        "server",
-	Aliases:     []string{"s"},
-	Value:       "",
-	Usage:       "Show apps of a specific server",
-	Destination: &newAppServer,
-}
-
-var newAppName string
-var newAppNameFlag = &cli.StringFlag{
-	Name:        "app-name",
-	Aliases:     []string{"a"},
-	Value:       "",
-	Usage:       "Choose an app name",
-	Destination: &newAppName,
-}
-
 var appNewDescription = `
-This command takes a recipe and uses it to create a new app. This new app
+Take a recipe and uses it to create a new app. This new app configuration is
-configuration is stored in your ~/.abra directory under the appropriate server.
+stored in your ~/.abra directory under the appropriate server.
 
 This command does not deploy your app for you. You will need to run "abra app
-deploy <app>" to do so.
+deploy <domain>" to do so.
 
 You can see what recipes are available (i.e. values for the <recipe> argument)
 by running "abra recipe ls".
@@ -63,44 +39,199 @@ pass store (see passwordstore.org for more). The pass command must be available
 on your $PATH.
 `
 
-var appNewCommand = &cli.Command{
+var appNewCommand = cli.Command{
 	Name:        "new",
-	Usage:       "Create a new app",
 	Aliases:     []string{"n"},
+	Usage:       "Create a new app",
 	Description: appNewDescription,
 	Flags: []cli.Flag{
-		newAppServerFlag,
+		internal.DebugFlag,
-		domainFlag,
+		internal.NoInputFlag,
-		newAppNameFlag,
+		internal.NewAppServerFlag,
+		internal.DomainFlag,
 		internal.PassFlag,
 		internal.SecretsFlag,
+		internal.OfflineFlag,
+		internal.ChaosFlag,
 	},
-	ArgsUsage: "<recipe>",
+	Before:       internal.SubCommandBefore,
-	Action:    action,
+	ArgsUsage:    "[<recipe>]",
-	BashComplete: func(c *cli.Context) {
+	BashComplete: autocomplete.RecipeNameComplete,
-		catl, err := catalogue.ReadRecipeCatalogue()
+	Action: func(c *cli.Context) error {
+		recipe := internal.ValidateRecipe(c)
+
+		if !internal.Chaos {
+			if err := recipePkg.EnsureIsClean(recipe.Name); err != nil {
+				logrus.Fatal(err)
+			}
+			if !internal.Offline {
+				if err := recipePkg.EnsureUpToDate(recipe.Name); err != nil {
+					logrus.Fatal(err)
+				}
+			}
+			if err := recipePkg.EnsureLatest(recipe.Name); err != nil {
+				logrus.Fatal(err)
+			}
+		}
+
+		if err := ensureServerFlag(); err != nil {
+			logrus.Fatal(err)
+		}
+
+		if err := ensureDomainFlag(recipe, internal.NewAppServer); err != nil {
+			logrus.Fatal(err)
+		}
+
+		sanitisedAppName := config.SanitiseAppName(internal.Domain)
+		logrus.Debugf("%s sanitised as %s for new app", internal.Domain, sanitisedAppName)
+
+		if err := config.TemplateAppEnvSample(
+			recipe.Name,
+			internal.Domain,
+			internal.NewAppServer,
+			internal.Domain,
+		); err != nil {
+			logrus.Fatal(err)
+		}
+
+		var secrets AppSecrets
+		var secretTable *jsontable.JSONTable
+		if internal.Secrets {
+			sampleEnv, err := recipe.SampleEnv()
 			if err != nil {
-			logrus.Warn(err)
+				logrus.Fatal(err)
 			}
-		if c.NArg() > 0 {
+
-			return
+			composeFiles, err := config.GetComposeFiles(recipe.Name, sampleEnv)
+			if err != nil {
+				logrus.Fatal(err)
 			}
-		for name := range catl {
+
-			fmt.Println(name)
+			envSamplePath := path.Join(config.RECIPES_DIR, recipe.Name, ".env.sample")
+			secretsConfig, err := secret.ReadSecretsConfig(envSamplePath, composeFiles, recipe.Name)
+			if err != nil {
+				return err
 			}
+
+			if err := promptForSecrets(recipe.Name, secretsConfig); err != nil {
+				logrus.Fatal(err)
+			}
+
+			cl, err := client.New(internal.NewAppServer)
+			if err != nil {
+				logrus.Fatal(err)
+			}
+
+			secrets, err = createSecrets(cl, secretsConfig, sanitisedAppName)
+			if err != nil {
+				logrus.Fatal(err)
+			}
+
+			secretCols := []string{"Name", "Value"}
+			secretTable = formatter.CreateTable(secretCols)
+			for name, val := range secrets {
+				secretTable.Append([]string{name, val})
+			}
+		}
+
+		if internal.NewAppServer == "default" {
+			internal.NewAppServer = "local"
+		}
+
+		tableCol := []string{"server", "recipe", "domain"}
+		table := formatter.CreateTable(tableCol)
+		table.Append([]string{internal.NewAppServer, recipe.Name, internal.Domain})
+
+		fmt.Println(fmt.Sprintf("A new %s app has been created! Here is an overview:", recipe.Name))
+		fmt.Println("")
+		table.Render()
+		fmt.Println("")
+		fmt.Println("You can configure this app by running the following:")
+		fmt.Println(fmt.Sprintf("\n    abra app config %s", internal.Domain))
+		fmt.Println("")
+		fmt.Println("You can deploy this app by running the following:")
+		fmt.Println(fmt.Sprintf("\n    abra app deploy %s", internal.Domain))
+
+		if len(secrets) > 0 {
+			fmt.Println("")
+			fmt.Println("Here are your generated secrets:")
+			fmt.Println("")
+			secretTable.Render()
+			logrus.Warn("generated secrets are not shown again, please take note of them NOW")
+		}
+
+		return nil
 	},
 }
 
+// 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.SecretValue, sanitisedAppName string) (AppSecrets, error) {
+	// NOTE(d1): trim to match app.StackName() implementation
+	if len(sanitisedAppName) > 45 {
+		logrus.Debugf("trimming %s to %s to avoid runtime limits", sanitisedAppName, sanitisedAppName[:45])
+		sanitisedAppName = sanitisedAppName[:45]
+	}
+
+	secrets, err := secret.GenerateSecrets(cl, secretsConfig, sanitisedAppName, internal.NewAppServer)
+	if err != nil {
+		return nil, err
+	}
+
+	if internal.Pass {
+		for secretName := range secrets {
+			secretValue := secrets[secretName]
+			if err := secret.PassInsertSecret(
+				secretValue,
+				secretName,
+				internal.Domain,
+				internal.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() error {
+func ensureDomainFlag(recipe recipe.Recipe, server string) error {
-	if domain == "" {
+	if internal.Domain == "" && !internal.NoInput {
 		prompt := &survey.Input{
 			Message: "Specify app domain",
+			Default: fmt.Sprintf("%s.%s", recipe.Name, server),
 		}
-		if err := survey.AskOne(prompt, &domain); err != nil {
+		if err := survey.AskOne(prompt, &internal.Domain); err != nil {
 			return err
 		}
 	}
+
+	if internal.Domain == "" {
+		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.SecretValue) error {
+	if len(secretsConfig) == 0 {
+		logrus.Debugf("%s has no secrets to generate, skipping...", recipeName)
+		return nil
+	}
+
+	if !internal.Secrets && !internal.NoInput {
+		prompt := &survey.Confirm{
+			Message: "Generate app secrets?",
+		}
+		if err := survey.AskOne(prompt, &internal.Secrets); err != nil {
+			return err
+		}
+	}
+
 	return nil
 }
 
@@ -111,120 +242,19 @@ func ensureServerFlag() error {
 		return err
 	}
 
-	if newAppServer == "" {
+	if internal.NewAppServer == "" && !internal.NoInput {
 		prompt := &survey.Select{
 			Message: "Select app server:",
 			Options: servers,
 		}
-		if err := survey.AskOne(prompt, &newAppServer); err != nil {
+		if err := survey.AskOne(prompt, &internal.NewAppServer); err != nil {
 			return err
 		}
 	}
 
-	return nil
+	if internal.NewAppServer == "" {
+		return fmt.Errorf("no server provided")
 	}
 
-// ensureServerFlag checks if the AppName flag was used. if not, asks the user for it.
-func ensureAppNameFlag() error {
-	if newAppName == "" {
-		prompt := &survey.Input{
-			Message: "Specify app name:",
-			Default: config.SanitiseAppName(domain),
-		}
-		if err := survey.AskOne(prompt, &newAppName); err != nil {
-			return err
-		}
-	}
-	return nil
-}
-
-// createSecrets creates all secrets for a new app.
-func createSecrets(sanitisedAppName string) (secrets, error) {
-	appEnvPath := path.Join(config.ABRA_DIR, "servers", newAppServer, fmt.Sprintf("%s.env", sanitisedAppName))
-	appEnv, err := config.ReadEnv(appEnvPath)
-	if err != nil {
-		return nil, err
-	}
-
-	secretEnvVars := secret.ReadSecretEnvVars(appEnv)
-	secrets, err := secret.GenerateSecrets(secretEnvVars, sanitisedAppName, newAppServer)
-	if err != nil {
-		return nil, err
-	}
-
-	if internal.Pass {
-		for secretName := range secrets {
-			secretValue := secrets[secretName]
-			if err := secret.PassInsertSecret(secretValue, secretName, sanitisedAppName, newAppServer); err != nil {
-				return nil, err
-			}
-		}
-	}
-	return secrets, nil
-}
-
-// action is the main command-line action for this package
-func action(c *cli.Context) error {
-	recipe := internal.ValidateRecipe(c)
-
-	if err := config.EnsureAbraDirExists(); err != nil {
-		logrus.Fatal(err)
-	}
-
-	if err := ensureServerFlag(); err != nil {
-		logrus.Fatal(err)
-	}
-
-	if err := ensureDomainFlag(); err != nil {
-		logrus.Fatal(err)
-	}
-
-	if err := ensureAppNameFlag(); err != nil {
-		logrus.Fatal(err)
-	}
-
-	sanitisedAppName := config.SanitiseAppName(newAppName)
-	if len(sanitisedAppName) > 45 {
-		logrus.Fatalf("'%s' cannot be longer than 45 characters", sanitisedAppName)
-	}
-	logrus.Debugf("'%s' sanitised as '%s' for new app", newAppName, sanitisedAppName)
-
-	if err := config.TemplateAppEnvSample(recipe.Name, newAppName, newAppServer, domain, recipe.Name); err != nil {
-		logrus.Fatal(err)
-	}
-
-	if internal.Secrets {
-		secrets, err := createSecrets(sanitisedAppName)
-		if err != nil {
-			logrus.Fatal(err)
-		}
-
-		secretCols := []string{"Name", "Value"}
-		secretTable := abraFormatter.CreateTable(secretCols)
-		for secret := range secrets {
-			secretTable.Append([]string{secret, secrets[secret]})
-		}
-
-		if len(secrets) > 0 {
-			defer secretTable.Render()
-		}
-	}
-
-	tableCol := []string{"Name", "Domain", "Type", "Server"}
-	table := abraFormatter.CreateTable(tableCol)
-	table.Append([]string{sanitisedAppName, domain, recipe.Name, newAppServer})
-
-	fmt.Println("")
-	fmt.Println(fmt.Sprintf("New '%s' created! Here is your new app overview:", recipe.Name))
-	fmt.Println("")
-	table.Render()
-	fmt.Println("")
-	fmt.Println("You can configure this app by running the following:")
-	fmt.Println(fmt.Sprintf("\n    abra app config %s", sanitisedAppName))
-	fmt.Println("")
-	fmt.Println("You can deploy this app by running the following:")
-	fmt.Println(fmt.Sprintf("\n    abra app deploy %s", sanitisedAppName))
-	fmt.Println("")
-
 	return nil
 }

cli/app/ps.go

@@ -1,24 +1,37 @@
 package app
 
 import (
-	"fmt"
+	"context"
 	"strings"
+	"time"
 
-	abraFormatter "coopcloud.tech/abra/cli/formatter"
 	"coopcloud.tech/abra/cli/internal"
+	"coopcloud.tech/abra/pkg/autocomplete"
 	"coopcloud.tech/abra/pkg/client"
 	"coopcloud.tech/abra/pkg/config"
-	"github.com/docker/cli/cli/command/formatter"
+	"coopcloud.tech/abra/pkg/formatter"
+	"coopcloud.tech/abra/pkg/service"
+	stack "coopcloud.tech/abra/pkg/upstream/stack"
+	"github.com/buger/goterm"
+	dockerFormatter "github.com/docker/cli/cli/command/formatter"
 	"github.com/docker/docker/api/types"
-	"github.com/docker/docker/api/types/filters"
+	dockerClient "github.com/docker/docker/client"
 	"github.com/sirupsen/logrus"
-	"github.com/urfave/cli/v2"
+	"github.com/urfave/cli"
 )
 
-var appPsCommand = &cli.Command{
+var appPsCommand = cli.Command{
 	Name:        "ps",
-	Usage:   "Check app status",
 	Aliases:     []string{"p"},
+	Usage:       "Check app status",
+	ArgsUsage:   "<domain>",
+	Description: "Show a more detailed status output of a specific deployed app",
+	Flags: []cli.Flag{
+		internal.WatchFlag,
+		internal.DebugFlag,
+	},
+	Before:       internal.SubCommandBefore,
+	BashComplete: autocomplete.AppNameComplete,
 	Action: func(c *cli.Context) error {
 		app := internal.ValidateApp(c)
 
@@ -27,43 +40,62 @@ var appPsCommand = &cli.Command{
 			logrus.Fatal(err)
 		}
 
-		filters := filters.NewArgs()
+		isDeployed, _, err := stack.IsDeployed(context.Background(), cl, app.StackName())
-		filters.Add("name", app.StackName())
-
-		containers, err := cl.ContainerList(c.Context, types.ContainerListOptions{Filters: filters})
 		if err != nil {
 			logrus.Fatal(err)
 		}
 
-		tableCol := []string{"id", "image", "command", "created", "status", "ports", "names"}
+		if !isDeployed {
-		table := abraFormatter.CreateTable(tableCol)
+			logrus.Fatalf("%s is not deployed?", app.Name)
+		}
+
+		if !internal.Watch {
+			showPSOutput(c, app, cl)
+			return nil
+		}
+
+		goterm.Clear()
+		for {
+			goterm.MoveCursor(1, 1)
+			showPSOutput(c, app, cl)
+			goterm.Flush()
+			time.Sleep(2 * time.Second)
+		}
+	},
+}
+
+// showPSOutput renders ps output.
+func showPSOutput(c *cli.Context, app config.App, cl *dockerClient.Client) {
+	filters, err := app.Filters(true, true)
+	if err != nil {
+		logrus.Fatal(err)
+	}
+
+	containers, err := cl.ContainerList(context.Background(), types.ContainerListOptions{Filters: filters})
+	if err != nil {
+		logrus.Fatal(err)
+	}
+
+	tableCol := []string{"service name", "image", "created", "status", "state", "ports"}
+	table := formatter.CreateTable(tableCol)
 
 	for _, container := range containers {
+		var containerNames []string
+		for _, containerName := range container.Names {
+			trimmed := strings.TrimPrefix(containerName, "/")
+			containerNames = append(containerNames, trimmed)
+		}
+
 		tableRow := []string{
-				abraFormatter.ShortenID(container.ID),
+			service.ContainerToServiceName(container.Names, app.StackName()),
-				abraFormatter.RemoveSha(container.Image),
+			formatter.RemoveSha(container.Image),
-				abraFormatter.Truncate(container.Command),
+			formatter.HumanDuration(container.Created),
-				abraFormatter.HumanDuration(container.Created),
 			container.Status,
-				formatter.DisplayablePorts(container.Ports),
+			container.State,
-				strings.Join(container.Names, ", "),
+			dockerFormatter.DisplayablePorts(container.Ports),
 		}
 		table.Append(tableRow)
 	}
 
 	table.Render()
-		return nil
-	},
-	BashComplete: func(c *cli.Context) {
-		appNames, err := config.GetAppNames()
-		if err != nil {
-			logrus.Warn(err)
-		}
-		if c.NArg() > 0 {
-			return
-		}
-		for _, a := range appNames {
-			fmt.Println(a)
-		}
-	},
 }

cli/app/remove.go

@@ -1,76 +1,86 @@
 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/config"
+	stack "coopcloud.tech/abra/pkg/upstream/stack"
 	"github.com/AlecAivazis/survey/v2"
 	"github.com/docker/docker/api/types"
-	"github.com/docker/docker/api/types/filters"
+	"github.com/docker/docker/api/types/volume"
 	"github.com/sirupsen/logrus"
-	"github.com/urfave/cli/v2"
+	"github.com/urfave/cli"
 )
 
-// Volumes stores the variable from VolumesFlag
+var appRemoveCommand = cli.Command{
-var Volumes bool
-
-// VolumesFlag is used to specify if volumes should be deleted when deleting an app
-var VolumesFlag = &cli.BoolFlag{
-	Name:        "volumes",
-	Value:       false,
-	Destination: &Volumes,
-}
-
-var appRemoveCommand = &cli.Command{
 	Name:      "remove",
-	Usage:   "Remove an already undeployed app",
 	Aliases:   []string{"rm"},
+	ArgsUsage: "<domain>",
+	Usage:     "Remove all app data, locally and remotely",
+	Description: `
+This command removes 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.
+`,
 	Flags: []cli.Flag{
-		VolumesFlag,
 		internal.ForceFlag,
+		internal.DebugFlag,
+		internal.NoInputFlag,
+		internal.OfflineFlag,
 	},
+	BashComplete: autocomplete.AppNameComplete,
+	Before:       internal.SubCommandBefore,
 	Action: func(c *cli.Context) error {
 		app := internal.ValidateApp(c)
 
-		if !internal.Force {
+		if !internal.Force && !internal.NoInput {
 			response := false
-			prompt := &survey.Confirm{
+			msg := "ALERTA ALERTA: this will completely remove %s data and configurations locally and remotely, are you sure?"
-				Message: fmt.Sprintf("about to delete %s, are you sure?", app.Name),
+			prompt := &survey.Confirm{Message: fmt.Sprintf(msg, app.Name)}
-			}
 			if err := survey.AskOne(prompt, &response); err != nil {
 				logrus.Fatal(err)
 			}
 			if !response {
-				logrus.Fatal("user aborted app removal")
+				logrus.Fatal("aborting as requested")
 			}
 		}
 
-		appFiles, err := config.LoadAppFiles("")
-		if err != nil {
-			logrus.Fatal(err)
-		}
-
 		cl, err := client.New(app.Server)
 		if err != nil {
 			logrus.Fatal(err)
 		}
-		if !internal.Force {
+
-			// FIXME: only query for app we are interested in, not all of them!
+		isDeployed, _, err := stack.IsDeployed(context.Background(), cl, app.StackName())
-			statuses, err := config.GetAppStatuses(appFiles)
 		if err != nil {
 			logrus.Fatal(err)
 		}
-			if statuses[app.Name]["status"] == "deployed" {
+		if isDeployed {
-				logrus.Fatalf("'%s' is still deployed. Run \"abra app %s undeploy\" or pass --force", app.Name, app.Name)
+			logrus.Fatalf("%s is still deployed. Run \"abra app undeploy %s\"", app.Name, app.Name)
-			}
 		}
 
-		fs := filters.NewArgs()
+		fs, err := app.Filters(false, false)
-		fs.Add("name", app.Name)
+		if err != nil {
-		secretList, err := cl.SecretList(c.Context, types.SecretListOptions{Filters: fs})
+			logrus.Fatal(err)
+		}
+
+		secretList, err := cl.SecretList(context.Background(), types.SecretListOptions{Filters: fs})
 		if err != nil {
 			logrus.Fatal(err)
 		}
@@ -84,20 +94,8 @@ var appRemoveCommand = &cli.Command{
 		}
 
 		if len(secrets) > 0 {
-			var secretNamesToRemove []string
+			for _, name := range secretNames {
-			if !internal.Force {
+				err := cl.SecretRemove(context.Background(), secrets[name])
-				secretsPrompt := &survey.MultiSelect{
-					Message: "which secrets do you want to remove?",
-					Options: secretNames,
-					Default: secretNames,
-				}
-				if err := survey.AskOne(secretsPrompt, &secretNamesToRemove); err != nil {
-					logrus.Fatal(err)
-				}
-			}
-
-			for _, name := range secretNamesToRemove {
-				err := cl.SecretRemove(c.Context, secrets[name])
 				if err != nil {
 					logrus.Fatal(err)
 				}
@@ -107,7 +105,13 @@ var appRemoveCommand = &cli.Command{
 			logrus.Info("no secrets to remove")
 		}
 
-		volumeListOKBody, err := cl.VolumeList(c.Context, fs)
+		fs, err = app.Filters(false, true)
+		if err != nil {
+			logrus.Fatal(err)
+		}
+
+		volumeListOptions := volume.ListOptions{fs}
+		volumeListOKBody, err := cl.VolumeList(context.Background(), volumeListOptions)
 		volumeList := volumeListOKBody.Volumes
 		if err != nil {
 			logrus.Fatal(err)
@@ -119,50 +123,23 @@ var appRemoveCommand = &cli.Command{
 		}
 
 		if len(vols) > 0 {
-			if Volumes {
+			for _, vol := range vols {
-				var removeVols []string
+				err := cl.VolumeRemove(context.Background(), vol, internal.Force) // last argument is for force removing
-				if !internal.Force {
-					volumesPrompt := &survey.MultiSelect{
-						Message: "which volumes do you want to remove?",
-						Options: vols,
-						Default: vols,
-					}
-					if err := survey.AskOne(volumesPrompt, &removeVols); err != nil {
-						logrus.Fatal(err)
-					}
-				}
-				for _, vol := range removeVols {
-					err := cl.VolumeRemove(c.Context, vol, internal.Force) // last argument is for force removing
 				if err != nil {
 					logrus.Fatal(err)
 				}
 				logrus.Info(fmt.Sprintf("volume %s removed", vol))
 			}
-			} else {
-				logrus.Info("no volumes were removed")
-			}
 		} else {
 			logrus.Info("no volumes to remove")
 		}
 
-		err = os.Remove(app.Path)
+		if err = os.Remove(app.Path); err != nil {
-		if err != nil {
 			logrus.Fatal(err)
 		}
+
 		logrus.Info(fmt.Sprintf("file: %s removed", app.Path))
 
 		return nil
 	},
-	BashComplete: func(c *cli.Context) {
-		appNames, err := config.GetAppNames()
-		if err != nil {
-			logrus.Warn(err)
-		}
-		if c.NArg() > 0 {
-			return
-		}
-		for _, a := range appNames {
-			fmt.Println(a)
-		}
-	},
 }

cli/app/restart.go

@@ -0,0 +1,80 @@
+package app
+
+import (
+	"context"
+	"errors"
+	"fmt"
+
+	"coopcloud.tech/abra/cli/internal"
+	"coopcloud.tech/abra/pkg/autocomplete"
+	"coopcloud.tech/abra/pkg/client"
+	upstream "coopcloud.tech/abra/pkg/upstream/service"
+	stack "coopcloud.tech/abra/pkg/upstream/stack"
+	"github.com/sirupsen/logrus"
+	"github.com/urfave/cli"
+)
+
+var appRestartCommand = cli.Command{
+	Name:      "restart",
+	Aliases:   []string{"re"},
+	Usage:     "Restart an app",
+	ArgsUsage: "<domain>",
+	Flags: []cli.Flag{
+		internal.DebugFlag,
+		internal.OfflineFlag,
+	},
+	Before:       internal.SubCommandBefore,
+	Description:  `This command restarts a service within a deployed app.`,
+	BashComplete: autocomplete.AppNameComplete,
+	Action: func(c *cli.Context) error {
+		app := internal.ValidateApp(c)
+
+		serviceNameShort := c.Args().Get(1)
+		if serviceNameShort == "" {
+			err := errors.New("missing service?")
+			internal.ShowSubcommandHelpAndError(c, err)
+		}
+
+		cl, err := client.New(app.Server)
+		if err != nil {
+			logrus.Fatal(err)
+		}
+
+		isDeployed, _, err := stack.IsDeployed(context.Background(), cl, app.StackName())
+		if err != nil {
+			logrus.Fatal(err)
+		}
+
+		if !isDeployed {
+			logrus.Fatalf("%s is not deployed?", app.Name)
+		}
+
+		serviceName := fmt.Sprintf("%s_%s", app.StackName(), serviceNameShort)
+
+		logrus.Debugf("attempting to scale %s to 0 (restart logic)", serviceName)
+		if err := upstream.RunServiceScale(context.Background(), cl, serviceName, 0); err != nil {
+			logrus.Fatal(err)
+		}
+
+		if err := stack.WaitOnService(context.Background(), cl, serviceName, app.Name); err != nil {
+			logrus.Fatal(err)
+		}
+
+		logrus.Debugf("%s has been scaled to 0 (restart logic)", serviceName)
+
+		logrus.Debugf("attempting to scale %s to 1 (restart logic)", serviceName)
+		if err := upstream.RunServiceScale(context.Background(), cl, serviceName, 1); err != nil {
+			logrus.Fatal(err)
+		}
+
+		if err := stack.WaitOnService(context.Background(), cl, serviceName, app.Name); err != nil {
+			logrus.Fatal(err)
+		}
+
+		logrus.Debugf("%s has been scaled to 1 (restart logic)", serviceName)
+
+		logrus.Infof("%s service successfully restarted", serviceNameShort)
+
+		return nil
+	},
+}

cli/app/restore.go

@@ -1,79 +1,223 @@
 package app
 
 import (
+	"context"
 	"errors"
 	"fmt"
-	"io/ioutil"
 	"os"
-	"os/exec"
-	"path"
-	"strings"
 
 	"coopcloud.tech/abra/cli/internal"
+	"coopcloud.tech/abra/pkg/autocomplete"
+	"coopcloud.tech/abra/pkg/client"
 	"coopcloud.tech/abra/pkg/config"
+	containerPkg "coopcloud.tech/abra/pkg/container"
+	"coopcloud.tech/abra/pkg/recipe"
+	recipePkg "coopcloud.tech/abra/pkg/recipe"
+	"coopcloud.tech/abra/pkg/upstream/container"
+	"github.com/docker/cli/cli/command"
+	"github.com/docker/docker/api/types"
+	"github.com/docker/docker/api/types/filters"
+	dockerClient "github.com/docker/docker/client"
+	"github.com/docker/docker/pkg/archive"
 	"github.com/sirupsen/logrus"
-	"github.com/urfave/cli/v2"
+	"github.com/urfave/cli"
 )
 
-var restoreAllServices bool
+type restoreConfig struct {
-var restoreAllServicesFlag = &cli.BoolFlag{
+	preHookCmd  string
-	Name:        "all",
+	postHookCmd string
-	Value:       false,
-	Destination: &restoreAllServices,
-	Aliases:     []string{"a"},
-	Usage:       "Restore all services",
 }
 
-var appRestoreCommand = &cli.Command{
+var appRestoreCommand = cli.Command{
 	Name:      "restore",
-	Usage:     "Restore an app from a backup",
+	Aliases:   []string{"rs"},
-	Aliases:   []string{"r"},
+	Usage:     "Run app restore",
-	Flags:     []cli.Flag{restoreAllServicesFlag},
+	ArgsUsage: "<domain> <service> <file>",
-	ArgsUsage: "<service> [<backup file>]",
+	Flags: []cli.Flag{
+		internal.DebugFlag,
+		internal.OfflineFlag,
+		internal.ChaosFlag,
+	},
+	Before:       internal.SubCommandBefore,
+	BashComplete: autocomplete.AppNameComplete,
+	Description: `
+Run an app restore.
+
+Pre/post hook commands are defined in the recipe configuration. Abra reads this
+configuration and run the comands in the context of the service before
+restoring the backup.
+
+Unlike "abra app backup", restore must be run on a per-service basis. You can
+not restore all services in one go. Backup files produced by Abra are
+compressed archives which use absolute paths. This allows Abra to restore
+according to standard tar command logic, i.e. the backup will be restored to
+the path it was originally backed up from.
+
+Example:
+
+    abra app restore example.com app ~/.abra/backups/example_com_app_609341138.tar.gz
+`,
 	Action: func(c *cli.Context) error {
 		app := internal.ValidateApp(c)
 
-		if c.Args().Len() > 1 && restoreAllServices {
+		recipe, err := recipe.Get(app.Recipe, internal.Offline)
-			internal.ShowSubcommandHelpAndError(c, errors.New("cannot use <service>/<backup file> and '--all' together"))
-		}
-
-		abraSh := path.Join(config.ABRA_DIR, "apps", app.Type, "abra.sh")
-		if _, err := os.Stat(abraSh); err != nil {
-			if os.IsNotExist(err) {
-				logrus.Fatalf("'%s' does not exist?", abraSh)
-			}
-			logrus.Fatal(err)
-		}
-
-		sourceCmd := fmt.Sprintf("source %s", abraSh)
-		execCmd := "abra_restore"
-		if !restoreAllServices {
-			serviceName := c.Args().Get(1)
-			if serviceName == "" {
-				internal.ShowSubcommandHelpAndError(c, errors.New("no service(s) target provided"))
-			}
-			execCmd = fmt.Sprintf("abra_restore_%s", serviceName)
-		}
-
-		bytes, err := ioutil.ReadFile(abraSh)
 		if err != nil {
 			logrus.Fatal(err)
 		}
-		if !strings.Contains(string(bytes), execCmd) {
+
-			logrus.Fatalf("%s doesn't have a '%s' function", app.Type, execCmd)
+		if !internal.Chaos {
+			if err := recipePkg.EnsureIsClean(app.Recipe); err != nil {
+				logrus.Fatal(err)
 			}
 
-		backupFile := c.Args().Get(2)
+			if !internal.Offline {
-		if backupFile != "" {
+				if err := recipePkg.EnsureUpToDate(app.Recipe); err != nil {
-			execCmd = fmt.Sprintf("%s %s", execCmd, backupFile)
+					logrus.Fatal(err)
+				}
 			}
 
-		sourceAndExec := fmt.Sprintf("%s; %s", sourceCmd, execCmd)
+			if err := recipePkg.EnsureLatest(app.Recipe); err != nil {
-		cmd := exec.Command("bash", "-c", sourceAndExec)
+				logrus.Fatal(err)
-		if err := internal.RunCmd(cmd); err != nil {
+			}
+		}
+
+		serviceName := c.Args().Get(1)
+		if serviceName == "" {
+			internal.ShowSubcommandHelpAndError(c, errors.New("missing <service>?"))
+		}
+
+		backupPath := c.Args().Get(2)
+		if backupPath == "" {
+			internal.ShowSubcommandHelpAndError(c, errors.New("missing <file>?"))
+		}
+
+		if _, err := os.Stat(backupPath); err != nil {
+			if os.IsNotExist(err) {
+				logrus.Fatalf("%s doesn't exist?", backupPath)
+			}
+		}
+
+		restoreConfigs := make(map[string]restoreConfig)
+		for _, service := range recipe.Config.Services {
+			if restoreEnabled, ok := service.Deploy.Labels["backupbot.restore"]; ok {
+				if restoreEnabled == "true" {
+					fullServiceName := fmt.Sprintf("%s_%s", app.StackName(), service.Name)
+					rsConfig := restoreConfig{}
+
+					logrus.Debugf("restore config detected for %s", fullServiceName)
+
+					if preHookCmd, ok := service.Deploy.Labels["backupbot.restore.pre-hook"]; ok {
+						logrus.Debugf("detected pre-hook command for %s: %s", fullServiceName, preHookCmd)
+						rsConfig.preHookCmd = preHookCmd
+					}
+
+					if postHookCmd, ok := service.Deploy.Labels["backupbot.restore.post-hook"]; ok {
+						logrus.Debugf("detected post-hook command for %s: %s", fullServiceName, postHookCmd)
+						rsConfig.postHookCmd = postHookCmd
+					}
+
+					restoreConfigs[service.Name] = rsConfig
+				}
+			}
+		}
+
+		rsConfig, ok := restoreConfigs[serviceName]
+		if !ok {
+			rsConfig = restoreConfig{}
+		}
+
+		cl, err := client.New(app.Server)
+		if err != nil {
+			logrus.Fatal(err)
+		}
+
+		if err := runRestore(cl, app, backupPath, serviceName, rsConfig); err != nil {
 			logrus.Fatal(err)
 		}
 
 		return nil
 	},
 }
+
+// runRestore does the actual restore logic.
+func runRestore(cl *dockerClient.Client, app config.App, backupPath, serviceName string, rsConfig restoreConfig) error {
+	// FIXME: avoid instantiating a new CLI
+	dcli, err := command.NewDockerCli()
+	if err != nil {
+		return err
+	}
+
+	filters := filters.NewArgs()
+	filters.Add("name", fmt.Sprintf("^%s_%s", app.StackName(), serviceName))
+
+	targetContainer, err := containerPkg.GetContainer(context.Background(), cl, filters, true)
+	if err != nil {
+		return err
+	}
+
+	fullServiceName := fmt.Sprintf("%s_%s", app.StackName(), serviceName)
+	if rsConfig.preHookCmd != "" {
+		splitCmd := internal.SafeSplit(rsConfig.preHookCmd)
+
+		logrus.Debugf("split pre-hook command for %s into %s", fullServiceName, splitCmd)
+
+		preHookExecOpts := types.ExecConfig{
+			AttachStderr: true,
+			AttachStdin:  true,
+			AttachStdout: true,
+			Cmd:          splitCmd,
+			Detach:       false,
+			Tty:          true,
+		}
+
+		if err := container.RunExec(dcli, cl, targetContainer.ID, &preHookExecOpts); err != nil {
+			return err
+		}
+
+		logrus.Infof("succesfully ran %s pre-hook command: %s", fullServiceName, rsConfig.preHookCmd)
+	}
+
+	backupReader, err := os.Open(backupPath)
+	if err != nil {
+		return err
+	}
+
+	content, err := archive.DecompressStream(backupReader)
+	if err != nil {
+		return err
+	}
+
+	// NOTE(d1): we use absolute paths so tar knows what to do. it will restore
+	// files according to the paths set in the compressed archive
+	restorePath := "/"
+
+	copyOpts := types.CopyToContainerOptions{AllowOverwriteDirWithFile: false, CopyUIDGID: false}
+	if err := cl.CopyToContainer(context.Background(), targetContainer.ID, restorePath, content, copyOpts); err != nil {
+		return err
+	}
+
+	logrus.Infof("restored %s to %s", backupPath, fullServiceName)
+
+	if rsConfig.postHookCmd != "" {
+		splitCmd := internal.SafeSplit(rsConfig.postHookCmd)
+
+		logrus.Debugf("split post-hook command for %s into %s", fullServiceName, splitCmd)
+
+		postHookExecOpts := types.ExecConfig{
+			AttachStderr: true,
+			AttachStdin:  true,
+			AttachStdout: true,
+			Cmd:          splitCmd,
+			Detach:       false,
+			Tty:          true,
+		}
+
+		if err := container.RunExec(dcli, cl, targetContainer.ID, &postHookExecOpts); err != nil {
+			return err
+		}
+
+		logrus.Infof("succesfully ran %s post-hook command: %s", fullServiceName, rsConfig.postHookCmd)
+	}
+
+	return nil
+}

cli/app/rollback.go

@@ -1,81 +1,239 @@
 package app
 
 import (
+	"context"
 	"fmt"
 
-	"context"
+	"coopcloud.tech/abra/pkg/autocomplete"
-
 	"coopcloud.tech/abra/pkg/config"
+	"coopcloud.tech/abra/pkg/lint"
+	"coopcloud.tech/abra/pkg/recipe"
+	stack "coopcloud.tech/abra/pkg/upstream/stack"
+	"coopcloud.tech/tagcmp"
 
 	"coopcloud.tech/abra/cli/internal"
-	appPkg "coopcloud.tech/abra/pkg/app"
-	"coopcloud.tech/abra/pkg/catalogue"
 	"coopcloud.tech/abra/pkg/client"
+	"github.com/AlecAivazis/survey/v2"
 	"github.com/sirupsen/logrus"
-	"github.com/urfave/cli/v2"
+	"github.com/urfave/cli"
 )
 
-var appRollbackCommand = &cli.Command{
+var appRollbackCommand = cli.Command{
 	Name:      "rollback",
+	Aliases:   []string{"rl"},
 	Usage:     "Roll an app back to a previous version",
-	Aliases:   []string{"r"},
+	ArgsUsage: "<domain> [<version>]",
-	ArgsUsage: "[<version>]",
+	Flags: []cli.Flag{
-	BashComplete: func(c *cli.Context) {
+		internal.DebugFlag,
-		appNames, err := config.GetAppNames()
+		internal.NoInputFlag,
-		if err != nil {
+		internal.ForceFlag,
-			logrus.Warn(err)
+		internal.ChaosFlag,
-		}
+		internal.NoDomainChecksFlag,
-		if c.NArg() > 0 {
+		internal.DontWaitConvergeFlag,
-			return
+		internal.OfflineFlag,
-		}
-		for _, a := range appNames {
-			fmt.Println(a)
-		}
 	},
+	Before: internal.SubCommandBefore,
+	Description: `
+This command rolls an app back to a previous version if one exists.
+
+You may pass "--force/-f" to downgrade to the same version again. This can be
+useful if the container runtime has gotten into a weird state.
+
+This action could be destructive, please ensure you have a copy of your app
+data beforehand.
+
+Chaos mode ("--chaos") will deploy your local checkout of a recipe as-is,
+including unstaged changes and can be useful for live hacking and testing new
+recipes.
+`,
+	BashComplete: autocomplete.AppNameComplete,
 	Action: func(c *cli.Context) error {
 		app := internal.ValidateApp(c)
+		stackName := app.StackName()
+
+		specificVersion := c.Args().Get(1)
+		if specificVersion != "" && internal.Chaos {
+			logrus.Fatal("cannot use <version> and --chaos together")
+		}
+
+		if err := recipe.EnsureExists(app.Recipe); err != nil {
+			logrus.Fatal(err)
+		}
+
+		if !internal.Chaos {
+			if err := recipe.EnsureIsClean(app.Recipe); err != nil {
+				logrus.Fatal(err)
+			}
+
+			if !internal.Offline {
+				if err := recipe.EnsureUpToDate(app.Recipe); err != nil {
+					logrus.Fatal(err)
+				}
+			}
+
+			if err := recipe.EnsureLatest(app.Recipe); err != nil {
+				logrus.Fatal(err)
+			}
+		}
+
+		r, err := recipe.Get(app.Recipe, internal.Offline)
+		if err != nil {
+			logrus.Fatal(err)
+		}
+
+		if err := lint.LintForErrors(r); err != nil {
+			logrus.Fatal(err)
+		}
 
-		ctx := context.Background()
 		cl, err := client.New(app.Server)
 		if err != nil {
 			logrus.Fatal(err)
 		}
 
-		recipeMeta, err := catalogue.GetRecipeMeta(app.Type)
+		logrus.Debugf("checking whether %s is already deployed", stackName)
+
+		isDeployed, deployedVersion, err := stack.IsDeployed(context.Background(), cl, stackName)
 		if err != nil {
 			logrus.Fatal(err)
 		}
-		if len(recipeMeta.Versions) == 0 {
-			logrus.Fatalf("no catalogue versions available for '%s'", app.Type)
-		}
 
-		deployedVersions, isDeployed, err := appPkg.DeployedVersions(ctx, cl, app)
-		if err != nil {
-			logrus.Fatal(err)
-		}
 		if !isDeployed {
-			logrus.Fatalf("'%s' is not deployed?", app.Name)
+			logrus.Fatalf("%s is not deployed?", app.Name)
-		}
-		if _, exists := deployedVersions["app"]; !exists {
-			logrus.Fatalf("no versioned 'app' service for '%s', cannot determine version", app.Name)
 		}
 
-		version := c.Args().Get(1)
+		catl, err := recipe.ReadRecipeCatalogue(internal.Offline)
-		if version == "" {
+		if err != nil {
-			// TODO:
+			logrus.Fatal(err)
-			// using deployedVersions["app"], get index+1 version from catalogue
+		}
-			// otherwise bail out saying there is nothing to rollback to
+
+		versions, err := recipe.GetRecipeCatalogueVersions(app.Recipe, catl)
+		if err != nil {
+			logrus.Fatal(err)
+		}
+
+		if len(versions) == 0 && !internal.Chaos {
+			logrus.Warn("no published versions in catalogue, trying local recipe repository")
+			recipeVersions, err := recipe.GetRecipeVersions(app.Recipe, internal.Offline)
+			if err != nil {
+				logrus.Warn(err)
+			}
+			for _, recipeVersion := range recipeVersions {
+				for version := range recipeVersion {
+					versions = append(versions, version)
+				}
+			}
+		}
+
+		var availableDowngrades []string
+		if deployedVersion == "unknown" {
+			availableDowngrades = versions
+			logrus.Warnf("failed to determine deployed version of %s", app.Name)
+		}
+
+		if specificVersion != "" {
+			parsedDeployedVersion, err := tagcmp.Parse(deployedVersion)
+			if err != nil {
+				logrus.Fatal(err)
+			}
+			parsedSpecificVersion, err := tagcmp.Parse(specificVersion)
+			if err != nil {
+				logrus.Fatal(err)
+			}
+			if parsedSpecificVersion.IsGreaterThan(parsedDeployedVersion) || parsedSpecificVersion.Equals(parsedDeployedVersion) {
+				logrus.Fatalf("%s is not a downgrade for %s?", deployedVersion, specificVersion)
+			}
+			availableDowngrades = append(availableDowngrades, specificVersion)
+		}
+
+		if deployedVersion != "unknown" && !internal.Chaos && specificVersion == "" {
+			for _, version := range versions {
+				parsedDeployedVersion, err := tagcmp.Parse(deployedVersion)
+				if err != nil {
+					logrus.Fatal(err)
+				}
+				parsedVersion, err := tagcmp.Parse(version)
+				if err != nil {
+					logrus.Fatal(err)
+				}
+				if parsedVersion.IsLessThan(parsedDeployedVersion) && !(parsedVersion.Equals(parsedDeployedVersion)) {
+					availableDowngrades = append(availableDowngrades, version)
+				}
+			}
+
+			if len(availableDowngrades) == 0 && !internal.Force {
+				logrus.Info("no available downgrades, you're on oldest ✌️")
+				return nil
+			}
+		}
+
+		var chosenDowngrade string
+		if len(availableDowngrades) > 0 && !internal.Chaos {
+			if internal.Force || internal.NoInput || specificVersion != "" {
+				chosenDowngrade = availableDowngrades[len(availableDowngrades)-1]
+				logrus.Debugf("choosing %s as version to downgrade to (--force/--no-input)", chosenDowngrade)
 			} else {
-			// TODO
+				prompt := &survey.Select{
-			// ensure this version is listed in the catalogue
+					Message: fmt.Sprintf("Please select a downgrade (current version: %s):", deployedVersion),
-			// ensure this version is "older" (lower down in the list)
+					Options: internal.ReverseStringList(availableDowngrades),
+				}
+				if err := survey.AskOne(prompt, &chosenDowngrade); err != nil {
+					return err
+				}
+			}
 		}
 
-		// TODO
+		if !internal.Chaos {
-		// display table of existing state and expected state and prompt
+			if err := recipe.EnsureVersion(app.Recipe, chosenDowngrade); err != nil {
-		// run the deployment with this target version!
+				logrus.Fatal(err)
+			}
+		}
 
-		logrus.Fatal("command not implemented yet, coming soon TM")
+		if internal.Chaos {
+			logrus.Warn("chaos mode engaged")
+			var err error
+			chosenDowngrade, err = recipe.ChaosVersion(app.Recipe)
+			if err != nil {
+				logrus.Fatal(err)
+			}
+		}
+
+		abraShPath := fmt.Sprintf("%s/%s/%s", config.RECIPES_DIR, app.Recipe, "abra.sh")
+		abraShEnv, err := config.ReadAbraShEnvVars(abraShPath)
+		if err != nil {
+			logrus.Fatal(err)
+		}
+		for k, v := range abraShEnv {
+			app.Env[k] = v
+		}
+
+		composeFiles, err := config.GetComposeFiles(app.Recipe, app.Env)
+		if err != nil {
+			logrus.Fatal(err)
+		}
+		deployOpts := stack.Deploy{
+			Composefiles: composeFiles,
+			Namespace:    stackName,
+			Prune:        false,
+			ResolveImage: stack.ResolveImageAlways,
+		}
+		compose, err := config.GetAppComposeConfig(app.Name, deployOpts, app.Env)
+		if err != nil {
+			logrus.Fatal(err)
+		}
+		config.ExposeAllEnv(stackName, compose, app.Env)
+		config.SetRecipeLabel(compose, stackName, app.Recipe)
+		config.SetChaosLabel(compose, stackName, internal.Chaos)
+		config.SetChaosVersionLabel(compose, stackName, chosenDowngrade)
+		config.SetUpdateLabel(compose, stackName, app.Env)
+
+		// NOTE(d1): no release notes implemeneted for rolling back
+		if err := internal.NewVersionOverview(app, deployedVersion, chosenDowngrade, ""); err != nil {
+			logrus.Fatal(err)
+		}
+
+		if err := stack.RunDeploy(cl, deployOpts, compose, stackName, internal.DontWaitConverge); err != nil {
+			logrus.Fatal(err)
+		}
 
 		return nil
 	},

cli/app/run.go

@@ -1,51 +1,55 @@
 package app
 
 import (
+	"context"
 	"errors"
 	"fmt"
 
 	"coopcloud.tech/abra/cli/internal"
+	"coopcloud.tech/abra/pkg/autocomplete"
 	"coopcloud.tech/abra/pkg/client"
-	"coopcloud.tech/abra/pkg/client/container"
+	containerPkg "coopcloud.tech/abra/pkg/container"
-	"coopcloud.tech/abra/pkg/config"
+	"coopcloud.tech/abra/pkg/upstream/container"
 	"github.com/docker/cli/cli/command"
 	"github.com/docker/docker/api/types"
 	"github.com/docker/docker/api/types/filters"
 	"github.com/sirupsen/logrus"
-	"github.com/urfave/cli/v2"
+	"github.com/urfave/cli"
 )
 
 var user string
 var userFlag = &cli.StringFlag{
-	Name:        "user",
+	Name:        "user, u",
 	Value:       "",
 	Destination: &user,
 }
 
 var noTTY bool
 var noTTYFlag = &cli.BoolFlag{
-	Name:        "no-tty",
+	Name:        "no-tty, t",
-	Value:       false,
 	Destination: &noTTY,
 }
 
-var appRunCommand = &cli.Command{
+var appRunCommand = cli.Command{
 	Name:    "run",
+	Aliases: []string{"r"},
 	Flags: []cli.Flag{
+		internal.DebugFlag,
 		noTTYFlag,
 		userFlag,
 	},
-	Aliases:   []string{"r"},
+	Before:       internal.SubCommandBefore,
-	ArgsUsage: "<service> <args>...",
+	ArgsUsage:    "<domain> <service> <args>...",
 	Usage:        "Run a command in a service container",
+	BashComplete: autocomplete.AppNameComplete,
 	Action: func(c *cli.Context) error {
 		app := internal.ValidateApp(c)
 
-		if c.Args().Len() < 2 {
+		if len(c.Args()) < 2 {
 			internal.ShowSubcommandHelpAndError(c, errors.New("no <service> provided?"))
 		}
 
-		if c.Args().Len() < 3 {
+		if len(c.Args()) < 3 {
 			internal.ShowSubcommandHelpAndError(c, errors.New("no <args> provided?"))
 		}
 
@@ -55,18 +59,16 @@ var appRunCommand = &cli.Command{
 		}
 
 		serviceName := c.Args().Get(1)
+		stackAndServiceName := fmt.Sprintf("^%s_%s", app.StackName(), serviceName)
 		filters := filters.NewArgs()
-		filters.Add("name", fmt.Sprintf("%s_%s", app.StackName(), serviceName))
+		filters.Add("name", stackAndServiceName)
 
-		containers, err := cl.ContainerList(c.Context, types.ContainerListOptions{Filters: filters})
+		targetContainer, err := containerPkg.GetContainer(context.Background(), cl, filters, false)
 		if err != nil {
 			logrus.Fatal(err)
 		}
-		if len(containers) > 1 {
-			logrus.Fatalf("expected 1 container but got %d", len(containers))
-		}
 
-		cmd := c.Args().Slice()[2:]
+		cmd := c.Args()[2:]
 		execCreateOpts := types.ExecConfig{
 			AttachStderr: true,
 			AttachStdin:  true,
@@ -83,41 +85,16 @@ var appRunCommand = &cli.Command{
 			execCreateOpts.Tty = false
 		}
 
-		// FIXME: an absolutely monumental hack to instantiate another command-line
+		// FIXME: avoid instantiating a new CLI
-		// client withing our command-line client so that we pass something down
-		// the tubes that satisfies the necessary interface requirements. We should
-		// refactor our vendored container code to not require all this cruft.  For
-		// now, It Works.
 		dcli, err := command.NewDockerCli()
 		if err != nil {
 			logrus.Fatal(err)
 		}
 
-		if err := container.RunExec(dcli, cl, containers[0].ID, &execCreateOpts); err != nil {
+		if err := container.RunExec(dcli, cl, targetContainer.ID, &execCreateOpts); err != nil {
 			logrus.Fatal(err)
 		}
 
 		return nil
 	},
-	BashComplete: func(c *cli.Context) {
-		switch c.NArg() {
-		case 0:
-			appNames, err := config.GetAppNames()
-			if err != nil {
-				logrus.Warn(err)
-			}
-			for _, a := range appNames {
-				fmt.Println(a)
-			}
-		case 1:
-			appName := c.Args().First()
-			serviceNames, err := config.GetAppServiceNames(appName)
-			if err != nil {
-				logrus.Warn(err)
-			}
-			for _, s := range serviceNames {
-				fmt.Println(s)
-			}
-		}
-	},
 }

cli/app/secret.go

@@ -1,41 +1,82 @@
 package app
 
 import (
+	"context"
 	"errors"
 	"fmt"
 	"os"
 	"strconv"
 
-	abraFormatter "coopcloud.tech/abra/cli/formatter"
 	"coopcloud.tech/abra/cli/internal"
+	"coopcloud.tech/abra/pkg/autocomplete"
 	"coopcloud.tech/abra/pkg/client"
 	"coopcloud.tech/abra/pkg/config"
+	"coopcloud.tech/abra/pkg/formatter"
+	"coopcloud.tech/abra/pkg/recipe"
 	"coopcloud.tech/abra/pkg/secret"
 	"github.com/docker/docker/api/types"
-	"github.com/docker/docker/api/types/filters"
+	dockerClient "github.com/docker/docker/client"
 	"github.com/sirupsen/logrus"
-	"github.com/urfave/cli/v2"
+	"github.com/urfave/cli"
 )
 
-var allSecrets bool
+var (
-var allSecretsFlag = &cli.BoolFlag{
+	allSecrets     bool
-	Name:        "all",
+	allSecretsFlag = &cli.BoolFlag{
-	Aliases:     []string{"A"},
+		Name:        "all, a",
-	Value:       false,
 		Destination: &allSecrets,
 		Usage:       "Generate all secrets",
 	}
+)
 
-var appSecretGenerateCommand = &cli.Command{
+var (
+	rmAllSecrets     bool
+	rmAllSecretsFlag = &cli.BoolFlag{
+		Name:        "all, a",
+		Destination: &rmAllSecrets,
+		Usage:       "Remove all secrets",
+	}
+)
+
+var appSecretGenerateCommand = cli.Command{
 	Name:      "generate",
 	Aliases:   []string{"g"},
 	Usage:     "Generate secrets",
-	ArgsUsage: "<secret> <version>",
+	ArgsUsage: "<domain> <secret> <version>",
-	Flags:     []cli.Flag{allSecretsFlag, internal.PassFlag},
+	Flags: []cli.Flag{
+		internal.DebugFlag,
+		allSecretsFlag,
+		internal.PassFlag,
+		internal.MachineReadableFlag,
+		internal.OfflineFlag,
+		internal.ChaosFlag,
+	},
+	Before:       internal.SubCommandBefore,
+	BashComplete: autocomplete.AppNameComplete,
 	Action: func(c *cli.Context) error {
 		app := internal.ValidateApp(c)
 
-		if c.Args().Len() == 1 && !allSecrets {
+		if err := recipe.EnsureExists(app.Recipe); err != nil {
+			logrus.Fatal(err)
+		}
+
+		if !internal.Chaos {
+			if err := recipe.EnsureIsClean(app.Recipe); err != nil {
+				logrus.Fatal(err)
+			}
+
+			if !internal.Offline {
+				if err := recipe.EnsureUpToDate(app.Recipe); err != nil {
+					logrus.Fatal(err)
+				}
+			}
+
+			if err := recipe.EnsureLatest(app.Recipe); err != nil {
+				logrus.Fatal(err)
+			}
+		}
+
+		if len(c.Args()) == 1 && !allSecrets {
 			err := errors.New("missing arguments <secret>/<version> or '--all'")
 			internal.ShowSubcommandHelpAndError(c, err)
 		}
@@ -45,33 +86,42 @@ var appSecretGenerateCommand = &cli.Command{
 			internal.ShowSubcommandHelpAndError(c, err)
 		}
 
-		secretsToCreate := make(map[string]string)
+		composeFiles, err := config.GetComposeFiles(app.Recipe, app.Env)
-		secretEnvVars := secret.ReadSecretEnvVars(app.Env)
+		if err != nil {
-		if allSecrets {
+			logrus.Fatal(err)
-			secretsToCreate = secretEnvVars
+		}
-		} else {
+
+		secrets, err := secret.ReadSecretsConfig(app.Path, composeFiles, app.Recipe)
+		if err != nil {
+			logrus.Fatal(err)
+		}
+
+		if !allSecrets {
 			secretName := c.Args().Get(1)
 			secretVersion := c.Args().Get(2)
-			matches := false
+			s, ok := secrets[secretName]
-			for sec := range secretEnvVars {
+			if !ok {
-				parsed := secret.ParseSecretEnvVarName(sec)
+				logrus.Fatalf("%s doesn't exist in the env config?", secretName)
-				if secretName == parsed {
-					secretsToCreate[sec] = secretVersion
 			}
-			}
+			s.Version = secretVersion
-			if !matches {
+			secrets = map[string]secret.SecretValue{
-				logrus.Fatalf("'%s' doesn't exist in the env config?", secretName)
+				secretName: s,
 			}
 		}
 
-		secretVals, err := secret.GenerateSecrets(secretsToCreate, app.StackName(), app.Server)
+		cl, err := client.New(app.Server)
+		if err != nil {
+			logrus.Fatal(err)
+		}
+
+		secretVals, err := secret.GenerateSecrets(cl, secrets, app.StackName(), app.Server)
 		if err != nil {
 			logrus.Fatal(err)
 		}
 
 		if internal.Pass {
 			for name, data := range secretVals {
-				if err := secret.PassInsertSecret(data, name, app.StackName(), app.Server); err != nil {
+				if err := secret.PassInsertSecret(data, name, app.Name, app.Server); err != nil {
 					logrus.Fatal(err)
 				}
 			}
@@ -83,41 +133,70 @@ var appSecretGenerateCommand = &cli.Command{
 		}
 
 		tableCol := []string{"name", "value"}
-		table := abraFormatter.CreateTable(tableCol)
+		table := formatter.CreateTable(tableCol)
 		for name, val := range secretVals {
 			table.Append([]string{name, val})
 		}
+
+		if internal.MachineReadable {
+			table.JSONRender()
+		} else {
 			table.Render()
-		logrus.Warn("generated secrets are not shown again, please take note of them *now*")
+		}
+		logrus.Warn("generated secrets are not shown again, please take note of them NOW")
 
 		return nil
 	},
 }
 
-var appSecretInsertCommand = &cli.Command{
+var appSecretInsertCommand = cli.Command{
 	Name:    "insert",
 	Aliases: []string{"i"},
 	Usage:   "Insert secret",
-	Flags:     []cli.Flag{internal.PassFlag},
+	Flags: []cli.Flag{
-	ArgsUsage: "<secret> <version> <data>",
+		internal.DebugFlag,
+		internal.PassFlag,
+	},
+	Before:       internal.SubCommandBefore,
+	ArgsUsage:    "<domain> <secret-name> <version> <data>",
+	BashComplete: autocomplete.AppNameComplete,
+	Description: `
+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" for more).
+
+Example:
+
+    abra app secret insert myapp db_pass v1 mySecretPassword
+
+`,
 	Action: func(c *cli.Context) error {
 		app := internal.ValidateApp(c)
 
-		if c.Args().Len() != 4 {
+		if len(c.Args()) != 4 {
 			internal.ShowSubcommandHelpAndError(c, errors.New("missing arguments?"))
 		}
 
+		cl, err := client.New(app.Server)
+		if err != nil {
+			logrus.Fatal(err)
+		}
+
 		name := c.Args().Get(1)
 		version := c.Args().Get(2)
 		data := c.Args().Get(3)
 
 		secretName := fmt.Sprintf("%s_%s_%s", app.StackName(), name, version)
-		if err := client.StoreSecret(secretName, data, app.Server); err != nil {
+		if err := client.StoreSecret(cl, secretName, data, app.Server); err != nil {
 			logrus.Fatal(err)
 		}
 
+		logrus.Infof("%s successfully stored on server", secretName)
+
 		if internal.Pass {
-			if err := secret.PassInsertSecret(data, name, app.StackName(), app.Server); err != nil {
+			if err := secret.PassInsertSecret(data, name, app.Name, app.Server); err != nil {
 				logrus.Fatal(err)
 			}
 		}
@@ -126,20 +205,85 @@ var appSecretInsertCommand = &cli.Command{
 	},
 }
 
-var appSecretRmCommand = &cli.Command{
+// secretRm removes a secret.
+func secretRm(cl *dockerClient.Client, app config.App, secretName, parsed string) error {
+	if err := cl.SecretRemove(context.Background(), secretName); err != nil {
+		return err
+	}
+
+	logrus.Infof("deleted %s successfully from server", secretName)
+
+	if internal.PassRemove {
+		if err := secret.PassRmSecret(parsed, app.StackName(), app.Server); err != nil {
+			return err
+		}
+
+		logrus.Infof("deleted %s successfully from local pass store", secretName)
+	}
+
+	return nil
+}
+
+var appSecretRmCommand = cli.Command{
 	Name:    "remove",
-	Usage:     "Remove a secret",
 	Aliases: []string{"rm"},
-	Flags:     []cli.Flag{allSecretsFlag, internal.PassFlag},
+	Usage:   "Remove a secret",
-	ArgsUsage: "<secret>",
+	Flags: []cli.Flag{
+		internal.DebugFlag,
+		internal.NoInputFlag,
+		rmAllSecretsFlag,
+		internal.PassRemoveFlag,
+		internal.OfflineFlag,
+		internal.ChaosFlag,
+	},
+	Before:       internal.SubCommandBefore,
+	ArgsUsage:    "<domain> [<secret-name>]",
+	BashComplete: autocomplete.AppNameComplete,
+	Description: `
+This command removes app secrets.
+
+Example:
+
+    abra app secret remove myapp db_pass
+`,
 	Action: func(c *cli.Context) error {
 		app := internal.ValidateApp(c)
 
-		if c.Args().Get(1) != "" && allSecrets {
+		if err := recipe.EnsureExists(app.Recipe); err != nil {
-			internal.ShowSubcommandHelpAndError(c, errors.New("cannot use '<secret>' and '--all' together"))
+			logrus.Fatal(err)
 		}
 
-		if c.Args().Get(1) == "" && !allSecrets {
+		if !internal.Chaos {
+			if err := recipe.EnsureIsClean(app.Recipe); err != nil {
+				logrus.Fatal(err)
+			}
+
+			if !internal.Offline {
+				if err := recipe.EnsureUpToDate(app.Recipe); err != nil {
+					logrus.Fatal(err)
+				}
+			}
+
+			if err := recipe.EnsureLatest(app.Recipe); err != nil {
+				logrus.Fatal(err)
+			}
+		}
+
+		composeFiles, err := config.GetComposeFiles(app.Recipe, app.Env)
+		if err != nil {
+			logrus.Fatal(err)
+		}
+
+		secrets, err := secret.ReadSecretsConfig(app.Path, composeFiles, app.Recipe)
+		if err != nil {
+			logrus.Fatal(err)
+		}
+
+		if c.Args().Get(1) != "" && rmAllSecrets {
+			internal.ShowSubcommandHelpAndError(c, errors.New("cannot use '<secret-name>' and '--all' together"))
+		}
+
+		if c.Args().Get(1) == "" && !rmAllSecrets {
 			internal.ShowSubcommandHelpAndError(c, errors.New("no secret(s) specified?"))
 		}
 
@@ -148,63 +292,12 @@ var appSecretRmCommand = &cli.Command{
 			logrus.Fatal(err)
 		}
 
-		filters := filters.NewArgs()
+		filters, err := app.Filters(false, false)
-		filters.Add("name", app.StackName())
-		secretList, err := cl.SecretList(c.Context, types.SecretListOptions{Filters: filters})
 		if err != nil {
 			logrus.Fatal(err)
 		}
 
-		secretToRm := c.Args().Get(1)
+		secretList, err := cl.SecretList(context.Background(), types.SecretListOptions{Filters: filters})
-		for _, cont := range secretList {
-			secretName := cont.Spec.Annotations.Name
-			parsed := secret.ParseGeneratedSecretName(secretName, app)
-			if allSecrets {
-				if err := cl.SecretRemove(c.Context, secretName); err != nil {
-					logrus.Fatal(err)
-				}
-				if internal.Pass {
-					if err := secret.PassRmSecret(parsed, app.StackName(), app.Server); err != nil {
-						logrus.Fatal(err)
-					}
-				}
-			} else {
-				if parsed == secretToRm {
-					if err := cl.SecretRemove(c.Context, secretName); err != nil {
-						logrus.Fatal(err)
-					}
-					if internal.Pass {
-						if err := secret.PassRmSecret(parsed, app.StackName(), app.Server); err != nil {
-							logrus.Fatal(err)
-						}
-					}
-				}
-			}
-		}
-
-		return nil
-	},
-}
-
-var appSecretLsCommand = &cli.Command{
-	Name:    "list",
-	Usage:   "List all secrets",
-	Aliases: []string{"ls"},
-	Action: func(c *cli.Context) error {
-		app := internal.ValidateApp(c)
-		secrets := secret.ReadSecretEnvVars(app.Env)
-
-		tableCol := []string{"Name", "Version", "Generated Name", "Created On Server"}
-		table := abraFormatter.CreateTable(tableCol)
-
-		cl, err := client.New(app.Server)
-		if err != nil {
-			logrus.Fatal(err)
-		}
-
-		filters := filters.NewArgs()
-		filters.Add("name", app.StackName())
-		secretList, err := cl.SecretList(c.Context, types.SecretListOptions{Filters: filters})
 		if err != nil {
 			logrus.Fatal(err)
 		}
@@ -214,44 +307,119 @@ var appSecretLsCommand = &cli.Command{
 			remoteSecretNames[cont.Spec.Annotations.Name] = true
 		}
 
-		for sec := range secrets {
+		match := false
-			createdRemote := false
+		secretToRm := c.Args().Get(1)
-			secretName := secret.ParseSecretEnvVarName(sec)
+		for secretName, val := range secrets {
-			secVal, err := secret.ParseSecretEnvVarValue(secrets[sec])
+			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 {
+							logrus.Fatal(err)
+						}
+
+						return nil
+					}
+				} else {
+					match = true
+
+					if err := secretRm(cl, app, secretRemoteName, secretName); err != nil {
+						logrus.Fatal(err)
+					}
+				}
+			}
+		}
+
+		if !match && secretToRm != "" {
+			logrus.Fatalf("%s doesn't exist on server?", secretToRm)
+		}
+
+		if !match {
+			logrus.Fatal("no secrets to remove?")
+		}
+
+		return nil
+	},
+}
+
+var appSecretLsCommand = cli.Command{
+	Name:    "list",
+	Aliases: []string{"ls"},
+	Flags: []cli.Flag{
+		internal.DebugFlag,
+		internal.OfflineFlag,
+		internal.ChaosFlag,
+		internal.MachineReadableFlag,
+	},
+	Before:       internal.SubCommandBefore,
+	Usage:        "List all secrets",
+	BashComplete: autocomplete.AppNameComplete,
+	Action: func(c *cli.Context) error {
+		app := internal.ValidateApp(c)
+
+		if err := recipe.EnsureExists(app.Recipe); err != nil {
+			logrus.Fatal(err)
+		}
+
+		if !internal.Chaos {
+			if err := recipe.EnsureIsClean(app.Recipe); err != nil {
+				logrus.Fatal(err)
+			}
+
+			if !internal.Offline {
+				if err := recipe.EnsureUpToDate(app.Recipe); err != nil {
+					logrus.Fatal(err)
+				}
+			}
+
+			if err := recipe.EnsureLatest(app.Recipe); err != nil {
+				logrus.Fatal(err)
+			}
+		}
+
+		cl, err := client.New(app.Server)
 		if err != nil {
 			logrus.Fatal(err)
 		}
-			secretRemoteName := fmt.Sprintf("%s_%s_%s", app.StackName(), secretName, secVal.Version)
+
-			if _, ok := remoteSecretNames[secretRemoteName]; ok {
+		tableCol := []string{"Name", "Version", "Generated Name", "Created On Server"}
-				createdRemote = true
+		table := formatter.CreateTable(tableCol)
+
+		secStats, err := secret.PollSecretsStatus(cl, app)
+		if err != nil {
+			logrus.Fatal(err)
+		}
+
+		for _, secStat := range secStats {
+			tableRow := []string{
+				secStat.LocalName,
+				secStat.Version,
+				secStat.RemoteName,
+				strconv.FormatBool(secStat.CreatedOnRemote),
 			}
-			tableRow := []string{secretName, secVal.Version, secretRemoteName, strconv.FormatBool(createdRemote)}
 			table.Append(tableRow)
 		}
 
+		if table.NumLines() > 0 {
+			if internal.MachineReadable {
+				table.JSONRender()
+			} else {
 				table.Render()
+			}
+		} else {
+			logrus.Warnf("no secrets stored for %s", app.Name)
+		}
+
 		return nil
 	},
-	BashComplete: func(c *cli.Context) {
-		appNames, err := config.GetAppNames()
-		if err != nil {
-			logrus.Warn(err)
-		}
-		if c.NArg() > 0 {
-			return
-		}
-		for _, a := range appNames {
-			fmt.Println(a)
-		}
-	},
 }
 
-var appSecretCommand = &cli.Command{
+var appSecretCommand = cli.Command{
 	Name:      "secret",
 	Aliases:   []string{"s"},
 	Usage:     "Manage app secrets",
-	ArgsUsage: "<command>",
+	ArgsUsage: "<domain>",
-	Subcommands: []*cli.Command{
+	Subcommands: []cli.Command{
 		appSecretGenerateCommand,
 		appSecretInsertCommand,
 		appSecretRmCommand,

cli/app/services.go

@@ -0,0 +1,80 @@
+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/service"
+	stack "coopcloud.tech/abra/pkg/upstream/stack"
+	"github.com/docker/docker/api/types"
+	"github.com/sirupsen/logrus"
+	"github.com/urfave/cli"
+)
+
+var appServicesCommand = cli.Command{
+	Name:      "services",
+	Aliases:   []string{"sr"},
+	Usage:     "Display all services of an app",
+	ArgsUsage: "<domain>",
+	Flags: []cli.Flag{
+		internal.DebugFlag,
+	},
+	Before:       internal.SubCommandBefore,
+	BashComplete: autocomplete.AppNameComplete,
+	Action: func(c *cli.Context) error {
+		app := internal.ValidateApp(c)
+
+		cl, err := client.New(app.Server)
+		if err != nil {
+			logrus.Fatal(err)
+		}
+
+		isDeployed, _, err := stack.IsDeployed(context.Background(), cl, app.StackName())
+		if err != nil {
+			logrus.Fatal(err)
+		}
+
+		if !isDeployed {
+			logrus.Fatalf("%s is not deployed?", app.Name)
+		}
+
+		filters, err := app.Filters(true, true)
+		if err != nil {
+			logrus.Fatal(err)
+		}
+
+		containers, err := cl.ContainerList(context.Background(), types.ContainerListOptions{Filters: filters})
+		if err != nil {
+			logrus.Fatal(err)
+		}
+
+		tableCol := []string{"service name", "image"}
+		table := formatter.CreateTable(tableCol)
+
+		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)
+
+			tableRow := []string{
+				serviceLongName,
+				formatter.RemoveSha(container.Image),
+			}
+			table.Append(tableRow)
+		}
+
+		table.Render()
+
+		return nil
+	},
+}

cli/app/undeploy.go

@@ -1,50 +1,138 @@
 package app
 
 import (
+	"context"
 	"fmt"
+	"time"
 
 	"coopcloud.tech/abra/cli/internal"
+	"coopcloud.tech/abra/pkg/autocomplete"
 	"coopcloud.tech/abra/pkg/client"
-	stack "coopcloud.tech/abra/pkg/client/stack"
 	"coopcloud.tech/abra/pkg/config"
+	"coopcloud.tech/abra/pkg/formatter"
+	stack "coopcloud.tech/abra/pkg/upstream/stack"
+	"github.com/docker/docker/api/types/filters"
+	dockerClient "github.com/docker/docker/client"
 	"github.com/sirupsen/logrus"
-	"github.com/urfave/cli/v2"
+	"github.com/urfave/cli"
 )
 
-var appUndeployCommand = &cli.Command{
+var prune bool
+
+var pruneFlag = &cli.BoolFlag{
+	Name:        "prune, p",
+	Destination: &prune,
+	Usage:       "Prunes unused containers, networks, and dangling images for an app",
+}
+
+// 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(c *cli.Context, cl *dockerClient.Client, app config.App) error {
+	stackName := app.StackName()
+	ctx := context.Background()
+
+	for {
+		logrus.Debugf("polling for %s stack, waiting to be undeployed...", stackName)
+
+		services, err := stack.GetStackServices(ctx, cl, stackName)
+		if err != nil {
+			return err
+		}
+
+		if len(services) == 0 {
+			logrus.Debugf("%s undeployed, moving on with pruning logic", stackName)
+			time.Sleep(time.Second) // give runtime more time to tear down related state
+			break
+		}
+
+		time.Sleep(time.Second)
+	}
+
+	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)
+	logrus.Infof("containers pruned: %d; space reclaimed: %s", len(cr.ContainersDeleted), cntSpaceReclaimed)
+
+	nr, err := cl.NetworksPrune(ctx, pruneFilters)
+	if err != nil {
+		return err
+	}
+
+	logrus.Infof("networks pruned: %d", len(nr.NetworksDeleted))
+
+	ir, err := cl.ImagesPrune(ctx, pruneFilters)
+	if err != nil {
+		return err
+	}
+
+	imgSpaceReclaimed := formatter.ByteCountSI(ir.SpaceReclaimed)
+	logrus.Infof("images pruned: %d; space reclaimed: %s", len(ir.ImagesDeleted), imgSpaceReclaimed)
+
+	return nil
+}
+
+var appUndeployCommand = cli.Command{
 	Name:      "undeploy",
-	Aliases: []string{"u"},
+	Aliases:   []string{"un"},
+	ArgsUsage: "<domain>",
+	Flags: []cli.Flag{
+		internal.DebugFlag,
+		internal.NoInputFlag,
+		pruneFlag,
+	},
+	Before:       internal.SubCommandBefore,
 	Usage:        "Undeploy an app",
+	BashComplete: autocomplete.AppNameComplete,
 	Description: `
-This does not destroy any of the application data. However, you should remain
+This does not destroy any of the application data.
-vigilant, as your swarm installation will consider any previously attached
+
-volumes as eligiblef or pruning once undeployed.
+However, you should remain vigilant, as your swarm installation will consider
+any previously attached volumes as eligible for pruning once undeployed.
+
+Passing "-p/--prune" does not remove those volumes.
 `,
 	Action: func(c *cli.Context) error {
 		app := internal.ValidateApp(c)
+		stackName := app.StackName()
 
 		cl, err := client.New(app.Server)
 		if err != nil {
 			logrus.Fatal(err)
 		}
 
-		rmOpts := stack.Remove{Namespaces: []string{app.StackName()}}
+		logrus.Debugf("checking whether %s is already deployed", stackName)
-		if err := stack.RunRemove(c.Context, cl, rmOpts); err != nil {
+
+		isDeployed, deployedVersion, err := stack.IsDeployed(context.Background(), cl, stackName)
+		if err != nil {
 			logrus.Fatal(err)
 		}
 
+		if !isDeployed {
+			logrus.Fatalf("%s is not deployed?", app.Name)
+		}
+
+		if err := internal.DeployOverview(app, deployedVersion, "continue with undeploy?"); err != nil {
+			logrus.Fatal(err)
+		}
+
+		rmOpts := stack.Remove{Namespaces: []string{app.StackName()}}
+		if err := stack.RunRemove(context.Background(), cl, rmOpts); err != nil {
+			logrus.Fatal(err)
+		}
+
+		if prune {
+			if err := pruneApp(c, cl, app); err != nil {
+				logrus.Fatal(err)
+			}
+		}
+
 		return nil
 	},
-	BashComplete: func(c *cli.Context) {
-		appNames, err := config.GetAppNames()
-		if err != nil {
-			logrus.Warn(err)
-		}
-		if c.NArg() > 0 {
-			return
-		}
-		for _, a := range appNames {
-			fmt.Println(a)
-		}
-	},
 }

cli/app/upgrade.go

@@ -0,0 +1,296 @@
+package app
+
+import (
+	"context"
+	"fmt"
+
+	"coopcloud.tech/abra/cli/internal"
+	"coopcloud.tech/abra/pkg/autocomplete"
+	"coopcloud.tech/abra/pkg/client"
+	"coopcloud.tech/abra/pkg/config"
+	"coopcloud.tech/abra/pkg/lint"
+	"coopcloud.tech/abra/pkg/recipe"
+	recipePkg "coopcloud.tech/abra/pkg/recipe"
+	stack "coopcloud.tech/abra/pkg/upstream/stack"
+	"coopcloud.tech/tagcmp"
+	"github.com/AlecAivazis/survey/v2"
+	"github.com/sirupsen/logrus"
+	"github.com/urfave/cli"
+)
+
+var appUpgradeCommand = cli.Command{
+	Name:      "upgrade",
+	Aliases:   []string{"up"},
+	Usage:     "Upgrade an app",
+	ArgsUsage: "<domain> [<version>]",
+	Flags: []cli.Flag{
+		internal.DebugFlag,
+		internal.NoInputFlag,
+		internal.ForceFlag,
+		internal.ChaosFlag,
+		internal.NoDomainChecksFlag,
+		internal.DontWaitConvergeFlag,
+		internal.OfflineFlag,
+	},
+	Before: internal.SubCommandBefore,
+	Description: `
+Upgrade an app. You can use it to choose and roll out a new upgrade to an
+existing app.
+
+This command specifically supports incrementing the version of running apps, as
+opposed to "abra app deploy <domain>" which will not change the version of a
+deployed app.
+
+You may pass "--force/-f" to upgrade to the same version again. This can be
+useful if the container runtime has gotten into a weird state.
+
+This action could be destructive, please ensure you have a copy of your app
+data beforehand.
+
+Chaos mode ("--chaos") will deploy your local checkout of a recipe as-is,
+including unstaged changes and can be useful for live hacking and testing new
+recipes.
+`,
+	BashComplete: autocomplete.AppNameComplete,
+	Action: func(c *cli.Context) error {
+		app := internal.ValidateApp(c)
+		stackName := app.StackName()
+
+		specificVersion := c.Args().Get(1)
+		if specificVersion != "" && internal.Chaos {
+			logrus.Fatal("cannot use <version> and --chaos together")
+		}
+
+		if !internal.Chaos {
+			if err := recipe.EnsureIsClean(app.Recipe); err != nil {
+				logrus.Fatal(err)
+			}
+
+			if !internal.Offline {
+				if err := recipe.EnsureUpToDate(app.Recipe); err != nil {
+					logrus.Fatal(err)
+				}
+			}
+
+			if err := recipe.EnsureLatest(app.Recipe); err != nil {
+				logrus.Fatal(err)
+			}
+		}
+
+		recipe, err := recipePkg.Get(app.Recipe, internal.Offline)
+		if err != nil {
+			logrus.Fatal(err)
+		}
+
+		if err := lint.LintForErrors(recipe); err != nil {
+			logrus.Fatal(err)
+		}
+
+		logrus.Debugf("checking whether %s is already deployed", stackName)
+
+		cl, err := client.New(app.Server)
+		if err != nil {
+			logrus.Fatal(err)
+		}
+
+		isDeployed, deployedVersion, err := stack.IsDeployed(context.Background(), cl, stackName)
+		if err != nil {
+			logrus.Fatal(err)
+		}
+
+		if !isDeployed {
+			logrus.Fatalf("%s is not deployed?", app.Name)
+		}
+
+		catl, err := recipePkg.ReadRecipeCatalogue(internal.Offline)
+		if err != nil {
+			logrus.Fatal(err)
+		}
+
+		versions, err := recipePkg.GetRecipeCatalogueVersions(app.Recipe, catl)
+		if err != nil {
+			logrus.Fatal(err)
+		}
+
+		if len(versions) == 0 && !internal.Chaos {
+			logrus.Warn("no published versions in catalogue, trying local recipe repository")
+			recipeVersions, err := recipePkg.GetRecipeVersions(app.Recipe, internal.Offline)
+			if err != nil {
+				logrus.Warn(err)
+			}
+			for _, recipeVersion := range recipeVersions {
+				for version := range recipeVersion {
+					versions = append(versions, version)
+				}
+			}
+		}
+
+		var availableUpgrades []string
+		if deployedVersion == "unknown" {
+			availableUpgrades = versions
+			logrus.Warnf("failed to determine deployed version of %s", app.Name)
+		}
+
+		if specificVersion != "" {
+			parsedDeployedVersion, err := tagcmp.Parse(deployedVersion)
+			if err != nil {
+				logrus.Fatal(err)
+			}
+			parsedSpecificVersion, err := tagcmp.Parse(specificVersion)
+			if err != nil {
+				logrus.Fatal(err)
+			}
+			if parsedSpecificVersion.IsLessThan(parsedDeployedVersion) || parsedSpecificVersion.Equals(parsedDeployedVersion) {
+				logrus.Fatalf("%s is not an upgrade for %s?", deployedVersion, specificVersion)
+			}
+			availableUpgrades = append(availableUpgrades, specificVersion)
+		}
+
+		parsedDeployedVersion, err := tagcmp.Parse(deployedVersion)
+		if err != nil {
+			logrus.Fatal(err)
+		}
+
+		if deployedVersion != "unknown" && !internal.Chaos && specificVersion == "" {
+			for _, version := range versions {
+				parsedVersion, err := tagcmp.Parse(version)
+				if err != nil {
+					logrus.Fatal(err)
+				}
+				if parsedVersion.IsGreaterThan(parsedDeployedVersion) && !(parsedVersion.Equals(parsedDeployedVersion)) {
+					availableUpgrades = append(availableUpgrades, version)
+				}
+			}
+
+			if len(availableUpgrades) == 0 && !internal.Force {
+				logrus.Infof("no available upgrades, you're on latest (%s) ✌️", deployedVersion)
+				return nil
+			}
+		}
+
+		var chosenUpgrade string
+		if len(availableUpgrades) > 0 && !internal.Chaos {
+			if internal.Force || internal.NoInput || specificVersion != "" {
+				chosenUpgrade = availableUpgrades[len(availableUpgrades)-1]
+				logrus.Debugf("choosing %s as version to upgrade to", chosenUpgrade)
+			} else {
+				prompt := &survey.Select{
+					Message: fmt.Sprintf("Please select an upgrade (current version: %s):", deployedVersion),
+					Options: internal.ReverseStringList(availableUpgrades),
+				}
+				if err := survey.AskOne(prompt, &chosenUpgrade); err != nil {
+					return err
+				}
+			}
+		}
+
+		if internal.Force && chosenUpgrade == "" {
+			logrus.Warnf("%s is already upgraded to latest but continuing (--force/--chaos)", app.Name)
+			chosenUpgrade = deployedVersion
+		}
+
+		// if release notes written after git tag published, read them before we
+		// check out the tag and then they'll appear to be missing. this covers
+		// when we obviously will forget to write release notes before publishing
+		var releaseNotes string
+		for _, version := range versions {
+			parsedVersion, err := tagcmp.Parse(version)
+			if err != nil {
+				logrus.Fatal(err)
+			}
+			parsedChosenUpgrade, err := tagcmp.Parse(chosenUpgrade)
+			if err != nil {
+				logrus.Fatal(err)
+			}
+
+			if !(parsedVersion.Equals(parsedDeployedVersion)) && parsedVersion.IsLessThan(parsedChosenUpgrade) {
+				note, err := internal.GetReleaseNotes(app.Recipe, version)
+				if err != nil {
+					return err
+				}
+				if note != "" {
+					releaseNotes += fmt.Sprintf("%s\n", note)
+				}
+			}
+		}
+
+		if !internal.Chaos {
+			if err := recipePkg.EnsureVersion(app.Recipe, chosenUpgrade); err != nil {
+				logrus.Fatal(err)
+			}
+		}
+
+		if internal.Chaos {
+			logrus.Warn("chaos mode engaged")
+			var err error
+			chosenUpgrade, err = recipePkg.ChaosVersion(app.Recipe)
+			if err != nil {
+				logrus.Fatal(err)
+			}
+		}
+
+		abraShPath := fmt.Sprintf("%s/%s/%s", config.RECIPES_DIR, app.Recipe, "abra.sh")
+		abraShEnv, err := config.ReadAbraShEnvVars(abraShPath)
+		if err != nil {
+			logrus.Fatal(err)
+		}
+		for k, v := range abraShEnv {
+			app.Env[k] = v
+		}
+
+		composeFiles, err := config.GetComposeFiles(app.Recipe, app.Env)
+		if err != nil {
+			logrus.Fatal(err)
+		}
+		deployOpts := stack.Deploy{
+			Composefiles: composeFiles,
+			Namespace:    stackName,
+			Prune:        false,
+			ResolveImage: stack.ResolveImageAlways,
+		}
+		compose, err := config.GetAppComposeConfig(app.Name, deployOpts, app.Env)
+		if err != nil {
+			logrus.Fatal(err)
+		}
+		config.ExposeAllEnv(stackName, compose, app.Env)
+		config.SetRecipeLabel(compose, stackName, app.Recipe)
+		config.SetChaosLabel(compose, stackName, internal.Chaos)
+		config.SetChaosVersionLabel(compose, stackName, chosenUpgrade)
+		config.SetUpdateLabel(compose, stackName, app.Env)
+
+		envVars, err := config.CheckEnv(app)
+		if err != nil {
+			logrus.Fatal(err)
+		}
+
+		for _, envVar := range envVars {
+			if !envVar.Present {
+				logrus.Warnf("env var %s missing from %s.env, present in recipe .env.sample", envVar.Name, app.Domain)
+			}
+		}
+
+		if err := internal.NewVersionOverview(app, deployedVersion, chosenUpgrade, releaseNotes); err != nil {
+			logrus.Fatal(err)
+		}
+
+		stack.WaitTimeout, err = config.GetTimeoutFromLabel(compose, stackName)
+		if err != nil {
+			logrus.Fatal(err)
+		}
+		logrus.Debugf("set waiting timeout to %d s", stack.WaitTimeout)
+
+		if err := stack.RunDeploy(cl, deployOpts, compose, stackName, internal.DontWaitConverge); err != nil {
+			logrus.Fatal(err)
+		}
+
+		postDeployCmds, ok := app.Env["POST_UPGRADE_CMDS"]
+		if ok && !internal.DontWaitConverge {
+			logrus.Debugf("run the following post-deploy commands: %s", postDeployCmds)
+			if err := internal.PostCmds(cl, app, postDeployCmds); err != nil {
+				logrus.Fatalf("attempting to run post deploy commands, saw: %s", err)
+			}
+		}
+
+		return nil
+	},
+}

cli/app/version.go

@@ -1,108 +1,117 @@
 package app
 
 import (
-	"fmt"
+	"context"
 	"sort"
-	"strings"
 
-	abraFormatter "coopcloud.tech/abra/cli/formatter"
 	"coopcloud.tech/abra/cli/internal"
-	appPkg "coopcloud.tech/abra/pkg/app"
+	"coopcloud.tech/abra/pkg/autocomplete"
-	"coopcloud.tech/abra/pkg/client/stack"
+	"coopcloud.tech/abra/pkg/client"
-	"coopcloud.tech/abra/pkg/config"
+	"coopcloud.tech/abra/pkg/formatter"
+	"coopcloud.tech/abra/pkg/recipe"
+	"coopcloud.tech/abra/pkg/upstream/stack"
 	"github.com/docker/distribution/reference"
+	"github.com/olekukonko/tablewriter"
 	"github.com/sirupsen/logrus"
-	"github.com/urfave/cli/v2"
+	"github.com/urfave/cli"
 )
 
+func sortServiceByName(versions [][]string) func(i, j int) bool {
+	return func(i, j int) bool {
+		// NOTE(d1): corresponds to the `tableCol` definition below
+		if versions[i][1] == "app" {
+			return true
+		}
+		return versions[i][1] < versions[j][1]
+	}
+}
+
 // getImagePath returns the image name
 func getImagePath(image string) (string, error) {
 	img, err := reference.ParseNormalizedNamed(image)
 	if err != nil {
 		return "", err
 	}
+
 	path := reference.Path(img)
-	if strings.Contains(path, "library") {
+
-		path = strings.Split(path, "/")[1]
+	path = formatter.StripTagMeta(path)
-	}
+
-	logrus.Debugf("parsed '%s' from '%s'", path, image)
+	logrus.Debugf("parsed %s from %s", path, image)
+
 	return path, nil
 }
 
-var appVersionCommand = &cli.Command{
+var appVersionCommand = cli.Command{
 	Name:      "version",
 	Aliases:   []string{"v"},
-	Usage:   "Show version of all services in app",
+	ArgsUsage: "<domain>",
+	Flags: []cli.Flag{
+		internal.DebugFlag,
+		internal.NoInputFlag,
+		internal.OfflineFlag,
+	},
+	Before:       internal.SubCommandBefore,
+	Usage:        "Show version info of a deployed app",
+	BashComplete: autocomplete.AppNameComplete,
 	Action: func(c *cli.Context) error {
 		app := internal.ValidateApp(c)
+		stackName := app.StackName()
 
-		composeFiles, err := config.GetAppComposeFiles(app.Type, app.Env)
+		cl, err := client.New(app.Server)
-		if err != nil {
-			logrus.Fatal(err)
-		}
-		opts := stack.Deploy{Composefiles: composeFiles}
-		compose, err := config.GetAppComposeConfig(app.Type, opts, app.Env)
 		if err != nil {
 			logrus.Fatal(err)
 		}
 
-		ch := make(chan stack.StackStatus, len(compose.Services))
+		logrus.Debugf("checking whether %s is already deployed", stackName)
-		for _, service := range compose.Services {
-			label := fmt.Sprintf("coop-cloud.%s.%s.version", app.StackName(), service.Name)
-			go func(s string, l string) {
-				ch <- stack.GetDeployedServicesByLabel(s, l)
-			}(app.Server, label)
-		}
 
-		tableCol := []string{"name", "image", "version", "digest"}
+		isDeployed, deployedVersion, err := stack.IsDeployed(context.Background(), cl, stackName)
-		table := abraFormatter.CreateTable(tableCol)
-
-		statuses := make(map[string]stack.StackStatus)
-		for range compose.Services {
-			status := <-ch
-			if len(status.Services) > 0 {
-				serviceName := appPkg.ParseServiceName(status.Services[0].Spec.Name)
-				statuses[serviceName] = status
-			}
-		}
-
-		sort.SliceStable(compose.Services, func(i, j int) bool {
-			return compose.Services[i].Name < compose.Services[j].Name
-		})
-
-		for _, service := range compose.Services {
-			if status, ok := statuses[service.Name]; ok {
-				statusService := status.Services[0]
-				label := fmt.Sprintf("coop-cloud.%s.%s.version", app.StackName(), service.Name)
-				version, digest := appPkg.ParseVersionLabel(statusService.Spec.Labels[label])
-				image, err := getImagePath(statusService.Spec.Labels["com.docker.stack.image"])
 		if err != nil {
 			logrus.Fatal(err)
 		}
-				table.Append([]string{service.Name, image, version, digest})
+
-				continue
+		if !isDeployed {
+			logrus.Fatalf("%s is not deployed?", app.Name)
 		}
 
-			image, err := getImagePath(service.Image)
+		if deployedVersion == "unknown" {
+			logrus.Fatalf("failed to determine version of deployed %s", app.Name)
+		}
+
+		recipeMeta, err := recipe.GetRecipeMeta(app.Recipe, internal.Offline)
 		if err != nil {
 			logrus.Fatal(err)
 		}
-			table.Append([]string{service.Name, image, "?", "?"})
+
+		versionsMeta := make(map[string]recipe.ServiceMeta)
+		for _, recipeVersion := range recipeMeta.Versions {
+			if currentVersion, exists := recipeVersion[deployedVersion]; exists {
+				versionsMeta = currentVersion
+			}
 		}
 
+		if len(versionsMeta) == 0 {
+			logrus.Fatalf("could not retrieve deployed version (%s) from recipe catalogue?", deployedVersion)
+		}
+
+		tableCol := []string{"version", "service", "image", "tag"}
+		table := formatter.CreateTable(tableCol)
+
+		var versions [][]string
+		for serviceName, versionMeta := range versionsMeta {
+			versions = append(versions, []string{deployedVersion, serviceName, versionMeta.Image, versionMeta.Tag})
+		}
+
+		sort.Slice(versions, sortServiceByName(versions))
+
+		for _, version := range versions {
+			table.Append(version)
+		}
+
+		table.SetAutoMergeCellsByColumnIndex([]int{0})
+		table.SetAlignment(tablewriter.ALIGN_LEFT)
 		table.Render()
+
 		return nil
 	},
-	BashComplete: func(c *cli.Context) {
-		appNames, err := config.GetAppNames()
-		if err != nil {
-			logrus.Warn(err)
-		}
-		if c.NArg() > 0 {
-			return
-		}
-		for _, a := range appNames {
-			fmt.Println(a)
-		}
-	},
 }

cli/app/volume.go

@@ -1,105 +1,156 @@
 package app
 
 import (
-	"fmt"
+	"context"
 
-	abraFormatter "coopcloud.tech/abra/cli/formatter"
 	"coopcloud.tech/abra/cli/internal"
+	"coopcloud.tech/abra/pkg/autocomplete"
 	"coopcloud.tech/abra/pkg/client"
-	"coopcloud.tech/abra/pkg/config"
+	"coopcloud.tech/abra/pkg/formatter"
+	"coopcloud.tech/abra/pkg/upstream/stack"
 	"github.com/AlecAivazis/survey/v2"
 	"github.com/sirupsen/logrus"
-	"github.com/urfave/cli/v2"
+	"github.com/urfave/cli"
 )
 
-var appVolumeListCommand = &cli.Command{
+var appVolumeListCommand = cli.Command{
 	Name:      "list",
-	Usage:   "List volumes associated with an app",
 	Aliases:   []string{"ls"},
+	ArgsUsage: "<domain>",
+	Flags: []cli.Flag{
+		internal.DebugFlag,
+		internal.NoInputFlag,
+	},
+	Before:       internal.SubCommandBefore,
+	Usage:        "List volumes associated with an app",
+	BashComplete: autocomplete.AppNameComplete,
 	Action: func(c *cli.Context) error {
 		app := internal.ValidateApp(c)
 
-		volumeList, err := client.GetVolumes(c.Context, app.Server, app.Name)
+		cl, err := client.New(app.Server)
 		if err != nil {
 			logrus.Fatal(err)
 		}
 
-		table := abraFormatter.CreateTable([]string{"driver", "volume name"})
+		filters, err := app.Filters(false, true)
+		if err != nil {
+			logrus.Fatal(err)
+		}
+
+		volumeList, err := client.GetVolumes(cl, context.Background(), app.Server, filters)
+		if err != nil {
+			logrus.Fatal(err)
+		}
+
+		table := formatter.CreateTable([]string{"name", "created", "mounted"})
 		var volTable [][]string
 		for _, volume := range volumeList {
-			volRow := []string{
+			volRow := []string{volume.Name, volume.CreatedAt, volume.Mountpoint}
-				volume.Driver,
-				volume.Name,
-			}
 			volTable = append(volTable, volRow)
 		}
 
 		table.AppendBulk(volTable)
+
+		if table.NumLines() > 0 {
 			table.Render()
+		} else {
+			logrus.Warnf("no volumes created for %s", app.Name)
+		}
 
 		return nil
 	},
 }
 
-var appVolumeRemoveCommand = &cli.Command{
+var appVolumeRemoveCommand = cli.Command{
 	Name:  "remove",
 	Usage: "Remove volume(s) associated with an app",
+	Description: `
+This command supports removing 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.
+`,
+	ArgsUsage: "<domain>",
 	Aliases:   []string{"rm"},
 	Flags: []cli.Flag{
+		internal.DebugFlag,
+		internal.NoInputFlag,
 		internal.ForceFlag,
 	},
+	Before:       internal.SubCommandBefore,
+	BashComplete: autocomplete.AppNameComplete,
 	Action: func(c *cli.Context) error {
 		app := internal.ValidateApp(c)
 
-		volumeList, err := client.GetVolumes(c.Context, app.Server, app.Name)
+		cl, err := client.New(app.Server)
+		if err != nil {
+			logrus.Fatal(err)
+		}
+
+		isDeployed, _, err := stack.IsDeployed(context.Background(), cl, app.StackName())
+		if err != nil {
+			logrus.Fatal(err)
+		}
+
+		if isDeployed {
+			logrus.Fatalf("%s is still deployed. Run \"abra app undeploy %s\"", app.Name, app.Name)
+		}
+
+		filters, err := app.Filters(false, true)
+		if err != nil {
+			logrus.Fatal(err)
+		}
+
+		volumeList, err := client.GetVolumes(cl, context.Background(), app.Server, filters)
 		if err != nil {
 			logrus.Fatal(err)
 		}
 		volumeNames := client.GetVolumeNames(volumeList)
 
 		var volumesToRemove []string
-		if !internal.Force {
+		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 {
 				logrus.Fatal(err)
 			}
-		} else {
+		}
+
+		if internal.Force || internal.NoInput {
 			volumesToRemove = volumeNames
 		}
 
-		err = client.RemoveVolumes(c.Context, app.Server, volumesToRemove, internal.Force)
+		if len(volumesToRemove) > 0 {
+			err = client.RemoveVolumes(cl, context.Background(), app.Server, volumesToRemove, internal.Force)
 			if err != nil {
 				logrus.Fatal(err)
 			}
 
 			logrus.Info("volumes removed successfully")
+		} else {
+			logrus.Info("no volumes removed")
+		}
 
 		return nil
 	},
-	BashComplete: func(c *cli.Context) {
-		appNames, err := config.GetAppNames()
-		if err != nil {
-			logrus.Warn(err)
-		}
-		if c.NArg() > 0 {
-			return
-		}
-		for _, a := range appNames {
-			fmt.Println(a)
-		}
-	},
 }
 
-var appVolumeCommand = &cli.Command{
+var appVolumeCommand = cli.Command{
 	Name:      "volume",
-	Aliases:   []string{"v"},
+	Aliases:   []string{"vl"},
 	Usage:     "Manage app volumes",
-	ArgsUsage: "<command>",
+	ArgsUsage: "<domain>",
-	Subcommands: []*cli.Command{
+	Subcommands: []cli.Command{
 		appVolumeListCommand,
 		appVolumeRemoveCommand,
 	},

cli/catalogue/catalogue.go

@@ -1,17 +1,223 @@
 package catalogue
 
 import (
-	"github.com/urfave/cli/v2"
+	"encoding/json"
+	"fmt"
+	"io/ioutil"
+	"path"
+
+	"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/recipe"
+	"github.com/go-git/go-git/v5"
+	"github.com/sirupsen/logrus"
+	"github.com/urfave/cli"
 )
 
+var catalogueGenerateCommand = cli.Command{
+	Name:    "generate",
+	Aliases: []string{"g"},
+	Usage:   "Generate the recipe catalogue",
+	Flags: []cli.Flag{
+		internal.DebugFlag,
+		internal.NoInputFlag,
+		internal.PublishFlag,
+		internal.DryFlag,
+		internal.SkipUpdatesFlag,
+		internal.ChaosFlag,
+		internal.OfflineFlag,
+	},
+	Before: internal.SubCommandBefore,
+	Description: `
+Generate a new copy of the recipe catalogue which can be found on:
+
+    https://recipes.coopcloud.tech (website that humans read)
+    https://recipes.coopcloud.tech/recipes.json (JSON that Abra reads)
+
+It polls the entire git.coopcloud.tech/coop-cloud/... recipe repository
+listing, parses README.md and git tags to produce recipe metadata which is
+loaded into the catalogue JSON file.
+
+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 have Abra log you in to avoid this. Pass
+"--user" and "--pass".
+
+Push your new release to git.coopcloud.tech with "-p/--publish". This requires
+that you have permission to git push to these repositories and have your SSH
+keys configured on your account.
+`,
+	ArgsUsage:    "[<recipe>]",
+	BashComplete: autocomplete.RecipeNameComplete,
+	Action: func(c *cli.Context) error {
+		recipeName := c.Args().First()
+
+		if recipeName != "" {
+			internal.ValidateRecipe(c)
+		}
+
+		if !internal.Chaos {
+			if err := catalogue.EnsureIsClean(); err != nil {
+				logrus.Fatal(err)
+			}
+		}
+
+		repos, err := recipe.ReadReposMetadata()
+		if err != nil {
+			logrus.Fatal(err)
+		}
+
+		var barLength int
+		var logMsg string
+		if recipeName != "" {
+			barLength = 1
+			logMsg = fmt.Sprintf("ensuring %v recipe is cloned & up-to-date", barLength)
+		} else {
+			barLength = len(repos)
+			logMsg = fmt.Sprintf("ensuring %v recipes are cloned & up-to-date, this could take some time...", barLength)
+		}
+
+		if !internal.SkipUpdates {
+			logrus.Warn(logMsg)
+			if err := recipe.UpdateRepositories(repos, recipeName); err != nil {
+				logrus.Fatal(err)
+			}
+		}
+
+		catl := make(recipe.RecipeCatalogue)
+		catlBar := formatter.CreateProgressbar(barLength, "generating catalogue metadata...")
+		for _, recipeMeta := range repos {
+			if recipeName != "" && recipeName != recipeMeta.Name {
+				catlBar.Add(1)
+				continue
+			}
+
+			versions, err := recipe.GetRecipeVersions(recipeMeta.Name, internal.Offline)
+			if err != nil {
+				logrus.Warn(err)
+			}
+
+			features, category, err := recipe.GetRecipeFeaturesAndCategory(recipeMeta.Name)
+			if err != nil {
+				logrus.Warn(err)
+			}
+
+			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,
+			}
+
+			catlBar.Add(1)
+		}
+
+		recipesJSON, err := json.MarshalIndent(catl, "", "    ")
+		if err != nil {
+			logrus.Fatal(err)
+		}
+
+		if recipeName == "" {
+			if err := ioutil.WriteFile(config.RECIPES_JSON, recipesJSON, 0764); err != nil {
+				logrus.Fatal(err)
+			}
+		} else {
+			catlFS, err := recipe.ReadRecipeCatalogue(internal.Offline)
+			if err != nil {
+				logrus.Fatal(err)
+			}
+
+			catlFS[recipeName] = catl[recipeName]
+
+			updatedRecipesJSON, err := json.MarshalIndent(catlFS, "", "    ")
+			if err != nil {
+				logrus.Fatal(err)
+			}
+
+			if err := ioutil.WriteFile(config.RECIPES_JSON, updatedRecipesJSON, 0764); err != nil {
+				logrus.Fatal(err)
+			}
+		}
+
+		logrus.Infof("generated new recipe catalogue in %s", config.RECIPES_JSON)
+
+		cataloguePath := path.Join(config.ABRA_DIR, "catalogue")
+		if internal.Publish {
+
+			isClean, err := gitPkg.IsClean(cataloguePath)
+			if err != nil {
+				logrus.Fatal(err)
+			}
+
+			if isClean {
+				if !internal.Dry {
+					logrus.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 {
+				logrus.Fatal(err)
+			}
+
+			repo, err := git.PlainOpen(cataloguePath)
+			if err != nil {
+				logrus.Fatal(err)
+			}
+
+			sshURL := fmt.Sprintf(config.SSH_URL_TEMPLATE, config.CATALOGUE_JSON_REPO_NAME)
+			if err := gitPkg.CreateRemote(repo, "origin-ssh", sshURL, internal.Dry); err != nil {
+				logrus.Fatal(err)
+			}
+
+			if err := gitPkg.Push(cataloguePath, "origin-ssh", false, internal.Dry); err != nil {
+				logrus.Fatal(err)
+			}
+		}
+
+		repo, err := git.PlainOpen(cataloguePath)
+		if err != nil {
+			logrus.Fatal(err)
+		}
+
+		head, err := repo.Head()
+		if err != nil {
+			logrus.Fatal(err)
+		}
+
+		if !internal.Dry && internal.Publish {
+			url := fmt.Sprintf("%s/%s/commit/%s", config.REPOS_BASE_URL, config.CATALOGUE_JSON_REPO_NAME, head.Hash())
+			logrus.Infof("new changes published: %s", url)
+		}
+
+		if internal.Dry {
+			logrus.Info("dry run: no changes published")
+		}
+
+		return nil
+	},
+}
+
 // CatalogueCommand defines the `abra catalogue` command and sub-commands.
-var CatalogueCommand = &cli.Command{
+var CatalogueCommand = cli.Command{
 	Name:        "catalogue",
 	Usage:       "Manage the recipe catalogue",
 	Aliases:     []string{"c"},
 	ArgsUsage:   "<recipe>",
 	Description: "This command helps recipe packagers interact with the recipe catalogue",
-	Subcommands: []*cli.Command{
+	Subcommands: []cli.Command{
 		catalogueGenerateCommand,
 	},
 }

cli/catalogue/generate.go

@@ -1,173 +0,0 @@
-package catalogue
-
-import (
-	"encoding/json"
-	"fmt"
-	"io/ioutil"
-	"os"
-	"path"
-
-	"coopcloud.tech/abra/cli/formatter"
-	"coopcloud.tech/abra/pkg/catalogue"
-	"coopcloud.tech/abra/pkg/config"
-	"coopcloud.tech/abra/pkg/git"
-	"github.com/sirupsen/logrus"
-	"github.com/urfave/cli/v2"
-)
-
-// CatalogueSkipList is all the repos that are not recipes.
-var CatalogueSkipList = map[string]bool{
-	"abra":                  true,
-	"abra-bash":             true,
-	"abra-apps":             true,
-	"abra-aur":              true,
-	"abra-capsul":           true,
-	"abra-gandi":            true,
-	"abra-hetzner":          true,
-	"apps":                  true,
-	"aur-abra-git":          true,
-	"auto-apps-json":        true,
-	"auto-mirror":           true,
-	"backup-bot":            true,
-	"coopcloud.tech":        true,
-	"coturn":                true,
-	"docker-cp-deploy":      true,
-	"docker-dind-bats-kcov": true,
-	"docs.coopcloud.tech":   true,
-	"example":               true,
-	"gardening":             true,
-	"go-abra":               true,
-	"organising":            true,
-	"pyabra":                true,
-	"radicle-seed-node":     true,
-	"stack-ssh-deploy":      true,
-	"swarm-cronjob":         true,
-	"tagcmp":                true,
-	"tyop":                  true,
-}
-
-var catalogueGenerateCommand = &cli.Command{
-	Name:      "generate",
-	Aliases:   []string{"g"},
-	Usage:     "Generate a new copy of the catalogue",
-	ArgsUsage: "[<recipe>]",
-	BashComplete: func(c *cli.Context) {
-		catl, err := catalogue.ReadRecipeCatalogue()
-		if err != nil {
-			logrus.Warn(err)
-		}
-		if c.NArg() > 0 {
-			return
-		}
-		for name := range catl {
-			fmt.Println(name)
-		}
-	},
-	Action: func(c *cli.Context) error {
-		recipeName := c.Args().First()
-
-		repos, err := catalogue.ReadReposMetadata()
-		if err != nil {
-			logrus.Fatal(err)
-		}
-
-		logrus.Debugf("ensuring '%v' recipe(s) are locally present and up-to-date", len(repos))
-
-		retrieveBar := formatter.CreateProgressbar(len(repos), "retrieving recipes...")
-		ch := make(chan string, len(repos))
-		for _, repoMeta := range repos {
-			go func(rm catalogue.RepoMeta) {
-				if recipeName != "" && recipeName != rm.Name {
-					ch <- rm.Name
-					retrieveBar.Add(1)
-					return
-				}
-				if _, exists := CatalogueSkipList[rm.Name]; exists {
-					ch <- rm.Name
-					retrieveBar.Add(1)
-					return
-				}
-
-				recipeDir := path.Join(config.ABRA_DIR, "apps", rm.Name)
-
-				if err := git.Clone(recipeDir, rm.SSHURL); err != nil {
-					logrus.Fatal(err)
-				}
-
-				if err := git.EnsureUpToDate(recipeDir); err != nil {
-					logrus.Fatal(err)
-				}
-
-				ch <- rm.Name
-				retrieveBar.Add(1)
-			}(repoMeta)
-		}
-
-		for range repos {
-			<-ch // wait for everything
-		}
-
-		catl := make(catalogue.RecipeCatalogue)
-		catlBar := formatter.CreateProgressbar(len(repos), "generating catalogue...")
-		for _, recipeMeta := range repos {
-			if recipeName != "" && recipeName != recipeMeta.Name {
-				catlBar.Add(1)
-				continue
-			}
-
-			if _, exists := CatalogueSkipList[recipeMeta.Name]; exists {
-				catlBar.Add(1)
-				continue
-			}
-
-			versions, err := catalogue.GetRecipeVersions(recipeMeta.Name)
-			if err != nil {
-				logrus.Fatal(err)
-			}
-
-			catl[recipeMeta.Name] = catalogue.RecipeMeta{
-				Name:          recipeMeta.Name,
-				Repository:    recipeMeta.CloneURL,
-				Icon:          recipeMeta.AvatarURL,
-				DefaultBranch: recipeMeta.DefaultBranch,
-				Description:   recipeMeta.Description,
-				Website:       recipeMeta.Website,
-				Versions:      versions,
-				// Category:      ..., // FIXME: once we sort out the machine-readable catalogue interface
-				// Features:      ..., // FIXME: once we figure out the machine-readable catalogue interface
-			}
-			catlBar.Add(1)
-		}
-
-		recipesJSON, err := json.MarshalIndent(catl, "", "    ")
-		if err != nil {
-			logrus.Fatal(err)
-		}
-
-		if _, err := os.Stat(config.APPS_JSON); err != nil && os.IsNotExist(err) {
-			if err := ioutil.WriteFile(config.APPS_JSON, recipesJSON, 0644); err != nil {
-				logrus.Fatal(err)
-			}
-		} else {
-			if recipeName != "" {
-				catlFS, err := catalogue.ReadRecipeCatalogue()
-				if err != nil {
-					logrus.Fatal(err)
-				}
-				catlFS[recipeName] = catl[recipeName]
-
-				updatedRecipesJSON, err := json.MarshalIndent(catlFS, "", "    ")
-				if err != nil {
-					logrus.Fatal(err)
-				}
-				if err := ioutil.WriteFile(config.APPS_JSON, updatedRecipesJSON, 0644); err != nil {
-					logrus.Fatal(err)
-				}
-			}
-		}
-
-		logrus.Infof("generated new recipe catalogue in '%s'", config.APPS_JSON)
-
-		return nil
-	},
-}

cli/cli.go

@@ -2,50 +2,149 @@
 package cli
 
 import (
+	"errors"
 	"fmt"
 	"os"
+	"os/exec"
 	"path"
 
 	"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/autocomplete"
+	cataloguePkg "coopcloud.tech/abra/pkg/catalogue"
 	"coopcloud.tech/abra/pkg/config"
-	logrusStack "github.com/Gurpartap/logrus-stack"
+	"coopcloud.tech/abra/pkg/web"
 	"github.com/sirupsen/logrus"
-	"github.com/urfave/cli/v2"
+	"github.com/urfave/cli"
 )
 
-// Verbose stores the variable from VerboseFlag.
+// AutoCompleteCommand helps people set up auto-complete in their shells
-var Verbose bool
+var AutoCompleteCommand = cli.Command{
+	Name:    "autocomplete",
+	Aliases: []string{"ac"},
+	Usage:   "Configure shell autocompletion (recommended)",
+	Description: `
+Set up auto-completion in your shell by downloading the relevant files and
+laying out what additional information must be loaded. Supported shells are as
+follows: bash, fish, fizsh & zsh.
 
-// VerboseFlag turns on/off verbose logging down to the INFO level.
+Example:
-var VerboseFlag = &cli.BoolFlag{
+
-	Name:        "verbose",
+    abra autocomplete bash
-	Aliases:     []string{"V"},
+`,
-	Value:       false,
+	ArgsUsage: "<shell>",
-	Destination: &Verbose,
+	Flags: []cli.Flag{
-	Usage:       "Show INFO messages",
+		internal.DebugFlag,
+	},
+	Action: func(c *cli.Context) error {
+		shellType := c.Args().First()
+
+		if shellType == "" {
+			internal.ShowSubcommandHelpAndError(c, errors.New("no shell provided"))
 		}
 
-// Debug stores the variable from DebugFlag.
+		supportedShells := map[string]bool{
-var Debug bool
+			"bash":  true,
-
+			"zsh":   true,
-// DebugFlag turns on/off verbose logging down to the DEBUG level.
+			"fizsh": true,
-var DebugFlag = &cli.BoolFlag{
+			"fish":  true,
-	Name:        "debug",
-	Aliases:     []string{"d"},
-	Value:       false,
-	Destination: &Debug,
-	Usage:       "Show DEBUG messages",
 		}
 
-// RunApp runs CLI abra app.
+		if _, ok := supportedShells[shellType]; !ok {
-func RunApp(version, commit string) {
+			logrus.Fatalf("%s is not a supported shell right now, sorry", shellType)
+		}
+
+		if shellType == "fizsh" {
+			shellType = "zsh" // handled the same on the autocompletion side
+		}
+
+		autocompletionDir := path.Join(config.ABRA_DIR, "autocompletion")
+		if err := os.Mkdir(autocompletionDir, 0764); err != nil {
+			if !os.IsExist(err) {
+				logrus.Fatal(err)
+			}
+			logrus.Debugf("%s already created", autocompletionDir)
+		}
+
+		autocompletionFile := path.Join(config.ABRA_DIR, "autocompletion", shellType)
+		if _, err := os.Stat(autocompletionFile); err != nil && os.IsNotExist(err) {
+			url := fmt.Sprintf("https://git.coopcloud.tech/coop-cloud/abra/raw/branch/main/scripts/autocomplete/%s", shellType)
+			logrus.Infof("fetching %s", url)
+			if err := web.GetFile(autocompletionFile, url); err != nil {
+				logrus.Fatal(err)
+			}
+		}
+
+		switch shellType {
+		case "bash":
+			fmt.Println(fmt.Sprintf(`
+# Run the following commands to install auto-completion
+sudo mkdir /etc/bash_completion.d/
+sudo cp %s /etc/bash_completion.d/abra
+echo "source /etc/bash_completion.d/abra" >> ~/.bashrc
+# To test, run the following: "abra app <hit tab key>" - you should see command completion!
+`, autocompletionFile))
+		case "zsh":
+			fmt.Println(fmt.Sprintf(`
+# Run the following commands to install auto-completion
+sudo mkdir /etc/zsh/completion.d/
+sudo cp %s /etc/zsh/completion.d/abra
+echo "PROG=abra\n_CLI_ZSH_AUTOCOMPLETE_HACK=1\nsource /etc/zsh/completion.d/abra" >> ~/.zshrc
+# To test, run the following: "abra app <hit tab key>" - you should see command completion!
+`, autocompletionFile))
+		case "fish":
+			fmt.Println(fmt.Sprintf(`
+# Run the following commands to install auto-completion
+sudo mkdir -p /etc/fish/completions
+sudo cp %s /etc/fish/completions/abra
+echo "source /etc/fish/completions/abra" >> ~/.config/fish/config.fish
+# To test, run the following: "abra app <hit tab key>" - you should see command completion!
+`, autocompletionFile))
+		}
+
+		return nil
+	},
+}
+
+// UpgradeCommand upgrades abra in-place.
+var UpgradeCommand = cli.Command{
+	Name:    "upgrade",
+	Aliases: []string{"u"},
+	Usage:   "Upgrade Abra itself",
+	Description: `
+Upgrade Abra in-place with the latest stable or release candidate.
+
+Pass "-r/--rc" to install the latest release candidate. Please bear in mind
+that it may contain catastrophic bugs. Thank you very much for the testing
+efforts!
+`,
+	Flags: []cli.Flag{internal.RCFlag},
+	Action: func(c *cli.Context) error {
+		mainURL := "https://install.abra.coopcloud.tech"
+		cmd := exec.Command("bash", "-c", fmt.Sprintf("wget -q -O- %s | bash", mainURL))
+
+		if internal.RC {
+			releaseCandidateURL := "https://git.coopcloud.tech/coop-cloud/abra/raw/branch/main/scripts/installer/installer"
+			cmd = exec.Command("bash", "-c", fmt.Sprintf("wget -q -O- %s | bash -s -- --rc", releaseCandidateURL))
+		}
+
+		logrus.Debugf("attempting to run %s", cmd)
+
+		if err := internal.RunCmd(cmd); err != nil {
+			logrus.Fatal(err)
+		}
+
+		return nil
+	},
+}
+
+func newAbraApp(version, commit string) *cli.App {
 	app := &cli.App{
 		Name: "abra",
 		Usage: `The Co-op Cloud command-line utility belt 🎩🐇
-
     ____                           ____ _                 _
    / ___|___         ___  _ __    / ___| | ___  _   _  __| |
   | |   / _ \ _____ / _ \| '_ \  | |   | |/ _ \| | | |/ _' |
@@ -54,59 +153,53 @@ func RunApp(version, commit string) {
                          |_|
 `,
 		Version: fmt.Sprintf("%s-%s", version, commit[:7]),
-		Commands: []*cli.Command{
+		Commands: []cli.Command{
 			app.AppCommand,
 			server.ServerCommand,
 			recipe.RecipeCommand,
 			catalogue.CatalogueCommand,
-			VersionCommand,
 			UpgradeCommand,
+			AutoCompleteCommand,
 		},
-		Flags: []cli.Flag{
+		BashComplete: autocomplete.SubcommandComplete,
-			VerboseFlag,
-			DebugFlag,
-		},
-		Authors: []*cli.Author{
-			{
-				Name:  "Autonomic Co-op",
-				Email: "helo@autonomic.zone",
-			},
-		},
 	}
 
 	app.EnableBashCompletion = true
 
 	app.Before = func(c *cli.Context) error {
-		if Debug {
-			logrus.SetLevel(logrus.DebugLevel)
-			logrus.SetFormatter(&logrus.TextFormatter{})
-			logrus.SetOutput(os.Stderr)
-			logrus.AddHook(logrusStack.StandardHook())
-		}
-
 		paths := []string{
 			config.ABRA_DIR,
-			path.Join(config.ABRA_DIR, "servers"),
+			config.SERVERS_DIR,
-			path.Join(config.ABRA_DIR, "apps"),
+			config.RECIPES_DIR,
-			path.Join(config.ABRA_DIR, "vendor"),
+			config.VENDOR_DIR,
+			config.BACKUP_DIR,
 		}
 
 		for _, path := range paths {
-			if err := os.Mkdir(path, 0755); err != nil {
+			if err := os.Mkdir(path, 0764); err != nil {
 				if !os.IsExist(err) {
 					logrus.Fatal(err)
 				}
-				logrus.Debugf("'%s' already created, moving on...", path)
 				continue
 			}
-			logrus.Debugf("'%s' is missing, creating...", path)
 		}
 
-		logrus.Debugf("abra version '%s', commit '%s'", version, commit)
+		if err := cataloguePkg.EnsureCatalogue(); err != nil {
+			logrus.Fatal(err)
+		}
+
+		logrus.Debugf("abra version %s, commit %s", version, commit)
 
 		return nil
 	}
 
+	return app
+}
+
+// RunApp runs CLI abra app.
+func RunApp(version, commit string) {
+	app := newAbraApp(version, commit)
+
 	if err := app.Run(os.Args); err != nil {
 		logrus.Fatal(err)
 	}

cli/formatter/formatter.go

@@ -1,52 +0,0 @@
-package formatter
-
-import (
-	"fmt"
-	"os"
-	"strings"
-	"time"
-
-	"github.com/docker/cli/cli/command/formatter"
-	"github.com/docker/go-units"
-	"github.com/olekukonko/tablewriter"
-	"github.com/schollz/progressbar/v3"
-)
-
-func ShortenID(str string) string {
-	return str[:12]
-}
-
-func Truncate(str string) string {
-	return fmt.Sprintf(`"%s"`, formatter.Ellipsis(str, 19))
-}
-
-// RemoveSha remove image sha from a string that are added in some docker outputs
-func RemoveSha(str string) string {
-	return strings.Split(str, "@")[0]
-}
-
-// HumanDuration from docker/cli RunningFor() to be accessible outside of the class
-func HumanDuration(timestamp int64) string {
-	date := time.Unix(timestamp, 0)
-	now := time.Now().UTC()
-	return units.HumanDuration(now.Sub(date)) + " ago"
-}
-
-// CreateTable prepares a table layout for output.
-func CreateTable(columns []string) *tablewriter.Table {
-	table := tablewriter.NewWriter(os.Stdout)
-	table.SetHeader(columns)
-	return table
-}
-
-// CreateProgressbar generates a progress bar
-func CreateProgressbar(length int, title string) *progressbar.ProgressBar {
-	return progressbar.NewOptions(
-		length,
-		progressbar.OptionClearOnFinish(),
-		progressbar.OptionSetPredictTime(false),
-		progressbar.OptionShowCount(),
-		progressbar.OptionFullWidth(),
-		progressbar.OptionSetDescription(title),
-	)
-}

cli/internal/backup.go

@@ -0,0 +1,35 @@
+package internal
+
+import (
+	"strings"
+)
+
+// SafeSplit splits up a string into a list of commands safely.
+func SafeSplit(s string) []string {
+	split := strings.Split(s, " ")
+
+	var result []string
+	var inquote string
+	var block string
+	for _, i := range split {
+		if inquote == "" {
+			if strings.HasPrefix(i, "'") || strings.HasPrefix(i, "\"") {
+				inquote = string(i[0])
+				block = strings.TrimPrefix(i, inquote) + " "
+			} else {
+				result = append(result, i)
+			}
+		} else {
+			if !strings.HasSuffix(i, inquote) {
+				block += i + " "
+			} else {
+				block += strings.TrimSuffix(i, inquote)
+				inquote = ""
+				result = append(result, block)
+				block = ""
+			}
+		}
+	}
+
+	return result
+}

cli/internal/cli.go

@@ -0,0 +1,251 @@
+package internal
+
+import (
+	"os"
+
+	logrusStack "github.com/Gurpartap/logrus-stack"
+	"github.com/sirupsen/logrus"
+	"github.com/urfave/cli"
+)
+
+// Secrets stores the variable from SecretsFlag
+var Secrets bool
+
+// SecretsFlag turns on/off automatically generating secrets
+var SecretsFlag = &cli.BoolFlag{
+	Name:        "secrets, S",
+	Usage:       "Automatically generate secrets",
+	Destination: &Secrets,
+}
+
+// Pass stores the variable from PassFlag
+var Pass bool
+
+// PassFlag turns on/off storing generated secrets in pass
+var PassFlag = &cli.BoolFlag{
+	Name:        "pass, p",
+	Usage:       "Store the generated secrets in a local pass store",
+	Destination: &Pass,
+}
+
+// PassRemove stores the variable for PassRemoveFlag
+var PassRemove bool
+
+// PassRemoveFlag turns on/off removing generated secrets from pass
+var PassRemoveFlag = &cli.BoolFlag{
+	Name:        "pass, p",
+	Usage:       "Remove generated secrets from a local pass store",
+	Destination: &PassRemove,
+}
+
+// Force force functionality without asking.
+var Force bool
+
+// ForceFlag turns on/off force functionality.
+var ForceFlag = &cli.BoolFlag{
+	Name:        "force, f",
+	Usage:       "Perform action without further prompt. Use with care!",
+	Destination: &Force,
+}
+
+// Chaos engages chaos mode.
+var Chaos bool
+
+// ChaosFlag turns on/off chaos functionality.
+var ChaosFlag = &cli.BoolFlag{
+	Name:        "chaos, C",
+	Usage:       "Proceed with uncommitted recipes changes. Use with care!",
+	Destination: &Chaos,
+}
+
+// Disable tty to run commands from script
+var Tty bool
+
+// TtyFlag turns on/off tty mode.
+var TtyFlag = &cli.BoolFlag{
+	Name:        "tty, T",
+	Usage:       "Disables TTY mode to run this command from a script.",
+	Destination: &Tty,
+}
+
+var NoInput bool
+var NoInputFlag = &cli.BoolFlag{
+	Name:        "no-input, n",
+	Usage:       "Toggle non-interactive mode",
+	Destination: &NoInput,
+}
+
+// Debug stores the variable from DebugFlag.
+var Debug bool
+
+// DebugFlag turns on/off verbose logging down to the DEBUG level.
+var DebugFlag = &cli.BoolFlag{
+	Name:        "debug, d",
+	Destination: &Debug,
+	Usage:       "Show DEBUG messages",
+}
+
+// Offline stores the variable from OfflineFlag.
+var Offline bool
+
+// DebugFlag turns on/off offline mode.
+var OfflineFlag = &cli.BoolFlag{
+	Name:        "offline, o",
+	Destination: &Offline,
+	Usage:       "Prefer offline & filesystem access when possible",
+}
+
+// MachineReadable stores the variable from MachineReadableFlag
+var MachineReadable bool
+
+// MachineReadableFlag turns on/off machine readable output where supported
+var MachineReadableFlag = &cli.BoolFlag{
+	Name:        "machine, m",
+	Destination: &MachineReadable,
+	Usage:       "Output in a machine-readable format (where supported)",
+}
+
+// RC signifies the latest release candidate
+var RC bool
+
+// RCFlag chooses the latest release candidate for install
+var RCFlag = &cli.BoolFlag{
+	Name:        "rc, r",
+	Destination: &RC,
+	Usage:       "Install the latest release candidate",
+}
+
+var Major bool
+var MajorFlag = &cli.BoolFlag{
+	Name:        "major, x",
+	Usage:       "Increase the major part of the version",
+	Destination: &Major,
+}
+
+var Minor bool
+var MinorFlag = &cli.BoolFlag{
+	Name:        "minor, y",
+	Usage:       "Increase the minor part of the version",
+	Destination: &Minor,
+}
+
+var Patch bool
+var PatchFlag = &cli.BoolFlag{
+	Name:        "patch, z",
+	Usage:       "Increase the patch part of the version",
+	Destination: &Patch,
+}
+
+var Dry bool
+var DryFlag = &cli.BoolFlag{
+	Name:        "dry-run, r",
+	Usage:       "Only reports changes that would be made",
+	Destination: &Dry,
+}
+
+var Publish bool
+var PublishFlag = &cli.BoolFlag{
+	Name:        "publish, p",
+	Usage:       "Publish changes to git.coopcloud.tech",
+	Destination: &Publish,
+}
+
+var Domain string
+var DomainFlag = &cli.StringFlag{
+	Name:        "domain, D",
+	Value:       "",
+	Usage:       "Choose a domain name",
+	Destination: &Domain,
+}
+
+var NewAppServer string
+var NewAppServerFlag = &cli.StringFlag{
+	Name:        "server, s",
+	Value:       "",
+	Usage:       "Show apps of a specific server",
+	Destination: &NewAppServer,
+}
+
+var NoDomainChecks bool
+var NoDomainChecksFlag = &cli.BoolFlag{
+	Name:        "no-domain-checks, D",
+	Usage:       "Disable app domain sanity checks",
+	Destination: &NoDomainChecks,
+}
+
+var StdErrOnly bool
+var StdErrOnlyFlag = &cli.BoolFlag{
+	Name:        "stderr, s",
+	Usage:       "Only tail stderr",
+	Destination: &StdErrOnly,
+}
+
+var SinceLogs string
+var SinceLogsFlag = &cli.StringFlag{
+	Name:        "since, S",
+	Value:       "",
+	Usage:       "tail logs since YYYY-MM-DDTHH:MM:SSZ",
+	Destination: &SinceLogs,
+}
+
+var DontWaitConverge bool
+var DontWaitConvergeFlag = &cli.BoolFlag{
+	Name:        "no-converge-checks, c",
+	Usage:       "Don't wait for converge logic checks",
+	Destination: &DontWaitConverge,
+}
+
+var Watch bool
+var WatchFlag = &cli.BoolFlag{
+	Name:        "watch, w",
+	Usage:       "Watch status by polling repeatedly",
+	Destination: &Watch,
+}
+
+var OnlyErrors bool
+var OnlyErrorFlag = &cli.BoolFlag{
+	Name:        "errors, e",
+	Usage:       "Only show errors",
+	Destination: &OnlyErrors,
+}
+
+var SkipUpdates bool
+var SkipUpdatesFlag = &cli.BoolFlag{
+	Name:        "skip-updates, s",
+	Usage:       "Skip updating recipe repositories",
+	Destination: &SkipUpdates,
+}
+
+var AllTags bool
+var AllTagsFlag = &cli.BoolFlag{
+	Name:        "all-tags, a",
+	Usage:       "List all tags, not just upgrades",
+	Destination: &AllTags,
+}
+
+var LocalCmd bool
+var LocalCmdFlag = &cli.BoolFlag{
+	Name:        "local, l",
+	Usage:       "Run command locally",
+	Destination: &LocalCmd,
+}
+
+var RemoteUser string
+var RemoteUserFlag = &cli.StringFlag{
+	Name:        "user, u",
+	Value:       "",
+	Usage:       "User to run command within a service context",
+	Destination: &RemoteUser,
+}
+
+// SubCommandBefore wires up pre-action machinery (e.g. --debug handling).
+func SubCommandBefore(c *cli.Context) error {
+	if Debug {
+		logrus.SetLevel(logrus.DebugLevel)
+		logrus.SetFormatter(&logrus.TextFormatter{})
+		logrus.SetOutput(os.Stderr)
+		logrus.AddHook(logrusStack.StandardHook())
+	}
+
+	return nil
+}

cli/internal/command.go

@@ -2,10 +2,109 @@ package internal
 
 import (
 	"bufio"
+	"context"
 	"fmt"
+	"io/ioutil"
 	"os/exec"
+	"strings"
+
+	"coopcloud.tech/abra/pkg/config"
+	containerPkg "coopcloud.tech/abra/pkg/container"
+	"coopcloud.tech/abra/pkg/formatter"
+	"coopcloud.tech/abra/pkg/upstream/container"
+	"github.com/docker/cli/cli/command"
+	"github.com/docker/docker/api/types"
+	"github.com/docker/docker/api/types/filters"
+	dockerClient "github.com/docker/docker/client"
+	"github.com/docker/docker/pkg/archive"
+	"github.com/sirupsen/logrus"
 )
 
+// RunCmdRemote executes an abra.sh command in the target service
+func RunCmdRemote(cl *dockerClient.Client, app config.App, abraSh, serviceName, cmdName, cmdArgs 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
+	}
+
+	logrus.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 := types.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 := types.ExecConfig{
+		AttachStderr: true,
+		AttachStdin:  true,
+		AttachStdout: true,
+		Cmd:          findShell,
+		Detach:       false,
+		Tty:          false,
+	}
+
+	if err := container.RunExec(dcli, cl, targetContainer.ID, &execCreateOpts); err != nil {
+		logrus.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)}
+	}
+
+	logrus.Debugf("running command: %s", strings.Join(cmd, " "))
+
+	if RemoteUser != "" {
+		logrus.Debugf("running command with user %s", RemoteUser)
+		execCreateOpts.User = RemoteUser
+	}
+
+	execCreateOpts.Cmd = cmd
+	execCreateOpts.Tty = true
+	if Tty {
+		execCreateOpts.Tty = false
+	}
+
+	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()

cli/internal/common.go

@@ -1,51 +0,0 @@
-package internal
-
-import (
-	"github.com/urfave/cli/v2"
-)
-
-// Secrets stores the variable from SecretsFlag
-var Secrets bool
-
-// SecretsFlag turns on/off automatically generating secrets
-var SecretsFlag = &cli.BoolFlag{
-	Name:        "secrets",
-	Aliases:     []string{"S"},
-	Value:       false,
-	Usage:       "Automatically generate secrets",
-	Destination: &Secrets,
-}
-
-// Pass stores the variable from PassFlag
-var Pass bool
-
-// PassFlag turns on/off storing generated secrets in pass
-var PassFlag = &cli.BoolFlag{
-	Name:        "pass",
-	Aliases:     []string{"P"},
-	Value:       false,
-	Usage:       "Store the generated secrets in a local pass store",
-	Destination: &Pass,
-}
-
-// Context is temp
-var Context string
-
-// ContextFlag is temp
-var ContextFlag = &cli.StringFlag{
-	Name:        "context",
-	Value:       "",
-	Aliases:     []string{"c"},
-	Destination: &Context,
-}
-
-// Force force functionality without asking.
-var Force bool
-
-// ForceFlag turns on/off force functionality.
-var ForceFlag = &cli.BoolFlag{
-	Name:        "force",
-	Value:       false,
-	Aliases:     []string{"f"},
-	Destination: &Force,
-}

cli/internal/deploy.go

@@ -0,0 +1,173 @@
+package internal
+
+import (
+	"fmt"
+	"io/ioutil"
+	"os"
+	"path"
+	"strings"
+
+	"coopcloud.tech/abra/pkg/config"
+	"coopcloud.tech/abra/pkg/formatter"
+	"github.com/AlecAivazis/survey/v2"
+	dockerClient "github.com/docker/docker/client"
+	"github.com/sirupsen/logrus"
+)
+
+// NewVersionOverview shows an upgrade or downgrade overview
+func NewVersionOverview(app config.App, currentVersion, newVersion, releaseNotes string) error {
+	tableCol := []string{"server", "recipe", "config", "domain", "current version", "to be deployed"}
+	table := formatter.CreateTable(tableCol)
+
+	deployConfig := "compose.yml"
+	if composeFiles, ok := app.Env["COMPOSE_FILE"]; ok {
+		deployConfig = strings.Join(strings.Split(composeFiles, ":"), "\n")
+	}
+
+	server := app.Server
+	if app.Server == "default" {
+		server = "local"
+	}
+
+	table.Append([]string{server, app.Recipe, deployConfig, app.Domain, currentVersion, newVersion})
+	table.Render()
+
+	if releaseNotes != "" && newVersion != "" {
+		fmt.Println()
+		fmt.Print(releaseNotes)
+	} else {
+		logrus.Warnf("no release notes available for %s", newVersion)
+	}
+
+	if NoInput {
+		return nil
+	}
+
+	response := false
+	prompt := &survey.Confirm{
+		Message: "continue with deployment?",
+	}
+
+	if err := survey.AskOne(prompt, &response); err != nil {
+		return err
+	}
+
+	if !response {
+		logrus.Fatal("exiting as requested")
+	}
+
+	return nil
+}
+
+// GetReleaseNotes prints release notes for a recipe version
+func GetReleaseNotes(recipeName, version string) (string, error) {
+	if version == "" {
+		return "", nil
+	}
+
+	fpath := path.Join(config.RECIPES_DIR, recipeName, "release", version)
+
+	if _, err := os.Stat(fpath); !os.IsNotExist(err) {
+		releaseNotes, err := ioutil.ReadFile(fpath)
+		if err != nil {
+			return "", err
+		}
+		withTitle := fmt.Sprintf("%s release notes:\n%s", version, string(releaseNotes))
+		return withTitle, nil
+	}
+
+	return "", nil
+}
+
+// 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 config.App, commands string) error {
+	abraSh := path.Join(config.RECIPES_DIR, app.Recipe, "abra.sh")
+	if _, err := os.Stat(abraSh); err != nil {
+		if os.IsNotExist(err) {
+			return fmt.Errorf(fmt.Sprintf("%s does not exist for %s?", abraSh, 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:], " "))
+		}
+		logrus.Infof("running post-command '%s %s' in container %s", cmdName, parsedCmdArgs, targetServiceName)
+
+		if err := EnsureCommand(abraSh, app.Recipe, cmdName); err != nil {
+			return err
+		}
+
+		serviceNames, err := config.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))
+		}
+
+		logrus.Debugf("running command %s %s within the context of %s_%s", cmdName, parsedCmdArgs, app.StackName(), targetServiceName)
+
+		Tty = true
+		if err := RunCmdRemote(cl, app, abraSh, targetServiceName, cmdName, parsedCmdArgs); err != nil {
+			return err
+		}
+	}
+	return nil
+}
+
+// DeployOverview shows a deployment overview
+func DeployOverview(app config.App, version, message string) error {
+	tableCol := []string{"server", "recipe", "config", "domain", "version"}
+	table := formatter.CreateTable(tableCol)
+
+	deployConfig := "compose.yml"
+	if composeFiles, ok := app.Env["COMPOSE_FILE"]; ok {
+		deployConfig = strings.Join(strings.Split(composeFiles, ":"), "\n")
+	}
+
+	server := app.Server
+	if app.Server == "default" {
+		server = "local"
+	}
+
+	table.Append([]string{server, app.Recipe, deployConfig, app.Domain, version})
+	table.Render()
+
+	if NoInput {
+		return nil
+	}
+
+	response := false
+	prompt := &survey.Confirm{
+		Message: message,
+	}
+
+	if err := survey.AskOne(prompt, &response); err != nil {
+		return err
+	}
+
+	if !response {
+		logrus.Fatal("exiting as requested")
+	}
+
+	return nil
+}

cli/internal/errors.go

@@ -4,7 +4,7 @@ import (
 	"os"
 
 	"github.com/sirupsen/logrus"
-	"github.com/urfave/cli/v2"
+	"github.com/urfave/cli"
 )
 
 // ShowSubcommandHelpAndError exits the program on error, logs the error to the

cli/internal/list.go

@@ -0,0 +1,10 @@
+package internal
+
+// ReverseStringList reverses a list of a strings. Roll on Go generics.
+func ReverseStringList(strings []string) []string {
+	for i, j := 0, len(strings)-1; i < j; i, j = i+1, j-1 {
+		strings[i], strings[j] = strings[j], strings[i]
+	}
+
+	return strings
+}

cli/internal/recipe.go

@@ -0,0 +1,110 @@
+package internal
+
+import (
+	"fmt"
+
+	"coopcloud.tech/abra/pkg/formatter"
+	"coopcloud.tech/abra/pkg/recipe"
+	"github.com/AlecAivazis/survey/v2"
+	"github.com/docker/distribution/reference"
+	"github.com/sirupsen/logrus"
+)
+
+// 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 {
+		logrus.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 {
+		logrus.Fatal("no version bump type specififed?")
+	}
+}
+
+// GetMainAppImage retrieves the main 'app' image name
+func GetMainAppImage(recipe recipe.Recipe) (string, error) {
+	var path string
+
+	for _, service := range recipe.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

@@ -2,30 +2,79 @@ package internal
 
 import (
 	"errors"
+	"strings"
 
 	"coopcloud.tech/abra/pkg/app"
 	"coopcloud.tech/abra/pkg/config"
 	"coopcloud.tech/abra/pkg/recipe"
+	"github.com/AlecAivazis/survey/v2"
 	"github.com/sirupsen/logrus"
-	"github.com/urfave/cli/v2"
+	"github.com/urfave/cli"
 )
 
 // ValidateRecipe ensures the recipe arg is valid.
 func ValidateRecipe(c *cli.Context) recipe.Recipe {
 	recipeName := c.Args().First()
 
-	if recipeName == "" {
+	if recipeName == "" && !NoInput {
-		ShowSubcommandHelpAndError(c, errors.New("no recipe provided"))
+		var recipes []string
-	}
 
-	recipe, err := recipe.Get(recipeName)
+		catl, err := recipe.ReadRecipeCatalogue(Offline)
 		if err != nil {
 			logrus.Fatal(err)
 		}
 
-	logrus.Debugf("validated '%s' as recipe argument", recipeName)
+		knownRecipes := make(map[string]bool)
+		for name := range catl {
+			knownRecipes[name] = true
+		}
 
-	return recipe
+		localRecipes, err := recipe.GetRecipesLocal()
+		if err != nil {
+			logrus.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 {
+			logrus.Fatal(err)
+		}
+	}
+
+	if recipeName == "" {
+		ShowSubcommandHelpAndError(c, errors.New("no recipe name provided"))
+	}
+
+	chosenRecipe, err := recipe.Get(recipeName, Offline)
+	if err != nil {
+		if c.Command.Name == "generate" {
+			if strings.Contains(err.Error(), "missing a compose") {
+				logrus.Fatal(err)
+			}
+			logrus.Warn(err)
+		} else {
+			if strings.Contains(err.Error(), "template_driver is not allowed") {
+				logrus.Warnf("ensure %s recipe compose.* files include \"version: '3.8'\"", recipeName)
+			}
+			logrus.Fatalf("unable to validate recipe: %s", err)
+		}
+	}
+
+	logrus.Debugf("validated %s as recipe argument", recipeName)
+
+	return chosenRecipe
 }
 
 // ValidateApp ensures the app name arg is valid.
@@ -41,11 +90,7 @@ func ValidateApp(c *cli.Context) config.App {
 		logrus.Fatal(err)
 	}
 
-	if err := recipe.EnsureExists(app.Type); err != nil {
+	logrus.Debugf("validated %s as app argument", appName)
-		logrus.Fatal(err)
-	}
-
-	logrus.Debugf("validated '%s' as app argument", appName)
 
 	return app
 }
@@ -54,11 +99,74 @@ func ValidateApp(c *cli.Context) config.App {
 func ValidateDomain(c *cli.Context) string {
 	domainName := c.Args().First()
 
+	if domainName == "" && !NoInput {
+		prompt := &survey.Input{
+			Message: "Specify a domain name",
+			Default: "example.com",
+		}
+		if err := survey.AskOne(prompt, &domainName); err != nil {
+			logrus.Fatal(err)
+		}
+	}
+
 	if domainName == "" {
 		ShowSubcommandHelpAndError(c, errors.New("no domain provided"))
 	}
 
-	logrus.Debugf("validated '%s' as domain argument", domainName)
+	logrus.Debugf("validated %s as domain argument", domainName)
 
 	return domainName
 }
+
+// ValidateSubCmdFlags ensures flag order conforms to correct order
+func ValidateSubCmdFlags(c *cli.Context) bool {
+	for argIdx, arg := range c.Args() {
+		if !strings.HasPrefix(arg, "--") {
+			for _, flag := range c.Args()[argIdx:] {
+				if strings.HasPrefix(flag, "--") {
+					return false
+				}
+			}
+		}
+	}
+	return true
+}
+
+// ValidateServer ensures the server name arg is valid.
+func ValidateServer(c *cli.Context) string {
+	serverName := c.Args().First()
+
+	serverNames, err := config.ReadServerNames()
+	if err != nil {
+		logrus.Fatal(err)
+	}
+
+	if serverName == "" && !NoInput {
+		prompt := &survey.Select{
+			Message: "Specify a server name",
+			Options: serverNames,
+		}
+		if err := survey.AskOne(prompt, &serverName); err != nil {
+			logrus.Fatal(err)
+		}
+	}
+
+	matched := false
+	for _, name := range serverNames {
+		if name == serverName {
+			matched = true
+		}
+	}
+
+	if serverName == "" {
+		ShowSubcommandHelpAndError(c, errors.New("no server provided"))
+	}
+
+	if !matched {
+		ShowSubcommandHelpAndError(c, errors.New("server doesn't exist?"))
+	}
+
+	logrus.Debugf("validated %s as server argument", serverName)
+
+	return serverName
+}

cli/recipe/diff.go

@@ -0,0 +1,40 @@
+package recipe
+
+import (
+	"path"
+
+	"coopcloud.tech/abra/cli/internal"
+	"coopcloud.tech/abra/pkg/autocomplete"
+	"coopcloud.tech/abra/pkg/config"
+	gitPkg "coopcloud.tech/abra/pkg/git"
+	"github.com/sirupsen/logrus"
+	"github.com/urfave/cli"
+)
+
+var recipeDiffCommand = cli.Command{
+	Name:        "diff",
+	Usage:       "Show unstaged changes in recipe config",
+	Description: "Due to limitations in our underlying Git dependency, this command requires /usr/bin/git.",
+	Aliases:     []string{"d"},
+	ArgsUsage:   "<recipe>",
+	Flags: []cli.Flag{
+		internal.DebugFlag,
+		internal.NoInputFlag,
+	},
+	Before:       internal.SubCommandBefore,
+	BashComplete: autocomplete.RecipeNameComplete,
+	Action: func(c *cli.Context) error {
+		recipeName := c.Args().First()
+
+		if recipeName != "" {
+			internal.ValidateRecipe(c)
+		}
+
+		recipeDir := path.Join(config.RECIPES_DIR, recipeName)
+		if err := gitPkg.DiffUnstaged(recipeDir); err != nil {
+			logrus.Fatal(err)
+		}
+
+		return nil
+	},
+}

cli/recipe/fetch.go

@@ -0,0 +1,44 @@
+package recipe
+
+import (
+	"coopcloud.tech/abra/cli/internal"
+	"coopcloud.tech/abra/pkg/autocomplete"
+	"coopcloud.tech/abra/pkg/recipe"
+	"github.com/sirupsen/logrus"
+	"github.com/urfave/cli"
+)
+
+var recipeFetchCommand = cli.Command{
+	Name:        "fetch",
+	Usage:       "Fetch recipe(s)",
+	Aliases:     []string{"f"},
+	ArgsUsage:   "[<recipe>]",
+	Description: "Retrieves all recipes if no <recipe> argument is passed",
+	Flags: []cli.Flag{
+		internal.DebugFlag,
+		internal.NoInputFlag,
+	},
+	Before:       internal.SubCommandBefore,
+	BashComplete: autocomplete.RecipeNameComplete,
+	Action: func(c *cli.Context) error {
+		recipeName := c.Args().First()
+
+		if recipeName != "" {
+			internal.ValidateRecipe(c)
+		}
+
+		if err := recipe.EnsureExists(recipeName); err != nil {
+			logrus.Fatal(err)
+		}
+
+		if err := recipe.EnsureUpToDate(recipeName); err != nil {
+			logrus.Fatal(err)
+		}
+
+		if err := recipe.EnsureLatest(recipeName); err != nil {
+			logrus.Fatal(err)
+		}
+
+		return nil
+	},
+}

cli/recipe/lint.go

@@ -2,105 +2,121 @@ package recipe
 
 import (
 	"fmt"
-	"os"
-	"strconv"
 
-	"coopcloud.tech/abra/cli/formatter"
 	"coopcloud.tech/abra/cli/internal"
-	"coopcloud.tech/abra/pkg/catalogue"
+	"coopcloud.tech/abra/pkg/autocomplete"
-	"coopcloud.tech/abra/pkg/config"
+	"coopcloud.tech/abra/pkg/formatter"
-	"coopcloud.tech/tagcmp"
+	"coopcloud.tech/abra/pkg/lint"
-	"github.com/docker/distribution/reference"
+	recipePkg "coopcloud.tech/abra/pkg/recipe"
 	"github.com/sirupsen/logrus"
-	"github.com/urfave/cli/v2"
+	"github.com/urfave/cli"
 )
 
-var recipeLintCommand = &cli.Command{
+var recipeLintCommand = cli.Command{
 	Name:      "lint",
 	Usage:     "Lint a recipe",
 	Aliases:   []string{"l"},
 	ArgsUsage: "<recipe>",
+	Flags: []cli.Flag{
+		internal.DebugFlag,
+		internal.OnlyErrorFlag,
+		internal.OfflineFlag,
+		internal.NoInputFlag,
+		internal.ChaosFlag,
+	},
+	Before:       internal.SubCommandBefore,
+	BashComplete: autocomplete.RecipeNameComplete,
 	Action: func(c *cli.Context) error {
 		recipe := internal.ValidateRecipe(c)
 
-		expectedVersion := false
+		if err := recipePkg.EnsureExists(recipe.Name); err != nil {
-		if recipe.Config.Version == "3.8" {
-			expectedVersion = true
-		}
-
-		envSampleProvided := false
-		envSample := fmt.Sprintf("%s/%s/.env.sample", config.APPS_DIR, recipe.Name)
-		if _, err := os.Stat(envSample); !os.IsNotExist(err) {
-			envSampleProvided = true
-		} else if err != nil {
 			logrus.Fatal(err)
 		}
 
-		serviceNamedApp := false
+		if !internal.Chaos {
-		traefikEnabled := false
+			if err := recipePkg.EnsureIsClean(recipe.Name); err != nil {
-		healthChecksForAllServices := true
-		allImagesTagged := true
-		noUnstableTags := true
-		semverLikeTags := true
-		for _, service := range recipe.Config.Services {
-			if service.Name == "app" {
-				serviceNamedApp = true
-			}
-
-			for label := range service.Deploy.Labels {
-				if label == "traefik.enable" {
-					if service.Deploy.Labels[label] == "true" {
-						traefikEnabled = true
-					}
-				}
-			}
-
-			img, err := reference.ParseNormalizedNamed(service.Image)
-			if err != nil {
 				logrus.Fatal(err)
 			}
-			if reference.IsNameOnly(img) {
-				allImagesTagged = false
-			}
 
-			tag := img.(reference.NamedTagged).Tag()
+			if !internal.Offline {
-			if tag == "latest" {
+				if err := recipePkg.EnsureUpToDate(recipe.Name); err != nil {
-				noUnstableTags = false
+					logrus.Fatal(err)
-			}
-
-			if !tagcmp.IsParsable(tag) {
-				semverLikeTags = false
-			}
-
-			if service.HealthCheck == nil {
-				healthChecksForAllServices = false
 				}
 			}
 
-		tableCol := []string{"rule", "satisfied"}
+			if err := recipePkg.EnsureLatest(recipe.Name); err != nil {
+				logrus.Fatal(err)
+			}
+		}
+
+		tableCol := []string{"ref", "rule", "severity", "satisfied", "skipped", "resolve"}
 		table := formatter.CreateTable(tableCol)
-		table.Append([]string{"compose files have the expected version", strconv.FormatBool(expectedVersion)})
-		table.Append([]string{"environment configuration is provided", strconv.FormatBool(envSampleProvided)})
-		table.Append([]string{"recipe contains a service named 'app'", strconv.FormatBool(serviceNamedApp)})
-		table.Append([]string{"traefik routing enabled on at least one service", strconv.FormatBool(traefikEnabled)})
-		table.Append([]string{"all services have a healthcheck enabled", strconv.FormatBool(healthChecksForAllServices)})
-		table.Append([]string{"all images are using a tag", strconv.FormatBool(allImagesTagged)})
-		table.Append([]string{"no usage of unstable 'latest' tags", strconv.FormatBool(noUnstableTags)})
-		table.Append([]string{"all tags are using a semver-like format", strconv.FormatBool(semverLikeTags)})
-		table.Render()
 
-		return nil
+		hasError := false
-	},
+		bar := formatter.CreateProgressbar(-1, "running recipe lint rules...")
-	BashComplete: func(c *cli.Context) {
+		for level := range lint.LintRules {
-		catl, err := catalogue.ReadRecipeCatalogue()
+			for _, rule := range lint.LintRules[level] {
+				if internal.OnlyErrors && rule.Level != "error" {
+					logrus.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 {
 						logrus.Warn(err)
 					}
-		if c.NArg() > 0 {
+
-			return
+					if !ok && rule.Level == "error" {
+						hasError = true
 					}
-		for name := range catl {
+
-			fmt.Println(name)
+					if ok {
+						satisfied = true
 					}
+				}
+
+				satisfiedOutput := "✅"
+				if !satisfied {
+					satisfiedOutput = "❌"
+					if skipped {
+						satisfiedOutput = "-"
+					}
+				}
+
+				table.Append([]string{
+					rule.Ref,
+					rule.Description,
+					rule.Level,
+					satisfiedOutput,
+					skippedOutput,
+					rule.HowToResolve,
+				})
+
+				bar.Add(1)
+			}
+		}
+
+		if table.NumLines() > 0 {
+			fmt.Println()
+			table.Render()
+		}
+
+		if hasError {
+			logrus.Warn("watch out, some critical errors are present in your recipe config")
+		}
+
+		return nil
 	},
 }

cli/recipe/list.go

@@ -3,36 +3,80 @@ package recipe
 import (
 	"fmt"
 	"sort"
+	"strconv"
+	"strings"
 
-	"coopcloud.tech/abra/cli/formatter"
+	"coopcloud.tech/abra/cli/internal"
-	"coopcloud.tech/abra/pkg/catalogue"
+	"coopcloud.tech/abra/pkg/formatter"
+	"coopcloud.tech/abra/pkg/recipe"
 	"github.com/sirupsen/logrus"
-	"github.com/urfave/cli/v2"
+	"github.com/urfave/cli"
 )
 
-var recipeListCommand = &cli.Command{
+var pattern string
+var patternFlag = &cli.StringFlag{
+	Name:        "pattern, p",
+	Value:       "",
+	Usage:       "Simple string to filter recipes",
+	Destination: &pattern,
+}
+
+var recipeListCommand = cli.Command{
 	Name:    "list",
 	Usage:   "List available recipes",
 	Aliases: []string{"ls"},
+	Flags: []cli.Flag{
+		internal.DebugFlag,
+		internal.MachineReadableFlag,
+		patternFlag,
+		internal.OfflineFlag,
+	},
+	Before: internal.SubCommandBefore,
 	Action: func(c *cli.Context) error {
-		catl, err := catalogue.ReadRecipeCatalogue()
+		catl, err := recipe.ReadRecipeCatalogue(internal.Offline)
 		if err != nil {
 			logrus.Fatal(err.Error())
 		}
 
 		recipes := catl.Flatten()
-		sort.Sort(catalogue.ByRecipeName(recipes))
+		sort.Sort(recipe.ByRecipeName(recipes))
 
-		tableCol := []string{"name", "category", "status"}
+		tableCol := []string{"name", "category", "status", "healthcheck", "backups", "email", "tests", "SSO"}
 		table := formatter.CreateTable(tableCol)
 
+		len := 0
 		for _, recipe := range recipes {
-			status := fmt.Sprintf("%v", recipe.Features.Status)
+			tableRow := []string{
-			tableRow := []string{recipe.Name, recipe.Category, status}
+				recipe.Name,
-			table.Append(tableRow)
+				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.Append(tableRow)
+					len++
+				}
+			} else {
+				table.Append(tableRow)
+				len++
+			}
+		}
+
+		if table.NumLines() > 0 {
+			if internal.MachineReadable {
+				table.SetCaption(false, "")
+				table.JSONRender()
+			} else {
+				table.SetCaption(true, fmt.Sprintf("total recipes: %v", len))
 				table.Render()
+			}
+		}
 
 		return nil
 	},

cli/recipe/new.go

@@ -1,7 +1,10 @@
 package recipe
 
 import (
+	"bytes"
+	"errors"
 	"fmt"
+	"io/ioutil"
 	"os"
 	"path"
 	"text/template"
@@ -10,70 +13,129 @@ import (
 	"coopcloud.tech/abra/pkg/config"
 	"coopcloud.tech/abra/pkg/git"
 	"github.com/sirupsen/logrus"
-	"github.com/urfave/cli/v2"
+	"github.com/urfave/cli"
 )
 
-var recipeNewCommand = &cli.Command{
+// recipeMetadata is the recipe metadata for the README.md
-	Name:      "new",
+type recipeMetadata struct {
-	Usage:     "Create a new recipe",
+	Name        string
-	Aliases:   []string{"n"},
+	Description string
-	ArgsUsage: "<recipe>",
+	Category    string
-	Action: func(c *cli.Context) error {
+	Status      string
-		recipe := internal.ValidateRecipe(c)
+	Image       string
+	Healthcheck string
+	Backups     string
+	Email       string
+	Tests       string
+	SSO         string
+}
 
-		directory := path.Join(config.APPS_DIR, recipe.Name)
+var recipeNewCommand = cli.Command{
+	Name:    "new",
+	Aliases: []string{"n"},
+	Flags: []cli.Flag{
+		internal.DebugFlag,
+		internal.NoInputFlag,
+		internal.OfflineFlag,
+	},
+	Before:    internal.SubCommandBefore,
+	Usage:     "Create a new recipe",
+	ArgsUsage: "<recipe>",
+	Description: `
+Create a new recipe.
+
+Abra uses the built-in example repository which is available here:
+
+    https://git.coopcloud.tech/coop-cloud/example
+
+Files within the example repository make use of the Golang templating system
+which Abra uses to inject values into the generated recipe folder (e.g. name of
+recipe and domain in the sample environment config).
+`,
+	Action: func(c *cli.Context) error {
+		recipeName := c.Args().First()
+
+		if recipeName == "" {
+			internal.ShowSubcommandHelpAndError(c, errors.New("no recipe name provided"))
+		}
+
+		directory := path.Join(config.RECIPES_DIR, recipeName)
 		if _, err := os.Stat(directory); !os.IsNotExist(err) {
-			logrus.Fatalf("'%s' recipe directory already exists?", directory)
+			logrus.Fatalf("%s recipe directory already exists?", directory)
-			return nil
 		}
 
 		url := fmt.Sprintf("%s/example.git", config.REPOS_BASE_URL)
 		if err := git.Clone(directory, url); err != nil {
-			return err
+			logrus.Fatal(err)
 		}
 
-		gitRepo := path.Join(config.APPS_DIR, recipe.Name, ".git")
+		gitRepo := path.Join(config.RECIPES_DIR, recipeName, ".git")
 		if err := os.RemoveAll(gitRepo); err != nil {
 			logrus.Fatal(err)
-			return nil
 		}
-		logrus.Debugf("removed git repo in '%s'", gitRepo)
+		logrus.Debugf("removed example git repo in %s", gitRepo)
+
+		meta := newRecipeMeta(recipeName)
 
 		toParse := []string{
-			path.Join(config.APPS_DIR, recipe.Name, "README.md"),
+			path.Join(config.RECIPES_DIR, recipeName, "README.md"),
-			path.Join(config.APPS_DIR, recipe.Name, ".env.sample"),
+			path.Join(config.RECIPES_DIR, recipeName, ".env.sample"),
-			path.Join(config.APPS_DIR, recipe.Name, ".drone.yml"),
 		}
 		for _, path := range toParse {
-			file, err := os.OpenFile(path, os.O_RDWR, 0755)
-			if err != nil {
-				logrus.Fatal(err)
-				return nil
-			}
-
 			tpl, err := template.ParseFiles(path)
 			if err != nil {
 				logrus.Fatal(err)
-				return nil
 			}
 
-			// TODO: ask for description and probably other things so that the
+			var templated bytes.Buffer
-			// template repository is more "ready" to go than the current best-guess
+			if err := tpl.Execute(&templated, meta); err != nil {
-			// mode of templating
-			if err := tpl.Execute(file, struct {
-				Name        string
-				Description string
-			}{recipe.Name, "TODO"}); err != nil {
 				logrus.Fatal(err)
-				return nil
-			}
 			}
 
-		logrus.Infof(
+			if err := ioutil.WriteFile(path, templated.Bytes(), 0644); err != nil {
-			"new recipe '%s' created in %s, happy hacking!\n",
+				logrus.Fatal(err)
-			recipe.Name, path.Join(config.APPS_DIR, recipe.Name),
+			}
-		)
+
+		}
+
+		newGitRepo := path.Join(config.RECIPES_DIR, recipeName)
+		if err := git.Init(newGitRepo, true); err != nil {
+			logrus.Fatal(err)
+		}
+
+		fmt.Print(fmt.Sprintf(`
+Your new %s recipe has been created in %s.
+
+In order to share your recipe, you can upload it the git repository to:
+
+    https://git.coopcloud.tech/coop-cloud/%s
+
+If you're not sure how to do that, come chat with us:
+
+    https://docs.coopcloud.tech/intro/contact
+
+See "abra recipe -h" for additional recipe maintainer commands.
+
+Happy Hacking!
+
+`, recipeName, path.Join(config.RECIPES_DIR, recipeName), recipeName))
 
 		return nil
 	},
 }
+
+// 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",
+	}
+}

cli/recipe/recipe.go

@@ -1,51 +1,36 @@
 package recipe
 
 import (
-	"github.com/urfave/cli/v2"
+	"github.com/urfave/cli"
 )
 
-var Major bool
-var MajorFlag = &cli.BoolFlag{
-	Name:        "major",
-	Value:       false,
-	Aliases:     []string{"ma", "x"},
-	Destination: &Major,
-}
-
-var Minor bool
-var MinorFlag = &cli.BoolFlag{
-	Name:        "minor",
-	Value:       false,
-	Aliases:     []string{"mi", "y"},
-	Destination: &Minor,
-}
-
-var Patch bool
-var PatchFlag = &cli.BoolFlag{
-	Name:        "patch",
-	Value:       false,
-	Aliases:     []string{"p", "z"},
-	Destination: &Patch,
-}
-
 // RecipeCommand defines all recipe related sub-commands.
-var RecipeCommand = &cli.Command{
+var RecipeCommand = cli.Command{
 	Name:      "recipe",
+	Aliases:   []string{"r"},
 	Usage:     "Manage recipes",
 	ArgsUsage: "<recipe>",
-	Aliases:   []string{"r"},
 	Description: `
-A recipe is a blueprint for an app. It is a bunch of configuration files which
+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 and create apps for you.
+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. Abra supports convenient automation for recipe maintainenace, see the
+"abra recipe upgrade", "abra recipe sync" and "abra recipe release" commands.
 `,
-	Subcommands: []*cli.Command{
+	Subcommands: []cli.Command{
-		recipeListCommand,
+		recipeFetchCommand,
-		recipeVersionCommand,
-		recipeReleaseCommand,
-		recipeNewCommand,
-		recipeUpgradeCommand,
-		recipeSyncCommand,
 		recipeLintCommand,
+		recipeListCommand,
+		recipeNewCommand,
+		recipeReleaseCommand,
+		recipeSyncCommand,
+		recipeUpgradeCommand,
+		recipeVersionCommand,
+		recipeResetCommand,
+		recipeDiffCommand,
 	},
 }

cli/recipe/release.go

@@ -7,306 +7,460 @@ import (
 	"strings"
 
 	"coopcloud.tech/abra/cli/internal"
+	"coopcloud.tech/abra/pkg/autocomplete"
 	"coopcloud.tech/abra/pkg/config"
+	"coopcloud.tech/abra/pkg/formatter"
+	gitPkg "coopcloud.tech/abra/pkg/git"
 	"coopcloud.tech/abra/pkg/recipe"
 	recipePkg "coopcloud.tech/abra/pkg/recipe"
 	"coopcloud.tech/tagcmp"
 	"github.com/AlecAivazis/survey/v2"
+	"github.com/docker/distribution/reference"
 	"github.com/go-git/go-git/v5"
-	"github.com/go-git/go-git/v5/plumbing"
 	"github.com/sirupsen/logrus"
-	"github.com/urfave/cli/v2"
+	"github.com/urfave/cli"
 )
 
-var Push bool
+var recipeReleaseCommand = cli.Command{
-var PushFlag = &cli.BoolFlag{
-	Name:        "push",
-	Value:       false,
-	Destination: &Push,
-}
-
-var Dry bool
-var DryFlag = &cli.BoolFlag{
-	Name:        "dry-run",
-	Value:       false,
-	Aliases:     []string{"d"},
-	Destination: &Dry,
-}
-
-var CommitMessage string
-var CommitMessageFlag = &cli.StringFlag{
-	Name:        "commit-message",
-	Usage:       "commit message. Implies --commit",
-	Aliases:     []string{"cm"},
-	Destination: &CommitMessage,
-}
-
-var Commit bool
-var CommitFlag = &cli.BoolFlag{
-	Name:        "commit",
-	Usage:       "add compose.yml to staging area and commit changes",
-	Value:       false,
-	Aliases:     []string{"c"},
-	Destination: &Commit,
-}
-
-var TagMessage string
-var TagMessageFlag = &cli.StringFlag{
-	Name:        "tag-comment",
-	Usage:       "tag comment. If not given, user will be asked for it",
-	Aliases:     []string{"t", "tm"},
-	Destination: &TagMessage,
-}
-
-var recipeReleaseCommand = &cli.Command{
 	Name:      "release",
-	Usage:     "tag a recipe",
 	Aliases:   []string{"rl"},
-	ArgsUsage: "<recipe> [<tag>]",
+	Usage:     "Release a new recipe version",
+	ArgsUsage: "<recipe> [<version>]",
 	Description: `
-This command is used to specify a new tag for a recipe. These tags are used to
+Create a new version of a recipe. These versions are then published on the
-identify different versions of the recipe and are published on the Co-op Cloud
+Co-op Cloud recipe catalogue. These versions take the following form:
-recipe catalogue.
-
-These tags take the following form:
 
     a.b.c+x.y.z
 
-Where the "a.b.c" part is maintained as a semantic version of the recipe by the
+Where the "a.b.c" part is a semantic version determined by the maintainer. The
-recipe maintainer. And the "x.y.z" part is the image tag of the recipe "app"
+"x.y.z" part is the image tag of the recipe "app" service (the main container
-service (the main container which contains the software to be used).
+which contains the software to be used, by naming convention).
 
-We maintain a semantic versioning scheme ("a.b.c") alongside the libre app
+We maintain a semantic versioning scheme ("a.b.c") alongside the recipe
-versioning scheme in order to maximise the chances that the nature of recipe
+versioning scheme ("x.y.z") in order to maximise the chances that the nature of
-updates are properly communicated.
+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.
 
-Abra does its best to read the "a.b.c" version scheme and communicate what
+Publish your new release to git.coopcloud.tech with "-p/--publish". This
-action needs to be taken when performing different operations such as an update
+requires that you have permission to git push to these repositories and have
-or a rollback of an app.
+your SSH keys configured on your account.
 `,
 	Flags: []cli.Flag{
-		DryFlag,
+		internal.DebugFlag,
-		PatchFlag,
+		internal.NoInputFlag,
-		MinorFlag,
+		internal.DryFlag,
-		MajorFlag,
+		internal.MajorFlag,
-		PushFlag,
+		internal.MinorFlag,
-		CommitFlag,
+		internal.PatchFlag,
-		CommitMessageFlag,
+		internal.PublishFlag,
-		TagMessageFlag,
+		internal.OfflineFlag,
 	},
+	Before:       internal.SubCommandBefore,
+	BashComplete: autocomplete.RecipeNameComplete,
 	Action: func(c *cli.Context) error {
 		recipe := internal.ValidateRecipe(c)
-		directory := path.Join(config.APPS_DIR, recipe.Name)
+
-		tagstring := c.Args().Get(1)
+		imagesTmp, err := getImageVersions(recipe)
-		imagesTmp := getImageVersions(recipe)
+		if err != nil {
-		mainApp := getMainApp(recipe)
+			logrus.Fatal(err)
+		}
+
+		mainApp, err := internal.GetMainAppImage(recipe)
+		if err != nil {
+			logrus.Fatal(err)
+		}
+
 		mainAppVersion := imagesTmp[mainApp]
-
-		if err := recipePkg.EnsureExists(recipe.Name); err != nil {
-			logrus.Fatal(err)
-		}
-
 		if mainAppVersion == "" {
-			logrus.Fatal("main app version is empty?")
+			logrus.Fatalf("main app service version for %s is empty?", recipe.Name)
 		}
 
-		if tagstring != "" {
+		tagString := c.Args().Get(1)
-			if _, err := tagcmp.Parse(tagstring); err != nil {
+		if tagString != "" {
-				logrus.Fatal("invalid tag specified")
+			if _, err := tagcmp.Parse(tagString); err != nil {
+				logrus.Fatalf("cannot parse %s, invalid tag specified?", tagString)
 			}
 		}
 
-		if TagMessage == "" {
+		if (internal.Major || internal.Minor || internal.Patch) && tagString != "" {
-			prompt := &survey.Input{
+			logrus.Fatal("cannot specify tag and bump type at the same time")
-				Message: "tag message",
-			}
-			survey.AskOne(prompt, &TagMessage)
 		}
 
-		var createTagOptions git.CreateTagOptions
+		if tagString != "" {
-		createTagOptions.Message = TagMessage
+			if err := createReleaseFromTag(recipe, tagString, mainAppVersion); err != nil {
-
-		if Commit || (CommitMessage != "") {
-			commitRepo, err := git.PlainOpen(directory)
-			if err != nil {
 				logrus.Fatal(err)
 			}
-			commitWorktree, err := commitRepo.Worktree()
+		}
+
+		tags, err := recipe.Tags()
 		if err != nil {
 			logrus.Fatal(err)
 		}
 
-			if CommitMessage == "" {
+		if tagString == "" && (!internal.Major && !internal.Minor && !internal.Patch) {
-				prompt := &survey.Input{
+			var err error
-					Message: "commit message",
+			tagString, err = getLabelVersion(recipe, false)
-				}
-				survey.AskOne(prompt, &CommitMessage)
-			}
-			err = commitWorktree.AddGlob("compose.**yml")
 			if err != nil {
 				logrus.Fatal(err)
 			}
-			logrus.Debug("staged compose.**yml for commit")
+		}
 
-			_, err = commitWorktree.Commit(CommitMessage, &git.CommitOptions{})
+		isClean, err := gitPkg.IsClean(recipe.Dir())
 		if err != nil {
 			logrus.Fatal(err)
 		}
-			logrus.Info("changes commited")
+
+		if !isClean {
+			logrus.Infof("%s currently has these unstaged changes 👇", recipe.Name)
+			if err := gitPkg.DiffUnstaged(recipe.Dir()); err != nil {
+				logrus.Fatal(err)
+			}
 		}
 
+		if len(tags) > 0 {
+			logrus.Warnf("previous git tags detected, assuming this is a new semver release")
+			if err := createReleaseFromPreviousTag(tagString, mainAppVersion, recipe, tags); err != nil {
+				logrus.Fatal(err)
+			}
+		} else {
+			logrus.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(tagString, recipe.Name); err != nil {
+					logrus.Fatal(cleanUpErr)
+				}
+				logrus.Fatal(err)
+			}
+		}
+
+		return nil
+	},
+}
+
+// getImageVersions retrieves image versions for a recipe
+func getImageVersions(recipe recipe.Recipe) (map[string]string, error) {
+	var services = make(map[string]string)
+
+	missingTag := false
+	for _, service := range recipe.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
+
+	directory := path.Join(config.RECIPES_DIR, recipe.Name)
 	repo, err := git.PlainOpen(directory)
 	if err != nil {
-			logrus.Fatal(err)
+		return err
-		}
-		head, err := repo.Head()
-		if err != nil {
-			logrus.Fatal(err)
 	}
 
-		// bumpType is used to decide what part of the tag should be incremented
+	tag, err := tagcmp.Parse(tagString)
-		bumpType := btoi(Major)*4 + btoi(Minor)*2 + btoi(Patch)
+	if err != nil {
-		if bumpType != 0 {
+		return err
-			// a bitwise check if the number is a power of 2
-			if (bumpType & (bumpType - 1)) != 0 {
-				logrus.Fatal("you can only use one of: --major, --minor, --patch.")
-			}
 	}
 
-		if tagstring != "" {
-			if bumpType > 0 {
-				logrus.Warn("user specified a version number and --major/--minor/--patch at the same time! using version number...")
-			}
-			tag, err := tagcmp.Parse(tagstring)
-			if err != nil {
-				logrus.Fatal(err)
-			}
 	if tag.MissingMinor {
 		tag.Minor = "0"
 		tag.MissingMinor = false
 	}
+
 	if tag.MissingPatch {
 		tag.Patch = "0"
 		tag.MissingPatch = false
 	}
-			tagstring = fmt.Sprintf("%s+%s", tag.String(), mainAppVersion)
+
-			if Dry {
+	if tagString == "" {
-				logrus.Info(fmt.Sprintf("dry run only: NOT creating tag %s at %s", tagstring, head.Hash()))
+		tagString = fmt.Sprintf("%s+%s", tag.String(), mainAppVersion)
-				return nil
 	}
 
-			repo.CreateTag(tagstring, head.Hash(), &createTagOptions)
+	if err := commitRelease(recipe, tagString); err != nil {
-			logrus.Info(fmt.Sprintf("created tag %s at %s", tagstring, head.Hash()))
-			if Push {
-				if err := repo.Push(&git.PushOptions{}); err != nil {
 		logrus.Fatal(err)
 	}
-				logrus.Info(fmt.Sprintf("pushed tag %s to remote", tagstring))
+
+	if err := tagRelease(tagString, repo); err != nil {
+		logrus.Fatal(err)
+	}
+
+	if err := pushRelease(recipe, tagString); err != nil {
+		logrus.Fatal(err)
 	}
 
 	return nil
 }
 
-		// get the latest tag with its hash, name etc
+// btoi converts a boolean value into an integer
-		var lastGitTag tagcmp.Tag
-		iter, err := repo.Tags()
-		if err != nil {
-			logrus.Fatal(err)
-		}
-		if err := iter.ForEach(func(ref *plumbing.Reference) error {
-			obj, err := repo.TagObject(ref.Hash())
-			if err != nil {
-				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 {
-			logrus.Fatal(err)
-		}
-
-		fmt.Println(lastGitTag)
-
-		newTag := lastGitTag
-		var newTagString string
-		if bumpType > 0 {
-			if Patch {
-				now, err := strconv.Atoi(newTag.Patch)
-				if err != nil {
-					logrus.Fatal(err)
-				}
-				newTag.Patch = strconv.Itoa(now + 1)
-			} else if Minor {
-				now, err := strconv.Atoi(newTag.Minor)
-				if err != nil {
-					logrus.Fatal(err)
-				}
-				newTag.Patch = "0"
-				newTag.Minor = strconv.Itoa(now + 1)
-			} else if Major {
-				now, err := strconv.Atoi(newTag.Major)
-				if err != nil {
-					logrus.Fatal(err)
-				}
-				newTag.Patch = "0"
-				newTag.Minor = "0"
-				newTag.Major = strconv.Itoa(now + 1)
-			}
-		} else {
-			logrus.Fatal("we don't support automatic tag generation yet - specify a version or use one of: --major --minor --patch")
-		}
-		newTag.Metadata = mainAppVersion
-		newTagString = newTag.String()
-		if Dry {
-			logrus.Info(fmt.Sprintf("dry run only: NOT creating tag %s at %s", newTagString, head.Hash()))
-			return nil
-		}
-
-		repo.CreateTag(newTagString, head.Hash(), &createTagOptions)
-		logrus.Info(fmt.Sprintf("created tag %s at %s", newTagString, head.Hash()))
-		if Push {
-			if err := repo.Push(&git.PushOptions{}); err != nil {
-				logrus.Fatal(err)
-			}
-			logrus.Info(fmt.Sprintf("pushed tag %s to remote", newTagString))
-		}
-
-		return nil
-
-	},
-}
-
-func getImageVersions(recipe recipe.Recipe) map[string]string {
-
-	var services = make(map[string]string)
-	for _, service := range recipe.Config.Services {
-		srv := strings.Split(service.Image, ":")
-		services[srv[0]] = srv[1]
-	}
-
-	return services
-}
-
-func getMainApp(recipe recipe.Recipe) string {
-	for _, service := range recipe.Config.Services {
-		name := service.Name
-		if name == "app" {
-			return strings.Split(service.Image, ":")[0]
-		}
-	}
-	return ""
-}
-
 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
+}
+
+func commitRelease(recipe recipe.Recipe, tag string) error {
+	if internal.Dry {
+		logrus.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)
+	repoPath := path.Join(config.RECIPES_DIR, recipe.Name)
+	if err := gitPkg.Commit(repoPath, msg, internal.Dry); err != nil {
+		return err
+	}
+
+	return nil
+}
+
+func tagRelease(tagString string, repo *git.Repository) error {
+	if internal.Dry {
+		logrus.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())
+	logrus.Debugf(fmt.Sprintf("created tag %s at %s", tagString, hash))
+
+	return nil
+}
+
+func pushRelease(recipe recipe.Recipe, tagString string) error {
+	if internal.Dry {
+		logrus.Info("dry run: no changes published")
+		return nil
+	}
+
+	if !internal.Publish && !internal.NoInput {
+		prompt := &survey.Confirm{
+			Message: "publish new release?",
+		}
+
+		if err := survey.AskOne(prompt, &internal.Publish); err != nil {
+			return err
+		}
+	}
+
+	if internal.Publish {
+		if err := recipe.Push(internal.Dry); err != nil {
+			return err
+		}
+		url := fmt.Sprintf("%s/%s/src/tag/%s", config.REPOS_BASE_URL, recipe.Name, tagString)
+		logrus.Infof("new release published: %s", url)
+	} else {
+		logrus.Info("no -p/--publish passed, not publishing")
+	}
+
+	return nil
+}
+
+func createReleaseFromPreviousTag(tagString, mainAppVersion string, recipe recipe.Recipe, tags []string) error {
+	directory := path.Join(config.RECIPES_DIR, recipe.Name)
+	repo, err := git.PlainOpen(directory)
+	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 {
+		logrus.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 {
+			logrus.Fatal(err)
+		}
+
+		if !ok {
+			logrus.Fatal("exiting as requested")
+		}
+	}
+
+	if err := commitRelease(recipe, tagString); err != nil {
+		logrus.Fatalf("failed to commit changes: %s", err.Error())
+	}
+
+	if err := tagRelease(tagString, repo); err != nil {
+		logrus.Fatalf("failed to tag release: %s", err.Error())
+	}
+
+	if err := pushRelease(recipe, tagString); err != nil {
+		logrus.Fatalf("failed to publish new release: %s", err.Error())
+	}
+
+	return nil
+}
+
+// cleanUpTag removes a freshly created tag
+func cleanUpTag(tag, recipeName string) error {
+	directory := path.Join(config.RECIPES_DIR, recipeName)
+	repo, err := git.PlainOpen(directory)
+	if err != nil {
+		return err
+	}
+
+	if err := repo.DeleteTag(tag); err != nil {
+		if !strings.Contains(err.Error(), "not found") {
+			return err
+		}
+	}
+
+	logrus.Debugf("removed freshly created tag %s", tag)
+
+	return nil
+}
+
+func getLabelVersion(recipe recipe.Recipe, prompt bool) (string, error) {
+	initTag, err := recipePkg.GetVersionLabelLocal(recipe)
+	if err != nil {
+		return "", err
+	}
+
+	if initTag == "" {
+		logrus.Fatalf("unable to read version for %s from synced label. Did you try running \"abra recipe sync %s\" already?", recipe.Name, recipe.Name)
+	}
+
+	logrus.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
+}

cli/recipe/reset.go

@@ -0,0 +1,56 @@
+package recipe
+
+import (
+	"path"
+
+	"coopcloud.tech/abra/cli/internal"
+	"coopcloud.tech/abra/pkg/autocomplete"
+	"coopcloud.tech/abra/pkg/config"
+	"github.com/go-git/go-git/v5"
+	"github.com/sirupsen/logrus"
+	"github.com/urfave/cli"
+)
+
+var recipeResetCommand = cli.Command{
+	Name:        "reset",
+	Usage:       "Remove all unstaged changes from recipe config",
+	Description: "WARNING, this will delete your changes. Be Careful.",
+	Aliases:     []string{"rs"},
+	ArgsUsage:   "<recipe>",
+	Flags: []cli.Flag{
+		internal.DebugFlag,
+		internal.NoInputFlag,
+	},
+	Before:       internal.SubCommandBefore,
+	BashComplete: autocomplete.RecipeNameComplete,
+	Action: func(c *cli.Context) error {
+		recipeName := c.Args().First()
+
+		if recipeName != "" {
+			internal.ValidateRecipe(c)
+		}
+
+		repoPath := path.Join(config.RECIPES_DIR, recipeName)
+		repo, err := git.PlainOpen(repoPath)
+		if err != nil {
+			logrus.Fatal(err)
+		}
+
+		ref, err := repo.Head()
+		if err != nil {
+			logrus.Fatal(err)
+		}
+
+		worktree, err := repo.Worktree()
+		if err != nil {
+			logrus.Fatal(err)
+		}
+
+		opts := &git.ResetOptions{Commit: ref.Hash(), Mode: git.HardReset}
+		if err := worktree.Reset(opts); err != nil {
+			logrus.Fatal(err)
+		}
+
+		return nil
+	},
+}

cli/recipe/sync.go

@@ -1,87 +1,214 @@
 package recipe
 
 import (
-	"errors"
 	"fmt"
+	"path"
+	"strconv"
 
 	"coopcloud.tech/abra/cli/internal"
-	"coopcloud.tech/abra/pkg/catalogue"
+	"coopcloud.tech/abra/pkg/autocomplete"
+	"coopcloud.tech/abra/pkg/config"
+	gitPkg "coopcloud.tech/abra/pkg/git"
+	"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/sirupsen/logrus"
-	"github.com/urfave/cli/v2"
+	"github.com/urfave/cli"
 )
 
-var recipeSyncCommand = &cli.Command{
+var recipeSyncCommand = cli.Command{
 	Name:      "sync",
-	Usage:     "Ensure recipe version labels are up-to-date",
 	Aliases:   []string{"s"},
-	ArgsUsage: "<recipe> <version>",
+	Usage:     "Sync recipe version label",
+	ArgsUsage: "<recipe> [<version>]",
+	Flags: []cli.Flag{
+		internal.DebugFlag,
+		internal.NoInputFlag,
+		internal.DryFlag,
+		internal.MajorFlag,
+		internal.MinorFlag,
+		internal.PatchFlag,
+	},
+	Before: internal.SubCommandBefore,
 	Description: `
-This command will generate labels for the main recipe service (i.e. by
+Generate labels for the main recipe service (i.e. by convention, the service
-convention, typically the service named "app") which corresponds to the
+named "app") which corresponds to the following format:
-following format:
 
     coop-cloud.${STACK_NAME}.version=<version>
 
-The <version> is determined by the recipe maintainer and is specified on the
+Where <version> can be specifed on the command-line or Abra can attempt to
-command-line. The <recipe> configuration will be updated on the local file
+auto-generate it for you. The <recipe> configuration will be updated on the
-system.
+local file system.
 `,
-	BashComplete: func(c *cli.Context) {
+	BashComplete: autocomplete.RecipeNameComplete,
-		catl, err := catalogue.ReadRecipeCatalogue()
-		if err != nil {
-			logrus.Warn(err)
-		}
-		if c.NArg() > 0 {
-			return
-		}
-		for name := range catl {
-			fmt.Println(name)
-		}
-	},
 	Action: func(c *cli.Context) error {
-		if c.Args().Len() != 2 {
-			internal.ShowSubcommandHelpAndError(c, errors.New("missing <recipe>/<version> arguments?"))
-		}
-
 		recipe := internal.ValidateRecipe(c)
 
-		// TODO: validate with tagcmp when new commits come in
+		mainApp, err := internal.GetMainAppImage(recipe)
-		// See https://git.coopcloud.tech/coop-cloud/abra/pulls/109
+		if err != nil {
+			logrus.Fatal(err)
+		}
+
+		imagesTmp, err := getImageVersions(recipe)
+		if err != nil {
+			logrus.Fatal(err)
+		}
+
+		mainAppVersion := imagesTmp[mainApp]
+
+		tags, err := recipe.Tags()
+		if err != nil {
+			logrus.Fatal(err)
+		}
+
 		nextTag := c.Args().Get(1)
+		if len(tags) == 0 && nextTag == "" {
+			logrus.Warnf("no git tags found for %s", recipe.Name)
+			if internal.NoInput {
+				logrus.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 {
+				logrus.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 {
+				logrus.Fatal(err)
+			}
+		}
+
+		if nextTag == "" {
+			recipeDir := path.Join(config.RECIPES_DIR, recipe.Name)
+			repo, err := git.PlainOpen(recipeDir)
+			if err != nil {
+				logrus.Fatal(err)
+			}
+
+			var lastGitTag tagcmp.Tag
+			iter, err := repo.Tags()
+			if err != nil {
+				logrus.Fatal(err)
+			}
+
+			if err := iter.ForEach(func(ref *plumbing.Reference) error {
+				obj, err := repo.TagObject(ref.Hash())
+				if err != nil {
+					logrus.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 {
+				logrus.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 {
+					logrus.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 {
+						logrus.Fatal(err)
+					}
+
+					newTag.Patch = strconv.Itoa(now + 1)
+				} else if internal.Minor {
+					now, err := strconv.Atoi(newTag.Minor)
+					if err != nil {
+						logrus.Fatal(err)
+					}
+
+					newTag.Patch = "0"
+					newTag.Minor = strconv.Itoa(now + 1)
+				} else if internal.Major {
+					now, err := strconv.Atoi(newTag.Major)
+					if err != nil {
+						logrus.Fatal(err)
+					}
+
+					newTag.Patch = "0"
+					newTag.Minor = "0"
+					newTag.Major = strconv.Itoa(now + 1)
+				}
+			}
+
+			newTag.Metadata = mainAppVersion
+			logrus.Debugf("choosing %s as new version for %s", newTag.String(), recipe.Name)
+			nextTag = newTag.String()
+		}
+
+		if _, err := tagcmp.Parse(nextTag); err != nil {
+			logrus.Fatalf("invalid version %s specified", nextTag)
+		}
 
 		mainService := "app"
-		var services []string
-		hasAppService := false
-		for _, service := range recipe.Config.Services {
-			services = append(services, service.Name)
-			if service.Name == "app" {
-				hasAppService = true
-				logrus.Debugf("detected app service in '%s'", recipe.Name)
-			}
-		}
-
-		if !hasAppService {
-			logrus.Warnf("no 'app' service defined in '%s'", recipe.Name)
-			var chosenService string
-			prompt := &survey.Select{
-				Message: fmt.Sprintf("what is the main service name for '%s'?", recipe.Name),
-				Options: services,
-			}
-			if err := survey.AskOne(prompt, &chosenService); err != nil {
-				logrus.Fatal(err)
-			}
-			mainService = chosenService
-		}
-
-		logrus.Debugf("selecting '%s' as the service to sync version labels", mainService)
-
 		label := fmt.Sprintf("coop-cloud.${STACK_NAME}.version=%s", nextTag)
-		if err := recipe.UpdateLabel(mainService, label); err != nil {
+		if !internal.Dry {
+			if err := recipe.UpdateLabel("compose.y*ml", mainService, label); err != nil {
 				logrus.Fatal(err)
 			}
+		} else {
+			logrus.Infof("dry run: not syncing label %s for recipe %s", nextTag, recipe.Name)
+		}
 
-		logrus.Infof("synced label '%s' to service '%s'", label, mainService)
+		isClean, err := gitPkg.IsClean(recipe.Dir())
+		if err != nil {
+			logrus.Fatal(err)
+		}
+		if !isClean {
+			logrus.Infof("%s currently has these unstaged changes 👇", recipe.Name)
+			if err := gitPkg.DiffUnstaged(recipe.Dir()); err != nil {
+				logrus.Fatal(err)
+			}
+		}
 
 		return nil
 	},

cli/recipe/upgrade.go

@@ -1,43 +1,95 @@
 package recipe
 
 import (
+	"bufio"
+	"encoding/json"
 	"fmt"
+	"os"
+	"path"
 	"sort"
 	"strings"
 
 	"coopcloud.tech/abra/cli/internal"
-	"coopcloud.tech/abra/pkg/catalogue"
+	"coopcloud.tech/abra/pkg/autocomplete"
 	"coopcloud.tech/abra/pkg/client"
+	"coopcloud.tech/abra/pkg/config"
+	"coopcloud.tech/abra/pkg/formatter"
+	gitPkg "coopcloud.tech/abra/pkg/git"
+	recipePkg "coopcloud.tech/abra/pkg/recipe"
 	"coopcloud.tech/tagcmp"
 	"github.com/AlecAivazis/survey/v2"
 	"github.com/docker/distribution/reference"
 	"github.com/sirupsen/logrus"
-	"github.com/urfave/cli/v2"
+	"github.com/urfave/cli"
 )
 
-var recipeUpgradeCommand = &cli.Command{
+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 = cli.Command{
 	Name:    "upgrade",
-	Usage:   "Upgrade recipe image tags",
 	Aliases: []string{"u"},
+	Usage:   "Upgrade recipe image tags",
 	Description: `
-This command reads and attempts to parse all image tags within the given
+Parse all image tags within the given <recipe> configuration and prompt with
-<recipe> configuration and prompt with more recent tags to upgrade to. It will
+more recent tags to upgrade to. It will update the relevant compose file tags
-update the relevant compose file tags on the local file system.
+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:
+
+    abra recipe upgrade
 `,
 	ArgsUsage: "<recipe>",
 	Flags: []cli.Flag{
-		PatchFlag,
+		internal.DebugFlag,
-		MinorFlag,
+		internal.NoInputFlag,
-		MajorFlag,
+		internal.PatchFlag,
+		internal.MinorFlag,
+		internal.MajorFlag,
+		internal.MachineReadableFlag,
+		internal.AllTagsFlag,
 	},
+	Before:       internal.SubCommandBefore,
+	BashComplete: autocomplete.RecipeNameComplete,
 	Action: func(c *cli.Context) error {
 		recipe := internal.ValidateRecipe(c)
 
-		bumpType := btoi(Major)*4 + btoi(Minor)*2 + btoi(Patch)
+		if err := recipePkg.EnsureIsClean(recipe.Name); err != nil {
+			logrus.Fatal(err)
+		}
+
+		if err := recipePkg.EnsureExists(recipe.Name); err != nil {
+			logrus.Fatal(err)
+		}
+
+		if err := recipePkg.EnsureUpToDate(recipe.Name); err != nil {
+			logrus.Fatal(err)
+		}
+
+		if err := recipePkg.EnsureLatest(recipe.Name); err != nil {
+			logrus.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 {
@@ -45,46 +97,86 @@ is up to the end-user to decide.
 			}
 		}
 
-		for _, service := range recipe.Config.Services {
+		if internal.MachineReadable {
-			catlVersions, err := catalogue.VersionsOfService(recipe.Name, service.Name)
+			// -m implies -n in this case
+			internal.NoInput = true
+		}
+
+		upgradeList := make(map[string]anUpgrade)
+
+		// check for versions file and load pinned versions
+		versionsPresent := false
+		recipeDir := path.Join(config.RECIPES_DIR, recipe.Name)
+		versionsPath := path.Join(recipeDir, "versions")
+		var servicePins = make(map[string]imgPin)
+		if _, err := os.Stat(versionsPath); err == nil {
+			logrus.Debugf("found versions file for %s", recipe.Name)
+			file, err := os.Open(versionsPath)
 			if err != nil {
 				logrus.Fatal(err)
 			}
+			scanner := bufio.NewScanner(file)
+			for scanner.Scan() {
+				line := scanner.Text()
+				splitLine := strings.Split(line, " ")
+				if splitLine[0] != "pin" || len(splitLine) != 3 {
+					logrus.Fatalf("malformed version pin specification: %s", line)
+				}
+				pinSlice := strings.Split(splitLine[2], ":")
+				pinTag, err := tagcmp.Parse(pinSlice[1])
+				if err != nil {
+					logrus.Fatal(err)
+				}
+				pin := imgPin{
+					image:   pinSlice[0],
+					version: pinTag,
+				}
+				servicePins[splitLine[1]] = pin
+			}
+			if err := scanner.Err(); err != nil {
+				logrus.Error(err)
+			}
+			versionsPresent = true
+		} else {
+			logrus.Debugf("did not find versions file for %s", recipe.Name)
+		}
 
+		for _, service := range recipe.Config.Services {
 			img, err := reference.ParseNormalizedNamed(service.Image)
 			if err != nil {
 				logrus.Fatal(err)
 			}
 
-			image := reference.Path(img)
+			regVersions, err := client.GetRegistryTags(img)
-			regVersions, err := client.GetRegistryTags(image)
 			if err != nil {
 				logrus.Fatal(err)
 			}
-			logrus.Debugf("retrieved '%s' from remote registry for '%s'", regVersions, image)
 
-			if strings.Contains(image, "library") {
+			image := reference.Path(img)
-				// ParseNormalizedNamed prepends 'library' to images like nginx:<tag>,
+			logrus.Debugf("retrieved %s from remote registry for %s", regVersions, image)
-				// postgres:<tag>, i.e. images which do not have a username in the
+			image = formatter.StripTagMeta(image)
-				// first position of the string
-				image = strings.Split(image, "/")[1]
-			}
 
-			semverLikeTag := true
+			switch img.(type) {
+			case reference.NamedTagged:
 				if !tagcmp.IsParsable(img.(reference.NamedTagged).Tag()) {
-				logrus.Debugf("'%s' not considered semver-like", img.(reference.NamedTagged).Tag())
+					logrus.Debugf("%s not considered semver-like", img.(reference.NamedTagged).Tag())
-				semverLikeTag = false
+				}
+			default:
+				logrus.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 && semverLikeTag {
+			if err != nil {
-				logrus.Fatal(err)
+				logrus.Warnf("unable to parse %s, error was: %s, skipping upgrade for %s", image, err.Error(), service.Name)
+				continue
 			}
-			logrus.Debugf("parsed '%s' for '%s'", tag, service.Name)
+
+			logrus.Debugf("parsed %s for %s", tag, service.Name)
 
 			var compatible []tagcmp.Tag
 			for _, regVersion := range regVersions {
-				other, err := tagcmp.Parse(regVersion.Name)
+				other, err := tagcmp.Parse(regVersion)
 				if err != nil {
 					continue // skip tags that cannot be parsed
 				}
@@ -94,16 +186,21 @@ is up to the end-user to decide.
 				}
 			}
 
-			logrus.Debugf("detected potential upgradable tags '%s' for '%s'", compatible, service.Name)
+			logrus.Debugf("detected potential upgradable tags %s for %s", compatible, service.Name)
 
 			sort.Sort(tagcmp.ByTagDesc(compatible))
 
-			if len(compatible) == 0 && semverLikeTag {
+			if len(compatible) == 0 && !internal.AllTags {
-				logrus.Info(fmt.Sprintf("no new versions available for '%s', '%s' is the latest", image, tag))
+				logrus.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
 			}
 
-			var compatibleStrings []string
+			catlVersions, err := recipePkg.VersionsOfService(recipe.Name, service.Name, internal.Offline)
+			if err != nil {
+				logrus.Fatal(err)
+			}
+
+			compatibleStrings := []string{"skip"}
 			for _, compat := range compatible {
 				skip := false
 				for _, catlVersion := range catlVersions {
@@ -116,8 +213,33 @@ is up to the end-user to decide.
 				}
 			}
 
-			logrus.Debugf("detected compatible upgradable tags '%s' for '%s'", compatibleStrings, service.Name)
+			logrus.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 {
+						logrus.Infof("upgrading service %s from %s to %s (pinned tag: %s)", service.Name, tag.String(), upgradeTag, pinnedTagString)
+					} else {
+						logrus.Infof("service %s, image %s pinned to %s, no compatible upgrade found", service.Name, servicePins[service.Name].image, pinnedTagString)
+						continue
+					}
+				} else {
+					logrus.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)
@@ -131,34 +253,101 @@ is up to the end-user to decide.
 						}
 					}
 					if upgradeTag == "" {
-					logrus.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)
+						logrus.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, tag: %s)", service.Name, tag)
+					msg := fmt.Sprintf("upgrade to which tag? (service: %s, image: %s, tag: %s)", service.Name, image, tag)
-				if !tagcmp.IsParsable(img.(reference.NamedTagged).Tag()) {
+					if !tagcmp.IsParsable(img.(reference.NamedTagged).Tag()) || internal.AllTags {
 						tag := img.(reference.NamedTagged).Tag()
-					logrus.Warning(fmt.Sprintf("unable to determine versioning semantics of '%s', listing all tags", tag))
+						if !internal.AllTags {
+							logrus.Warning(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{}
+						compatibleStrings = []string{"skip"}
 						for _, regVersion := range regVersions {
-						compatibleStrings = append(compatibleStrings, regVersion.Name)
+							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 {
 							logrus.Fatal(err)
 						}
 					}
-
+				}
-			if err := recipe.UpdateTag(image, upgradeTag); err != nil {
+			}
+			if upgradeTag != "skip" {
+				ok, err := recipe.UpdateTag(image, upgradeTag)
+				if err != nil {
+					logrus.Fatal(err)
+				}
+				if ok {
+					logrus.Infof("tag upgraded from %s to %s for %s", tag.String(), upgradeTag, image)
+				}
+			} else {
+				if !internal.NoInput {
+					logrus.Warnf("not upgrading %s, skipping as requested", image)
+				}
+			}
+		}
+
+		if internal.NoInput {
+			if internal.MachineReadable {
+				jsonstring, err := json.Marshal(upgradeList)
+				if err != nil {
+					logrus.Fatal(err)
+				}
+
+				fmt.Println(string(jsonstring))
+
+				return nil
+			}
+
+			for _, upgrade := range upgradeList {
+				logrus.Infof("can upgrade service: %s, image: %s, tag: %s ::\n", upgrade.Service, upgrade.Image, upgrade.Tag)
+				for _, utag := range upgrade.UpgradeTags {
+					logrus.Infof("    %s\n", utag)
+				}
+			}
+		}
+
+		isClean, err := gitPkg.IsClean(recipeDir)
+		if err != nil {
+			logrus.Fatal(err)
+		}
+		if !isClean {
+			logrus.Infof("%s currently has these unstaged changes 👇", recipe.Name)
+			if err := gitPkg.DiffUnstaged(recipeDir); err != nil {
 				logrus.Fatal(err)
 			}
-			logrus.Infof("tag upgraded from '%s' to '%s' for '%s'", tag.String(), upgradeTag, image)
 		}
 
 		return nil

cli/recipe/version.go

@@ -1,44 +1,84 @@
 package recipe
 
 import (
-	"coopcloud.tech/abra/cli/formatter"
+	"fmt"
+	"sort"
+
 	"coopcloud.tech/abra/cli/internal"
-	"coopcloud.tech/abra/pkg/catalogue"
+	"coopcloud.tech/abra/pkg/autocomplete"
+	"coopcloud.tech/abra/pkg/formatter"
+	recipePkg "coopcloud.tech/abra/pkg/recipe"
+	"github.com/olekukonko/tablewriter"
 	"github.com/sirupsen/logrus"
-	"github.com/urfave/cli/v2"
+	"github.com/urfave/cli"
 )
 
-var recipeVersionCommand = &cli.Command{
+func sortServiceByName(versions [][]string) func(i, j int) bool {
+	return func(i, j int) bool {
+		// NOTE(d1): corresponds to the `tableCol` definition below
+		if versions[i][1] == "app" {
+			return true
+		}
+		return versions[i][1] < versions[j][1]
+	}
+}
+
+var recipeVersionCommand = cli.Command{
 	Name:        "versions",
-	Usage:     "List recipe versions",
 	Aliases:     []string{"v"},
+	Usage:       "List recipe versions",
 	ArgsUsage:   "<recipe>",
+	Description: "Versions are read from the recipe catalogue.",
+	Flags: []cli.Flag{
+		internal.DebugFlag,
+		internal.OfflineFlag,
+		internal.NoInputFlag,
+		internal.MachineReadableFlag,
+	},
+	Before:       internal.SubCommandBefore,
+	BashComplete: autocomplete.RecipeNameComplete,
 	Action: func(c *cli.Context) error {
 		recipe := internal.ValidateRecipe(c)
 
-		catalogue, err := catalogue.ReadRecipeCatalogue()
+		catl, err := recipePkg.ReadRecipeCatalogue(internal.Offline)
 		if err != nil {
 			logrus.Fatal(err)
 		}
 
-		recipeMeta, ok := catalogue[recipe.Name]
+		recipeMeta, ok := catl[recipe.Name]
 		if !ok {
-			logrus.Fatalf("'%s' recipe doesn't exist?", recipe.Name)
+			logrus.Fatalf("%s is not published on the catalogue?", recipe.Name)
 		}
 
-		tableCol := []string{"Version", "Service", "Image", "Tag", "Digest"}
+		if len(recipeMeta.Versions) == 0 {
-		table := formatter.CreateTable(tableCol)
+			logrus.Fatalf("%s has no catalogue published versions?", recipe.Name)
+		}
 
-		for _, serviceVersion := range recipeMeta.Versions {
+		for i := len(recipeMeta.Versions) - 1; i >= 0; i-- {
-			for tag, meta := range serviceVersion {
+			tableCols := []string{"version", "service", "image", "tag"}
+			table := formatter.CreateTable(tableCols)
+			for version, meta := range recipeMeta.Versions[i] {
+				var versions [][]string
 				for service, serviceMeta := range meta {
-					table.Append([]string{tag, service, serviceMeta.Image, serviceMeta.Tag, serviceMeta.Digest})
+					versions = append(versions, []string{version, service, serviceMeta.Image, serviceMeta.Tag})
-				}
-			}
 				}
 
-		table.SetAutoMergeCells(true)
+				sort.Slice(versions, sortServiceByName(versions))
+
+				for _, version := range versions {
+					table.Append(version)
+				}
+
+				if internal.MachineReadable {
+					table.JSONRender()
+				} else {
+					table.SetAutoMergeCellsByColumnIndex([]int{0})
+					table.SetAlignment(tablewriter.ALIGN_LEFT)
 					table.Render()
+					fmt.Println()
+				}
+			}
+		}
 
 		return nil
 	},

cli/server/add.go

@@ -1,137 +1,180 @@
 package server
 
 import (
-	"context"
 	"errors"
-	"os/user"
+	"os"
-	"strings"
+	"path/filepath"
 
 	"coopcloud.tech/abra/cli/internal"
 	"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/server"
+	sshPkg "coopcloud.tech/abra/pkg/ssh"
 	"github.com/sirupsen/logrus"
-	"github.com/urfave/cli/v2"
+	"github.com/urfave/cli"
 )
 
 var local bool
 var localFlag = &cli.BoolFlag{
-	Name:        "local",
+	Name:        "local, l",
-	Aliases:     []string{"L"},
+	Usage:       "Use local server",
-	Value:       false,
-	Usage:       "Set up the local server",
 	Destination: &local,
 }
 
-var serverAddCommand = &cli.Command{
+func cleanUp(domainName string) {
-	Name:  "add",
+	if domainName != "default" {
-	Usage: "Add a new server",
+		logrus.Infof("cleaning up context for %s", domainName)
-	Description: `
+		if err := client.DeleteContext(domainName); err != nil {
-This command adds a new server that abra will communicate with, to deploy apps.
-
-If "--local" is passed, then Abra assumes that the current local server is
-intended as the target server.
-
-Otherwise, you may specify a remote server. The <domain> argument must be a
-publicy accessible domain name which points to your server. You should have SSH
-access to this server, Abra will assume port 22 and will use your current
-system username to make an initial connection. You can use the <user> and
-<port> arguments to adjust this.
-
-For example:
-
-    abra server add varia.zone glodemodem 12345
-
-Abra will construct the following SSH connection string then:
-
-    ssh://globemodem@varia.zone:12345
-
-All communication between Abra and the server will use this SSH connection.
-`,
-	Aliases: []string{"a"},
-	Flags: []cli.Flag{
-		localFlag,
-	},
-	ArgsUsage: "<domain> [<user>] [<port>]",
-	Action: func(c *cli.Context) error {
-		if c.Args().Len() == 1 && !local {
-			err := errors.New("missing arguments <domain> or '--local'")
-			internal.ShowSubcommandHelpAndError(c, err)
-		}
-
-		if c.Args().Get(1) != "" && local {
-			err := errors.New("cannot use '<domain>' and '--local' together")
-			internal.ShowSubcommandHelpAndError(c, err)
-		}
-
-		domainName := "default"
-
-		if local {
-			if err := server.CreateServerDir(domainName); err != nil {
 			logrus.Fatal(err)
 		}
-			logrus.Info("local server has been added")
-			return nil
 	}
 
-		domainName = internal.ValidateDomain(c)
+	logrus.Infof("attempting to clean up server directory for %s", domainName)
 
-		var username string
+	serverDir := filepath.Join(config.SERVERS_DIR, domainName)
-		var port string
+	files, err := config.GetAllFilesInDirectory(serverDir)
-
-		username = c.Args().Get(1)
-		if username == "" {
-			systemUser, err := user.Current()
 	if err != nil {
+		logrus.Fatalf("unable to list files in %s: %s", serverDir, err)
+	}
+
+	if len(files) > 0 {
+		logrus.Warnf("aborting clean up of %s because it is not empty", serverDir)
+		return
+	}
+
+	if err := os.RemoveAll(serverDir); err != nil {
 		logrus.Fatal(err)
 	}
-			username = systemUser.Username
 }
 
-		port = c.Args().Get(2)
+// newContext creates a new internal Docker context for a server. This is how
-		if port == "" {
+// Docker manages SSH connection details. These are stored to disk in
-			port = "22"
+// ~/.docker. Abra can manage this completely for the user, so it's an
-		}
+// implementation detail.
-
+func newContext(c *cli.Context, domainName, username, port string) error {
-		store := client.NewDefaultDockerContextStore()
+	store := contextPkg.NewDefaultDockerContextStore()
 	contexts, err := store.Store.List()
 	if err != nil {
-			logrus.Fatal(err)
+		return err
 	}
 
 	for _, context := range contexts {
 		if context.Name == domainName {
-				logrus.Fatalf("server at '%s' already exists?", domainName)
+			logrus.Debugf("context for %s already exists", domainName)
+			return nil
 		}
 	}
 
-		logrus.Debugf("creating context with domain '%s', username '%s' and port '%s'", domainName, username, port)
+	logrus.Debugf("creating context with domain %s, username %s and port %s", domainName, username, port)
 
 	if err := client.CreateContext(domainName, username, port); err != nil {
+		return err
+	}
+
+	return nil
+}
+
+// createServerDir creates the ~/.abra/servers/... directory for a new server.
+func createServerDir(domainName string) error {
+	if err := server.CreateServerDir(domainName); err != nil {
+		if !os.IsExist(err) {
+			return err
+		}
+		logrus.Debugf("server dir for %s already created", domainName)
+	}
+
+	return nil
+}
+
+var serverAddCommand = cli.Command{
+	Name:    "add",
+	Aliases: []string{"a"},
+	Usage:   "Add a server to your configuration",
+	Description: `
+Add a new server to your configuration so that it can be managed by Abra.
+
+Abra uses the SSH command-line to discover connection details for your server.
+It is advised to configure an entry per-host in your ~/.ssh/config for each
+server. For example:
+
+Host example.com
+  Hostname example.com
+  User exampleUser
+  Port 12345
+  IdentityFile ~/.ssh/example@somewhere
+
+Abra can then load SSH connection details from this configuratiion with:
+
+    abra server add example.com
+
+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.
+`,
+	Flags: []cli.Flag{
+		internal.DebugFlag,
+		internal.NoInputFlag,
+		localFlag,
+	},
+	Before:    internal.SubCommandBefore,
+	ArgsUsage: "<domain>",
+	Action: func(c *cli.Context) error {
+		if len(c.Args()) > 0 && local || !internal.ValidateSubCmdFlags(c) {
+			err := errors.New("cannot use <domain> and --local together")
+			internal.ShowSubcommandHelpAndError(c, err)
+		}
+
+		var domainName string
+		if local {
+			domainName = "default"
+		} else {
+			domainName = internal.ValidateDomain(c)
+		}
+
+		if local {
+			if err := createServerDir(domainName); err != nil {
 				logrus.Fatal(err)
 			}
 
-		ctx := context.Background()
+			logrus.Infof("attempting to create client for %s", domainName)
-		cl, err := client.New(domainName)
+			if _, err := client.New(domainName); err != nil {
+				cleanUp(domainName)
+				logrus.Fatal(err)
+			}
+
+			logrus.Info("local server added")
+
+			return nil
+		}
+
+		if _, err := dns.EnsureIPv4(domainName); err != nil {
+			logrus.Fatal(err)
+		}
+
+		if err := createServerDir(domainName); err != nil {
+			logrus.Fatal(err)
+		}
+
+		hostConfig, err := sshPkg.GetHostConfig(domainName)
 		if err != nil {
 			logrus.Fatal(err)
 		}
 
-		if _, err := cl.Info(ctx); err != nil {
+		if err := newContext(c, domainName, hostConfig.User, hostConfig.Port); err != nil {
-			if strings.Contains(err.Error(), "command not found") {
-				logrus.Fatalf("docker is not installed on '%s'?", domainName)
-			} else {
-				logrus.Fatalf("unable to make a connection to '%s'?", domainName)
-			}
-			logrus.Debug(err)
-		}
-
-		logrus.Debugf("remote connection to '%s' is definitely up", domainName)
-
-		if err := server.CreateServerDir(domainName); err != nil {
 			logrus.Fatal(err)
 		}
 
-		logrus.Infof("server at '%s' has been added", domainName)
+		logrus.Infof("attempting to create client for %s", domainName)
+		if _, err := client.New(domainName); err != nil {
+			cleanUp(domainName)
+			logrus.Debugf("failed to construct client for %s, saw %s", domainName, err.Error())
+			logrus.Fatal(sshPkg.Fatal(domainName, err))
+		}
+
+		logrus.Infof("%s added", domainName)
 
 		return nil
 	},

cli/server/init.go

@@ -1,81 +0,0 @@
-package server
-
-import (
-	"context"
-	"fmt"
-	"net"
-	"time"
-
-	"coopcloud.tech/abra/cli/internal"
-	"coopcloud.tech/abra/pkg/client"
-	"github.com/docker/docker/api/types"
-	"github.com/docker/docker/api/types/swarm"
-	"github.com/sirupsen/logrus"
-	"github.com/urfave/cli/v2"
-)
-
-var serverInitCommand = &cli.Command{
-	Name:      "init",
-	Usage:     "Initialise server for deploying apps",
-	Aliases:   []string{"i"},
-	HideHelp:  true,
-	ArgsUsage: "<domain>",
-	Description: `
-Initialise swarm mode on the target <domain>.
-
-This initialisation explicitly chooses the "single host swarm" mode which uses
-the default IPv4 address as the advertising address. This can be re-configured
-later for more advanced use cases.
-`,
-	Action: func(c *cli.Context) error {
-		domainName := internal.ValidateDomain(c)
-
-		cl, err := client.New(domainName)
-		if err != nil {
-			return err
-		}
-
-		// https://www.privacy-handbuch.de/handbuch_93d.htm
-		freifunkDNS := "5.1.66.255:53"
-
-		resolver := &net.Resolver{
-			PreferGo: false,
-			Dial: func(ctx context.Context, network, address string) (net.Conn, error) {
-				d := net.Dialer{
-					Timeout: time.Millisecond * time.Duration(10000),
-				}
-				// comrade librehosters DNS resolver https://snopyta.org/service/dns/
-				return d.DialContext(ctx, "udp", freifunkDNS)
-			},
-		}
-		logrus.Debugf("created DNS resolver via '%s'", freifunkDNS)
-
-		ctx := context.Background()
-		ips, err := resolver.LookupIPAddr(ctx, domainName)
-		if err != nil {
-			logrus.Fatal(err)
-		}
-
-		if len(ips) == 0 {
-			return fmt.Errorf("unable to retrieve ipv4 address for %s", domainName)
-		}
-		ipv4 := ips[0].IP.To4().String()
-
-		initReq := swarm.InitRequest{
-			ListenAddr:    "0.0.0.0:2377",
-			AdvertiseAddr: ipv4,
-		}
-		if _, err := cl.SwarmInit(ctx, initReq); err != nil {
-			return err
-		}
-		logrus.Debugf("initialised swarm on '%s'", domainName)
-
-		netOpts := types.NetworkCreate{Driver: "overlay", Scope: "swarm"}
-		if _, err := cl.NetworkCreate(ctx, "proxy", netOpts); err != nil {
-			return err
-		}
-		logrus.Debug("swarm overlay network 'proxy' created")
-
-		return nil
-	},
-}

cli/server/list.go

@@ -3,29 +3,43 @@ package server
 import (
 	"strings"
 
-	"coopcloud.tech/abra/cli/formatter"
+	"coopcloud.tech/abra/cli/internal"
-	"coopcloud.tech/abra/pkg/client"
 	"coopcloud.tech/abra/pkg/config"
+	"coopcloud.tech/abra/pkg/context"
+	"coopcloud.tech/abra/pkg/formatter"
+	"github.com/docker/cli/cli/connhelper/ssh"
 	"github.com/sirupsen/logrus"
-	"github.com/urfave/cli/v2"
+	"github.com/urfave/cli"
 )
 
-var serverListCommand = &cli.Command{
+var problemsFilter bool
+
+var problemsFilterFlag = &cli.BoolFlag{
+	Name:        "problems, p",
+	Usage:       "Show only servers with potential connection problems",
+	Destination: &problemsFilter,
+}
+
+var serverListCommand = cli.Command{
 	Name:    "list",
 	Aliases: []string{"ls"},
 	Usage:   "List managed servers",
-	ArgsUsage: " ",
+	Flags: []cli.Flag{
-	HideHelp:  true,
+		problemsFilterFlag,
+		internal.DebugFlag,
+		internal.MachineReadableFlag,
+		internal.OfflineFlag,
+	},
+	Before: internal.SubCommandBefore,
 	Action: func(c *cli.Context) error {
-		dockerContextStore := client.NewDefaultDockerContextStore()
+		dockerContextStore := context.NewDefaultDockerContextStore()
 		contexts, err := dockerContextStore.Store.List()
 		if err != nil {
 			logrus.Fatal(err)
 		}
 
-		tableColumns := []string{"Name", "Connection"}
+		tableColumns := []string{"name", "host", "user", "port"}
 		table := formatter.CreateTable(tableColumns)
-		defer table.Render()
 
 		serverNames, err := config.ReadServerNames()
 		if err != nil {
@@ -35,23 +49,60 @@ var serverListCommand = &cli.Command{
 		for _, serverName := range serverNames {
 			var row []string
 			for _, ctx := range contexts {
-				endpoint, err := client.GetContextEndpoint(ctx)
+				endpoint, err := context.GetContextEndpoint(ctx)
 				if err != nil && strings.Contains(err.Error(), "does not exist") {
 					// No local context found, we can continue safely
 					continue
 				}
+
 				if ctx.Name == serverName {
-					row = []string{serverName, endpoint}
+					sp, err := ssh.ParseURL(endpoint)
+					if err != nil {
+						logrus.Fatal(err)
+					}
+
+					if sp.Host == "" {
+						sp.Host = "unknown"
+					}
+					if sp.User == "" {
+						sp.User = "unknown"
+					}
+					if sp.Port == "" {
+						sp.Port = "unknown"
+					}
+
+					row = []string{serverName, sp.Host, sp.User, sp.Port}
 				}
 			}
+
 			if len(row) == 0 {
 				if serverName == "default" {
-					row = []string{serverName, "local"}
+					row = []string{serverName, "local", "n/a", "n/a"}
 				} else {
-					row = []string{serverName, "unknown"}
+					row = []string{serverName, "unknown", "unknown", "unknown"}
 				}
 			}
+
+			if problemsFilter {
+				for _, val := range row {
+					if val == "unknown" {
 						table.Append(row)
+						break
+					}
+				}
+			} else {
+				table.Append(row)
+			}
+		}
+
+		if internal.MachineReadable {
+			table.JSONRender()
+		} else {
+			if problemsFilter && table.NumLines() == 0 {
+				logrus.Info("all servers wired up correctly 👏")
+			} else {
+				table.Render()
+			}
 		}
 
 		return nil

cli/server/new.go

@@ -1,264 +0,0 @@
-package server
-
-import (
-	"bytes"
-	"context"
-	"encoding/json"
-	"errors"
-	"fmt"
-	"io/ioutil"
-	"net/http"
-	"time"
-
-	"coopcloud.tech/abra/cli/formatter"
-	"coopcloud.tech/abra/cli/internal"
-	"github.com/hetznercloud/hcloud-go/hcloud"
-	"github.com/sirupsen/logrus"
-	"github.com/urfave/cli/v2"
-)
-
-var hetznerCloudType string
-var hetznerCloudImage string
-var hetznerCloudSSHKeys cli.StringSlice
-var hetznerCloudLocation string
-var hetznerCloudAPIToken string
-var serverNewHetznerCloudCommand = &cli.Command{
-	Name:      "hetzner",
-	Usage:     "Create a new Hetzner virtual server",
-	ArgsUsage: "<name>",
-	Description: `
-Create a new Hetzner virtual server.
-
-This command uses the uses the Hetzner Cloud API bindings to send a server
-creation request. You must already have a Hetzner Cloud account and an account
-API token before using this command.
-
-Your token can be loaded from the environment using the HCLOUD_TOKEN
-environment variable or otherwise passing the "--env/-e" flag.
-`,
-	Flags: []cli.Flag{
-		&cli.StringFlag{
-			Name:        "type",
-			Aliases:     []string{"t"},
-			Usage:       "Server type",
-			Destination: &hetznerCloudType,
-			Value:       "cx11",
-		},
-		&cli.StringFlag{
-			Name:        "image",
-			Aliases:     []string{"i"},
-			Usage:       "Image type",
-			Value:       "debian-10",
-			Destination: &hetznerCloudImage,
-		},
-		&cli.StringSliceFlag{
-			Name:        "ssh-keys",
-			Aliases:     []string{"s"},
-			Usage:       "SSH keys",
-			Destination: &hetznerCloudSSHKeys,
-		},
-		&cli.StringFlag{
-			Name:        "location",
-			Aliases:     []string{"l"},
-			Usage:       "Server location",
-			Value:       "hel1",
-			Destination: &hetznerCloudLocation,
-		},
-		&cli.StringFlag{
-			Name:        "token",
-			Aliases:     []string{"T"},
-			Usage:       "Hetzner Cloud API token",
-			EnvVars:     []string{"HCLOUD_TOKEN"},
-			Destination: &hetznerCloudAPIToken,
-		},
-	},
-	Action: func(c *cli.Context) error {
-		name := c.Args().First()
-		if name == "" {
-			internal.ShowSubcommandHelpAndError(c, errors.New("no name provided"))
-		}
-
-		if hetznerCloudAPIToken == "" {
-			logrus.Fatal("Hetzner Cloud API token is missing")
-		}
-
-		ctx := context.Background()
-		client := hcloud.NewClient(hcloud.WithToken(hetznerCloudAPIToken))
-
-		logrus.Debugf("successfully created hetzner cloud API client")
-
-		var sshKeys []*hcloud.SSHKey
-		for _, sshKey := range c.StringSlice("ssh-keys") {
-			sshKey, _, err := client.SSHKey.GetByName(ctx, sshKey)
-			if err != nil {
-				logrus.Fatal(err)
-			}
-			sshKeys = append(sshKeys, sshKey)
-		}
-
-		serverOpts := hcloud.ServerCreateOpts{
-			Name:       name,
-			ServerType: &hcloud.ServerType{Name: hetznerCloudType},
-			Image:      &hcloud.Image{Name: hetznerCloudImage},
-			SSHKeys:    sshKeys,
-			Location:   &hcloud.Location{Name: hetznerCloudLocation},
-		}
-		res, _, err := client.Server.Create(ctx, serverOpts)
-		if err != nil {
-			logrus.Fatal(err)
-		}
-
-		logrus.Debugf("new server '%s' created", name)
-
-		tableColumns := []string{"Name", "IPv4", "Root Password"}
-		table := formatter.CreateTable(tableColumns)
-
-		if len(sshKeys) > 0 {
-			table.Append([]string{name, res.Server.PublicNet.IPv4.IP.String(), "N/A (using SSH keys)"})
-		} else {
-			table.Append([]string{name, res.Server.PublicNet.IPv4.IP.String(), res.RootPassword})
-		}
-
-		table.Render()
-
-		return nil
-	},
-}
-
-var capsulInstance string
-var capsulType string
-var capsulImage string
-var capsulSSHKey string
-var capsulAPIToken string
-var serverNewCapsulCommand = &cli.Command{
-	Name:      "capsul",
-	Usage:     "Create a new Capsul virtual server",
-	ArgsUsage: "<name>",
-	Description: `
-Create a new Capsul virtual server.
-
-This command uses the uses the Capsul API bindings of your chosen instance to
-send a server creation request. You must already have an account on your chosen
-Capsul instance before using this command.
-
-Your token can be loaded from the environment using the CAPSUL_TOKEN
-environment variable or otherwise passing the "--env/-e" flag.
-`,
-	Flags: []cli.Flag{
-		&cli.StringFlag{
-			Name:        "instance",
-			Aliases:     []string{"I"},
-			Usage:       "Capsul instance",
-			Destination: &capsulInstance,
-			Value:       "yolo.servers.coop",
-		},
-		&cli.StringFlag{
-			Name:        "type",
-			Aliases:     []string{"t"},
-			Usage:       "Server type",
-			Value:       "f1-xs",
-			Destination: &capsulType,
-		},
-		&cli.StringFlag{
-			Name:        "image",
-			Aliases:     []string{"i"},
-			Usage:       "Image type",
-			Value:       "debian10",
-			Destination: &capsulImage,
-		},
-		&cli.StringFlag{
-			Name:        "ssh-key",
-			Aliases:     []string{"s"},
-			Usage:       "SSH key",
-			Value:       "",
-			Destination: &capsulSSHKey,
-		},
-		&cli.StringFlag{
-			Name:        "token",
-			Aliases:     []string{"T"},
-			Usage:       "Capsul instance API token",
-			EnvVars:     []string{"CAPSUL_TOKEN"},
-			Destination: &capsulAPIToken,
-		},
-	},
-	Action: func(c *cli.Context) error {
-		name := c.Args().First()
-		if name == "" {
-			internal.ShowSubcommandHelpAndError(c, errors.New("no name provided"))
-		}
-
-		if capsulAPIToken == "" {
-			logrus.Fatal("Capsul API token is missing")
-		}
-
-		// yep, the response time is quite slow, something to fix on the Capsul side
-		client := &http.Client{Timeout: 20 * time.Second}
-
-		capsulCreateURL := fmt.Sprintf("https://%s/api/capsul/create", capsulInstance)
-		logrus.Debugf("using '%s' as capsul create url", capsulCreateURL)
-		values := map[string]string{
-			"name":      name,
-			"size":      capsulType,
-			"os":        capsulImage,
-			"ssh_key_0": capsulSSHKey,
-		}
-
-		payload, err := json.Marshal(values)
-		if err != nil {
-			logrus.Fatal(err)
-		}
-
-		req, err := http.NewRequest("POST", capsulCreateURL, bytes.NewBuffer(payload))
-		if err != nil {
-			logrus.Fatal(err)
-		}
-
-		req.Header = http.Header{
-			"Content-Type":  []string{"application/json"},
-			"Authorization": []string{capsulAPIToken},
-		}
-
-		res, err := client.Do(req)
-		if err != nil {
-			logrus.Fatal(err)
-		}
-		defer res.Body.Close()
-
-		if res.StatusCode != http.StatusOK {
-			body, err := ioutil.ReadAll(res.Body)
-			if err != nil {
-				panic(err)
-			}
-			logrus.Fatal(string(body))
-		}
-
-		type capsulCreateResponse struct{ ID string }
-		var resp capsulCreateResponse
-		if err := json.NewDecoder(res.Body).Decode(&resp); err != nil {
-			logrus.Fatal(err)
-		}
-		logrus.Debugf("capsul created with ID: '%s'", resp.ID)
-
-		tableColumns := []string{"Name", "ID"}
-		table := formatter.CreateTable(tableColumns)
-		table.Append([]string{name, resp.ID})
-		table.Render()
-
-		return nil
-	},
-}
-
-var serverNewCommand = &cli.Command{
-	Name:    "new",
-	Aliases: []string{"n"},
-	Usage:   "Create a new server using a 3rd party provider",
-	Description: `
-Use a provider plugin to create a new server which can then be used to house a
-new Co-op Cloud installation.
-`,
-	ArgsUsage: "<provider>",
-	Subcommands: []*cli.Command{
-		serverNewHetznerCloudCommand,
-		serverNewCapsulCommand,
-	},
-}

cli/server/prune.go

@@ -0,0 +1,103 @@
+package server
+
+import (
+	"context"
+
+	"coopcloud.tech/abra/cli/internal"
+	"coopcloud.tech/abra/pkg/autocomplete"
+	"coopcloud.tech/abra/pkg/client"
+	"coopcloud.tech/abra/pkg/formatter"
+	"github.com/docker/docker/api/types/filters"
+	"github.com/sirupsen/logrus"
+	"github.com/urfave/cli"
+)
+
+var allFilter bool
+
+var allFilterFlag = &cli.BoolFlag{
+	Name:        "all, a",
+	Usage:       "Remove all unused images not just dangling ones",
+	Destination: &allFilter,
+}
+
+var volumesFilter bool
+
+var volumesFilterFlag = &cli.BoolFlag{
+	Name:        "volumes, v",
+	Usage:       "Prune volumes. This will remove app data, Be Careful!",
+	Destination: &volumesFilter,
+}
+
+var serverPruneCommand = cli.Command{
+	Name:    "prune",
+	Aliases: []string{"p"},
+	Usage:   "Prune a managed server; Runs a docker system prune",
+	Description: `
+Prunes unused containers, networks, and dangling images.
+
+If passing "-v/--volumes" then volumes not connected to a deployed app will
+also be removed. This can result in unwanted data loss if not used carefully.
+	`,
+	ArgsUsage: "[<server>]",
+	Flags: []cli.Flag{
+		allFilterFlag,
+		volumesFilterFlag,
+		internal.DebugFlag,
+		internal.OfflineFlag,
+		internal.NoInputFlag,
+	},
+	Before:       internal.SubCommandBefore,
+	BashComplete: autocomplete.ServerNameComplete,
+	Action: func(c *cli.Context) error {
+		serverName := internal.ValidateServer(c)
+
+		cl, err := client.New(serverName)
+		if err != nil {
+			logrus.Fatal(err)
+		}
+
+		var args filters.Args
+
+		ctx := context.Background()
+		cr, err := cl.ContainersPrune(ctx, args)
+		if err != nil {
+			logrus.Fatal(err)
+		}
+
+		cntSpaceReclaimed := formatter.ByteCountSI(cr.SpaceReclaimed)
+		logrus.Infof("containers pruned: %d; space reclaimed: %s", len(cr.ContainersDeleted), cntSpaceReclaimed)
+
+		nr, err := cl.NetworksPrune(ctx, args)
+		if err != nil {
+			logrus.Fatal(err)
+		}
+
+		logrus.Infof("networks pruned: %d", len(nr.NetworksDeleted))
+
+		pruneFilters := filters.NewArgs()
+		if allFilter {
+			logrus.Debugf("removing all images, not only dangling ones")
+			pruneFilters.Add("dangling", "false")
+		}
+
+		ir, err := cl.ImagesPrune(ctx, pruneFilters)
+		if err != nil {
+			logrus.Fatal(err)
+		}
+
+		imgSpaceReclaimed := formatter.ByteCountSI(ir.SpaceReclaimed)
+		logrus.Infof("images pruned: %d; space reclaimed: %s", len(ir.ImagesDeleted), imgSpaceReclaimed)
+
+		if volumesFilter {
+			vr, err := cl.VolumesPrune(ctx, args)
+			if err != nil {
+				logrus.Fatal(err)
+			}
+
+			volSpaceReclaimed := formatter.ByteCountSI(vr.SpaceReclaimed)
+			logrus.Infof("volumes pruned: %d; space reclaimed: %s", len(vr.VolumesDeleted), volSpaceReclaimed)
+		}
+
+		return nil
+	},
+}

cli/server/remove.go

@@ -1,29 +1,47 @@
 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"
 	"github.com/sirupsen/logrus"
-	"github.com/urfave/cli/v2"
+	"github.com/urfave/cli"
 )
 
-var serverRemoveCommand = &cli.Command{
+var serverRemoveCommand = cli.Command{
 	Name:      "remove",
 	Aliases:   []string{"rm"},
-	Usage:   "Remove a server",
+	ArgsUsage: "<server>",
-	Description: `
+	Usage:     "Remove a managed server",
-This does not destroy the actual server. It simply removes it from Abra
+	Description: `Remove a managed server.
-internal bookkeeping so that it is not managed any more.
-`,
-	HideHelp: true,
-	Action: func(c *cli.Context) error {
-		domainName := internal.ValidateDomain(c)
 
-		if err := client.DeleteContext(domainName); err != nil {
+Abra will remove the internal bookkeeping (~/.abra/servers/...) and underlying
+client connection context. This server will then be lost in time, like tears in
+rain.
+`,
+	Flags: []cli.Flag{
+		internal.DebugFlag,
+		internal.NoInputFlag,
+		internal.OfflineFlag,
+	},
+	Before:       internal.SubCommandBefore,
+	BashComplete: autocomplete.ServerNameComplete,
+	Action: func(c *cli.Context) error {
+		serverName := internal.ValidateServer(c)
+
+		if err := client.DeleteContext(serverName); err != nil {
 			logrus.Fatal(err)
 		}
 
-		logrus.Infof("server at '%s' has been forgotten", domainName)
+		if err := os.RemoveAll(filepath.Join(config.SERVERS_DIR, serverName)); err != nil {
+			logrus.Fatal(err)
+		}
+
+		logrus.Infof("server at %s has been lost in time, like tears in rain", serverName)
 
 		return nil
 	},

cli/server/server.go

@@ -1,26 +1,18 @@
 package server
 
 import (
-	"github.com/urfave/cli/v2"
+	"github.com/urfave/cli"
 )
 
 // ServerCommand defines the `abra server` command and its subcommands
-var ServerCommand = &cli.Command{
+var ServerCommand = cli.Command{
 	Name:    "server",
 	Aliases: []string{"s"},
 	Usage:   "Manage servers",
-	Description: `
+	Subcommands: []cli.Command{
-Manage the lifecycle of a server.
-
-These commands support creating new servers using 3rd party integrations,
-initialising existing servers to support Co-op Cloud deployments and managing
-the connections to those servers.
-`,
-	Subcommands: []*cli.Command{
-		serverNewCommand,
-		serverInitCommand,
 		serverAddCommand,
 		serverListCommand,
 		serverRemoveCommand,
+		serverPruneCommand,
 	},
 }

cli/updater/updater.go

@@ -0,0 +1,498 @@
+package updater
+
+import (
+	"context"
+	"fmt"
+	"os"
+	"strconv"
+	"strings"
+
+	"coopcloud.tech/abra/cli/internal"
+	"coopcloud.tech/abra/pkg/client"
+	"coopcloud.tech/abra/pkg/config"
+	"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"
+	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/sirupsen/logrus"
+	"github.com/urfave/cli"
+)
+
+const SERVER = "localhost"
+
+var majorUpdate bool
+var majorFlag = &cli.BoolFlag{
+	Name:        "major, m",
+	Usage:       "Also check for major updates",
+	Destination: &majorUpdate,
+}
+
+var updateAll bool
+var allFlag = &cli.BoolFlag{
+	Name:        "all, a",
+	Usage:       "Update all deployed apps",
+	Destination: &updateAll,
+}
+
+// Notify checks for available upgrades
+var Notify = cli.Command{
+	Name:    "notify",
+	Aliases: []string{"n"},
+	Usage:   "Check for available upgrades",
+	Flags: []cli.Flag{
+		internal.DebugFlag,
+		majorFlag,
+		internal.OfflineFlag,
+	},
+	Before: internal.SubCommandBefore,
+	Description: `
+It reads the deployed app versions and looks for new versions in the recipe
+catalogue. If a new patch/minor version is available, a notification is
+printed. To include major versions use the --major flag.
+`,
+	Action: func(c *cli.Context) error {
+		cl, err := client.New("default")
+		if err != nil {
+			logrus.Fatal(err)
+		}
+
+		stacks, err := stack.GetStacks(cl)
+		if err != nil {
+			logrus.Fatal(err)
+		}
+
+		for _, stackInfo := range stacks {
+			stackName := stackInfo.Name
+			recipeName, err := getLabel(cl, stackName, "recipe")
+			if err != nil {
+				logrus.Fatal(err)
+			}
+
+			if recipeName != "" {
+				_, err = getLatestUpgrade(cl, stackName, recipeName)
+				if err != nil {
+					logrus.Fatal(err)
+				}
+			}
+		}
+
+		return nil
+	},
+}
+
+// UpgradeApp upgrades apps.
+var UpgradeApp = cli.Command{
+	Name:      "upgrade",
+	Aliases:   []string{"u"},
+	Usage:     "Upgrade apps",
+	ArgsUsage: "<stack-name> <recipe>",
+	Flags: []cli.Flag{
+		internal.DebugFlag,
+		internal.ChaosFlag,
+		majorFlag,
+		allFlag,
+		internal.OfflineFlag,
+	},
+	Before: internal.SubCommandBefore,
+	Description: `
+Upgrade an app by specifying its stack name and recipe. By passing "--all"
+instead, every deployed app is upgraded. For each apps with enabled auto
+updates 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" flag. Don't do that, it will probably
+break things. Only apps that are not deployed with "--chaos" are upgraded, to
+update chaos deployments use the "--chaos" flag. Use it with care.
+`,
+	Action: func(c *cli.Context) error {
+		cl, err := client.New("default")
+		if err != nil {
+			logrus.Fatal(err)
+		}
+
+		if !updateAll {
+			stackName := c.Args().Get(0)
+			recipeName := c.Args().Get(1)
+			err = tryUpgrade(cl, stackName, recipeName)
+			if err != nil {
+				logrus.Fatal(err)
+			}
+
+			return nil
+		}
+
+		stacks, err := stack.GetStacks(cl)
+		if err != nil {
+			logrus.Fatal(err)
+		}
+
+		for _, stackInfo := range stacks {
+			stackName := stackInfo.Name
+			recipeName, err := getLabel(cl, stackName, "recipe")
+			if err != nil {
+				logrus.Fatal(err)
+			}
+
+			err = tryUpgrade(cl, stackName, recipeName)
+			if err != nil {
+				logrus.Fatal(err)
+			}
+		}
+
+		return nil
+	},
+}
+
+// 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
+		}
+	}
+
+	logrus.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
+	}
+
+	logrus.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) (config.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 {
+				logrus.Debugf("can't separate key from value: %s (this variable is probably unset)", envString)
+				continue
+			}
+			k := splitString[0]
+			v := splitString[1]
+			logrus.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 {
+		logrus.Debugf("no available upgrades for %s", stackName)
+		return "", nil
+	}
+
+	var chosenUpgrade string
+	if len(availableUpgrades) > 0 {
+		chosenUpgrade = availableUpgrades[len(availableUpgrades)-1]
+		logrus.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) {
+	logrus.Debugf("Retrieve deployed version whether %s is already deployed", stackName)
+
+	isDeployed, deployedVersion, err := stack.IsDeployed(context.Background(), cl, stackName)
+	if err != nil {
+		return "", err
+	}
+
+	if !isDeployed {
+		return "", fmt.Errorf("%s is not deployed?", stackName)
+	}
+
+	if deployedVersion == "unknown" {
+		return "", fmt.Errorf("failed to determine deployed version of %s", stackName)
+	}
+
+	return deployedVersion, 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 {
+		logrus.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 || majorUpdate) {
+			availableUpgrades = append(availableUpgrades, version)
+		}
+	}
+
+	logrus.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(recipeName, version string) error {
+	if err := recipe.EnsureExists(recipeName); err != nil {
+		return err
+	}
+
+	if err := recipe.EnsureUpToDate(recipeName); err != nil {
+		return err
+	}
+
+	if err := recipe.EnsureVersion(recipeName, version); err != nil {
+		return err
+	}
+
+	if r, err := recipe.Get(recipeName, internal.Offline); err != nil {
+		return err
+	} else if err := lint.LintForErrors(r); err != nil {
+		return err
+	}
+
+	return nil
+}
+
+// mergeAbraShEnv merges abra.sh env vars into the app env vars.
+func mergeAbraShEnv(recipeName string, env config.AppEnv) error {
+	abraShPath := fmt.Sprintf("%s/%s/%s", config.RECIPES_DIR, recipeName, "abra.sh")
+	abraShEnv, err := config.ReadAbraShEnvVars(abraShPath)
+	if err != nil {
+		return err
+	}
+
+	for k, v := range abraShEnv {
+		logrus.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(recipeName string, stackName string, env config.AppEnv) (*composetypes.Config, stack.Deploy, error) {
+	env["STACK_NAME"] = stackName
+
+	deployOpts := stack.Deploy{
+		Namespace:    stackName,
+		Prune:        false,
+		ResolveImage: stack.ResolveImageAlways,
+	}
+
+	composeFiles, err := config.GetComposeFiles(recipeName, env)
+	if err != nil {
+		return nil, deployOpts, err
+	}
+
+	deployOpts.Composefiles = composeFiles
+	compose, err := config.GetAppComposeConfig(stackName, deployOpts, env)
+	if err != nil {
+		return nil, deployOpts, err
+	}
+
+	config.ExposeAllEnv(stackName, compose, env)
+
+	// after the upgrade the deployment won't be in chaos state anymore
+	config.SetChaosLabel(compose, stackName, false)
+	config.SetRecipeLabel(compose, stackName, recipeName)
+	config.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 == "" {
+		logrus.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 {
+		logrus.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 {
+		logrus.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 == "" {
+		logrus.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 := config.App{
+		Name:   stackName,
+		Recipe: recipeName,
+		Server: SERVER,
+		Env:    env,
+	}
+
+	if err = processRecipeRepoVersion(recipeName, upgradeVersion); err != nil {
+		return err
+	}
+
+	if err = mergeAbraShEnv(recipeName, app.Env); err != nil {
+		return err
+	}
+
+	compose, deployOpts, err := createDeployConfig(recipeName, stackName, app.Env)
+	if err != nil {
+		return err
+	}
+
+	logrus.Infof("upgrade %s (%s) to version %s", stackName, recipeName, upgradeVersion)
+
+	err = stack.RunDeploy(cl, deployOpts, compose, stackName, true)
+
+	return err
+}
+
+func newAbraApp(version, commit string) *cli.App {
+	app := &cli.App{
+		Name: "kadabra",
+		Usage: `The Co-op Cloud auto-updater
+    ____                           ____ _                 _
+   / ___|___         ___  _ __    / ___| | ___  _   _  __| |
+  | |   / _ \ _____ / _ \| '_ \  | |   | |/ _ \| | | |/ _' |
+  | |__| (_) |_____| (_) | |_) | | |___| | (_) | |_| | (_| |
+   \____\___/       \___/| .__/   \____|_|\___/ \__,_|\__,_|
+                         |_|
+`,
+		Version: fmt.Sprintf("%s-%s", version, commit[:7]),
+		Commands: []cli.Command{
+			Notify,
+			UpgradeApp,
+		},
+	}
+
+	app.Before = func(c *cli.Context) error {
+		logrus.Debugf("kadabra version %s, commit %s", version, commit)
+		return nil
+	}
+
+	return app
+}
+
+// RunApp runs CLI abra app.
+func RunApp(version, commit string) {
+	app := newAbraApp(version, commit)
+
+	if err := app.Run(os.Args); err != nil {
+		logrus.Fatal(err)
+	}
+}

cli/upgrade.go

@@ -1,23 +0,0 @@
-package cli
-
-import (
-	"os/exec"
-
-	"coopcloud.tech/abra/cli/internal"
-	"github.com/sirupsen/logrus"
-	"github.com/urfave/cli/v2"
-)
-
-// UpgradeCommand upgrades abra in-place.
-var UpgradeCommand = &cli.Command{
-	Name:  "upgrade",
-	Usage: "Upgrade abra",
-	Action: func(c *cli.Context) error {
-		cmd := exec.Command("bash", "-c", "curl -s https://install.abra.coopcloud.tech | bash")
-		logrus.Debugf("attempting to run '%s'", cmd)
-		if err := internal.RunCmd(cmd); err != nil {
-			logrus.Fatal(err)
-		}
-		return nil
-	},
-}

cli/version.go

@@ -1,15 +0,0 @@
-package cli
-
-import (
-	"github.com/urfave/cli/v2"
-)
-
-// VersionCommand prints the version of abra.
-var VersionCommand = &cli.Command{
-	Name:  "version",
-	Usage: "Print version",
-	Action: func(c *cli.Context) error {
-		cli.VersionPrinter(c)
-		return nil
-	},
-}

cmd/abra/main.go

@@ -5,14 +5,13 @@ import (
 	"coopcloud.tech/abra/cli"
 )
 
-// Version is the current version of abra.
+// Version is the current version of Abra.
 var Version string
 
-// Commit is the current commit of abra.
+// Commit is the current git commit of Abra.
 var Commit string
 
 func main() {
-	// If not set in the ld-flags
 	if Version == "" {
 		Version = "dev"
 	}

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)
+}

go.mod

@@ -1,99 +1,120 @@
 module coopcloud.tech/abra
 
-go 1.17
+go 1.21
 
 require (
-	coopcloud.tech/tagcmp v0.0.0-20211011140827-4f27c74467eb
+	coopcloud.tech/tagcmp v0.0.0-20211103052201-885b22f77d52
-	github.com/AlecAivazis/survey/v2 v2.3.1
+	git.coopcloud.tech/coop-cloud/godotenv v1.5.2-0.20231130100106-7462d91acefd
-	github.com/Autonomic-Cooperative/godotenv v1.3.1-0.20210731170023-c37c0920d1a4
+	github.com/AlecAivazis/survey/v2 v2.3.7
 	github.com/Gurpartap/logrus-stack v0.0.0-20170710170904-89c00d8a28f4
-	github.com/docker/cli v20.10.8+incompatible
+	github.com/docker/cli v24.0.7+incompatible
-	github.com/docker/distribution v2.7.1+incompatible
+	github.com/docker/distribution v2.8.3+incompatible
-	github.com/docker/docker v20.10.8+incompatible
+	github.com/docker/docker v24.0.7+incompatible
-	github.com/docker/go-units v0.4.0
+	github.com/docker/go-units v0.5.0
-	github.com/go-git/go-git/v5 v5.4.2
+	github.com/go-git/go-git/v5 v5.10.0
-	github.com/hetznercloud/hcloud-go v1.32.0
+	github.com/moby/sys/signal v0.7.0
-	github.com/moby/sys/signal v0.5.0
+	github.com/moby/term v0.5.0
-	github.com/moby/term v0.0.0-20210619224110-3f7ff695adc6
 	github.com/olekukonko/tablewriter v0.0.5
 	github.com/pkg/errors v0.9.1
-	github.com/schollz/progressbar/v3 v3.8.3
+	github.com/schollz/progressbar/v3 v3.14.1
-	github.com/schultz-is/passgen v1.0.1
+	github.com/sirupsen/logrus v1.9.3
-	github.com/sirupsen/logrus v1.8.1
+	gotest.tools/v3 v3.5.1
-	github.com/urfave/cli/v2 v2.3.0
-	gotest.tools/v3 v3.0.3
 )
 
 require (
+	dario.cat/mergo v1.0.0 // indirect
 	github.com/Azure/go-ansiterm v0.0.0-20210617225240-d185dfc1b5a1 // indirect
-	github.com/Microsoft/go-winio v0.4.17 // indirect
+	github.com/BurntSushi/toml v1.0.0 // indirect
-	github.com/Microsoft/hcsshim v0.8.21 // indirect
+	github.com/Microsoft/go-winio v0.6.1 // indirect
-	github.com/ProtonMail/go-crypto v0.0.0-20210428141323-04723f9f07d7 // indirect
+	github.com/Microsoft/hcsshim v0.9.2 // indirect
-	github.com/acomagu/bufpipe v1.0.3 // indirect
+	github.com/ProtonMail/go-crypto v0.0.0-20230828082145-3c4c8a2d2371 // indirect
+	github.com/acomagu/bufpipe v1.0.4 // indirect
 	github.com/beorn7/perks v1.0.1 // indirect
-	github.com/cespare/xxhash/v2 v2.1.1 // indirect
+	github.com/cespare/xxhash/v2 v2.2.0 // indirect
-	github.com/containerd/cgroups v1.0.1 // indirect
+	github.com/cloudflare/circl v1.3.3 // indirect
-	github.com/containerd/containerd v1.5.5 // indirect
+	github.com/cpuguy83/go-md2man/v2 v2.0.1 // indirect
-	github.com/cpuguy83/go-md2man/v2 v2.0.0 // indirect
+	github.com/cyphar/filepath-securejoin v0.2.4 // indirect
-	github.com/docker/docker-credential-helpers v0.6.4 // indirect
+	github.com/davecgh/go-spew v1.1.1 // indirect
+	github.com/distribution/reference v0.5.0 // indirect
 	github.com/docker/go v1.5.1-1.0.20160303222718-d30aec9fd63c // indirect
 	github.com/docker/go-connections v0.4.0 // indirect
 	github.com/docker/go-metrics v0.0.1 // indirect
-	github.com/emirpasic/gods v1.12.0 // indirect
+	github.com/docker/libtrust v0.0.0-20160708172513-aabc10ec26b7 // indirect
-	github.com/facebookgo/stack v0.0.0-20160209184415-751773369052 // indirect
+	github.com/emirpasic/gods v1.18.1 // indirect
-	github.com/fvbommel/sortorder v1.0.2 // indirect
+	github.com/ghodss/yaml v1.0.0 // indirect
-	github.com/go-git/gcfg v1.5.0 // indirect
+	github.com/go-git/gcfg v1.5.1-0.20230307220236-3a3c6141e376 // indirect
-	github.com/go-git/go-billy/v5 v5.3.1 // indirect
+	github.com/go-git/go-billy/v5 v5.5.0 // indirect
 	github.com/gogo/protobuf v1.3.2 // indirect
-	github.com/golang/groupcache v0.0.0-20200121045136-8c9f03a8e57e // indirect
+	github.com/golang/groupcache v0.0.0-20210331224755-41bb18bfe9da // indirect
-	github.com/golang/protobuf v1.5.0 // indirect
+	github.com/golang/protobuf v1.5.3 // indirect
-	github.com/google/go-cmp v0.5.5 // indirect
+	github.com/google/go-cmp v0.5.9 // indirect
-	github.com/google/shlex v0.0.0-20191202100458-e7afc7fbc510 // indirect
+	github.com/hashicorp/go-cleanhttp v0.5.2 // indirect
-	github.com/gorilla/mux v1.8.0 // indirect
 	github.com/imdario/mergo v0.3.12 // indirect
 	github.com/inconshreveable/mousetrap v1.0.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 v0.0.0-20201106050909-4977a11b4351 // indirect
+	github.com/kevinburke/ssh_config v1.2.0 // indirect
-	github.com/mattn/go-colorable v0.1.2 // indirect
+	github.com/klauspost/compress v1.14.2 // indirect
-	github.com/mattn/go-isatty v0.0.14 // indirect
+	github.com/mattn/go-colorable v0.1.12 // indirect
-	github.com/mattn/go-runewidth v0.0.13 // indirect
+	github.com/mattn/go-isatty v0.0.20 // indirect
-	github.com/matttproud/golang_protobuf_extensions v1.0.2-0.20181231171920-c182affec369 // indirect
+	github.com/mattn/go-runewidth v0.0.14 // indirect
+	github.com/matttproud/golang_protobuf_extensions v1.0.4 // indirect
 	github.com/mgutz/ansi v0.0.0-20170206155736-9520e82c474b // indirect
 	github.com/miekg/pkcs11 v1.0.3 // indirect
 	github.com/mitchellh/colorstring v0.0.0-20190213212951-d06e56a500db // indirect
-	github.com/mitchellh/go-homedir v1.1.0 // indirect
+	github.com/mitchellh/mapstructure v1.4.3 // indirect
-	github.com/mitchellh/mapstructure v1.1.2 // indirect
-	github.com/moby/sys/mount v0.2.0 // indirect
-	github.com/moby/sys/mountinfo v0.4.1 // indirect
 	github.com/morikuni/aec v1.0.0 // indirect
 	github.com/opencontainers/go-digest v1.0.0 // indirect
-	github.com/opencontainers/image-spec v1.0.1 // indirect
+	github.com/opencontainers/runc v1.1.0 // indirect
-	github.com/opencontainers/runc v1.0.2 // indirect
+	github.com/pjbgf/sha1cd v0.3.0 // indirect
-	github.com/prometheus/client_golang v1.11.0 // indirect
+	github.com/pmezard/go-difflib v1.0.0 // indirect
-	github.com/prometheus/client_model v0.2.0 // indirect
+	github.com/prometheus/client_model v0.3.0 // indirect
-	github.com/prometheus/common v0.26.0 // indirect
+	github.com/prometheus/common v0.42.0 // indirect
-	github.com/prometheus/procfs v0.6.0 // indirect
+	github.com/prometheus/procfs v0.10.1 // indirect
-	github.com/rivo/uniseg v0.2.0 // indirect
+	github.com/rivo/uniseg v0.4.4 // indirect
-	github.com/russross/blackfriday/v2 v2.0.1 // indirect
+	github.com/russross/blackfriday/v2 v2.1.0 // indirect
-	github.com/sergi/go-diff v1.1.0 // indirect
+	github.com/skeema/knownhosts v1.2.0 // indirect
-	github.com/shurcooL/sanitized_anchor_name v1.0.0 // indirect
-	github.com/spf13/cobra v1.0.0 // indirect
 	github.com/spf13/pflag v1.0.5 // indirect
-	github.com/theupdateframework/notary v0.7.0 // indirect
+	github.com/xanzy/ssh-agent v0.3.3 // indirect
-	github.com/xanzy/ssh-agent v0.3.0 // indirect
-	github.com/xeipuuv/gojsonpointer v0.0.0-20180127040702-4e3ac2762d5f // indirect
 	github.com/xeipuuv/gojsonreference v0.0.0-20180127040603-bd5ef7bd5415 // indirect
 	github.com/xeipuuv/gojsonschema v1.2.0 // indirect
-	go.opencensus.io v0.22.3 // indirect
+	golang.org/x/crypto v0.14.0 // indirect
-	golang.org/x/crypto v0.0.0-20210817164053-32db794688a5 // indirect
+	golang.org/x/mod v0.12.0 // indirect
-	golang.org/x/net v0.0.0-20210326060303-6b1517762897 // indirect
+	golang.org/x/net v0.17.0 // indirect
-	golang.org/x/sys v0.0.0-20210910150752-751e447fb3d0 // indirect
+	golang.org/x/sync v0.3.0 // indirect
-	golang.org/x/term v0.0.0-20210615171337-6886f2dfbf5b // indirect
+	golang.org/x/term v0.14.0 // indirect
-	golang.org/x/text v0.3.4 // indirect
+	golang.org/x/text v0.13.0 // indirect
-	google.golang.org/genproto v0.0.0-20201110150050-8816d57aaa9a // indirect
+	golang.org/x/time v0.0.0-20200630173020-3af7569d3a1e // indirect
-	google.golang.org/grpc v1.33.2 // indirect
+	golang.org/x/tools v0.13.0 // indirect
-	google.golang.org/protobuf v1.26.0 // indirect
+	google.golang.org/protobuf v1.30.0 // indirect
 	gopkg.in/warnings.v0 v0.1.2 // indirect
 	gopkg.in/yaml.v2 v2.4.0 // indirect
+	gopkg.in/yaml.v3 v3.0.1 // indirect
+)
+
+require (
+	github.com/AdaLogics/go-fuzz-headers v0.0.0-20230106234847-43070de90fa1 // indirect
+	github.com/buger/goterm v1.0.4
+	github.com/containerd/containerd v1.5.9 // indirect
+	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.6.4 // indirect
+	github.com/facebookgo/stack v0.0.0-20160209184415-751773369052 // indirect
+	github.com/fvbommel/sortorder v1.0.2 // indirect
+	github.com/google/shlex v0.0.0-20191202100458-e7afc7fbc510 // indirect
+	github.com/gorilla/mux v1.8.0 // indirect
+	github.com/hashicorp/go-retryablehttp v0.7.5
+	github.com/klauspost/pgzip v1.2.6
+	github.com/moby/patternmatcher v0.5.0 // indirect
+	github.com/moby/sys/sequential v0.5.0 // indirect
+	github.com/opencontainers/image-spec v1.0.3-0.20211202193544-a5463b7f9c84 // indirect
+	github.com/prometheus/client_golang v1.16.0 // indirect
+	github.com/sergi/go-diff v1.2.0 // indirect
+	github.com/spf13/cobra v1.3.0 // indirect
+	github.com/stretchr/testify v1.8.4
+	github.com/theupdateframework/notary v0.7.0 // indirect
+	github.com/urfave/cli v1.22.9
+	github.com/xeipuuv/gojsonpointer v0.0.0-20190809123943-df4f5c81cb3b // indirect
+	golang.org/x/sys v0.14.0
 )

pkg/app/app.go

@@ -1,13 +1,9 @@
 package app
 
 import (
-	"context"
-	"fmt"
 	"strings"
 
-	"coopcloud.tech/abra/pkg/client/stack"
 	"coopcloud.tech/abra/pkg/config"
-	apiclient "github.com/docker/docker/client"
 	"github.com/sirupsen/logrus"
 )
 
@@ -23,7 +19,7 @@ func Get(appName string) (config.App, error) {
 		return config.App{}, err
 	}
 
-	logrus.Debugf("retrieved '%s' for '%s'", app, appName)
+	logrus.Debugf("retrieved %s for %s", app, appName)
 
 	return app, nil
 }
@@ -37,49 +33,10 @@ type deployedServiceSpec struct {
 // VersionSpec represents a deployed app and associated metadata.
 type VersionSpec map[string]deployedServiceSpec
 
-// DeployedVersions lists metadata (e.g. versions) for deployed
+// ParseServiceName parses a $STACK_NAME_$SERVICE_NAME service label.
-func DeployedVersions(ctx context.Context, cl *apiclient.Client, app config.App) (VersionSpec, bool, error) {
-	services, err := stack.GetStackServices(ctx, cl, app.StackName())
-	if err != nil {
-		return VersionSpec{}, false, err
-	}
-
-	appSpec := make(VersionSpec)
-	for _, service := range services {
-		serviceName := ParseServiceName(service.Spec.Name)
-		label := fmt.Sprintf("coop-cloud.%s.%s.version", app.StackName(), serviceName)
-		if deployLabel, ok := service.Spec.Labels[label]; ok {
-			version, _ := ParseVersionLabel(deployLabel)
-			appSpec[serviceName] = deployedServiceSpec{Name: serviceName, Version: version}
-		}
-	}
-
-	deployed := len(services) > 0
-
-	if deployed {
-		logrus.Debugf("detected '%s' as deployed versions of '%s'", appSpec, app.Name)
-	} else {
-		logrus.Debugf("detected '%s' as not deployed", app.Name)
-	}
-
-	return appSpec, len(services) > 0, nil
-}
-
-// ParseVersionLabel parses a $VERSION-$DIGEST app service label.
-func ParseVersionLabel(label string) (string, string) {
-	// versions may look like v4.2-abcd or v4.2-alpine-abcd
-	idx := strings.LastIndex(label, "-")
-	version := label[:idx]
-	digest := label[idx+1:]
-	logrus.Debugf("parsed '%s' as version from '%s'", version, label)
-	logrus.Debugf("parsed '%s' as digest from '%s'", digest, label)
-	return version, digest
-}
-
-// ParseVersionName parses a $STACK_NAME_$SERVICE_NAME service label.
 func ParseServiceName(label string) string {
 	idx := strings.LastIndex(label, "_")
 	serviceName := label[idx+1:]
-	logrus.Debugf("parsed '%s' as service name from '%s'", serviceName, label)
+	logrus.Debugf("parsed %s as service name from %s", serviceName, label)
 	return serviceName
 }

pkg/autocomplete/autocomplete.go

@@ -0,0 +1,88 @@
+package autocomplete
+
+import (
+	"fmt"
+
+	"coopcloud.tech/abra/pkg/config"
+	"coopcloud.tech/abra/pkg/recipe"
+	"github.com/sirupsen/logrus"
+	"github.com/urfave/cli"
+)
+
+// AppNameComplete copletes app names.
+func AppNameComplete(c *cli.Context) {
+	appNames, err := config.GetAppNames()
+	if err != nil {
+		logrus.Warn(err)
+	}
+
+	if c.NArg() > 0 {
+		return
+	}
+
+	for _, a := range appNames {
+		fmt.Println(a)
+	}
+}
+
+func ServiceNameComplete(appName string) {
+	serviceNames, err := config.GetAppServiceNames(appName)
+	if err != nil {
+		return
+	}
+	for _, s := range serviceNames {
+		fmt.Println(s)
+	}
+}
+
+// RecipeNameComplete completes recipe names.
+func RecipeNameComplete(c *cli.Context) {
+	catl, err := recipe.ReadRecipeCatalogue(false)
+	if err != nil {
+		logrus.Warn(err)
+	}
+
+	if c.NArg() > 0 {
+		return
+	}
+
+	for name := range catl {
+		fmt.Println(name)
+	}
+}
+
+// ServerNameComplete completes server names.
+func ServerNameComplete(c *cli.Context) {
+	files, err := config.LoadAppFiles("")
+	if err != nil {
+		logrus.Fatal(err)
+	}
+
+	if c.NArg() > 0 {
+		return
+	}
+
+	for _, appFile := range files {
+		fmt.Println(appFile.Server)
+	}
+}
+
+// SubcommandComplete completes sub-commands.
+func SubcommandComplete(c *cli.Context) {
+	if c.NArg() > 0 {
+		return
+	}
+
+	subcmds := []string{
+		"app",
+		"autocomplete",
+		"catalogue",
+		"recipe",
+		"server",
+		"upgrade",
+	}
+
+	for _, cmd := range subcmds {
+		fmt.Println(cmd)
+	}
+}

pkg/catalogue/catalogue.go

@@ -1,502 +1,88 @@
-// Package catalogue provides ways of interacting with recipe catalogues which
-// are JSON data structures which contain meta information about recipes (e.g.
-// what versions of the Nextcloud recipe are available?).
 package catalogue
 
 import (
-	"encoding/json"
 	"fmt"
-	"io/ioutil"
-	"net/http"
 	"os"
 	"path"
 	"strings"
-	"time"
 
-	"coopcloud.tech/abra/pkg/client"
 	"coopcloud.tech/abra/pkg/config"
-	"coopcloud.tech/abra/pkg/recipe"
+	gitPkg "coopcloud.tech/abra/pkg/git"
-	"coopcloud.tech/abra/pkg/web"
-	"github.com/docker/distribution/reference"
 	"github.com/go-git/go-git/v5"
-	"github.com/go-git/go-git/v5/plumbing"
 	"github.com/sirupsen/logrus"
 )
 
-// RecipeCatalogueURL is the only current recipe catalogue available.
+// EnsureCatalogue ensures that the catalogue is cloned locally & present.
-const RecipeCatalogueURL = "https://apps.coopcloud.tech"
+func EnsureCatalogue() error {
-
+	catalogueDir := path.Join(config.ABRA_DIR, "catalogue")
-// ReposMetadataURL is the recipe repository metadata
+	if _, err := os.Stat(catalogueDir); err != nil && os.IsNotExist(err) {
-const ReposMetadataURL = "https://git.coopcloud.tech/api/v1/orgs/coop-cloud/repos"
+		logrus.Warnf("local recipe catalogue is missing, retrieving now")
-
+		url := fmt.Sprintf("%s/%s.git", config.REPOS_BASE_URL, config.CATALOGUE_JSON_REPO_NAME)
-// image represents a recipe container image.
+		if err := gitPkg.Clone(catalogueDir, url); err != nil {
-type image struct {
-	Image  string `json:"image"`
-	Rating string `json:"rating"`
-	Source string `json:"source"`
-	URL    string `json:"url"`
-}
-
-// features represent what top-level features a recipe supports (e.g. does this
-// recipe support backups?).
-type features struct {
-	Backups     string `json:"backups"`
-	Email       string `json:"email"`
-	Healthcheck string `json:"healthcheck"`
-	Image       image  `json:"image"`
-	Status      int    `json:"status"`
-	Tests       string `json:"tests"`
-}
-
-// tag represents a git tag.
-type tag = string
-
-// service represents a service within a recipe.
-type service = string
-
-// serviceMeta represents meta info associated with a service.
-type serviceMeta struct {
-	Digest string `json:"digest"`
-	Image  string `json:"image"`
-	Tag    string `json:"tag"`
-}
-
-// RecipeVersions are the versions associated with a recipe.
-type RecipeVersions []map[tag]map[service]serviceMeta
-
-// RecipeMeta represents metadata for a recipe in the abra catalogue.
-type RecipeMeta struct {
-	Category      string         `json:"category"`
-	DefaultBranch string         `json:"default_branch"`
-	Description   string         `json:"description"`
-	Features      features       `json:"features"`
-	Icon          string         `json:"icon"`
-	Name          string         `json:"name"`
-	Repository    string         `json:"repository"`
-	Versions      RecipeVersions `json:"versions"`
-	Website       string         `json:"website"`
-}
-
-// LatestVersion returns the latest version of a recipe.
-func (r RecipeMeta) LatestVersion() string {
-	var version string
-
-	// apps.json versions are sorted so the last key is latest
-	latest := r.Versions[len(r.Versions)-1]
-
-	for tag := range latest {
-		version = tag
-	}
-
-	logrus.Debugf("choosing '%s' as latest version of '%s'", version, r.Name)
-
-	return version
-}
-
-// Name represents a recipe name.
-type Name = string
-
-// RecipeCatalogue represents the entire recipe catalogue.
-type RecipeCatalogue map[Name]RecipeMeta
-
-// Flatten converts AppCatalogue to slice
-func (r RecipeCatalogue) Flatten() []RecipeMeta {
-	recipes := make([]RecipeMeta, 0, len(r))
-
-	for name := range r {
-		recipes = append(recipes, r[name])
-	}
-
-	return recipes
-}
-
-// ByRecipeName sorts recipes by name.
-type ByRecipeName []RecipeMeta
-
-func (r ByRecipeName) Len() int      { return len(r) }
-func (r ByRecipeName) Swap(i, j int) { r[i], r[j] = r[j], r[i] }
-func (r ByRecipeName) Less(i, j int) bool {
-	return strings.ToLower(r[i].Name) < strings.ToLower(r[j].Name)
-}
-
-// recipeCatalogueFSIsLatest checks whether the recipe catalogue stored locally
-// is up to date.
-func recipeCatalogueFSIsLatest() (bool, error) {
-	httpClient := &http.Client{Timeout: web.Timeout}
-	res, err := httpClient.Head(RecipeCatalogueURL)
-	if err != nil {
-		return false, err
-	}
-
-	lastModified := res.Header["Last-Modified"][0]
-	parsed, err := time.Parse(time.RFC1123, lastModified)
-	if err != nil {
-		return false, err
-	}
-
-	info, err := os.Stat(config.APPS_JSON)
-	if err != nil {
-		if os.IsNotExist(err) {
-			logrus.Debugf("no recipe catalogue found in file system cache")
-			return false, nil
-		}
-		return false, err
-	}
-
-	localModifiedTime := info.ModTime().Unix()
-	remoteModifiedTime := parsed.Unix()
-
-	if localModifiedTime < remoteModifiedTime {
-		logrus.Debug("file system cached recipe catalogue is out-of-date")
-		return false, nil
-	}
-
-	logrus.Debug("file system cached recipe catalogue is up-to-date")
-
-	return true, nil
-}
-
-// ReadRecipeCatalogue reads the recipe catalogue.
-func ReadRecipeCatalogue() (RecipeCatalogue, error) {
-	recipes := make(RecipeCatalogue)
-
-	recipeFSIsLatest, err := recipeCatalogueFSIsLatest()
-	if err != nil {
-		return nil, err
-	}
-
-	if !recipeFSIsLatest {
-		logrus.Debugf("reading recipe catalogue from web to get latest")
-		if err := readRecipeCatalogueWeb(&recipes); err != nil {
-			return nil, err
-		}
-		return recipes, nil
-	}
-
-	logrus.Debugf("reading recipe catalogue from file system cache to get latest")
-	if err := readRecipeCatalogueFS(&recipes); err != nil {
-		return nil, err
-	}
-
-	return recipes, nil
-}
-
-// readRecipeCatalogueFS reads the catalogue from the file system.
-func readRecipeCatalogueFS(target interface{}) error {
-	recipesJSONFS, err := ioutil.ReadFile(config.APPS_JSON)
-	if err != nil {
 			return err
 		}
 
-	if err := json.Unmarshal(recipesJSONFS, &target); err != nil {
+		logrus.Debugf("cloned catalogue repository to %s", catalogueDir)
-		return err
 	}
 
-	logrus.Debugf("read recipe catalogue from file system cache in '%s'", config.APPS_JSON)
-
 	return nil
 }
 
-// readRecipeCatalogueWeb reads the catalogue from the web.
+// EnsureIsClean makes sure that the catalogue has no unstaged changes.
-func readRecipeCatalogueWeb(target interface{}) error {
+func EnsureIsClean() error {
-	if err := web.ReadJSON(RecipeCatalogueURL, &target); err != nil {
+	isClean, err := gitPkg.IsClean(config.CATALOGUE_DIR)
-		return err
-	}
-
-	recipesJSON, err := json.MarshalIndent(target, "", "    ")
 	if err != nil {
 		return err
 	}
 
-	if err := ioutil.WriteFile(config.APPS_JSON, recipesJSON, 0644); err != nil {
+	if !isClean {
-		return err
+		msg := "%s has locally unstaged changes? please commit/remove your changes before proceeding"
+		return fmt.Errorf(msg, config.CATALOGUE_DIR)
 	}
 
-	logrus.Debugf("read recipe catalogue from web at '%s'", RecipeCatalogueURL)
-
 	return nil
 }
 
-// VersionsOfService lists the version of a service.
+// EnsureUpToDate ensures that the local catalogue is up to date.
-func VersionsOfService(recipe, serviceName string) ([]string, error) {
+func EnsureUpToDate() error {
-	catalogue, err := ReadRecipeCatalogue()
+	repo, err := git.PlainOpen(config.CATALOGUE_DIR)
 	if err != nil {
-		return nil, err
+		return err
 	}
 
-	rec, ok := catalogue[recipe]
+	remotes, err := repo.Remotes()
-	if !ok {
-		return nil, fmt.Errorf("recipe '%s' does not exist?", recipe)
-	}
-
-	versions := []string{}
-	alreadySeen := make(map[string]bool)
-	for _, serviceVersion := range rec.Versions {
-		for tag := range serviceVersion {
-			if _, ok := alreadySeen[tag]; !ok {
-				alreadySeen[tag] = true
-				versions = append(versions, tag)
-			}
-		}
-	}
-
-	logrus.Debugf("detected versions '%s' for '%s'", strings.Join(versions, ", "), recipe)
-
-	return versions, nil
-}
-
-// GetRecipeMeta retrieves the recipe metadata from the recipe catalogue.
-func GetRecipeMeta(recipeName string) (RecipeMeta, error) {
-	catl, err := ReadRecipeCatalogue()
 	if err != nil {
-		return RecipeMeta{}, err
+		return err
 	}
 
-	recipeMeta, ok := catl[recipeName]
+	if len(remotes) == 0 {
-	if !ok {
+		msg := "cannot ensure %s is up-to-date, no git remotes configured"
-		err := fmt.Errorf("recipe '%s' does not exist?", recipeName)
+		logrus.Debugf(msg, config.CATALOGUE_DIR)
-		return RecipeMeta{}, err
+		return nil
-	}
-
-	if err := recipe.EnsureExists(recipeName); err != nil {
-		return RecipeMeta{}, err
-	}
-
-	logrus.Debugf("recipe metadata retrieved for '%s'", recipeName)
-
-	return recipeMeta, nil
-}
-
-// RepoMeta is a single recipe repo metadata.
-type RepoMeta struct {
-	ID                        int `json:"id"`
-	Owner                     Owner
-	Name                      string      `json:"name"`
-	FullName                  string      `json:"full_name"`
-	Description               string      `json:"description"`
-	Empty                     bool        `json:"empty"`
-	Private                   bool        `json:"private"`
-	Fork                      bool        `json:"fork"`
-	Template                  bool        `json:"template"`
-	Parent                    interface{} `json:"parent"`
-	Mirror                    bool        `json:"mirror"`
-	Size                      int         `json:"size"`
-	HTMLURL                   string      `json:"html_url"`
-	SSHURL                    string      `json:"ssh_url"`
-	CloneURL                  string      `json:"clone_url"`
-	OriginalURL               string      `json:"original_url"`
-	Website                   string      `json:"website"`
-	StarsCount                int         `json:"stars_count"`
-	ForksCount                int         `json:"forks_count"`
-	WatchersCount             int         `json:"watchers_count"`
-	OpenIssuesCount           int         `json:"open_issues_count"`
-	OpenPRCount               int         `json:"open_pr_counter"`
-	ReleaseCounter            int         `json:"release_counter"`
-	DefaultBranch             string      `json:"default_branch"`
-	Archived                  bool        `json:"archived"`
-	CreatedAt                 string      `json:"created_at"`
-	UpdatedAt                 string      `json:"updated_at"`
-	Permissions               Permissions
-	HasIssues                 bool `json:"has_issues"`
-	InternalTracker           InternalTracker
-	HasWiki                   bool   `json:"has_wiki"`
-	HasPullRequests           bool   `json:"has_pull_requests"`
-	HasProjects               bool   `json:"has_projects"`
-	IgnoreWhitespaceConflicts bool   `json:"ignore_whitespace_conflicts"`
-	AllowMergeCommits         bool   `json:"allow_merge_commits"`
-	AllowRebase               bool   `json:"allow_rebase"`
-	AllowRebaseExplicit       bool   `json:"allow_rebase_explicit"`
-	AllowSquashMerge          bool   `json:"allow_squash_merge"`
-	AvatarURL                 string `json:"avatar_url"`
-	Internal                  bool   `json:"internal"`
-	MirrorInterval            string `json:"mirror_interval"`
-}
-
-// Owner is the repo organisation owner metadata.
-type Owner struct {
-	ID         int    `json:"id"`
-	Login      string `json:"login"`
-	FullName   string `json:"full_name"`
-	Email      string `json:"email"`
-	AvatarURL  string `json:"avatar_url"`
-	Language   string `json:"language"`
-	IsAdmin    bool   `json:"is_admin"`
-	LastLogin  string `json:"last_login"`
-	Created    string `json:"created"`
-	Restricted bool   `json:"restricted"`
-	Username   string `json:"username"`
-}
-
-// Permissions is perms metadata for a repo.
-type Permissions struct {
-	Admin bool `json:"admin"`
-	Push  bool `json:"push"`
-	Pull  bool `json:"pull"`
-}
-
-// InternalTracker is issue tracker metadata for a repo.
-type InternalTracker struct {
-	EnableTimeTracker                bool `json:"enable_time_tracker"`
-	AllowOnlyContributorsToTrackTime bool `json:"allow_only_contributors_to_track_time"`
-	EnableIssuesDependencies         bool `json:"enable_issue_dependencies"`
-}
-
-// RepoCatalogue represents all the recipe repo metadata.
-type RepoCatalogue map[string]RepoMeta
-
-// ReadReposMetadata retrieves coop-cloud/... repo metadata from Gitea.
-func ReadReposMetadata() (RepoCatalogue, error) {
-	reposMeta := make(RepoCatalogue)
-
-	pageIdx := 1
-	for {
-		var reposList []RepoMeta
-
-		pagedURL := fmt.Sprintf("%s?page=%v", ReposMetadataURL, pageIdx)
-
-		logrus.Debugf("fetching repo metadata from '%s'", pagedURL)
-
-		if err := web.ReadJSON(pagedURL, &reposList); err != nil {
-			return reposMeta, err
-		}
-
-		if len(reposList) == 0 {
-			break
-		}
-
-		for idx, repo := range reposList {
-			reposMeta[repo.Name] = reposList[idx]
-		}
-
-		pageIdx++
-	}
-
-	return reposMeta, nil
-}
-
-// GetRecipeVersions retrieves all recipe versions.
-func GetRecipeVersions(recipeName string) (RecipeVersions, error) {
-	versions := RecipeVersions{}
-
-	recipeDir := path.Join(config.ABRA_DIR, "apps", recipeName)
-
-	logrus.Debugf("attempting to open git repository in '%s'", recipeDir)
-
-	repo, err := git.PlainOpen(recipeDir)
-	if err != nil {
-		return versions, err
 	}
 
 	worktree, err := repo.Worktree()
 	if err != nil {
-		logrus.Fatal(err)
+		return err
 	}
 
-	gitTags, err := repo.Tags()
+	branch, err := gitPkg.CheckoutDefaultBranch(repo, config.CATALOGUE_DIR)
 	if err != nil {
-		return versions, err
+		return err
 	}
 
-	if err := gitTags.ForEach(func(ref *plumbing.Reference) (err error) {
+	opts := &git.PullOptions{
-		tag := strings.TrimPrefix(string(ref.Name()), "refs/tags/")
-
-		logrus.Debugf("processing '%s' for '%s'", tag, recipeName)
-
-		checkOutOpts := &git.CheckoutOptions{
-			Create: false,
 		Force:         true,
-			Keep:   false,
+		ReferenceName: branch,
-			Branch: plumbing.ReferenceName(ref.Name()),
 	}
-		if err := worktree.Checkout(checkOutOpts); err != nil {
+
-			logrus.Debugf("failed to check out '%s' in '%s'", tag, recipeDir)
+	if err := worktree.Pull(opts); err != nil {
+		if !strings.Contains(err.Error(), "already up-to-date") {
 			return err
 		}
-
-		logrus.Debugf("successfully checked out '%s' in '%s'", ref.Name(), recipeDir)
-
-		recipe, err := recipe.Get(recipeName)
-		if err != nil {
-			return err
 	}
 
-		versionMeta := make(map[string]serviceMeta)
+	logrus.Debugf("fetched latest git changes for %s", config.CATALOGUE_DIR)
-		for _, service := range recipe.Config.Services {
-
-			img, err := reference.ParseNormalizedNamed(service.Image)
-			if err != nil {
-				return err
-			}
-
-			path := reference.Path(img)
-			if strings.Contains(path, "library") {
-				path = strings.Split(path, "/")[1]
-			}
-
-			digest, err := client.GetTagDigest(img)
-			if err != nil {
-				return err
-			}
-
-			versionMeta[service.Name] = serviceMeta{
-				Digest: digest,
-				Image:  path,
-				Tag:    img.(reference.NamedTagged).Tag(),
-			}
-
-			logrus.Debugf("collecting digest: '%s', image: '%s', tag: '%s'", digest, path, tag)
-		}
-
-		versions = append(versions, map[string]map[string]serviceMeta{tag: versionMeta})
 
 	return nil
-	}); err != nil {
-		return versions, err
-	}
-
-	branch := "master"
-	if _, err := repo.Branch("master"); err != nil {
-		if _, err := repo.Branch("main"); err != nil {
-			logrus.Debugf("failed to select branch in '%s'", recipeDir)
-			logrus.Fatal(err)
-		}
-		branch = "main"
-	}
-
-	refName := fmt.Sprintf("refs/heads/%s", branch)
-	checkOutOpts := &git.CheckoutOptions{
-		Create: false,
-		Force:  true,
-		Keep:   false,
-		Branch: plumbing.ReferenceName(refName),
-	}
-	if err := worktree.Checkout(checkOutOpts); err != nil {
-		logrus.Debugf("failed to check out '%s' in '%s'", branch, recipeDir)
-		logrus.Fatal(err)
-	}
-
-	logrus.Debugf("switched back to '%s' in '%s'", branch, recipeDir)
-	logrus.Debugf("collected '%s' for '%s'", versions, recipeName)
-
-	return versions, nil
-}
-
-// GetRecipeCatalogueVersions list the recipe versions listed in the recipe catalogue.
-func GetRecipeCatalogueVersions(recipeName string) ([]string, error) {
-	var versions []string
-
-	catl, err := ReadRecipeCatalogue()
-	if err != nil {
-		return versions, err
-	}
-
-	if recipeMeta, exists := catl[recipeName]; exists {
-		for _, versionMeta := range recipeMeta.Versions {
-			for tag := range versionMeta {
-				versions = append(versions, tag)
-			}
-		}
-	}
-
-	return versions, nil
 }

pkg/client/client.go

@@ -2,39 +2,56 @@
 package client
 
 import (
+	"context"
+	"errors"
+	"fmt"
 	"net/http"
 	"os"
+	"time"
 
+	contextPkg "coopcloud.tech/abra/pkg/context"
+	sshPkg "coopcloud.tech/abra/pkg/ssh"
+	commandconnPkg "coopcloud.tech/abra/pkg/upstream/commandconn"
 	"github.com/docker/docker/client"
 	"github.com/sirupsen/logrus"
 )
 
-// New initiates a new Docker client.
+// New initiates a new Docker client. New client connections are validated so
-func New(contextName string) (*client.Client, error) {
+// that we ensure connections via SSH to the daemon can succeed. It takes into
-	context, err := GetContext(contextName)
+// 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) (*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
 		}
 
-	ctxEndpoint, err := GetContextEndpoint(context)
+		helper, err := commandconnPkg.NewConnectionHelper(ctxEndpoint)
 		if err != nil {
 			return nil, err
 		}
 
-	helper := newConnectionHelper(ctxEndpoint)
 		httpClient := &http.Client{
-		// No tls, no proxy
 			Transport: &http.Transport{
 				DialContext:     helper.Dialer,
+				IdleConnTimeout: 30 * time.Second,
 			},
 		}
 
-	var clientOpts []client.Opt
 		clientOpts = append(clientOpts,
 			client.WithHTTPClient(httpClient),
 			client.WithHost(helper.Host),
 			client.WithDialContext(helper.Dialer),
 		)
+	}
 
 	version := os.Getenv("DOCKER_API_VERSION")
 	if version != "" {
@@ -45,10 +62,23 @@ func New(contextName string) (*client.Client, error) {
 
 	cl, err := client.NewClientWithOpts(clientOpts...)
 	if err != nil {
-		logrus.Fatalf("unable to create Docker client: %s", err)
+		return nil, err
 	}
 
-	logrus.Debugf("created client for '%s'", contextName)
+	logrus.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)
+		} else {
+			return cl, errors.New("swarm mode not enabled on local server?")
+		}
+	}
 
 	return cl, nil
 }

pkg/client/connection.go

@@ -1,45 +0,0 @@
-package client
-
-import (
-	"github.com/docker/cli/cli/connhelper"
-	"github.com/docker/cli/cli/context/docker"
-	dCliContextStore "github.com/docker/cli/cli/context/store"
-	dClient "github.com/docker/docker/client"
-	"github.com/sirupsen/logrus"
-)
-
-func newConnectionHelper(daemonURL string) *connhelper.ConnectionHelper {
-	helper, err := connhelper.GetConnectionHelper(daemonURL)
-
-	if err != nil {
-		logrus.Fatal(err)
-	}
-	return helper
-}
-
-func getDockerEndpoint(host string) (docker.Endpoint, error) {
-	skipTLSVerify := false
-	ep := docker.Endpoint{
-		EndpointMeta: docker.EndpointMeta{
-			Host:          host,
-			SkipTLSVerify: skipTLSVerify,
-		},
-	}
-	// try to resolve a docker client, validating the configuration
-	opts, err := ep.ClientOpts()
-	if err != nil {
-		return docker.Endpoint{}, err
-	}
-	if _, err := dClient.NewClientWithOpts(opts...); err != nil {
-		return docker.Endpoint{}, err
-	}
-	return ep, nil
-}
-
-func getDockerEndpointMetadataAndTLS(host string) (docker.EndpointMeta, *dCliContextStore.EndpointTLSData, error) {
-	ep, err := getDockerEndpoint(host)
-	if err != nil {
-		return docker.EndpointMeta{}, nil, err
-	}
-	return ep.EndpointMeta, ep.TLSData.ToStoreTLSData(), nil
-}

pkg/client/container/LICENSE

@@ -1,191 +0,0 @@
-
-                                 Apache License
-                           Version 2.0, January 2004
-                        https://www.apache.org/licenses/
-
-   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
-
-   1. Definitions.
-
-      "License" shall mean the terms and conditions for use, reproduction,
-      and distribution as defined by Sections 1 through 9 of this document.
-
-      "Licensor" shall mean the copyright owner or entity authorized by
-      the copyright owner that is granting the License.
-
-      "Legal Entity" shall mean the union of the acting entity and all
-      other entities that control, are controlled by, or are under common
-      control with that entity. For the purposes of this definition,
-      "control" means (i) the power, direct or indirect, to cause the
-      direction or management of such entity, whether by contract or
-      otherwise, or (ii) ownership of fifty percent (50%) or more of the
-      outstanding shares, or (iii) beneficial ownership of such entity.
-
-      "You" (or "Your") shall mean an individual or Legal Entity
-      exercising permissions granted by this License.
-
-      "Source" form shall mean the preferred form for making modifications,
-      including but not limited to software source code, documentation
-      source, and configuration files.
-
-      "Object" form shall mean any form resulting from mechanical
-      transformation or translation of a Source form, including but
-      not limited to compiled object code, generated documentation,
-      and conversions to other media types.
-
-      "Work" shall mean the work of authorship, whether in Source or
-      Object form, made available under the License, as indicated by a
-      copyright notice that is included in or attached to the work
-      (an example is provided in the Appendix below).
-
-      "Derivative Works" shall mean any work, whether in Source or Object
-      form, that is based on (or derived from) the Work and for which the
-      editorial revisions, annotations, elaborations, or other modifications
-      represent, as a whole, an original work of authorship. For the purposes
-      of this License, Derivative Works shall not include works that remain
-      separable from, or merely link (or bind by name) to the interfaces of,
-      the Work and Derivative Works thereof.
-
-      "Contribution" shall mean any work of authorship, including
-      the original version of the Work and any modifications or additions
-      to that Work or Derivative Works thereof, that is intentionally
-      submitted to Licensor for inclusion in the Work by the copyright owner
-      or by an individual or Legal Entity authorized to submit on behalf of
-      the copyright owner. For the purposes of this definition, "submitted"
-      means any form of electronic, verbal, or written communication sent
-      to the Licensor or its representatives, including but not limited to
-      communication on electronic mailing lists, source code control systems,
-      and issue tracking systems that are managed by, or on behalf of, the
-      Licensor for the purpose of discussing and improving the Work, but
-      excluding communication that is conspicuously marked or otherwise
-      designated in writing by the copyright owner as "Not a Contribution."
-
-      "Contributor" shall mean Licensor and any individual or Legal Entity
-      on behalf of whom a Contribution has been received by Licensor and
-      subsequently incorporated within the Work.
-
-   2. Grant of Copyright License. Subject to the terms and conditions of
-      this License, each Contributor hereby grants to You a perpetual,
-      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
-      copyright license to reproduce, prepare Derivative Works of,
-      publicly display, publicly perform, sublicense, and distribute the
-      Work and such Derivative Works in Source or Object form.
-
-   3. Grant of Patent License. Subject to the terms and conditions of
-      this License, each Contributor hereby grants to You a perpetual,
-      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
-      (except as stated in this section) patent license to make, have made,
-      use, offer to sell, sell, import, and otherwise transfer the Work,
-      where such license applies only to those patent claims licensable
-      by such Contributor that are necessarily infringed by their
-      Contribution(s) alone or by combination of their Contribution(s)
-      with the Work to which such Contribution(s) was submitted. If You
-      institute patent litigation against any entity (including a
-      cross-claim or counterclaim in a lawsuit) alleging that the Work
-      or a Contribution incorporated within the Work constitutes direct
-      or contributory patent infringement, then any patent licenses
-      granted to You under this License for that Work shall terminate
-      as of the date such litigation is filed.
-
-   4. Redistribution. You may reproduce and distribute copies of the
-      Work or Derivative Works thereof in any medium, with or without
-      modifications, and in Source or Object form, provided that You
-      meet the following conditions:
-
-      (a) You must give any other recipients of the Work or
-          Derivative Works a copy of this License; and
-
-      (b) You must cause any modified files to carry prominent notices
-          stating that You changed the files; and
-
-      (c) You must retain, in the Source form of any Derivative Works
-          that You distribute, all copyright, patent, trademark, and
-          attribution notices from the Source form of the Work,
-          excluding those notices that do not pertain to any part of
-          the Derivative Works; and
-
-      (d) If the Work includes a "NOTICE" text file as part of its
-          distribution, then any Derivative Works that You distribute must
-          include a readable copy of the attribution notices contained
-          within such NOTICE file, excluding those notices that do not
-          pertain to any part of the Derivative Works, in at least one
-          of the following places: within a NOTICE text file distributed
-          as part of the Derivative Works; within the Source form or
-          documentation, if provided along with the Derivative Works; or,
-          within a display generated by the Derivative Works, if and
-          wherever such third-party notices normally appear. The contents
-          of the NOTICE file are for informational purposes only and
-          do not modify the License. You may add Your own attribution
-          notices within Derivative Works that You distribute, alongside
-          or as an addendum to the NOTICE text from the Work, provided
-          that such additional attribution notices cannot be construed
-          as modifying the License.
-
-      You may add Your own copyright statement to Your modifications and
-      may provide additional or different license terms and conditions
-      for use, reproduction, or distribution of Your modifications, or
-      for any such Derivative Works as a whole, provided Your use,
-      reproduction, and distribution of the Work otherwise complies with
-      the conditions stated in this License.
-
-   5. Submission of Contributions. Unless You explicitly state otherwise,
-      any Contribution intentionally submitted for inclusion in the Work
-      by You to the Licensor shall be under the terms and conditions of
-      this License, without any additional terms or conditions.
-      Notwithstanding the above, nothing herein shall supersede or modify
-      the terms of any separate license agreement you may have executed
-      with Licensor regarding such Contributions.
-
-   6. Trademarks. This License does not grant permission to use the trade
-      names, trademarks, service marks, or product names of the Licensor,
-      except as required for reasonable and customary use in describing the
-      origin of the Work and reproducing the content of the NOTICE file.
-
-   7. Disclaimer of Warranty. Unless required by applicable law or
-      agreed to in writing, Licensor provides the Work (and each
-      Contributor provides its Contributions) on an "AS IS" BASIS,
-      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
-      implied, including, without limitation, any warranties or conditions
-      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
-      PARTICULAR PURPOSE. You are solely responsible for determining the
-      appropriateness of using or redistributing the Work and assume any
-      risks associated with Your exercise of permissions under this License.
-
-   8. Limitation of Liability. In no event and under no legal theory,
-      whether in tort (including negligence), contract, or otherwise,
-      unless required by applicable law (such as deliberate and grossly
-      negligent acts) or agreed to in writing, shall any Contributor be
-      liable to You for damages, including any direct, indirect, special,
-      incidental, or consequential damages of any character arising as a
-      result of this License or out of the use or inability to use the
-      Work (including but not limited to damages for loss of goodwill,
-      work stoppage, computer failure or malfunction, or any and all
-      other commercial damages or losses), even if such Contributor
-      has been advised of the possibility of such damages.
-
-   9. Accepting Warranty or Additional Liability. While redistributing
-      the Work or Derivative Works thereof, You may choose to offer,
-      and charge a fee for, acceptance of support, warranty, indemnity,
-      or other liability obligations and/or rights consistent with this
-      License. However, in accepting such obligations, You may act only
-      on Your own behalf and on Your sole responsibility, not on behalf
-      of any other Contributor, and only if You agree to indemnify,
-      defend, and hold each Contributor harmless for any liability
-      incurred by, or claims asserted against, such Contributor by reason
-      of your accepting any such warranty or additional liability.
-
-   END OF TERMS AND CONDITIONS
-
-   Copyright 2013-2017 Docker, Inc.
-
-   Licensed under the Apache License, Version 2.0 (the "License");
-   you may not use this file except in compliance with the License.
-   You may obtain a copy of the License at
-
-       https://www.apache.org/licenses/LICENSE-2.0
-
-   Unless required by applicable law or agreed to in writing, software
-   distributed under the License is distributed on an "AS IS" BASIS,
-   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-   See the License for the specific language governing permissions and
-   limitations under the License.

pkg/client/container/README.md

@@ -1,7 +0,0 @@
-# github.com/docker/cli/cli/command/container
-
-Due to this literally just being copy-pasted from the lib, the Apache license
-will be posted in this folder. Small edits to the source code have been to
-function names and parts we don't need deleted.
-
-Same vibe as [../convert](../convert).

pkg/client/context.go

@@ -4,12 +4,11 @@ import (
 	"errors"
 	"fmt"
 
-	command "github.com/docker/cli/cli/command"
+	"coopcloud.tech/abra/pkg/context"
+	commandconnPkg "coopcloud.tech/abra/pkg/upstream/commandconn"
 	dConfig "github.com/docker/cli/cli/config"
-	context "github.com/docker/cli/cli/context"
 	"github.com/docker/cli/cli/context/docker"
 	contextStore "github.com/docker/cli/cli/context/store"
-	"github.com/moby/term"
 	"github.com/sirupsen/logrus"
 )
 
@@ -27,13 +26,13 @@ func CreateContext(contextName string, user string, port string) error {
 	if err := createContext(contextName, host); err != nil {
 		return err
 	}
-	logrus.Debugf("created the '%s' context", contextName)
+	logrus.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 := NewDefaultDockerContextStore()
+	s := context.NewDefaultDockerContextStore()
 	contextMetadata := contextStore.Metadata{
 		Endpoints: make(map[string]interface{}),
 		Name:      name,
@@ -43,7 +42,7 @@ func createContext(name string, host string) error {
 		Endpoints: make(map[string]contextStore.EndpointTLSData),
 	}
 
-	dockerEP, dockerTLS, err := getDockerEndpointMetadataAndTLS(host)
+	dockerEP, dockerTLS, err := commandconnPkg.GetDockerEndpointMetadataAndTLS(host)
 	if err != nil {
 		return err
 	}
@@ -73,56 +72,20 @@ func DeleteContext(name string) error {
 		return err
 	}
 
-	// remove any context that might be loaded
-	// TODO: Check if the context we are removing is the active one rather than doing it all the time
 	cfg := dConfig.LoadDefaultConfigFile(nil)
 	cfg.CurrentContext = ""
 	if err := cfg.Save(); err != nil {
 		return err
 	}
 
-	return NewDefaultDockerContextStore().Remove(name)
+	return context.NewDefaultDockerContextStore().Remove(name)
 }
 
 func GetContext(contextName string) (contextStore.Metadata, error) {
-	ctx, err := NewDefaultDockerContextStore().GetMetadata(contextName)
+	ctx, err := context.NewDefaultDockerContextStore().GetMetadata(contextName)
 	if err != nil {
 		return contextStore.Metadata{}, err
 	}
 
 	return ctx, nil
 }
-
-func GetContextEndpoint(ctx contextStore.Metadata) (string, error) {
-	// safe to use docker key hardcoded since abra doesn't use k8s... yet...
-	endpointmeta, ok := ctx.Endpoints["docker"].(context.EndpointMetaBase)
-	if !ok {
-		err := errors.New("context lacks Docker endpoint")
-		return "", err
-	}
-	return endpointmeta.Host, nil
-}
-
-func newContextStore(dir string, config contextStore.Config) contextStore.Store {
-	return contextStore.New(dir, config)
-}
-
-func NewDefaultDockerContextStore() *command.ContextStoreWithDefault {
-	// Grabbing the stderr from Docker commands
-	// Much easier to fit this into the code we are using to replicate docker cli commands
-	_, _, stderr := term.StdStreams()
-	// TODO: Look into custom docker configs in case users want that
-	dockerConfig := dConfig.LoadDefaultConfigFile(stderr)
-	contextDir := dConfig.ContextStoreDir()
-	storeConfig := command.DefaultContextStoreConfig()
-	store := newContextStore(contextDir, storeConfig)
-
-	dockerContextStore := &command.ContextStoreWithDefault{
-		Store: store,
-		Resolver: func() (*command.DefaultContext, error) {
-			// nil for the Opts because it works without it and its a cli thing
-			return command.ResolveDefaultContext(nil, dockerConfig, storeConfig, stderr)
-		},
-	}
-	return dockerContextStore
-}

pkg/client/context_test.go

@@ -1,52 +0,0 @@
-package client_test
-
-import (
-	"testing"
-
-	"coopcloud.tech/abra/pkg/client"
-	dContext "github.com/docker/cli/cli/context"
-	dCliContextStore "github.com/docker/cli/cli/context/store"
-)
-
-type TestContext struct {
-	context           dCliContextStore.Metadata
-	expected_endpoint string
-}
-
-func dockerContext(host, key string) TestContext {
-	dockerContext := dCliContextStore.Metadata{
-		Name:     "foo",
-		Metadata: nil,
-		Endpoints: map[string]interface{}{
-			key: dContext.EndpointMetaBase{
-				Host:          host,
-				SkipTLSVerify: false,
-			},
-		},
-	}
-	return TestContext{
-		context:           dockerContext,
-		expected_endpoint: host,
-	}
-}
-
-func TestGetContextEndpoint(t *testing.T) {
-	var testDockerContexts = []TestContext{
-		dockerContext("ssh://foobar", "docker"),
-		dockerContext("ssh://foobar", "k8"),
-	}
-	for _, context := range testDockerContexts {
-		endpoint, err := client.GetContextEndpoint(context.context)
-		if err != nil {
-			if err.Error() != "context lacks Docker endpoint" {
-				t.Error(err)
-			}
-		} else {
-			if endpoint != context.expected_endpoint {
-				t.Errorf("did not get correct context endpoint. Expected: %s, received: %s", context.expected_endpoint, endpoint)
-			}
-		}
-
-	}
-
-}

pkg/client/convert/LICENSE

@@ -1,191 +0,0 @@
-
-                                 Apache License
-                           Version 2.0, January 2004
-                        https://www.apache.org/licenses/
-
-   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
-
-   1. Definitions.
-
-      "License" shall mean the terms and conditions for use, reproduction,
-      and distribution as defined by Sections 1 through 9 of this document.
-
-      "Licensor" shall mean the copyright owner or entity authorized by
-      the copyright owner that is granting the License.
-
-      "Legal Entity" shall mean the union of the acting entity and all
-      other entities that control, are controlled by, or are under common
-      control with that entity. For the purposes of this definition,
-      "control" means (i) the power, direct or indirect, to cause the
-      direction or management of such entity, whether by contract or
-      otherwise, or (ii) ownership of fifty percent (50%) or more of the
-      outstanding shares, or (iii) beneficial ownership of such entity.
-
-      "You" (or "Your") shall mean an individual or Legal Entity
-      exercising permissions granted by this License.
-
-      "Source" form shall mean the preferred form for making modifications,
-      including but not limited to software source code, documentation
-      source, and configuration files.
-
-      "Object" form shall mean any form resulting from mechanical
-      transformation or translation of a Source form, including but
-      not limited to compiled object code, generated documentation,
-      and conversions to other media types.
-
-      "Work" shall mean the work of authorship, whether in Source or
-      Object form, made available under the License, as indicated by a
-      copyright notice that is included in or attached to the work
-      (an example is provided in the Appendix below).
-
-      "Derivative Works" shall mean any work, whether in Source or Object
-      form, that is based on (or derived from) the Work and for which the
-      editorial revisions, annotations, elaborations, or other modifications
-      represent, as a whole, an original work of authorship. For the purposes
-      of this License, Derivative Works shall not include works that remain
-      separable from, or merely link (or bind by name) to the interfaces of,
-      the Work and Derivative Works thereof.
-
-      "Contribution" shall mean any work of authorship, including
-      the original version of the Work and any modifications or additions
-      to that Work or Derivative Works thereof, that is intentionally
-      submitted to Licensor for inclusion in the Work by the copyright owner
-      or by an individual or Legal Entity authorized to submit on behalf of
-      the copyright owner. For the purposes of this definition, "submitted"
-      means any form of electronic, verbal, or written communication sent
-      to the Licensor or its representatives, including but not limited to
-      communication on electronic mailing lists, source code control systems,
-      and issue tracking systems that are managed by, or on behalf of, the
-      Licensor for the purpose of discussing and improving the Work, but
-      excluding communication that is conspicuously marked or otherwise
-      designated in writing by the copyright owner as "Not a Contribution."
-
-      "Contributor" shall mean Licensor and any individual or Legal Entity
-      on behalf of whom a Contribution has been received by Licensor and
-      subsequently incorporated within the Work.
-
-   2. Grant of Copyright License. Subject to the terms and conditions of
-      this License, each Contributor hereby grants to You a perpetual,
-      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
-      copyright license to reproduce, prepare Derivative Works of,
-      publicly display, publicly perform, sublicense, and distribute the
-      Work and such Derivative Works in Source or Object form.
-
-   3. Grant of Patent License. Subject to the terms and conditions of
-      this License, each Contributor hereby grants to You a perpetual,
-      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
-      (except as stated in this section) patent license to make, have made,
-      use, offer to sell, sell, import, and otherwise transfer the Work,
-      where such license applies only to those patent claims licensable
-      by such Contributor that are necessarily infringed by their
-      Contribution(s) alone or by combination of their Contribution(s)
-      with the Work to which such Contribution(s) was submitted. If You
-      institute patent litigation against any entity (including a
-      cross-claim or counterclaim in a lawsuit) alleging that the Work
-      or a Contribution incorporated within the Work constitutes direct
-      or contributory patent infringement, then any patent licenses
-      granted to You under this License for that Work shall terminate
-      as of the date such litigation is filed.
-
-   4. Redistribution. You may reproduce and distribute copies of the
-      Work or Derivative Works thereof in any medium, with or without
-      modifications, and in Source or Object form, provided that You
-      meet the following conditions:
-
-      (a) You must give any other recipients of the Work or
-          Derivative Works a copy of this License; and
-
-      (b) You must cause any modified files to carry prominent notices
-          stating that You changed the files; and
-
-      (c) You must retain, in the Source form of any Derivative Works
-          that You distribute, all copyright, patent, trademark, and
-          attribution notices from the Source form of the Work,
-          excluding those notices that do not pertain to any part of
-          the Derivative Works; and
-
-      (d) If the Work includes a "NOTICE" text file as part of its
-          distribution, then any Derivative Works that You distribute must
-          include a readable copy of the attribution notices contained
-          within such NOTICE file, excluding those notices that do not
-          pertain to any part of the Derivative Works, in at least one
-          of the following places: within a NOTICE text file distributed
-          as part of the Derivative Works; within the Source form or
-          documentation, if provided along with the Derivative Works; or,
-          within a display generated by the Derivative Works, if and
-          wherever such third-party notices normally appear. The contents
-          of the NOTICE file are for informational purposes only and
-          do not modify the License. You may add Your own attribution
-          notices within Derivative Works that You distribute, alongside
-          or as an addendum to the NOTICE text from the Work, provided
-          that such additional attribution notices cannot be construed
-          as modifying the License.
-
-      You may add Your own copyright statement to Your modifications and
-      may provide additional or different license terms and conditions
-      for use, reproduction, or distribution of Your modifications, or
-      for any such Derivative Works as a whole, provided Your use,
-      reproduction, and distribution of the Work otherwise complies with
-      the conditions stated in this License.
-
-   5. Submission of Contributions. Unless You explicitly state otherwise,
-      any Contribution intentionally submitted for inclusion in the Work
-      by You to the Licensor shall be under the terms and conditions of
-      this License, without any additional terms or conditions.
-      Notwithstanding the above, nothing herein shall supersede or modify
-      the terms of any separate license agreement you may have executed
-      with Licensor regarding such Contributions.
-
-   6. Trademarks. This License does not grant permission to use the trade
-      names, trademarks, service marks, or product names of the Licensor,
-      except as required for reasonable and customary use in describing the
-      origin of the Work and reproducing the content of the NOTICE file.
-
-   7. Disclaimer of Warranty. Unless required by applicable law or
-      agreed to in writing, Licensor provides the Work (and each
-      Contributor provides its Contributions) on an "AS IS" BASIS,
-      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
-      implied, including, without limitation, any warranties or conditions
-      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
-      PARTICULAR PURPOSE. You are solely responsible for determining the
-      appropriateness of using or redistributing the Work and assume any
-      risks associated with Your exercise of permissions under this License.
-
-   8. Limitation of Liability. In no event and under no legal theory,
-      whether in tort (including negligence), contract, or otherwise,
-      unless required by applicable law (such as deliberate and grossly
-      negligent acts) or agreed to in writing, shall any Contributor be
-      liable to You for damages, including any direct, indirect, special,
-      incidental, or consequential damages of any character arising as a
-      result of this License or out of the use or inability to use the
-      Work (including but not limited to damages for loss of goodwill,
-      work stoppage, computer failure or malfunction, or any and all
-      other commercial damages or losses), even if such Contributor
-      has been advised of the possibility of such damages.
-
-   9. Accepting Warranty or Additional Liability. While redistributing
-      the Work or Derivative Works thereof, You may choose to offer,
-      and charge a fee for, acceptance of support, warranty, indemnity,
-      or other liability obligations and/or rights consistent with this
-      License. However, in accepting such obligations, You may act only
-      on Your own behalf and on Your sole responsibility, not on behalf
-      of any other Contributor, and only if You agree to indemnify,
-      defend, and hold each Contributor harmless for any liability
-      incurred by, or claims asserted against, such Contributor by reason
-      of your accepting any such warranty or additional liability.
-
-   END OF TERMS AND CONDITIONS
-
-   Copyright 2013-2017 Docker, Inc.
-
-   Licensed under the Apache License, Version 2.0 (the "License");
-   you may not use this file except in compliance with the License.
-   You may obtain a copy of the License at
-
-       https://www.apache.org/licenses/LICENSE-2.0
-
-   Unless required by applicable law or agreed to in writing, software
-   distributed under the License is distributed on an "AS IS" BASIS,
-   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-   See the License for the specific language governing permissions and
-   limitations under the License.

pkg/client/convert/README.md

@@ -1,10 +0,0 @@
-# github.com/docker/cli/cli/compose/convert
-
-DISCLAIMER: This is like the entire `github.com/docker/cli/cli/compose/convert`
-package. This should be an easy import but importing it creates DEPENDENCY
-HELL. I tried for an hour to fix it but it would work. TRY TO FIX AT YOUR OWN
-RISK!!!
-
-Due to this literally just being copy-pasted from the lib, the Apache license
-will be posted in this folder. Small edits to the source code have been to
-function names and parts we don't need deleted.

pkg/client/registry.go

@@ -1,170 +1,28 @@
 package client
 
 import (
-	"encoding/json"
+	"context"
 	"fmt"
-	"io/ioutil"
-	"net/http"
-	"strings"
 
-	"coopcloud.tech/abra/pkg/web"
+	"github.com/containers/image/docker"
+	"github.com/containers/image/types"
 	"github.com/docker/distribution/reference"
 )
 
-type RawTag struct {
+// GetRegistryTags retrieves all tags of an image from a container registry.
-	Layer string
+func GetRegistryTags(img reference.Named) ([]string, error) {
-	Name  string
+	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())
 	}
 
-type RawTags []RawTag
+	ctx := context.Background()
-
+	tags, err = docker.GetRepositoryTags(ctx, &types.SystemContext{}, ref)
-var registryURL = "https://registry.hub.docker.com/v1/repositories/%s/tags"
+	if err != nil {
-
-func GetRegistryTags(image string) (RawTags, error) {
-	var tags RawTags
-
-	tagsUrl := fmt.Sprintf(registryURL, image)
-	if err := web.ReadJSON(tagsUrl, &tags); err != nil {
 		return tags, err
 	}
 
 	return tags, nil
 }
-
-// getRegv2Token retrieves a registry v2 authentication token.
-func getRegv2Token(image reference.Named) (string, error) {
-	img := reference.Path(image)
-	authTokenURL := fmt.Sprintf("https://auth.docker.io/token?service=registry.docker.io&scope=repository:%s:pull", img)
-	req, err := http.NewRequest("GET", authTokenURL, nil)
-	if err != nil {
-		return "", err
-	}
-
-	client := &http.Client{Timeout: web.Timeout}
-	res, err := client.Do(req)
-	if err != nil {
-		return "", err
-	}
-	defer res.Body.Close()
-
-	if res.StatusCode != http.StatusOK {
-		_, err := ioutil.ReadAll(res.Body)
-		if err != nil {
-			return "", err
-		}
-	}
-
-	body, err := ioutil.ReadAll(res.Body)
-	if err != nil {
-		return "", nil
-	}
-
-	tokenRes := struct {
-		Token  string
-		Expiry string
-		Issued string
-	}{}
-
-	if err := json.Unmarshal(body, &tokenRes); err != nil {
-		return "", err
-	}
-
-	return tokenRes.Token, nil
-}
-
-// GetTagDigest retrieves an image digest from a v2 registry
-func GetTagDigest(image reference.Named) (string, error) {
-	img := reference.Path(image)
-	tag := image.(reference.NamedTagged).Tag()
-	manifestURL := fmt.Sprintf("https://index.docker.io/v2/%s/manifests/%s", img, tag)
-
-	req, err := http.NewRequest("GET", manifestURL, nil)
-	if err != nil {
-		return "", err
-	}
-
-	token, err := getRegv2Token(image)
-	if err != nil {
-		return "", err
-	}
-
-	req.Header = http.Header{
-		"Accept": []string{
-			"application/vnd.docker.distribution.manifest.v2+json",
-			"application/vnd.docker.distribution.manifest.list.v2+json",
-		},
-		"Authorization": []string{fmt.Sprintf("Bearer %s", token)},
-	}
-
-	client := &http.Client{Timeout: web.Timeout}
-	res, err := client.Do(req)
-	if err != nil {
-		return "", err
-	}
-	defer res.Body.Close()
-
-	if res.StatusCode != http.StatusOK {
-		_, err := ioutil.ReadAll(res.Body)
-		if err != nil {
-			return "", err
-		}
-	}
-
-	body, err := ioutil.ReadAll(res.Body)
-	if err != nil {
-		return "", err
-	}
-
-	registryResT1 := struct {
-		SchemaVersion int
-		MediaType     string
-		Manifests     []struct {
-			MediaType string
-			Size      int
-			Digest    string
-			Platform  struct {
-				Architecture string
-				Os           string
-			}
-		}
-	}{}
-
-	registryResT2 := struct {
-		SchemaVersion int
-		MediaType     string
-		Config        struct {
-			MediaType string
-			Size      int
-			Digest    string
-		}
-		Layers []struct {
-			MediaType string
-			Size      int
-			Digest    string
-		}
-	}{}
-
-	if err := json.Unmarshal(body, &registryResT1); err != nil {
-		return "", err
-	}
-
-	var digest string
-	for _, manifest := range registryResT1.Manifests {
-		if string(manifest.Platform.Architecture) == "amd64" {
-			digest = strings.Split(manifest.Digest, ":")[1][:7]
-		}
-	}
-
-	if digest == "" {
-		if err := json.Unmarshal(body, &registryResT2); err != nil {
-			return "", err
-		}
-		digest = strings.Split(registryResT2.Config.Digest, ":")[1][:7]
-	}
-
-	if digest == "" {
-		return "", fmt.Errorf("Unable to retrieve amd64 digest for '%s'", image)
-	}
-
-	return digest, nil
-}

pkg/client/secret.go

@@ -4,20 +4,14 @@ import (
 	"context"
 
 	"github.com/docker/docker/api/types/swarm"
+	"github.com/docker/docker/client"
 )
 
-func StoreSecret(secretName, secretValue, server string) error {
+func StoreSecret(cl *client.Client, secretName, secretValue, server string) error {
-	cl, err := New(server)
-	if err != nil {
-		return err
-	}
-
-	ctx := context.Background()
 	ann := swarm.Annotations{Name: secretName}
 	spec := swarm.SecretSpec{Annotations: ann, Data: []byte(secretValue)}
 
-	// We don't bother with the secret IDs for now
+	if _, err := cl.SecretCreate(context.Background(), spec); err != nil {
-	if _, err := cl.SecretCreate(ctx, spec); err != nil {
 		return err
 	}
 

pkg/client/volumes.go

@@ -3,49 +3,39 @@ package client
 import (
 	"context"
 
-	"github.com/docker/docker/api/types"
 	"github.com/docker/docker/api/types/filters"
-	"github.com/sirupsen/logrus"
+	"github.com/docker/docker/api/types/volume"
+	"github.com/docker/docker/client"
 )
 
-func GetVolumes(ctx context.Context, server string, appName string) ([]*types.Volume, error) {
+func GetVolumes(cl *client.Client, ctx context.Context, server string, fs filters.Args) ([]*volume.Volume, error) {
-
+	volumeListOptions := volume.ListOptions{fs}
-	cl, err := New(server)
+	volumeListOKBody, err := cl.VolumeList(ctx, volumeListOptions)
-	if err != nil {
-		return nil, err
-	}
-
-	fs := filters.NewArgs()
-	fs.Add("name", appName)
-
-	volumeListOKBody, err := cl.VolumeList(ctx, fs)
 	volumeList := volumeListOKBody.Volumes
 	if err != nil {
-		logrus.Fatal(err)
+		return volumeList, err
 	}
 
 	return volumeList, nil
 }
 
-func GetVolumeNames(volumes []*types.Volume) []string {
+func GetVolumeNames(volumes []*volume.Volume) []string {
 	var volumeNames []string
+
 	for _, vol := range volumes {
 		volumeNames = append(volumeNames, vol.Name)
 	}
+
 	return volumeNames
 }
 
-func RemoveVolumes(ctx context.Context, server string, volumeNames []string, force bool) error {
+func RemoveVolumes(cl *client.Client, ctx context.Context, server string, volumeNames []string, force bool) error {
-	cl, err := New(server)
-	if err != nil {
-		return err
-	}
 	for _, volName := range volumeNames {
 		err := cl.VolumeRemove(ctx, volName, force)
 		if err != nil {
 			return err
 		}
 	}
-	return nil
 
+	return nil
 }

pkg/compose/compose.go

@@ -7,35 +7,36 @@ import (
 	"path/filepath"
 	"strings"
 
-	"coopcloud.tech/abra/pkg/client/stack"
-	loader "coopcloud.tech/abra/pkg/client/stack"
 	"coopcloud.tech/abra/pkg/config"
+	"coopcloud.tech/abra/pkg/formatter"
+	"coopcloud.tech/abra/pkg/upstream/stack"
+	loader "coopcloud.tech/abra/pkg/upstream/stack"
 	composetypes "github.com/docker/cli/cli/compose/types"
 	"github.com/docker/distribution/reference"
 	"github.com/sirupsen/logrus"
 )
 
 // UpdateTag updates an image tag in-place on file system local compose files.
-func UpdateTag(pattern, image, tag, recipeName string) error {
+func UpdateTag(pattern, image, tag, recipeName string) (bool, error) {
 	composeFiles, err := filepath.Glob(pattern)
 	if err != nil {
-		return err
+		return false, err
 	}
 
-	logrus.Debugf("considering '%s' config(s) for tag update", strings.Join(composeFiles, ", "))
+	logrus.Debugf("considering %s config(s) for tag update", strings.Join(composeFiles, ", "))
 
 	for _, composeFile := range composeFiles {
 		opts := stack.Deploy{Composefiles: []string{composeFile}}
 
-		envSamplePath := path.Join(config.ABRA_DIR, "apps", recipeName, ".env.sample")
+		envSamplePath := path.Join(config.RECIPES_DIR, recipeName, ".env.sample")
 		sampleEnv, err := config.ReadEnv(envSamplePath)
 		if err != nil {
-			return err
+			return false, err
 		}
 
 		compose, err := loader.LoadComposefile(opts, sampleEnv)
 		if err != nil {
-			return err
+			return false, err
 		}
 
 		for _, service := range compose.Services {
@@ -45,40 +46,42 @@ func UpdateTag(pattern, image, tag, recipeName string) error {
 
 			img, _ := reference.ParseNormalizedNamed(service.Image)
 			if err != nil {
-				return err
+				return false, err
 			}
 
-			composeImage := reference.Path(img)
+			var composeTag string
-			if strings.Contains(composeImage, "library") {
+			switch img.(type) {
-				// ParseNormalizedNamed prepends 'library' to images like nginx:<tag>,
+			case reference.NamedTagged:
-				// postgres:<tag>, i.e. images which do not have a username in the
+				composeTag = img.(reference.NamedTagged).Tag()
-				// first position of the string
+			default:
-				composeImage = strings.Split(composeImage, "/")[1]
+				logrus.Debugf("unable to parse %s, skipping", img)
+				continue
 			}
-			composeTag := img.(reference.NamedTagged).Tag()
 
-			logrus.Debugf("parsed '%s' from '%s'", composeTag, service.Image)
+			composeImage := formatter.StripTagMeta(reference.Path(img))
+
+			logrus.Debugf("parsed %s from %s", composeTag, service.Image)
 
 			if image == composeImage {
 				bytes, err := ioutil.ReadFile(composeFile)
 				if err != nil {
-					return err
+					return false, err
 				}
 
 				old := fmt.Sprintf("%s:%s", composeImage, composeTag)
 				new := fmt.Sprintf("%s:%s", composeImage, tag)
 				replacedBytes := strings.Replace(string(bytes), old, new, -1)
 
-				logrus.Debugf("updating '%s' to '%s' in '%s'", old, new, compose.Filename)
+				logrus.Debugf("updating %s to %s in %s", old, new, compose.Filename)
 
-				if err := ioutil.WriteFile(compose.Filename, []byte(replacedBytes), 0644); err != nil {
+				if err := ioutil.WriteFile(compose.Filename, []byte(replacedBytes), 0764); err != nil {
-					return err
+					return false, err
 				}
 			}
 		}
 	}
 
-	return nil
+	return false, nil
 }
 
 // UpdateLabel updates a label in-place on file system local compose files.
@@ -88,12 +91,12 @@ func UpdateLabel(pattern, serviceName, label, recipeName string) error {
 		return err
 	}
 
-	logrus.Debugf("considering '%s' config(s) for label update", strings.Join(composeFiles, ", "))
+	logrus.Debugf("considering %s config(s) for label update", strings.Join(composeFiles, ", "))
 
 	for _, composeFile := range composeFiles {
 		opts := stack.Deploy{Composefiles: []string{composeFile}}
 
-		envSamplePath := path.Join(config.ABRA_DIR, "apps", recipeName, ".env.sample")
+		envSamplePath := path.Join(config.RECIPES_DIR, recipeName, ".env.sample")
 		sampleEnv, err := config.ReadEnv(envSamplePath)
 		if err != nil {
 			return err
@@ -117,8 +120,11 @@ func UpdateLabel(pattern, serviceName, label, recipeName string) error {
 			continue
 		}
 
+		discovered := false
 		for oldLabel, value := range service.Deploy.Labels {
-			if strings.HasPrefix(oldLabel, "coop-cloud") {
+			if strings.HasPrefix(oldLabel, "coop-cloud") && strings.Contains(oldLabel, "version") {
+				discovered = true
+
 				bytes, err := ioutil.ReadFile(composeFile)
 				if err != nil {
 					return err
@@ -127,13 +133,25 @@ func UpdateLabel(pattern, serviceName, label, recipeName string) error {
 				old := fmt.Sprintf("coop-cloud.${STACK_NAME}.version=%s", value)
 				replacedBytes := strings.Replace(string(bytes), old, label, -1)
 
-				logrus.Debugf("updating '%s' to '%s' in '%s'", old, label, compose.Filename)
+				if old == label {
+					logrus.Warnf("%s is already set, nothing to do?", label)
+					return nil
+				}
 
-				if err := ioutil.WriteFile(compose.Filename, []byte(replacedBytes), 0644); err != nil {
+				logrus.Debugf("updating %s to %s in %s", old, label, compose.Filename)
+
+				if err := ioutil.WriteFile(compose.Filename, []byte(replacedBytes), 0764); err != nil {
 					return err
 				}
+
+				logrus.Infof("synced label %s to service %s", label, serviceName)
 			}
 		}
+
+		if !discovered {
+			logrus.Warn("no existing label found, automagic insertion not supported yet")
+			logrus.Fatalf("add '- \"%s\"' manually to the 'app' service in %s", label, composeFile)
+		}
 	}
 
 	return nil

pkg/config/app.go

@@ -1,18 +1,22 @@
 package config
 
 import (
-	"errors"
 	"fmt"
 	"io/ioutil"
 	"os"
 	"path"
+	"strconv"
 	"strings"
 
-	"coopcloud.tech/abra/cli/formatter"
+	"github.com/schollz/progressbar/v3"
-	"coopcloud.tech/abra/pkg/client/convert"
+
-	loader "coopcloud.tech/abra/pkg/client/stack"
+	"coopcloud.tech/abra/pkg/client"
-	stack "coopcloud.tech/abra/pkg/client/stack"
+	"coopcloud.tech/abra/pkg/formatter"
+	"coopcloud.tech/abra/pkg/upstream/convert"
+	loader "coopcloud.tech/abra/pkg/upstream/stack"
+	stack "coopcloud.tech/abra/pkg/upstream/stack"
 	composetypes "github.com/docker/cli/cli/compose/types"
+	"github.com/docker/docker/api/types/filters"
 	"github.com/sirupsen/logrus"
 )
 
@@ -21,6 +25,9 @@ import (
 // AppEnv is a map of the values in an apps env config
 type AppEnv = map[string]string
 
+// AppModifiers is a map of modifiers in an apps env config
+type AppModifiers = map[string]map[string]string
+
 // AppName is AppName
 type AppName = string
 
@@ -36,24 +43,75 @@ type AppFiles map[AppName]AppFile
 // App reprents an app with its env file read into memory
 type App struct {
 	Name   AppName
-	Type   string
+	Recipe string
 	Domain string
 	Env    AppEnv
 	Server string
 	Path   string
 }
 
-// StackName gets what the docker safe stack name is for the app
+// 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 (a App) StackName() string {
 	if _, exists := a.Env["STACK_NAME"]; exists {
 		return a.Env["STACK_NAME"]
 	}
+
 	stackName := SanitiseAppName(a.Name)
+
+	if len(stackName) > 45 {
+		logrus.Debugf("trimming %s to %s to avoid runtime limits", stackName, stackName[:45])
+		stackName = stackName[:45]
+	}
+
 	a.Env["STACK_NAME"] = stackName
+
 	return stackName
 }
 
-// SORTING TYPES
+// Filters retrieves exact app filters for querying the container runtime. 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) (filters.Args, error) {
+	filters := filters.NewArgs()
+
+	composeFiles, err := GetComposeFiles(a.Recipe, a.Env)
+	if err != nil {
+		return filters, err
+	}
+
+	opts := stack.Deploy{Composefiles: composeFiles}
+	compose, err := GetAppComposeConfig(a.Recipe, opts, a.Env)
+	if err != nil {
+		return filters, err
+	}
+
+	for _, service := range compose.Services {
+		var filter string
+
+		if appendServiceNames {
+			if exactMatch {
+				filter = fmt.Sprintf("^%s_%s", a.StackName(), service.Name)
+			} else {
+				filter = fmt.Sprintf("%s_%s", a.StackName(), service.Name)
+			}
+		} else {
+			if exactMatch {
+				filter = fmt.Sprintf("^%s", a.StackName())
+			} else {
+				filter = fmt.Sprintf("%s", a.StackName())
+			}
+		}
+
+		filters.Add("name", filter)
+	}
+
+	return filters, nil
+}
 
 // ByServer sort a slice of Apps
 type ByServer []App
@@ -64,25 +122,25 @@ func (a ByServer) Less(i, j int) bool {
 	return strings.ToLower(a[i].Server) < strings.ToLower(a[j].Server)
 }
 
-// ByServerAndType sort a slice of Apps
+// ByServerAndRecipe sort a slice of Apps
-type ByServerAndType []App
+type ByServerAndRecipe []App
 
-func (a ByServerAndType) Len() int      { return len(a) }
+func (a ByServerAndRecipe) Len() int      { return len(a) }
-func (a ByServerAndType) Swap(i, j int) { a[i], a[j] = a[j], a[i] }
+func (a ByServerAndRecipe) Swap(i, j int) { a[i], a[j] = a[j], a[i] }
-func (a ByServerAndType) Less(i, j int) bool {
+func (a ByServerAndRecipe) Less(i, j int) bool {
 	if a[i].Server == a[j].Server {
-		return strings.ToLower(a[i].Type) < strings.ToLower(a[j].Type)
+		return strings.ToLower(a[i].Recipe) < strings.ToLower(a[j].Recipe)
 	}
 	return strings.ToLower(a[i].Server) < strings.ToLower(a[j].Server)
 }
 
-// ByType sort a slice of Apps
+// ByRecipe sort a slice of Apps
-type ByType []App
+type ByRecipe []App
 
-func (a ByType) Len() int      { return len(a) }
+func (a ByRecipe) Len() int      { return len(a) }
-func (a ByType) Swap(i, j int) { a[i], a[j] = a[j], a[i] }
+func (a ByRecipe) Swap(i, j int) { a[i], a[j] = a[j], a[i] }
-func (a ByType) Less(i, j int) bool {
+func (a ByRecipe) Less(i, j int) bool {
-	return strings.ToLower(a[i].Type) < strings.ToLower(a[j].Type)
+	return strings.ToLower(a[i].Recipe) < strings.ToLower(a[j].Recipe)
 }
 
 // ByName sort a slice of Apps
@@ -94,85 +152,90 @@ 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) {
+func ReadAppEnvFile(appFile AppFile, name AppName) (App, error) {
 	env, err := ReadEnv(appFile.Path)
 	if err != nil {
-		return App{}, fmt.Errorf("env file for '%s' couldn't be read: %s", name, err.Error())
+		return App{}, fmt.Errorf("env file for %s couldn't be read: %s", name, err.Error())
 	}
 
-	logrus.Debugf("read env '%s' from '%s'", env, appFile.Path)
+	logrus.Debugf("read env %s from %s", env, appFile.Path)
 
-	app, err := newApp(env, name, appFile)
+	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{}, fmt.Errorf("env file for %s has issues: %s", name, err.Error())
 	}
 
 	return app, nil
 }
 
-// newApp creates new App object
+// NewApp creates new App object
-func newApp(env AppEnv, name string, appFile AppFile) (App, error) {
+func NewApp(env AppEnv, name string, appFile AppFile) (App, error) {
-	// Checking for type as it is required - apps wont work without it
 	domain := env["DOMAIN"]
-	apptype, ok := env["TYPE"]
+
-	if !ok {
+	recipe, exists := env["RECIPE"]
-		return App{}, errors.New("missing TYPE variable")
+	if !exists {
+		recipe, exists = env["TYPE"]
+		if !exists {
+			return App{}, fmt.Errorf("%s is missing the TYPE env var?", name)
+		}
 	}
 
 	return App{
 		Name:   name,
 		Domain: domain,
-		Type:   apptype,
+		Recipe: recipe,
 		Env:    env,
 		Server: appFile.Server,
 		Path:   appFile.Path,
 	}, nil
 }
 
-// LoadAppFiles gets all app files for a given set of servers or all servers
+// 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 = getAllFoldersInDirectory(ABRA_SERVER_FOLDER)
+			servers, err = GetAllFoldersInDirectory(SERVERS_DIR)
 			if err != nil {
-				return nil, err
+				return appFiles, err
 			}
 		}
 	}
 
-	logrus.Debugf("collecting metadata from '%v' servers: '%s'", len(servers), strings.Join(servers, ", "))
+	logrus.Debugf("collecting metadata from %v servers: %s", len(servers), strings.Join(servers, ", "))
 
 	for _, server := range servers {
-		serverDir := path.Join(ABRA_SERVER_FOLDER, server)
+		serverDir := path.Join(SERVERS_DIR, server)
-		files, err := getAllFilesInDirectory(serverDir)
+		files, err := GetAllFilesInDirectory(serverDir)
 		if err != nil {
-			return nil, err
+			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(ABRA_SERVER_FOLDER, server, file.Name())
+			appFilePath := path.Join(SERVERS_DIR, server, file.Name())
 			appFiles[appName] = AppFile{
 				Path:   appFilePath,
 				Server: server,
 			}
 		}
 	}
+
 	return appFiles, nil
 }
 
-// GetApp loads an apps settings, reading it from file, in preparation to use it
+// 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
-// ONLY use when ready to use the env file to keep IO down
+// 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)
+		return App{}, fmt.Errorf("cannot find app with name %s", name)
 	}
 
-	app, err := readAppEnvFile(appFile, name)
+	app, err := ReadAppEnvFile(appFile, name)
 	if err != nil {
 		return App{}, err
 	}
@@ -180,8 +243,9 @@ func GetApp(apps AppFiles, name AppName) (App, error) {
 	return app, nil
 }
 
-// GetApps returns a slice of Apps with their env files read from a given slice of AppFiles
+// GetApps returns a slice of Apps with their env files read from a given
-func GetApps(appFiles AppFiles) ([]App, error) {
+// slice of AppFiles.
+func GetApps(appFiles AppFiles, recipeFilter string) ([]App, error) {
 	var apps []App
 
 	for name := range appFiles {
@@ -189,8 +253,15 @@ func GetApps(appFiles AppFiles) ([]App, error) {
 		if err != nil {
 			return nil, err
 		}
+
+		if recipeFilter != "" {
+			if app.Recipe == recipeFilter {
 				apps = append(apps, app)
 			}
+		} else {
+			apps = append(apps, app)
+		}
+	}
 
 	return apps, nil
 }
@@ -209,13 +280,13 @@ func GetAppServiceNames(appName string) ([]string, error) {
 		return serviceNames, err
 	}
 
-	composeFiles, err := GetAppComposeFiles(app.Type, app.Env)
+	composeFiles, err := GetComposeFiles(app.Recipe, app.Env)
 	if err != nil {
 		return serviceNames, err
 	}
 
 	opts := stack.Deploy{Composefiles: composeFiles}
-	compose, err := GetAppComposeConfig(app.Type, opts, app.Env)
+	compose, err := GetAppComposeConfig(app.Recipe, opts, app.Env)
 	if err != nil {
 		return serviceNames, err
 	}
@@ -236,7 +307,7 @@ func GetAppNames() ([]string, error) {
 		return appNames, err
 	}
 
-	apps, err := GetApps(appFiles)
+	apps, err := GetApps(appFiles, "")
 	if err != nil {
 		return appNames, err
 	}
@@ -248,61 +319,85 @@ func GetAppNames() ([]string, error) {
 	return appNames, nil
 }
 
-// TemplateAppEnvSample copies the example env file for the app into the users env files
+// TemplateAppEnvSample copies the example env file for the app into the users
-func TemplateAppEnvSample(appType, appName, server, domain, recipe string) error {
+// env files.
-	envSamplePath := path.Join(ABRA_DIR, "apps", appType, ".env.sample")
+func TemplateAppEnvSample(recipeName, appName, server, domain string) error {
+	envSamplePath := path.Join(RECIPES_DIR, recipeName, ".env.sample")
 	envSample, err := ioutil.ReadFile(envSamplePath)
 	if err != nil {
 		return err
 	}
 
 	appEnvPath := path.Join(ABRA_DIR, "servers", server, fmt.Sprintf("%s.env", appName))
-	if _, err := os.Stat(appEnvPath); err == nil {
+	if _, err := os.Stat(appEnvPath); !os.IsNotExist(err) {
 		return fmt.Errorf("%s already exists?", appEnvPath)
 	}
 
-	envSample = []byte(strings.Replace(string(envSample), fmt.Sprintf("%s.example.com", recipe), domain, -1))
+	err = ioutil.WriteFile(appEnvPath, envSample, 0664)
-	envSample = []byte(strings.Replace(string(envSample), "example.com", domain, -1))
-
-	err = ioutil.WriteFile(appEnvPath, envSample, 0755)
 	if err != nil {
 		return err
 	}
 
-	logrus.Debugf("copied '%s' to '%s'", envSamplePath, appEnvPath)
+	read, err := ioutil.ReadFile(appEnvPath)
+	if err != nil {
+		return err
+	}
+
+	newContents := strings.Replace(string(read), recipeName+".example.com", domain, -1)
+
+	err = ioutil.WriteFile(appEnvPath, []byte(newContents), 0)
+	if err != nil {
+		return err
+	}
+
+	logrus.Debugf("copied & templated %s to %s", envSamplePath, appEnvPath)
 
 	return nil
 }
 
-// SanitiseAppName makes a app name usable with Docker by replacing illegal characters
+// 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
+// GetAppStatuses queries servers to check the deployment status of given apps.
-func GetAppStatuses(appFiles AppFiles) (map[string]map[string]string, error) {
+func GetAppStatuses(apps []App, MachineReadable bool) (map[string]map[string]string, error) {
 	statuses := make(map[string]map[string]string)
 
-	var unique []string
 	servers := make(map[string]struct{})
-	for _, appFile := range appFiles {
+	for _, app := range apps {
-		if _, ok := servers[appFile.Server]; !ok {
+		if _, ok := servers[app.Server]; !ok {
-			servers[appFile.Server] = struct{}{}
+			servers[app.Server] = struct{}{}
-			unique = append(unique, appFile.Server)
 		}
 	}
 
-	bar := formatter.CreateProgressbar(len(servers), "querying remote servers...")
+	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(s)
+			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]
@@ -311,13 +406,28 @@ func GetAppStatuses(appFiles AppFiles) (map[string]map[string]string, error) {
 				result["status"] = "deployed"
 			}
 
-			labelKey := fmt.Sprintf("coop-cloud.%s.version", name)
+			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 {
-				//FIXME: we only need to check containers with the version label not
-				//       every single container and then skip when we see no label perf gains
-				//       to be had here
 				continue
 			}
 
@@ -325,32 +435,62 @@ func GetAppStatuses(appFiles AppFiles) (map[string]map[string]string, error) {
 		}
 	}
 
-	logrus.Debugf("retrieved app statuses: '%s'", statuses)
+	logrus.Debugf("retrieved app statuses: %s", statuses)
 
 	return statuses, nil
 }
 
-// GetAppComposeFiles gets the list of compose files for an app which should be
+// ensurePathExists ensures that a path exists.
-// merged into a composetypes.Config while respecting the COMPOSE_FILE env var.
+func ensurePathExists(path string) error {
-func GetAppComposeFiles(recipe string, appEnv AppEnv) ([]string, error) {
+	if _, err := os.Stat(path); err != nil && os.IsNotExist(err) {
+		return err
+	}
+	return nil
+}
+
+// GetComposeFiles gets the list of compose files for an app (or recipe if you
+// don't already have an app) which should be merged into a composetypes.Config
+// while respecting the COMPOSE_FILE env var.
+func GetComposeFiles(recipe string, appEnv AppEnv) ([]string, error) {
 	var composeFiles []string
 
-	if _, ok := appEnv["COMPOSE_FILE"]; !ok {
+	composeFileEnvVar, ok := appEnv["COMPOSE_FILE"]
-		logrus.Debug("no COMPOSE_FILE detected, loading compose.yml")
+	if !ok {
-		path := fmt.Sprintf("%s/%s/compose.yml", APPS_DIR, recipe)
+		path := fmt.Sprintf("%s/%s/compose.yml", RECIPES_DIR, recipe)
+		if err := ensurePathExists(path); err != nil {
+			return composeFiles, err
+		}
+		logrus.Debugf("no COMPOSE_FILE detected, loading default: %s", path)
 		composeFiles = append(composeFiles, path)
 		return composeFiles, nil
 	}
 
-	composeFileEnvVar := appEnv["COMPOSE_FILE"]
+	if !strings.Contains(composeFileEnvVar, ":") {
-	envVars := strings.Split(composeFileEnvVar, ":")
+		path := fmt.Sprintf("%s/%s/%s", RECIPES_DIR, recipe, composeFileEnvVar)
-	logrus.Debugf("COMPOSE_FILE detected ('%s'), loading '%s'", composeFileEnvVar, strings.Join(envVars, ", "))
+		if err := ensurePathExists(path); err != nil {
-	for _, file := range strings.Split(composeFileEnvVar, ":") {
+			return composeFiles, err
-		path := fmt.Sprintf("%s/%s/%s", APPS_DIR, recipe, file)
+		}
+		logrus.Debugf("COMPOSE_FILE detected, loading %s", path)
+		composeFiles = append(composeFiles, path)
+		return composeFiles, nil
+	}
+
+	numComposeFiles := strings.Count(composeFileEnvVar, ":") + 1
+	envVars := strings.SplitN(composeFileEnvVar, ":", numComposeFiles)
+	if len(envVars) != numComposeFiles {
+		return composeFiles, fmt.Errorf("COMPOSE_FILE (=\"%s\") parsing failed?", composeFileEnvVar)
+	}
+
+	for _, file := range envVars {
+		path := fmt.Sprintf("%s/%s/%s", RECIPES_DIR, recipe, file)
+		if err := ensurePathExists(path); err != nil {
+			return composeFiles, err
+		}
 		composeFiles = append(composeFiles, path)
 	}
 
-	logrus.Debugf("retrieved '%s' configs for '%s'", strings.Join(composeFiles, ", "), recipe)
+	logrus.Debugf("COMPOSE_FILE detected (%s), loading %s", composeFileEnvVar, strings.Join(envVars, ", "))
+	logrus.Debugf("retrieved %s configs for %s", strings.Join(composeFiles, ", "), recipe)
 
 	return composeFiles, nil
 }
@@ -364,7 +504,102 @@ func GetAppComposeConfig(recipe string, opts stack.Deploy, appEnv AppEnv) (*comp
 		return &composetypes.Config{}, err
 	}
 
-	logrus.Debugf("retrieved '%s' for '%s'", compose.Filename, recipe)
+	logrus.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 AppEnv) {
+	for _, service := range compose.Services {
+		if service.Name == "app" {
+			logrus.Debugf("Add the following environment to the app service config of %s:", stackName)
+			for k, v := range appEnv {
+				_, exists := service.Environment[k]
+				if !exists {
+					value := v
+					service.Environment[k] = &value
+					logrus.Debugf("Add Key: %s Value: %s to %s", k, value, stackName)
+				}
+			}
+		}
+	}
+}
+
+// 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" {
+			logrus.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" {
+			logrus.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" {
+			logrus.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
+		}
+	}
+}
+
+// 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 AppEnv) {
+	for _, service := range compose.Services {
+		if service.Name == "app" {
+			enable_auto_update, exists := appEnv["ENABLE_AUTO_UPDATE"]
+			if !exists {
+				enable_auto_update = "false"
+			}
+			logrus.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)
+			logrus.Debugf("get label '%s'", labelKey)
+			if labelValue, ok := service.Deploy.Labels[labelKey]; ok {
+				return labelValue
+			}
+		}
+	}
+	logrus.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) {
+	var timeout = 50 // Default Timeout
+	var err error = nil
+	if timeoutLabel := GetLabel(compose, stackName, "timeout"); timeoutLabel != "" {
+		logrus.Debugf("timeout label: %s", timeoutLabel)
+		timeout, err = strconv.Atoi(timeoutLabel)
+	}
+	return timeout, err
+}

pkg/config/app_test.go

@@ -1,37 +1,108 @@
-package config
+package config_test
 
 import (
+	"fmt"
 	"reflect"
 	"testing"
+
+	"coopcloud.tech/abra/pkg/config"
+	"coopcloud.tech/abra/pkg/recipe"
+	"github.com/stretchr/testify/assert"
 )
 
 func TestNewApp(t *testing.T) {
-	app, err := newApp(expectedAppEnv, appName, expectedAppFile)
+	app, err := config.NewApp(ExpectedAppEnv, AppName, ExpectedAppFile)
 	if err != nil {
 		t.Fatal(err)
 	}
-	if !reflect.DeepEqual(app, expectedApp) {
+	if !reflect.DeepEqual(app, ExpectedApp) {
-		t.Fatalf("did not get expected app type. Expected: %s; Got: %s", app, expectedApp)
+		t.Fatalf("did not get expected app type. Expected: %s; Got: %s", app, ExpectedApp)
 	}
 }
 
 func TestReadAppEnvFile(t *testing.T) {
-	app, err := readAppEnvFile(expectedAppFile, appName)
+	app, err := config.ReadAppEnvFile(ExpectedAppFile, AppName)
 	if err != nil {
 		t.Fatal(err)
 	}
-	if !reflect.DeepEqual(app, expectedApp) {
+	if !reflect.DeepEqual(app, ExpectedApp) {
-		t.Fatalf("did not get expected app type. Expected: %s; Got: %s", app, expectedApp)
+		t.Fatalf("did not get expected app type. Expected: %s; Got: %s", app, ExpectedApp)
 	}
 }
 
 func TestGetApp(t *testing.T) {
-	// TODO: Test failures as well as successes
+	app, err := config.GetApp(ExpectedAppFiles, AppName)
-	app, err := GetApp(expectedAppFiles, appName)
 	if err != nil {
 		t.Fatal(err)
 	}
-	if !reflect.DeepEqual(app, expectedApp) {
+	if !reflect.DeepEqual(app, ExpectedApp) {
-		t.Fatalf("did not get expected app type. Expected: %s; Got: %s", app, expectedApp)
+		t.Fatalf("did not get expected app type. Expected: %s; Got: %s", app, ExpectedApp)
+	}
+}
+
+func TestGetComposeFiles(t *testing.T) {
+	offline := true
+	r, err := recipe.Get("abra-test-recipe", offline)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	tests := []struct {
+		appEnv       map[string]string
+		composeFiles []string
+	}{
+		{
+			map[string]string{},
+			[]string{
+				fmt.Sprintf("%s/%s/compose.yml", config.RECIPES_DIR, r.Name),
+			},
+		},
+		{
+			map[string]string{"COMPOSE_FILE": "compose.yml"},
+			[]string{
+				fmt.Sprintf("%s/%s/compose.yml", config.RECIPES_DIR, r.Name),
+			},
+		},
+		{
+			map[string]string{"COMPOSE_FILE": "compose.extra_secret.yml"},
+			[]string{
+				fmt.Sprintf("%s/%s/compose.extra_secret.yml", config.RECIPES_DIR, r.Name),
+			},
+		},
+		{
+			map[string]string{"COMPOSE_FILE": "compose.yml:compose.extra_secret.yml"},
+			[]string{
+				fmt.Sprintf("%s/%s/compose.yml", config.RECIPES_DIR, r.Name),
+				fmt.Sprintf("%s/%s/compose.extra_secret.yml", config.RECIPES_DIR, r.Name),
+			},
+		},
+	}
+
+	for _, test := range tests {
+		composeFiles, err := config.GetComposeFiles(r.Name, test.appEnv)
+		if err != nil {
+			t.Fatal(err)
+		}
+		assert.Equal(t, composeFiles, test.composeFiles)
+	}
+}
+
+func TestGetComposeFilesError(t *testing.T) {
+	offline := true
+	r, err := recipe.Get("abra-test-recipe", offline)
+	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 := config.GetComposeFiles(r.Name, test.appEnv)
+		if err == nil {
+			t.Fatalf("should have failed: %v", test.appEnv)
+		}
 	}
 }

pkg/config/env.go

@@ -8,61 +8,96 @@ import (
 	"os"
 	"path"
 	"path/filepath"
+	"regexp"
+	"sort"
 	"strings"
 
-	"github.com/Autonomic-Cooperative/godotenv"
+	"git.coopcloud.tech/coop-cloud/godotenv"
 	"github.com/sirupsen/logrus"
 )
 
-var ABRA_DIR = os.ExpandEnv("$HOME/.abra")
+// getBaseDir retrieves the Abra base directory.
-var ABRA_SERVER_FOLDER = path.Join(ABRA_DIR, "servers")
+func getBaseDir() string {
-var APPS_JSON = path.Join(ABRA_DIR, "apps.json")
+	home := os.ExpandEnv("$HOME/.abra")
-var APPS_DIR = path.Join(ABRA_DIR, "apps")
+	if customAbraDir, exists := os.LookupEnv("ABRA_DIR"); exists && customAbraDir != "" {
+		home = customAbraDir
+	}
+	return home
+}
+
+var ABRA_DIR = getBaseDir()
+var SERVERS_DIR = path.Join(ABRA_DIR, "servers")
+var RECIPES_DIR = path.Join(ABRA_DIR, "recipes")
+var VENDOR_DIR = path.Join(ABRA_DIR, "vendor")
+var BACKUP_DIR = path.Join(ABRA_DIR, "backups")
+var CATALOGUE_DIR = path.Join(ABRA_DIR, "catalogue")
+var RECIPES_JSON = path.Join(ABRA_DIR, "catalogue", "recipes.json")
 var REPOS_BASE_URL = "https://git.coopcloud.tech/coop-cloud"
+var CATALOGUE_JSON_REPO_NAME = "recipes-catalogue-json"
+var SSH_URL_TEMPLATE = "ssh://git@git.coopcloud.tech:2222/coop-cloud/%s.git"
+
+// envVarModifiers is a list of env var modifier strings. These are added to
+// env vars as comments and modify their processing by Abra, e.g. determining
+// how long secrets should be.
+var envVarModifiers = []string{"length"}
 
 // GetServers retrieves all servers.
 func GetServers() ([]string, error) {
 	var servers []string
 
-	servers, err := getAllFoldersInDirectory(ABRA_SERVER_FOLDER)
+	servers, err := GetAllFoldersInDirectory(SERVERS_DIR)
 	if err != nil {
 		return servers, err
 	}
 
-	logrus.Debugf("retrieved '%v' servers: '%s'", len(servers), servers)
+	logrus.Debugf("retrieved %v servers: %s", len(servers), servers)
 
 	return servers, nil
 }
 
 // ReadEnv loads an app envivornment into a map.
 func ReadEnv(filePath string) (AppEnv, error) {
-	var envFile AppEnv
+	var envVars AppEnv
 
-	envFile, err := godotenv.Read(filePath)
+	envVars, _, err := godotenv.Read(filePath)
 	if err != nil {
 		return nil, err
 	}
 
-	logrus.Debugf("read '%s' from '%s'", envFile, filePath)
+	logrus.Debugf("read %s from %s", envVars, filePath)
 
-	return envFile, nil
+	return envVars, nil
+}
+
+// ReadEnv loads an app envivornment and their modifiers in two different maps.
+func ReadEnvWithModifiers(filePath string) (AppEnv, AppModifiers, error) {
+	var envVars AppEnv
+
+	envVars, mods, err := godotenv.Read(filePath)
+	if err != nil {
+		return nil, mods, err
+	}
+
+	logrus.Debugf("read %s from %s", envVars, filePath)
+
+	return envVars, mods, nil
 }
 
 // ReadServerNames retrieves all server names.
 func ReadServerNames() ([]string, error) {
-	serverNames, err := getAllFoldersInDirectory(ABRA_SERVER_FOLDER)
+	serverNames, err := GetAllFoldersInDirectory(SERVERS_DIR)
 
 	if err != nil {
 		return nil, err
 	}
 
-	logrus.Debugf("read '%s' from '%s'", strings.Join(serverNames, ","), ABRA_SERVER_FOLDER)
+	logrus.Debugf("read %s from %s", strings.Join(serverNames, ","), SERVERS_DIR)
 
 	return serverNames, nil
 }
 
-// getAllFilesInDirectory returns filenames of all files in directory
+// GetAllFilesInDirectory returns filenames of all files in directory
-func getAllFilesInDirectory(directory string) ([]fs.FileInfo, error) {
+func GetAllFilesInDirectory(directory string) ([]fs.FileInfo, error) {
 	var realFiles []fs.FileInfo
 
 	files, err := ioutil.ReadDir(directory)
@@ -80,7 +115,7 @@ func getAllFilesInDirectory(directory string) ([]fs.FileInfo, error) {
 
 		realPath, err := filepath.EvalSymlinks(filePath)
 		if err != nil {
-			logrus.Warningf("broken symlink in your abra config folders: '%s'", filePath)
+			logrus.Warningf("broken symlink in your abra config folders: %s", filePath)
 		} else {
 			realFile, err := os.Stat(realPath)
 			if err != nil {
@@ -95,8 +130,8 @@ func getAllFilesInDirectory(directory string) ([]fs.FileInfo, error) {
 	return realFiles, nil
 }
 
-// getAllFoldersInDirectory returns both folder and symlink paths
+// GetAllFoldersInDirectory returns both folder and symlink paths
-func getAllFoldersInDirectory(directory string) ([]string, error) {
+func GetAllFoldersInDirectory(directory string) ([]string, error) {
 	var folders []string
 
 	files, err := ioutil.ReadDir(directory)
@@ -104,7 +139,7 @@ func getAllFoldersInDirectory(directory string) ([]string, error) {
 		return nil, err
 	}
 	if len(files) == 0 {
-		return nil, fmt.Errorf("directory is empty: '%s'", directory)
+		return nil, fmt.Errorf("directory is empty: %s", directory)
 	}
 
 	for _, file := range files {
@@ -113,7 +148,7 @@ func getAllFoldersInDirectory(directory string) ([]string, error) {
 			filePath := path.Join(directory, file.Name())
 			realDir, err := filepath.EvalSymlinks(filePath)
 			if err != nil {
-				logrus.Warningf("broken symlink in your abra config folders: '%s'", filePath)
+				logrus.Warningf("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())
@@ -124,17 +159,6 @@ func getAllFoldersInDirectory(directory string) ([]string, error) {
 	return folders, nil
 }
 
-// EnsureAbraDirExists checks for the abra config folder and throws error if not
-func EnsureAbraDirExists() error {
-	if _, err := os.Stat(ABRA_DIR); os.IsNotExist(err) {
-		logrus.Debugf("'%s' does not exist, creating it", ABRA_DIR)
-		if err := os.Mkdir(ABRA_DIR, 0777); err != nil {
-			return err
-		}
-	}
-	return nil
-}
-
 // ReadAbraShEnvVars reads env vars from an abra.sh recipe file.
 func ReadAbraShEnvVars(abraSh string) (map[string]string, error) {
 	envVars := make(map[string]string)
@@ -146,22 +170,107 @@ func ReadAbraShEnvVars(abraSh string) (map[string]string, error) {
 		}
 		return envVars, err
 	}
+	defer file.Close()
+
+	exportRegex, err := regexp.Compile(`^export\s+(\w+=\w+)`)
+	if err != nil {
+		return envVars, err
+	}
 
 	scanner := bufio.NewScanner(file)
 	for scanner.Scan() {
-		line := scanner.Text()
+		txt := scanner.Text()
-		if strings.Contains(line, "export") {
+		if exportRegex.MatchString(txt) {
-			splitVals := strings.Split(line, "export ")
+			splitVals := strings.Split(txt, "export ")
 			envVarDef := splitVals[len(splitVals)-1]
 			keyVal := strings.Split(envVarDef, "=")
 			if len(keyVal) != 2 {
-				return envVars, fmt.Errorf("couldn't parse %s", line)
+				return envVars, fmt.Errorf("couldn't parse %s", txt)
 			}
 			envVars[keyVal[0]] = keyVal[1]
 		}
 	}
 
-	logrus.Debugf("read '%s' from '%s'", envVars, abraSh)
+	if len(envVars) > 0 {
+		logrus.Debugf("read %s from %s", envVars, abraSh)
+	} else {
+		logrus.Debugf("read 0 env var exports from %s", abraSh)
+	}
 
 	return envVars, nil
 }
+
+type EnvVar struct {
+	Name    string
+	Present bool
+}
+
+func CheckEnv(app App) ([]EnvVar, error) {
+	var envVars []EnvVar
+
+	envSamplePath := path.Join(RECIPES_DIR, app.Recipe, ".env.sample")
+	if _, err := os.Stat(envSamplePath); err != nil {
+		if os.IsNotExist(err) {
+			return envVars, fmt.Errorf("%s does not exist?", envSamplePath)
+		}
+		return envVars, err
+	}
+
+	envSample, err := ReadEnv(envSamplePath)
+	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, EnvVar{Name: key, Present: true})
+		} else {
+			envVars = append(envVars, 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 {
+		logrus.Debugf("read %s from %s", strings.Join(cmdNames, " "), abraSh)
+	} else {
+		logrus.Debugf("read 0 command names from %s", abraSh)
+	}
+
+	return cmdNames, nil
+}

pkg/config/env_test.go

@@ -1,60 +1,69 @@
-package config
+package config_test
 
 import (
+	"fmt"
 	"os"
 	"path"
 	"reflect"
+	"slices"
 	"strings"
 	"testing"
+
+	"coopcloud.tech/abra/pkg/config"
+	"coopcloud.tech/abra/pkg/recipe"
 )
 
-var testFolder = os.ExpandEnv("$PWD/../../tests/resources/test_folder")
+var (
-var validAbraConf = os.ExpandEnv("$PWD/../../tests/resources/valid_abra_config")
+	TestFolder    = os.ExpandEnv("$PWD/../../tests/resources/test_folder")
+	ValidAbraConf = os.ExpandEnv("$PWD/../../tests/resources/valid_abra_config")
+)
 
 // make sure these are in alphabetical order
-var tFolders = []string{"folder1", "folder2"}
+var (
-var tFiles = []string{"bar.env", "foo.env"}
+	TFolders = []string{"folder1", "folder2"}
+	TFiles   = []string{"bar.env", "foo.env"}
+)
 
-var appName = "ecloud"
+var (
-var serverName = "evil.corp"
+	AppName    = "ecloud"
+	ServerName = "evil.corp"
+)
 
-var expectedAppEnv = AppEnv{
+var ExpectedAppEnv = config.AppEnv{
 	"DOMAIN": "ecloud.evil.corp",
-	"TYPE":   "ecloud",
+	"RECIPE": "ecloud",
 }
 
-var expectedApp = App{
+var ExpectedApp = config.App{
-	Name:   appName,
+	Name:   AppName,
-	Type:   expectedAppEnv["TYPE"],
+	Recipe: ExpectedAppEnv["RECIPE"],
-	Domain: expectedAppEnv["DOMAIN"],
+	Domain: ExpectedAppEnv["DOMAIN"],
-	Env:    expectedAppEnv,
+	Env:    ExpectedAppEnv,
-	Path:   expectedAppFile.Path,
+	Path:   ExpectedAppFile.Path,
-	Server: expectedAppFile.Server,
+	Server: ExpectedAppFile.Server,
 }
 
-var expectedAppFile = AppFile{
+var ExpectedAppFile = config.AppFile{
-	Path:   path.Join(validAbraConf, "servers", serverName, appName+".env"),
+	Path:   path.Join(ValidAbraConf, "servers", ServerName, AppName+".env"),
-	Server: serverName,
+	Server: ServerName,
 }
 
-var expectedAppFiles = map[string]AppFile{
+var ExpectedAppFiles = map[string]config.AppFile{
-	appName: expectedAppFile,
+	AppName: ExpectedAppFile,
 }
 
-// var expectedServerNames = []string{"evil.corp"}
-
 func TestGetAllFoldersInDirectory(t *testing.T) {
-	folders, err := getAllFoldersInDirectory(testFolder)
+	folders, err := config.GetAllFoldersInDirectory(TestFolder)
 	if err != nil {
 		t.Fatal(err)
 	}
-	if !reflect.DeepEqual(folders, tFolders) {
+	if !reflect.DeepEqual(folders, TFolders) {
-		t.Fatalf("did not get expected folders. Expected: (%s), Got: (%s)", strings.Join(tFolders, ","), strings.Join(folders, ","))
+		t.Fatalf("did not get expected folders. Expected: (%s), Got: (%s)", strings.Join(TFolders, ","), strings.Join(folders, ","))
 	}
 }
 
 func TestGetAllFilesInDirectory(t *testing.T) {
-	files, err := getAllFilesInDirectory(testFolder)
+	files, err := config.GetAllFilesInDirectory(TestFolder)
 	if err != nil {
 		t.Fatal(err)
 	}
@@ -62,23 +71,205 @@ func TestGetAllFilesInDirectory(t *testing.T) {
 	for _, file := range files {
 		fileNames = append(fileNames, file.Name())
 	}
-	if !reflect.DeepEqual(fileNames, tFiles) {
+	if !reflect.DeepEqual(fileNames, TFiles) {
-		t.Fatalf("did not get expected files. Expected: (%s), Got: (%s)", strings.Join(tFiles, ","), strings.Join(fileNames, ","))
+		t.Fatalf("did not get expected files. Expected: (%s), Got: (%s)", strings.Join(TFiles, ","), strings.Join(fileNames, ","))
 	}
 }
 
 func TestReadEnv(t *testing.T) {
-	env, err := ReadEnv(expectedAppFile.Path)
+	env, err := config.ReadEnv(ExpectedAppFile.Path)
 	if err != nil {
 		t.Fatal(err)
 	}
-	if !reflect.DeepEqual(env, expectedAppEnv) {
+	if !reflect.DeepEqual(env, ExpectedAppEnv) {
 		t.Fatalf(
-			"did not get expected application settings. Expected: DOMAIN=%s TYPE=%s; Got: DOMAIN=%s TYPE=%s",
+			"did not get expected application settings. Expected: DOMAIN=%s RECIPE=%s; Got: DOMAIN=%s RECIPE=%s",
-			expectedAppEnv["DOMAIN"],
+			ExpectedAppEnv["DOMAIN"],
-			expectedAppEnv["TYPE"],
+			ExpectedAppEnv["RECIPE"],
 			env["DOMAIN"],
-			env["TYPE"],
+			env["RECIPE"],
 		)
 	}
 }
+
+func TestReadAbraShEnvVars(t *testing.T) {
+	offline := true
+	r, err := recipe.Get("abra-test-recipe", offline)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	abraShPath := fmt.Sprintf("%s/%s/%s", config.RECIPES_DIR, r.Name, "abra.sh")
+	abraShEnv, err := config.ReadAbraShEnvVars(abraShPath)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	if len(abraShEnv) == 0 {
+		t.Error("at least one env var should be exported")
+	}
+
+	if _, ok := abraShEnv["INNER_FOO"]; ok {
+		t.Error("INNER_FOO should not be exported")
+	}
+
+	if _, ok := abraShEnv["INNER_BAZ"]; ok {
+		t.Error("INNER_BAZ should not be exported")
+	}
+
+	if _, ok := abraShEnv["OUTER_FOO"]; !ok {
+		t.Error("OUTER_FOO should be exported")
+	}
+}
+
+func TestReadAbraShCmdNames(t *testing.T) {
+	offline := true
+	r, err := recipe.Get("abra-test-recipe", offline)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	abraShPath := fmt.Sprintf("%s/%s/%s", config.RECIPES_DIR, r.Name, "abra.sh")
+	cmdNames, err := config.ReadAbraShCmdNames(abraShPath)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	if len(cmdNames) == 0 {
+		t.Error("at least one command name should be found")
+	}
+
+	expectedCmdNames := []string{"test_cmd", "test_cmd_args"}
+	for _, cmdName := range expectedCmdNames {
+		if !slices.Contains(cmdNames, cmdName) {
+			t.Fatalf("%s should have been found in %s", cmdName, abraShPath)
+		}
+	}
+}
+
+func TestCheckEnv(t *testing.T) {
+	offline := true
+	r, err := recipe.Get("abra-test-recipe", offline)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	envSamplePath := path.Join(config.RECIPES_DIR, r.Name, ".env.sample")
+	envSample, err := config.ReadEnv(envSamplePath)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	app := config.App{
+		Name:   "test-app",
+		Recipe: r.Name,
+		Domain: "example.com",
+		Env:    envSample,
+		Path:   "example.com.env",
+		Server: "example.com",
+	}
+
+	envVars, err := config.CheckEnv(app)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	for _, envVar := range envVars {
+		if !envVar.Present {
+			t.Fatalf("%s should be present", envVar.Name)
+		}
+	}
+}
+
+func TestCheckEnvError(t *testing.T) {
+	offline := true
+	r, err := recipe.Get("abra-test-recipe", offline)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	envSamplePath := path.Join(config.RECIPES_DIR, r.Name, ".env.sample")
+	envSample, err := config.ReadEnv(envSamplePath)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	delete(envSample, "DOMAIN")
+
+	app := config.App{
+		Name:   "test-app",
+		Recipe: r.Name,
+		Domain: "example.com",
+		Env:    envSample,
+		Path:   "example.com.env",
+		Server: "example.com",
+	}
+
+	envVars, err := config.CheckEnv(app)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	for _, envVar := range envVars {
+		if envVar.Name == "DOMAIN" && envVar.Present {
+			t.Fatalf("%s should not be present", envVar.Name)
+		}
+	}
+}
+
+func TestEnvVarCommentsRemoved(t *testing.T) {
+	offline := true
+	r, err := recipe.Get("abra-test-recipe", offline)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	envSamplePath := path.Join(config.RECIPES_DIR, r.Name, ".env.sample")
+	envSample, err := config.ReadEnv(envSamplePath)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	envVar, exists := envSample["WITH_COMMENT"]
+	if !exists {
+		t.Fatal("WITH_COMMENT env var should be present in .env.sample")
+	}
+
+	if strings.Contains(envVar, "should be removed") {
+		t.Fatalf("comment from '%s' should be removed", envVar)
+	}
+
+	envVar, exists = envSample["SECRET_TEST_PASS_TWO_VERSION"]
+	if !exists {
+		t.Fatal("WITH_COMMENT env var should be present in .env.sample")
+	}
+
+	if strings.Contains(envVar, "length") {
+		t.Fatal("comment from env var SECRET_TEST_PASS_TWO_VERSION should have been removed")
+	}
+}
+
+func TestEnvVarModifiersIncluded(t *testing.T) {
+	offline := true
+	r, err := recipe.Get("abra-test-recipe", offline)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	envSamplePath := path.Join(config.RECIPES_DIR, r.Name, ".env.sample")
+	envSample, modifiers, err := config.ReadEnvWithModifiers(envSamplePath)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	if !strings.Contains(envSample["SECRET_TEST_PASS_TWO_VERSION"], "v1") {
+		t.Errorf("value should be 'v1', got: '%s'", envSample["SECRET_TEST_PASS_TWO_VERSION"])
+	}
+	if modifiers == nil || modifiers["SECRET_TEST_PASS_TWO_VERSION"] == nil {
+		t.Errorf("no modifiers included")
+	} else {
+		if modifiers["SECRET_TEST_PASS_TWO_VERSION"]["length"] != "10" {
+			t.Errorf("length modifier should be '10', got: '%s'", modifiers["SECRET_TEST_PASS_TWO_VERSION"]["length"])
+		}
+	}
+}

pkg/container/container.go

@@ -0,0 +1,70 @@
+package container
+
+import (
+	"context"
+	"fmt"
+	"strings"
+
+	"coopcloud.tech/abra/pkg/formatter"
+	"github.com/AlecAivazis/survey/v2"
+	"github.com/docker/docker/api/types"
+	"github.com/docker/docker/api/types/filters"
+	"github.com/docker/docker/client"
+	"github.com/sirupsen/logrus"
+)
+
+// 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 := types.ContainerListOptions{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
+		}
+
+		logrus.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
+			}
+		}
+
+		logrus.Panic("failed to match chosen container")
+	}
+
+	return containers[0], nil
+}

pkg/context/context.go

@@ -0,0 +1,41 @@
+package context
+
+import (
+	"errors"
+
+	"github.com/docker/cli/cli/command"
+	dConfig "github.com/docker/cli/cli/config"
+	"github.com/docker/cli/cli/context"
+	contextStore "github.com/docker/cli/cli/context/store"
+	cliflags "github.com/docker/cli/cli/flags"
+)
+
+func NewDefaultDockerContextStore() *command.ContextStoreWithDefault {
+	contextDir := dConfig.ContextStoreDir()
+	storeConfig := command.DefaultContextStoreConfig()
+	store := newContextStore(contextDir, storeConfig)
+
+	opts := &cliflags.ClientOptions{Context: "default"}
+
+	dockerContextStore := &command.ContextStoreWithDefault{
+		Store: store,
+		Resolver: func() (*command.DefaultContext, error) {
+			return command.ResolveDefaultContext(opts, storeConfig)
+		},
+	}
+
+	return dockerContextStore
+}
+
+func GetContextEndpoint(ctx contextStore.Metadata) (string, error) {
+	endpointmeta, ok := ctx.Endpoints["docker"].(context.EndpointMetaBase)
+	if !ok {
+		err := errors.New("context lacks Docker endpoint")
+		return "", err
+	}
+	return endpointmeta.Host, nil
+}
+
+func newContextStore(dir string, config contextStore.Config) contextStore.Store {
+	return contextStore.New(dir, config)
+}

pkg/dns/dns.go

@@ -0,0 +1,55 @@
+package dns
+
+import (
+	"fmt"
+	"net"
+)
+
+// EnsureIPv4 ensures that an ipv4 address is set for a domain name
+func EnsureIPv4(domainName string) (string, error) {
+	ipv4, err := net.ResolveIPAddr("ip4", domainName)
+	if err != nil {
+		return "", err
+	}
+
+	// NOTE(d1): e.g. when there is only an ipv6 record available
+	if ipv4 == nil {
+		return "", fmt.Errorf("unable to resolve ipv4 address for %s", domainName)
+	}
+
+	return ipv4.String(), nil
+}
+
+// EnsureDomainsResolveSameIPv4 ensures that domains resolve to the same ipv4 address
+func EnsureDomainsResolveSameIPv4(domainName, server string) (string, error) {
+	if server == "default" || server == "local" {
+		return "", nil
+	}
+
+	var ipv4 string
+
+	domainIPv4, err := EnsureIPv4(domainName)
+	if err != nil {
+		return ipv4, err
+	}
+
+	if domainIPv4 == "" {
+		return ipv4, fmt.Errorf("cannot resolve ipv4 for %s?", domainName)
+	}
+
+	serverIPv4, err := EnsureIPv4(server)
+	if err != nil {
+		return ipv4, err
+	}
+
+	if serverIPv4 == "" {
+		return ipv4, fmt.Errorf("cannot resolve ipv4 for %s?", server)
+	}
+
+	if domainIPv4 != serverIPv4 {
+		err := "app domain %s (%s) does not appear to resolve to app server %s (%s)?"
+		return ipv4, fmt.Errorf(err, domainName, domainIPv4, server, serverIPv4)
+	}
+
+	return ipv4, nil
+}

pkg/dns/dns_test.go

@@ -0,0 +1,64 @@
+package dns
+
+import (
+	"fmt"
+	"testing"
+
+	"gotest.tools/v3/assert"
+)
+
+func TestEnsureDomainsResolveSameIPv4(t *testing.T) {
+	tests := []struct {
+		domainName     string
+		serverName     string
+		shouldValidate bool
+	}{
+		// NOTE(d1): DNS records get checked, so use something that is maintained
+		// within the federation. if you're here because of a failing test, try
+		// `dig +short <domain>` to ensure stuff matches first! If flakyness
+		// becomes an issue we can look into mocking
+		{"docs.coopcloud.tech", "coopcloud.tech", true},
+		{"docs.coopcloud.tech", "swarm.autonomic.zone", true},
+
+		// NOTE(d1): special case handling for "--local"
+		{"", "default", true},
+		{"", "local", true},
+
+		{"", "", false},
+		{"123", "", false},
+	}
+
+	for _, test := range tests {
+		_, err := EnsureDomainsResolveSameIPv4(test.domainName, test.serverName)
+		if err != nil && test.shouldValidate {
+			t.Fatal(err)
+		}
+
+		if err == nil && !test.shouldValidate {
+			t.Fatal(fmt.Errorf("should have failed but did not: %v", test))
+		}
+	}
+}
+
+func TestEnsureIpv4(t *testing.T) {
+	// NOTE(d1): DNS records get checked, so use something that is maintained
+	// within the federation. if you're here because of a failing test, try `dig
+	// +short <domain>` to ensure stuff matches first! If flakyness becomes an
+	// issue we can look into mocking
+	domainName := "collabora.ostrom.collective.tools"
+	serverName := "ostrom.collective.tools"
+
+	for i := 0; i < 15; i++ {
+		domainIpv4, err := EnsureIPv4(domainName)
+		if err != nil {
+			t.Fatal(err)
+		}
+
+		serverIpv4, err := EnsureIPv4(serverName)
+		if err != nil {
+			t.Fatal(err)
+		}
+
+		assert.Equal(t, domainIpv4, serverIpv4)
+	}
+}

pkg/formatter/formatter.go

@@ -0,0 +1,91 @@
+package formatter
+
+import (
+	"fmt"
+	"os"
+	"strings"
+	"time"
+
+	"github.com/docker/go-units"
+	// "github.com/olekukonko/tablewriter"
+	"coopcloud.tech/abra/pkg/jsontable"
+	"github.com/schollz/progressbar/v3"
+	"github.com/sirupsen/logrus"
+)
+
+func ShortenID(str string) string {
+	return str[:12]
+}
+
+func SmallSHA(hash string) string {
+	return hash[:8]
+}
+
+// RemoveSha remove image sha from a string that are added in some docker outputs
+func RemoveSha(str string) string {
+	return strings.Split(str, "@")[0]
+}
+
+// HumanDuration from docker/cli RunningFor() to be accessible outside of the class
+func HumanDuration(timestamp int64) string {
+	date := time.Unix(timestamp, 0)
+	now := time.Now().UTC()
+	return units.HumanDuration(now.Sub(date)) + " ago"
+}
+
+// CreateTable prepares a table layout for output.
+func CreateTable(columns []string) *jsontable.JSONTable {
+	table := jsontable.NewJSONTable(os.Stdout)
+	table.SetAutoWrapText(false)
+	table.SetHeader(columns)
+	return table
+}
+
+// CreateProgressbar generates a progress bar
+func CreateProgressbar(length int, title string) *progressbar.ProgressBar {
+	return progressbar.NewOptions(
+		length,
+		progressbar.OptionClearOnFinish(),
+		progressbar.OptionSetPredictTime(false),
+		progressbar.OptionShowCount(),
+		progressbar.OptionFullWidth(),
+		progressbar.OptionSetDescription(title),
+	)
+}
+
+// StripTagMeta strips front-matter image tag data that we don't need for parsing.
+func StripTagMeta(image string) string {
+	originalImage := image
+
+	if strings.Contains(image, "docker.io") {
+		image = strings.Split(image, "/")[1]
+	}
+
+	if strings.Contains(image, "library") {
+		image = strings.Split(image, "/")[1]
+	}
+
+	if originalImage != image {
+		logrus.Debugf("stripped %s to %s for parsing", originalImage, image)
+	}
+
+	return image
+}
+
+// ByteCountSI presents a human friendly representation of a byte count. See
+// https://yourbasic.org/golang/formatting-byte-size-to-human-readable-format.
+func ByteCountSI(b uint64) string {
+	const unit = 1000
+
+	if b < unit {
+		return fmt.Sprintf("%d B", b)
+	}
+
+	div, exp := uint64(unit), 0
+	for n := b / unit; n >= unit; n /= unit {
+		div *= unit
+		exp++
+	}
+
+	return fmt.Sprintf("%.1f %cB", float64(b)/float64(div), "kMGTPE"[exp])
+}

pkg/git/branch.go

@@ -0,0 +1,100 @@
+package git
+
+import (
+	"fmt"
+
+	"github.com/go-git/go-git/v5"
+	"github.com/go-git/go-git/v5/plumbing"
+	"github.com/sirupsen/logrus"
+)
+
+// Check if a branch exists in a repo. Use this and not repository.Branch(),
+// because the latter does not actually check for existing branches. See
+// https://github.com/gogit/gogit/issues/518 for more.
+func HasBranch(repository *git.Repository, name string) bool {
+	var exist bool
+
+	if iter, err := repository.Branches(); err == nil {
+		iterFunc := func(reference *plumbing.Reference) error {
+			if name == reference.Name().Short() {
+				exist = true
+				return nil
+			}
+			return nil
+		}
+		_ = iter.ForEach(iterFunc)
+	}
+
+	return exist
+}
+
+// GetCurrentBranch retrieves the current branch of a repository.
+func GetCurrentBranch(repository *git.Repository) (string, error) {
+	branchRefs, err := repository.Branches()
+	if err != nil {
+		return "", err
+	}
+
+	headRef, err := repository.Head()
+	if err != nil {
+		return "", err
+	}
+
+	var currentBranchName string
+	err = branchRefs.ForEach(func(branchRef *plumbing.Reference) error {
+		if branchRef.Hash() == headRef.Hash() {
+			currentBranchName = branchRef.Name().String()
+
+			return nil
+		}
+
+		return nil
+	})
+	if err != nil {
+		return "", err
+	}
+
+	return currentBranchName, nil
+}
+
+// GetDefaultBranch retrieves the default branch of a repository.
+func GetDefaultBranch(repo *git.Repository, repoPath string) (plumbing.ReferenceName, error) {
+	branch := "master"
+
+	if !HasBranch(repo, "master") {
+		if !HasBranch(repo, "main") {
+			return "", fmt.Errorf("failed to select default branch in %s", repoPath)
+		}
+		branch = "main"
+	}
+
+	return plumbing.ReferenceName(fmt.Sprintf("refs/heads/%s", branch)), nil
+}
+
+// CheckoutDefaultBranch checks out the default branch of a repository.
+func CheckoutDefaultBranch(repo *git.Repository, repoPath string) (plumbing.ReferenceName, error) {
+	branch, err := GetDefaultBranch(repo, repoPath)
+	if err != nil {
+		return plumbing.ReferenceName(""), err
+	}
+
+	worktree, err := repo.Worktree()
+	if err != nil {
+		return plumbing.ReferenceName(""), err
+	}
+
+	checkOutOpts := &git.CheckoutOptions{
+		Create: false,
+		Force:  true,
+		Branch: branch,
+	}
+
+	if err := worktree.Checkout(checkOutOpts); err != nil {
+		logrus.Debugf("failed to check out %s in %s", branch, repoPath)
+		return branch, err
+	}
+
+	logrus.Debugf("successfully checked out %v in %s", branch, repoPath)
+
+	return branch, nil
+}

pkg/git/clone.go

@@ -3,10 +3,10 @@ package git
 import (
 	"fmt"
 	"os"
+	"path/filepath"
 	"strings"
 
 	"github.com/go-git/go-git/v5"
-	"github.com/go-git/go-git/v5/config"
 	"github.com/go-git/go-git/v5/plumbing"
 	"github.com/sirupsen/logrus"
 )
@@ -14,81 +14,37 @@ import (
 // Clone runs a git clone which accounts for different default branches.
 func Clone(dir, url string) error {
 	if _, err := os.Stat(dir); os.IsNotExist(err) {
-		logrus.Debugf("'%s' does not exist, attempting to git clone from '%s'", dir, url)
+		logrus.Debugf("%s does not exist, attempting to git clone from %s", dir, url)
-		_, err := git.PlainClone(dir, false, &git.CloneOptions{URL: url, Tags: git.AllTags})
+
+		_, err := git.PlainClone(dir, false, &git.CloneOptions{
+			URL:           url,
+			Tags:          git.AllTags,
+			ReferenceName: plumbing.ReferenceName("refs/heads/master"),
+			SingleBranch:  true,
+		})
 		if err != nil {
-			logrus.Debugf("cloning '%s' default branch failed, attempting from main branch", url)
+			logrus.Debugf("cloning %s default branch failed, attempting from main branch", url)
+
 			_, err := git.PlainClone(dir, false, &git.CloneOptions{
 				URL:           url,
 				Tags:          git.AllTags,
 				ReferenceName: plumbing.ReferenceName("refs/heads/main"),
+				SingleBranch:  true,
 			})
 			if err != nil {
+				if strings.Contains(err.Error(), "authentication required") {
+					name := filepath.Base(dir)
+					return fmt.Errorf("unable to clone %s, does %s exist?", name, url)
+				}
+
 				return err
 			}
 		}
-		logrus.Debugf("'%s' has been git cloned successfully", dir)
+
+		logrus.Debugf("%s has been git cloned successfully", dir)
 	} else {
-		logrus.Debugf("'%s' already exists, doing nothing", dir)
+		logrus.Debugf("%s already exists", dir)
 	}
 
 	return nil
 }
-
-// EnsureUpToDate ensures that a git repo on disk has the latest changes (git-fetch).
-func EnsureUpToDate(dir string) error {
-	repo, err := git.PlainOpen(dir)
-	if err != nil {
-		return err
-	}
-
-	branch := "master"
-	if _, err := repo.Branch("master"); err != nil {
-		if _, err := repo.Branch("main"); err != nil {
-			logrus.Debugf("failed to select branch in '%s'", dir)
-			return err
-		}
-		branch = "main"
-	}
-
-	logrus.Debugf("choosing '%s' as main git branch in '%s'", branch, dir)
-
-	worktree, err := repo.Worktree()
-	if err != nil {
-		return err
-	}
-
-	refName := fmt.Sprintf("refs/heads/%s", branch)
-	checkOutOpts := &git.CheckoutOptions{
-		Create: false,
-		Force:  true,
-		Keep:   false,
-		Branch: plumbing.ReferenceName(refName),
-	}
-	if err := worktree.Checkout(checkOutOpts); err != nil {
-		logrus.Debugf("failed to check out '%s' in '%s'", refName, dir)
-		return err
-	}
-
-	logrus.Debugf("successfully checked out '%s' in '%s'", branch, dir)
-
-	remote, err := repo.Remote("origin")
-	if err != nil {
-		return err
-	}
-
-	fetchOpts := &git.FetchOptions{
-		RemoteName: "origin",
-		RefSpecs:   []config.RefSpec{"refs/heads/*:refs/remotes/origin/*"},
-		Force:      true,
-	}
-	if err := remote.Fetch(fetchOpts); err != nil {
-		if !strings.Contains(err.Error(), "already up-to-date") {
-			return err
-		}
-	}
-
-	logrus.Debugf("successfully fetched all changes in '%s'", dir)
-
-	return nil
-}