> 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/product-docs/product-docs-en/architecture/caddy.md).

# Caddy

Caddy is the external entry point to the platform. It accepts HTTPS requests, obtains certificates, routes the user to the correct language version, and shows error pages if the backend is unavailable.

{% hint style="info" %}
Caddy can be thought of as a dispatcher for incoming traffic. It does not store cards, users, settings, tokens, or the database.
{% endhint %}

### Where it is located

In the client installation, the shared Caddy layer is created by the installer in the folder:

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

Inside are:

| File or folder       | Purpose                                      |
| -------------------- | -------------------------------------------- |
| `Caddyfile`          | Domain, route, and error rules.              |
| `docker-compose.yml` | Starting the Caddy container.                |
| `www/index.html`     | Language selection and redirect page.        |
| `www/errors`         | Pages `403`, `404`, `502`.                   |
| `www/assets`         | Shared styles and background for edge pages. |

### How the request is handled

```mermaid
flowchart TB
    A["https://example.com"] --> B["Caddy edge"]
    B --> C{"Request path"}
    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["language selection page"]
    C -->|"error"| E["/errors/403.html, 404.html, 502.html"]
```

### What Caddy does

| Task        | What happens                                                        |
| ----------- | ------------------------------------------------------------------- |
| HTTPS       | Caddy automatically serves HTTPS certificates.                      |
| Routing     | Directs `/bloggers/{lang}/` to the backend of the required version. |
| Compression | Enables `zstd` and `gzip`.                                          |
| Admin panel | Disables caching for `/admin`.                                      |
| Errors      | Shows branded error pages.                                          |
| Language    | Shows a redirect page if multiple languages are installed.          |

### Language routes

{% 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 strips the external prefix `/bloggers/{lang}` before passing the request to the backend. Thanks to this, the application inside the container works as if it were exposed from the root.

### Home page

<details>

<summary>What happens when opening the domain root</summary>

If one language version is installed, Caddy can immediately redirect the user to it.

If multiple versions are installed, Caddy serves a lightweight page `www/index.html`. It detects the language of Telegram or the browser and redirects the user to the appropriate installed version.

If the needed language is not available, the fallback is used:

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

</details>

### Error pages

Caddy shows edge error pages when the request has not reached the backend or the path was not found at the edge level.

```
/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" %}
Error `502` often means that Caddy is running, but the backend of the required language version is unavailable.
{% endhint %}

### Please do not break

<details>

<summary>Ports</summary>

Caddy occupies the public ports:

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

If another web server is already running on these ports on the server, the installation may conflict.

</details>

<details>

<summary>Docker network</summary>

Backend containers are connected to the shared Docker network `bloggers_edge`. Through it, Caddy sees `backend_ru`, `backend_en`, `backend_zh` and `backend_ar`.

</details>

<details>

<summary>Manual edits to Caddyfile</summary>

The installer and `manager.sh` can regenerate Caddyfile. Therefore, manual changes are best made only if you understand how they will be preserved during an update.

</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/product-docs/product-docs-en/architecture/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.