docs: add detailed INSTALL.md and update README

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-06-06 15:05:41 +03:00
parent c4d54d1bfc
commit 006cc40bb6
2 changed files with 614 additions and 24 deletions
@@ -0,0 +1,608 @@
+# PhotoHost — Подробная инструкция по установке
+
+**Версия:** 1.0.0-beta
+
+PhotoHost — фотохостинг на Next.js 15 с PostgreSQL. Ниже описаны все способы установки: через Docker (рекомендуется), локальная разработка и production-деплой на сервер.
+
+---
+
+## Содержание
+
+1. [Требования](#1-требования)
+2. [Получение исходного кода](#2-получение-исходного-кода)
+3. [Установка через Docker (рекомендуется)](#3-установка-через-docker-рекомендуется)
+4. [Локальная разработка без Docker](#4-локальная-разработка-без-docker)
+5. [Настройка переменных окружения](#5-настройка-переменных-окружения)
+6. [Production-деплой на сервер](#6-production-деплой-на-сервер)
+7. [Проверка работоспособности](#7-проверка-работоспособности)
+8. [Обновление](#8-обновление)
+9. [Резервное копирование](#9-резервное-копирование)
+10. [Устранение неполадок](#10-устранение-неполадок)
+
+---
+
+## 1. Требования
+
+### Для установки через Docker (минимальный набор)
+
+| Компонент | Минимальная версия |
+|-----------|-------------------|
+| Docker | 24.0+ |
+| Docker Compose | 2.20+ |
+| Свободная RAM | 1 ГБ |
+| Свободное место на диске | 2 ГБ |
+
+Проверка:
+
+```bash
+docker --version
+docker compose version
+```
+
+### Для локальной разработки (дополнительно)
+
+| Компонент | Минимальная версия |
+|-----------|-------------------|
+| Node.js | 20.x или 22.x |
+| npm | 10.x+ |
+| PostgreSQL | 16.x (или Docker только для БД) |
+
+Проверка:
+
+```bash
+node --version
+npm --version
+```
+
+### Сетевые порты
+
+| Порт | Назначение |
+|------|------------|
+| `3000` | Веб-приложение PhotoHost |
+| `5432` | PostgreSQL (только при локальной разработке или если проброшен наружу) |
+
+Убедитесь, что порты свободны:
+
+```bash
+# Linux / macOS
+ss -tlnp | grep -E '3000|5432'
+
+# Windows PowerShell
+netstat -ano | findstr ":3000"
+netstat -ano | findstr ":5432"
+```
+
+---
+
+## 2. Получение исходного кода
+
+### Из Git-репозитория
+
+```bash
+git clone https://git.evilfox.cc/test2/hosting-files.git photohost
+cd photohost
+```
+
+### Из архива релиза
+
+Скачайте архив с [страницы релиза v1.0.0-beta](https://git.evilfox.cc/test2/hosting-files/releases/tag/v1.0.0-beta) и распакуйте:
+
+```bash
+# Linux / macOS
+tar -xzf hosting-files-1.0.0-beta.tar.gz
+cd hosting-files
+
+# Windows PowerShell
+Expand-Archive hosting-files-1.0.0-beta.zip -DestinationPath photohost
+cd photohost
+```
+
+---
+
+## 3. Установка через Docker (рекомендуется)
+
+Самый простой способ — один контейнер с приложением и один с PostgreSQL. База данных и загруженные файлы сохраняются в Docker volumes.
+
+### Шаг 1. Перейдите в каталог проекта
+
+```bash
+cd photohost
+```
+
+### Шаг 2. (Опционально) Измените пароль БД
+
+По умолчанию используются учётные данные из `docker-compose.yml`:
+
+| Параметр | Значение по умолчанию |
+|----------|----------------------|
+| Пользователь БД | `photohost` |
+| Пароль БД | `photohost_secret` |
+| Имя базы | `photohost` |
+
+Для production **обязательно** смените пароль. Откройте `docker-compose.yml` и измените:
+
+```yaml
+environment:
+  POSTGRES_PASSWORD: ваш_надёжный_пароль
+```
+
+И в секции `app`:
+
+```yaml
+environment:
+  DATABASE_URL: postgresql://photohost:ваш_надёжный_пароль@db:5432/photohost?schema=public
+```
+
+### Шаг 3. Сборка и запуск
+
+```bash
+docker compose up --build -d
+```
+
+Флаги:
+- `--build` — пересобрать образ приложения
+- `-d` — запуск в фоновом режиме
+
+Первый запуск занимает 2–5 минут (скачивание образов, установка npm-зависимостей, сборка Next.js).
+
+### Шаг 4. Проверка статуса контейнеров
+
+```bash
+docker compose ps
+```
+
+Ожидаемый результат:
+
+```
+NAME            STATUS          PORTS
+photohost-app   Up              0.0.0.0:3000->3000/tcp
+photohost-db    Up (healthy)    0.0.0.0:5432->5432/tcp
+```
+
+### Шаг 5. Просмотр логов (при необходимости)
+
+```bash
+# Все сервисы
+docker compose logs -f
+
+# Только приложение
+docker compose logs -f app
+
+# Только база данных
+docker compose logs -f db
+```
+
+### Шаг 6. Откройте в браузере
+
+```
+http://localhost:3000
+```
+
+### Управление сервисами
+
+```bash
+# Остановить
+docker compose stop
+
+# Запустить снова
+docker compose start
+
+# Остановить и удалить контейнеры (данные в volumes сохранятся)
+docker compose down
+
+# Остановить и удалить всё, включая volumes (УДАЛИТ ДАННЫЕ!)
+docker compose down -v
+```
+
+---
+
+## 4. Локальная разработка без Docker
+
+Подходит для разработки и отладки. PostgreSQL можно запустить в Docker, а приложение — локально через Node.js.
+
+### Шаг 1. Установите Node.js
+
+Скачайте LTS-версию с [nodejs.org](https://nodejs.org/) (рекомендуется 22.x).
+
+### Шаг 2. Создайте файл `.env`
+
+```bash
+# Linux / macOS
+cp .env.example .env
+
+# Windows PowerShell
+Copy-Item .env.example .env
+```
+
+Содержимое `.env`:
+
+```env
+DATABASE_URL="postgresql://photohost:photohost_secret@localhost:5432/photohost?schema=public"
+```
+
+### Шаг 3. Запустите PostgreSQL
+
+**Вариант A — PostgreSQL в Docker (рекомендуется):**
+
+```bash
+docker compose up db -d
+```
+
+**Вариант B — локально установленный PostgreSQL:**
+
+```sql
+CREATE USER photohost WITH PASSWORD 'photohost_secret';
+CREATE DATABASE photohost OWNER photohost;
+```
+
+### Шаг 4. Установите зависимости
+
+```bash
+npm install
+```
+
+### Шаг 5. Примените схему базы данных
+
+```bash
+npx prisma db push
+```
+
+Команда создаст таблицу `Photo` в PostgreSQL согласно `prisma/schema.prisma`.
+
+### Шаг 6. Создайте каталог для загрузок
+
+```bash
+# Linux / macOS
+mkdir -p public/uploads
+
+# Windows PowerShell
+New-Item -ItemType Directory -Force -Path public\uploads
+```
+
+### Шаг 7. Запустите dev-сервер
+
+```bash
+npm run dev
+```
+
+Приложение будет доступно на [http://localhost:3000](http://localhost:3000) с hot-reload.
+
+### Полезные команды для разработки
+
+```bash
+npm run build      # Production-сборка
+npm run start      # Запуск production-сборки локально
+npm run lint       # Проверка ESLint
+npm run db:push    # Синхронизация схемы БД
+npm run db:generate # Перегенерация Prisma Client
+```
+
+---
+
+## 5. Настройка переменных окружения
+
+| Переменная | Обязательная | Описание | Пример |
+|------------|-------------|----------|--------|
+| `DATABASE_URL` | Да | Строка подключения к PostgreSQL | `postgresql://user:pass@host:5432/photohost?schema=public` |
+| `NODE_ENV` | Нет | Режим работы (`development` / `production`) | `production` |
+
+### Формат DATABASE_URL
+
+```
+postgresql://[пользователь]:[пароль]@[хост]:[порт]/[база]?schema=public
+```
+
+Примеры:
+
+```env
+# Docker Compose (app → db)
+DATABASE_URL="postgresql://photohost:photohost_secret@db:5432/photohost?schema=public"
+
+# Локальная разработка
+DATABASE_URL="postgresql://photohost:photohost_secret@localhost:5432/photohost?schema=public"
+
+# Внешний PostgreSQL-сервер
+DATABASE_URL="postgresql://photohost:secret@192.168.1.100:5432/photohost?schema=public"
+```
+
+> **Важно:** файл `.env` не коммитится в Git. Никогда не публикуйте пароли в репозитории.
+
+---
+
+## 6. Production-деплой на сервер
+
+### 6.1. Подготовка сервера (Linux)
+
+```bash
+# Ubuntu / Debian
+sudo apt update && sudo apt install -y git docker.io docker-compose-plugin
+
+# Запуск Docker
+sudo systemctl enable docker
+sudo systemctl start docker
+
+# Добавить пользователя в группу docker (перелогиньтесь после)
+sudo usermod -aG docker $USER
+```
+
+### 6.2. Клонирование и настройка
+
+```bash
+git clone https://git.evilfox.cc/test2/hosting-files.git /opt/photohost
+cd /opt/photohost
+```
+
+Измените пароль БД в `docker-compose.yml` (см. раздел 3, шаг 2).
+
+### 6.3. Запуск
+
+```bash
+docker compose up --build -d
+```
+
+### 6.4. Reverse proxy (Nginx)
+
+Для доступа по домену и HTTPS настройте Nginx как прокси:
+
+```nginx
+server {
+    listen 80;
+    server_name photos.example.com;
+
+    client_max_body_size 10M;
+
+    location / {
+        proxy_pass http://127.0.0.1:3000;
+        proxy_http_version 1.1;
+        proxy_set_header Upgrade $http_upgrade;
+        proxy_set_header Connection 'upgrade';
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+        proxy_cache_bypass $http_upgrade;
+    }
+}
+```
+
+Получите SSL-сертификат через Certbot:
+
+```bash
+sudo apt install certbot python3-certbot-nginx
+sudo certbot --nginx -d photos.example.com
+```
+
+### 6.5. Автозапуск при перезагрузке сервера
+
+Docker Compose с `restart: unless-stopped` (уже настроено в `docker-compose.yml`) автоматически перезапускает контейнеры после reboot.
+
+Проверка:
+
+```bash
+sudo reboot
+# после перезагрузки:
+docker compose ps
+```
+
+### 6.6. Firewall
+
+```bash
+# UFW (Ubuntu)
+sudo ufw allow 80/tcp
+sudo ufw allow 443/tcp
+sudo ufw enable
+
+# Порт 5432 НЕ открывайте наружу — база доступна только внутри Docker-сети
+```
+
+Для production рекомендуется убрать проброс порта `5432` из `docker-compose.yml`:
+
+```yaml
+# Удалите или закомментируйте:
+# ports:
+#   - "5432:5432"
+```
+
+---
+
+## 7. Проверка работоспособности
+
+### 7.1. Веб-интерфейс
+
+Откройте `http://localhost:3000` (или ваш домен). Должна отображаться главная страница с зоной загрузки.
+
+### 7.2. Загрузка тестового изображения
+
+1. Перетащите JPG/PNG файл в зону загрузки (или нажмите для выбора).
+2. Дождитесь сообщения «Фото загружено!».
+3. Скопируйте полученную ссылку и откройте в новой вкладке — изображение должно отображаться.
+
+### 7.3. API
+
+```bash
+# Список фото
+curl http://localhost:3000/api/photos
+
+# Загрузка файла
+curl -X POST http://localhost:3000/api/upload \
+  -F "file=@/path/to/image.jpg"
+```
+
+### 7.4. База данных
+
+```bash
+docker compose exec db psql -U photohost -d photohost -c "SELECT id, \"originalName\", \"createdAt\" FROM \"Photo\" ORDER BY \"createdAt\" DESC LIMIT 5;"
+```
+
+### 7.5. Файлы на диске
+
+```bash
+docker compose exec app ls -la /app/public/uploads/
+```
+
+---
+
+## 8. Обновление
+
+### Docker-установка
+
+```bash
+cd /opt/photohost   # или ваш каталог
+
+# Получить новую версию
+git pull origin main
+
+# Пересобрать и перезапустить
+docker compose up --build -d
+```
+
+### Локальная разработка
+
+```bash
+git pull origin main
+npm install
+npx prisma db push
+npm run build   # для production
+```
+
+---
+
+## 9. Резервное копирование
+
+### База данных
+
+```bash
+# Создать дамп
+docker compose exec db pg_dump -U photohost photohost > backup_$(date +%Y%m%d).sql
+
+# Восстановить из дампа
+cat backup_20260606.sql | docker compose exec -T db psql -U photohost photohost
+```
+
+### Загруженные файлы
+
+Файлы хранятся в Docker volume `uploads_data`:
+
+```bash
+# Узнать имя volume
+docker volume ls | grep uploads
+
+# Скопировать файлы из volume
+docker run --rm -v hosting_uploads_data:/data -v $(pwd):/backup alpine \
+  tar czf /backup/uploads_backup.tar.gz -C /data .
+```
+
+### Автоматический бэкап (cron)
+
+```bash
+# crontab -e
+0 3 * * * cd /opt/photohost && docker compose exec -T db pg_dump -U photohost photohost | gzip > /backups/photohost_$(date +\%Y\%m\%d).sql.gz
+```
+
+---
+
+## 10. Устранение неполадок
+
+### Приложение не запускается
+
+```bash
+docker compose logs app
+```
+
+**Частые причины:**
+- База данных ещё не готова — подождите 10–15 секунд и проверьте `docker compose ps`
+- Ошибка сборки — убедитесь, что достаточно RAM (минимум 1 ГБ)
+
+### Ошибка подключения к БД
+
+```
+Error: P1001: Can't reach database server
+```
+
+**Решение:**
+1. Проверьте, что контейнер `photohost-db` в статусе `healthy`:
+   ```bash
+   docker compose ps
+   ```
+2. Проверьте `DATABASE_URL` — хост должен быть `db` внутри Docker, `localhost` при локальной разработке.
+3. Перезапустите сервисы:
+   ```bash
+   docker compose restart
+   ```
+
+### Порт 3000 занят
+
+```bash
+# Linux / macOS — найти процесс
+lsof -i :3000
+
+# Windows
+netstat -ano | findstr ":3000"
+```
+
+Измените порт в `docker-compose.yml`:
+
+```yaml
+ports:
+  - "8080:3000"   # доступ через http://localhost:8080
+```
+
+### Загрузка файлов не работает
+
+1. Проверьте права на каталог `public/uploads/`
+2. Убедитесь, что файл — изображение (JPG, PNG, GIF, WebP) и меньше 10 МБ
+3. При использовании Nginx проверьте `client_max_body_size 10M;`
+
+### Ошибка Prisma при первом запуске
+
+```bash
+# Вручную применить схему
+docker compose exec app npx prisma db push
+```
+
+### Полный сброс (удалить все данные)
+
+```bash
+docker compose down -v
+docker compose up --build -d
+```
+
+> **Внимание:** команда `-v` удалит все загруженные фото и данные из базы.
+
+---
+
+## Структура проекта
+
+```
+photohost/
+├── docker-compose.yml      # Оркестрация: app + PostgreSQL
+├── Dockerfile              # Сборка production-образа
+├── .env.example            # Шаблон переменных окружения
+├── package.json            # Зависимости Node.js
+├── prisma/
+│   └── schema.prisma       # Схема базы данных
+├── public/
+│   ├── icon.svg            # Иконка сайта
+│   └── uploads/            # Загруженные изображения
+├── src/
+│   ├── app/
+│   │   ├── api/
+│   │   │   ├── upload/     # POST — загрузка фото
+│   │   │   └── photos/     # GET — список фото
+│   │   ├── globals.css     # Стили
+│   │   ├── layout.tsx      # Корневой layout
+│   │   └── page.tsx        # Главная страница
+│   ├── components/         # UI-компоненты
+│   └── lib/
+│       └── prisma.ts       # Клиент Prisma
+├── CHANGELOG.md
+├── INSTALL.md              # Эта инструкция
+└── README.md
+```
+
+---
+
+## Поддержка
+
+- Репозиторий: https://git.evilfox.cc/test2/hosting-files
+- Релизы: https://git.evilfox.cc/test2/hosting-files/releases