test/shop10
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 5 Wiki Activity

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

Browse Source 
Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
shop
2026-05-17 09:47:47 +03:00
parent c6bac33c71
commit b9e6060610
7 changed files with 586 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+2
View File
@@ -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
+53
View File
@@ -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
+50
View File
@@ -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
+143
View File
@@ -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
+244
View File
@@ -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
+88
View File
@@ -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
+6
View File
@@ -0,0 +1,6 @@
### Навигация
- [Главная](Home)
- [Установка — Docker](Install-Docker)
- [Установка — без Docker](Install-Native)
- [Решение проблем](Troubleshooting)