# Installation (local / evaluation)

For a production server, use [DEPLOYMENT.md](DEPLOYMENT.md). This page sets the system up on a PC
(Windows, macOS or Linux) with Docker.

## Requirements

- Docker Desktop. On Windows it needs WSL2 enabled.
- About 6 GB free disk space and 4 GB RAM for Docker.
- Free ports: 8088 (app), 3307 (MySQL), 6380 (Redis), 8025 (Mailpit).

## Steps

```bash
git clone <repository-url> almasa-cms && cd almasa-cms
cp .env.example .env
```

In `.env`, set `DB_PASSWORD`, `SEED_ADMIN_EMAIL`, `SEED_ADMIN_PASSWORD`, `BACKUP_ARCHIVE_PASSWORD` and
`APP_PORT=8088`. Then:

```bash
docker compose up -d --build
docker compose exec -u sail laravel.test composer install
docker compose exec -u sail laravel.test php artisan key:generate
docker compose exec -u sail laravel.test php artisan migrate --seed
docker compose exec -u sail laravel.test php artisan storage:link
docker compose exec -u sail laravel.test npm install
docker compose exec -u sail laravel.test npm run build
docker compose exec -u sail laravel.test php artisan route:cache
docker compose exec -u sail laravel.test php artisan filament:optimize
```

Open <http://localhost:8088> and sign in with the seed admin account. Outgoing e-mail is caught by Mailpit
at <http://localhost:8025>.

Outside production, the seeder also adds sample contracts. In production, sample data is only added if
you set `SEED_SAMPLE_DATA=true`.

## Services started

| Container | Purpose |
|---|---|
| `laravel.test` | Web app (8 parallel PHP workers, OPcache) |
| `queue` | Background jobs: OCR/AI extraction, notifications, reports, backups |
| `scheduler` | Daily expiry check, reminders, backups, heartbeats |
| `mysql` | MySQL 8.4 (data in the `sail-mysql` volume) |
| `redis` | Cache and queue |
| `mailpit` | Catches outgoing e-mail during development |

## Tests

```bash
docker compose exec -u sail laravel.test php artisan test --parallel --processes=4
docker compose exec -u sail laravel.test php -d pcov.enabled=1 vendor/bin/pest --parallel --coverage
```

The tests run against a separate MySQL database named `testing`. Never run them with the config cached
(`php artisan config:cache`): Laravel would then use the cached main database settings, and the tests
would wipe that database.

## Next steps

1. Connect e-mail, WhatsApp, Telegram and AI: [CREDENTIALS_SETUP.md](CREDENTIALS_SETUP.md)
2. Enter company details: **System → Settings Center**
3. Create users and assign roles: [ROLES_AND_PERMISSIONS.md](ROLES_AND_PERMISSIONS.md)
4. Read the user guide: [USER_GUIDE.ar.md](USER_GUIDE.ar.md) / [USER_GUIDE.en.md](USER_GUIDE.en.md)
