# Modal Deployment Guide

This guide explains how to deploy and run Modal workers using the centralized deployment system.

## Overview

Two scripts are available for working with Modal workers:
- **`deploy_modal.py`** - For deploying Modal workers to dev or prod environments
- **`run_modal.py`** - For running Modal workers locally with proper environment configuration

Both scripts automatically manage environment configuration to ensure consistent behavior.

## Quick Start

### Running Modal Workers Locally

From the `suno_utils` directory:

```bash
uv run run_modal.py <path-to-modal-file> [additional-args...]
```

Example:
```bash
uv run run_modal.py suno_utils/worker/modal_upload_video.py
```

The run script automatically:
- Sets the deployment type to `dev` (avoiding the "Deployment type not set" error)
- Preserves rich terminal output (colors, progress bars, etc.)
- Passes any additional arguments to the modal command
- Restores the original configuration after running

### Deploying Modal Workers

From the `suno_utils` directory:

```bash
uv run deploy_modal.py <path-to-modal-file>
```

Example:
```bash
uv run deploy_modal.py suno_utils/worker/modal_upload_video.py
```

## How It Works

### Deploy Script (`deploy_modal.py`)

The deployment script:

1. **Detects your app prefix** by reading `get_app_name("your-prefix")` from your Modal file
2. **Prompts for environment selection** (dev or prod)
3. **Shows the target app name** (e.g., `your-prefix-dev` or `your-prefix-prod`)
4. **Temporarily updates** [deployment_utils.py](https://github.com/suno-ai/glockenspiel/blob/main/suno_utils/suno_utils/worker/deployment_utils.py#L12) with the deployment type
5. **Runs** `modal deploy` with your file
6. **Restores** the original deployment configuration

This ensures your Modal app is deployed with the correct name suffix (`-dev` or `-prod`) without manually editing configuration files.

### Run Script (`run_modal.py`)

The run script:

1. **Detects your app prefix** by reading `get_app_name("your-prefix")` from your Modal file
2. **Automatically sets deployment type to `dev`** (no prompts)
3. **Temporarily updates** [deployment_utils.py](https://github.com/suno-ai/glockenspiel/blob/main/suno_utils/suno_utils/worker/deployment_utils.py#L12) with `dev` configuration
4. **Runs** `modal run` with your file and any additional arguments
5. **Restores** the original deployment configuration

This eliminates the "Deployment type not set. This application must be deployed using the deploy_modal.py script. Defaulting to dev, but this must be fixed." error message that appears when running modal workers directly.

## Setting Up Your Modal File

To use both the deployment and run scripts, your Modal file must follow this pattern:

```python
from suno_utils.worker.deployment_utils import get_app_name

# Set your app prefix - this becomes "my-worker-dev" or "my-worker-prod"
APP_NAME = get_app_name("my-worker")

# Create your Modal app
app = modal.App(APP_NAME)
```

## Understanding the Deployment System

### The deployment_utils.py File

The [deployment_utils.py](https://github.com/suno-ai/glockenspiel/blob/main/suno_utils/suno_utils/worker/deployment_utils.py) file contains a static configuration variable:

```python
_STATIC_DEPLOYMENT_TYPE = "NOT_SET"
```

During deployment, the script:
1. Temporarily changes this to `"dev"` or `"prod"`
2. Runs `modal deploy`
3. Restores it to `"NOT_SET"`

This ensures that:
- Local development always shows `"NOT_SET"` (preventing accidental prod references)
- Deployed apps have the correct environment baked in at deploy time
- No environment variables or runtime configuration is needed

### App Naming Convention

All Modal apps follow this naming pattern:
- Development: `{prefix}-dev` (e.g., `upload-video-dev`)
- Production: `{prefix}-prod` (e.g., `upload-video-prod`)

This makes it easy to identify which environment an app belongs to in the Modal dashboard.

## Common Issues

### Error: File doesn't use the centralized deployment system

```
Error: <file> doesn't use the centralized deployment system
File should import from suno_utils.worker.deployment_utils
```

**Solution**: Add the required imports to your Modal file:

```python
from suno_utils.worker.deployment_utils import get_app_name

APP_NAME = get_app_name("your-prefix")
app = modal.App(APP_NAME)
```

### Error: Could not determine app name prefix

```
Error: Could not determine app name prefix from <file>
```

**Solution**: Ensure you're calling `get_app_name()` with a string literal:

```python
# Good
APP_NAME = get_app_name("my-worker")

# Bad - won't be detected
prefix = "my-worker"
APP_NAME = get_app_name(prefix)
```

## Manual Operations (Not Recommended)

### Direct Modal Deploy

If you need to deploy without the script:

```bash
# Direct modal deployment (skips environment management)
uv run modal deploy suno_utils/worker/modal_upload_video.py
```

**Warning**: This will use whatever value is currently in `_STATIC_DEPLOYMENT_TYPE`, which is usually `"NOT_SET"` and will default to dev. Always prefer using `deploy_modal.py` for consistent deployments.

### Direct Modal Run

If you need to run without the script:

```bash
# Direct modal run (will show "Deployment type not set" error)
uv run modal run suno_utils/worker/modal_upload_video.py
```

**Warning**: This will trigger the "Deployment type not set" error message because `_STATIC_DEPLOYMENT_TYPE` is `"NOT_SET"`. While it will still work (defaulting to dev), the error is noisy. Always prefer using `run_modal.py` for a clean experience.

## Related Files

- [deploy_modal.py](https://github.com/suno-ai/glockenspiel/blob/main/suno_utils/deploy_modal.py) - Deployment script for dev/prod
- [run_modal.py](https://github.com/suno-ai/glockenspiel/blob/main/suno_utils/run_modal.py) - Run script for local development
- [modal_deployment_shared.py](https://github.com/suno-ai/glockenspiel/blob/main/suno_utils/modal_deployment_shared.py) - Shared utilities for both scripts
- [deployment_utils.py](https://github.com/suno-ai/glockenspiel/blob/main/suno_utils/suno_utils/worker/deployment_utils.py) - Central deployment configuration
- [Modal Workers README](https://github.com/suno-ai/glockenspiel/blob/main/suno_utils/suno_utils/worker/README.md) - General Modal worker documentation