Installation (Ubuntu)

This project uses pyenv for Python version management and Poetry for dependency and virtual environment management.

---

1. Install uv

1.1 Install uv (if not already installed)

curl -LsSf https://astral.sh/uv/install.sh | sh

Reload the shell:

exec "$SHELL"

Verify:

uv --version

2. Install Python 3.14 using uv

uv python install 3.14

Set the local Python version for this project:

uv python pin 3.14

Verify:

python --version

---

3. Install project dependencies

3.1 Install dependencies

uv sync

This will:

• Create a local .venv
• Install all dependencies defined in pyproject.toml
• Generate/update uv.lock
• Use Python 3.14

---

4. Activate the environment (optional)

source .venv/bin/activate

Deactivate:

deactivate

Or run commands directly:

uv run python your_script.py

---

5. Install nvm

5.1 Install nvm (if not already installed)

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash

5.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.
• Do not install dependencies manually.
• Always use uv sync to install or update dependencies.
• Commit both: pyproject.toml and uv.lock
• PostgreSQL must be running and properly configured before application startup.