From 07f4d10bd6b7eb0f7566fc7f8c9db27e5eb15b6e Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Katariina=20J=C3=A4rvenm=C3=A4ki?=
 <katariina.jarvenmaki@proton.me>
Date: Sat, 4 Apr 2026 10:15:17 +0300
Subject: [PATCH] Add local installation guide in docs/install.md

---
 docs/install.md | 87 +++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 87 insertions(+)
 create mode 100644 docs/install.md

diff --git a/docs/install.md b/docs/install.md
new file mode 100644
index 0000000..b8b6d2b
--- /dev/null
+++ b/docs/install.md
@@ -0,0 +1,87 @@
+# Local Setup (without Docker)
+
+If you prefer not to use Docker, you can install Tampio's dependencies natively. The tricky part is libvoikko and the Finnish morphological dictionary — the Docker path handles all of this for you, so that's recommended if you just want to try the examples.
+
+## Prerequisites
+
+- Python 3.8+
+- [libvoikko](https://voikko.puimula.org/) — Finnish morphology library
+- `python3-libvoikko` — Python bindings for libvoikko
+- fi-x-morpho dictionary — the specific Finnish dictionary Tampio requires
+
+## Ubuntu / Debian
+
+```sh
+# Install libvoikko, Python bindings, and the base voikko-fi package
+sudo apt-get update
+sudo apt-get install -y libvoikko-dev voikko-fi python3 python3-libvoikko curl unzip
+
+# Download the fi-x-morpho dictionary (not available via apt)
+# This installs it system-wide; alternatively unzip to ~/.voikko/
+curl -fsSL https://www.puimula.org/htp/testing/voikko-snapshot-v5/dict-morpho.zip \
+    -o /tmp/dict-morpho.zip
+sudo unzip /tmp/dict-morpho.zip -d /usr/lib/voikko
+rm /tmp/dict-morpho.zip
+```
+
+> **Note:** The `voikko-fi` apt package only ships `mor-standard`. Tampio requires the `fi-x-morpho` variant, which is why the manual download step is needed.
+
+## macOS
+
+Install voikko via Homebrew:
+
+```sh
+brew install libvoikko
+pip3 install libvoikko
+```
+
+Then download the dictionary manually:
+
+```sh
+mkdir -p ~/.voikko
+curl -fsSL https://www.puimula.org/htp/testing/voikko-snapshot-v5/dict-morpho.zip \
+    -o /tmp/dict-morpho.zip
+unzip /tmp/dict-morpho.zip -d ~/.voikko
+rm /tmp/dict-morpho.zip
+```
+
+> macOS compatibility is not officially tested — if you run into issues, Docker is the reliable fallback.
+
+## Install Tampio
+
+Tampio is not on PyPI. Clone it directly from GitHub:
+
+```sh
+git clone https://github.com/fergusq/tampio.git
+```
+
+Optionally add a wrapper so you can call `tampio` from anywhere:
+
+```sh
+echo '#!/bin/sh\npython3 /path/to/tampio/tampio.py "$@"' > /usr/local/bin/tampio
+chmod +x /usr/local/bin/tampio
+```
+
+## Verify
+
+```sh
+echo 'Kun nykyinen sivu avautuu, teksti "Hei!" näytetään käyttäjälle.' \
+    | python3 tampio/tampio.py /dev/stdin
+```
+
+If you see HTML output, the setup is working.
+
+## Build the Examples
+
+From the Tampiorama root:
+
+```sh
+# Override the Docker command with a direct tampio call
+make TAMPIO="python3 /path/to/tampio/tampio.py -i -p"
+```
+
+Or compile manually:
+
+```sh
+python3 /path/to/tampio/tampio.py -i -p examples/basics/hello.itp > examples/basics/hello.html
+```