# 行前準備

:::info <mark style="background-color:green;">**本頁面網址：**</mark> <mark style="background-color:green;"></mark><mark style="background-color:green;"><https://hackmd.io/@estraining/DevOpsDaysTaipei2022></mark> <mark style="background-color:green;"></mark><mark style="background-color:green;">**講者：**</mark> [<mark style="background-color:green;">喬叔 (Joe Wu)</mark>](https://training.onedoggo.com/about-me) <mark style="background-color:green;">**Facebook 粉絲頁：**</mark> [<mark style="background-color:green;">喬叔 - Elastic Stack 技術交流</mark>](https://www.facebook.com/Joe.ElasticStack/) :::

### 行前準備

#### 操作電腦需求

* 最少 **16GB** 以上的 RAM
* 最少 30GB 以上的 Disk Space
* MacOS, Linux, Windows 皆可，但請不要用太舊的作業系統

:::danger :exclamation:請注意，由於這次工作坊執行的 docker containers 數量眾多，記憶體的要求較高，如果記憶體不到 16GB 的話幾乎很難順利運作，若是要開雲端主機的話，可以參考 - 如果要使用雲端主機，可以設定-SSH-Tunnel-來存取 的設定方式。 :::

#### 準備執行環境

請先在電腦中安裝以下所需的執行環境：

