Merge pull request #3812 from werf/win-quickstart-docs-fix

docs: Adding fixes to the Quickstart and Installation in the Windows section
werf · Oct 12, 2021 · f2a6a03 · f2a6a03
2 parents 885a85b + 2ce8e3a
commit f2a6a03
Show file tree

Hide file tree

Showing 4 changed files with 71 additions and 48 deletions.
diff --git a/docs/documentation/pages_en/quickstart.md b/docs/documentation/pages_en/quickstart.md
@@ -34,37 +34,38 @@ Or use one of the following instructions to set up the local Kubernetes cluster
 <a href="javascript:void(0)" class="details__summary">Windows — minikube</a>
 <div class="details__content" markdown="1">
 1. Install [minikube](https://github.com/kubernetes/minikube#installation).
-2. Start minikube:
+2. Install [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl-windows/).
+3. Start minikube:
 
    {% raw %}
    ```shell
-   minikube start --driver=hyperv --insecure-registry registry.example.com:80
+   minikube start --driver=docker --insecure-registry registry.example.com:80
    ```
    {% endraw %}
 
    **IMPORTANT** Param `--insecure-registry` allows usage of Container Registry without TLS. TLS in our case dropped for simplicity.
 
-3. Install NGINX Ingress Controller:
+4. Install NGINX Ingress Controller:
 
    {% raw %}
    ```shell
    minikube addons enable ingress
    ```
    {% endraw %}
 
-4. Install Container Registry to store images:
+5. Install Container Registry to store images:
 
    {% raw %}
    ```shell
    minikube addons enable registry
    ```
    {% endraw %}
 
-   Create Ingress to access Container Registry:
+   Create Ingress to access Container Registry. 
 
-   {% raw %}
+       {% raw %}
    ```shell
-   kubectl apply -f - << EOF
+   @"
    ---
    apiVersion: networking.k8s.io/v1
    kind: Ingress
@@ -85,11 +86,11 @@ Or use one of the following instructions to set up the local Kubernetes cluster
                name: registry
                port:
                  number: 80
-   EOF
+   "@ | kubectl apply -f -  
    ```
    {% endraw %}
 
-5. Allow usage of Container Registry without TLS for docker:
+6. Allow usage of Container Registry without TLS for Docker:
 
    Using menu Docker Desktop -> Settings -> Docker Engine add following configuration key:
 
@@ -101,7 +102,13 @@ Or use one of the following instructions to set up the local Kubernetes cluster
 
    Restart Docker Desktop using right button menu of the tray Docker Desktop icon.
 
-6. Allow usage of Container Registry without TLS for werf:
+   Then start minikube again:
+
+   ```shell
+   minikube start --driver=docker --insecure-registry registry.example.com:80
+   ```
+
+7. Allow usage of Container Registry without TLS for werf:
 
    Set `WERF_INSECURE_REGISTRY=1` environment variable in the terminal where werf would run.
 
@@ -123,7 +130,7 @@ Or use one of the following instructions to set up the local Kubernetes cluster
    $Env:WERF_INSECURE_REGISTRY = "1"
    ```
 
-7. We are going to use `vote.quickstart-application.example.com` and `result.quickstart-application.example.com` domains to access application and `registry.example.com` domain to access Container Registry.
+8. We are going to use `vote.quickstart-application.example.com` and `result.quickstart-application.example.com` domains to access application and `registry.example.com` domain to access Container Registry.
 
    Let's update hosts file. Get minikube IP-address:
 
@@ -142,7 +149,7 @@ Or use one of the following instructions to set up the local Kubernetes cluster
    192.168.99.99          vote.quickstart-application.example.com result.quickstart-application.example.com registry.example.com
    ```
 
-8. Let's also add `registry.example.com` domain to the minikube node:
+9. Let's also add `registry.example.com` domain to the minikube node:
 
    ```shell
    minikube ssh -- "echo $(minikube ip) registry.example.com | sudo tee -a /etc/hosts"

diff --git a/docs/documentation/pages_ru/quickstart.md b/docs/documentation/pages_ru/quickstart.md
@@ -27,7 +27,7 @@ werf version
 
  1. Выполнить стандартный вход в container registry со своего хоста.
  2. Убедиться, что кластер Kubernetes доступен с хоста (дополнительная настройка `werf`, скорее всего, не потребуется, если у вас уже установлен и работает `kubectl`).
- 
+
 <br>
 
 В ином случае выполните одну из следующих инструкций, чтобы настроить локальный кластер Kubernetes и container registry в вашей системе:
@@ -36,37 +36,38 @@ werf version
 <a href="javascript:void(0)" class="details__summary">Windows — minikube</a>
 <div class="details__content" markdown="1">
 1. Установите [minikube](https://github.com/kubernetes/minikube#installation).
-2. Запустите minikube:
+2. Установите [kubectl](https://kubernetes.io/ru/docs/tasks/tools/install-kubectl/#%D1%83%D1%81%D1%82%D0%B0%D0%BD%D0%BE%D0%B2%D0%BA%D0%B0-kubectl-%D0%B2-windows).
+3. Запустите minikube:
 
    {% raw %}
    ```shell
-   minikube start --driver=hyperv --insecure-registry registry.example.com:80
+   minikube start --driver=docker --insecure-registry registry.example.com:80
    ```
    {% endraw %}
 
    **ВАЖНО.** С параметром `--insecure-registry` мы подготавливаем такое окружение, которое сможет работать с Container Registry без TLS. В нашем случае для упрощения настройка TLS отсутствует.
 
-3. Установка NGINX Ingress Controller:
+4. Установка NGINX Ingress Controller:
 
    {% raw %}
    ```shell
    minikube addons enable ingress
    ```
    {% endraw %}
 
-4. Установка Container Registry для хранения образов:
+5. Установка Container Registry для хранения образов:
 
    {% raw %}
    ```shell
    minikube addons enable registry
    ```
    {% endraw %}
 
-   Создадим Ingress для доступа к Container Registry:
+   Создадим Ingress для доступа к Container Registry. 
 
-   {% raw %}
+      {% raw %}
    ```shell
-   kubectl apply -f - << EOF
+   @"
    ---
    apiVersion: networking.k8s.io/v1
    kind: Ingress
@@ -87,11 +88,11 @@ werf version
                name: registry
                port:
                  number: 80
-   EOF
+   "@ | kubectl apply -f -  
    ```
    {% endraw %}
 
-5. Разрешаем доступ в Container Registry без TLS для docker:
+6. Разрешаем доступ в Container Registry без TLS для Docker:
 
    Через меню Docker Desktop -> Settings -> Docker Engine добавим новый ключ в конфигурацию:
 
@@ -103,7 +104,13 @@ werf version
 
    Перезапустим Docker Desktop через меню, открывающееся правым кликом по иконке Docker Desktop в трее.
 
-6. Разрешаем доступ в Container Registry без TLS для werf:
+   Затем снова запустим minikube:
+
+   ```shell
+   minikube start --driver=docker --insecure-registry registry.example.com:80
+   ```
+
+7. Разрешаем доступ в Container Registry без TLS для werf:
 
    В терминале где будет запускаться werf установим переменную окружения `WERF_INSECURE_REGISTRY=1`.
 
@@ -125,7 +132,7 @@ werf version
    $Env:WERF_INSECURE_REGISTRY = "1"
    ```
 
-7. Мы будем использовать домены `vote.quickstart-application.example.com` и `result.quickstart-application.example.com` для доступа к приложению и домен `registry.example.com` для доступа к Container Registry.
+8. Мы будем использовать домены `vote.quickstart-application.example.com` и `result.quickstart-application.example.com` для доступа к приложению и домен `registry.example.com` для доступа к Container Registry.
 
    Обновим файл hosts. Сначала получите IP-адрес minikube:
 
@@ -134,7 +141,7 @@ werf version
    ```
 
    Используя полученный выше IP-адрес minikube, добавьте в конец файла `C:\Windows\System32\drivers\etc\hosts` следующую строку:
-   
+
    ```
    <IP-адрес minikube>    vote.quickstart-application.example.com result.quickstart-application.example.com registry.example.com
    ```
@@ -144,7 +151,7 @@ werf version
    192.168.99.99          vote.quickstart-application.example.com result.quickstart-application.example.com registry.example.com
    ```
 
-8. Также делаем доступ к домену `registry.example.com` из minikube node:
+9. Также делаем доступ к домену `registry.example.com` из minikube node:
 
    ```shell
    minikube ssh -- "echo $(minikube ip) registry.example.com | sudo tee -a /etc/hosts"
@@ -215,13 +222,13 @@ werf version
 5. Разрешаем доступ в Container Registry без TLS для docker:
 
    Через меню Docker Desktop -> Settings -> Docker Engine добавим новый ключ в конфигурацию:
-   
+
    ```json
    {
    "insecure-registries": ["registry.example.com:80"]
    }
    ```
-   
+
    Перезапустим Docker Desktop через меню, открывающееся правым кликом по иконке Docker Desktop в трее.
 
 6. Разрешаем доступ в Container Registry без TLS для werf:
@@ -326,18 +333,19 @@ werf version
    
 6. Разрешаем доступ в Container Registry без TLS для Docker:
 
+
    В файл, по умолчанию находящийся в `/etc/docker/daemon.json`, добавим новый ключ:
 
    ```json
    {
    "insecure-registries": ["registry.example.com:80"]
    }
    ```
-
+  
    Если такого файла в каталоге нет, его нужно создать и вставить в него указанные выше строки. Обратите внимание, что для доступа к изменению файлов в каталоге `/etc` нужны права суперпользователя (root).
-   
+
    Перезапустим Docker:
-   
+
    ```shell
    sudo systemctl restart docker
    ```
@@ -391,10 +399,10 @@ werf version
 </div>
 </div>
 
-## Разверните приложение-пример 
+## Разверните приложение-пример
 
 1. Склонируйте репозиторий нашего приложения-примера:
- 
+
    {% raw %}
    ```shell
    git clone https://github.com/werf/quickstart-application

diff --git a/docs/site/_includes/en/installation/trdl_windows.md b/docs/site/_includes/en/installation/trdl_windows.md
@@ -1,4 +1,4 @@
-Make sure you have Git 2.18.0 or newer and [Docker](https://docs.docker.com/get-docker) installed.
+Make sure you have [Git](https://git-scm.com/download/win) 2.18.0 or newer and [Docker](https://docs.docker.com/get-docker) installed.
 
 Following instructions should be executed in the PowerShell.
 
@@ -18,7 +18,7 @@ Add `werf` repo:
 trdl add werf https://tuf.werf.io 1 b7ff6bcbe598e072a86d595a3621924c8612c7e6dc6a82e919abe89707d7e3f468e616b5635630680dd1e98fc362ae5051728406700e6274c5ed1ad92bea52a2
 ```
 
-For local usage we recommend automatically activating `werf` for new PowerShell sessions. Run in the PowerShell under Administrator:
+To use werf locally in your terminal, we recommend to enable its automatic activation. To make werf available in all new PowerShell sessions, you need to execute this command (just once, run under Administrator):
 ```powershell
 # Allow execution of locally created scripts.
 Set-ExecutionPolicy RemoteSigned -Scope CurrentUser
@@ -30,12 +30,16 @@ if (!(Test-Path "$profile")) {
 Add-Content -Path "$profile" -Value '. $(trdl use werf {{ include.version }} {{ include.channel }})'
 ```
 
-But in CI you should prefer activating `werf` explicitly in the beginning of each job/pipeline:
+Now, if you log out and log in to the system again, werf will be always available. You can make sure of that by executing:
+
 ```shell
-. $(trdl use werf {{ include.version }} {{ include.channel }})
+werf version
 ```
 
-Make sure that `werf` is available now (open new PowerShell session if you chose automatic activation):
-```powershell
-werf version
+To get werf running in your current terminal only (before any logout/login is done), you can simply execute the `. $(trdl use werf {{ include.version }} {{ include.channel }})` command.
+
+In CI, you need a different approaching with activating `werf` explicitly in the beginning of each job/pipeline by executing:
+
+```shell
+. $(trdl use werf {{ include.version }} {{ include.channel }})
 ```
diff --git a/docs/site/_includes/ru/installation/trdl_windows.md b/docs/site/_includes/ru/installation/trdl_windows.md
@@ -1,4 +1,4 @@
-Убедитесь, что Git версии 2.18.0 или новее и [Docker](https://docs.docker.com/get-docker) установлены.
+Убедитесь, что [Git](https://git-scm.com/download/win) версии 2.18.0 или новее и [Docker](https://docs.docker.com/get-docker) установлены.
 
 Описанные далее команды должны быть выполнены в PowerShell.
 
@@ -13,12 +13,12 @@ mkdir -Force "$env:USERPROFILE\bin"
 Invoke-WebRequest -Uri "https://tuf.trdl.dev/targets/releases/0.1.3/windows-{{ include.arch }}/bin/trdl.exe" -OutFile "$env:USERPROFILE\bin\trdl.exe"
 ```
 
-Добавьте `werf` репозиторий:
+Добавьте репозиторий с `werf`:
 ```powershell
 trdl add werf https://tuf.werf.io 1 b7ff6bcbe598e072a86d595a3621924c8612c7e6dc6a82e919abe89707d7e3f468e616b5635630680dd1e98fc362ae5051728406700e6274c5ed1ad92bea52a2
 ```
 
-Для локальной разработки рекомендуем настроить автоматическую активацию `werf` для новых shell-сессий:
+Для локального использования werf (в терминале) мы рекомендуем настроить автоматическую активацию утилиты. Чтобы werf была доступна во всех новых PowerShell-сессиях, выполните следующую команду (это потребуется сделать лишь один раз) от имени Администратора:
 ```powershell
 # Разрешите выполнение локально созданных скриптов.
 Set-ExecutionPolicy RemoteSigned -Scope CurrentUser
@@ -30,12 +30,16 @@ if (!(Test-Path "$profile")) {
 Add-Content -Path "$profile" -Value '. $(trdl use werf {{ include.version }} {{ include.channel }})'
 ```
 
-А в CI рекомендуем активировать `werf` явно в начале каждого job/pipeline:
-```shell
-. $(trdl use werf {{ include.version }} {{ include.channel }})
-```
+Теперь, если вы выйдете из системы и залогинитесь в неё обратно, werf всегда будет доступна. Убедиться в этом можно следующей командой:
 
-Убедитесь, что `werf` теперь доступен в командной строке (начните новую PowerShell-сессию, если вы предпочли автоматическую активацию):
 ```powershell
 werf version
 ```
+
+Чтобы получить werf только в текущем терминале (до того, как перезашли в систему), достаточно выполнить команду `. $(trdl use werf {{ include.version }} {{ include.channel }})`.
+
+Для CI рекомендуется другой подход с явной активацией `werf` в начале каждого job/pipeline. Она выполняется командой:
+
+```shell
+. $(trdl use werf {{ include.version }} {{ include.channel }})
+```