docs(getting-started): updated flow and added on-prem (#3956)

kubeshop · Aug 12, 2024 · 7b1d1a5 · 7b1d1a5
1 parent 30daeaa
commit 7b1d1a5
Show file tree

Hide file tree

Showing 5 changed files with 131 additions and 107 deletions.
diff --git a/docs/docs/getting-started/installation.mdx b/docs/docs/getting-started/installation.mdx
@@ -17,21 +17,30 @@ import TabItem from '@theme/TabItem';
 import CodeBlock from '@theme/CodeBlock';
 import GtagInstallCliTabs from '@site/src/components/GtagInstallCliTabs';
 
-This page showcases getting started with [Tracetest](https://app.tracetest.io/) by using the Tracetest CLI and Tracetest Agent.
+This page showcases getting started with [Tracetest](https://app.tracetest.io/).
+
+You can configure Cloud-based Managed Tracetest by using the Tracetest CLI and Tracetest Agent, or Enterprise Self-hosted Tracetest in your own infrastructure.
+
+<Tabs groupId="saas-onprem">
+<TabItem value="saas" label="Cloud-based Managed Tracetest" default>
 
 ## Install the Tracetest CLI
 
 <GtagInstallCliTabs></GtagInstallCliTabs>
 
+1. [Sign in to Tracetest](https://app.tracetest.io/).
+2. Create an [Organization](/concepts/organizations) and [Environment](/concepts/environments).
+3. Copy the default [Tracetest Organization API Key/Token](/concepts/organization-tokens) from your Tracetest Organization Tokens page. (Or create a new token.)
+4. Copy the Environment ID from your Tracetest Environment Settings page.
+5. Configure the CLI with your Organization API Key/Token and Environment ID.
 
-<Tabs groupId="saas-onprem">
-<TabItem value="saas" label="Cloud-based Managed Tracetest" default>
+```bash title="Terminal"
+tracetest configure -t <TRACETEST_API_KEY> --environment <TRACETEST_ENVIRONMENT_ID>
+```
 
 ## Install the Tracetest Agent
 
-[Tracetest Agent](/concepts/agent) runs as a standalone process. It runs either locally on your machine or as a container. Once started, Tracetest Agent exposes OTLP ports `4317` (gRPC) and `4318` (HTTP) for trace ingestion. It executes tests in the environment where it is running and returns the response from triggered tests.
-
-[Sign in to Tracetest](https://app.tracetest.io/), and get your [Tracetest Agent API Key](/configuration/agent).
+[Tracetest Agent](/concepts/agent) runs as a standalone process. It runs either locally on your machine or as a container.
 
 <Tabs groupId="installation">
 <TabItem value="cli" label="Tracetest CLI" default>
@@ -40,23 +49,26 @@ This page showcases getting started with [Tracetest](https://app.tracetest.io/)
   language="text"
   title="Terminal"
 >
-{`tracetest start --api-key <your_api_key>`}
+{`tracetest start --api-key <TRACETEST_API_KEY> --environment <TRACETEST_ENVIRONMENT_ID>`}
 </CodeBlock>
 
 <CodeBlock
   language="text"
   title="Expected output:"
 >
-{`Defaulting to only available Environment: localMode
-  INFO Connecting Agent with name local to Organization org_name and Environment localMode
-  INFO Starting Agent with name local...
-Agent is started! Leave the terminal open so tests can be run and traces gathered from this environment (env_name).
-You can: [type to search]:
+{`Tracetest start launches a lightweight agent. It enables you to run tests and collect traces with Tracetest.
+Once started, Tracetest Agent exposes OTLP ports 4317 and 4318 to ingest traces via gRCP and HTTP.
+
+ INFO  Running in desktop mode...
+ INFO  Starting Agent with name Adnans-Air...
+Agent is started! Leave the terminal open so tests can be run and traces gathered from this environment.
+You can:
 > Open Tracetest in a browser to this environment
+  (Experimental) Open Dashboard
   Stop this agent`}
 </CodeBlock>
 
-The Tracetest Agent is running and ready to accept traces.
+Once started, Tracetest Agent exposes OTLP ports `4317` (gRPC) and `4318` (HTTP) for trace ingestion. It executes tests in the environment where it is running and returns the response from triggered tests.
 
 gRPC: `http://localhost:4317`
 
@@ -69,20 +81,46 @@ HTTP: `http://localhost:4318/v1/traces`
     language="text"
     title="Terminal"
 >
-{`docker run \\\n-p 4317:4317 \\\n-p 4318:4318 \\\n-e TRACETEST_API_KEY="<your_api_key>" \\\nkubeshop/tracetest-agent`}
+{`docker run \\\n  -p 4317:4317 \\\n  -p 4318:4318 \\\n  -e TRACETEST_API_KEY="<TRACETEST_API_KEY>" \\\n  -e TRACETEST_ENVIRONMENT_ID="<TRACETEST_ENVIRONMENT_ID>" \\\n  kubeshop/tracetest-agent`}
 </CodeBlock>
 
+The Tracetest Agent is running in Docker and ready to accept traces.
+
+gRPC: `http://<service-name>:4317`
+
+HTTP: `http://<service-name>:4318/v1/traces`
+
+:::note Docker Network
+Running a test against `localhost` will resolve as `127.0.0.1` inside the Tracetest Agent container.
+
+To run tests against apps running on your local machine you have two options:
+
+1. Run Tracetest Agent locally with the `tracetest start` command.
+2. Add Tracetest Agent to the same network and use service name mapping. *Example: Instead of running an app on `localhost:8080`, add it to your Docker Compose file, connect it to the same network as your Tracetest Agent service, and use `<service-name>:8080` in the URL field when creating a test.*
+
+You can reach services running on your local machine using:
+
+- Linux (docker version < 20.10.0): `172.17.0.1:8080`
+- MacOS (docker version >= 18.03) and Linux (docker version >= 20.10.0): `host.docker.internal:8080`
+:::
+
+</TabItem>
+<TabItem value="docker-compose" label="Docker Compose" default>
+
 <CodeBlock
-  language="text"
-  title="Expected output:"
+    language="text"
+    title="Terminal"
 >
-{`Defaulting to only available Environment: localMode
-  INFO Connecting Agent with name local to Organization org_name and Environment localMode
-  INFO Starting Agent with name local...
-Agent is started! Leave the terminal open so tests can be run and traces gathered from this environment (env_name).
-You can: [type to search]:
-> Open Tracetest in a browser to this environment
-  Stop this agent`}
+{`tracetest-agent:
+  image: kubeshop/tracetest-agent
+  command:
+    - "--mode=verbose"
+  environment:
+    - TRACETEST_API_KEY=<TRACETEST_API_KEY>
+    - TRACETEST_ENVIRONMENT_ID=<TRACETEST_ENVIRONMENT_ID>
+  ports:
+    - 4317:4317
+    - 4318:4318`}
 </CodeBlock>
 
 The Tracetest Agent is running in Docker and ready to accept traces.
@@ -91,7 +129,7 @@ gRPC: `http://<service-name>:4317`
 
 HTTP: `http://<service-name>:4318/v1/traces`
 
-:::note
+:::note Docker Network
 Running a test against `localhost` will resolve as `127.0.0.1` inside the Tracetest Agent container.
 
 To run tests against apps running on your local machine you have two options:
@@ -112,20 +150,7 @@ You can reach services running on your local machine using:
     language="text"
     title="Terminal"
 >
-{`curl https://raw.githubusercontent.com/kubeshop/tracetest/main/k8s/agent/deploy-agent.sh | bash -s -- default <your_api_key>`}
-</CodeBlock>
-
-<CodeBlock
-  language="text"
-  title="Expected output:"
->
-{`Defaulting to only available Environment: localMode
-  INFO Connecting Agent with name local to Organization org_name and Environment localMode
-  INFO Starting Agent with name local...
-Agent is started! Leave the terminal open so tests can be run and traces gathered from this environment (env_name).
-You can: [type to search]:
-> Open Tracetest in a browser to this environment
-  Stop this agent`}
+{`curl https://raw.githubusercontent.com/kubeshop/tracetest/main/k8s/agent/deploy-agent.sh | bash -s -- default <TRACETEST_API_KEY>`}
 </CodeBlock>
 
 The Tracetest Agent is running in Kubernetes and ready to accept traces.
@@ -134,7 +159,7 @@ gRPC: `http://<service-name>:4317`
 
 HTTP: `http://<service-name>:4318/v1/traces`
 
-:::note
+:::note K8s Network
 Running a test against `localhost` will resolve as `127.0.0.1` inside the Tracetest Agent container.
 
 To run tests against apps running on your local machine you have two options:
@@ -151,13 +176,69 @@ You can reach services running on your local machine using:
 </TabItem>
 </Tabs>
 
+## Start the Sample Pokeshop API
+
+To create tests quickly, start the official sample called [Pokeshop API](/live-examples/pokeshop/overview).
+
+```bash title="Terminal"
+git clone --depth 1 https://github.com/kubeshop/tracetest.git
+cd tracetest/examples/tracetest-agent/pokeshop/
+
+docker compose up -d --build
+```
+
+- [`https://app.tracetest.io/`](https://app.tracetest.io) - Access the Tracetest Web UI. Sign up and create an organization.
+- [`http://localhost:8081`](http://localhost:8081) and [`http://localhost:8081`](http://localhost:8081) - Access the Pokeshop API demo to run tests.
+- `http://localhost:4317` / `http://localhost:4318` / `http://service-name:4317` / `http://service-name:4318` - Trace ingestion URL where Tracetest Agent will accept traces.
+
+
+<details>
+  <summary>
+    <b>Click to view the sample Pokeshop API 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>
+
 </TabItem>
 <TabItem value="on-prem" label="Enterprise Self-hosted Tracetest" default>
 
 ## Install Tracetest On-Prem
 
-:::note
+:::tip For Development Environment
 This installation is meant for testing purposes only. It uses self signed certificates, so your browser will show a warning about it.
+
+For the Production-ready installation, [view the official Helm chart readme](https://github.com/kubeshop/tracetest-cloud-charts/blob/main/README.md).
 :::
 
 1. Install [Helm](https://helm.sh/) and [kind](https://kind.sigs.k8s.io/) on your machine. Clone the official Tracetest Helm chart.

diff --git a/docs/docs/getting-started/open.mdx b/docs/docs/getting-started/open.mdx
@@ -11,63 +11,7 @@ keywords:
 image: https://res.cloudinary.com/djwdcmwdz/image/upload/v1698686403/docs/Blog_Thumbnail_14_rsvkmo.jpg
 ---
 
-This page showcases opening the Tracetest Web UI and creating a test against the [microservice sample Pokeshop API](/live-examples/pokeshop/overview).
-
-Once you've signed in to Tracetest, as explained in the [installation guide](./installation.mdx), the [Tracetest Agent](/concepts/agent) is running in your environment on ports `4317` and `4318`, or you'll get an API endpoint if you're using the [Tracetest Cloud Agent](/concepts/cloud-agent).
-
-You access the Tracetest Web UI on [`app.tracetest.io`](https://app.tracetest.io). Here's what will greet you after a fresh install.
-
-![Landing page Tracetest](https://res.cloudinary.com/djwdcmwdz/image/upload/v1688474565/docs/screely-1688474539641_kbhvvc.png)
-
-## Start the Sample Pokeshop API
-
-To create tests quickly, start the official sample called Pokeshop API.
-
-```bash title=Terminal
-git clone --depth 1 https://github.com/kubeshop/tracetest.git
-cd tracetest/examples/tracetest-agent/pokeshop/
-docker-compose up
-```
-
-This will start an HTTP API on `localhost:8081` and a GRPC API on `localhost:8082`.
-
-<details>
-  <summary>
-    <b>Click to view the sample Pokeshop API 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>
+This page showcases opening [Tracetest](https://app.tracetest.io/) for the first time and creating tests.
 
 ## Creating Trace-based Tests
 

diff --git a/docs/docs/getting-started/overview.mdx b/docs/docs/getting-started/overview.mdx
@@ -23,25 +23,21 @@ import {TracetestGettingStartedGuideCardsRow, TracetestCoreGettingStartedGuideCa
 Tracetest is a cloud-native application, designed to run in the cloud. Get started in three ways.
 
 - **[Cloud-based Managed Tracetest](https://app.tracetest.io/) (Free to get started!)**: Use managed infrastructure with collaboration for teams, and additional features on top of Tracetest Core.
-- **[Enterprise Self-hosted Tracetest](https://tracetest.io/on-prem-installation)**: Same experience as with Cloud-based Managed Tracetest but self-hosted in your own infrastructure. **([Request a demo!](https://dub.sh/tracetest-demo))**
+- **[Enterprise Self-hosted Tracetest](https://tracetest.io/on-prem-installation) (Free trial, no credit card required)**: Same experience as with Cloud-based Managed Tracetest but self-hosted in your own infrastructure. **([Request a demo!](https://dub.sh/tracetest-demo))**
 - **[Hobby Self-hosted Open-source Tracetest Core](/core/getting-started/overview)**: Deploy a hobby instance in your own infrastructure with Docker or Kubernetes. Not suitable for production workloads.
 
-## Cloud-based Managed Tracetest
+## Cloud-based Managed Tracetest and Enterprise Self-hosted Tracetest
 
 **We recommend using [Cloud-based Managed Tracetest](https://app.tracetest.io/)**. It's the easiest way to test microservices and distributed apps with OpenTelemetry distributed traces. Tracetest provides managed infrastructure, [collaboration for teams](/concepts/environments), [RBAC](/concepts/roles-and-permissions), [organizations](/concepts/organizations), [dependency-free config](/concepts/agent), [agentless serverless config](/concepts/cloud-agent), and much more.
 
 Get started with the installation guide below, tailored for microservice and distributed app developers. You may find it insightful even if you have [one of many other supported use cases](/examples-tutorials/recipes).
 
+If your organization requires you to keep data on-prem, you can use Enterprise Self-hosted Tracetest and deploy it in your own infrastructure. It contains the same features as Cloud-based Managed Tracetest. [Request a license key for Enterprise Self-hosted Tracetest, here.](https://tracetest.io/on-prem-installation)
+
 ```mdx-code-block
 <TracetestGettingStartedGuideCardsRow />
 ```
 
-## Enterprise Self-hosted Tracetest
-
-If your organization requires you to keep data on-prem, you can use Enterprise Self-hosted Tracetest and deploy it in your own infrastructure. It contains the same features as Cloud-based Managed Tracetest.
-
-We recommend you try [Cloud-based Managed Tracetest](https://app.tracetest.io/) as a trial, and reach out to us to [request a demo](https://dub.sh/tracetest-demo) for Enterprise Self-hosted Tracetest.
-
 ### Features Available in Cloud-based Managed Tracetest and Enterprise Self-hosted Tracetest
 
 #### All Tracetest Core features, plus...

diff --git a/docs/docs/index.mdx b/docs/docs/index.mdx
@@ -108,9 +108,9 @@ Tracetest is a cloud-native application, designed to run in the cloud. [Get star
 
 The easiest and most reliable way to test microservices and distributed apps with OpenTelemetry distributed traces is signing up for free at [app.tracetest.io](https://app.tracetest.io/). After creating an account, getting started is as easy as [installing the Tracetest Agent](/getting-started/installation).
 
-### Enterprise Self-hosted Tracetest (Coming soon...)
+### Enterprise Self-hosted Tracetest (Free trial, no credit card required)
 
-Get the same experience as with the Cloud-based Managed Tracetest but self-hosted in your own infrastructure. [Book a call](https://dub.sh/tracetest-demo) to get into early access.
+Get the same experience as with the Cloud-based Managed Tracetest but self-hosted in your own infrastructure. [Request a license key](https://tracetest.io/on-prem-installation) or [book a call](https://dub.sh/tracetest-demo) to get a trial.
 
 ### Hobby Self-hosted Open-source Tracetest Core
 

diff --git a/examples/quick-start-nodejs/docker-compose.yaml b/examples/quick-start-nodejs/docker-compose.yaml
@@ -13,9 +13,12 @@ services:
   # Cloud-based Managed Tracetest
   tracetest-agent:
     image: kubeshop/tracetest-agent:latest
+    command:
+      - "--mode=verbose"
     environment:
       # Find the Agent API Key here: https://docs.tracetest.io/configuration/agent
       - TRACETEST_API_KEY=${TRACETEST_API_KEY}
+      - TRACETEST_ENVIRONMENT_ID=${TRACETEST_ENVIRONMENT_ID}
     ports:
       - 4317:4317
       - 4318:4318