# Ephemeral Environments

Short-lived copies of ows-coda in QA for PR previews and integration testing.

## Quick start

Comment on any PR:

| Comment                | Effect                       |
| ---------------------- | ---------------------------- |
| `ephemeral deploy`     | Deploy this PR (7-day TTL)   |
| `ephemeral deploy 15d` | Deploy with 15-day TTL       |
| `ephemeral extend 7d`  | Reset TTL to 7 days from now |
| `ephemeral destroy`    | Tear down                    |
| `ephemeral list`       | Show all active environments |

The environment URL will be posted as a PR comment:
`https://qa-ows-coda-pr-{id}.theorchard.io`

## How it works

Each ephemeral environment gets:

- Its own Fargate service (reduced sizing: 512 CPU, 1GB RAM, 1 task)
- Its own database schema on the shared QA RDS cluster
- Shared Redis, S3, and downstream service connections

Tests must pass before deploy. The environment expires automatically via TTL.
Maximum 10 concurrent environments.

## One-time setup (admin)

These steps are required before the pipeline works for the first time:

### 1. Create Jenkins job

Create a new pipeline job in Jenkins:

- **Type:** Pipeline (not multibranch)
- **Source:** ows-coda repo
- **Script path:** `Jenkinsfile.ephemeral`
- **Triggers:** Enable "GitHub Pull Request Comment Trigger" and "Build periodically" (cron: `H 3 * * *`)

### 2. Create coda_ephemeral DB user

Connect to the QA RDS cluster as `coda_admin`:

```sql
CREATE USER 'coda_ephemeral'@'%' IDENTIFIED BY '<generated-password>';
GRANT ALL PRIVILEGES ON `coda\_%`.* TO 'coda_ephemeral'@'%';
FLUSH PRIVILEGES;
```

### 3. Update coda_svc grants

```sql
GRANT ALL PRIVILEGES ON `coda\_%`.* TO 'coda_svc'@'%';
FLUSH PRIVILEGES;
```

### 4. Store password in Secrets Manager

```bash
aws secretsmanager create-secret \
  --name qa/ows-coda/CODA_DB_EPHEMERAL_PASS \
  --secret-string '<the-password-from-step-2>' \
  --region us-east-1
```

### 5. Apply Terraform changes

PR and merge the terraform-infra changes (Tasks 1-3) to add the secret to the Terraform module.

### 6. Verify Terraform role permissions

Confirm the `prod-jenkins-aws-pipeline-agent` role can run `terraform apply/destroy` in QA for ECS, EC2 security groups, IAM, and ELB resources. If not, create a scoped role.

## Troubleshooting

### Environment created but unhealthy

The database may not exist or migrations may have failed. Check the Jenkins build log for DB Setup errors. Run `ephemeral destroy` and retry.

### "At capacity" error

Run `ephemeral list` to see active environments. Destroy unused ones or wait for TTL expiry.

### "Environment already exists" error

Run `ephemeral destroy` first, then `ephemeral deploy`.