docs.coopcloud.tech/docs/abra/trouble.md

title
Troubleshoot

Where do I report abra bugs / feature requests?

You can use this issue tracker.

SSH connection issues?

abra tries its best to learn from your system configuration or command-line input what the correct SSH connection details are for a given server. This doesn't always work out. Here are some things to try to fix it.

First, ensure that you can ssh <my-server> and things work. If you can't SSH to your server then neither can abra. If you have a password protected SSH key, then you'll need to make sure your ssh-agent is running and you've added your SSH key part:

eval $(ssh-agent -k)
ssh-add ~/.ssh/<my-secret-key-part>
ssh-add -L # validate loaded keys

The first thing abra will check for is the connection details listed in abra server ls. Check those details are correct. If you haven't managed to abra server add your server yet, then no details will appear in that list. You may need to take a look at this entry to clean up old values depending on your situation.

abra will then try to read your ~/.ssh/config entries and match the server domain against a Host entry. So, if you do ssh myserver.com and you have:

Host myserver.com
  Hostname myserver.com
  User myuser
  Port 222
  IdentityFile ~/.ssh/my@myserver.com

Then abra should have all it needs to build a working SSH connection. You can validate this by passing -d/--debug to your commands.

However, sometimes, you use an alias in your SSH configuration, say:

Host mys
...

So that you can simply type ssh mys. abra won't be able to match against those entries to discover connection details. You can use aliases to remedy this:

Host mys, myserver.com
...

abra will try to read the relevant IdentityFile entry from your ~/.ssh/config but if it can't make a match, it will rely on your key being added to the ssh-agent.

Due to a limitation in our implementation, abra uses 2 methods of making SSH connections, the main abra -> remote docker connection using /usr/bin/ssh which can seamlessly pick up loaded SSH keys. However, for SSH host key checking, abra uses an SSH library & Golang SSH internals. We're working on resolving this to a single implementation but it is tricky work.

"abra server ls" shows the wrong details?

You can use abra server rm to remove the incorrect details. Make sure to take a backup of your ~/.abra/servers/<domain> first. You can then try to re-create by using abra server add ... again, making sure to take care if you need to use <user> <port>, see abra server add -h for more help on this.

However, if you have Docker installed on the same machine you have abra, then there might be some confusion. If you run docker context ls you'll see that Docker uses context connection strings also. abra simply uses this approach. Sometimes, your Docker defined context details & your abra context details can get out of sync. You can use docker context rm to resolve this.

If you need to create a new context from Docker, you can do:

docker context create <domain> --docker "host=ssh://<user>@<domain>:<port>"

(This is what we used to before we wrote abra to make it more convenient.)

Command-line flag handling is weird?

Unfortunately, there is a limitation in our underlying command-line library implementation for abra (ref) (and more fundamentally in the design of flags in the Go programming language itself (ref)). We're aiming to work with upstream to resolve the flag handling but this it is not yet clear when this will be resolved.

Why can't abra support multiline definitions in the .env files?

We're sorry, it's an issue with an upstream dependency. See #291 for more.