TenerifeProp/docs/AI_DEPLOY_CONTEXT.md

# 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