# 🚀 Dotlaa ERP — Production Deployment Guide

This guide provides step-by-step instructions to deploy the Dotlaa ERP Laravel backend to an Ubuntu server in a secure, production-ready environment.

---

## 1. Server Prerequisites & Stack
- **OS:** Ubuntu 22.04 LTS or newer
- **Web Server:** Nginx
- **Database:** MySQL 8.0+
- **PHP Version:** PHP 8.3 (configured with php-fpm, php-mysql, php-xml, php-mbstring, php-curl, php-zip, php-sqlite3, php-redis)
- **SSL:** Let's Encrypt Certbot
- **Process Manager:** Systemd (for Queue workers)

---

## 2. Nginx Site Configuration

Create the site configuration file:
`/etc/nginx/sites-available/dotlaa_pos`

```nginx
server {
    listen 80;
    listen [::]:80;
    server_name api.dotlaaerp.com *.dotlaaerp.com;
    root /var/www/dotlaa_pos_backend/public;

    add_header X-Frame-Options "SAMEORIGIN";
    add_header X-Content-Type-Options "nosniff";

    index index.php;

    charset utf-8;

    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }

    location = /favicon.ico { access_log off; log_not_found off; }
    location = /robots.txt  { access_log off; log_not_found off; }

    error_page 404 /index.php;

    location ~ \.php$ {
        fastcgi_pass unix:/var/run/php/php8.3-fpm.sock;
        fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
        include fastcgi_params;
    }

    location ~ /\.(?!well-known).* {
        deny all;
    }
}
```

Enable the site configuration and restart Nginx:
```bash
sudo ln -s /etc/nginx/sites-available/dotlaa_pos /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl restart nginx
```

---

## 3. Directory Permissions

Set tight ownership and permission levels for standard web server execution:
```bash
sudo chown -R www-data:www-data /var/www/dotlaa_pos_backend
sudo find /var/www/dotlaa_pos_backend -type f -exec chmod 644 {} \;
sudo find /var/www/dotlaa_pos_backend -type d -exec chmod 755 {} \;
sudo chmod -R 775 /var/www/dotlaa_pos_backend/storage
sudo chmod -R 775 /var/www/dotlaa_pos_backend/bootstrap/cache
```

---

## 4. Database Setup & Migrations

1. Create a MySQL database and user:
   ```sql
   CREATE DATABASE dotlaa_pos_production CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
   CREATE USER 'dotlaa_user'@'localhost' IDENTIFIED BY 'production-db-secure-password';
   GRANT ALL PRIVILEGES ON dotlaa_pos_production.* TO 'dotlaa_user'@'localhost';
   FLUSH PRIVILEGES;
   ```
2. Populate the `.env` settings to target this database:
   ```env
   DB_CONNECTION=mysql
   DB_HOST=127.0.0.1
   DB_PORT=3306
   DB_DATABASE=dotlaa_pos_production
   DB_USERNAME=dotlaa_user
   DB_PASSWORD=production-db-secure-password
   ```
3. Run migrations and seed the pilot data:
   ```bash
   php artisan migrate --force
   php artisan db:seed --force
   ```

---

## 5. Queue Worker Setup (Systemd)

We manage background queue tasks (such as inventory updates or barcode job notifications) via Systemd queue worker daemons.

Create the service file:
`/etc/systemd/system/laravel-worker.service`

```ini
[Unit]
Description=Laravel Queue Worker
After=network.target

[Service]
User=www-data
Group=www-data
Restart=always
ExecStart=/usr/bin/php /var/www/dotlaa_pos_backend/artisan queue:work --queue=default --sleep=3 --tries=3 --timeout=90
StandardOutput=syslog
StandardError=syslog

[Install]
WantedBy=multi-user.target
```

Enable and start the service:
```bash
sudo systemctl daemon-reload
sudo systemctl enable laravel-worker.service
sudo systemctl start laravel-worker.service
```

---

## 6. Laravel Scheduler Setup (Cron Job)

The scheduler executes backups, log rotations, and cleanups automatically.

Open server crontab:
```bash
sudo crontab -u www-data -e
```

Append this single cron line:
```cron
* * * * * cd /var/www/dotlaa_pos_backend && php artisan schedule:run >> /dev/null 2>&1
```

---

## 7. SSL Certificate Installation

Install Certbot for automated Let's Encrypt SSL configuration:
```bash
sudo apt update
sudo apt install certbot python3-certbot-nginx -y
sudo certbot --nginx -d api.dotlaaerp.com -d boutique-a.dotlaaerp.com
```

---

## 8. Backups Integration

Verify backups are running and saving database states. Ensure your backup configuration maps to a remote storage disk (e.g. S3 bucket) rather than purely local storage:
- Manual Test: `php artisan backup:run --only-db`
- Check Backup Files: `php artisan backup:list`
- See [BACKUP_RESTORE_GUIDE.md](file:///d:/dotlaa_pos/dotlaa_pos_backend/BACKUP_RESTORE_GUIDE.md) for details.