enviPy

Local Development Setup

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

Prerequisites

• Python 3.11 or later
• uv - Python package manager
• Docker and Docker Compose - Required for running PostgreSQL database
• 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.

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

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

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.

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)

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