1 files changed, 229 insertions, 0 deletions
diff --git a/doc/operations/quickstart-guide.md b/doc/operations/quickstart-guide.md
new file mode 100644
index 00000000000..91c5f25405c
--- /dev/null
+++ b/doc/operations/quickstart-guide.md
@@ -0,0 +1,229 @@
+---
+stage: Monitor
+group: Observability
+info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments
+---
+
+# GitLab Observability Quickstart
+
+You can try GitLab Observability by [cloning or forking the project](https://gitlab.com/gitlab-org/opstrace/opstrace.git) and creating a local installation.
+
+## Prerequisites and dependencies
+
+To install GitLab Observability Platform (GOP), install and configure the following third-party dependencies. You can do this manually, or [automatically by using asdf](#install-dependencies-using-asdf):
+
+- [kind](https://kind.sigs.k8s.io/docs/user/quick-start/#installation) for creating a local Kubernetes cluster.
+- [Docker](https://docs.docker.com/install)
+  - [Docker Compose](https://docs.docker.com/compose/compose-v2/) is now part of the `docker` distribution.
+- [kubectl](https://kubernetes.io/docs/tasks/tools/#kubectl) for interacting with GitLab Observability.
+- [Telepresence](https://www.telepresence.io/) allows you to code and test microservices locally against a remote Kubernetes cluster.
+- [jq](https://stedolan.github.io/jq/download/) for some Makefile utilities.
+- [Go 1.19](https://go.dev/doc/install).
+
+The current versions of these dependencies are pinned in the `.tool-versions` file in the project.
+
+You can run the following commands to check the availability and versions of these dependencies on your machine:
+
+```shell
+kind --version
+docker --version
+kubectl version
+telepresence version
+jq --version
+go version
+```
+
+### Run GOP on macOS
+
+If you're running GOP on macOS, ensure you have enough resources dedicated to Docker Desktop. The recommended minimum is:
+
+- CPUs: 4+
+- Memory: 8 GB+
+- Swap: 1 GB+
+
+It's possible to run GOP with fewer resources, but this specification works.
+
+### Install dependencies using asdf
+
+If you install dependencies using [`asdf`](https://asdf-vm.com/#/core-manage-asdf), GOP manages them for you automatically.
+
+1. If you have not already done so, clone the `opstrace` repository into your preferred location:
+
+   ```shell
+   git clone https://gitlab.com/gitlab-org/opstrace/opstrace.git
+   ```
+
+1. Change into the project directory:
+
+   ```shell
+   cd opstrace
+   ```
+
+1. Optional. If you need to install `asdf`, run:
+
+   ```shell
+   make install-asdf
+   ```
+
+1. Install dependencies using `asdf`:
+
+   ```shell
+   make bootstrap
+   ```
+
+## Step 1: Create a local Kubernetes cluster with kind
+
+Make sure Docker Desktop is running. In the `opstrace` project you cloned, run the following command:
+
+```shell
+make kind
+```
+
+Wait a few minutes while kind creates your Kubernetes cluster. When it's finished, you should see the following message:
+
+```plaintext
+Traffic Manager installed successfully
+```
+
+Now deploy the scheduler by running the following command in the `opstrace` project:
+
+```shell
+make deploy
+```
+
+This takes around 1 minute.
+
+## Step 2: Create a GitLab application for authentication
+
+You must create a GitLab application to use for authentication.
+
+In the GitLab instance you'd like to connect with GOP, [create an OAuth application](../integration/oauth_provider.md).
+This application can be a user-owned, group-owned or instance-wide application.
+In production, you would create a trusted instance-wide application so that users are explicitly authorized without the consent screen.
+The following example shows how to configure the application.
+
+1. Select the API scope and enter `http://localhost/v1/auth/callback` as the redirect URI.
+
+1. Run the following command to create the secret that holds the authentication data:
+
+   ```shell
+   kubectl create secret generic \
+       --from-literal=gitlab_oauth_client_id=<gitlab_application_client_id> \
+       --from-literal=gitlab_oauth_client_secret=<gitlab_application_client_secret> \
+       --from-literal=internal_endpoint_token=<error_tracking_internal_endpoint_token> \
+        dev-secret
+   ```
+
+1. Replace `<gitlab_application_client_id>` and `<gitlab_application_client_secret>` with the values from the GitLab application you just created.
+Replace `<error_tracking_internal_endpoint_token>` with any string if you do not plan to use error tracking.
+
+You can also view [this MR on how to get the token to test error tracking](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/91928).
+You must specify all the parameters when creating the secret.
+
+## Step 3: Create the cluster definition
+
+1. In your `opstrace` project, run the following command to create a `Cluster.yaml` manifest file:
+
+   ```shell
+   cat <<EOF > Cluster.yaml
+   apiVersion: opstrace.com/v1alpha1
+   kind: Cluster
+   metadata:
+     name: dev-cluster
+   spec:
+     target: kind
+     goui:
+       image: "registry.gitlab.com/gitlab-org/opstrace/opstrace-ui/   gitlab-observability-ui:c9fb6e70"
+     dns:
+       acmeEmail: ""
+       dns01Challenge: {}
+       externalDNSProvider: {}
+     gitlab:
+       groupAllowedAccess: '*'
+       groupAllowedSystemAccess: "6543"
+       instanceUrl: https://gitlab.com
+       authSecret:
+         name: dev-secret
+   EOF
+   ```
+
+1. Apply the file you just created with the following command:
+
+   ```shell
+   kubectl apply -f Cluster.yaml
+   ```
+
+1. Run the following command to wait for the cluster to be ready:
+
+   ```shell
+   kubectl wait --for=condition=ready cluster/dev-cluster --timeout=600s
+   ```
+
+After the previous command exits, the cluster is ready.
+
+## Step 4: Enable Observability on a GitLab namespace you own
+
+Go to a namespace you own in the connected GitLab instance and copy the Group ID below the group name.
+
+GOP can only be enabled for groups you own.
+To list all the groups that your user owns, go to the menu in upper left corner and select `Groups`->`View all Groups`. You then see the **Your groups** tab.
+
+In your browser, go to `http://localhost/-/{GroupID}`. For example, `http://localhost/-/14485840`.
+
+Follow the on-screen instructions to enable observability for the namespace.
+This can take a couple of minutes if it's the first time observability has been enabled for the root level namespace (GitLab.org in the previous example.)
+
+Once your namespace has been enabled and is ready, the page automatically redirects you to the GitLab Observability UI.
+
+## Step 5: Send traces to GOP
+
+[Follow this guide to send traces to your namespace and monitor them in the UI](https://gitlab.com/gitlab-org/opstrace/opstrace/-/blob/main/docs/guides/user/sending-traces-locally.md).
+
+## Step 6: Clean up your local GOP
+
+To tear down your locally running GOP instance, run the following command:
+
+```shell
+make destroy
+```
+
+## Known issues
+
+### Incorrect architecture for `kind/node` image
+
+If your machine has an Apple silicon (M1/M2) chip, you might encounter an architecture problem with the `kind/node` image when running the `make kind` command. For more details, see [issue 1802](https://gitlab.com/gitlab-org/opstrace/opstrace/-/issues/1802).
+
+To fix this problem, you first need to create a Dockerfile. Then build and deploy the image:
+
+1. Create a new Dockerfile (without a file extension) and paste the following commands:
+
+   ```Dockerfile
+   FROM --platform=arm64 kindest/node:v1.23.13
+   RUN arch
+   ```
+
+1. Save your Dockerfile, then build the image with the following command:
+
+   ```shell
+   docker build -t tempkind .
+   ```
+
+   Do not forget the period at the end.
+
+1. Create a cluster using your new image with the following command:
+
+   ```shell
+   kind create cluster --image tempkind
+   ```
+
+### scheduler-controller-manager pod cannot start due to ImagePullBackOff
+
+If while executing `make deploy` in step 1, the `scheduler-controller-manager` pod cannot start due to `ImagePullBackOff`, you must set the `CI_COMMIT_TAG` to a non-dirty state. By setting the commit tag to the latest commit, you ensure the Docker image can be pulled from the container registry.
+
+Run the following command to set the commit tag:
+
+```shell
+make kind
+export CI_COMMIT_TAG=0.2.0-e1206acf
+make deploy
+```