docs: wiki — установка Docker и без Docker (v0.10.0)

Co-authored-by: Cursor <cursoragent@cursor.com>

README.md

@@ -6,6 +6,8 @@
 
 Подробности релиза: [CHANGELOG.md](CHANGELOG.md) · [docs/RELEASE-0.10.md](docs/RELEASE-0.10.md)
 
+**Wiki (установка):** https://git.evilfox.cc/test/shop10/wiki
+
 ## Возможности
 
 - Каталог товаров с категориями и поиском

scripts/push-wiki.sh

@@ -0,0 +1,53 @@
+#!/bin/bash
+# Публикация wiki/ в Gitea Wiki
+# Использование:
+#   export GITEA_TOKEN=токен   # или настройте git credentials
+#   bash scripts/push-wiki.sh
+set -euo pipefail
+
+GITEA_WIKI_URL="${GITEA_WIKI_URL:-https://git.evilfox.cc/test/shop10.wiki.git}"
+REPO_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+WIKI_SRC="${REPO_ROOT}/wiki"
+TMPDIR="${TMPDIR:-/tmp}/shop-wiki-$$"
+
+if [ ! -d "$WIKI_SRC" ]; then
+  echo "Нет каталога wiki/"
+  exit 1
+fi
+
+cleanup() { rm -rf "$TMPDIR"; }
+trap cleanup EXIT
+
+if [ -n "${GITEA_TOKEN:-}" ]; then
+  CLONE_URL="https://${GITEA_TOKEN}@${GITEA_WIKI_URL#https://}"
+else
+  CLONE_URL="$GITEA_WIKI_URL"
+fi
+
+if git clone "$CLONE_URL" "$TMPDIR" 2>/dev/null; then
+  :
+else
+  echo "Клонирование wiki (первый раз)..."
+  mkdir -p "$TMPDIR"
+  cd "$TMPDIR"
+  git init
+  git remote add origin "$CLONE_URL"
+  cd -
+fi
+
+rsync -a --delete "${WIKI_SRC}/" "${TMPDIR}/"
+
+cd "$TMPDIR"
+git add -A
+if git diff --staged --quiet; then
+  echo "Wiki без изменений."
+  exit 0
+fi
+
+git config user.email "wiki@shop.local"
+git config user.name "Shop Wiki"
+git commit -m "docs: установка Docker и без Docker (v0.10.0)"
+git branch -M main 2>/dev/null || true
+git push -u origin main
+
+echo "Wiki опубликована: https://git.evilfox.cc/test/shop10/wiki"

wiki/Home.md

