docs.coopcloud.tech/docs/abra/upgrade.md

title

title
Upgrade

Release channels

Stable

abra upgrade

Release candidate

abra upgrade --rc

Manually

You can also download a release manually. Go to the releases page, download the release file, confirm the checksum and untar it.

For example, for release candidate 0.10.0-rc1-beta and linux_amd64. Download the release file.

wget https://git.coopcloud.tech/toolshed/abra/releases/download/0.10.0-rc1-beta/abra_0.10.0-rc1-beta_linux_amd64.tar.gz

Confirm the checksum.

wget https://git.coopcloud.tech/toolshed/abra/releases/download/0.10.0-rc1-beta/checksums.txt
cat checksums.txt
sha256sum abra_0.10.0-rc1-beta_linux_amd64.tar.gz

Untar the release.

tar -xvf abra_0.10.0-rc1-beta_linux_amd64.tar.gz

And test things work.

./abra -v

Migration guides

General release notes are here

0.10.x-beta -> WIP

• We now ensure that $ABRA_DIR/servers has stricter permissions (0600). See #592 for more.

0.9.x-beta -> 0.10.x-beta

• abra will now write the app deployment version to the app env file ($ABRA_DIR/servers/<server>/<domain>.env) against the TYPE=/RECIPE= env var. This has a number of implications which are detailed in the release announcement post. The current v0.9.x series of abra will not be able to parse this version. So, if you're testing the release candidate, you might to clean up your .env files afterwards.

• We have finally migrated from urfave/cli to spf13/cobra as our command-line handling library. This means we should (hopefully!) not have to deal with so many command-line breaking changes in the future, e.g. how -- is handled, how flags/args are parsed and so on. We expect to maintain compatibility across this migration, however you might run into something we didn't expect. Please do let us know.

• spf13/cobra does not support "shorthand" flags with multiple characters. So, the shorthard flags for --git-name / --git-email on abra recipe new are now -N / -e respectively.

• Auto-completion for abra is handled differently now. See abra autocomplete --help for more. The full help output is available for each specific shell, e.g. abra autocomplete zsh --help. It is now generated on the fly. WARNING: you'll need to REMOVE your pre v0.10.x abra auto-complete config for the new auto-complete to work. Check your $SHELL configuration file (e.g. .zshrc for Zsh). See #553 for more.

• Several commands now make use of the --chaos/-C commands, such as abra app ps and abra app cp. See --help for more.

• + unstaged changes is shown as +U in the overviews. This change was made to support more compact display layouts. This marker will always be shown in bold (+U) as a visual aid.

• abra will no longer attempt to parse your ~/.ssh/config. This means that whatever you configure in your ~/.ssh/config is the source of truth and abra does not try to guess connection details. abra now only invokes /usr/bin/ssh. This also means that --problems/-p goes away on abra server list.

• abra app backup / abra app restore now officially use backup-bot-two! We are still discussing how to handle this transition wrt. the original backup-bot. Please see this ticket for more.

• --no-domain-checks has been removed from abra server add. See #631 for more.

• The output of abra app ps is less redundant in order to 1) reduce how much horizontal width is required to render the table and 2) simplify the amount of information shown. The -w option was also retired, you can use the standard watch command, e.g. watch abra app ps ... to get the same functionality.

• Several overview screens have changed their layout. E.g. abra app deploy now shows more (hopefully!) useful information. These changes have been made to accomodate the work done around operator collaboration and stable versioning.

• abra app deploy / upgrade / rollback / etc. now show the deployment progress, retry attempts and the healthcheck status.

• Failed deployments will write output logs to file in ~/$ABRA_DIR/logs.

• abra app errors went away. It never really worked and was retired. You can rely on abra app logs for the time being.

• It's not possible to --chaos/-C on upgrade / rollback. See #559 for more.

• main will be chosen for new repositories created by abra. abra will also attempt to clone the main branch first instead of the master branch. The master branch is tried afterwards. This is mainly due to the fact that the majority of our recipes use the main branch.

• abra recipe fetch now accepts an --all flag to fetch all repositories.

• It's now possible to set the character charset for a password. See #521 for more.

• abra secret insert now supports a --file/-f flag to support inserting from file without using Bash-isms. See See #555 for more.

0.8.x-beta -> 0.9.x-beta

None at this time.

0.7.x-beta -> 0.8.x-beta

