Add manual how to run local Extender. (#474)

* Add manual how to run local Extender. * Make more clear where command should be executed. * Add --platform argument in pull command. * Add note about Docker running. * Add notes about build server address. * Note for Windows users.
defold · Sep 12, 2024 · e563eb3 · e563eb3
1 parent 205ea98
commit e563eb3
Show file tree

Hide file tree

Showing 3 changed files with 241 additions and 0 deletions.
diff --git a/docs/en/en.json b/docs/en/en.json
@@ -1562,6 +1562,10 @@
                     {
                         "path": "https://lua.msys.ch/lua-integration-guide.html#_the_lua_c_api",
                         "name": "The Lua C API (external)"
+                    },
+                    {
+                        "path": "/manuals/extender-local-setup",
+                        "name": "Setup local build server"
                     }
                 ]
             }

diff --git a/docs/en/manuals/extender-local-setup.md b/docs/en/manuals/extender-local-setup.md
@@ -0,0 +1,119 @@
+---
+title: Setup local build server
+brief: Manual described how to setup and run local build server
+---
+
+# Build server local setup
+
+There are two variants how to run local build server (aka 'Extender'):
+1. Run local build server with preconfigured artifacts.
+2. Build all necessary artifacts locally and use it to run local build server.
+
+## How to run local Extender with preconfigured artifacts
+
+### Prerequisites
+* **Docker** - https://www.docker.com/products/docker-desktop/
+* **gcloud cli** - https://cloud.google.com/sdk/docs/install
+* **google account**
+
+### How to use ready-to-use Docker images
+**Note for Windows users**: use git bash terminal for executing commands below.
+1. Authorize to Google Cloud and create Application default credentials
+   ```sh
+   gcloud auth application-default login
+   ```
+2. Configure Docker to use Artifact registries
+   ```sh
+   gcloud auth configure-docker europe-west1-docker.pkg.dev
+   ```
+3. Check that Docker is running.
+4. Check that everything set up correctly by pulling base image. Run
+   ```sh
+   docker pull --platform linux/amd64 europe-west1-docker.pkg.dev/extender-426409/extender-public-registry/extender-base-env:latest
+   ```
+5. Clone `Extender` repository and switch to cloned repository root folder
+   ```sh
+   git clone https://github.com/defold/extender.git
+   cd extender
+   ```
+6. Download prebuilt jars:
+   ```sh
+    TMP_DIR=$(pwd)/server/_tmp
+    APPLICATION_DIR=$(pwd)/server/app
+    # set nesessary version of Extender and Manifest merge tool
+    # versions can be found at Github release page https://github.com/defold/extender/releases
+    # or you can pull latest version (see code sample below)
+    EXTENDER_VERSION=2.6.5
+    MANIFESTMERGETOOL_VERSION=1.3.0
+    echo "Download prebuild jars to ${APPLICATION_DIR}"
+    rm -rf ${TMP_DIR}
+    mkdir -p ${TMP_DIR}
+    rm -rf ${APPLICATION_DIR}
+    mkdir -p ${APPLICATION_DIR}
+
+    gcloud artifacts files download \
+    --project=extender-426409 \
+    --location=europe-west1 \
+    --repository=extender-maven \
+    --destination=${TMP_DIR} \
+    com/defold/extender/server/${EXTENDER_VERSION}/server-${EXTENDER_VERSION}.jar
+
+    gcloud artifacts files download \
+    --project=extender-426409 \
+    --location=europe-west1 \
+    --repository=extender-maven \
+    --destination=${TMP_DIR} \
+    com/defold/extender/manifestmergetool/${MANIFESTMERGETOOL_VERSION}/manifestmergetool-${MANIFESTMERGETOOL_VERSION}.jar
+
+    cp ${TMP_DIR}/$(ls ${TMP_DIR} | grep server-${EXTENDER_VERSION}.jar) ${APPLICATION_DIR}/extender.jar
+    cp ${TMP_DIR}/$(ls ${TMP_DIR} | grep manifestmergetool-${MANIFESTMERGETOOL_VERSION}.jar) ${APPLICATION_DIR}/manifestmergetool.jar
+   ```
+7. Run docker compose:
+main command
+```sh
+docker compose -p extender -f server/docker/docker-compose.yml --profile <profile> up
+```
+where *profile* can be:
+* **all** - runs remote instances for every platform
+* **android** - runs frontend instance + remote instances to build Android version
+* **web** - runs frontend instance + remote instances to build Web version
+* **linux** - runs frontend instance + remote instances to build Linux version
+* **windows** - runs frontend instance + remote instances to build Windows version
+* **consoles** - runs frontend instance + remote instances to build Nintendo Switch/PS4/PS5 versions
+* **nintendo** - runs frontend instance + remote instances to build Nintendo Switch version
+* **playstation** - runs frontend instance + remote instances to build PS4/PS5 versions
+* **metrics** - runs VictoriaMetrics + Grafana as metrics backend and tool for visualization
+For more information about `docker compose` argumets see https://docs.docker.com/reference/cli/docker/compose/.
+
+When docker compose is up you can use **http://localhost:9000** as Build server address in Editor's preference or as `--build-server` value if you use Bob to build the project.
+
+Several profiles can be passed to command line. For example:
+```sh
+docker compose -p extender -f server/docker/docker-compose.yml --profile android --profile web --profile windows up
+```
+Example above runs frontend, Android, Web, Windows instances.
+
+To stop services - Press Ctrl+C if docker compose runs in non-detached mode, or 
+```sh
+docker compose -p extender down
+```
+if docker compose was run in detached mode (e.g. '-d' flag was passed to `docker compose up` command).
+
+If you want to pull latest versions of jars you can use following command to determine latest version
+```sh
+    EXTENDER_VERSION=$(gcloud artifacts versions list \
+        --location=europe-west1 \
+        --repository=extender-maven \
+        --package="com.defold.extender:server" \
+        --sort-by="~createTime" \
+        --limit=1 \
+        --format="get(name)" | awk -F'/' '{print $NF}')
+
+    MANIFESTMERGETOOL_VERSION=$(gcloud artifacts versions list \
+        --location=europe-west1 \
+        --repository=extender-maven \
+        --package="com.defold.extender:manifestmergetool" \
+        --sort-by="~createTime" \
+        --limit=1 \
+        --format="get(name)" | awk -F'/' '{print $NF}')
+```
diff --git a/docs/ru/manuals/extender-local-setup.md b/docs/ru/manuals/extender-local-setup.md
@@ -0,0 +1,118 @@
+---
+title: Установка локального сервера сборки
+brief: Руководство описывает как установить и запустить локальный сервер сборки
+---
+
+# Установка локального сервера сборки
+Существует два способа запуска локального сервера сборки (Extender):
+1. Запуск локального сервера сборки с готовыми артефактами.
+2. Сборка всех необходимых артефактов локально и использование этих артефактов для запуска локального сервера сборки.
+
+## Как запустить локальный сервер сборки с готовыми артефактами
+
+### Предустановки
+* **Docker** - https://www.docker.com/products/docker-desktop/
+* **gcloud cli** - https://cloud.google.com/sdk/docs/install
+* **google account**
+
+### Как использовать готовые образы Docker
+**Примечание для пользователей Windows**: используйте git bash для выполнения команд описанных ниже.
+1. Авторизуемся в Google Cloud и создаем учетные данные приложения по умолчанию (Application default credentials/ADC)
+   ```sh
+   gcloud auth application-default login
+   ```
+2. Конфигурируем Docker для использования реестра Артефактов
+   ```sh
+   gcloud auth configure-docker europe-west1-docker.pkg.dev
+   ```
+3. Проверить, что Docker запущен.
+4. Проверяем, что все сконфигурировано корректно путем скачивания базового образа. Запустите
+   ```sh
+   docker pull --platform linux/amd64  europe-west1-docker.pkg.dev/extender-426409/extender-public-registry/extender-base-env:latest
+   ```
+5. Клонируем репозиторий `Extender` и переходим в корневую директорию склонированного репозитория
+   ```sh
+   git clone https://github.com/defold/extender.git
+   cd extender/
+   ```
+6. Скачиваем готовые jar файлы:
+   ```sh
+    TMP_DIR=$(pwd)/server/_tmp
+    APPLICATION_DIR=$(pwd)/server/app
+    # set nesessary version of Extender and Manifest merge tool
+    # versions can be found at Github release page https://github.com/defold/extender/releases
+    # or you can pull latest version (see code sample below)
+    EXTENDER_VERSION=2.6.5
+    MANIFESTMERGETOOL_VERSION=1.3.0
+    echo "Download prebuild jars to ${APPLICATION_DIR}"
+    rm -rf ${TMP_DIR}
+    mkdir -p ${TMP_DIR}
+    rm -rf ${APPLICATION_DIR}
+    mkdir -p ${APPLICATION_DIR}
+
+    gcloud artifacts files download \
+    --project=extender-426409 \
+    --location=europe-west1 \
+    --repository=extender-maven \
+    --destination=${TMP_DIR} \
+    com/defold/extender/server/${EXTENDER_VERSION}/server-${EXTENDER_VERSION}.jar
+
+    gcloud artifacts files download \
+    --project=extender-426409 \
+    --location=europe-west1 \
+    --repository=extender-maven \
+    --destination=${TMP_DIR} \
+    com/defold/extender/manifestmergetool/${MANIFESTMERGETOOL_VERSION}/manifestmergetool-${MANIFESTMERGETOOL_VERSION}.jar
+
+    cp ${TMP_DIR}/$(ls ${TMP_DIR} | grep server-${EXTENDER_VERSION}.jar) ${APPLICATION_DIR}/extender.jar
+    cp ${TMP_DIR}/$(ls ${TMP_DIR} | grep manifestmergetool-${MANIFESTMERGETOOL_VERSION}.jar) ${APPLICATION_DIR}/manifestmergetool.jar
+   ```
+7. Запускаем docker compose
+главная команда
+```sh
+docker compose -p extender -f server/docker/docker-compose.yml --profile <profile> up
+```
+где *profile* может быть:
+* **all** - запускает все сервисы, которые нужны для сборки на всех поддерживаемых платформах
+* **android** - запускает frontend сервис + сервис для сборки Android версии
+* **web** - запускает frontend сервис + сервис для сборки Web версии
+* **linux** - запускает frontend сервис + сервис для сборки Linux версии
+* **windows** - запускает frontend сервис + сервис для сборки Windows версии
+* **consoles** - запускает frontend сервис + сервисы для сборки Nintendo Switch/PS4/PS5 версий
+* **nintendo** - запускает frontend сервис + сервис для сборки Nintendo Switch версии
+* **playstation** - запускает frontend сервис + сервисы для сборки PS4/PS5 версий
+* **metrics** - запускает VictoriaMetrics + Grafana в качестве сервиса для сбора метрик и их визуализации
+Для дополнительной информации о том, какие аргументы могут быть переданы команде `docker compose` смотрите https://docs.docker.com/reference/cli/docker/compose/.
+
+Когда docker compose запустить, то можно использовать адрес **http://localhost:9000** как адрес сервера сборки в настройках Редактора или как значение для аргумента `--build-server`, если Вы используете Bob для сборки проекта.
+
+Несколько профилей может быть одновременно передано в командную строку. Например:
+```sh
+docker compose -p extender -f server/docker/docker-compose.yml --profile android --profile web --profile windows up
+```
+Пример выше запустит frontend сервис, а также сервисы для сборки Android, Web, Windows.
+
+Для остановки всех сервисов - нажмите Ctrl+C если docker compose запущен в режиме без отсоединения, или
+```sh
+docker compose -p extender down
+```
+если docker compose был запущен в режиме отсоединения (т.е. флаг '-d' был передан при выполнении команды `docker compose up`).
+
+Если вы хотите скачать последние версии jar файлов, то вы можете использовать следующие команды для определения последних доступных для скачивания версий
+```sh
+    EXTENDER_VERSION=$(gcloud artifacts versions list \
+        --location=europe-west1 \
+        --repository=extender-maven \
+        --package="com.defold.extender:server" \
+        --sort-by="~createTime" \
+        --limit=1 \
+        --format="get(name)" | awk -F'/' '{print $NF}')
+
+    MANIFESTMERGETOOL_VERSION=$(gcloud artifacts versions list \
+        --location=europe-west1 \
+        --repository=extender-maven \
+        --package="com.defold.extender:manifestmergetool" \
+        --sort-by="~createTime" \
+        --limit=1 \
+        --format="get(name)" | awk -F'/' '{print $NF}')
+```