toolshed/abra
toolshed/abra
4
2
Fork 18
Code Issues 29 Pull Requests 3 Packages Releases 40 Activity

UX difficulties encountered when working with recipes #563

New Issue
Closed
opened 2025-05-25 20:20:50 +00:00 by mac-chaffee · 7 comments
mac-chaffee commented 2025-05-25 20:20:50 +00:00
Copy Link

Hello, first of all I wanted to say thanks for making this cool project! I work as a platform engineer and I love to explore the different tradeoffs people make when building platforms for running apps.

So I've been following the package handbook here and I have some UX feedback to provide.

No command to apply new config, must undeploy && deploy

If I want to change the LOG_LEVEL or some other environment variable, I have to run abra app undeploy <app name> followed by abra app deploy <app name>. In Kubernetes, you can just run kubectl apply. In docker-compose, you can just run docker-compose up -d --recreate. It would be nice if abra had some kind of "apply" command. Docker-compose (I think) can detect which apps do actually need to be recreated, that way you don't have to shut down your database just to change a variable on a web app.

EDIT: Solved by abra app deploy --force

Lots of typing of app domain names

Since all abra app * commands require typing the full domain name, it makes hacking on recipes a little slow. It would be nice if there was an abra setting (could go in ~/.abra) which sets the default root domain, that way you only have to type the first word of the subdomain.

Advanced users with multiple domains would just not set the default root domain.

EDIT: Solved by setting up autocomplete

Undeploy doesn't wait for container deletion

When I run abra app undeploy on recipes like matrix-synapse, it seems to return instantly, before the containers are killed. This causes problems when I try to abra app deploy soon after, since it will sometimes result in the network not being recreated.

EDIT: Tracked in #557

No ability to automatically set new default env vars for new versions

If a recipe adds a new default environment variable to .env.sample, everyone will have to also add that env var to their own config since there doesn't seem to be any merging of config. Abra will warn you that the new config is missing, but I think there should be a mechanism to fix it automatically.

Helm charts solve this by merging a user's values.yaml with a default values.yaml file. But if we don't want to implement config merging, maybe at least abra could prompt to add the new default config values automatically.

EDIT: Tracked in #504

Chaos mode has a high chance of destroying your changes

The docs recommend testing out recipe changes in ~/.abra/recipes then running abra app deploy --chaos to allow deploying a recipe with uncommitted changes. If you ever forget to add the --chaos flag commit your changes but don't push them, all your hard work will be silently deleted :(

Instead of abra running git reset silently, it might be nicer for it to just log an error when there are unstaged changes new commits but --chaos was not set.

Overall, I feel like there could be a nicer method of hacking on recipes than --chaos. For example, it would be nice to be able to redeploy/upgrade an app to any git repo/fork/branch, but the commit SHA in TYPE makes this difficult. There's also a chance for config mismatches when you change the compose.yml file locally before running undeploy, which is generally not a problem when working with docker-compose directly.

Perhaps the problem comes from abra tracking the deploy state and the git repo state and enforcing lots of controls over transitions of those states. When working directly with the kubectl or docker-compose CLI tools, those tools don't enforce anything about version control and they don't track any state. They will dutifully apply any config changes to reconcile the live state of the application to match the desired state of the provided .yaml files. Maybe abra could have a different mode of operation where it only enforces the git versioning stuff when working on official recipes.

To hack on a recipe, abra could allow you to run abra app new <any folder or git repo> and all abra operations in this folder are --chaos mode by default, with lint errors converted to just warnings, etc.

Sorry for the info dump, this is just everything I remembered encountering while learning how to use coop-cloud, so it's not super organized. No need to implement everything here, just wanted to add my feedback as a data point :)

