# enviPy

## Local Development Setup

These instructions will guide you through setting up the project for local development.

### Prerequisites

- Python 3.11 or later
- [uv](https://github.com/astral-sh/uv) - Python package manager
- **Docker and Docker Compose** - Required for running PostgreSQL database and Redis (for async Celery tasks)
- Git
- Make

> **Note:** This application requires PostgreSQL (uses `ArrayField`). Docker is the easiest way to run PostgreSQL locally.

### 1. Install Dependencies

This project uses `uv` to manage dependencies and `poe-the-poet` for task running. First, [install `uv` if you don't have it yet](https://docs.astral.sh/uv/guides/install-python/).

Then, sync the project dependencies. This will create a virtual environment in `.venv` and install all necessary packages, including `poe-the-poet`.

```bash
uv sync --dev
```

Note on RDkit installation: if you have rdkit installed on your system globally with a different version of python, the installation will try to link against that and subsequent calls fail. Only option remove global rdkit and rerun sync.

---

The frontend requires `pnpm` to correctly display in development.
[Install it here](https://pnpm.io/installation).

### 2. Set Up Environment File

Copy the example environment file for local setup:

```bash
cp .env.local.example .env
```

This file contains the necessary environment variables for local development.

### 3. Quick Setup with Poe

The easiest way to set up the development environment is by using the `poe` task runner, which is executed via `uv run`.

```bash
uv run poe setup
```

This single command will:

1. Start the PostgreSQL database using Docker Compose.
2. Run database migrations.
3. Bootstrap initial data (anonymous user, default packages, models).

After setup, start the development server:

```bash
uv run poe dev
```

This will start the css-watcher as well as the django-development server,
The application will be available at `http://localhost:8000`.

**Note:** The development server automatically starts a CSS watcher (`pnpm run dev`) alongside the Django server to rebuild CSS files when changes are detected. This ensures your styles are always up-to-date during development.

#### Other useful Poe commands

You can list all available commands by running `uv run poe --help`.

```bash
uv run poe db-up         # Start PostgreSQL only
uv run poe db-down       # Stop PostgreSQL
uv run poe migrate       # Run migrations only
uv run poe bootstrap     # Bootstrap data only
uv run poe shell         # Open the Django shell
uv run poe build         # Build frontend assets and collect static files
uv run poe clean         # Remove database volumes (WARNING: destroys all data)
uv run poe celery        # Start Celery worker for async task processing
uv run poe celery-dev    # Start database and Celery worker
```

### 4. Async Celery Setup (Optional)

By default, Celery tasks run synchronously (`CELERY_TASK_ALWAYS_EAGER = True`), which means prediction tasks block the HTTP request until completion. To enable asynchronous task processing with live status updates on pathway pages:

1. **Set the Celery flag in your `.env` file:**

   ```bash
   FLAG_CELERY_PRESENT=True
   ```

2. **Start Redis and Celery worker:**

   ```bash
   uv run poe celery-dev
   ```

3. **Start the development server** (in another terminal):
   ```bash
   uv run poe dev
   ```

### Troubleshooting

- **Docker Connection Error:** If you see an error like `open //./pipe/dockerDesktopLinuxEngine: The system cannot find the file specified` (on Windows), it likely means your Docker Desktop application is not running. Please start Docker Desktop and try the command again.

- **SSH Keys for Git Dependencies:** Some dependencies are installed from private git repositories and require SSH authentication. Ensure your SSH keys are configured correctly for Git.
  - For a general guide, see [GitHub's official documentation](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent).
  - **Windows Users:** If `uv sync` hangs while fetching git dependencies, you may need to explicitly configure Git to use the Windows OpenSSH client and use the `ssh-agent` to manage your key's passphrase.
    1.  **Point Git to the correct SSH executable:**
        ```powershell
        git config --global core.sshCommand "C:/Windows/System32/OpenSSH/ssh.exe"
        ```
    2.  **Enable and use the SSH agent:**

        ```powershell
        # Run these commands in an administrator PowerShell
        Get-Service ssh-agent | Set-Service -StartupType Automatic -PassThru | Start-Service

        # Add your key to the agent. It will prompt for the passphrase once.
        ssh-add
        ```
