# Local Development

Source: https://www.potatoannotator.com/docs/deployment/local-development

Get Potato running on your local machine for development and testing.

## Prerequisites

- Python 3.7 or higher
- pip package manager
- Git (optional, for cloning examples)

## Installation

### Using pip (Recommended)

```bash
pip install potato-annotation
```

### From Source

```bash
git clone https://github.com/davidjurgens/potato.git
cd potato
pip install -e .
```

### With Optional Dependencies

```bash
# For audio annotation support
pip install potato-annotation[audio]

# For all optional features
pip install potato-annotation[all]
```

## Quick Start

### 1. Create a Configuration File

Create `config.yaml`:

```yaml
task_name: "My First Annotation Task"

server:
  port: 8000

data_files:
  - path: data.json
    text_field: text

annotation_schemes:
  - annotation_type: radio
    name: sentiment
    description: "What is the sentiment?"
    labels:
      - Positive
      - Negative
      - Neutral

output:
  path: annotations/
```

### 2. Prepare Sample Data

Create `data.json`:

```json
[
  {"id": "1", "text": "I love this product!"},
  {"id": "2", "text": "This is terrible."},
  {"id": "3", "text": "It's okay, nothing special."}
]
```

### 3. Start the Server

```bash
potato start config.yaml
```

### 4. Access the Interface

Open your browser to `http://localhost:8000`

## Development Mode

### Hot Reloading

Enable auto-restart when config changes:

```bash
potato start config.yaml --reload
```

### Debug Mode

Enable detailed logging:

```bash
potato start config.yaml --debug
```

### Verbose Output

See all server activity:

```bash
potato start config.yaml --verbose
```

## Directory Structure

Recommended project layout:

```
my-annotation-project/
├── config.yaml           # Main configuration
├── data/
│   ├── train.json        # Training data
│   └── main.json         # Annotation data
├── annotations/          # Output directory
├── templates/            # Custom HTML templates
└── static/               # Custom CSS/JS
```

## Testing Your Configuration

### Validate Config

Check for syntax errors:

```bash
potato validate config.yaml
```

### Preview Mode

Start without saving annotations:

```bash
potato start config.yaml --preview
```

### Test with Sample Data

Generate test data:

```bash
potato generate-data --count 10 --output test_data.json
```

## Common Issues

### Port Already in Use

```bash
# Use a different port
potato start config.yaml --port 8080

# Or in config.yaml
server:
  port: 8080
```

### Data File Not Found

Ensure paths are relative to the config file location:

```yaml
# If data is in subdirectory
data_files:
  - path: data/main.json

# Or use absolute path
data_files:
  - path: /full/path/to/data.json
```

### Permission Denied

Check file permissions:

```bash
chmod 755 annotations/
chmod 644 data/*.json
```

## Multiple Users Locally

For testing multi-user scenarios:

```yaml
allow_all_users: true
url_user_id_param: user_id
```

Access with different users:
- `http://localhost:8000/?user_id=annotator1`
- `http://localhost:8000/?user_id=annotator2`

## Reset Annotations

Clear all annotations and start fresh:

```bash
# Remove annotation files
rm -rf annotations/*

# Restart server
potato start config.yaml
```

## Environment Variables

Configure via environment:

```bash
export POTATO_PORT=8000
export POTATO_DEBUG=true
export POTATO_DATA_PATH=/path/to/data

potato start config.yaml
```

## Using with Virtual Environments

### venv

```bash
python -m venv potato-env
source potato-env/bin/activate  # Linux/Mac
potato-env\Scripts\activate     # Windows
pip install potato-annotation
```

### Conda

```bash
conda create -n potato python=3.10
conda activate potato
pip install potato-annotation
```

## IDE Integration

### VS Code

Install the YAML extension for config file support:

```json
// settings.json
{
  "yaml.schemas": {
    "https://potato-annotation.com/schema.json": "config.yaml"
  }
}
```

### PyCharm

Set up a run configuration:
1. Add → Python
2. Script: `potato`
3. Parameters: `start config.yaml`
4. Working directory: your project path

## Next Steps

- [Configuration Basics](/docs/getting-started/configuration-basics) - Learn all config options
- [Data Formats](/docs/core-concepts/data-formats) - Understand data structure
- [Production Setup](/docs/deployment/production-setup) - Deploy for real use