Migrate Studio Self hosted docs to dvc.org #4344
Conversation
jesper7
added
the
C: studio
Link Check ReportThere were no links to check! |
| using the following installation methods: | ||
|
|
||
| - [AMI (AWS)](/doc/studio/selfhosted/installation/ami) | ||
| - [Helm (Kubernetes)](/doc/studio/selfhosted/installation/helm) |
There was a problem hiding this comment.
Should we address here pre-requisites like setting up SCM repo apps before installation?
There was a problem hiding this comment.
We provide example configurations in each installation guide and suggest looking at the configuration section before deploying so I think it naturally ends up in that order.
For example, the reader might end up on a path like:
Helm guide -> Configuration -> SCM providers -> GitHub -> Helm guide
There was a problem hiding this comment.
I find that the order of operations and an understanding of the high-level steps is something you always want to make crystal clear beforehand and not be "emergent" - it's easy to feel overwhelmed as a reader of a guide if you're jumping back and forth between pages without a high-level ordered-step-list in mind
There was a problem hiding this comment.
I agree. However, there are going to be problems with circular dependencies either way.
For instance, if we implement your suggestion:
- User reads the installation methods page and is made aware that Git forges need to be set up before continuing.
- User heads over to the GitHub page, sets up the GitHub app, and doesn't know what to do when encountering the YAML config section, e.g., https://dvc-org-studio-selfhost-l2oxcs.herokuapp.com/doc/studio/self-hosting/configuration/github#configuring-studio-with-the-github-app
Can we work around this without it becoming confusing for the user? The only idea I have is a separation of the external (e.g., Github) and the internal (Studio) configuration, but this also leads to indirection.
| # Optional | ||
| # This is useful in cases where Studio is on an internal | ||
| # network, but the webhook endpoint is on an external network | ||
| # webhookUrl: https://webhook.studio.company.com/webhook/gitlab/ |
There was a problem hiding this comment.
Same question as in github - not clear if this "optional" is because webhooks as a feature are optional, or they will work without setting this explicitly
There was a problem hiding this comment.
The webhooks will work if the SCM provider has connectivity with Studio. This wouldn't be the case on an internal network, so users can selectively expose the webhook on an external network so that it still works.
Do you think it needs rephrasing to make this more clear?
| # Configuration | ||
|
|
||
| Studio uses a standardized, unified YAML configuration file, often referred to | ||
| as `values.yaml` in the documentation. |
There was a problem hiding this comment.
Seems really weird to me to talk about this without mentioning Helm. This is not just some "unified YAML" (not sure what that even means).
Suggest to add a link here somehow: https://helm.sh/docs/chart_template_guide/values_files/
There was a problem hiding this comment.
We can, of course, mention Helm. My concern here was with overwhelming AMI users with Kubernetes terminology. There are also plans to move to an interactive installer, so manual configuration eventually becomes obsolete for most users.
This is not just some "unified YAML" (not sure what that even means).
I can see it's confusing, and I'll rephrase it. The point was that the configuration works for both the AMI and Helm flavors.
| $ ssh -i <EC2 key pair> ubuntu@$EC2_INSTANCE | ||
| ``` | ||
|
|
||
| 13. Configure the Docker registry credentials: |
There was a problem hiding this comment.
Shouldn't we link to the k8s-helm for the rest of the steps?
Seems like a direct duplication, wdyt?
There was a problem hiding this comment.
Do you mean https://github.com/iterative/helm-charts?
I think having the documentation in one place is better for our users. The documentation in the helm-charts repo is also outdated
There was a problem hiding this comment.
@jesper7 - I mean installation/k8s-helm.md so cross-linking inside the docs in dvc.org
There was a problem hiding this comment.
Got it. I think it's better to have all the steps on one page. We can perhaps see if it's possible to create snippets that can be included across pages
| <admon type="info"> | ||
|
|
||
| Replace the strings marked with `< >` | ||
|
|
||
| </admon> |
There was a problem hiding this comment.
This is not needed at this point.
| <admon type="info"> | |
| Replace the strings marked with `< >` | |
| </admon> |
omesser
changed the title
This PR migrates all of our Studio Selfhosted docs on Notion and Github to dvc.org.
Contents