Clarify a couple of things in deployment guide. #14

knoflook · 2021-06-22T17:02:16Z

knoflook commented

2021-06-22 17:02:16 +00:00

this PR addresses what I believe to be lacking from the deployment guide.

it's not clear from the docs that you have to install docker both locally and on the server
after doing abra init you get this:

Swarm initialized: current node ([redacted]) is now a
manager.

To add a worker to this swarm, run the following command:

    docker swarm join --token [redacted] [redacted]

To add a manager to this swarm, run 'docker swarm join-token manager'
and follow the instructions.

[redacted]

for somebody who never used docker this response might be unexpected and it might be a good idea to clarify that this is in fact the desired behaviour.

can't generate secrets for nextcloud as it requires pwqgen which is not a part of default debian stable or devuan beowulf installation. You need to install passwdqc to get it. This should be stated in the getting started guide.
got an error message ERROR: https://[redacted] still isn't up, check status by running "abra app nextcloud-coopcloud ps", and the same one for traefik. They just needed some more time.

I'm putting WIP in the title because even I believe these changes are needed, I would like somebody to check if what I've written is gramatically correct and easy to read.

this PR addresses what I believe to be lacking from the deployment guide. - it's not clear from the docs that you have to install docker both locally and on the server - after doing abra <server> init you get this: ``` Swarm initialized: current node ([redacted]) is now a manager. To add a worker to this swarm, run the following command: docker swarm join --token [redacted] [redacted] To add a manager to this swarm, run 'docker swarm join-token manager' and follow the instructions. [redacted] ``` for somebody who never used docker this response might be unexpected and it might be a good idea to clarify that this is in fact the desired behaviour. - can't generate secrets for nextcloud as it requires pwqgen which is not a part of default debian stable or devuan beowulf installation. You need to install passwdqc to get it. This should be stated in the getting started guide. - got an error message `ERROR: https://[redacted] still isn't up, check status by running "abra app nextcloud-coopcloud ps"`, and the same one for traefik. They just needed some more time. I'm putting WIP in the title because even I believe these changes are needed, I would like somebody to check if what I've written is gramatically correct and easy to read.

❤️ 2

knoflook added 1 commit 2021-06-22 17:02:17 +00:00

Clarify a couple of things in deployment guide. 39e7c6c2bc

decentral1se approved these changes 2021-06-23 11:33:27 +00:00

decentral1se left a comment

Wonderful stuff! Thanks for taking a pass on this. The comments below are just more informational than anything. I'd be happy to merge this as is but let us know when you're finished working on it.

docs/deploy.md

						
				@ -86,6 +86,23 @@ Once you've added the sever, you can initialise the [new single-host swarm](http

				abra server example.com init

				```

				You might see some messages from docker-swarm such as:

decentral1se commented

2021-06-23 11:31:46 +00:00

We have discussed making the underlying tools visible so as to make more clear that abra is a thin wrapper on other tools. Also see 57f3f96bbc/abra (L1322) as an example of that. However, this does show how this approach can be confusing for newcomers! I have pondered if we should be capturing this output instead? We still explain what is going on but make it more clear through output we control? I will open a ticket for this.

These docs are good as is though 🚀

We have discussed making the underlying tools visible so as to make more clear that `abra` is a thin wrapper on other tools. Also see https://git.autonomic.zone/coop-cloud/abra/src/commit/57f3f96bbc05836633b833b4eb5d03d219bd2820/abra#L1322 as an example of that. However, this does show how this approach can be confusing for newcomers! I have pondered if we should be capturing this output instead? We still explain what is going on but make it more clear through output we control? I will open a ticket for this. These docs are good as is though 🚀

decentral1se marked this conversation as resolved

docs/deploy.md

						
				@ -114,0 +131,4 @@

				```bash

				ERROR: https://traefik.example.com still isn't up, check status by running "abra app traefik ps"

				```

				It might need a few seconds more to start up. We can then check that everything came up as expected.

decentral1se commented

2021-06-23 11:31:42 +00:00

FYI we're working on making this domain not mandatory if you don't enable the Traefik dashboard in https://git.autonomic.zone/coop-cloud/traefik/issues/24. Most people won't need it. When there is no domain, abra skips over this message. This note is also great to have though.

FYI we're working on making this domain not mandatory if you don't enable the Traefik dashboard in https://git.autonomic.zone/coop-cloud/traefik/issues/24. Most people won't need it. When there is no domain, `abra` skips over this message. This note is also great to have though.

decentral1se marked this conversation as resolved

docs/deploy.md

						
				@ -135,3 +156,4 @@

				abra app nextcloud secret generate --all

				```

				If abra complains about lacking pwqgen, it is available in the packet passwdqc on debian. Install it with