-
Notifications
You must be signed in to change notification settings - Fork 394
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Migrate Studio Self hosted docs to dvc.org (#4344)
* Migrate Studio Selfhosted docs to dvc.org * Add Gitlab, Github, Troubleshooting pages * Fix indentation in GitHub docs * Use cli code blocks instead of shell * Selfhosted -> Self hosting * Apply suggestions from code reviews * Apply additional suggestions from code review * Add a page about custom CA certificates * Move Git forges to subsection * Use subsections instead of bold text * Add info tip to AMI guide * Rephrase sentence in AMI guide * Rephrase sentence in AMI guide * Elaborate on Studio's configuration * Fix links * Remove redundant admon --------- Co-authored-by: Thomas Kunwar <[email protected]>
- Loading branch information
Showing
32 changed files
with
692 additions
and
1 deletion.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
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----- | ||
``` |
3 changes: 3 additions & 0 deletions
3
content/docs/studio/self-hosting/configuration/git-forges/bitbucket.md
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,3 @@ | ||
# Bitbucket integration | ||
|
||
To be updated. |
76 changes: 76 additions & 0 deletions
76
content/docs/studio/self-hosting/configuration/git-forges/github.md
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,76 @@ | ||
# GitHub integration | ||
|
||
## Setting up the Github App | ||
|
||
1. Go to **Organization settings** -> **Developer settings** -> **Github Apps** | ||
-> **New Github App** | ||
|
||
Fill out the details as follows: | ||
|
||
![](/img/studio-selfhosted-github-1.png) | ||
|
||
![](/img/studio-selfhosted-github-2.png) | ||
|
||
![](/img/studio-selfhosted-github-3.png) | ||
|
||
![](/img/studio-selfhosted-github-4.png) | ||
|
||
2. Replace [`localhost:8080`](http://localhost:8080) with your Studio domain and | ||
port if applicable. | ||
|
||
3. Under permissions, set the following: | ||
|
||
**Repository permissions:** | ||
|
||
- Contents: Read / Write | ||
- Issues: Read / Write | ||
- Metadata: Read | ||
- Pull Requests: Read / Write | ||
- Webhooks: Read / Write | ||
|
||
**User permissions:** | ||
|
||
- Email addresses: Read | ||
|
||
4. Click **Create Github App** | ||
|
||
5. Copy the **App ID** and **Client ID** | ||
|
||
Click **Generate a new client secret**, copy the output | ||
|
||
![](/img/studio-selfhosted-github-5.png) | ||
|
||
6. Scroll down to **Private keys**, click **Generate a private key**, copy the | ||
output | ||
|
||
## Configuring Studio with the GitHub App | ||
|
||
Merge the `values.yaml` file with the following contents: | ||
|
||
```yaml | ||
scmProviders: | ||
github: | ||
enabled: true | ||
|
||
# Set this if you're using the selfhosted version | ||
url: <GitHub Enterprise URL> | ||
# Set this if you're using the selfhosted version | ||
apiUrl: <GitHub Enterprise API URL> | ||
|
||
clientId: <GitHub OAuth App Client ID> | ||
appName: <GitHub OAuth App Name> | ||
appId: <GitHub OAuth App ID> | ||
appSecret: <GitHub OAuth App Secret> | ||
privateKey: <GitHub OAuth App Private Key> | ||
|
||
# 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/github/ | ||
``` | ||
|
||
<admon type="info"> | ||
|
||
Replace the strings marked with `< >` | ||
|
||
</admon> |
92 changes: 92 additions & 0 deletions
92
content/docs/studio/self-hosting/configuration/git-forges/gitlab.md
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,92 @@ | ||
# GitLab integration | ||
|
||
## Creating the GitLab Application | ||
|
||
1. Go to **Admin Area** -> **Applications** -> **Applications** -> **New** | ||
**application** Fill out the details as follows | ||
|
||
![](/img/studio-selfhosted-gitlab-1.png) | ||
|
||
2. Replace [`localhost:8080`](http://localhost:8080) with your Studio domain and | ||
port if applicable. | ||
3. Click **Save application** | ||
4. Copy the **Application ID** and **Secret** | ||
|
||
![](/img/studio-selfhosted-gitlab-2.png) | ||
|
||
## Creating the webhook | ||
|
||
The webhooks are created automatically per repository. To check if the webhook | ||
got created: | ||
|
||
1. Go to repository **Settings -> Webhooks** | ||
2. Scroll down to see **Project Hooks** | ||
3. Check if there is a hook pointing to your Studio instance: | ||
|
||
![](/img/studio-selfhosted-gitlab-3.png) | ||
|
||
## Configuring Studio with the GitLab App | ||
|
||
Merge the `values.yaml` file with the following contents: | ||
|
||
```yaml | ||
scmProviders: | ||
gitlab: | ||
enabled: true | ||
|
||
# Set this if you're hosting GitLab on a | ||
# custom domain | ||
url: '' | ||
|
||
clientId: <GitLab OAuth App Client ID> | ||
secretKey: <GitLab OAuth App Secret Key> | ||
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/ | ||
``` | ||
|
||
<admon type="info"> | ||
|
||
Replace the strings marked with `< >` | ||
|
||
</admon> | ||
|
||
## Troubleshooting | ||
|
||
### GitLab Webhook didn’t get created | ||
|
||
If there is no webhook in the repository, it is likely due to the GitLab | ||
instance settings. | ||
|
||
By default, GitLab blocks webhook requests to local networks. To fix this, you | ||
need to whitelist your domain in GitLab: | ||
|
||
1. Open **Admin Area** in GitLab | ||
2. Go to **Settings -> Network** | ||
|
||
![](/img/studio-selfhosted-gitlab-4.png) | ||
|
||
1. Expand the **Outbound requests** panel | ||
|
||
![](/img/studio-selfhosted-gitlab-5.png) | ||
|
||
2. Select the checkbox: **Allow requests to the local network from system | ||
hooks** | ||
3. In the textbox, **Local IP addresses and domain names that hooks and services | ||
may access,** either write: | ||
|
||
- your studio domain, e.g. **studio.example.com** | ||
- IP network range, e.g. **10.0.0.0/16** | ||
|
||
So if Studio is configured with | ||
[https://studio.example.com](https://studio.example.com), write: | ||
|
||
```bash | ||
studio.example.com | ||
``` | ||
|
||
More examples of using the allowlist can be found in GitLab’s documentation: | ||
[Create an allowlist for local requests](https://docs.gitlab.com/ee/security/webhooks.html#create-an-allowlist-for-local-requests) |
17 changes: 17 additions & 0 deletions
17
content/docs/studio/self-hosting/configuration/git-forges/index.md
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,17 @@ | ||
# Git Forges | ||
|
||
Studio integrates with several Git forges (also referred to as SCM providers), | ||
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/git-forges/github) | ||
- [GitLab](/doc/studio/self-hosting/configuration/git-forges/gitlab) | ||
- [Bitbucket](/doc/studio/self-hosting/configuration/git-forges/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> |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,50 @@ | ||
# Configuration | ||
|
||
Studio gets provisioned by Helm, which uses a single YAML file for | ||
configuration, often referred to as `values.yaml` in our documentation. | ||
|
||
To learn more about Helm's configuration format, refer to the page | ||
[Values Files ](https://helm.sh/docs/chart_template_guide/values_files/) on the | ||
Helm website. | ||
|
||
## Updating the configuration | ||
|
||
<admon type="info"> | ||
|
||
If you've deployed Studio with the AMI, you'll need to SSH to the EC2 instance | ||
before continuing. | ||
|
||
</admon> | ||
|
||
To update the configuration and apply the changes, follow the instructions | ||
below: | ||
|
||
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. | ||
|
||
To integrate Studio with your Git forge (GitHub, GitLab, Bitbucket), see the | ||
[Git Forges](/doc/studio/self-hosting/configuration/git-forges) section. | ||
|
||
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. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,54 @@ | ||
# TLS certificates | ||
|
||
We strongly recommend deploying Studio with a TLS certificate. | ||
|
||
## Configuring up the TLS certificate and private key | ||
|
||
To configure TLS certificates to Studio, following the instructions below | ||
according to your installation method: | ||
|
||
<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 | ||
|
||
```cli | ||
$ scp studio.crt studio.pem ubuntu@my-ec2-instance:. | ||
``` | ||
|
||
2. Connect with SSH to your EC2 instance | ||
|
||
```cli | ||
$ ssh ubuntu@my-ec2-instance | ||
``` | ||
|
||
</admon> | ||
|
||
1. Store your TLS certificate and private key in an object | ||
|
||
```cli | ||
$ kubectl create secret tls studio-ingress-tls \ | ||
--namespace studio \ | ||
--cert=studio.crt \ | ||
--key=studio.pem | ||
``` | ||
|
||
2. Update Studio's config file | ||
|
||
Merge the `values.yaml` file with the following contents: | ||
|
||
```yaml | ||
global: | ||
ingress: | ||
tlsEnabled: true | ||
tlsSecretName: studio-ingress-tls | ||
``` | ||
3. Reload Studio | ||
```cli | ||
$ helm upgrade --wait studio iterative/studio --namespace studio -f values.yaml | ||
``` |
Oops, something went wrong.