Vaultwarden on Cloudron initial setup

[nebulon]

For some reason that diff does not really match the latest docs version, but I pushed a change to fix the ./vaultwarden hash command as you also have in the diff. Not sure if this was really all in the end.

[robi]

@nebulon the docs are still not right, as what's in the docs (img below) is not what a user will see when they open the web terminal.

should be more like:

root@abc:/app/code# ./vaultwarden hash

[girish]

@robi i had changed it to be absolute path. What is wrong with the path?

[necrevistonnezr]

Users may not understand that they either have to copy & past the whole /app/code/vaultwarden hash into the command line OR just ./vaultwarden hash

[nebulon]

if both works, I don't quite see the issue here, or is one not working as expected?

[LoudLemur]

@necrevistonnezr said in Vaultwarden on Cloudron initial setup:

Users may not understand that they either have to copy & past the whole /app/code/vaultwarden hash into the command line OR just ./vaultwarden hash

Trying this didn't work: /app/code/vaultwarden hash

As @robi said, using the following command does: ./vaultwarden hash

I think part of the problem in this case is not having a clear policy about how to represent commands in the documentation.

[necrevistonnezr]

@LoudLemur Weird. If I open up the Web Terminal for Vaultwarden and copy & past /app/code/vaultwarden hash (the whole thing!), it works for me:

[girish]

I just double checked this. It works fine even when run from /tmp as current directory.

root@bb442c5d-ba11-4a7f-b4ff-663720abdc2f:/tmp# /app/code/vaultwarden hash
Generate an Argon2id PHC string using the 'bitwarden' preset:

Password: 
Confirm Password: 

ADMIN_TOKEN='$argon2id$v=19$m=65540,t=3,p=4$vIlWyi0mBy4yIEnMZB54VWRjZN+sbamxAvvVy+ORGf0$IfU/tB2ULY97ccACP0444mSmm6rCORIWraTApg4E5uA'

Generation of the Argon2id PHC string took: 268.843761ms

[robi]

@girish while you may know how to make it work from any directory, the average user perspective is a very point-and-click one with direct comparison to what they see in their terminal and your docs.

So all the variations you give are just adding confusion, as it doesn't match what they see once they click the web terminal button and the new tab opens.

Hence the docs need instructions as compared to the default experience users see.

Is that clearer?

[girish]

@robi sure. But absolute paths are the correct paths to use in docs. We don't use relative paths (when we do, we also put a cd command before that). relative paths depend on the the package WORKDIR from Dockerfile as well.

[LoudLemur]

I think the documentation should present the necessary command in isolation.

This should then be accompanied by an sort of screenshot image of what the user can expect to see when they attempt it, the context and perhaps the results after successfully using the command.

Currently, what Cloudron documentation shows is only the last part, what one might see in the terminal.

The markdown used to create this could be more clear. Different use of colour could be used to indicate:

• the commands to be typed into the terminal
• the prompt/path
• the results from using the command

I will have a look around for some better custom markdown. Somebody might know some good stuff already.

root@bb442c5d-ba11-4a7f-b4ff-663720abdc2f:/tmp# /app/code/vaultwarden hash
Generate an Argon2id PHC string using the 'bitwarden' preset:

Password: 
Confirm Password: 

ADMIN_TOKEN='$argon2id$v=19$m=65540,t=3,p=4$vIlWyi0mBy4yIEnMZB54VWRjZN+sbamxAvvVy+ORGf0$IfU/tB2ULY97ccACP0444mSmm6rCORIWraTApg4E5uA'

Generation of the Argon2id PHC string took: 268.843761ms

If the documentation presents the information like this, the user has to know that there is a:

• distinction between the current path being indicated and the command itself
• how to extract the command from the other information.

If users trying to follow the documentation don't realize this, then they may attempt to follow the instructions by trying to copy/paste like this into the terminal:

root@bb442c5d-ba11-4a7f-b4ff-663720abdc2f:/tmp# /app/code/vaultwarden hash

or they might even try and copy paste this:

root@bb442c5d-ba11-4a7f-b4ff-663720abdc2f:/tmp# /app/code/vaultwarden hash
Generate an Argon2id PHC string using the 'bitwarden' preset:

or this:

Generate an Argon2id PHC string using the 'bitwarden' preset:

[LoudLemur]

Here is a quick example of well regarded documentation from the Django framework:

You can see that the command is highlighted in bold, and then the view in the shell is presented, too.

[LoudLemur]

At this site, one can experiment with different themes. For example, you can see how well Monokai distinguishes elements from one another by using colour syntax:

https://highlightjs.org/static/demo/

For comparison, here is base 16 solarized dark:

and Atom One Dark:

[girish]

@LoudLemur good ideas. I think the docs can highlight and separate the command to be run and the output . Not the first time our docs cause this confusion (also, some people paste the # as well which actually is the prompt but in shell it is a comment).

I will make a task to revisit our entire docs to show the command and output better.

[LoudLemur]

Docusaurus 2.0 is out today. It has been completely rewritten.
https://docusaurus.io/docs/markdown-features/code-blocks#theming

There is also readthedocs:
https://docs.readthedocs.io/

I like that Atom One Dark theme. If documentation might be upgraded then the default theme for the Cloudron terminal might also be considered for revision.

[LoudLemur]

I have created a new thread for documentation here:
https://forum.cloudron.io/topic/9462/cloudron-documentation-ideas/2

I think @girish talents are too precious to be used on documentation and that the community may well prefer him to be focused on something else.