docs: add deployment guides, audit reports, and production sync scripts
- BRAINYCP_DEPLOY_GUIDE.md: complete human deployment guide - AI_DEPLOY_CONTEXT.md: machine-readable deploy instructions for AI agents - sync-production.sh: universal deployment script (full/quick/status/logs/backup) - DEPLOY_PLAN.md: step-by-step deployment plan - DEPLOY_AUDIT_REPORT.md: server audit results - MIGRATION_AUDIT_REPORT.md: MySQL migration complexity analysis - SERVER_AUDIT_REPORT.md: server environment audit - Update README.md with BrainyCP deploy workflow and Git sync instructions Refs: production server 46.175.149.131, domain tenerifeprop.es
This commit is contained in:
APAW Agent Sync
182
docs/AI_DEPLOY_CONTEXT.md
Normal file
182
docs/AI_DEPLOY_CONTEXT.md
Normal file
@@ -0,0 +1,182 @@
|
||||
# AI Deploy Context — TenerifeProp on BrainyCP
|
||||
|
||||
## Machine-Readable Checklist
|
||||
|
||||
```yaml
|
||||
project: TenerifeProp
|
||||
runtime: Bun v1.3.14
|
||||
framework: Hono v4.12.10
|
||||
database: SQLite (WAL mode)
|
||||
ssl: Let's Encrypt (BrainyCP managed)
|
||||
proxy: Nginx (BrainyCP managed)
|
||||
port: 3003
|
||||
server_ip: 46.175.149.131
|
||||
server_os: Ubuntu 22.04 LTS
|
||||
panel: BrainyCP (user: nero, no SSH)
|
||||
```
|
||||
|
||||
## Critical Rules for AI Agents
|
||||
|
||||
### 1. NEVER modify BrainyCP-managed files directly
|
||||
- ❌ Do NOT edit `/etc/nginx/sites-available/*.conf` directly
|
||||
- ❌ Do NOT edit `/etc/nginx/nginx.conf` directly
|
||||
- ❌ Do NOT modify `/lib/systemd/system/nodejs@*.service`
|
||||
- ✅ Use BrainyCP web interface for Nginx changes
|
||||
- ✅ Use custom systemd unit `tenerifeprop.service` for process management
|
||||
|
||||
### 2. Permissions Hierarchy (BrainyCP standard)
|
||||
```
|
||||
/home/nero/ : root:root, 755 — managed by BrainyCP
|
||||
/home/nero/sites/ : root:root, 755 — managed by BrainyCP
|
||||
/home/nero/sites/tenerifeprop.es/ : nero:nero, 755 — site content
|
||||
All files inside : nero:nero, 644
|
||||
All directories : nero:nero, 755
|
||||
.env : nero:nero, 600 (restricted)
|
||||
data/ : nero:nero, 755
|
||||
tenerifeprop.db : nero:nero, 644
|
||||
```
|
||||
|
||||
NEVER change `/home/nero` or `/home/nero/sites/` ownership from `root:root`.
|
||||
ONLY change contents inside `/home/nero/sites/tenerifeprop.es/` to `nero:nero`.
|
||||
|
||||
### 3. Bun Location (not in PATH)
|
||||
```
|
||||
Binary: /home/nero/.bun/bin/bun
|
||||
Version: 1.3.14
|
||||
Owner: root:root (installation)
|
||||
User execution: via su - nero -s /bin/bash -c '...'
|
||||
```
|
||||
|
||||
Always use full path to bun on server.
|
||||
|
||||
### 4. Deployment Flow (Git-based)
|
||||
```
|
||||
[Local] dev branch → commit → push → PR → main
|
||||
[Server] production branch ← git pull origin production → restart
|
||||
```
|
||||
|
||||
The server tracks `production` branch, not `main` or `dev`.
|
||||
|
||||
### 5. Restart Sequence
|
||||
```bash
|
||||
# Correct way to restart
|
||||
systemctl restart tenerifeprop
|
||||
|
||||
# After updating files
|
||||
systemctl restart tenerifeprop
|
||||
|
||||
# After updating .env
|
||||
systemctl restart tenerifeprop
|
||||
```
|
||||
|
||||
### 6. Healthcheck Endpoint
|
||||
```bash
|
||||
curl -s http://localhost:3003/api/settings
|
||||
# Expected: {"success":true,"data":{...}}
|
||||
```
|
||||
|
||||
### 7. Log Inspection
|
||||
```bash
|
||||
journalctl -u tenerifeprop -f
|
||||
```
|
||||
|
||||
### 8. Backup Before Deploy
|
||||
```bash
|
||||
/home/nero/sites/tenerifeprop.es/scripts/backup.sh
|
||||
# Creates: /backup/db/tenerifeprop-YYYYMMDD-HHMMSS.db
|
||||
# Keeps: 7 days of backups
|
||||
# Cron: Daily at 03:00
|
||||
```
|
||||
|
||||
### 9. Deploy Script
|
||||
```bash
|
||||
/home/nero/sites/tenerifeprop.es/scripts/deploy.sh
|
||||
```
|
||||
What it does:
|
||||
1. Backup database.
|
||||
2. Fetch and reset to origin/production.
|
||||
3. Run `bun install --production`.
|
||||
4. Fix permissions (chown nero:nero, chmod 644/755).
|
||||
5. Restart `tenerifeprop.service`.
|
||||
6. Healthcheck (expect HTTP 200 on /api/settings).
|
||||
|
||||
### 10. Environment Variables (production)
|
||||
```
|
||||
NODE_ENV=production
|
||||
PORT=3003
|
||||
RESEND_API_KEY=
|
||||
TELEGRAM_BOT_TOKEN=
|
||||
TELEGRAM_CHAT_ID=
|
||||
GITEA_API_URL=https://git.softuniq.eu/api/v1
|
||||
GITEA_TOKEN=
|
||||
GITEA_USER=
|
||||
GITEA_PASS=
|
||||
```
|
||||
|
||||
File location: `/home/nero/sites/tenerifeprop.es/.env`
|
||||
Permissions: `600` (read-only owner)
|
||||
|
||||
## Synchronization Workflow
|
||||
|
||||
### From local to production (via Git)
|
||||
|
||||
1. Developer commits to `dev`:
|
||||
```bash
|
||||
git add .
|
||||
git commit -m "feat: new feature"
|
||||
git push origin dev
|
||||
```
|
||||
|
||||
2. Merge to `main` (via PR or manually):
|
||||
```bash
|
||||
git checkout main
|
||||
git merge dev
|
||||
git push origin main
|
||||
```
|
||||
|
||||
3. Push `main` to `production` branch:
|
||||
```bash
|
||||
git push origin main:production
|
||||
# or
|
||||
git checkout production
|
||||
git merge main
|
||||
git push origin production
|
||||
```
|
||||
|
||||
4. Deploy on server:
|
||||
```bash
|
||||
ssh root@46.175.149.131
|
||||
cd /home/nero/sites/tenerifeprop.es
|
||||
./scripts/deploy.sh
|
||||
```
|
||||
|
||||
### Auto-deploy (optional)
|
||||
Add webhook in Gitea to call POST endpoint.
|
||||
Server endpoint runs `./scripts/deploy.sh`.
|
||||
|
||||
## File Structure on Server
|
||||
```
|
||||
/home/nero/sites/tenerifeprop.es/
|
||||
├── .env # Env vars (secrets)
|
||||
├── .git/ # Git repository (production branch)
|
||||
├── data/
|
||||
│ └── tenerifeprop.db # SQLite database
|
||||
├── node_modules/ # Dependencies
|
||||
├── public/ # Static files
|
||||
├── scripts/
|
||||
│ ├── deploy.sh # Deployment script
|
||||
│ └── backup.sh # Backup script
|
||||
├── src/ # Source code
|
||||
├── package.json
|
||||
├── bun.lock
|
||||
└── docs/ # Documentation
|
||||
```
|
||||
|
||||
## Forbidden Actions
|
||||
- ❌ Do NOT run `git push --force` on production branch
|
||||
- ❌ Do NOT edit `.env` without backup
|
||||
- ❌ Do NOT delete `data/tenerifeprop.db` without backup
|
||||
- ❌ Do NOT change Bun version without testing locally
|
||||
- ❌ Do NOT modify BrainyCP Nginx configs directly
|
||||
- ❌ Do NOT use port other than 3003 without updating Nginx
|
||||
- ❌ Do NOT change `/home/nero` or `/home/nero/sites/` ownership
|
||||
309
docs/BRAINYCP_DEPLOY_GUIDE.md
Normal file
309
docs/BRAINYCP_DEPLOY_GUIDE.md
Normal file
@@ -0,0 +1,309 @@
|
||||
# Руководство по деплою TenerifeProp на BrainyCP
|
||||
|
||||
## Для кого это руководство
|
||||
Для разработчиков и DevOps-инженеров, которые будут разворачивать или обновлять проект TenerifeProp на хостинге с панелью BrainyCP.
|
||||
|
||||
## 1. Предварительные требования
|
||||
|
||||
### На сервере (что уже должно быть)
|
||||
- **BrainyCP** установлена и работает.
|
||||
- **Домен** добавлен в панель (`tenerifeprop.es`).
|
||||
- **NodeJS** установлен через панель BrainyCP (создаст заглушку на порту, например `3003`).
|
||||
- **SSL** активирован (Let's Encrypt через панель).
|
||||
- **SSH-доступ** к серверу с правами root.
|
||||
- **Git** установлен (`git --version`).
|
||||
|
||||
### На локальной машине
|
||||
- Доступ к репозиторию `git.softuniq.eu/UniqueSoft/TenerifeProp`.
|
||||
- SSH-ключ или логин/пароль для доступа к серверу.
|
||||
|
||||
### Ветки проекта
|
||||
```
|
||||
origin/dev — основная ветка разработки
|
||||
origin/main — ветка релиза
|
||||
origin/production — ветка продакшена на BrainyCP (создаётся при первом деплое)
|
||||
```
|
||||
|
||||
## 2. Структура проекта на сервере
|
||||
|
||||
```
|
||||
/home/nero/sites/tenerifeprop.es/
|
||||
├── .env # Переменные окружения
|
||||
├── src/ # Серверный код
|
||||
├── public/ # Статические файлы
|
||||
├── data/
|
||||
│ └── tenerifeprop.db # SQLite база данных
|
||||
├── node_modules/ # Зависимости
|
||||
├── package.json
|
||||
├── bun.lock
|
||||
└── .git/ # Git репозиторий (если клонирован)
|
||||
```
|
||||
|
||||
## 3. Первый деплой (ручной)
|
||||
|
||||
### Шаг 1: Остановить заглушку BrainyCP
|
||||
```bash
|
||||
ssh root@46.175.149.131
|
||||
systemctl stop nodejs@3003.service
|
||||
systemctl disable nodejs@3003.service
|
||||
```
|
||||
|
||||
### Шаг 2: Установить Bun
|
||||
```bash
|
||||
# Установка Bun в папку пользователя (не трогает системный Node.js)
|
||||
curl -fsSL https://bun.sh/install | BUN_INSTALL=/home/nero/.bun bash
|
||||
chown -R nero:nero /home/nero/.bun
|
||||
```
|
||||
|
||||
Путь к Bun: `/home/nero/.bun/bin/bun`
|
||||
|
||||
### Шаг 3: Клонировать репозиторий
|
||||
```bash
|
||||
cd /home/nero/sites/tenerifeprop.es
|
||||
# Очистить заглушку (сохранить .well-known для SSL)
|
||||
rm -f index.js app.js app.css
|
||||
git clone https://git.softuniq.eu/UniqueSoft/TenerifeProp.git .
|
||||
```
|
||||
|
||||
### Шаг 4: Переключиться на ветку production
|
||||
```bash
|
||||
git checkout -b production origin/production
|
||||
# или если ветки нет:
|
||||
git checkout -b production
|
||||
```
|
||||
|
||||
### Шаг 5: Создать `.env`
|
||||
```bash
|
||||
cat > .env <<'EOF'
|
||||
NODE_ENV=production
|
||||
PORT=3003
|
||||
RESEND_API_KEY=your_key_here
|
||||
TELEGRAM_BOT_TOKEN=your_token_here
|
||||
TELEGRAM_CHAT_ID=your_chat_id_here
|
||||
GITEA_API_URL=https://git.softuniq.eu/api/v1
|
||||
GITEA_TOKEN=your_gitea_token
|
||||
EOF
|
||||
chmod 600 .env
|
||||
chown nero:nero .env
|
||||
```
|
||||
|
||||
### Шаг 6: Установить зависимости
|
||||
```bash
|
||||
/home/nero/.bun/bin/bun install --production
|
||||
```
|
||||
|
||||
### Шаг 7: Настроить systemd
|
||||
Создать файл `/etc/systemd/system/tenerifeprop.service`:
|
||||
|
||||
```ini
|
||||
[Unit]
|
||||
Description=TenerifeProp Bun Server
|
||||
After=network.target
|
||||
|
||||
[Service]
|
||||
Type=simple
|
||||
User=nero
|
||||
WorkingDirectory=/home/nero/sites/tenerifeprop.es
|
||||
Environment=NODE_ENV=production
|
||||
Environment=PORT=3003
|
||||
EnvironmentFile=/home/nero/sites/tenerifeprop.es/.env
|
||||
ExecStart=/home/nero/.bun/bin/bun run src/server/index.ts
|
||||
Restart=always
|
||||
RestartSec=5
|
||||
StandardOutput=journal
|
||||
StandardError=journal
|
||||
|
||||
[Install]
|
||||
WantedBy=multi-user.target
|
||||
```
|
||||
|
||||
Активировать:
|
||||
```bash
|
||||
systemctl daemon-reload
|
||||
systemctl enable tenerifeprop.service
|
||||
systemctl start tenerifeprop.service
|
||||
```
|
||||
|
||||
### Шаг 8: Проверить работу
|
||||
```bash
|
||||
# Локальный тест
|
||||
curl http://localhost:3003/api/settings
|
||||
# Ожидается: {"success":true,"data":{...}}
|
||||
|
||||
# Публичный тест
|
||||
curl https://tenerifeprop.es/api/settings
|
||||
|
||||
# Логи
|
||||
journalctl -u tenerifeprop -f
|
||||
```
|
||||
|
||||
## 4. Обновление проекта (Git-based deploy)
|
||||
|
||||
### Метод A: Скрипт автообновления (рекомендуется)
|
||||
|
||||
На сервере есть скрипт `/home/nero/sites/tenerifeprop.es/scripts/deploy.sh`.
|
||||
|
||||
```bash
|
||||
# Обновить из ветки production
|
||||
cd /home/nero/sites/tenerifeprop.es
|
||||
./scripts/deploy.sh
|
||||
```
|
||||
|
||||
Что делает скрипт:
|
||||
1. `git fetch origin`
|
||||
2. `git reset --hard origin/production`
|
||||
3. `bun install --production`
|
||||
4. `chown -R nero:nero .`
|
||||
5. `chmod 600 .env`
|
||||
6. `systemctl restart tenerifeprop`
|
||||
7. Проверка healthcheck
|
||||
|
||||
### Метод B: Ручное обновление
|
||||
|
||||
```bash
|
||||
ssh root@46.175.149.131
|
||||
cd /home/nero/sites/tenerifeprop.es
|
||||
|
||||
# Переключиться на production
|
||||
git checkout production
|
||||
git pull origin production
|
||||
|
||||
# Установить зависимости (если изменились)
|
||||
/home/nero/.bun/bin/bun install --production
|
||||
|
||||
# Права
|
||||
chown -R nero:nero .
|
||||
chmod 600 .env
|
||||
|
||||
# Перезапустить
|
||||
systemctl restart tenerifeprop
|
||||
|
||||
# Проверить
|
||||
systemctl status tenerifeprop
|
||||
curl http://localhost:3003/api/settings
|
||||
```
|
||||
|
||||
## 5. Git workflow для синхронизации
|
||||
|
||||
### Схема веток
|
||||
```
|
||||
[dev] → commit, push → PR → [main] → tag → PR → [production] → auto-deploy
|
||||
```
|
||||
|
||||
### Как внести изменения
|
||||
|
||||
1. **Разработка** (на локальной машине или в Docker):
|
||||
```bash
|
||||
git checkout dev
|
||||
# вносишь изменения
|
||||
git add .
|
||||
git commit -m "feat: новая фича"
|
||||
git push origin dev
|
||||
```
|
||||
|
||||
2. **Релиз** (merge в main):
|
||||
```bash
|
||||
git checkout main
|
||||
git merge dev
|
||||
git tag -a v1.1.0 -m "Release v1.1.0"
|
||||
git push origin main --tags
|
||||
```
|
||||
|
||||
3. **Деплой** (merge в production):
|
||||
```bash
|
||||
git checkout production
|
||||
git merge main
|
||||
git push origin production
|
||||
```
|
||||
|
||||
4. **Авто-деплой** (на сервере):
|
||||
- Вебхук Gitea → сервер получает уведомление.
|
||||
- Или `git pull` по cron каждые 5 минут.
|
||||
- Или запускаешь `./scripts/deploy.sh` вручную.
|
||||
|
||||
### Webhook (Gitea → сервер)
|
||||
|
||||
В Gitea (Settings → Webhooks → Add Webhook):
|
||||
- URL: `https://tenerifeprop.es/api/admin/deploy`
|
||||
- Секретный ключ: настрой в `.env` (`DEPLOY_SECRET`)
|
||||
- События: `push`
|
||||
|
||||
На сервере нужен endpoint `/api/admin/deploy`, который:
|
||||
1. Проверяет секретный ключ.
|
||||
2. Запускает `git pull origin production`.
|
||||
3. Перезапускает сервер.
|
||||
|
||||
Это усложнение — рекомендуется начать со скрипта.
|
||||
|
||||
## 6. Резервное копирование базы данных
|
||||
|
||||
### Дамп БД (на сервере)
|
||||
```bash
|
||||
cd /home/nero/sites/tenerifeprop.es
|
||||
# SQLite — просто копируем файл
|
||||
cp data/tenerifeprop.db /backup/tenerifeprop-$(date +%Y%m%d).db
|
||||
```
|
||||
|
||||
### Восстановление
|
||||
```bash
|
||||
systemctl stop tenerifeprop
|
||||
cp /backup/tenerifeprop-20260513.db data/tenerifeprop.db
|
||||
chown nero:nero data/tenerifeprop.db
|
||||
chmod 644 data/tenerifeprop.db
|
||||
systemctl start tenerifeprop
|
||||
```
|
||||
|
||||
## 7. Troubleshooting
|
||||
|
||||
| Проблема | Решение |
|
||||
|----------|---------|
|
||||
| Bun не найден | Проверь `ls /home/nero/.bun/bin/bun`. Если нет — переустановить. |
|
||||
| Порт 3003 занят | `lsof -i :3003` → найти и убить процесс. Или изменить порт в `.env` и Nginx. |
|
||||
| Nginx не проксирует | Проверить конфиг BrainyCP. Сравнить с рабочим сайтом. |
|
||||
| Permission denied | `chown -R nero:nero /home/nero/sites/tenerifeprop.es` |
|
||||
| SQLite database is locked | Остановить сервер, удалить `*.db-shm` и `*.db-wal`, запустить. |
|
||||
| 502 Bad Gateway | Backend не запущен. `systemctl start tenerifeprop`. |
|
||||
| Статика 404 | Проверить пути в `public/`. CSS/JS должны быть доступны через Bun. |
|
||||
|
||||
## 8. Команды для мониторинга
|
||||
|
||||
```bash
|
||||
# Статус сервера
|
||||
systemctl status tenerifeprop
|
||||
|
||||
# Логи реального времени
|
||||
journalctl -u tenerifeprop -f
|
||||
|
||||
# Проверка порта
|
||||
ss -tlnp | grep 3003
|
||||
lsof -i :3003
|
||||
|
||||
# Проверка процесса Bun
|
||||
ps aux | grep bun
|
||||
|
||||
# Проверка API
|
||||
curl -s http://localhost:3003/api/settings | python -m json.tool
|
||||
|
||||
# Проверка SSL
|
||||
openssl s_client -connect tenerifeprop.es:443 -servername tenerifeprop.es
|
||||
|
||||
# Ресурсы сервера
|
||||
htop
|
||||
df -h
|
||||
free -h
|
||||
```
|
||||
|
||||
## 9. Контакты и доступы
|
||||
|
||||
| Параметр | Значение |
|
||||
|----------|----------|
|
||||
| Сервер | `46.175.149.131` |
|
||||
| SSH логин | `root` |
|
||||
| Панель | BrainyCP (пользователь `nero`) |
|
||||
| Домен | `tenerifeprop.es` |
|
||||
| Backend порт | `3003` |
|
||||
| Bun путь | `/home/nero/.bun/bin/bun` |
|
||||
| Папка сайта | `/home/nero/sites/tenerifeprop.es` |
|
||||
| Логи | `journalctl -u tenerifeprop` |
|
||||
| База данных | `data/tenerifeprop.db` (SQLite) |
|
||||
| GitHub/Gitea | `https://git.softuniq.eu/UniqueSoft/TenerifeProp` |
|
||||
Reference in New Issue
Block a user