docs/quick-start.md

# Быстрый старт: минимальное развертывание Welley

Самый короткий путь к работающему экземпляру Welley на одном Linux-сервере: в любом облаке или на вашем собственном оборудовании. Здесь используются только те флаги, которые CLI действительно требует, всё остальное остаётся по умолчанию.

Что вы получите: платформу, RAG-конвейер, Nginx, Redis и **встроенный** контейнер PostgreSQL, а также сертификат Let's Encrypt, который выпускается во время установки. Управляемой базы данных, CDN, телеметрии и интеграции со Slack здесь нет. Для них см. руководства по AWS EC2 и DigitalOcean.

## 1\. Что понадобится

**Linux-сервер**

-   Ubuntu 24.04 LTS (или похожий актуальный дистрибутив).
-   Для начала 2 vCPU, 4 ГБ оперативной памяти и 60 ГБ диска.
-   Публичный IPv4-адрес, который не меняется.
-   Входящие TCP-порты **80** и **443** открыты для интернета, а порт **22** открыт для вас. Порт 80 нужен во время установки для проверки при выпуске сертификата, а потом для еженедельного продления.
-   Пользователь без прав root, но с `sudo`. В этом руководстве всё запускается от него, дальше он обозначен как `<user>`.

**DNS**

Две записи, обе указывают на публичный IP сервера:

| Запись | Назначение |
| --- | --- |
| `<domain>` | сам сайт |
| `storage.<domain>` | загруженные и статические файлы, потому что в этой конфигурации нет CDN |

Создайте их до начала установки: CLI проверяет, что оба имени указывают на этот сервер, и останавливается, если это не так.

**DNS-записи для почты**

Для домена вашего адреса в `--smtp-from` нужны записи аутентификации почты. Без них Gmail, Outlook и другие крупные почтовые сервисы часто не доставляют письма получателям, которые раньше ничего от вас не получали. Это касается всех приглашений и подтверждений регистрации. Письма при этом даже не попадают в спам, хотя ваш SMTP-провайдер сообщает, что отправил их.

| Запись | Тип | Значение |
| --- | --- | --- |
| `<mail-domain>` | TXT | SPF, например `v=spf1 include:<provider> ~all`. Точное значение возьмите у вашего SMTP-провайдера |
| `_dmarc.<mail-domain>` | TXT | DMARC, например `v=DMARC1; p=none; rua=mailto:dmarc@<mail-domain>` |
| `<selector>._domainkey.<mail-domain>` | TXT или CNAME | DKIM, его создаёт ваш SMTP-провайдер, когда вы подтверждаете домен |

У домена может быть только одна запись SPF. Если она уже есть, добавьте в неё своего провайдера, а не создавайте вторую. Команда `create` предупредит, если SPF или DMARC нет, но не остановится. Проверить DKIM она не может, потому что имя селектора зависит от вашего провайдера.

Не пропускайте DKIM. Многие провайдеры, в том числе Amazon SES, по умолчанию отправляют письма со своим доменом в качестве адреса отправителя в конверте. Тогда SPF проверяет домен провайдера, а не ваш, поэтому он не учитывается в DMARC, и пройти DMARC помогает только DKIM. Состояние DKIM смотрите в консоли вашего провайдера. В Amazon SES оно находится в разделе _Verified identities, затем `<mail-domain>`, затем DKIM_ и должно быть _Successful_. SES Easy DKIM публикует три CNAME-записи с именами `<token>._domainkey.<mail-domain>`.

**Данные для SMTP**

Хост, пользователь, пароль и адрес отправителя от любого провайдера. Платформе они нужны для подтверждения почты и восстановления пароля, и без них CLI не будет устанавливать систему. По умолчанию предполагается отправка через STARTTLS на порту 587.

**Email администратора** для первого входа и восстановления пароля.

## 2\. Установите Docker

