# Installation

## Prerequisites

- Python 3.11 or later
- UV package manager (recommended) or pip
- Git

## Install with UV (Recommended)

```bash
# Clone the repository
git clone https://github.com/SoftmatterLMU-RaedlerGroup/pyama.git
cd pyama

# Install all dependencies including dev tools
uv sync --all-extras

# Install packages in development mode
uv pip install -e pyama/
```

## Install with pip

```bash
# Clone the repository
git clone https://github.com/SoftmatterLMU-RaedlerGroup/pyama.git
cd pyama

# Create and activate virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -e pyama/
```

## Verify Installation

```bash
# Start the API server
uv run pyama serve --port 8000 --reload

# In another terminal, run the React/Electron client
cd pyama-react
bun install  # or npm install
bun run dev
```

## Development Dependencies

For development, you'll also want to install the dev dependencies:

```bash
# With UV
uv sync --all-extras

# With pip
pip install pytest ruff ty
```

## Docker (API Server)

Run the pyama API server in a Docker container:

```bash
cd pyama

# Build and run with GPU (default - Linux with NVIDIA)
docker compose up --build

# Or CPU-only (Mac or no GPU)
docker compose --profile cpu up --build pyama-cpu

# Server available at http://localhost:8765
# Health check: curl http://localhost:8765/health
```

### Volume Mounts

Configure data access in `docker-compose.yml`:

```yaml
volumes:
  - ~/data:/data        # Microscopy files (use /data/... in API requests)
  - ~/results:/results  # Output directory (use /results/... in API requests)
  - pyama-db:/root/.pyama  # Persist task database
```

**Important**: Symlinks in mounted directories won't work. Mount the actual data locations instead.

### GPU Support

The container uses PyTorch 2.10.0 with CUDA 13.0:

- **GPU (default)**: `docker compose up` - requires [NVIDIA Container Toolkit](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/install-guide.html) on Linux
- **CPU**: `docker compose --profile cpu up pyama-cpu` - works on Mac or systems without GPU

## Troubleshooting

### Python Version
Make sure you're using Python 3.11 or later. Check with:
```bash
python --version
```

### UV Installation
Install UV following the official guide at https://docs.astral.sh/uv/

### Web Frontend Dependencies
PyAMA React client requires Node.js plus either Bun or npm:
- **Install Bun (recommended)**: https://bun.sh/
- **Or use npm**: bundled with Node.js