Installation (Ubuntu)
This project uses pyenv for Python version management and Poetry for dependency and virtual environment management.
1. Install pyenv
1.1 Install pyenv (if not already installed)
curl -fsSL https://pyenv.run | bash
1.2 Configure shell for pyenv
Add the following to ~/.zshrc:
echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.zshrc
echo '[[ -d $PYENV_ROOT/bin ]] && export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.zshrc
echo 'eval "$(pyenv init - zsh)"' >> ~/.zshrc
Reload the shell:
exec "$SHELL"
Verify:
pyenv --version
1.3 Install system dependencies
sudo apt update; sudo apt install make build-essential libssl-dev zlib1g-dev \
libbz2-dev libreadline-dev libsqlite3-dev curl git \
libncursesw5-dev xz-utils tk-dev libxml2-dev libxmlsec1-dev libffi-dev liblzma-dev
2. Install Python 3.14 using pyenv
pyenv install 3.14.0
Set the local Python version for this project:
pyenv local 3.14.0
Verify:
python --version
3. Install Poetry
3.1 Install Poetry (if not already installed)
curl -sSL https://install.python-poetry.org | python3 -
Ensure Poetry is on PATH:
export PATH="$HOME/.local/bin:$PATH"
Enable tab completion for Zsh
poetry completions zsh > ~/.zfunc/_poetry
Verify:
poetry --version
4. Configure Poetry to use pyenv’s Python
From the project root directory:
poetry env use "$(pyenv which python)"
Verify the environment:
poetry env info
5. Install the project
5.1 Install dependencies
poetry install
This will:
- Create a virtual environment
- Install all dependencies defined in
pyproject.toml - Use Python 3.14 from pyenv
6. Activate the environment (optional)
eval $(poetry env activate)
Or run commands directly:
poetry run python your_script.py
7. Install nvm
7.1 Install nvm (if not already installed)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash
7.2 Configure shell for pyenv
Add the following to ~/.zshrc:
export NVM_DIR="$([ -z "${XDG_CONFIG_HOME-}" ] && printf %s "${HOME}/.nvm" || printf %s "${XDG_CONFIG_HOME}/nvm")"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh" # This loads nvm
Reload the shell:
exec "$SHELL"
Verify:
nvm --version
Notes
- Do not use system-wide pip for this project.
- All dependencies (including
psycopg) are managed by Poetry. - PostgreSQL must be running and properly configured before application startup.