import { Callout } from 'nextra/components'

# Deployment Processes

How we deploy code changes to staging and production.

## API Deployment (`studio_api`)

**Trigger**: Push to `main` branch

### Pipeline (AWS CodePipeline in dev account)

1. **Source Stage**
   - GitHub webhook detects commit
   - Downloads latest code

2. **Build Stage** (CodeBuild)
   - Runs tests (`pytest`)
   - Builds Docker image
   - Pushes to ECR (Elastic Container Registry)

3. **Deploy Stage**
   - ECS rolling deployment
   - Health checks before marking healthy
   - Automatic rollback on failure

### Monitoring Deployment

- View pipeline in AWS Console
- Check logs in CloudWatch
- Monitor deployment in Datadog

### Manual Rollback

<Callout type="error">
  **Emergency rollback procedure:**

  If the deployment causes issues, rollback to the previous task definition:

  ```bash
  aws ecs update-service \
    --cluster studio-api-prod \
    --service api-service \
    --task-definition studio-api:PREVIOUS_VERSION
  ```

  Always check Datadog error rates and Sentry before and after deployment.
</Callout>

## Modal Deployment (`suno_utils`)

**Location**: `suno_utils`

**Script**: `deploy_modal.py`

### Process

```bash
cd suno_utils
uv run deploy_modal.py suno_utils/worker/modal_runner_chirp_v4_engine.py
# Prompts: Choose environment (dev/prod)
```

**What it does**:
1. Asks for environment (dev/prod)
2. Temporarily updates `deployment_utils.py`
3. Runs `modal deploy <worker_file.py>`
4. App name becomes `chirp-v4-engine-{env}`
5. Restores original config

**See**: [Modal Deployment Guide](/backend/modal/deployment) for details

## Frontend Deployment (`ui`)

Merging main will deploy to staging. Then run `/deploy-ui` from [#tech-ui](https://suno-main.slack.com/archives/C06ANEMRBPS) to deploy to production.

## Database Migrations

### Local (During Development)

```bash
cd studio_api
uv run manage.py makemigrations
uv run manage.py migrate
```

### Production (Via CI/CD)

- Migrations run automatically before deployment

### Rollback

<Callout type="warning">
  **Reverting migrations:**

  ```bash
  # Revert last migration
  uv run manage.py migrate app_name PREVIOUS_MIGRATION_NAME
  ```

  Always test rollback procedures in staging first!
</Callout>

### Secrets Management

**AWS Secrets Manager**:
- `studio-api-dev-envs` - Local development secrets (prod AWS account)
- `studio-api-staging-envs` - Staging secrets (staging AWS account)
- `studio-api-prod-envs` - Production secrets (prod AWS account)

**Accessing Secrets**:
```bash
# View secret in AWS Console
aws secretsmanager get-secret-value \
  --secret-id studio-api-prod-envs \
  --region us-east-2 \
  --profile production
```

## Best Practices

### Pre-Deployment Checklist

- [ ] Tests pass locally
- [ ] Code reviewed and approved
- [ ] Database migrations tested in staging
- [ ] Breaking changes communicated to team
- [ ] Deployment plan documented (if complex)

### During Deployment

- [ ] Monitor Datadog error rates
- [ ] Check Sentry for new errors
- [ ] Verify health checks pass
- [ ] Test critical user flows
- [ ] Watch CloudWatch logs

### Post-Deployment

- [ ] Verify metrics return to normal
- [ ] Check for new Sentry errors
- [ ] Monitor for 30 minutes
- [ ] Update team in Slack
- [ ] Document any issues