# Almasa CMS — Deployment handover (for the KG1 developer)

**Client:** Almasa Advertising & Publicity (UAE)
**Application:** Contract Management System — Laravel 13 (PHP 8.5) + Filament 5, MySQL 8.4, Redis
**Target:** one Ubuntu 24.04 LTS server, behind Nginx with HTTPS
**Language / time:** Arabic-first (RTL) with English, Asia/Dubai, AED

The step-by-step server configs (Nginx, PHP, Supervisor, cron) are in `docs/DEPLOYMENT.md` inside the
pack. This sheet is the short path through them, plus what to hand back to the client.

---

## 0. What you receive

| File | What it is |
|---|---|
| `almasa-cms-release-2026-10-22.zip` | The application source. **No** `.env`, `vendor/`, `node_modules/`, documents, logs or backups. |
| `DEVELOPER_HANDOVER.md` | This guide (also inside the zip under `docs/`) |

Inside the zip, read in this order:
1. `docs/DEPLOYMENT.md` — full server setup
2. `docs/CREDENTIALS_SETUP.md` — SMTP, WhatsApp, Telegram, AI keys
3. `docs/BACKUP_RESTORE.md` — backups and restore
4. `docs/OPERATIONS.md` — daily checks and troubleshooting

## 1. Server requirements

- Ubuntu 24.04 LTS, at least 2 vCPU, 4 GB RAM and 80 GB SSD
- A domain or sub-domain pointing to the server, e.g. `contracts.almasa.ae` (DNS A record)
- Open ports 22, 80 and 443 only. MySQL and Redis must listen on localhost.
- Software (commands in `DEPLOYMENT.md` §2):
  - Nginx, PHP 8.5-FPM (ppa:ondrej/php), MySQL 8.4 or 8.0, Redis, Supervisor, Composer 2, Node.js 22
  - PHP extensions: bcmath curl gd intl mbstring mysql redis xml zip readline igbinary
  - `tesseract-ocr` with the `tesseract-ocr-ara` and `tesseract-ocr-eng` packs, `poppler-utils`, `mysql-client`

## 2. Fresh install (first deployment)

Follow `DEPLOYMENT.md` §1–§8. In short:

```bash
# 2.1 user + folder
sudo adduser --disabled-password --gecos "" almasa && sudo usermod -aG www-data almasa
sudo mkdir -p /var/www/almasa && sudo chown almasa:www-data /var/www/almasa

# 2.2 database (use a long random password)
sudo mysql -e "CREATE DATABASE almasa_cms CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
  CREATE USER 'almasa'@'localhost' IDENTIFIED BY 'CHANGE-ME';
  GRANT ALL PRIVILEGES ON almasa_cms.* TO 'almasa'@'localhost'; FLUSH PRIVILEGES;"

# 2.3 code (upload the zip to /home/almasa with SFTP first)
sudo -iu almasa
cd /var/www/almasa && unzip -q ~/almasa-cms-release-2026-10-22.zip && chmod +x deploy.sh
cp .env.example .env && nano .env
```

**2.4 `.env` values to set** (full list in `DEPLOYMENT.md` §5b):

| Key | Value |
|---|---|
| `APP_ENV` | `production` |
| `APP_DEBUG` | `false` |
| `APP_URL` | `https://contracts.almasa.ae` |
| `APP_TIMEZONE` | `Asia/Dubai` |
| `APP_LOCALE` | `ar` |
| `DB_*` | Database from 2.2 |
| `REDIS_PASSWORD` | Set one in `/etc/redis/redis.conf` and copy it here |
| `QUEUE_CONNECTION`, `CACHE_STORE` | `redis` |
| `SESSION_DRIVER` | `database` |
| `SESSION_SECURE_COOKIE` | `true` |
| `SEED_ADMIN_EMAIL`, `SEED_ADMIN_PASSWORD` | First Super Admin login. Remove the password after the first login. |
| `BACKUP_ARCHIVE_PASSWORD` | Long random value. **Give it to the client to store off-server.** |
| `MAIL_*` | Client's SMTP (see `CREDENTIALS_SETUP.md`). Can be filled in later. |

```bash
# 2.5 install
composer install --no-dev --optimize-autoloader
php artisan key:generate                  # ONCE only. Give APP_KEY to the client to store off-server
npm ci && npm run build                   # Almasa brand theme (required)
php artisan migrate --seed --force        # roles, master data, default rules, Super Admin
php artisan storage:link
php artisan optimize && php artisan filament:optimize
sudo chown -R almasa:www-data storage bootstrap/cache && sudo chmod -R ug+rwX storage bootstrap/cache
```

**2.6 Remaining setup** (configs are in `DEPLOYMENT.md`):

