# Server Requirements

## Runtime

- Linux server with Nginx or Apache, PHP-FPM, shell access, and cron.
- PHP 8.3.6 or a compatible PHP 8.3 patch release and Composer 2. PHP 8.4 is not required; Composer resolves and locks dependencies for the PHP 8.3.6 deployment target.
- Required PHP extensions: `bcmath`, `ctype`, `curl`, `dom`, `fileinfo`, `filter`, `hash`, `intl`, `mbstring`, `openssl`, `pdo`, `pdo_mysql`, `session`, `tokenizer`, and `xml`; `gd` and `zip` are recommended for images and archives.
- MySQL 8 with `utf8mb4`, InnoDB, a dedicated database/user, and timezone configured consistently.
- Node.js 20+ and npm only if assets are built on the server; CI uses Node.js 20. The deployment artifact includes `public/build` and does not require Node.js on the server.
- `.env.example` defaults to file cache, file sessions, and the synchronous queue. Redis and database-backed queue/cache/session drivers are optional deployment choices, not prerequisites.

Baseline sizing for a small installation is 2 CPU cores, 2 GB RAM, and sufficient SSD space for releases, logs, uploads, database growth, and backups. Measure real traffic and increase resources before saturation. Suggested PHP limits are `memory_limit=256M`, `upload_max_filesize=20M`, `post_max_size=25M`, and `max_execution_time=60`; adjust upload limits to validated product needs while keeping the application limit no higher than the server limit.

## Web and filesystem

- Set the virtual-host document root to the release's `public/` directory, never the repository root.
- Deny access to dotfiles, `.env`, source control, storage internals, and dependency manifests.
- Redirect HTTP to HTTPS and use a valid automatically renewed TLS certificate.
- The deployment account should own release files. The PHP-FPM/queue group needs read access and write access only to `storage/` and `bootstrap/cache/`.
- Use directories around `0755`, files around `0644`, and writable runtime directories around `0775`; do not use `0777`.
- Keep `.env` around `0640` (or stricter) and outside release replacement. Persist `storage/app` as required and run `php artisan storage:link` if public-disk files are used.

Example writable-directory preparation, with names adjusted to the host:

```bash
chown -R deploy:www-data /var/www/threegoats
find /var/www/threegoats -type d -exec chmod 0755 {} \;
find /var/www/threegoats -type f -exec chmod 0644 {} \;
find /var/www/threegoats/shared/storage -type d -exec chmod 0775 {} \;
find /var/www/threegoats/shared/storage -type f -exec chmod 0664 {} \;
find /var/www/threegoats/current/bootstrap/cache -type d -exec chmod 0775 {} \;
find /var/www/threegoats/current/bootstrap/cache -type f -exec chmod 0664 {} \;
chmod 0640 /var/www/threegoats/shared/.env
```

## Processes

Run the scheduler every minute as the deployment/PHP user:

```cron
* * * * * cd /var/www/threegoats/current && php artisan schedule:run >> /dev/null 2>&1
```

If `QUEUE_CONNECTION` selects an asynchronous driver such as `database` or `redis`, run at least one process-manager-supervised worker:

```bash
php /var/www/threegoats/current/artisan queue:work --sleep=3 --tries=3 --max-time=3600
```

Configure automatic restart, log rotation, and startup after reboot. Execute `php artisan queue:restart` after each release that uses workers. Ensure failed-job monitoring is operational. The default `sync` driver does not use a worker.

## External services

- Configure authenticated production mail (SMTP or supported provider); `MAIL_MAILER=log` is not delivery.
- Keep MySQL/Redis private to the application network and back them up.
- Provide DNS, HTTPS, outbound DNS/HTTPS, NTP, and mail-provider connectivity.
- Back up MySQL, persistent storage, `.env`, and `APP_KEY`; define retention and test restores.

## Required environment

Set at minimum:

- Application: `APP_NAME`, `APP_ENV=production`, persistent `APP_KEY`, `APP_DEBUG=false`, `APP_URL=https://...`, locale values, and `LOG_*`.
- Database: `DB_CONNECTION=mysql`, `DB_HOST`, `DB_PORT=3306`, `DB_DATABASE`, `DB_USERNAME`, `DB_PASSWORD` (or a controlled `DB_URL`).
- State: `SESSION_DRIVER`, `SESSION_DOMAIN`, `SESSION_SECURE_COOKIE=true` where supported, `CACHE_STORE`, `QUEUE_CONNECTION`, and `FILESYSTEM_DISK`.
- Mail: `MAIL_MAILER`, `MAIL_SCHEME`, `MAIL_HOST`, `MAIL_PORT`, `MAIL_USERNAME`, `MAIL_PASSWORD`, `MAIL_FROM_ADDRESS`, and `MAIL_FROM_NAME`.
- Redis only when selected: `REDIS_CLIENT`, `REDIS_HOST`, `REDIS_PASSWORD`, and `REDIS_PORT`.
- Object storage only when selected: `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_DEFAULT_REGION`, `AWS_BUCKET`, and endpoint/path-style settings.

Do not copy local values blindly. Validate every environment choice against the installed release and never send secret values in acceptance or feedback reports.

## Status

These are target requirements only. No server was accessed, validated, provisioned, or deployed while preparing this document.