From 030b0afb24d659eb21b4a6f633b41db0307be524 Mon Sep 17 00:00:00 2001
From: Arkadiy Kukarkin <parkan@gmail.com>
Date: Thu, 28 May 2026 13:00:02 +0200
Subject: [PATCH] add docker compose with persistent redis

---
 .env.example       | 17 +++++++++++++++++
 .gitignore         |  1 +
 README.md          | 34 +++++++++++++++++++---------------
 docker-compose.yml | 37 +++++++++++++++++++++++++++++++++++++
 4 files changed, 74 insertions(+), 15 deletions(-)
 create mode 100644 .env.example
 create mode 100644 docker-compose.yml

diff --git a/.env.example b/.env.example
new file mode 100644
index 0000000..e4c4832
--- /dev/null
+++ b/.env.example
@@ -0,0 +1,17 @@
+# copy to .env and fill in, then: docker compose up -d
+
+# required: bcrypt hash. generate with:
+#   htpasswd -nbBC 10 "" 'your-password' | tr -d ':\n'
+HAUK_PASSWORD_HASH=
+
+# public url used in generated share links
+HAUK_PUBLIC_URL=http://localhost:8080/
+
+# max share lifetime in seconds (redis key TTL)
+HAUK_MAX_DURATION=86400
+
+# trust X-Forwarded-For; set true only when behind a reverse proxy
+HAUK_TRUST_PROXY=false
+
+# redis persistence: on => survives restart, off => in-memory only
+REDIS_PERSIST=on
diff --git a/.gitignore b/.gitignore
index c081dcb..28b6adb 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1 +1,2 @@
 hauk
+.env
diff --git a/README.md b/README.md
index e44c333..8af65ba 100644
--- a/README.md
+++ b/README.md
@@ -16,26 +16,29 @@ The original PHP implementation works fine but has some overhead. This port prov
 
 ## usage
 
+run go-hauk and redis together with docker compose:
+
 ```
-# create network
-docker network create hauk
-
-# start redis
-docker run -d --name redis --network hauk redis:alpine
-
-# generate password hash
+# generate a password hash
 export HAUK_PASSWORD_HASH=$(htpasswd -nbBC 10 "" 'your-password' | tr -d ':\n')
 
-# start hauk
-docker run -d --name hauk \
-  --network hauk \
-  -p 8080:8080 \
-  -e HAUK_AUTH_METHOD=password \
-  -e HAUK_PASSWORD_HASH \
-  -e HAUK_REDIS_ADDR=redis:6379 \
-  ghcr.io/parkan/go-hauk
+docker compose up -d
 ```
 
+or copy `.env.example` to `.env`, fill it in, and `docker compose up -d`.
+
+### persistence
+
+share data (sessions, links, locations) lives in redis with a per-share TTL
+(`HAUK_MAX_DURATION`, default 24h). the bundled redis persists to a named volume
+by default, so restarts and redeploys keep active shares alive. set
+`REDIS_PERSIST=off` for in-memory only -- faster, but every share is lost on
+restart.
+
+### deploy on railway
+
+use the **Deploy on Railway** button above.
+
 ## config
 
 all config via environment variables:
@@ -47,6 +50,7 @@ all config via environment variables:
 | HAUK_REDIS_ADDR | localhost:6379 | redis address (host:port or redis:// url) |
 | HAUK_AUTH_METHOD | password | auth method (password, htpasswd, ldap) |
 | HAUK_PASSWORD_HASH | | bcrypt hash for password auth |
+| HAUK_MAX_DURATION | 86400 | max share lifetime in seconds (redis key TTL) |
 | HAUK_RATE_LIMIT_AUTH | 10 | max auth requests per minute per ip |
 | HAUK_RATE_LIMIT_ADOPT | 10 | max adopt requests per minute per ip |
 | HAUK_TRUST_PROXY | true | trust X-Forwarded-For (set false if not behind proxy) |
diff --git a/docker-compose.yml b/docker-compose.yml
new file mode 100644
index 0000000..e15d049
--- /dev/null
+++ b/docker-compose.yml
@@ -0,0 +1,37 @@
+services:
+  hauk:
+    image: ghcr.io/parkan/go-hauk
+    ports:
+      - "8080:8080"
+    environment:
+      HAUK_REDIS_ADDR: redis:6379
+      HAUK_AUTH_METHOD: password
+      HAUK_PASSWORD_HASH: "${HAUK_PASSWORD_HASH:?set HAUK_PASSWORD_HASH, see README}"
+      HAUK_PUBLIC_URL: "${HAUK_PUBLIC_URL:-http://localhost:8080/}"
+      HAUK_MAX_DURATION: "${HAUK_MAX_DURATION:-86400}"
+      HAUK_TRUST_PROXY: "${HAUK_TRUST_PROXY:-false}"
+    depends_on:
+      redis:
+        condition: service_healthy
+    restart: unless-stopped
+
+  redis:
+    image: redis:alpine
+    # REDIS_PERSIST=off => in-memory only; default persists to the volume below
+    command:
+      - sh
+      - -c
+      - '[ "$$REDIS_PERSIST" = off ] && exec redis-server --save "" --appendonly no || exec redis-server --appendonly yes'
+    environment:
+      REDIS_PERSIST: "${REDIS_PERSIST:-on}"
+    volumes:
+      - redis-data:/data
+    healthcheck:
+      test: ["CMD", "redis-cli", "ping"]
+      interval: 5s
+      timeout: 3s
+      retries: 5
+    restart: unless-stopped
+
+volumes:
+  redis-data: