xamxam/docs/DEPLOYMENT_STEPS.md

# Deployment Steps

## First-Time Deployment (New Structure)

Since we're moving from `/var/www/html/` to `/var/www/posterg/`, follow these steps:

### 1. Setup Server Directory (ONE TIME)

```bash
just setup-server
```

This creates `/var/www/posterg/` with correct permissions:
- Owner: `www-data:posterg`
- Permissions: `775`

### 2. Deploy Application

```bash
just deploy
```

This deploys all files to `/var/www/posterg/`:
- `public/` → `/var/www/posterg/public/`
- `includes/` → `/var/www/posterg/includes/`
- `config/` → `/var/www/posterg/config/`
- `database/` → `/var/www/posterg/database/`
- `lib/` → `/var/www/posterg/lib/`

### 3. Update Nginx Configuration

```bash
just deploy-nginx
```

This checks that nginx config has correct DocumentRoot and uploads it to server.

**IMPORTANT:** The nginx config must have:
```nginx
root /var/www/posterg/public;
```

If the check fails, edit `nginx/posterg.conf` first.

### 4. Apply Nginx Configuration on Server

```bash
ssh posterg
sudo bash /tmp/deploy-production.sh
sudo systemctl reload nginx
```

### 5. Verify Deployment

```bash
just server-status
```

Check:
- https://posterg.erg.be/ (should work)
- https://posterg.erg.be/admin/ (should work)
- https://posterg.erg.be/database/test.db (should 404 ✅)

---

## Subsequent Deployments

After the first deployment, you only need:

```bash
just deploy
```

That's it! The directory structure is already in place.

---

## Deploy Database

If you need to deploy the database:

```bash
just deploy-database
```

This will:
1. Upload `database/test.db` to server
2. Set correct permissions
3. Warn before overwriting

---

## Troubleshooting

### Permission Denied on Deploy

**Error:**
```
mkdir "/var/www/posterg" failed: Permission denied (13)
```

**Solution:**
```bash
just setup-server
```

### Nginx 500 Error

**Cause:** Nginx DocumentRoot still pointing to old location

**Solution:**
1. Check nginx config has: `root /var/www/posterg/public;`
2. Redeploy nginx config:
   ```bash
   just deploy-nginx
   ssh posterg
   sudo bash /tmp/deploy-production.sh
   sudo systemctl reload nginx
   ```

### Database Connection Errors

**Cause:** Database file permissions incorrect

**Solution:**
```bash
ssh posterg
cd /var/www/posterg
sudo chown www-data:posterg database/test.db
sudo chmod 660 database/test.db
```

### Admin 404

**Cause:** Nginx still using old `/formulaire/` location

**Solution:** Update `nginx/posterg.conf` to use `/admin/` location

---

## Rollback

If something goes wrong, rollback is easy:

### 1. Restore Old Directory

```bash
ssh posterg
sudo cp -r /var/www/html.backup /var/www/html  # If you backed up
```

### 2. Restore Old Nginx Config

```bash
ssh posterg
sudo cp /etc/nginx/sites-available/posterg.backup /etc/nginx/sites-available/posterg
sudo systemctl reload nginx
```

### 3. Rollback Code with jj

```bash
jj log
jj edit <previous-change-id>
```

---

## Migration Checklist

- [ ] `just setup-server` - Create server directory
- [ ] `just deploy` - Deploy application
- [ ] `just deploy-nginx` - Update nginx config
- [ ] SSH to server and apply nginx config
- [ ] `sudo systemctl reload nginx`
- [ ] Verify site works: https://posterg.erg.be/
- [ ] Verify security: https://posterg.erg.be/database/test.db → 404
- [ ] Test admin: https://posterg.erg.be/admin/
- [ ] Deploy database (if needed): `just deploy-database`

---

## Commands Reference

| Command | Purpose |
|---------|---------|
| `just setup-server` | Create `/var/www/posterg/` (first time only) |
| `just deploy` | Deploy application files |
| `just deploy-nginx` | Update nginx configuration |
| `just deploy-database` | Deploy database file |
| `just server-status` | Check server health |
| `just server-logs` | View server logs |

---

## Directory Structure on Server

```
/var/www/posterg/               # Application root (private)
├── public/                     # DocumentRoot (nginx points here)
│   ├── index.php
│   ├── search.php
│   ├── memoire.php
│   ├── admin/
│   └── assets/
├── includes/                   # Templates (private)
├── config/                     # Configuration (private)
├── database/                   # Database (private)
├── lib/                        # PHP classes (private)
└── vendor/                     # Dependencies (private)
```

**Nginx DocumentRoot:** `/var/www/posterg/public/`

Only the `public/` directory is accessible via web browser. Everything else is private.