# cPanel deployment guide

## Domain structure

Create three separate hostnames:

```text
developer.example.com → AI panel
 test.example.com      → staging application
 app.example.com       → production application
```

Use separate directories and databases. The AI panel's configured project root must be the staging application root.

## Suggested directory structure

```text
/home/USER/apps/
├── cpanel-ai-developer/
│   ├── config/
│   ├── public/          ← developer.example.com document root
│   ├── src/
│   └── storage/
├── myapp-staging/
│   └── public/          ← test.example.com document root
└── myapp-production/
    └── public/          ← app.example.com document root
```

Some older PHP applications use the application root itself as the public document root. The panel can still manage them, but keeping configuration and application code outside the public directory is safer.

## Staging database

Create a new MySQL database and database user in cPanel. Use a staging-only configuration file that is blocked from the AI panel and Git. Prefer generated/sample records. If production data must be copied, remove names, emails, phone numbers, access tokens, payment details, and other personal information first.

## Git branches

Recommended:

```text
origin/staging → /home/USER/apps/myapp-staging
origin/main    → /home/USER/apps/myapp-production
```

The panel can commit an approved staging file. Push staging, review/merge into main, then update the production checkout.

## cPanel Git deployment

cPanel deployment requires a checked-in `.cpanel.yml` in the repository root, at least one branch, and a clean working tree. Edit `.cpanel.yml.example` before renaming it. Do not deploy the `.git` directory, secrets, or writable runtime data.

Manual pull deployment in cPanel is safer for production because it separates **Update from Remote** from **Deploy HEAD Commit**.

## Manual production command

The starter's example uses:

```bash
/usr/bin/git -C /home/USER/apps/myapp-production pull --ff-only origin main
```

Test the command in SSH first. Only then set `deploy.enabled` to true. `--ff-only` prevents an unexpected merge from being created on the server.

Applications that require build, cache-clear, or migration commands should use a reviewed deployment script with fixed commands. Do not expose free-form shell input in the panel.

## Database migrations

Version 0.1.0 does not execute migrations automatically. A safe production workflow is:

1. back up the production database;
2. test the migration against the staging database;
3. review whether it is backward-compatible;
4. enable maintenance mode if required;
5. run the exact migration command manually;
6. deploy code;
7. run smoke tests;
8. disable maintenance mode.

## SSL and access protection

Use AutoSSL for all three domains. Restrict the developer domain further using cPanel Directory Privacy, an IP allowlist, or both. The application's login is defense in depth, not a replacement for HTTPS and hosting-level controls.