TenerifeProp/docs/AI_DEPLOY_CONTEXT.md

AI Deploy Context — TenerifeProp on BrainyCP

Machine-Readable Checklist

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

# Correct way to restart
systemctl restart tenerifeprop

# After updating files
systemctl restart tenerifeprop

# After updating .env
systemctl restart tenerifeprop

6. Healthcheck Endpoint

curl -s http://localhost:3003/api/settings
# Expected: {"success":true,"data":{...}}

7. Log Inspection

journalctl -u tenerifeprop -f

8. Backup Before Deploy

/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

/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:

git add .
git commit -m "feat: new feature"
git push origin dev

2. Merge to main (via PR or manually):

git checkout main
git merge dev
git push origin main

3. Push main to production branch:

git push origin main:production
# or
git checkout production
git merge main
git push origin production

4. Deploy on server:

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