# Railway Deploy Checklist

Короткий operational checklist для стабильного деплоя `SnapLink` на Railway.

## Когда использовать этот чеклист

- перед первым production deploy
- перед релизом со сменой env
- после изменения Prisma schema
- после включения новых integrations вроде Redis, Cloudinary или Sentry

## 1. Перед релизом

- Убедись, что `README.md` и `.env.example` не расходятся с реальным runtime.
- Если менялся `prisma/schema.prisma`, в `prisma/migrations/` должна быть новая migration.
- В production не используй `prisma db push`.
- Перед пушем желательно прогнать:

```bash
npm run lint
npm run typecheck
npm run build
npm test -- --runInBand
```

## 2. Минимальные env для Railway

Обязательный минимум:

```env
DATABASE_URL=<railway postgres url>
NEXTAUTH_SECRET=<long random secret>
NEXT_PUBLIC_APP_URL=https://your-app.up.railway.app
BILLING_SETTINGS_ENCRYPTION_KEY=<64-char hex key or empty if billing disabled>

TELEGRAM_BOT_TOKEN=<bot token>
TELEGRAM_BOT_USERNAME=<bot username>
TELEGRAM_WEBHOOK_SECRET=<random secret>
TELEGRAM_ADMIN_ID=<telegram user id>

OG_STORAGE_PROVIDER=cloudinary
CLOUDINARY_CLOUD_NAME=<cloudinary cloud name>
CLOUDINARY_API_KEY=<cloudinary api key>
CLOUDINARY_API_SECRET=<cloudinary api secret>
CLOUDINARY_FOLDER=snaplink/og-images
```

Важно:

- если оставляешь `OG_STORAGE_PROVIDER=local`, убедись, что тебя устраивает хранение файлов внутри контейнера

## 3. Redis env для rate limit

Для production предпочтительно использовать Redis:

```env
RATE_LIMIT_BACKEND=redis
RATE_LIMIT_REDIS_URL=<redis url>
```

Если Redis пока не подключен, можно временно оставить:

```env
RATE_LIMIT_BACKEND=memory
```

Но это хуже подходит для нескольких инстансов.

## 4. Sentry env

Рекомендуемый минимум:

```env
SENTRY_DSN=<server sentry dsn>
NEXT_PUBLIC_SENTRY_DSN=<client sentry dsn>
SENTRY_ENVIRONMENT=production
SENTRY_RELEASE=<commit-or-tag>
SENTRY_TRACES_SAMPLE_RATE=0
SENTRY_REPLAYS_SESSION_SAMPLE_RATE=0
SENTRY_REPLAYS_ON_ERROR_SAMPLE_RATE=1
```

Если загружаешь source maps в CI/build, добавь:

```env
SENTRY_ORG=<org>
SENTRY_PROJECT=<project>
SENTRY_AUTH_TOKEN=<token>
```

## 5. Дополнительные production env

Если нужно тонко настраивать поведение, проверь:

- `NEXT_PUBLIC_ENABLE_ANALYTICS_DEBUG_UI`
- `GEO_LOOKUP_ENABLED`
- `BOT_FILTER_STRICT_MODE`
- `OG_SOURCE_FETCH_TIMEOUT_MS`
- все `RATE_LIMIT_*` thresholds из `.env.example`

Если не уверены, оставляй значения по умолчанию из `.env.example`.

## 6. Что делает Railway при старте

Railway запускает:

```bash
node scripts/start-with-migrations.mjs
```

Этот скрипт:

1. проверяет обязательные env
2. валидирует настройки storage
3. выполняет `prisma migrate deploy`
4. автоматически настраивает Telegram webhook на `<NEXT_PUBLIC_APP_URL>/api/telegram/webhook`
5. запускает production-сервер

## 7. Health и readiness probes

Используй:

- liveness: `GET /api/health`
- readiness: `GET /api/ready`

Ожидаемо после успешного старта:

- `/api/health` -> `200`
- `/api/ready` -> `200`

Если `/api/ready` возвращает `503`, приложение не готово принимать трафик.

## 8. Post-deploy smoke check

После каждого релиза проверь:

1. `GET /api/health`
2. `GET /api/ready`
3. `/login`
4. вход под `TELEGRAM_ADMIN_ID` через Telegram-бота
5. создание тестовой ссылки в `/profile`
6. редирект по `/{slug}`
7. preview через `/preview/[slug]`
8. statistics page `/profile/links/[id]`
9. если ссылка защищена паролем, flow через `/unlock/[slug]`

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

### `/api/ready` вернул `503`

- проверь `DATABASE_URL`
- проверь обязательные env
- проверь Cloudinary env, если включен `cloudinary`
- проверь `RATE_LIMIT_REDIS_URL`, если включен Redis backend

### После релиза сломались редиректы или analytics

- проверь `NEXT_PUBLIC_APP_URL`
- проверь доступность БД
- проверь, что миграции применились успешно
- проверь server logs и `requestId`

### Нужен быстрый rollback

- откати релиз до предыдущего стабильного deploy в Railway
- повтори smoke check после rollback
- только потом разбирайся с проблемным релизом