From 47ee084eabe2403232d89480cb7ee93098003cc6 Mon Sep 17 00:00:00 2001 From: Lazzexus <54175295+ScuffedLazzexus@users.noreply.github.com> Date: Mon, 12 Oct 2026 18:09:03 +0200 Subject: [PATCH] Add Unraid deployment example to docs A compose file for running the Kafkatorio services on the same Unraid server as the Factorio server, via the Compose Manager plugin: - syslog ingest bound to 127.0.0.1 only (the Docker syslog log driver connects from the host), Kafka not exposed - persistent Kafka data, with a fixed cluster ID so the data survives image rebuilds - the web map is the single public entry point Co-Authored-By: Claude Opus 5.5 --- docs/guide.md | 38 ++++++++ .../unraid/docker-compose.yml | 96 +++++++++++++++++++ docs/kafkatorio-platform/unraid/example.env | 4 + 3 files changed, 138 insertions(+) create mode 100644 docs/kafkatorio-platform/unraid/docker-compose.yml create mode 100644 docs/kafkatorio-platform/unraid/example.env diff --git a/docs/guide.md b/docs/guide.md index 8fd2a94..7b9167f 100644 --- a/docs/guide.md +++ b/docs/guide.md @@ -50,3 +50,41 @@ build the project, and Docker Compose to create images. ```terminal docker-compose up -d; docker-compose logs -f ``` + +### Unraid set up + +> See [./kafkatorio-platform/unraid/docker-compose.yml](kafkatorio-platform/unraid/docker-compose.yml) + +This runs the Kafkatorio services on the same Unraid server as the Factorio server. The Docker +syslog log driver runs in the Docker daemon on the host, so the syslog port only needs to listen +on `127.0.0.1`, and Kafka isn't exposed at all. + +1. Install the *Compose Manager* plugin (or *Compose Manager Plus*) from the Apps tab. +2. Build the images locally, and copy them to Unraid (no registry needed): + + ```terminal + ./gradlew dockerComposeBuild + docker save $(docker images --format '{{.Repository}}:{{.Tag}}' | grep dev.adamko.kafkatorio) \ + | gzip | ssh root@ 'gunzip | docker load' + ``` +3. On Unraid, create `/mnt/user/appdata/kafkatorio-platform/` containing + * `.secret.kafkatorio-config.yml` (see above) + * `config/kafka-server.properties` (copy from [./kafkatorio-platform/config](kafkatorio-platform/config)) + * `config/cluster_id` - a fixed Kafka cluster ID, so the Kafka data survives image rebuilds. + Generate one with `docker run --rm --entrypoint ./bin/kafka-storage.sh random-uuid`. +4. Create a Compose Manager stack, with the Unraid `docker-compose.yml`, and + [`example.env`](kafkatorio-platform/unraid/example.env) as its `.env`. Start the stack. +5. Edit the Factorio container, enable 'Advanced View', and set 'Extra Parameters' to + + ``` + --log-driver=syslog --log-opt syslog-address=tcp://127.0.0.1:12035 --log-opt syslog-format=rfc5424 --log-opt mode=non-blocking --log-opt tag= + ``` + + Docker won't start a container if its TCP syslog server isn't reachable, so on the Docker tab + give the Factorio container an autostart 'wait' of ~30 seconds, so the Kafkatorio services start + first. +6. The web map is on port `12081`. It also proxies `/kafkatorio/` to the events server, so a + reverse proxy (e.g. Nginx Proxy Manager) only needs to forward to that one port - make sure + WebSocket support is enabled. +7. In Factorio, run `/kafkatorio prototypes` and then `/kafkatorio chunks 10` to send the existing + map. diff --git a/docs/kafkatorio-platform/unraid/docker-compose.yml b/docs/kafkatorio-platform/unraid/docker-compose.yml new file mode 100644 index 0000000..ad1ec25 --- /dev/null +++ b/docs/kafkatorio-platform/unraid/docker-compose.yml @@ -0,0 +1,96 @@ +name: kafkatorio + +services: + + ## Kafka (KRaft mode). Only reachable by the other containers. + infra-kafka: + image: ${REGISTRY_HOST}/dev.adamko.kafkatorio/kafka-kraft:${KAFKATORIO_VERSION} + container_name: kafkatorio-kafka + restart: unless-stopped + networks: + kafkatorio-nw: + aliases: [ kafka ] + volumes: + - "${APPDATA}/config/kafka-server.properties:/kafka/server.properties:ro" + # fixed cluster ID, so persisted data survives image rebuilds + - "${APPDATA}/config/cluster_id:/kafka/cluster_id:ro" + - "${APPDATA}/kafka-data:/tmp/kraft-combined-logs" + + ## Process Kafkatorio events + events-processors: + image: ${REGISTRY_HOST}/dev.adamko.kafkatorio/events-processors:${KAFKATORIO_VERSION} + container_name: kafkatorio-events-processors + restart: unless-stopped + environment: + KAFKA_BOOTSTRAP_SERVERS: "kafka:29092" + networks: [ kafkatorio-nw ] + depends_on: [ infra-kafka ] + volumes: + - "${APPDATA}/state/events-processors:/app/state" + secrets: + - source: kafkatorio_config + target: /.secret.config.yml + + ## Receives packets from the Factorio server, forwarded by the Docker syslog log driver. + ## The log driver runs in the Docker daemon on the host, so localhost-only is enough. + events-server-syslog: + image: ${REGISTRY_HOST}/dev.adamko.kafkatorio/events-server-syslog:${KAFKATORIO_VERSION} + container_name: kafkatorio-events-server-syslog + restart: unless-stopped + environment: + KAFKA_BOOTSTRAP_SERVERS: "kafka:29092" + SOCKET_SERVER_HOST: "0.0.0.0" + SOCKET_SERVER_PORT: "9002" + ports: + - "127.0.0.1:12035:9002" + networks: [ kafkatorio-nw ] + depends_on: [ infra-kafka ] + secrets: + - source: kafkatorio_config + target: /.secret.config.yml + + ## Hosts map tiles and forwards websocket messages to browsers + events-server-web: + image: ${REGISTRY_HOST}/dev.adamko.kafkatorio/events-server-web:${KAFKATORIO_VERSION} + container_name: events-server-web # web-map's nginx proxies to this hostname + restart: unless-stopped + environment: + KAFKA_BOOTSTRAP_SERVERS: "kafka:29092" + WEB_SERVER_PORT: "80" + networks: [ kafkatorio-nw ] + depends_on: [ infra-kafka ] + volumes: + - "${APPDATA}/data/events-server-web:/app/data" + - "${APPDATA}/state/events-server-web:/app/state" + secrets: + - source: kafkatorio_config + target: /.secret.config.yml + + ## Web map (also proxies /kafkatorio/ to events-server-web). Point Nginx Proxy Manager here. + web-map: + image: ${REGISTRY_HOST}/dev.adamko.kafkatorio/web-map:${KAFKATORIO_VERSION} + container_name: kafkatorio-web-map + restart: unless-stopped + ports: + - "12081:80" + networks: [ kafkatorio-nw ] + + ## Kafka admin UI - LAN/DMZ only, don't proxy this publicly + infra-kafka-ui: + image: provectuslabs/kafka-ui:v0.4.0 + container_name: kafkatorio-kafka-ui + restart: unless-stopped + ports: + - "18090:8080" + networks: [ kafkatorio-nw ] + depends_on: [ infra-kafka ] + environment: + KAFKA_CLUSTERS_0_NAME: "kafkatorio" + KAFKA_CLUSTERS_0_BOOTSTRAPSERVERS: "kafka:29092" + +secrets: + kafkatorio_config: + file: ${APPDATA}/.secret.kafkatorio-config.yml + +networks: + kafkatorio-nw: diff --git a/docs/kafkatorio-platform/unraid/example.env b/docs/kafkatorio-platform/unraid/example.env new file mode 100644 index 0000000..91620d3 --- /dev/null +++ b/docs/kafkatorio-platform/unraid/example.env @@ -0,0 +1,4 @@ +KAFKATORIO_VERSION=0.10.1 +REGISTRY_HOST=localhost +# persistent data, config, and secrets +APPDATA=/mnt/user/appdata/kafkatorio-platform