Skip to content

Commit

Permalink
Migrate Studio Self hosted docs to dvc.org (#4344)
Browse files Browse the repository at this point in the history
* 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
jesper7 and yathomasi authored Mar 9, 2023
1 parent 04903de commit c684c68
Show file tree
Hide file tree
Showing 32 changed files with 692 additions and 1 deletion.
64 changes: 63 additions & 1 deletion content/docs/sidebar.json
Original file line number Diff line number Diff line change
Expand Up @@ -619,7 +619,69 @@
"connect-custom-gitlab-server"
]
},
"troubleshooting"
"troubleshooting",
{
"slug": "self-hosting",
"source": false,
"children": [
{
"slug": "installation",
"source": "installation/index.md",
"children": [
{
"label": "AWS AMI",
"slug": "aws-ami"
},
{
"label": "Kubernetes (Helm)",
"slug": "k8s-helm"
}
]
},
{
"slug": "configuration",
"source": "configuration/index.md",
"children": [
{
"label": "TLS certificates",
"slug": "tls"
},
{
"label": "CA certificates",
"slug": "ca"
},
{
"slug": "git-forges",
"source": "git-forges/index.md",
"children": [
{
"label": "GitHub",
"slug": "github"
},
{
"label": "GitLab",
"slug": "gitlab"
},
{
"label": "Bitbucket",
"slug": "bitbucket"
}
]
}
]
},
{
"slug": "troubleshooting",
"source": false,
"children": [
{
"label": "502 Service Unavailable",
"slug": "502"
}
]
}
]
}
]
},
{
Expand Down
16 changes: 16 additions & 0 deletions content/docs/studio/self-hosting/configuration/ca.md
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-----
```
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
# Bitbucket integration

To be updated.
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>
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 content/docs/studio/self-hosting/configuration/git-forges/index.md
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>
50 changes: 50 additions & 0 deletions content/docs/studio/self-hosting/configuration/index.md
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.
54 changes: 54 additions & 0 deletions content/docs/studio/self-hosting/configuration/tls.md
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
```
Loading

0 comments on commit c684c68

Please sign in to comment.