Hello, first of all I wanted to say thanks for making this cool project! I work as a platform engineer and I love to explore the different tradeoffs people make when building platforms for running apps. So I've been following the package handbook [here]([url](https://docs.coopcloud.tech/maintainers/handbook/)) and I have some UX feedback to provide. ## No command to apply new config, must undeploy && deploy If I want to change the `LOG_LEVEL` or some other environment variable, I have to run `abra app undeploy <app name>` followed by `abra app deploy <app name>`. In Kubernetes, you can just run `kubectl apply`. In docker-compose, you can just run `docker-compose up -d --recreate`. It would be nice if abra had some kind of "apply" command. Docker-compose (I think) can detect which apps do actually need to be recreated, that way you don't have to shut down your database just to change a variable on a web app. EDIT: Solved by `abra app deploy --force` ## Lots of typing of app domain names Since all `abra app *` commands require typing the full domain name, it makes hacking on recipes a little slow. It would be nice if there was an abra setting (could go in `~/.abra`) which sets the default root domain, that way you only have to type the first word of the subdomain. Advanced users with multiple domains would just not set the default root domain. EDIT: Solved by setting up autocomplete ## Undeploy doesn't wait for container deletion When I run `abra app undeploy` on recipes like matrix-synapse, it seems to return instantly, before the containers are killed. This causes problems when I try to `abra app deploy` soon after, since it will sometimes result in the network not being recreated. EDIT: Tracked in #557 ## No ability to automatically set new default env vars for new versions If a recipe adds a new default environment variable to .env.sample, everyone will have to also add that env var to their own config since there doesn't seem to be any merging of config. Abra will warn you that the new config is missing, but I think there should be a mechanism to fix it automatically. Helm charts solve this by merging a user's `values.yaml` with a default `values.yaml` file. But if we don't want to implement config merging, maybe at least abra could prompt to add the new default config values automatically. EDIT: Tracked in #504 ## Chaos mode has a high chance of destroying your changes The docs recommend testing out recipe changes in `~/.abra/recipes` then running `abra app deploy --chaos` to allow deploying a recipe with uncommitted changes. If you ever ~~forget to add the `--chaos` flag~~ commit your changes but don't push them, all your hard work will be silently deleted :( Instead of abra running `git reset` silently, it might be nicer for it to just log an error when there are ~~unstaged changes~~ new commits but `--chaos` was not set. Overall, I feel like there could be a nicer method of hacking on recipes than `--chaos`. For example, it would be nice to be able to redeploy/upgrade an app to any git repo/fork/branch, but the commit SHA in `TYPE` makes this difficult. There's also a chance for config mismatches when you change the `compose.yml` file locally before running `undeploy`, which is generally not a problem when working with `docker-compose` directly. Perhaps the problem comes from abra tracking the `deploy` state and the git repo state and enforcing lots of controls over transitions of those states. When working directly with the `kubectl` or `docker-compose` CLI tools, those tools don't enforce anything about version control and they don't track any state. They will dutifully apply any config changes to reconcile the live state of the application to match the desired state of the provided .yaml files. Maybe abra could have a different mode of operation where it only enforces the git versioning stuff when working on official recipes. To hack on a recipe, abra could allow you to run `abra app new <any folder or git repo>` and all abra operations in this folder are `--chaos` mode by default, with lint errors converted to just warnings, etc. --- Sorry for the info dump, this is just everything I remembered encountering while learning how to use coop-cloud, so it's not super organized. No need to implement everything here, just wanted to add my feedback as a data point :)
❤️ 2
decentral1se commented 2025-05-25 20:43:41 +00:00
Owner
Copy Link

Thanks for this @mac-chaffee! Good to have these perspectives.

No command to apply new config, must undeploy && deploy

abra app deploy --force does this. I agree that the apply interface surface is kinda nice but I'm unsure it would warrant a new sub-command for abra? I'd be curious what other folks think. Perhaps @moritz @p4u1 @fauno you've used other config mgmt tools?

Lots of typing of app domain names

I think abra is nearly unusable for this reason without auto-completion. Does auto-completion not sort things out for you? See abra autocomplete -h for more.

Undeploy doesn't wait for container deletion

This is definitely a bug. It's hard to deal with because the container runtime is also not really doing it well. I'll open a ticket. I also ran into #557. This sub-command definitely needs improvement. There was a large refactor recently in the internals...

No ability to automatically set new default env vars for new versions

I think we need to definitely implement this. See also #504.

Chaos mode has a high chance of destroying your changes

If you --chaos with uncommited changes and then you do not --chaos, it will not wipe your changes, it will bail out immediately. If you lost your changes, that is a bad bug. Can you please provide more information on which workflow this was?

Thanks for this @mac-chaffee! Good to have these perspectives. > No command to apply new config, must undeploy && deploy `abra app deploy --force` does this. I agree that the `apply` interface surface is kinda nice but I'm unsure it would warrant a new sub-command for `abra`? I'd be curious what other folks think. Perhaps @moritz @p4u1 @fauno you've used other config mgmt tools? > Lots of typing of app domain names I think `abra` is nearly unusable for this reason without auto-completion. Does auto-completion not sort things out for you? See `abra autocomplete -h` for more. > Undeploy doesn't wait for container deletion This is definitely a bug. It's hard to deal with because the container runtime is also not really doing it well. I'll open a ticket. I also ran into https://git.coopcloud.tech/toolshed/abra/issues/557. This sub-command definitely needs improvement. There was a large refactor recently in the internals... > No ability to automatically set new default env vars for new versions I think we need to definitely implement this. See also https://git.coopcloud.tech/toolshed/abra/issues/504. > Chaos mode has a high chance of destroying your changes If you `--chaos` with uncommited changes and then you do not `--chaos`, it will not wipe your changes, it will bail out immediately. If you lost your changes, that is a bad bug. Can you please provide more information on which workflow this was?
mac-chaffee commented 2025-05-26 03:20:44 +00:00
Author
Copy Link

