forked from enviPath/enviPy
97 lines
3.8 KiB
Markdown
97 lines
3.8 KiB
Markdown
# 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
|
|
- 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.
|
|
|
|
### 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
|
|
```
|
|
|
|
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)
|
|
```
|
|
|
|
### 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
|
|
```
|