Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Migrate Studio Self hosted docs to dvc.org #4344

Merged
merged 17 commits into from
Mar 9, 2023
Merged

Migrate Studio Self hosted docs to dvc.org #4344

Show file tree
Hide file tree
Changes from 6 commits
Commits
Show all changes
17 commits
Select commit Hold shift + click to select a range
9ed867b
Migrate Studio Selfhosted docs to dvc.org
Mar 1, 2023
cc4b9a7
Add Gitlab, Github, Troubleshooting pages
Mar 2, 2023
fa1852a
Fix indentation in GitHub docs
Mar 3, 2023
c6e58fd
Use cli code blocks instead of shell
Mar 3, 2023
41415c4
Selfhosted -> Self hosting
Mar 3, 2023
8b00b6e
Apply suggestions from code reviews
Mar 3, 2023
400d79a
Apply additional suggestions from code review
Mar 3, 2023
725917b
Add a page about custom CA certificates
Mar 3, 2023
fc59843
Move Git forges to subsection
Mar 6, 2023
1446f17
Use subsections instead of bold text
Mar 6, 2023
bb1cb37
Add info tip to AMI guide
Mar 6, 2023
b30c1d2
Rephrase sentence in AMI guide
Mar 6, 2023
86f3481
Rephrase sentence in AMI guide
Mar 6, 2023
2200a46
Elaborate on Studio's configuration
Mar 6, 2023
5f36e24
Fix links
Mar 6, 2023
66491a0
Merge branch 'main' into studio-selfhosted-docs
yathomasi Mar 6, 2023
2e4ae0b
Remove redundant admon
Mar 6, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 13 additions & 5 deletions content/docs/sidebar.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -616,20 +616,20 @@
},
"troubleshooting",
{
"slug": "selfhosted",
"slug": "self-hosting",
"source": false,
"children": [
{
"slug": "installation",
"source": "installation/index.md",
"children": [
{
"label": "AMI",
"slug": "ami"
"label": "AWS AMI",
"slug": "aws-ami"
},
{
"label": "Helm",
"slug": "helm"
"label": "Kubernetes (Helm)",
"slug": "k8s-helm"
}
]
},
Expand All @@ -641,13 +641,21 @@
"label": "TLS certificates",
"slug": "tls"
},
{
"label": "CA certificates",
"slug": "ca"
},
{
"label": "GitHub integration",
"slug": "github"
},
{
"label": "GitLab integration",
"slug": "gitlab"
},
{
"label": "Bitbucket integration",
"slug": "bitbucket"
}
]
},
Expand Down
3 changes: 3 additions & 0 deletions content/docs/studio/self-hosting/configuration/bitbucket.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
# Bitbucket integration

To be updated.
16 changes: 16 additions & 0 deletions content/docs/studio/self-hosting/configuration/ca.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,16 @@
# CA certificates

Does your Git forge use a certificate signed by a custom certificate authority
(CA)? If so, Studio needs to have the CA certificate in order to connect to the
Git forge.

To do this, copy your CA certificate as plain text, then insert it in the
`customCaCert` key in the `values.yaml` configuration file:

```yaml
global:
customCaCert: |-
-----BEGIN CERTIFICATE-----
....
-----END CERTIFICATE-----
```
19 changes: 10 additions & 9 deletions ...studio/selfhosted/configuration/github.md → ...udio/self-hosting/configuration/github.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,15 +22,15 @@ Fill out the details as follows:

**Repository permissions:**

- Contents: Read / Write
- Issues: Read / Write
- Metadata: Read
- Pull Requests: Read / Write
- Webhooks: Read / Write
- Contents: Read / Write
- Issues: Read / Write
- Metadata: Read
- Pull Requests: Read / Write
- Webhooks: Read / Write

**User permissions:**
**User permissions:**

- Email addresses: Read
- Email addresses: Read

4. Click **Create Github App**

Expand Down Expand Up @@ -63,9 +63,10 @@ scmProviders:
appSecret: <GitHub OAuth App Secret>
privateKey: <GitHub OAuth App Private Key>