| Step | Section |
|---|---|
| Nginx site, including the `/storage/` hardening block | §6 |
| HTTPS: `sudo certbot --nginx -d contracts.almasa.ae --redirect` | §6 |
| PHP-FPM tuning: OPcache with `validate_timestamps=0` | §4 |
| Queue workers with Supervisor (2 processes, `--timeout=900`) | §7 |
| Scheduler cron: `* * * * * cd /var/www/almasa && php artisan schedule:run` | §8 |
| Sudoers line so `deploy.sh` can reload PHP-FPM | §9 |

> Never run `php artisan db:seed` again on production, and never run the test suite there: the tests
> wipe the database.

## 3. Updating an existing installation (this release or later)

Use this if a previous pack is already deployed. Your `.env`, documents and backups stay untouched.

```bash
# upload the new zip to /home/almasa first
sudo -iu almasa
cd /var/www/almasa
unzip -oq ~/almasa-cms-release-2026-10-22.zip     # -o: overwrite code files
chmod +x deploy.sh
./deploy.sh
```

`deploy.sh` does the following:
1. Turns on maintenance mode.
2. Runs `composer install` (no dev packages).
3. Builds the theme.
4. **Backs up the database.**
5. Runs `migrate --force` and `permissions:sync`.
6. Rebuilds the caches.
7. Restarts the queue workers and reloads PHP-FPM.
8. Turns maintenance mode off.

The script stops at the first error, brings the site back out of maintenance mode, and prints the failing
step. Fix the cause and run `./deploy.sh` again; every step is safe to repeat. If a migration fails, the
pre-migration database backup is under **System → Backups** and in `storage/app/backups/`.

**Database changes in this release.** All are additive and reversible, and `deploy.sh` applies them:
- `2026_10_12_000001`: optional VAT per contract (`vat_applicable`, `vat_components`)
- `2026_10_12_000002`: default permissions for the Operations and Department Manager roles (grants only;
  nothing is revoked)
- `2026_10_13_000001`: "Sharjah contracts" category and the `contract_permits` table
- `2026_10_22_000001`: record types and folders — `contracts.record_type` + `details`, `contract_extractions.target_folder`, new categories (licences, vehicles, media, ministry, commercial, generators, pension, decisions)

**Server settings changed in this release** (see `DEPLOYMENT.md` §4 and §6):
- PHP `upload_max_filesize = 105M` and `post_max_size = 110M` (documents up to 100 MB)
- Nginx `client_max_body_size 110M`

After deploying, reload PHP-FPM and Nginx.

**Optional — importing the client's scanned archive:** copy the archive folder ("SYSTEM Orignal Source Files") to the server, then run:

```bash
php artisan records:import-folders "/path/to/SYSTEM Orignal Source Files"
```

Each file is queued into its matching folder. Files already in the system are skipped. The client then reviews and approves each record in **Contracts → Contract import & analysis**.

## 4. Verify the deployment

1. Open `https://<domain>/admin` and sign in with the seed admin. Change the password, then remove
   `SEED_ADMIN_PASSWORD` from `.env`.
2. Open **System → System health**. Within about 5 minutes these must be green:
   - Database, Cache, Queue workers, Scheduler, Document storage
   - Debug mode (off) and HTTPS

   Email, WhatsApp, Telegram and AI stay yellow until the client adds credentials.
3. Open **System → Backups** and press **Back up now**. A new archive should appear within a minute or two.
4. Open **Contracts → عقود الشارقة**. The section loads, and **New** opens with Sharjah pre-filled.
5. Upload a sample PDF under **Contracts → Contract import & analysis**. Its status should change from
   *Queued* to *Awaiting review*, which proves the queue and OCR are working.
6. Check the security headers:

   ```bash
   curl -sI https://<domain>/admin/login | grep -iE "strict-transport|content-security|x-frame"
   ```

## 5. Hand back to the client

- [ ] URL working over HTTPS; HTTP redirects to HTTPS
- [ ] Super Admin login handed over, and the client changed the password
- [ ] `APP_KEY` and `BACKUP_ARCHIVE_PASSWORD` given to the client privately; they store them off the server
- [ ] Server root / SSH access details handed over, with key-based login only
- [ ] First backup created; off-site copy (S3) configured, or the client informed it is pending (`DEPLOYMENT.md` §10)
- [ ] System health screenshot showing all core checks green

## 6. Support notes

| Topic | Details |
|---|---|
| Logs | `storage/logs/` (one file per day). `laravel-*.log` for errors, `queue-*.log` for failed jobs, `security-*.log` for sign-in failures. |
| Failed jobs | `php artisan queue:failed`, then `php artisan queue:retry all` once the cause is fixed |
| Workers stuck after a code change | `php artisan queue:restart` (`deploy.sh` does this) |
| Restore | `docs/BACKUP_RESTORE.md`. The archives are AES-256 encrypted, so use `7z x` (not `unzip`) with `BACKUP_ARCHIVE_PASSWORD`. |
| Roles and permissions | `docs/ROLES_AND_PERMISSIONS.md`. Permanent deletion, backups and AI keys are Super Admin only by design. |
