Files

Tobias O 1bad6e4b03 docs: add makefile and docker-compose for initial setup

Since sqlite is not a suitable backend due to array field switch to an
easy to setup postgres backend relying on docker. From cloning to run is
now just two commands.

Signed-off-by: Tobias O <tobias.olenyi@envipath.com>

2025-10-13 21:05:07 +13:00

3.5 KiB

Raw Blame History

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

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.

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:

Start the PostgreSQL database using Docker Compose.
Run database migrations.
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
```

3.5 KiB Raw Blame History