Docs/Deployment

Local Development

Set up Potato for local development and testing.

Local Development

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

Prerequisites

  • Python 3.8 or higher
  • pip package manager
  • Git (optional, for cloning examples)

Installation

Using pip (Recommended)

pip install potato-annotation

From Source

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

With Optional Dependencies

# 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:

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:

[
  {"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

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:

potato start config.yaml --reload

Debug Mode

Enable detailed logging:

potato start config.yaml --debug

Verbose Output

See all server activity:

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:

potato validate config.yaml

Preview Mode

Start without saving annotations:

potato start config.yaml --preview

Test with Sample Data

Generate test data:

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

Common Issues

Port Already in Use

# 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:

# 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:

chmod 755 annotations/
chmod 644 data/*.json

Multiple Users Locally

For testing multi-user scenarios:

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:

# Remove annotation files
rm -rf annotations/*
 
# Restart server
potato start config.yaml

Environment Variables

Configure via environment:

export POTATO_PORT=8000
export POTATO_DEBUG=true
export POTATO_DATA_PATH=/path/to/data
 
potato start config.yaml

Using with Virtual Environments

venv

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

Conda

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:

// 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

NextProduction Setup