Better document the mount behavior in appsody

appsody / website

Appsody website and documentation. This repo will be archived soon.

https://appsody.dev

Apache License 2.0

13 stars 29 forks source link

Better document the mount behavior in appsody #233

Open kylegc opened 5 years ago

kylegc commented 5 years ago

Follow-up to https://github.com/appsody/stacks/issues/280 We should do a better job of documenting the mount points, specifically:

[ ] host path is relative to the appsody project dir
[x] the layout of the stack (https://appsody.dev/docs/stacks/stacks-overview)
[ ] what will be picked up for extraction and deployment thereon.

skoh7645 commented 5 years ago

Do we have an idea as to where we would add this?

kylegc commented 5 years ago

@appsody/website please see Sandy's question above.

Kamran64 commented 5 years ago

We could document this in the stack structure page under or near Mounting the correct directories into the image. My only worry is that this page is already very text heavy as it is...

tomleah commented 5 years ago

My only worry is that this page is already very text heavy as it is...

Agreed, I couldn't even find the heading you were talking about @Kamran64, its all 1 block of text. We should at improving the doc pages design.

We might need some more explanation in Appsody Environment Variables also? Not as much how the mounts work, but just verify how mounts must be specified. I see some conversation about . vs / in https://github.com/appsody/stacks/issues/280

Another idea, maybe we start on getting some architecture diagrams in a high-level architecture doc. Then we can graphically show where directories are and what happens to them on appsody init, appsody extract etc. We can then show the relation between host and container directories with the ENV variables/mounts

helenmasters commented 4 years ago

@kylegc the env variables documentation has had an overhaul recently which addresses how the mounts must be specified. What else would you like to see documented given the docs we have now ie do we need to do more in order to close off this issue?

kylegc commented 4 years ago

I changed the first comment into a checklist and reviewed the documentation. From what I see, only one of the three items is covered by documentation. We still need the following:

1) Mount host path is relative to the appsody project dir Update APPSODY_MOUNTS in Appsody Environment Variables to make this clear. It should explain what a ., /, and ~ means in the path.

2) What will be extracted This should probably documented/improved in a few places:

The CLI Reference/help text for extract
The [Stacks Overview] (https://appsody.dev/docs/stacks/stacks-overview) page
The APPSODY_PROJECT_DIR in Appsody Environment Variables needs improvement. Both the description and the example are misleading. This value is not a local path, it is a path within the container.