Template

Files

T

orohi 006cc40bb6 docs: add detailed INSTALL.md and update README

Co-authored-by: Cursor <cursoragent@cursor.com>

2026-06-06 15:05:41 +03:00

17 KiB

Raw Permalink Blame History

PhotoHost — Подробная инструкция по установке

Версия: 1.0.0-beta

PhotoHost — фотохостинг на Next.js 15 с PostgreSQL. Ниже описаны все способы установки: через Docker (рекомендуется), локальная разработка и production-деплой на сервер.

1. Требования

Для установки через Docker (минимальный набор)

Компонент	Минимальная версия
Docker	24.0+
Docker Compose	2.20+
Свободная RAM	1 ГБ
Свободное место на диске	2 ГБ

Проверка:

docker --version
docker compose version

Для локальной разработки (дополнительно)

Компонент	Минимальная версия
Node.js	20.x или 22.x
npm	10.x+
PostgreSQL	16.x (или Docker только для БД)

Проверка:

node --version
npm --version

Сетевые порты

Порт	Назначение
`3000`	Веб-приложение PhotoHost
`5432`	PostgreSQL (только при локальной разработке или если проброшен наружу)

Убедитесь, что порты свободны:

# Linux / macOS
ss -tlnp | grep -E '3000|5432'

# Windows PowerShell
netstat -ano | findstr ":3000"
netstat -ano | findstr ":5432"

2. Получение исходного кода

Из Git-репозитория

git clone https://git.evilfox.cc/test2/hosting-files.git photohost
cd photohost

Из архива релиза

Скачайте архив с страницы релиза v1.0.0-beta и распакуйте:

# 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. Перейдите в каталог проекта

cd photohost

Шаг 2. (Опционально) Измените пароль БД

По умолчанию используются учётные данные из docker-compose.yml:

Параметр	Значение по умолчанию
Пользователь БД	`photohost`
Пароль БД	`photohost_secret`
Имя базы	`photohost`

Для production обязательно смените пароль. Откройте docker-compose.yml и измените:

environment:
  POSTGRES_PASSWORD: ваш_надёжный_пароль

И в секции app:

environment:
  DATABASE_URL: postgresql://photohost:ваш_надёжный_пароль@db:5432/photohost?schema=public

Шаг 3. Сборка и запуск

docker compose up --build -d

Флаги:

--build — пересобрать образ приложения
-d — запуск в фоновом режиме

Первый запуск занимает 2–5 минут (скачивание образов, установка npm-зависимостей, сборка Next.js).

Шаг 4. Проверка статуса контейнеров

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. Просмотр логов (при необходимости)

# Все сервисы
docker compose logs -f

# Только приложение
docker compose logs -f app

# Только база данных
docker compose logs -f db

Шаг 6. Откройте в браузере

http://localhost:3000

Управление сервисами

# Остановить
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 (рекомендуется 22.x).

Шаг 2. Создайте файл `.env`

# Linux / macOS
cp .env.example .env

# Windows PowerShell
Copy-Item .env.example .env

Содержимое .env:

DATABASE_URL="postgresql://photohost:photohost_secret@localhost:5432/photohost?schema=public"

Шаг 3. Запустите PostgreSQL

Вариант A — PostgreSQL в Docker (рекомендуется):

docker compose up db -d

Вариант B — локально установленный PostgreSQL:

CREATE USER photohost WITH PASSWORD 'photohost_secret';
CREATE DATABASE photohost OWNER photohost;

Шаг 4. Установите зависимости

npm install

Шаг 5. Примените схему базы данных

npx prisma db push

Команда создаст таблицу Photo в PostgreSQL согласно prisma/schema.prisma.

Шаг 6. Создайте каталог для загрузок

# Linux / macOS
mkdir -p public/uploads

# Windows PowerShell
New-Item -ItemType Directory -Force -Path public\uploads

Шаг 7. Запустите dev-сервер

npm run dev

Приложение будет доступно на http://localhost:3000 с hot-reload.

Полезные команды для разработки

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

Примеры:

# 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)

# 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. Клонирование и настройка

git clone https://git.evilfox.cc/test2/hosting-files.git /opt/photohost
cd /opt/photohost

Измените пароль БД в docker-compose.yml (см. раздел 3, шаг 2).

6.3. Запуск

docker compose up --build -d

6.4. Reverse proxy (Nginx)

Для доступа по домену и HTTPS настройте 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:

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.

Проверка:

sudo reboot
# после перезагрузки:
docker compose ps

6.6. Firewall

# UFW (Ubuntu)
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw enable

# Порт 5432 НЕ открывайте наружу — база доступна только внутри Docker-сети

