# Production and On-Premise Deployment

MicroLearn ships one application image set for SaaS and dedicated On-Premise installations. `DEPLOYMENT_MODE` selects capabilities; it does not fork product code.

## Prerequisites

- Docker Engine 26+ with Compose v2
- 4 CPU, 8 GB RAM, and storage sized for uploaded video/export retention
- DNS and TLS termination at the ingress/load balancer
- Unique MySQL, Redis, MinIO/S3 and application secrets

## First boot

1. Copy `infrastructure/production/.env.production.example` to `.env.production` outside source control. For dedicated installs use the On-Premise template.
2. Generate `APP_KEY` with `php artisan key:generate --show` and replace every `CHANGE_ME` value.
3. Set `MICROLEARN_ENV_FILE` and secret variables in the deployment environment.
4. Run `docker compose -f docker-compose.production.yml build --pull`.
5. Run `docker compose -f docker-compose.production.yml run --rm app php artisan migrate --force`.
6. Start with `docker compose -f docker-compose.production.yml up -d`.
7. Verify `/api/v1/health`; database and storage must report `ok`. Confirm worker and scheduler containers remain healthy in logs.

TLS terminates before Nginx. Forward the original scheme/host through the trusted ingress and keep PHP, MySQL, Redis and object storage on a private network. Never expose MinIO console or database ports publicly.

## Scaling and operations

- Scale `worker` independently for ingestion/export/event load; keep `--timeout` above the largest export execution time.
- Run one or more schedulers with Laravel `withoutOverlapping` locks backed by Redis.
- Configure S3 lifecycle only after application export-retention policy; canonical Assets must not be expired by an export rule.
- Collect container logs, HTTP latency/error rate, queue depth/age, failed jobs, storage capacity, MySQL connections and scheduler heartbeat.
- Alert on health degradation, queue age, repeated export failures, low capacity, backup failure and certificate verification errors.

## On-Premise

Set `DEPLOYMENT_MODE=on_premise`. Multi-organization and subscription SaaS controls are hidden by capabilities. External AI defaults off. `FILESYSTEM_DISK`/`EXPORT_DISK` may be `local` for one-node installs or `s3` for MinIO-compatible storage. SMTP can remain `log` in disconnected environments.

## Release and rollback

Before every release: take and verify a backup, build immutable versioned images, run CI, inspect migrations, then deploy app/worker/scheduler from the same image digest. Run migrations once. Roll back images only for backward-compatible migrations; otherwise follow the database restore runbook.

## Disaster recovery

Define site-specific RPO/RTO. The reference scripts back up MySQL plus private application storage. Object-store versioning/replication supplements—but does not replace—tested restores. Perform a restore drill at least quarterly.