From b9e6060610e8b85778279bce7e917095c59fbdf0 Mon Sep 17 00:00:00 2001 From: shop Date: Sun, 17 May 2026 09:47:47 +0300 Subject: [PATCH] =?UTF-8?q?docs:=20wiki=20=E2=80=94=20=D1=83=D1=81=D1=82?= =?UTF-8?q?=D0=B0=D0=BD=D0=BE=D0=B2=D0=BA=D0=B0=20Docker=20=D0=B8=20=D0=B1?= =?UTF-8?q?=D0=B5=D0=B7=20Docker=20(v0.10.0)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Cursor --- README.md | 2 + scripts/push-wiki.sh | 53 +++++++++ wiki/Home.md | 50 ++++++++ wiki/Install-Docker.md | 143 +++++++++++++++++++++++ wiki/Install-Native.md | 244 ++++++++++++++++++++++++++++++++++++++++ wiki/Troubleshooting.md | 88 +++++++++++++++ wiki/_Sidebar.md | 6 + 7 files changed, 586 insertions(+) create mode 100644 scripts/push-wiki.sh create mode 100644 wiki/Home.md create mode 100644 wiki/Install-Docker.md create mode 100644 wiki/Install-Native.md create mode 100644 wiki/Troubleshooting.md create mode 100644 wiki/_Sidebar.md diff --git a/README.md b/README.md index fae7829..cd6da8d 100644 --- a/README.md +++ b/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 + ## Возможности - Каталог товаров с категориями и поиском diff --git a/scripts/push-wiki.sh b/scripts/push-wiki.sh new file mode 100644 index 0000000..6f3bafd --- /dev/null +++ b/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" diff --git a/wiki/Home.md b/wiki/Home.md new file mode 100644 index 0000000..cfaa658 --- /dev/null +++ b/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) diff --git a/wiki/Install-Docker.md b/wiki/Install-Docker.md new file mode 100644 index 0000000..2d27452 --- /dev/null +++ b/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) diff --git a/wiki/Install-Native.md b/wiki/Install-Native.md new file mode 100644 index 0000000..5f84e51 --- /dev/null +++ b/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 +``` diff --git a/wiki/Troubleshooting.md b/wiki/Troubleshooting.md new file mode 100644 index 0000000..139feef --- /dev/null +++ b/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) diff --git a/wiki/_Sidebar.md b/wiki/_Sidebar.md new file mode 100644 index 0000000..257f908 --- /dev/null +++ b/wiki/_Sidebar.md @@ -0,0 +1,6 @@ +### Навигация + +- [Главная](Home) +- [Установка — Docker](Install-Docker) +- [Установка — без Docker](Install-Native) +- [Решение проблем](Troubleshooting)