Merge pull request #3816 from werf/mac-quickstart-docs-fix

docs: Adding fixes to the Quickstart and Installation in the MacOS section

docs/documentation/pages_en/quickstart.md

@@ -161,7 +161,8 @@ Or use one of the following instructions to set up the local Kubernetes cluster
 <a href="javascript:void(0)" class="details__summary">MacOS — 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-macos/).
+3. Start minikube:
 
    {% raw %}
    ```shell
@@ -171,15 +172,15 @@ Or use one of the following instructions to set up the local Kubernetes cluster
 
    **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
@@ -216,7 +217,7 @@ Or use one of the following instructions to set up the local Kubernetes cluster
    ```
    {% 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:
 
@@ -228,7 +229,15 @@ 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:
+
+   {% raw %}
+   ```shell
+   minikube start --vm=true --insecure-registry registry.example.com:80
+   ```
+   {% endraw %}
+
+7. Allow usage of Container Registry without TLS for werf:
 
    Set `WERF_INSECURE_REGISTRY=1` environment variable in the terminal where werf would run. For bash:
 
@@ -242,15 +251,15 @@ Or use one of the following instructions to set up the local Kubernetes cluster
    echo export WERF_INSECURE_REGISTRY=1 | tee -a ~/.bashrc
    ```
 
-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. Run the following command in the terminal:
    
    ```shell
    echo "$(minikube ip) vote.quickstart-application.example.com result.quickstart-application.example.com registry.example.com" | sudo tee -a /etc/hosts
    ```
 
-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"

docs/documentation/pages_ru/quickstart.md

@@ -164,7 +164,8 @@ werf version
 <a href="javascript:void(0)" class="details__summary">MacOS — minikube</a>
 <div class="details__content" markdown="1">
 1. Установите [minikube](https://github.com/kubernetes/minikube#installation).
-2. Запустите minikube:
+2. Установите [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl-macos/).
+3. Запустите minikube:
 
    {% raw %}
    ```shell
@@ -174,15 +175,15 @@ werf version
 
    **ВАЖНО.** С параметром `--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
@@ -219,7 +220,7 @@ werf version
    ```
    {% endraw %}
 
-5. Разрешаем доступ в Container Registry без TLS для docker:
+6. Разрешаем доступ в Container Registry без TLS для docker:
 
    Через меню Docker Desktop -> Settings -> Docker Engine добавим новый ключ в конфигурацию:
 
@@ -231,7 +232,15 @@ werf version
 
    Перезапустим Docker Desktop через меню, открывающееся правым кликом по иконке Docker Desktop в трее.
 
-6. Разрешаем доступ в Container Registry без TLS для werf:
+   Затем снова запустим minikube:
+   
+   {% raw %}
+   ```shell
+   minikube start --vm=true --insecure-registry registry.example.com:80
+   ```
+   {% endraw %}
+
+7. Разрешаем доступ в Container Registry без TLS для werf:
 
    В терминале где будет запускаться werf установим переменную окружения `WERF_INSECURE_REGISTRY=1`. Для bash:
 
@@ -245,15 +254,15 @@ werf version
    echo export WERF_INSECURE_REGISTRY=1 | tee -a ~/.bashrc
    ```
 
-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. Выполните команду в терминале:
 
    ```shell
    echo "$(minikube ip) vote.quickstart-application.example.com result.quickstart-application.example.com registry.example.com" | sudo tee -a /etc/hosts
    ```
 
-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"

docs/site/_includes/en/installation/trdl_macos.md

@@ -1,6 +1,7 @@
-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/mac) 2.18.0 or newer and [Docker](https://docs.docker.com/get-docker) installed.
 
 Setup [trdl](https://github.com/werf/trdl) which will manage `werf` installation and updates:
+
 ```shell
 # Add ~/bin to the PATH.
 echo 'export PATH=$HOME/bin:$PATH' >> ~/.zprofile
@@ -17,17 +18,21 @@ Add `werf` repo:
 trdl add werf https://tuf.werf.io 1 b7ff6bcbe598e072a86d595a3621924c8612c7e6dc6a82e919abe89707d7e3f468e616b5635630680dd1e98fc362ae5051728406700e6274c5ed1ad92bea52a2
 ```
 
-For local usage we recommend automatically activating `werf` for new shell sessions:
+To use werf locally in your terminal, we recommend to enable its automatic activation. To make werf available in all new shell sessions, you need to execute this command (just once):
 ```shell
 echo 'source $(trdl use werf {{ include.version }} {{ include.channel }})' >> ~/.zshrc
 ```
 
-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
-source $(trdl use werf {{ include.version }} {{ include.channel }})
+werf version
 ```
 
-Make sure that `werf` is available now (open new shell if you chose automatic activation):
+To get werf running in your current terminal only (before any logout/login is done), you can simply execute the `source $(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
-werf version
+source $(trdl use werf {{ include.version }} {{ include.channel }})
 ```

docs/site/_includes/ru/installation/trdl_macos.md

@@ -1,6 +1,7 @@
-Убедитесь, что Git версии 2.18.0 или новее и [Docker](https://docs.docker.com/get-docker) установлены.
+Убедитесь, что [Git](https://git-scm.com/download/mac) версии 2.18.0 или новее и [Docker](https://docs.docker.com/get-docker) установлены.
 
 Установите [trdl](https://github.com/werf/trdl), который будет отвечать за установку и обновление `werf`:
+
 ```shell
 # Добавьте ~/bin в PATH.
 echo 'export PATH=$HOME/bin:$PATH' >> ~/.zprofile
@@ -12,22 +13,26 @@ mkdir -p ~/bin
 install /tmp/trdl ~/bin/trdl
 ```
 
-Добавьте `werf` репозиторий:
+Добавьте репозиторий с `werf`:
 ```shell
 trdl add werf https://tuf.werf.io 1 b7ff6bcbe598e072a86d595a3621924c8612c7e6dc6a82e919abe89707d7e3f468e616b5635630680dd1e98fc362ae5051728406700e6274c5ed1ad92bea52a2
 ```
 
-Для локальной разработки рекомендуем настроить автоматическую активацию `werf` для новых shell-сессий:
+Для локального использования werf (в терминале) мы рекомендуем настроить автоматическую активацию утилиты. Чтобы werf была доступна во всех новых shell-сессиях, выполните следующую команду (это потребуется сделать лишь один раз):
 ```shell
 echo 'source $(trdl use werf {{ include.version }} {{ include.channel }})' >> ~/.zshrc
 ```
 
-А в CI рекомендуем активировать `werf` явно в начале каждого job/pipeline:
+Теперь, если вы выйдете из системы и залогинитесь в неё обратно, werf всегда будет доступна. Убедиться в этом можно следующей командой:
+
 ```shell
-source $(trdl use werf {{ include.version }} {{ include.channel }})
+werf version
 ```
 
-Убедитесь, что `werf` теперь доступен в командной строке (начните новую shell-сессию, если вы предпочли автоматическую активацию):
+Чтобы получить werf только в текущем терминале (до того, как перезашли в систему), достаточно выполнить команду `source $(trdl use werf {{ include.version }} {{ include.channel }})`.
+
+Для CI рекомендуется другой подход с явной активацией `werf` в начале каждого job/pipeline. Она выполняется командой:
+
 ```shell
-werf version
+source $(trdl use werf {{ include.version }} {{ include.channel }})
 ```