# 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)

```bash
curl -fsSL https://pyenv.run | bash
```

### 1.2 Configure shell for pyenv

Add the following to `~/.zshrc`:

```zsh
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:

```zsh
exec "$SHELL"
```

Verify:

```zsh
pyenv --version
```

### 1.3 Install system dependencies
```zsh
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

```zsh
pyenv install 3.14
```

Set the local Python version for this project:

```zsh
pyenv local 3.14
```

Verify:

```zsh
python --version
```

---

## 3. Install Poetry

### 3.1 Install Poetry (if not already installed)

```zsh
curl -sSL https://install.python-poetry.org | python3 -
```

Ensure Poetry is on PATH:

```zsh
export PATH="$HOME/.local/bin:$PATH"
```

Enable tab completion for Zsh
```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:
```zsh
plugins(
	poetry
	...
	)
```

Verify:

```zsh
poetry --version
```

---

## 4. Configure Poetry to use pyenv’s Python

From the project root directory:

```zsh
poetry env use "$(pyenv which python)"
```

Verify the environment:

```zsh
poetry env info
```

---

## 5. Install the project

### 5.1 Install dependencies

```zsh
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)

```zsh
eval $(poetry env activate)
```

Or run commands directly:

```zsh
poetry run python your_script.py
```

---

## 7. Install nvm

### 7.1 Install nvm (if not already installed)

```bash
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`:

```zsh
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:

```zsh
exec "$SHELL"
```

Verify:

```zsh
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.

```