* Docker
* Docker Compose ([安裝說明](https://docs.docker.com/compose/install/))
* Python3 ([安裝說明](https://github.com/elastic/apm-integration-testing#python-3))
* Git (會簡單的 `git clone`, `git pull`, `git checkout` 即可。)

#### 準備好 Docker Images

這次的工作坊，使用的是 Elastic 在 GitHub 所提供的 [apm-integration-testing](https://github.com/elastic/apm-integration-testing) 開源專案。

因為在操作時會需要 build Docker image 以及下載一些 Elastic Stack 的 Docker images，為了避免工作坊的時間被佔用在處理 build & download，建議請大家先完成以下的步驟。

:::danger :exclamation:<mark style="background-color:red;">請注意，喬叔有特別為了這次工作坊進行一些準備，所以請直接到喬叔 fork 出來的 GitHub 專案進行下載</mark> [<mark style="background-color:red;">https://github.com/joecwu/apm-integration-testing/</mark>](https://github.com/joecwu/apm-integration-testing/)<mark style="background-color:red;">，不要下載到 Elastic 官方版的哦！</mark> :::

1. 取得 apm-integration-testing 的檔案。

可使用 `git clone` 的指令，或是直接[下載 Zip 壓縮檔](https://github.com/joecwu/apm-integration-testing/archive/refs/heads/main.zip)。

```
git clone https://github.com/joecwu/apm-integration-testing.git
```

2. 準備好 Docker Images

有以下兩種選擇，自行 build 或是直接抓喬叔準備好的 docker images.

2-1. **自行 build:** 在專案的根路徑下，執行以下 `compose.py build` 的指令，以建立及下載所需要使用到的 Docker images：

Mac or Linux：

```
./scripts/compose.py build --release --with-opbeans-java --with-opbeans-ruby --with-opbeans-python --with-opbeans-go --with-opbeans-node --with-opbeans-rum --with-filebeat --with-metricbeat --with-heartbeat 8.4.1
```

Windows：

```
python .\scripts\compose.py build --release --with-opbeans-java --with-opbeans-ruby --with-opbeans-python --with-opbeans-go --with-opbeans-node --with-opbeans-rum --with-filebeat --with-metricbeat --with-heartbeat 8.4.1
```

2-2. **直接使用喬叔 build 好的 docker image**

**Mac M1**：

```
docker-compose -f ./docker-compose-arm64.yml pull 
```

**Linux**：

```
docker-compose -f ./docker-compose-linux.yml pull 
```

**Windows**：

```
docker-compose -f ./docker-compose-windows.yml pull 
```

:::danger <mark style="background-color:red;">其他平台需自行 build，否則</mark> <mark style="background-color:red;"></mark><mark style="background-color:red;">`opbeans-go`</mark> <mark style="background-color:red;"></mark><mark style="background-color:red;">和</mark> <mark style="background-color:red;"></mark><mark style="background-color:red;">`opbeans-rum`</mark> <mark style="background-color:red;"></mark><mark style="background-color:red;">會無法成功執行。</mark> :::

3. 確認 Docker Images 已被成功建置及下載。

使用 `docker images` 指令，確認有存在下列 Docker Images.

![](https://i.imgur.com/wSSnE7D.png)

4. 多確認是否能正常運作 Docker Cotainers

使用自行 build，請用：`docker-compose up -d`

若是使用另外的 yml 檔，請指定 `-f` 參數：`docker-compose -f ./docker-compose-linux.yml up -d`

請確認 containers 都能正常運作 (狀態為 `healthy`)，若有問題，可先參考 FAQ

:::info 若遇到任何問題，歡迎透過 FB 粉絲頁 [喬叔 - Elastic Stack 技術交流](https://www.facebook.com/Joe.ElasticStack/) 與我聯繫。 :::

### FAQ

#### 執行 `composer.py` 時 Docker build 出現 `GPG error`

docker 出現 GPG error: At least one invalid signature was encountered 相關問題及解決辦法。

> There are a few reasons why you encounter these errors:
>
> There might be an issue with the existing cache and/or disc space. In order to fix it you need to clear the APT cache by executing: sudo apt-get clean and sudo apt-get update.
>
> The same goes with existing docker images. Execute: docker image prune -f and docker container prune -f in order to remove unused data and free disc space.
>
> If you don’t care about the security risks, you can try to run the apt-get command with the --allow-unauthenticated or --allow-insecure-repositories flag. According to the docs:
>
> Ignore if packages can’t be authenticated and don’t prompt about it. This can be useful while working with local repositories, but is a huge security risk if data authenticity isn’t ensured in another way by the user itself.
>
> Finally, on MacOS, where Docker runs inside a dedicated VM, you may need to increase the disk available to Docker from the Docker Desktop application (Settings -> Resources -> Advanced -> Disk image size).

:::danger 執行以下指令會將你的 Docker 環境清空，包含 images, dangling build caches, containers，請確認後再操作。 :::

```
docker container prune
docker image prune -a 
docker system prune
docker system df
```

#### 啟動時，容器異常中止

查看 docker-compose logs `{container_name}` 時，發現以下的錯誤：

```
exec /usr/bin/dumb-init: exec format error
```

這代表該 Docker Image 不是用對應的 platform 所建置，需自行 build imgae 才能使用。

#### 啟動時，發生 `unhealthy` 的錯誤

```
ERROR: for opbeans-node  Container "907fc7a0c9be" is unhealthy.

ERROR: for opbeans-load-generator  Container "24e4d86c54ed" is unhealthy.
ERROR: Encountered errors while bringing up the project.
Traceback (most recent call last):
  File "/Users/joecwu/projects/joecwu/apm-integration-testing/./scripts/compose.py", line 31, in <module>
    main()
  File "/Users/joecwu/projects/joecwu/apm-integration-testing/./scripts/compose.py", line 17, in main
    setup()
  File "/Users/joecwu/projects/joecwu/apm-integration-testing/scripts/modules/cli.py", line 213, in __call__
    self.args.func()
  File "/Users/joecwu/projects/joecwu/apm-integration-testing/scripts/modules/cli.py", line 590, in start_handler
    self.build_start_handler("start")
  File "/Users/joecwu/projects/joecwu/apm-integration-testing/scripts/modules/cli.py", line 782, in build_start_handler
    self.run_docker_compose_process(docker_compose_cmd + up_params)
  File "/Users/joecwu/projects/joecwu/apm-integration-testing/scripts/modules/cli.py", line 476, in run_docker_compose_process
    subprocess.check_call(docker_compose_cmd)
  File "/Users/joecwu/.pyenv/versions/3.9.2/lib/python3.9/subprocess.py", line 373, in check_call
    raise CalledProcessError(retcode, cmd)
subprocess.CalledProcessError: Command '['docker-compose', '-f', '/Users/joecwu/projects/joecwu/apm-integration-testing/docker-compose.yml', 'up', '-d']' returned non-zero exit status 1.
```

有可能是當下某一些有相依性的 service 還沒有正常的啟動，可以先重新使用 `docker-compose` 啟動一次試試，看看是否有改善。

```
docker-compose up -d
```

若是依然有服務沒辦法正常啟動，可使用 `docker ps -a` 查看沒有正常啟動的服務是哪些，並進一步使用 `docker logs {{DockerContainerName}}` 查看錯誤訊息。

#### `opbeans-dotnet` 在 Apple M1 無法啟動

使用 `docker logs localtesting_8.4.1_opbeans-dotnet` 查看，發現以下錯誤：

```
Failed to resolve full path of the current executable [/proc/self/exe]
```

:::warning 在這次 Workshop 中，若是使用 Apple M1，我們先不啟用 `opbeans-dotnet` :::

#### 如果已經啟動過，但想要清空環境，重新再來

先清除所有正在運作中的 containers，以下方式二擇一：

1. 使用 `composer.py`

```
./scripts/compose.py stop
```

2. 使用 `docker-compose`

```
docker-compose down
```

如果有需要，可以一併刪除已產生的 docker volume.

```
docker volume rm apm-integration-testing_esdata
docker volume rm apm-integration-testing_pgdata
```

#### 如果要使用雲端主機，可以設定 SSH Tunnel 來存取

`~/.ssh/config` 的參考設定如下：

```
Host gcptunnel
    HostName <my.gcp.host.ip>
    IdentityFile ~/.ssh/google_compute_engine           <--- yours may differ
    User jamie                                          <--- yours probably differs
    Compression yes
    ExitOnForwardFailure no
    LocalForward 3000 127.0.0.1:3000
    LocalForward 3001 127.0.0.1:3001
    LocalForward 3002 127.0.0.1:3002
    LocalForward 3003 127.0.0.1:3003
    LocalForward 3004 127.0.0.1:80
    LocalForward 5601 127.0.0.1:5601
    LocalForward 8000 127.0.0.1:8000
    LocalForward 9200 127.0.0.1:9200
    LocalForward 9222 127.0.0.1:9222
```

以上述的例子，設定完成後，執行 `ssh gcptunnel` 即可將本機的 port 轉接到雲端主機。


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://training.onedoggo.com/tech-sharing/gong-zuo-fang/devopsdays-taipei-2022/preparation.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.