From 66543b75d4af6a434ca5bad733fa9ee13d648dec Mon Sep 17 00:00:00 2001
From: simon <simon.kruecken@web.de>
Date: Tue, 26 May 2026 17:12:32 +0200
Subject: [PATCH] Added Readme with install instructions

---
 README.md | 107 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 107 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..977ea92
--- /dev/null
+++ b/README.md
@@ -0,0 +1,107 @@
+# Alox printer backend
+
+HTTP backend and admin UI for managing print plates, item SVG templates, layout configurations, and PDF previews.
+
+## Requirements
+
+| Requirement | Required for | Notes |
+|-------------|--------------|-------|
+| **Go 1.26+** | Build and run | See `go.mod` for the exact toolchain version. |
+| **`rsvg-convert`** | PDF export only | Part of [librsvg](https://wiki.gnome.org/Projects/LibRsvg). The server starts without it; PDF endpoints return an error until it is installed and on `PATH`. |
+
+### Installing `rsvg-convert`
+
+Examples:
+
+```bash
+# Debian / Ubuntu
+sudo apt install librsvg2-bin
+
+# Fedora
+sudo dnf install librsvg2-tools
+
+# Arch / Manjaro
+sudo pacman -S librsvg
+
+# macOS (Homebrew)
+brew install librsvg
+```
+
+Verify:
+
+```bash
+rsvg-convert --version
+```
+
+## Build
+
+From the repository root:
+
+```bash
+go build -o printer-backend .
+```
+
+## Run
+
+Start the API and admin servers from the **repository root** (or any directory where you want the `data/` folder to live):
+
+```bash
+./printer-backend serve
+```
+
+Defaults (no config file):
+
+- **API:** `http://127.0.0.1:8080`
+- **Admin dashboard:** `http://127.0.0.1:8081`
+
+Stop with `Ctrl+C`.
+
+### Optional configuration
+
+Copy `config.example.json` and pass it with `--config`:
+
+```bash
+cp config.example.json config.json
+./printer-backend serve --config config.json
+```
+
+| Field | Default | Description |
+|-------|---------|-------------|
+| `host` | `127.0.0.1` | Bind address for both servers |
+| `api_port` | `8080` | REST API port |
+| `admin_port` | `8081` | Admin UI port |
+
+Legacy field `port` is still accepted and maps to `api_port` when `api_port` is unset.
+
+## Data directory
+
+All runtime data is stored under `data/` relative to the **current working directory**:
+
+```
+data/
+  plates/           # plate definitions (JSON)
+  svg_template/     # item SVG files and metadata
+  configurations/   # plate + item + spacing presets (JSON)
+```
+
+Directories are created automatically when you save plates, items, or configurations. Run `serve` from the project root if you want to use the bundled sample data.
+
+## Other commands
+
+```bash
+# Print version
+./printer-backend version
+
+# Generate a square SVG item template (writes to data/svg_template/)
+./printer-backend template -o my_item.svg -s 80 -b 2 -m 5 -p 3
+```
+
+## Quick check
+
+After starting the server:
+
+```bash
+curl -s http://127.0.0.1:8080/health
+```
+
+Open the admin UI in a browser at `http://127.0.0.1:8081`.