Local Development

Install and run Potato locally for development and testing. Covers pip install, config setup, launching the dev server, and debugging common startup issues.

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:

text

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:

Add → Python
Script: potato
Parameters: start config.yaml
Working directory: your project path

Next Steps

Configuration Basics - Learn all config options
Data Formats - Understand data structure
Production Setup - Deploy for real use