@@ -0,0 +1,50 @@
+# Shop — документация v0.10.0
+
+Интернет-магазин на **Node.js** и **PostgreSQL 17**.
+
+## Способы установки
+
+| Способ | Когда использовать |
+|--------|-------------------|
+| **[Установка через Docker](Install-Docker)** | Быстрый старт, тест, изолированное окружение |
+| **[Установка без Docker](Install-Native)** | Production на Ubuntu, systemd, свой Caddy |
+
+## Требования
+
+**Docker:** Docker Engine 24+, Docker Compose v2.
+
+**Без Docker:** Ubuntu 22.04 / 24.04, Node.js 20, PostgreSQL 17.
+
+## Быстрый старт
+
+### Docker (3 команды)
+
+```bash
+git clone https://git.evilfox.cc/test/shop10.git && cd shop10
+git checkout v0.10.0
+cp .env.docker.example .env && docker compose up -d --build
+```
+
+Сайт: http://localhost:3000
+
+### Без Docker
+
+```bash
+git clone https://git.evilfox.cc/test/shop10.git && cd shop10
+git checkout v0.10.0
+# см. Install-Native
+```
+
+## Проверка работы
+
+```bash
+curl -s http://127.0.0.1:3000/health
+```
+
+Ожидается: `{"ok":true,"service":"shop","database":"postgresql"}`
+
+## Ссылки
+
+- [Репозиторий](https://git.evilfox.cc/test/shop10)
+- [Releases](https://git.evilfox.cc/test/shop10/releases)
+- [Решение проблем](Troubleshooting)

wiki/Install-Docker.md

@@ -0,0 +1,143 @@
+# Установка через Docker Compose
+
+Полный стек в контейнерах: **PostgreSQL 17** + **приложение Shop** (+ опционально **Caddy** для HTTPS).
+
+## 1. Требования
+
+- Docker Engine 24 или новее
+- Docker Compose v2 (`docker compose`)
+- Git
+- Порты: **3000** (сайт) или **80/443** (с Caddy)
+
+Проверка:
+
+```bash
+docker --version
+docker compose version
+```
+
+## 2. Получение кода
+
+```bash
+git clone https://git.evilfox.cc/test/shop10.git
+cd shop10
+git checkout v0.10.0
+```
+
+## 3. Настройка переменных
+
+```bash
+cp .env.docker.example .env
+nano .env
+```
+
+| Переменная | Описание | Пример |
+|------------|----------|--------|
+| `POSTGRES_USER` | Пользователь БД | `shop` |
+| `POSTGRES_PASSWORD` | Пароль БД | смените в production |
+| `POSTGRES_DB` | Имя базы | `shop` |
+| `SESSION_SECRET` | Секрет сессий | `openssl rand -hex 32` |
+| `APP_PORT` | Порт на хосте | `3000` |
+| `TRUST_PROXY` | За Caddy: `1`, иначе `0` | `0` |
+
+## 4. Запуск
+
+```bash
+docker compose up -d --build
+```
+
+Первый запуск: сборка образа `app`, скачивание `postgres:17-alpine`, создание таблиц и демо-товаров.
+
+Статус:
+
+```bash
+docker compose ps
+docker compose logs -f app
+```
+
+## 5. Проверка
+
+```bash
+curl -s http://127.0.0.1:3000/health
+```
+
+В браузере: **http://IP_СЕРВЕРА:3000** или **http://localhost:3000**
+
+## 6. HTTPS с Caddy (опционально)
+
+1. В `.env` установите `TRUST_PROXY=1`
+2. Отредактируйте `caddy/Caddyfile.docker.example`:
+   - укажите свой домен вместо `shop.example.com`
+   - или оставьте блок `:80` для доступа по IP
+3. Запуск:
+
+```bash
+docker compose --profile proxy up -d --build
+```
+
+Открыты порты **80** и **443**. Контейнер `caddy` проксирует на `app:3000`.
+
+## 7. Полезные команды
+
+| Команда | Действие |
+|---------|----------|
+| `docker compose logs -f app` | Логи приложения |
+| `docker compose logs -f postgres` | Логи БД |
+| `docker compose restart app` | Перезапуск приложения |
+| `docker compose down` | Остановить контейнеры |
+| `docker compose down -v` | Остановить и **удалить данные БД** |
+| `docker compose up -d --build` | Пересборка после `git pull` |
+
+## 8. Обновление версии
+
+```bash
+cd shop10
+git fetch --tags
+git checkout v0.10.0   # или новый тег
+docker compose up -d --build
+```
+
+## 9. Только PostgreSQL (разработка)
+
+Приложение на хосте (`npm run dev`), БД в Docker:
+
+```bash
+docker compose -f docker-compose.dev.yml up -d
+cp .env.example .env
+```
+
+В `.env`:
+
+```env
+DATABASE_URL=postgresql://shop:shop@127.0.0.1:5432/shop
+HOST=0.0.0.0
+```
+
+```bash
+npm install
+npm run dev
+```
+
+## 10. Архитектура
+
+```
+┌─────────────┐     ┌──────────────┐     ┌─────────────┐
+│   Браузер   │────▶│ Caddy :443   │────▶│  app :3000  │
+│             │     │ (опционально)│     │   Node.js   │
+└─────────────┘     └──────────────┘     └──────┬──────┘
+                                                 │
+                                          ┌──────▼──────┐
+                                          │ postgres:17 │
+                                          └─────────────┘
+```
+
+## 11. Типичные ошибки
+
+| Симптом | Решение |
+|---------|---------|
+| `port is already allocated` | Смените `APP_PORT` в `.env` или освободите порт 3000 |
+| `app` unhealthy | `docker compose logs app` — часто нет связи с postgres |
+| Пустой каталог | Подождите seed; `docker compose logs app` |
+| 502 с Caddy | `TRUST_PROXY=1`, проверьте `docker compose ps` |
+
+Подробнее: [Решение проблем](Troubleshooting)

wiki/Install-Native.md

@@ -0,0 +1,244 @@
+# Установка без Docker (Ubuntu)
+
+Production-развёртывание на **Ubuntu 22.04 / 24.04**: Node.js 20, PostgreSQL 17, systemd, опционально Caddy.
+
+## 1. Требования
+
+- Сервер Ubuntu 22.04 или 24.04 (root или sudo)
+- Минимум 1 GB RAM, 10 GB диск
+- Открыты порты **22**, **80**, **443** (если используете Caddy)
+- Порт **3000** наружу не открывать — только localhost
+
+## 2. Установка системных пакетов
+
+```bash
+apt update
+apt install -y git curl ca-certificates
+```
+
+### Node.js 20 LTS
+
+```bash
+curl -fsSL https://deb.nodesource.com/setup_20.x | bash -
+apt install -y nodejs
+node -v   # v20.x
+```
+
+### PostgreSQL 17
+
+```bash
+apt install -y postgresql-17 postgresql-client-17
+systemctl enable postgresql
+systemctl start postgresql
+pg_isready -h 127.0.0.1 -p 5432
+```
+
+Если пакет `postgresql-17` не найден — [репозиторий PGDG](https://www.postgresql.org/download/linux/ubuntu/):
+
+```bash
+apt install -y curl ca-certificates
+install -d /usr/share/postgresql-common/pgdg
+curl -o /usr/share/postgresql-common/pgdg/apt.postgresql.org.asc --fail \
+  https://www.postgresql.org/media/keys/ACCC4CF8.asc
+sh -c 'echo "deb [signed-by=/usr/share/postgresql-common/pgdg/apt.postgresql.org.asc] https://apt.postgresql.org/pub/repos/apt $(. /etc/os-release && echo ${VERSION_CODENAME}-pgdg) main" > /etc/apt/sources.list.d/pgdg.list'
+apt update
+apt install -y postgresql-17 postgresql-client-17
+```
+
+## 3. Клонирование проекта
+
+```bash
+cd /opt
+git clone https://git.evilfox.cc/test/shop10.git shop
+cd shop
+git checkout v0.10.0
+```
+
+## 4. База данных PostgreSQL
+
+```bash
+cd /opt/shop
+bash scripts/setup-postgres-ubuntu.sh
+```
+
+Скрипт:
+- запускает PostgreSQL;
+- создаёт пользователя и БД `shop` (по умолчанию пароль `shop` — **смените в production**);
+- выводит строку `DATABASE_URL`.
+
+Проверка:
+
+```bash
+psql "postgresql://shop:shop@127.0.0.1:5432/shop" -c "SELECT 1"
+```
+
+## 5. Файл окружения `.env`
+
+```bash
+cp .env.example .env
+nano .env
+```
+
+Обязательные параметры:
+
+```env
+PORT=3000
+HOST=127.0.0.1
+NODE_ENV=production
+TRUST_PROXY=1
+SESSION_SECRET=сгенерируйте_длинную_строку
+DATABASE_URL=postgresql://shop:ВАШ_ПАРОЛЬ@127.0.0.1:5432/shop
+```
+
+Секрет сессии:
+
+```bash
+openssl rand -hex 32
+```
+
+`HOST=127.0.0.1` — приложение доступно только локально; снаружи — через Caddy.
+
+## 6. Установка зависимостей Node.js
+
+```bash
+cd /opt/shop
+npm install --omit=dev
+```
+
+При первом запуске приложение создаст таблицы и демо-товары (если каталог пуст).
+
+## 7. Служба systemd
+
+```bash
+cp /opt/shop/deploy/shop.service /etc/systemd/system/shop.service
+systemctl daemon-reload
+systemctl enable shop
+systemctl start shop
+systemctl status shop
+```
+
+Unit ждёт PostgreSQL (`ExecStartPre` + `pg_isready`) и запускает Node от пользователя `www-data`.
+
+**Важно:** не выполняйте `chown -R www-data /opt/shop` — это ломает `git pull`. Права на запись нужны только для каталога `data/` (если используется); с PostgreSQL каталог `data/` не обязателен.
+
+Логи:
+
+```bash
+journalctl -u shop -f
+```
+
+## 8. Проверка backend
+
+```bash
+curl -s http://127.0.0.1:3000/health
+ss -tlnp | grep 3000
+```
+
+В логах должно быть: `Магазин: http://127.0.0.1:3000 (PostgreSQL)`
+
+## 9. Caddy — HTTPS и reverse proxy
+
+Установка Caddy:
+
+```bash
+apt install -y debian-keyring debian-archive-keyring apt-transport-https
+curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' \
+  | gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg
+curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt' \
+  | tee /etc/apt/sources.list.d/caddy-stable.list
+apt update && apt install -y caddy
+```
+
+Конфигурация:
+
+```bash
+cp /opt/shop/caddy/Caddyfile.example /etc/caddy/Caddyfile
+nano /etc/caddy/Caddyfile
+```
+
+Пример (замените домен и email):
+
+```caddyfile
+{
+	email admin@example.com
+}
+
+shop.example.com {
+	encode gzip zstd
+	reverse_proxy 127.0.0.1:3000
+}
+```
+
+```bash
+caddy validate --config /etc/caddy/Caddyfile
+systemctl enable caddy
+systemctl reload caddy
+```
+
+Файрвол:
+
+```bash
+ufw allow 22/tcp
+ufw allow 80/tcp
+ufw allow 443/tcp
+ufw enable
+```
+
+Зависимость Caddy от shop (опционально):
+
+```bash
+mkdir -p /etc/systemd/system/caddy.service.d
+cp /opt/shop/deploy/caddy-after-shop.conf /etc/systemd/system/caddy.service.d/shop.conf
+systemctl daemon-reload
+```
+
+## 10. Обновление
+
+```bash
+cd /opt/shop
+git config --global --add safe.directory /opt/shop
+bash scripts/server-update.sh
+```
+
+Или вручную:
+
+```bash
+git pull
+npm install --omit=dev
+systemctl restart shop
+curl -s http://127.0.0.1:3000/health
+systemctl reload caddy
+```
+
+## 11. Переход с SQLite (старая версия)
+
+1. Установите PostgreSQL (шаги 2–4)
+2. Добавьте `DATABASE_URL` в `.env`
+3. `git pull` → `npm install` → `systemctl restart shop`
+4. Демо-товары появятся автоматически; пользователей нужно зарегистрировать заново
+
+Быстрое исправление подключения к БД:
+
+```bash
+bash /opt/shop/scripts/fix-db-connection.sh
+```
+
+## 12. Архитектура
+
+```
+Интернет → Caddy :443 → 127.0.0.1:3000 (Node.js shop)
+                              ↓
+                    PostgreSQL 127.0.0.1:5432
+```
+
+## 13. Резервное копирование БД
+
+```bash
+sudo -u postgres pg_dump shop > shop_backup_$(date +%F).sql
+```
+
+Восстановление:
+
+```bash
+sudo -u postgres psql shop < shop_backup_2026-05-17.sql
+```

wiki/Troubleshooting.md

@@ -0,0 +1,88 @@
+# Решение проблем
+
+## Диагностика одной командой
+
+```bash
+bash /opt/shop/scripts/diagnose-502.sh
+```
+
+---
+
+## HTTP 502 (Caddy / браузер)
+
+**SSL работает, страница 502** — Caddy жив, backend (Node) не отвечает.
+
+```bash
+curl -s http://127.0.0.1:3000/health
+systemctl status shop
+journalctl -u shop -n 30 --no-pager
+```
+
+Пока `/health` не OK — Caddy будет отдавать 502.
+
+---
+
+## ECONNREFUSED 127.0.0.1:5432
+
+PostgreSQL не запущен или не установлен.
+
+```bash
+bash /opt/shop/scripts/fix-db-connection.sh
+```
+
+Или вручную:
+
+```bash
+systemctl start postgresql
+pg_isready -h 127.0.0.1 -p 5432
+bash scripts/setup-postgres-ubuntu.sh
+```
+
+Проверьте `DATABASE_URL` в `/opt/shop/.env`.
+
+---
+
+## Служба shop сразу останавливается
+
+В логе только «База уже содержит товары» без строки `Магазин: http://...`:
+
+```bash
+cd /opt/shop && git pull   # нужен исправленный seed.js (v0.10.0+)
+systemctl restart shop
+```
+
+---
+
+## dubious ownership (git pull)
+
+Не делайте `chown -R www-data /opt/shop`.
+
+```bash
+chown -R root:root /opt/shop
+git config --global --add safe.directory /opt/shop
+git pull
+```
+
+---
+
+## Docker: контейнер app unhealthy
+
+```bash
+docker compose logs app
+docker compose logs postgres
+docker compose up -d --build
+```
+
+---
+
+## Docker: нет связи с БД
+
+Проверьте, что `DATABASE_URL` в compose указывает на хост `postgres`, а не `127.0.0.1` (внутри контейнера app).
+
+---
+
+## Полезные ссылки
+
+- [Установка Docker](Install-Docker)
+- [Установка без Docker](Install-Native)
+- [Репозиторий](https://git.evilfox.cc/test/shop10)

wiki/_Sidebar.md

@@ -0,0 +1,6 @@
+### Навигация
+
+- [Главная](Home)
+- [Установка — Docker](Install-Docker)
+- [Установка — без Docker](Install-Native)
+- [Решение проблем](Troubleshooting)