diff --git a/Dockerfile b/Dockerfile
index 96cac62b..1c2af459 100644
--- a/Dockerfile
+++ b/Dockerfile
@@ -61,4 +61,8 @@ RUN chmod 777 /app/docker-entrypoint.sh \
     && ln -s /app/docker-entrypoint.sh /
 ENTRYPOINT ["docker-entrypoint.sh"]
 
+# at the end of your Dockerfile, before CMD or after EXPOSE
+HEALTHCHECK --interval=30s --timeout=5s --start-period=10s --retries=3 \
+  CMD curl -f http://localhost/health || exit 1
+
 CMD ["poetry", "run", "/app/run.sh"]
diff --git a/README.md b/README.md
index 06286b5d..a87f3a2a 100644
--- a/README.md
+++ b/README.md
@@ -1,41 +1,176 @@
-# Installation on Ubuntu 14.04
-## Prepare the system
-1. Install system-wide pip
-**Currently the ensurepip is broken in Python 3.4 / Ubuntu 14.04, therefore we need to install system-wide pip**
+# 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
-sudo apt-get install python3-pip
+curl -fsSL https://pyenv.run | bash
 ```
 
-2. Install postgresql
-```bash
-sudo apt-get install postgresql postgresql-client pgadmin3
-```
-[Full Guide](https://help.ubuntu.com/community/PostgreSQL)
+### 1.2 Configure shell for pyenv
 
-3. Configure the server and set password
-```bash
-sudo -u postgres psql postgres
-\password postgres
+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
 ```
 
-4. Install components to build psycopg2
-```bash
-sudo apt-get install libpq-dev python3-dev
+Reload the shell:
+
+```zsh
+exec "$SHELL"
 ```
 
-## Setup the virutal environment
-1. Create the virtual environment
-**Currently the ensurepip is broken in Python 3.4 / Ubuntu 14.04, therefore --without-pip is needed.**
-```bash
-pyvenv-3.4 env --without-pip --system-site-packages
+Verify:
+
+```zsh
+pyenv --version
 ```
 
-2. Activate the virtual environment
-```bash
-source env/bin/activate
+### 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.0
 ```
 
-3. Install pyramid, sqlachemy, psycopg2 and other dependencies:
-```bash
-python3 -m pip install pyramid waitress sqlalchemy zope.sqlalchemy psycopg2
+Set the local Python version for this project:
+
+```zsh
+pyenv local 3.14.0
+```
+
+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
+poetry completions zsh > ~/.zfunc/_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.
+
 ```
diff --git a/barker/barker/main.py b/barker/barker/main.py
index 12d91c38..d6b7dbf9 100644
--- a/barker/barker/main.py
+++ b/barker/barker/main.py
@@ -13,6 +13,7 @@ from .routers import (
     device,
     guest_book,
     header_footer,
+    health,
     login,
     menu_category,
     modifier,
@@ -117,6 +118,7 @@ app.include_router(merge_move.router, prefix="/api", tags=["voucher"])
 app.include_router(split.router, prefix="/api", tags=["voucher"])
 app.include_router(change.router, prefix="/api/voucher", tags=["voucher"])
 
+app.include_router(health.router, prefix="/health", tags=["health"])
 app.mount("/static", StaticFiles(directory="static"), name="static")
 
 
diff --git a/barker/barker/routers/health.py b/barker/barker/routers/health.py
new file mode 100644
index 00000000..4031f195
--- /dev/null
+++ b/barker/barker/routers/health.py
@@ -0,0 +1,17 @@
+from fastapi import APIRouter, HTTPException
+from sqlalchemy import text
+
+from ..db.session import SessionFuture
+
+
+router = APIRouter()
+
+
+@router.get("")
+def health_check():
+    try:
+        with SessionFuture() as db:  # lightweight DB check
+            db.execute(text("SELECT 1"))
+            return {"status": "ok", "database": "connected"}
+    except Exception as e:
+        raise HTTPException(status_code=500, detail={"status": "error", "database": str(e)}) from e