From 006cc40bb6b21e2e6bd61988fd0312f4858bbabc Mon Sep 17 00:00:00 2001 From: orohi Date: Sat, 6 Jun 2026 15:05:41 +0300 Subject: [PATCH] docs: add detailed INSTALL.md and update README Co-authored-by: Cursor --- INSTALL.md | 608 +++++++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 30 +-- 2 files changed, 614 insertions(+), 24 deletions(-) create mode 100644 INSTALL.md diff --git a/INSTALL.md b/INSTALL.md new file mode 100644 index 0000000..03ae833 --- /dev/null +++ b/INSTALL.md @@ -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 diff --git a/README.md b/README.md index 6998b43..8f8a520 100644 --- a/README.md +++ b/README.md @@ -13,36 +13,18 @@ - PostgreSQL для хранения метаданных - Docker Compose для простого деплоя -## Быстрый старт (Docker) +## Установка + +Подробная инструкция по установке, настройке и деплою — в файле **[INSTALL.md](./INSTALL.md)**. + +### Быстрый старт (Docker) ```bash -docker compose up --build +docker compose up --build -d ``` Приложение будет доступно на [http://localhost:3000](http://localhost:3000) -## Локальная разработка - -1. Скопируйте `.env.example` в `.env`: - -```bash -cp .env.example .env -``` - -2. Запустите PostgreSQL: - -```bash -docker compose up db -d -``` - -3. Установите зависимости и запустите: - -```bash -npm install -npx prisma db push -npm run dev -``` - ## Стек - **Frontend:** Next.js 15, React 19, Tailwind CSS 4