Chaos mode has a high chance of destroying your changes

I'm remembering now that this happened before I knew about --chaos, so I thought the only way to get passed the <app> has locally unstaged changes? error was to commit the changes. But then abra seems to git reset to a previous commit when you deploy it, deleting the changes.

So I guess that part was user error, but it leads me to the part about "a nicer method of hacking on recipes than --chaos. Since abra app deploy reverts any new commits, I can't run git pull in my recipe to test out the latest changes, or git checkout to test a PR. Do we have to change the commit SHA in the TYPE variable in order to do that? Because if I run abra app upgrade, it will run a git pull, but then says FATA '49bd0f9d' is not supported (^[a-f0-9]{7,40}$).

Maybe there's a correct workflow here that I just need to learn. Maybe a few more lines of docs or some more info in the error messages could help push me in the right direction :)

> Chaos mode has a high chance of destroying your changes I'm remembering now that this happened before I knew about `--chaos`, so I thought the only way to get passed the `<app> has locally unstaged changes?` error was to commit the changes. But then abra seems to `git reset` to a previous commit when you `deploy` it, deleting the changes. So I guess that part was user error, but it leads me to the part about "a nicer method of hacking on recipes than `--chaos`. Since `abra app deploy` reverts any new commits, I can't run `git pull` in my recipe to test out the latest changes, or `git checkout` to test a PR. Do we have to change the commit SHA in the `TYPE` variable in order to do that? Because if I run `abra app upgrade`, it will run a `git pull`, but then says `FATA '49bd0f9d' is not supported (^[a-f0-9]{7,40}$)`. Maybe there's a correct workflow here that I just need to learn. Maybe a few more lines of docs or some more info in the error messages could help push me in the right direction :)
mac-chaffee commented 2025-05-26 03:22:46 +00:00
Author
Copy Link

Re: autocomplete. I was about to say "oh that works, maybe we should add it to the docs" but now I see it's already there and I just totally missed it haha 🤦‍♂️

https://docs.coopcloud.tech/operators/tutorial/#install-abra

Re: autocomplete. I was about to say "oh that works, maybe we should add it to the docs" but now I see it's already there and I just totally missed it haha 🤦‍♂️ https://docs.coopcloud.tech/operators/tutorial/#install-abra
😆 2
3wordchant commented 2025-05-26 12:32:30 +00:00
Owner
Copy Link

Re: autocomplete. I was about to say "oh that works, maybe we should add it to the docs" but now I see it's already there and I just totally missed it haha 🤦‍♂️

Any ideas welcome how to make this more obvious! I think it's also mentioned after running the installer script, but given how critical it is for usability maybe there should be a check during each command run? 🤔

> Re: autocomplete. I was about to say "oh that works, maybe we should add it to the docs" but now I see it's already there and I just totally missed it haha 🤦‍♂️ Any ideas welcome how to make this more obvious! I think it's also mentioned after running the installer script, but given how critical it is for usability maybe there should be a check during each command run? 🤔
mac-chaffee commented 2025-05-26 14:48:04 +00:00
Author
Copy Link

This should make it obvious enough for docs-skimmers like me 😁: toolshed/docs.coopcloud.tech#277

Maybe I'm weird, but I'm not a huge fan of autocomplete, since it's a lot of shell code to parse which slows down creating new terminals and it kinda enables arbitrary code execution a little too easily. I don't enable it for any other tool, including kubectl.

If we wanted to configure something by default, I'd prefer an abra config file (~/.abra/config) that stores a default domain name (and could store other things in the future, similar to a kubeconfig or ~/.docker/config.json or ~/.aws/config). Less platform-dependent too.