# Optional. This is useful in cases where Studio is on an internal
# Optional
# This is useful in cases where Studio is on an internal
# network, but the webhook endpoint is on an external network
webhookUrl: <GitHub Webhook URL, e.g. https://<domain>/webhook/github/>
# webhookUrl: https://webhook.studio.company.com/webhook/github/
jesper7 marked this conversation as resolved.
Show resolved Hide resolved
```

<admon type="info">
Expand Down
7 changes: 5 additions & 2 deletions ...studio/selfhosted/configuration/gitlab.md → ...udio/self-hosting/configuration/gitlab.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -40,9 +40,12 @@ scmProviders:

clientId: <GitLab OAuth App Client ID>
secretKey: <GitLab OAuth App Secret Key>

webhookUrl: <GitLab Webhook URL>
webhookSecret: <GitLab Webhook Secret>

# 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/
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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?

```

<admon type="info">
Expand Down
59 changes: 59 additions & 0 deletions content/docs/studio/self-hosting/configuration/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,59 @@
# Configuration

Studio uses a standardized, unified YAML configuration file, often referred to
as `values.yaml` in the documentation.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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/

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.


## Updating the configuration

To update the configuration and apply the changes, follow the instructions
below:

<admon type="info">

If you've deployed Studio with the AMI, you'll need to SSH to the EC2 instance
before continuing.

</admon>

1. Update Studio's `values.yaml` config file

**Example: Updating the hostname**

Merge the existing `values.yaml` file with the following contents:

```yaml
global:
host: studio.company2.com
```

3. Reload Studio

```cli
$ helm upgrade --wait studio iterative/studio --namespace studio -f values.yaml
```

## More configuration options

The previous chapter provided a basic example of updating the Studio
configuration. In most cases, you'll likely need to do more configuration to set
up Studio to your needs.

Studio integrates with several Git forges (also referred to as SCM providers),
jesper7 marked this conversation as resolved.
Show resolved Hide resolved
each of which are configured differently. For any Git forge type you'll need to
configure an app prior to Studio installation, and also configure a dedicated
block under `scmProviders` in the `values.yaml` file:

- [GitHub](/doc/studio/self-hosting/configuration/github)
- [GitLab](/doc/studio/self-hosting/configuration/gitlab)
- [Bitbucket](/doc/studio/self-hosting/configuration/bitbucket)

<admon type="tip">

If your Git forge uses a certificate signed by a custom certificate authority,
see [CA certificates](/doc/studio/self-hosting/configuration/ca)

</admon>

To allow secure access to Studio, we highly recommend setting up a valid TLS
certificate. To set this up, check out the
[TLS certificates](/doc/studio/self-hosting/configuration/tls) page.
49 changes: 10 additions & 39 deletions ...cs/studio/selfhosted/configuration/tls.md → .../studio/self-hosting/configuration/tls.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,54 +7,29 @@ We strongly recommend deploying Studio with a TLS certificate.
To configure TLS certificates to Studio, following the instructions below
according to your installation method:

<toggle>
<tab title="AMI">
<admon type="info">

If you've deployed Studio with the AMI, you'll need to copy your TLS certificate
and private key to the EC2 instance and start an SSH session before continuing.
Example:

1. Transfer your TLS certificate and private key to the EC2 instance

```shell
```cli
$ scp studio.crt studio.pem ubuntu@my-ec2-instance:.
```

2. Connect with SSH to your EC2 instance

```shell
```cli
$ ssh ubuntu@my-ec2-instance
```

3. Store your TLS certificate and private key in an object

```shell
$ kubectl create secret tls studio-ingress-tls \
--namespace studio \
--cert=studio.crt \
--key=studio.pem
```

4. Update Studio's config file

Merge the `values.yaml` file with the following contents:

```yaml
global:
ingress:
tlsEnabled: true
tlsSecretName: studio-ingress-tls
```

5. Reload Studio

```shell
$ helm upgrade --wait studio iterative/studio --namespace studio -f values.yaml
```

</tab>

<tab title="Helm">
</admon>

1. Store your TLS certificate and private key in an object

```shell
```cli
$ kubectl create secret tls studio-ingress-tls \
--namespace studio \
--cert=studio.crt \
Expand All @@ -74,10 +49,6 @@ global:

3. Reload Studio

```shell
```cli
$ helm upgrade --wait studio iterative/studio --namespace studio -f values.yaml
```

</tab>

</toggle>
Loading