Getting started: own settings go in compose.override.yml, uv waits 120 s for a download

.gitignore

@@ -9,6 +9,7 @@ node_modules/
 # Local configuration and credentials; never committed.
 .env
 secrets/
+compose.override.yml
 
 __pycache__/
 *.py[cod]

backend/Dockerfile

@@ -32,7 +32,9 @@ FROM python:3.13-slim AS backend
 
 # Ref: https://docs.astral.sh/uv/guides/integration/docker/
 COPY --from=ghcr.io/astral-sh/uv:0.9.26 /uv /bin/
-ENV UV_COMPILE_BYTECODE=1 UV_LINK_MODE=copy
+# A slow link, such as a Raspberry Pi on WiFi, outlasts uv's default 30 s
+# download timeout.
+ENV UV_COMPILE_BYTECODE=1 UV_LINK_MODE=copy UV_HTTP_TIMEOUT=120
 
 WORKDIR /app/
 

compose.yml

@@ -3,8 +3,9 @@
 #   docker compose up -d
 #   docker compose logs fluksio    # the admin password, printed once
 #
-# then open http://localhost:8080. Change the left side of `ports` to use
-# another host port. The operator stack under docker/ is a different file.
+# then open http://localhost:8080. Put your own settings in compose.override.yml,
+# which Compose reads along with this file and git leaves alone. The operator
+# stack under docker/ is a different file.
 name: fluksio
 
 services:

docs/code/agents.md

@@ -6,7 +6,7 @@ and run flows with the permissions of the user who authorizes it.
 ## Connect an agent
 
 Set `MCP_ENABLED=true` in the engine's environment and restart it, under
-`environment` in `compose.yml` for the Docker container. It defaults to off.
+`environment` in `compose.override.yml` for the Docker container. It defaults to off.
 
 Configure your MCP client with an HTTP endpoint:
 

docs/getting-started/facility-automation.md

@@ -23,16 +23,34 @@ the admin account and its password once, on the first start. Open
 requires that superuser account.
 
 Everything runs in that one container on one port: the engine, its API and the
-dashboard. To use another port, change the left side of `ports` in
-`compose.yml`, for example `"9000:8000"`. From another machine on your network,
-open `http://<host-ip>:8080`. Set `FRONTEND_HOST` in `compose.yml` to the
-address you open, since links for wall panels and mails are built from it.
+dashboard. From another machine on your network, open `http://<host-ip>:8080`.
+
+Keep your own settings in a `compose.override.yml` next to `compose.yml`.
+Compose reads both, and `git pull` leaves your file alone. Set `FRONTEND_HOST`
+there to the address you open, since links for wall panels and mails are built
+from it:
+
+```yaml
+services:
+  fluksio:
+    environment:
+      FRONTEND_HOST: http://192.168.1.20:8080
+```
+
+Apply a change with `docker compose up -d`. To use another port, replace the
+`ports` list. Without `!override`, Compose would add the port next to 8080:
+
+```yaml
+    ports: !override
+      - "9000:8000"
+```
 
 The image starts minimal. MQTT, InfluxDB, outbound mail and the rest are
 [extras](../reference/configuration.md#image-options). Add the ones you need to
-`EXTRAS` in `compose.yml` and rebuild:
+`EXTRAS` in `compose.override.yml` and rebuild:
 
 ```yaml
+    build:
       args:
         EXTRAS: "mqtt,influx"
 ```
@@ -144,7 +162,7 @@ fluksio.example.com {
 
 Set `FRONTEND_HOST` to `https://fluksio.example.com` and `TZ` to your
 timezone, such as `Europe/Berlin`. See [Configuration](../reference/configuration.md)
-for the other settings, which go under `environment` in `compose.yml`.
+for the other settings, which go under `environment` in `compose.override.yml`.
 
 To update, pull the repository and rebuild: