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)

just setup-server

This creates /var/www/posterg/ with correct permissions:

• Owner: www-data:posterg
• Permissions: 775

2. Deploy Application

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/
• storage/ → /var/www/posterg/storage/
• src/ → /var/www/posterg/lib/

3. Update Nginx Configuration

just deploy-nginx

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

IMPORTANT: The nginx config must have:

root /var/www/posterg/public;

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

4. Apply Nginx Configuration on Server

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

5. Verify Deployment

just server-status

Check:

• https://posterg.erg.be/ (should work)
• https://posterg.erg.be/admin/ (should work)
• https://posterg.erg.be/storage/test.db (should 404 ✅)

---

Subsequent Deployments

After the first deployment, you only need:

just deploy

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

---

Deploy Database

If you need to deploy the database:

just deploy-database

This will:

1. Upload storage/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:

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:

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

Database Connection Errors

Cause: Database file permissions incorrect

Solution:

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

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

2. Restore Old Nginx Config

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

3. Rollback Code with jj

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/storage/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.