• We now have an --offline flag instead of relying on internal logic to try to decide when offline/online works best. It's up to you! A lot of abra operations require network access, so it is not really truly "offline". The logic prefers local filesystem access when this flag is passed. E.g. if there is a local copy of the catalogue, then don't git pull.

• There is more --chaos! There is more consistent flag handling for manually overriding when to update the local recipe or leave it alone when hacking on changes.

• Secrets are now only generated by reading the recipe config, not the env vars. This should hopefully not affect you. If you're seeing weird behaviour, please see #464.

• There is a new linting rule for catching invalid tags in recipe versions. This is an seemingly unavoidable issue that requires some maintenance work. If you run into the error, here's some docs to help work through it.

• ~/.abra/catalogue is now only updated via git pull. You may need to cd ~/.abra/catalogue && git checkout . to get abra to stop complaining about unstaged changes.

• abra record ... & abra server new have been removed! Following a usage poll, these features were not being relied on. They were also alpha prototypes which we feel can be reconsidered once other more critical parts of Abra are more stable.

0.6.x-beta -> 0.7.x-beta

• ALERTA, ALERTA, security related issue: all $domain.env env vars are now exposed to the deployment via the app service container. Each FOO=BAR is exported within the context of the container. If you have any privately committed secrets in your .env files, please migrate them to the secrets: ... configuration in the recipe. This change was made to facilitate tooling which can support auto-upgrading of apps in a deployment.

• abra can no longer install Docker, initialise swarm mode and the proxy network. It will check if a Docker install exists and is in swarm mode or not and error out accordingly. We leave the provisioning to tools that are designed for that and reduce the command-line surface that we have to maintain going forward.

• abra server add <host> <args> 👉 abra server add <host>. We have finally removed the custom SSH handling code and now solely rely on invoking /usr/bin/ssh directly and reading from the ~/.ssh/config. The <host> argument should correspond to a Host <host> entry in your ~/.ssh/config or in an Include <file> statement (hosts are retrieved via ssh -G <host>). This means "how does abra interact with SSH is 1) do you have an ~/.ssh/config entry for <host> 2) can you ssh <host> successfully? 3) there is no 3. It's an easier mental model and also the way abra-bash works, hence, less weird obscure errors. <host> being public a domain name is still required.

• abra no longer tries to do the TOFU host key verification prompt. We follow the praxis of the Docker CLI and just give up when host keys are not validated. We leave it to folks to SSH in and verify themselves.

• Digests have been removed from the catalogue generation. They are not being used elsewhere and were significantly slowing down generation.

0.5.x-beta -> 0.6.x-beta

• Using {{ .Domain }} in recipe .envrc.sample files went away because it was portable enough. We revert to replacing e.g gitea.example.com with the domain. See 8fad34e for more.

• If your abra.sh scripts depend on /bin/sh and /bin/bash is available in the container then /bin/bash will be used from now on. /bin/sh is only now used if /bin/bash is not available. See 7f745ff for more.

v0.4.x -> v0.5.x

• The only breaking change was making abra understand that the JSON dump for the recipes listing lives on recipes.coopcloud.tech/recipes.json instead of recipes.coopcloud.tech.

v0.3.x -> v0.4.x

Make sure to back up your ~/.abra/servers configurations first for safety.

• Please run mv ~/.abra/apps ~/.abra/recipes.

• "app name" as a concept went away, abra now uses the domain name of an app as the identifier. However, we don't expect to see breaking behaviour if you have .env files like ~/.abra/servers/foo.com/mycoolapp.env and you still want to run abra app ps mycoolapp. abra still reads the filename to figure out the identifier. When running abra app new <recipe>, abra will now take the domain name as the name of the .env file.

• abra has a new SSH implementation which enforces SSH host key checking. You may run into connection issues as a result of this code churn, please see this entry for help navigating a fix.

• CLI flag/args handling has been made more flexible. We're working within the constraints of an upstream library issue but have hopefully made it easier to mange passing flags to commands with abra. See this troubleshooting entry for the full review.

• A number of short style flags have been re-mapped and/or added. This is again related to an issue with the upstream CLI library which sometimes understands short style flags as long style flags. E.g. --ch instead of -ch for --chaos. As a concrete example, --ch is now -C on abra app deploy.

• abra app backup & abra app restore are ready for alpha-testing! See this entry and that entry for more.

• abra server add --traefik went away, it was too unreliable & hard to maintain.