test2/hosting-files
Template
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases 2 Wiki Activity

docs: add detailed INSTALL.md and update README

Browse Source 
Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
orohi
2026-06-06 15:05:41 +03:00
parent c4d54d1bfc
commit 006cc40bb6
2 changed files with 614 additions and 24 deletions
Download Patch File Download Diff File Expand all files Collapse all files
INSTALL.md
+608
View File
@@ -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
README.md
+6 -24
View File
@@ -13,36 +13,18 @@
- PostgreSQL для хранения метаданных - PostgreSQL для хранения метаданных
- Docker Compose для простого деплоя - Docker Compose для простого деплоя
## Быстрый старт (Docker) ## Установка
Подробная инструкция по установке, настройке и деплою — в файле **[INSTALL.md](./INSTALL.md)**.
### Быстрый старт (Docker)
```bash ```bash
docker compose up --build docker compose up --build -d
``` ```
Приложение будет доступно на [http://localhost:3000](http://localhost:3000) Приложение будет доступно на [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 - **Frontend:** Next.js 15, React 19, Tailwind CSS 4