diff --git a/tutorial/content/labs/introduction/_index.md b/tutorial/content/labs/introduction/_index.md index 78ad9ba..9452c4b 100644 --- a/tutorial/content/labs/introduction/_index.md +++ b/tutorial/content/labs/introduction/_index.md @@ -4,37 +4,59 @@ draft = false weight = 1 +++ -## How to use this repo +## How to use this lab +The entire lab consists of one git repo, which contains all necessary things to run it within different environments as independent of the underlying hardware as possible. This repository consists of two main parts - the tutorial and the hands-on labs. In the tutorial everything you need to know on how to use OpenTelemetry for the labs will get explained. The labs give a hands-on experience on how to use OpenTelemetry in your applications. {{< figure src="images/lab_tutorial_setup.png" width=700 caption="Lab Architecture" >}} -The repository utilizes VS Code [Dev Containers](https://code.visualstudio.com/docs/devcontainers/containers). In order to use this repo you either need to -* Open this repository in [GitHub Codespaces](https://codespaces.new/JenSeReal/otel-getting-started) or in [Gitpod](https://gitpod.io/#https://github.com/JenSeReal/otel-getting-started) -* Or install [Docker](https://docs.docker.com/engine/install/), [VS Code](https://code.visualstudio.com/download) and the [Dev Containers extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) +The repository utilizes VS Code [Dev Containers](https://code.visualstudio.com/docs/devcontainers/containers) to provide a consistent developer experience across platforms. -With [GitHub Codespaces](https://codespaces.new/JenSeReal/otel-getting-started) a VS Instance in your browser will be opened automatically -The Dev Container spec will automatically open the labs part with a fully fledged and configured IDE and expose the tutorial on a port to your local system. -## How to navigate around the IDE -GitHub Codespaces and Gitpod will automatically run the [devcontainer.json](.devcontainer.json) and are immediately ready to go. +### Running the lab remotely + +For running the lab in cloud based dev environment you can either use [GitHub Codespaces](https://codespaces.new/JenSeReal/otel-getting-started) or in [Gitpod](https://gitpod.io/#https://github.com/JenSeReal/otel-getting-started). + +A requirement to run the lab remotely is a personal GitHub account. You can use this with either Codespaces or Gitpod. + +With both options a VS Instance in your browser will be opened automatically and you are immediately ready to go. + +### Running the lab locally + +In order to run the lab on your machine you need a local [Docker](https://docs.docker.com/engine/install/), [VS Code](https://code.visualstudio.com/download) and the [Dev Containers extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) + When using this repo with a locally installed VS Code instance you will be greeted by a prompt in the bottom right corner. -![Prompt to open the repo inside a Dev container](assets/prompt.png) +![Prompt to open the repo inside a Dev container](images/prompt.png) Press `Reopen in Container` to allow VS Code to use the [devcontainer.json](.devcontainer.json) specification to set up the IDE. If you missed the prompt hit Ctrl + Shift + P (on Mac Command + Shift + P) and type `Dev Containers: Rebuild and Reopen in Container`. After that the [devcontainer spec](.devcontainer.json) will run the [docker-compose.yml](docker-compose.yml) and pull all needed dependencies and build the [Docker Image](Dockerfile) for the application in which we will work on the lab content. To pull all Images and build all containers can take a second, so be patient. If the terminal is not visible open it under `View/Terminal` -![Open the terminal](assets/open-terminal.png) +![Open the terminal](images/open-terminal.png) When you run an application that exposes a port, VS Code will notify you that it is accessible. To open the application just click `Open in Browser` or open your Browser manually and type the URL yourself. -![Open the browser](assets/open-port.png) +![Open the browser](images/open-port.png) When you missed the prompt you can see the open ports in the `PORTS` tab. -![Where to find the forwarded ports](assets/ports.png) +![Where to find the forwarded ports](images/ports.png) + +## Important differences between local and remote way of running the lab + +Even though the experience with using a local or browser based VS Code is fairly similar, one thing you need to take care of is the variation in hostnames and ports. +Whereas on a local environment you can use the combination of `localhost` and the corresponding port. In a remote environment this will not work when trying to access endpoints via a browser. + +This is the ports tab of local VS Code environment: + +![VS Code ports](images/vscode_ports.png) + +This is the ports tab of a GitHub Codespaces environment: + +![Codespaces ports](images/codespaces_ports.png) + +This is the ports tab of a GitHub Codespaces environment: + +![Gitpod ports](images/gitpod_ports.png) + -You can at all times use the terminal to run applications and docker images. But you can also use the tab `Terminal/Run Task` -![Tasks](assets/tasks.png) -which will open a terminal and run the needed command automatically. For some labs you need to run two tasks, which will be explained in the respective lab. \ No newline at end of file diff --git a/tutorial/content/labs/introduction/images/codespaces_ports.png b/tutorial/content/labs/introduction/images/codespaces_ports.png new file mode 100644 index 0000000..a49b6f9 Binary files /dev/null and b/tutorial/content/labs/introduction/images/codespaces_ports.png differ diff --git a/tutorial/content/labs/introduction/images/gitpod_ports.png b/tutorial/content/labs/introduction/images/gitpod_ports.png new file mode 100644 index 0000000..f50a418 Binary files /dev/null and b/tutorial/content/labs/introduction/images/gitpod_ports.png differ diff --git a/tutorial/content/labs/introduction/images/open-port.png b/tutorial/content/labs/introduction/images/open-port.png new file mode 100644 index 0000000..0a5f815 Binary files /dev/null and b/tutorial/content/labs/introduction/images/open-port.png differ diff --git a/tutorial/content/labs/introduction/images/open-terminal.png b/tutorial/content/labs/introduction/images/open-terminal.png new file mode 100644 index 0000000..da09405 Binary files /dev/null and b/tutorial/content/labs/introduction/images/open-terminal.png differ diff --git a/tutorial/content/labs/introduction/images/ports.png b/tutorial/content/labs/introduction/images/ports.png new file mode 100644 index 0000000..3eaea1e Binary files /dev/null and b/tutorial/content/labs/introduction/images/ports.png differ diff --git a/tutorial/content/labs/introduction/images/prompt.png b/tutorial/content/labs/introduction/images/prompt.png new file mode 100644 index 0000000..8060483 Binary files /dev/null and b/tutorial/content/labs/introduction/images/prompt.png differ diff --git a/tutorial/content/labs/introduction/images/tasks.png b/tutorial/content/labs/introduction/images/tasks.png new file mode 100644 index 0000000..c4af4d4 Binary files /dev/null and b/tutorial/content/labs/introduction/images/tasks.png differ diff --git a/tutorial/content/labs/introduction/images/vscode_ports.png b/tutorial/content/labs/introduction/images/vscode_ports.png new file mode 100644 index 0000000..b5ae38d Binary files /dev/null and b/tutorial/content/labs/introduction/images/vscode_ports.png differ