enviPy

Local Development Setup

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

Prerequisites

• Python 3.11 or later
• uv - A fast Python package installer and resolver.
• Docker and Docker Compose - Required for running the PostgreSQL database.
• Git

Note: This application requires PostgreSQL, which uses ArrayField. Docker is the recommended 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.

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

uv sync --dev

Note on RDkit: If you have a different version of rdkit installed globally, the dependency installation may fail. If this happens, please uninstall the global version and run uv sync again.

2. Set Up Environment File

Copy the example environment file for local setup:

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.

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:

uv run poe dev

The application will be available at http://localhost:8000.

Other useful Poe commands:

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

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 clean         # Remove database volumes (WARNING: destroys all data)

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.

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

       git config --global core.sshCommand "C:/Windows/System32/OpenSSH/ssh.exe"
       

    2. Enable and use the SSH agent:

       # 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