This should make it obvious enough for docs-skimmers like me 😁: https://git.coopcloud.tech/toolshed/docs.coopcloud.tech/pulls/277 Maybe I'm weird, but I'm not a huge fan of autocomplete, since it's a lot of shell code to parse which slows down creating new terminals and it kinda enables arbitrary code execution a little too easily. I don't enable it for any other tool, including kubectl. If we wanted to configure something by default, I'd prefer an abra config file (~/.abra/config) that stores a default domain name (and could store other things in the future, similar to a kubeconfig or [`~/.docker/config.json`](https://docs.docker.com/reference/cli/docker/#docker-cli-configuration-file-configjson-properties) or `~/.aws/config`). Less platform-dependent too.
🎉 1
decentral1se commented 2025-05-27 07:02:21 +00:00
Owner
Copy Link

... But then abra seems to git reset to a previous commit when you deploy it, deleting the changes ... Since abra app deploy reverts any new commits

There's no logic to git reset / revert commits in abra. abra app deploy checks out HEAD or specific tags, your commits should not be getting wiped out. Please raise a specific ticket about this if you can reproduce data loss again? We've had a few data loss bugs in the past and I really wanna squash those.

re: "better than --chaos mode" method, I'm all ears but this approach has been built into abra since the beginning of time so you'd need to prepare a proposal and go through some discussion to get the ball rolling...

In general, I think you're running into some rough edges still in the tool on this workflow, so thanks for persevering!

Do we have to change the commit SHA in the TYPE variable in order to do that? Because if I run abra app upgrade, it will run a git pull, but then says FATA '49bd0f9d' is not supported (^[a-f0-9]{7,40}$).

#554
Also a bit of #561

I'd prefer an abra config file

The machinery is there and the idea has been floating for quite some time now, see toolshed/organising#303. I think we're just missing the code / proposal for specific config options. I could imagine people would be up for experimenting with stuff tho, so feel free to take a run at it!

> ... But then abra seems to git reset to a previous commit when you deploy it, deleting the changes ... Since abra app deploy reverts any new commits There's no logic to git reset / revert commits in `abra`. `abra app deploy` checks out `HEAD` or specific tags, your commits should not be getting wiped out. Please raise a specific ticket about this if you can reproduce data loss again? We've had a few data loss bugs in the past and I really wanna squash those. re: "better than `--chaos` mode" method, I'm all ears but this approach has been built into `abra` since the beginning of time so you'd need to prepare a proposal and go through some discussion to get the ball rolling... In general, I think you're running into some rough edges still in the tool on this workflow, so thanks for persevering! > Do we have to change the commit SHA in the TYPE variable in order to do that? Because if I run abra app upgrade, it will run a git pull, but then says FATA '49bd0f9d' is not supported (^[a-f0-9]{7,40}$). https://git.coopcloud.tech/toolshed/abra/issues/554 Also a bit of https://git.coopcloud.tech/toolshed/abra/issues/561 > I'd prefer an abra config file The machinery is there and the idea has been floating for quite some time now, see https://git.coopcloud.tech/toolshed/organising/issues/303. I think we're just missing the code / proposal for specific config options. I could imagine people would be up for experimenting with stuff tho, so feel free to take a run at it!
mac-chaffee commented 2025-05-28 02:21:08 +00:00
Author
Copy Link

abra app deploy checks out HEAD or specific tags, your commits should not be getting wiped out.

You're right, looks like the commits are recoverable with git reflog. They disappear from the git log which made me think abra was running git reset or something.

I documented the issue and the fix in #566 and closed it in case it helps others :)

I think that basically resolves all of the actionable things in this issue, so I think we can close it. Thanks for being responsive!

> abra app deploy checks out HEAD or specific tags, your commits should not be getting wiped out. You're right, looks like the commits are recoverable with `git reflog`. They disappear from the `git log` which made me think abra was running `git reset` or something. I documented the issue and the fix in #566 and closed it in case it helps others :) I think that basically resolves all of the actionable things in this issue, so I think we can close it. Thanks for being responsive!
❤️ 1
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
bug
Something is not working
build
go build related issues
ci/cd
Building things with CI/CD
contributing
Dealing with contributing
critical fix
https://docs.coopcloud.tech/federation/resolutions/passed/010/
design
UI/UX
documentation
Documenting all the things
duplicate
This issue or pull request already exists
enhancement
New feature
help wanted
Need some help
invalid
Something is wrong
meta
relating to the project or repo itself
question
More information is needed
release
Release management
release-candidate
Related to the new release candidate
security
Security related
test
Unit/integration testing
wontfix
This won't be fixed
No Label
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
3wordchant abra-bot ammaratef45 Apfelwurm carla cas decentral1se fauno kawaiipunk knoflook lambdabundesverband moritz p4u1 simon trav val yksflip
No Assignees
3 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: toolshed/abra#563
No description provided.
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?