# Local Development Setup

The `setup.sh` script at the root of the repository automates the initial setup of your local Suno development environment. This guide explains what the script does and how to use it.

## Prerequisites

Before running the script, you need:

1. **Environment file**: Create `ui/app-ui/.env` with required environment variables (ask a team member)
2. **AWS Profile**: Set the `AWS_PROFILE` environment variable
3. **CALLBACK_HOST**: Set this to your machine's Tailscale hostname (e.g., `your-machine.han-mahi.ts.net`)
   - Add to `~/.zprofile`: `export CALLBACK_HOST=<your_machine_name>.han-mahi.ts.net`
   - Or set it in `studio_api/.env`

## What the Script Does

### 1. Dependency Installation

The script checks for and installs the following tools via Homebrew:

- **Homebrew** - macOS package manager (auto-installs if missing)
- **Git** - Version control (includes Git Credential Manager)
- **Python 3.10** - Required Python version
- **uv** - Fast Python package manager
- **npm** - Node package manager
- **nvm** - Node version manager
- **pnpm** - Preferred Node package manager for this project
- **lefthook** - Git hooks manager for pre-commit checks

### 2. Service Setup

The script starts required local services:

#### PostgreSQL
- Detects and starts any installed PostgreSQL version (prefers 17, 16, 15, 14)
- If not installed, installs PostgreSQL 17 via Homebrew
- Waits up to 30 seconds for PostgreSQL to be ready
- Creates databases: `suno_studio`, `suno2`
- Creates user: `suno` with password `suno`
- Grants necessary privileges

#### Redis
- Starts Redis service via Homebrew
- Installs Redis if not found

#### Elasticsearch
- Creates Docker network named `elastic`
- Pulls `elasticsearch:8.15.2` image
- Creates/starts container named `elasticsearch`
- Runs on ports 9200 (HTTP) and 9300 (transport)
- Configured as single-node with security disabled

#### DynamoDB
- Sets up local DynamoDB via Docker (if not already running)
- Runs bootstrap script: `studio_api/scripts/local_lyrics_migration/bootstrap.sh`
- Runs migration script: `studio_api/scripts/local_lyrics_migration/migrate_local_lyrics.py`

### 3. Python Environment

- Creates virtual environment in `suno_utils/.venv`
- Runs `uv sync` to install Python dependencies

### 4. Database Migration and Seeding

- Runs Django migrations: `studio_api/manage.py migrate_all`
- Seeds model data: `studio_api/manage.py seed_model_data`

### 5. Frontend Setup

- Prepares DSP engine artifacts: `ui/app-ui/pnpm run prepare-dsp`

### 6. Modal Configuration

- Checks for `~/.modal.toml` configuration file
- If missing, runs `modal token new` to authenticate with Modal

## Running the Script

```bash
./setup.sh
```

The script will:
1. Prompt for confirmation before starting
2. Check/install dependencies
3. Verify environment variables
4. Start required services
5. Set up databases
6. Run migrations

## After Setup

Once the script completes successfully:

1. Run the VSCode task: **"Sync Packages and Models"**
2. Go to **Run/Debug** and press: **Run All**

This will start all necessary development servers.

## Troubleshooting

### PostgreSQL Won't Start
- Check if another PostgreSQL instance is running: `brew services list`
- Check PostgreSQL logs: `tail -f /opt/homebrew/var/log/postgresql@17.log`

### Docker Not Running
The script requires Docker to be running for Elasticsearch and DynamoDB. Start Docker Desktop before running the script.

### Modal Authentication Issues
If Modal token creation fails:
1. Ensure you have access to Suno's Modal workspace
2. Manually run: `cd suno_utils && uv run modal token new`
3. Follow the authentication flow in your browser

### Database Connection Issues
- Verify PostgreSQL is running: `psql -d template1 -c "SELECT 1"`
- Check database exists: `psql -l | grep suno`
- Verify user credentials: `psql -U suno -d suno_studio`

### Missing Environment Variables
If you see errors about missing env vars:
- `AWS_PROFILE`: Add to shell profile (`~/.zprofile`)
- `CALLBACK_HOST`: Add to shell profile or `studio_api/.env`
- `ui/app-ui/.env`: Get this file from a team member

## Idempotency

The script is designed to be **idempotent** - you can run it multiple times safely. It will:
- Skip installing packages that are already installed
- Skip starting services that are already running
- Skip creating databases/users that already exist
- Reuse existing Docker containers

## Adding New Databases

When adding a new database to the project, update the database creation section in `setup.sh` (around line 345). See the [Add a Database](/infra/postgres/add-new-db) guide for details.

## Related Documentation

- [How to Add a Database](/infra/postgres/add-new-db)
- [Backend Development Guide](/backend/backend-guide)
- [Frontend Development Guide](/frontend/frontend-guide)