Следуйте официальной инструкции для вашего дистрибутива: [Install Docker Engine](https://docs.docker.com/engine/install/). Затем разрешите своему пользователю работать с демоном:

```
sudo usermod -aG docker <user>
```

Выйдите из системы и войдите снова, затем проверьте, что обе части на месте:

```
docker ps
docker compose version
```

## 3\. Скачайте CLI

Выберите значение `platform`, которое подходит вашему серверу:

**linux/amd64**

```

curl -fL "https://appstore.allroads.social/v1/social.wellesley.wlycli/latest?channel=stable&platform=linux/amd64" -o wlycli
chmod +x wlycli
./wlycli -v
  
```
  **linux/arm64**

```

curl -fL "https://appstore.allroads.social/v1/social.wellesley.wlycli/latest?channel=stable&platform=linux/arm64" -o wlycli
chmod +x wlycli
./wlycli -v
  
```
  **darwin/arm64**

```

curl -fL "https://appstore.allroads.social/v1/social.wellesley.wlycli/latest?channel=stable&platform=darwin/arm64" -o wlycli
chmod +x wlycli
./wlycli -v
  
```
  **darwin/amd64**

```

curl -fL "https://appstore.allroads.social/v1/social.wellesley.wlycli/latest?channel=stable&platform=darwin/amd64" -o wlycli
chmod +x wlycli
./wlycli -v
  
```
  

## 4\. Развертывание

```
./wlycli deploy create \
-d example.com \
-e admin@example.com \
--smtp-host smtp.example.com \
--smtp-user "$MAIL_USER" \
--smtp-password "$MAIL_PASSWORD" \
--smtp-from noreply@example.com
```

Эти шесть флагов составляют весь обязательный набор. Команда проверяет DNS, записывает файлы развертывания, выпускает сертификат через Certbot и запускает контейнеры. Рассчитывайте, что это займёт несколько минут.

Значения по умолчанию, с которыми вы соглашаетесь:

| Настройка | Значение по умолчанию |
| --- | --- |
| Каталог установки | `~/.welley/<project>`, где `<project>` это домен, в котором каждый символ, не являющийся буквой или цифрой, заменён на `_` (так `example.com` становится `example_com`) |
| База данных | встроенный контейнер PostgreSQL, данные хранятся в каталоге установки |
| Сертификаты | Let's Encrypt через Certbot, автоматически продлеваются раз в неделю |
| Загруженные и статические файлы | отдаются с `https://storage.<domain>` |
| Обновления | канал `stable`, проверка раз в день, по возможности применяются без простоя |

## 5\. Первый вход

Сгенерированный пароль администратора выводится в лог платформы:

```
docker logs example_com-platform-blue-1 | grep "Auto-init complete"
```

Откройте `https://<domain>`, войдите с email администратора, который вы передали через `-e`, и сразу смените пароль. Пока вы этого не сделали, считайте лог секретным.

## 6\. Проверьте результат

```
docker ps
```

Вы должны увидеть по одному контейнеру для `nginx`, `platform-blue`, `rag-pipeline-blue`, `postgres`, `redis`, `autoheal` и `snoopy`. Все они называются `<project>-<service>-1`.

## Если что-то пошло не так

Команда `create` не запустится повторно, пока существует каталог проекта или его контейнеры. Если файлы в порядке, а не запустились только некоторые контейнеры, пересоздайте их, ничего не потеряв:

```
./wlycli deploy restart -d example.com
```

Если само развертывание нужно сделать заново, удалите его и начните сначала. Это удалит встроенную базу данных вместе со всем остальным:

```
./wlycli deploy delete -d example.com --yes-please-delete-all-the-data
```

## Другие документы

-   [**Welley CLI** docs/index.md](https://welley.com/ru/administrators/docs/cli/)
-   [**Развертывание сервера** skills/deploy-server/SKILL.md](https://welley.com/ru/administrators/docs/deploy-server-skill/)
-   [**openai.yaml** skills/deploy-server/agents/openai.yaml](https://welley.com/ru/administrators/docs/deploy-server-openai-yaml/)
-   [**Справка по DigitalOcean** skills/deploy-server/references/digitalocean.md](https://welley.com/ru/administrators/docs/deploy-server-digitalocean/)