> For the complete documentation index, see [llms.txt](https://vitrina-blogerov.gitbook.io/bloggers-showcase/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://vitrina-blogerov.gitbook.io/bloggers-showcase/arkhitektura/caddy.md).

# Caddy

Caddy - это внешний вход в платформу. Он принимает HTTPS-запросы, получает сертификаты, направляет пользователя в нужную языковую версию и показывает страницы ошибок, если backend недоступен.

{% hint style="info" %}
Caddy можно воспринимать как диспетчер входящего трафика. Он не хранит карточки, пользователей, настройки, токены и базу данных.
{% endhint %}

### Где находится

В клиентской установке общий Caddy-слой создается установщиком в папке:

```
/opt/bloggers_platform/edge/
```

Внутри находятся:

| Файл или папка       | Назначение                          |
| -------------------- | ----------------------------------- |
| `Caddyfile`          | Правила домена, маршрутов и ошибок. |
| `docker-compose.yml` | Запуск Caddy-контейнера.            |
| `www/index.html`     | Страница выбора языка и редиректа.  |
| `www/errors`         | Страницы `403`, `404`, `502`.       |
| `www/assets`         | Общие стили и фон для edge-страниц. |

### Как проходит запрос

```mermaid
flowchart TB
    A["https://example.com"] --> B["Caddy edge"]
    B --> C{"Путь запроса"}
    C -->|"/bloggers/ru/*"| RU["backend_ru:8000"]
    C -->|"/bloggers/en/*"| EN["backend_en:8000"]
    C -->|"/bloggers/zh/*"| ZH["backend_zh:8000"]
    C -->|"/bloggers/ar/*"| AR["backend_ar:8000"]
    C -->|"/"| R["страница выбора языка"]
    C -->|"ошибка"| E["/errors/403.html, 404.html, 502.html"]
```

### Что делает Caddy

| Задача        | Что происходит                                                   |
| ------------- | ---------------------------------------------------------------- |
| HTTPS         | Caddy автоматически обслуживает HTTPS-сертификаты.               |
| Маршрутизация | Направляет `/bloggers/{lang}/` в backend нужной версии.          |
| Сжатие        | Включает `zstd` и `gzip`.                                        |
| Админка       | Отключает кеширование для `/admin`.                              |
| Ошибки        | Показывает branded-страницы ошибок.                              |
| Язык          | Показывает redirect-страницу, если установлено несколько языков. |

### Маршруты языков

{% tabs %}
{% tab title="RU" %}

```
/bloggers/ru/* -> backend_ru:8000
```

{% endtab %}

{% tab title="EN" %}

```
/bloggers/en/* -> backend_en:8000
```

{% endtab %}

{% tab title="ZH" %}

```
/bloggers/zh/* -> backend_zh:8000
```

{% endtab %}

{% tab title="AR" %}

```
/bloggers/ar/* -> backend_ar:8000
```

{% endtab %}
{% endtabs %}

Caddy срезает внешний префикс `/bloggers/{lang}` перед передачей запроса в backend. Благодаря этому приложение внутри контейнера работает так, как будто оно открыто с корня.

### Главная страница

<details>

<summary>Что происходит при открытии корня домена</summary>

Если установлена одна языковая версия, Caddy может сразу перенаправить пользователя на нее.

Если установлено несколько версий, Caddy отдает легкую страницу `www/index.html`. Она определяет язык Telegram или браузера и перенаправляет пользователя в подходящую установленную версию.

Если нужного языка нет, используется fallback:

```
en -> zh -> ar -> ru
```

</details>

### Страницы ошибок

Caddy показывает edge-страницы ошибок, когда запрос не дошел до backend или путь не найден на уровне edge.

```
/opt/bloggers_platform/edge/www/errors/403.html
/opt/bloggers_platform/edge/www/errors/404.html
/opt/bloggers_platform/edge/www/errors/502.html
```

{% hint style="warning" %}
Ошибка `502` часто означает, что Caddy работает, но backend нужной языковой версии недоступен.
{% endhint %}

### Пожалуйста, не ломайте

<details>

<summary>Порты</summary>

Caddy занимает публичные порты:

```
80/tcp
443/tcp
443/udp
```

Если на сервере уже работает другой web-сервер на этих портах, установка может конфликтовать.

</details>

<details>

<summary>Docker-сеть</summary>

Backend-контейнеры подключаются к общей Docker-сети `bloggers_edge`. Через нее Caddy видит `backend_ru`, `backend_en`, `backend_zh` и `backend_ar`.

</details>

<details>

<summary>Ручные правки Caddyfile</summary>

Установщик и `manager.sh` могут перегенерировать Caddyfile. Поэтому ручные изменения лучше делать только если понятно, как они будут сохранены при обновлении.

</details>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

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

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://vitrina-blogerov.gitbook.io/bloggers-showcase/arkhitektura/caddy.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.