# 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