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

Set the local Python version for this project:

pyenv local 3.14

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

mkdir $ZSH_CUSTOM/plugins/poetry
poetry completions zsh > $ZSH_CUSTOM/plugins/poetry/_poetry

You must then add poetry to your plugins array in ~/.zshrc:

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