Migrate Studio Self hosted docs to dvc.org

content/docs/sidebar.json

@@ -614,7 +614,55 @@
           "connect-custom-gitlab-server"
         ]
       },
-      "troubleshooting"
+      "troubleshooting",
+      {
+        "slug": "selfhosted",
+        "source": false,
+        "children": [
+          {
+            "slug": "installation",
+            "source": "installation/index.md",
+            "children": [
+              {
+                "label": "AMI",
+                "slug": "ami"
+              },
+              {
+                "label": "Helm",
+                "slug": "helm"
+              }
+            ]
+          },
+          {
+            "slug": "configuration",
+            "source": "configuration/index.md",
+            "children": [
+              {
+                "label": "TLS certificates",
+                "slug": "tls"
+              },
+              {
+                "label": "GitHub integration",
+                "slug": "github"
+              },
+              {
+                "label": "GitLab integration",
+                "slug": "gitlab"
+              }
+            ]
+          },
+          {
+            "slug": "troubleshooting",
+            "source": false,
+            "children": [
+              {
+                "label": "502 Service Unavailable",
+                "slug": "502"
+              }
+            ]
+          }
+        ]
+      }
     ]
   },
   {

content/docs/studio/selfhosted/configuration/github.md

@@ -0,0 +1,75 @@
+# 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: <GitHub Webhook URL, e.g. https://<domain>/webhook/github/>
+```
+
+<admon type="info">
+
+Replace the strings marked with < >
+
+</admon>

content/docs/studio/selfhosted/configuration/gitlab.md

@@ -0,0 +1,89 @@
+# 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>
+
+    webhookUrl: <GitLab Webhook URL>
+    webhookSecret: <GitLab Webhook Secret>
+```
+
+<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](http://gitlab-customca.iterative.ai/help/security/webhooks.md#create-an-allowlist-for-local-requests)

content/docs/studio/selfhosted/configuration/index.md

@@ -0,0 +1,76 @@
+# Configuration
+
+Studio has a unified YAML configuration file, often referred to as `values.yaml`
+in the documentation.
+
+## Updating the configuration
+
+To update the configuration and reload Studio, follow the instructions according
+to your installation method:
+
+<toggle>
+<tab title="AMI">
+
+1. Connect with SSH to your EC2 instance
+
+```shell
+$ ssh ubuntu@my-ec2-instance
+```
+
+2. 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
+
+```shell
+$ helm upgrade --wait studio iterative/studio --namespace studio -f values.yaml
+```
+
+</tab>
+
+<tab title="Helm">
+
+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
+```
+
+2. Reload Studio
+
+```shell
+$ helm upgrade --wait studio iterative/studio --namespace studio -f values.yaml
+```
+
+</tab>
+
+</toggle>
+
+## 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, each of which are configured
+differently:
+
+- [GitHub](/doc/studio/selfhosted/configuration/github)
+- [GitLab](/doc/studio/selfhosted/configuration/gitlab)
+
+Additionally, you may want be interested in the following:
+
+- [TLS certificates](/doc/studio/selfhosted/configuration/tls)

content/docs/studio/selfhosted/configuration/tls.md

@@ -0,0 +1,83 @@
+# 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:
+
+<toggle>
+<tab title="AMI">
+
+1. Transfer your TLS certificate and private key to the EC2 instance
+
+```shell
+$ scp studio.crt studio.pem ubuntu@my-ec2-instance:.
+```
+
+2. Connect with SSH to your EC2 instance
+
+```shell
+$ 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">
+
+1. 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
+```
+
+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
+
+```shell
+$ helm upgrade --wait studio iterative/studio --namespace studio -f values.yaml
+```
+
+</tab>
+
+</toggle>