Ru doc initial

doc/ru/app.configuration.md

@@ -0,0 +1,33 @@
+# Конфигурация приложения
+
+/etc/surok/conf.d/app.json
+```
+{
+    "services": [
+      {
+        "name": "kioskservice",
+        "group": "production.romania",
+        "ports": ["web", "socket"]
+      }
+    ],
+    "conf_name": "kiosk",
+    "template": "/etc/surok/templates/kiosk.jj2",
+    "dest": "/etc/nginx/sites-available/kioskservice.conf",
+    "reload_cmd": "/bin/systemctl reload nginx",
+    "run_cmd": ["/usr/bin/node", "-c", "config.json"]
+}
+```
+
+Давайте разберем конфигурационный файл по опциям
+* services - array. Список хэшей с описанием сервисов
+    name - string. Имя сервиса. Это имя приложения в marathon
+    group - string. Группа в которой находится сервис. Группу можно узнать в marathon. Записывается в обратном порядке. Т.е. если у нас есть группа /webapps/php, то записывать её следует, как php.webapps
+    Если группа не указана, то сурок ожидает группу в переменной окружения SUROK_DISCOVERY_GROUP, если и SUROK_DISCOVERY_GROUP нет, то берется группа marathon(0.5.5).
+    ports - array.  Список имен портов сервиса. Не обязательная опция.
+* conf_name - string. Название конфига. Должен быть уникальным значением. Слежит для создания и чтения lock конфигурации.
+* template - string. Абсолютный путь к файлу шаблона.
+* dest - string. Абсолютный путь к файлу в который запишется результат генерации шаблона.
+* reload_cmd - string. Команда, которая будет выполнена в случае обноления конфига.
+    В reload_cmd можно использовать переменные окружения:
+    ```"reload_cmd": "/usr/bin/killall -9 calc || true && /usr/local/bin/calc -c /app/calc.conf ${CALC_NUM}"```
+* run_cmd(v0.6) - array. Список с командой на выполнение. Используется внутри контейнера вместо reload_cmd.

doc/ru/surok.configuration.md

@@ -0,0 +1,23 @@
+# Конфигурация Surok
+
+**/etc/surok/conf/surok.json**
+Разберем конфигурационный файл по опциям
+```
+{
+    "marathon": "10.0.1.199:8080",
+    "confd": "/etc/surok/conf.d",
+    "domain": "marathon.mesos",
+    "wait_time": 20,
+    "lock_dir": "/var/tmp",
+    "loglevel": "info|debug"
+    "container": true|false
+}
+```
+
+* marathon(v0.7) - string. Адрес Marathon Sheduler.
+* confd - strig. Абсолютный путь до директории с конфигурационными файлами приложений.
+* domain - string. Домен, который обслуживает mesos-dns.
+* wait_time - int. Время в секундах сколько Surok ждет до того, как начать заново делать запросы на обнаружение сервисов.
+* lock_dir - string. Абсолютный путь до директории с lock-конфигурациями.
+* loglevel - string. Уровень логирования.
+* container(v0.6) - boolean. Определяем внутри или нет контейнера запущен сурок. Меняется логика работы.

doc/ru/templates.md

@@ -0,0 +1,104 @@
+# Шиблоны
+
+Шаблоны для Surok пишутся на Jinja2. Возможно, стоит прочитать документацию.
+
+## Словарь my в шаблоне
+
+Surok заполняет словарь my и передает его в шаблон.
+```
+{
+   "services": {
+     "nginx": [
+         {
+          "name": "nginx.testing-kl92-s0.marathon.mesos.",
+          "port": "31200"
+         },
+         {
+          "name": "nginx.testing-kl123-s1.marathon.mesos.",
+          "port": "32230"
+         }
+      ],
+      "emailsender": [
+         {
+          "name": "emailsender.testing-kl92-s0.marathon.mesos.",
+          "port": "31201"
+         },
+         {
+          "name": "emailsender.testing-kl123-s1.marathon.mesos.",
+          "port": "32232"
+         }
+      ],
+     "service-with-defined-ports": {
+         "web": [
+           {
+             "name": "f.q.d.n",
+             "port": 12341
+           }
+         ],
+         "rpc": [
+           {
+             "name": "f.q.d.n",
+             "port": 12342
+           }
+         ]
+     }
+   },
+   "env": {
+      "HOME": "/var/lib/nginx"
+   }
+}
+```
+
+## Пример реального шаблона
+
+```
+upstream matrix-http {
+    hash $remote_addr;
+{% for server in my['services']['matrix']['http'] %}
+    server {{server['name']}}:{{server['port']}} max_fails=3;
+{% endfor %}
+}
+ 
+upstream riot-http {
+    hash $remote_addr;
+{% for server in my['services']['riot'] %}
+    server {{server['name']}}:{{server['port']}} max_fails=3;
+{% endfor %}
+}
+ 
+server {
+    listen 10.15.56.157:80;
+    server_name matrix.example.com;
+ 
+    client_max_body_size 10m;
+ 
+    location / {
+        proxy_pass http://riot-http;
+        proxy_set_header  X-Real-IP        $remote_addr;
+        proxy_set_header  Host             $http_host;
+        proxy_set_header  X-Forwarded-For  $proxy_add_x_forwarded_for;
+    }
+ 
+    location /_matrix/ {
+        proxy_pass http://matrix-http;
+        proxy_set_header  X-Real-IP        $remote_addr;
+        proxy_set_header  Host             $http_host;
+        proxy_set_header  X-Forwarded-For  $proxy_add_x_forwarded_for;
+    }
+ 
+}
+```
+Так для upstream matrix-http используются именованные порты, а для riot-http – нет.
+
+## Проверки в шаблоне
+
+Переменная _my['env']_ является классом python _os.environ_, что позваоляет нам строить различные проверки, например:
+
+```
+{% if my['env'].get('DB_HOST') %}
+host = '{{my['env']['DB_HOST']}}'
+{% else %}
+host = 'localhost'
+{% endif %}
+```
+