docs(commercial): Add new docs for commercial vs core (#3203)

* docs(cloud): initial setup * docs(cloud): overhauled cloud vs core onboarding * docs(commercial): updated docker and k8s install * Update docs/docs/core/deployment/docker.md Co-authored-by: Julianne Fermi <julianne@kubeshop.io> * Update docs/docs/getting-started/open.mdx Co-authored-by: Julianne Fermi <julianne@kubeshop.io> * Update docs/docs/core/deployment/kubernetes.mdx Co-authored-by: Julianne Fermi <julianne@kubeshop.io> * Update docs/docs/getting-started/open.mdx Co-authored-by: Julianne Fermi <julianne@kubeshop.io> * Update docs/docs/getting-started/open.mdx Co-authored-by: Julianne Fermi <julianne@kubeshop.io> * Update docs/docs/getting-started/open.mdx Co-authored-by: Julianne Fermi <julianne@kubeshop.io> * Update docs/docs/getting-started/open.mdx Co-authored-by: Julianne Fermi <julianne@kubeshop.io> * Update docs/docs/getting-started/open.mdx Co-authored-by: Julianne Fermi <julianne@kubeshop.io> * docs(cloud): typos and fixes --------- Co-authored-by: Julianne Fermi <julianne@kubeshop.io>
kubeshop · Oct 4, 2023 · 0f6e827 · 0f6e827
1 parent 0c94f68
commit 0f6e827
Show file tree

Hide file tree

Showing 26 changed files with 1,075 additions and 628 deletions.
diff --git a/README.md b/README.md
@@ -264,7 +264,7 @@ tracetest run test --file /path/to/pokeshop_import.yaml
 
 Check out the [CI/CD docs](https://docs.tracetest.io/ci-cd-automation/overview) to learn more about test automation.
 
-# Tests
+# 🧪 Tests
 
 We strive to produce quality code and improve Tracetest rapidly and safely. Therefore, we have a full suite of both front-end and back-end tests. Cypress tests are running against the front-end code and (surprise, surprise) Tracetest against the back-end code. You can see the [test runs here](https://github.com/kubeshop/tracetest/actions/workflows/pull-request.yaml), and a blog post describing our [testing pipelines here](https://tracetest.io/blog/50-faster-ci-pipelines-with-github-actions).
 

diff --git a/docs/docs/configuration/server.md b/docs/docs/configuration/server.md
@@ -15,14 +15,28 @@ postgres:
   dbname: postgres
   params: sslmode=disable
 
-server: 
+telemetry:
+  exporters:
+    collector:
+      serviceName: tracetest
+      sampling: 100 # 100%
+      exporter:
+        type: collector
+        collector:
+          endpoint: otel-collector:4317
+
+server:
   httpPort: 11633
   pathPrefix: /
+  telemetry:
+    exporter: collector
+    applicationExporter: collector
 ```
 
 Alternatively, we support setting a series of environment variables which can contain the connection information for the Postgres instance. If these environment variables are set, they will be used by the Tracetest server to connect to the database.
 
 The list of environment variables and example values is:
+
 - `TRACETEST_POSTGRES_HOST: "postgres"`
 - `TRACETEST_POSTGRES_PORT: "5432"`
 - `TRACETEST_POSTGRES_DBNAME: "postgres"`
@@ -35,6 +49,4 @@ You can also change the defaults for the Tracetest server, altering the port and
 - `TRACETEST_SERVER_HTTPPORT=11633`
 - `TRACETEST_SERVER_PATHPREFIX="/"`
 
-
-You can also intitalize the server with a number of resources the first time it is launched by using [provisioning](./provisioning).
-
+You can also initialize the server with a number of resources the first time it is launched by using [provisioning](./provisioning).
diff --git a/docs/docs/deployment/docker.md → docs/docs/core/deployment/docker.md b/docs/docs/deployment/docker.md → docs/docs/core/deployment/docker.md
@@ -56,4 +56,4 @@ Starting tracetest ...
 
 Then launch a browser to [http://localhost:11633/](http://localhost:11633/).
 
-For more configuration options, read more in the [configuration docs](../configuration/overview.md).
+For more configuration options, visit the [configuration docs](/configuration/overview.md).
diff --git a/docs/docs/deployment/kubernetes.mdx → docs/docs/core/deployment/kubernetes.mdx b/docs/docs/deployment/kubernetes.mdx → docs/docs/core/deployment/kubernetes.mdx
@@ -89,4 +89,4 @@ kubectl apply -f ./tracetest-kubernetes-manifests.yaml
   </TabItem>
 </Tabs>
 
-For more configuration options, read more in the [configuration docs](../configuration/overview.md).
+For more configuration options, visit the [configuration docs](/configuration/overview.md).
diff --git a/docs/docs/deployment/overview.md → docs/docs/core/deployment/overview.md b/docs/docs/deployment/overview.md → docs/docs/core/deployment/overview.md
@@ -5,7 +5,7 @@ This section contains a general overview of deploying Tracetest in production. Y
 - [Docker](./docker)
 - [Kubernetes](./kubernetes)
 
-As shown in the diagram below, a typical production Tracetest deployment consists of Postgres, an OpenTelemetry Colletor and a [trace data store](../configuration/overview). But, if you do not want to use a trace data store, you can rely entirely on OpenTelemetry Collector.
+As shown in the diagram below, a typical production Tracetest deployment consists of Postgres, an OpenTelemetry Colletor and a [trace data store](/configuration/overview.md). But, if you do not want to use a trace data store, you can rely entirely on OpenTelemetry Collector.
 
 <!-- Add graph for Tracetest cluster -->
 
@@ -46,6 +46,6 @@ postgres:
   params: sslmode=disable
 ```
 
-Read more in the [configuration docs](../configuration/overview.md).
+Read more in the [configuration docs](/configuration/overview.md).
 
 Or, continue reading to see how to run Tracetest in production with [Docker](./docker) or [Kubernetes](./kubernetes).
diff --git a/docs/docs/core/getting-started/installation.mdx b/docs/docs/core/getting-started/installation.mdx
@@ -0,0 +1,300 @@
+---
+id: installation
+title: Installing Tracetest Core
+description: Tracetest allows you to quickly build integration and end-to-end tests, powered by your OpenTelemetry traces.
+keywords:
+  - tracetest
+  - trace-based testing
+  - observability
+  - distributed tracing
+  - testing
+image: https://res.cloudinary.com/djwdcmwdz/image/upload/v1689693872/docs/Blog_Thumbnail_28_ugy2yy.png
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+import CodeBlock from '@theme/CodeBlock';
+import GtagInstallCliTabs from '@site/src/components/GtagInstallCliTabs';
+
+This page showcases getting started with Tracetest Core by using the Tracetest CLI, Docker, or Kubernetes.
+
+This simple installation includes a demo app called [Pokeshop](/live-examples/pokeshop/overview.md) that will be installed alongside Tracetest Core. It shows how to configure OpenTelemetry and Tracetest Core and the architecture of the Pokeshop sample app.
+
+## Install the Tracetest CLI
+
+<GtagInstallCliTabs></GtagInstallCliTabs>
+
+:::tip Want more info?
+Read the CLI installation reference [here](/cli/cli-installation-reference.md).
+:::
+
+## Install the Tracetest Server
+
+Tracetest Core runs as a standalone container. It runs a Server and exposes a Web UI on port `11633`.
+
+You have three options to install Tracetest Server:
+
+- Using the Tracetest CLI to guide your installation in Docker and Kubernetes.
+- Using the official [Helm chart](https://github.com/kubeshop/helm-charts/tree/main/charts/tracetest).
+- Using the [Docker Compose Quick Start with the Pokeshop Sample App](https://github.com/kubeshop/tracetest/tree/main/examples/quick-start-pokeshop).
+
+<Tabs groupId="installation">
+  <TabItem value="cli" label="Tracetest CLI" default>
+
+```bash title="Terminal"
+tracetest server install
+```
+
+<Tabs groupId="container-orchestrators">
+  <TabItem value="docker-compose" label="Docker Compose" default>
+    <CodeBlock
+        language="text"
+        title="Terminal"
+    >
+    {`How do you want to run Tracetest? [type to search]:
+> Using Docker Compose
+  Using Kubernetes`}
+    </CodeBlock>
+
+Choose to install Tracetest with the OpenTelemetry Collector and the [Pokeshop](/live-examples/pokeshop/overview.md) sample app.
+
+```text title="Expected output:"
+Do you have OpenTelemetry based tracing already set up, or would you like us to install a demo tracing environment and app? [type to search]: 
+  I have a tracing environment already. - Just install Tracetest.
+> Just learning tracing! Install Tracetest, OpenTelemetry Collector and the sample app.
+```
+
+Choosing any option, this installer will create a `tracetest` directory in the current directory and add a `docker-compose.yaml` file to it.
+
+- If you choose the first option, the `docker-compose.yaml` will have only Tracetest Core and its dependencies.
+- **By choosing the second option, a sample app called [Pokeshop](/live-examples/pokeshop/overview.md) will be installed with Tracetest Core, allowing you to create sample tests right away!**
+
+<details>
+  <summary>
+    <b>Click to view Pokeshop Sample App Architecture</b>
+  </summary>
+
+Here's the Architecture of the Pokeshop Sample App:
+
+- an **API** that serves client requests,
+- a **Worker** who deals with background processes.
+
+The communication between the API and Worker is made using a `RabbitMQ` queue, and both services emit telemetry data to OpenTelemetry Collector and communicate with a Postgres database.
+
+Tracetest triggers tests against the Node.js API.
+
+```mermaid
+flowchart TD
+    A[(Redis)]
+    B[(Postgres)]
+    C(Node.js API)
+    D(RabbitMQ)
+    E(Worker)
+    F(OpenTelemetry Collector)
+    G(Tracetest)
+
+    G --> C
+    F --> G
+    C --> A
+    C --> B
+    C --> D
+    D --> E
+    E --> B
+    C --> F
+    E --> F
+    
+    
+```
+</details>
+
+**Start Docker Compose from the directory where you ran `tracetest server install`.**
+
+<CodeBlock
+  language="bash"
+  title="Terminal"
+>
+{`docker compose -f tracetest/docker-compose.yaml up -d`}
+</CodeBlock>
+
+This will start the Tracetest Server and expose the Web UI on [`http://localhost:11633`](http://localhost:11633).
+
+  </TabItem>
+  <TabItem value="kubernetes" label="Kubernetes">
+    <CodeBlock
+        language="text"
+        title="Terminal"
+    >
+    {`How do you want to run TraceTest? [type to search]:
+  Using Docker Compose
+> Using Kubernetes`}
+    </CodeBlock>
+
+Choose to install Tracetest Core with the OpenTelemetry Collector and the [Pokeshop](/live-examples/pokeshop/overview.md) sample app.
+
+```text title="Expected output:"
+Do you have OpenTelemetry based tracing already set up, or would you like us to install a demo tracing environment and app? [type to search]: 
+  I have a tracing environment already - Just install Tracetest.
+> Just learning tracing! Install Tracetest, OpenTelemetry Collector and the sample app.
+```
+
+Choosing any option, this installer will create a `tracetest` namespace in the Kubernetes context you choose and create deployments for Tracetest Core and its dependencies.
+
+- If you choose the first option, the `tracetest` namespace will only contain Tracetest Core and its dependencies.
+- **By choosing the second option, a sample app called [Pokeshop](/live-examples/pokeshop/overview.md) will be installed in a `demo` namespace alongside Tracetest Core, allowing you to create sample tests right away!**
+
+<details>
+  <summary>
+    <b>Click to view Pokeshop Sample App Architecture</b>
+  </summary>
+
+Here's the Architecture of the Pokeshop Sample App:
+
+- an **API** that serves client requests,
+- a **Worker** who deals with background processes.
+
+The communication between the API and Worker is made using a `RabbitMQ` queue, and both services emit telemetry data to OpenTelemetry Collector and communicate with a Postgres database.
+
+Tracetest triggers tests against the Node.js API.
+
+```mermaid
+flowchart TD
+    A[(Redis)]
+    B[(Postgres)]
+    C(Node.js API)
+    D(RabbitMQ)
+    E(Worker)
+    F(OpenTelemetry Collector)
+    G(Tracetest)
+
+    G --> C
+    F --> G
+    C --> A
+    C --> B
+    C --> D
+    D --> E
+    E --> B
+    C --> F
+    E --> F
+    
+    
+```
+</details>
+
+**Access the Tracetest Server by port forwarding to the Tracetest `service`.**
+
+```bash title=Terminal
+export POD_NAME=$(kubectl get pods --namespace demo -l "app.kubernetes.io/name=pokemon-api,app.kubernetes.io/instance=demo" -o jsonpath="{.items[0].metadata.name}")
+export CONTAINER_PORT=$(kubectl get pod --namespace demo $POD_NAME -o jsonpath="{.spec.containers[0].ports[0].containerPort}")
+kubectl --namespace demo port-forward $POD_NAME 8080:$CONTAINER_PORT
+echo "Open http://127.0.0.1:8080 to view the Pokeshop demo app"
+
+kubectl --kubeconfig <path-to-your-home>/.kube/config --context <your-cluster-context> --namespace tracetest port-forward svc/tracetest 11633
+echo "Open http://127.0.0.1:11633 to view the Tracetest Web UI"
+```
+
+Access the Tracetest Web UI on [`http://localhost:11633`](http://localhost:11633).
+
+  </TabItem>
+</Tabs>
+
+  </TabItem>
+  <TabItem value="helm" label="Helm Chart">
+
+First, be sure that you have [Helm](https://helm.sh/) installed in your machine.
+
+The Tracetest Helm charts are located [here](https://github.com/kubeshop/helm-charts/tree/main/charts/tracetest).
+
+You can install them locally on your machine with the command:
+
+```bash title=Terminal
+helm repo add kubeshop https://kubeshop.github.io/helm-charts
+helm repo update
+```
+
+After that, you can install Tracetest with `helm install`:
+
+```bash title=Terminal
+helm install tracetest kubeshop/tracetest --namespace=tracetest --create-namespace
+```
+
+Or, generate a manifest file and apply it manually in your Kubernetes cluster:
+
+```bash title=Terminal
+helm template tracetest kubeshop/tracetest > tracetest-kubernetes-manifests.yaml
+kubectl apply -f ./tracetest-kubernetes-manifests.yaml
+```
+
+**Access the Tracetest Server by port forwarding to the Tracetest `service`.**
+
+```bash title=Terminal
+kubectl --kubeconfig <path-to-your-home>/.kube/config --context <your-cluster-context> --namespace tracetest port-forward svc/tracetest 11633
+```
+
+Access the Tracetest Web UI on [`http://localhost:11633`](http://localhost:11633).
+
+  </TabItem>
+  <TabItem value="docker-compose" label="Docker Compose">
+
+First, be sure that you have [Docker](https://docker.com/) installed in your machine.
+
+The Quick Start with the Pokeshop Sample App is located [here](https://github.com/kubeshop/tracetest/tree/main/examples/quick-start-pokeshop).
+
+**The [`docker-compose.yaml`](https://github.com/kubeshop/tracetest/blob/main/examples/quick-start-pokeshop/docker-compose.yml) contains Tracetest Core, the OpenTelemetry Collector, and a sample app called [Pokeshop](/live-examples/pokeshop/overview.md). This allows you to create sample tests right away!**
+
+<details>
+  <summary>
+    <b>Click to view Pokeshop Sample App Architecture</b>
+  </summary>
+
+Here's the Architecture of the Pokeshop Sample App:
+
+- an **API** that serves client requests,
+- a **Worker** who deals with background processes.
+
+The communication between the API and Worker is made using a `RabbitMQ` queue, and both services emit telemetry data to OpenTelemetry Collector and communicate with a Postgres database.
+
+Tracetest triggers tests against the Node.js API.
+
+```mermaid
+flowchart TD
+    A[(Redis)]
+    B[(Postgres)]
+    C(Node.js API)
+    D(RabbitMQ)
+    E(Worker)
+    F(OpenTelemetry Collector)
+    G(Tracetest)
+
+    G --> C
+    F --> G
+    C --> A
+    C --> B
+    C --> D
+    D --> E
+    E --> B
+    C --> F
+    E --> F
+    
+    
+```
+</details>
+
+**Start Docker Compose.**
+
+<CodeBlock
+  language="bash"
+  title="Terminal"
+>
+{`docker compose -f docker-compose.yaml up -d`}
+</CodeBlock>
+
+This will start the Tracetest Server and expose the Web UI on [`http://localhost:11633`](http://localhost:11633).
+
+  </TabItem>
+</Tabs>
+
+:::tip Don't have OpenTelemetry installed?
+Tracetest requires that you have [OpenTelemetry instrumentation](https://opentelemetry.io/docs/instrumentation/) added in your code, and configured [sending traces to a trace data store](/configuration/connecting-to-data-stores/jaeger.md), or [Tracetest directly](/configuration/connecting-to-data-stores/opentelemetry-collector.md).
+
+[Follow these instructions to install OpenTelemetry in 5 minutes without any code changes!](/getting-started/no-otel.mdx)
+:::