claudiomaradonna/azkaban
1
1
Fork 0
Code Issues Pull requests Packages Activity Actions

docs: add uninstall steps and two troubleshooting entries #63

Merged
claudiomaradonna merged 2 commits from docs/uninstall-troubleshooting into master 2026-10-30 18:19:59 +01:00
Conversation 0 Commits 2 Files changed 3 +45 -1
motoko commented 2026-10-30 18:18:54 +01:00
Collaborator
Copy link

Why

A user who wants to remove azkaban finds no word on what the installer
wrote or how to take it away: command links in ~/.local/bin, the
runtime in ~/.local/libexec/azkaban, client, base, and custom images,
and ~/.azkaban with their logins and identities. Two messages a user
commonly meets, a mistyped --identity and an unapproved workspace
Dockerfile in a launch without a terminal, have no Troubleshooting
entry. Both gaps come from the documentation audit behind #62. An
install.sh --uninstall command was set aside: it would be a new
interface, while the manual steps answer the question now.

What changed

Installation gains an Uninstall section. It removes only the command
links that point into azkaban's runtime, then the runtime, then the
images, with one Podman pipeline on Linux and the names to look for on
macOS, and links Updates for reclaiming untagged images. It says what
~/.azkaban holds before giving the command that deletes it, and that
the engine the installer may have added stays. The README's index entry
for Installation now names uninstalling.

Troubleshooting gains an entry for identity 'NAME' has no folder,
pointing to Identities, and one for the is not approved warning,
which says to launch once from a terminal and approve, pointing to
Approval.

How to verify

On a Linux host with azkaban installed and a custom image built once,
run the Uninstall commands in order. ls -l ~/.local/bin then lists
none of codex, claude, opencode that pointed into the runtime,
while any other link there stays; podman images lists no
localhost/codex-cli, claude-code, opencode-cli, azkaban-base,
custom image, or git.unitoo.it/claudiomaradonna/azkaban-base.

Verify (make lint && .agents/hooks/shellcheck.sh repo && make test)
passes on the tip. The link loop ran in a scratch home, removing the
runtime's link and keeping an unrelated one; the image pipeline and the
macOS steps were not run, since no Podman or Mac was available.

## Why A user who wants to remove azkaban finds no word on what the installer wrote or how to take it away: command links in `~/.local/bin`, the runtime in `~/.local/libexec/azkaban`, client, base, and custom images, and `~/.azkaban` with their logins and identities. Two messages a user commonly meets, a mistyped `--identity` and an unapproved workspace Dockerfile in a launch without a terminal, have no Troubleshooting entry. Both gaps come from the documentation audit behind #62. An `install.sh --uninstall` command was set aside: it would be a new interface, while the manual steps answer the question now. ## What changed Installation gains an Uninstall section. It removes only the command links that point into azkaban's runtime, then the runtime, then the images, with one Podman pipeline on Linux and the names to look for on macOS, and links Updates for reclaiming untagged images. It says what `~/.azkaban` holds before giving the command that deletes it, and that the engine the installer may have added stays. The README's index entry for Installation now names uninstalling. Troubleshooting gains an entry for `identity 'NAME' has no folder`, pointing to Identities, and one for the `is not approved` warning, which says to launch once from a terminal and approve, pointing to Approval. ## How to verify On a Linux host with azkaban installed and a custom image built once, run the Uninstall commands in order. `ls -l ~/.local/bin` then lists none of `codex`, `claude`, `opencode` that pointed into the runtime, while any other link there stays; `podman images` lists no `localhost/codex-cli`, `claude-code`, `opencode-cli`, `azkaban-base`, custom image, or `git.unitoo.it/claudiomaradonna/azkaban-base`. Verify (`make lint && .agents/hooks/shellcheck.sh repo && make test`) passes on the tip. The link loop ran in a scratch home, removing the runtime's link and keeping an unrelated one; the image pipeline and the macOS steps were not run, since no Podman or Mac was available. 
List the command links, runtime, and images the installer leaves, with
the commands that remove them, and say what ~/.azkaban holds before
its removal.
Explain the error for an identity without a folder and the warning a
launch without a terminal gives for an unapproved workspace Dockerfile.
claudiomaradonna deleted branch docs/uninstall-troubleshooting 2026-10-30 18:20:05 +01:00
Sign in to join this conversation.
Reviewers
No reviewers
Labels
Clear labels
No items
No labels
Milestone
Clear milestone
No items
No milestone
Projects
Clear projects
No items
No project
Assignees
Clear assignees
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
claudiomaradonna/azkaban!63
No description provided.