Для production рекомендуется убрать проброс порта 5432 из docker-compose.yml:

# Удалите или закомментируйте:
# ports:
#   - "5432:5432"

7. Проверка работоспособности

7.1. Веб-интерфейс

Откройте http://localhost:3000 (или ваш домен). Должна отображаться главная страница с зоной загрузки.

7.2. Загрузка тестового изображения

Перетащите JPG/PNG файл в зону загрузки (или нажмите для выбора).
Дождитесь сообщения «Фото загружено!».
Скопируйте полученную ссылку и откройте в новой вкладке — изображение должно отображаться.

7.3. API

# Список фото
curl http://localhost:3000/api/photos

# Загрузка файла
curl -X POST http://localhost:3000/api/upload \
  -F "file=@/path/to/image.jpg"

7.4. База данных

docker compose exec db psql -U photohost -d photohost -c "SELECT id, \"originalName\", \"createdAt\" FROM \"Photo\" ORDER BY \"createdAt\" DESC LIMIT 5;"

7.5. Файлы на диске

docker compose exec app ls -la /app/public/uploads/

8. Обновление

Docker-установка

cd /opt/photohost   # или ваш каталог

# Получить новую версию
git pull origin main

# Пересобрать и перезапустить
docker compose up --build -d

Локальная разработка

git pull origin main
npm install
npx prisma db push
npm run build   # для production

9. Резервное копирование

База данных

# Создать дамп
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:

# Узнать имя 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)

# 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. Устранение неполадок

Приложение не запускается

docker compose logs app

Частые причины:

База данных ещё не готова — подождите 10–15 секунд и проверьте docker compose ps
Ошибка сборки — убедитесь, что достаточно RAM (минимум 1 ГБ)

Ошибка подключения к БД

Error: P1001: Can't reach database server

Решение:

Проверьте, что контейнер photohost-db в статусе healthy:
```
docker compose ps
```
Проверьте DATABASE_URL — хост должен быть db внутри Docker, localhost при локальной разработке.
Перезапустите сервисы:
```
docker compose restart
```

Порт 3000 занят

# Linux / macOS — найти процесс
lsof -i :3000

# Windows
netstat -ano | findstr ":3000"

Измените порт в docker-compose.yml:

ports:
  - "8080:3000"   # доступ через http://localhost:8080

Загрузка файлов не работает

Проверьте права на каталог public/uploads/
Убедитесь, что файл — изображение (JPG, PNG, GIF, WebP) и меньше 10 МБ
При использовании Nginx проверьте client_max_body_size 10M;

Ошибка Prisma при первом запуске

# Вручную применить схему
docker compose exec app npx prisma db push

Полный сброс (удалить все данные)

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

17 KiB Raw Permalink Blame History Unescape Escape

PhotoHost — Подробная инструкция по установке

Содержание

1. Требования

Для установки через Docker (минимальный набор)

Для локальной разработки (дополнительно)

Сетевые порты

2. Получение исходного кода

Из Git-репозитория

Из архива релиза

3. Установка через Docker (рекомендуется)

Шаг 1. Перейдите в каталог проекта

Шаг 2. (Опционально) Измените пароль БД

Шаг 3. Сборка и запуск

Шаг 4. Проверка статуса контейнеров

Шаг 5. Просмотр логов (при необходимости)

Шаг 6. Откройте в браузере

Управление сервисами

4. Локальная разработка без Docker

Шаг 1. Установите Node.js

Шаг 2. Создайте файл .env

Шаг 3. Запустите PostgreSQL

Шаг 4. Установите зависимости

Шаг 5. Примените схему базы данных

Шаг 6. Создайте каталог для загрузок

Шаг 7. Запустите dev-сервер

Полезные команды для разработки

5. Настройка переменных окружения

Формат DATABASE_URL

6. Production-деплой на сервер

6.1. Подготовка сервера (Linux)

6.2. Клонирование и настройка

6.3. Запуск

6.4. Reverse proxy (Nginx)

6.5. Автозапуск при перезагрузке сервера

6.6. Firewall

7. Проверка работоспособности

7.1. Веб-интерфейс

7.2. Загрузка тестового изображения

7.3. API

7.4. База данных

7.5. Файлы на диске

8. Обновление

Docker-установка

Локальная разработка

9. Резервное копирование

База данных

Загруженные файлы

Автоматический бэкап (cron)

10. Устранение неполадок

Приложение не запускается

Ошибка подключения к БД

Порт 3000 занят

Загрузка файлов не работает

Ошибка Prisma при первом запуске

Полный сброс (удалить все данные)

Структура проекта

Поддержка

17 KiB

Raw Permalink Blame History

Шаг 2. Создайте файл `.env`