Improve documentation and usability of running a Tiled server

.env.example

@@ -0,0 +1,3 @@
+TILED_SINGLE_USER_API_KEY=secret
+POSTGRES_PASSWORD=secret
+REDIS_PASSWORD=secret

.gitignore

@@ -95,3 +95,7 @@ uv.lock
 # pixi environments
 .pixi/*
 !.pixi/config.toml
+
+# Do not commit overrides; these are for local changes.
+compose.override.yaml
+compose.override.yml

Containerfile

@@ -81,14 +81,16 @@ RUN set -ex && \
 
 FROM docker.io/python:${PYTHON_VERSION}-slim AS app_runtime
 ARG PYTHON_VERSION=3.12
+ARG APP_UID=999
 
 # Add the application virtualenv to search path.
 ENV PATH=/app/bin:$PATH
 
-# Don't run your app as root.
+# We will run the app as a user 'app' with a stable uid that is
+# configurable via an ARG.
 RUN set -ex && \
-groupadd -r app && \
-useradd -r -d /app -g app -N app
+    groupadd -r -g ${APP_UID} app && \
+    useradd -r -d /app -g app -u ${APP_UID} -N app
 
 # See <https://hynek.me/articles/docker-signals/>.
 STOPSIGNAL SIGINT
@@ -100,13 +102,14 @@ apt-get update -qy && \
 apt-get install -qyy \
     -o APT::Install-Recommends=false \
     -o APT::Install-Suggests=false \
-    curl && \
+    curl gosu && \
 apt-get clean && \
 rm -rf /var/lib/apt/lists/* /tmp/* /var/tmp/*
 
 RUN mkdir -p /deploy/config
-RUN mkdir -p /storage && chown -R app:app /storage
-COPY ./example_configs/single_catalog_single_user.yml /deploy/config
+# Note: the ownership of storage will be set in the entrypoint.
+RUN mkdir -p /storage
+COPY ./example_configs/config_for_containerfile.yml /deploy/config
 ENV TILED_CONFIG=/deploy/config
 
 # Copy the pre-built `/app` directory to the runtime container
@@ -118,6 +121,7 @@ COPY share/tiled/templates /app/share/tiled/templates
 # See tiled.utils.SHARE_TILED_PATH
 RUN touch /app/share/tiled/.identifying_file_72628d5f953b4229b58c9f1f8f6a9a09
 
+# Run smoke test as app so any cache files written to /app are owned by app.
 USER app
 WORKDIR /app
 
@@ -129,4 +133,11 @@ python -Ic 'import tiled'
 
 EXPOSE 8000
 
+# Switch back to root for entrypoint, which will gosu back to app
+# after ensuring that /storage is writable by the app user.
+USER root
+COPY docker-entrypoint.sh /usr/local/bin/docker-entrypoint.sh
+RUN chmod +x /usr/local/bin/docker-entrypoint.sh
+ENTRYPOINT ["docker-entrypoint.sh"]
+
 CMD ["tiled", "serve", "config", "--host", "0.0.0.0", "--port", "8000", "--scalable"]

compose.dev.yml

@@ -0,0 +1,74 @@
+---
+services:
+  tiled:
+    build:
+      context: .
+      dockerfile: Containerfile
+    environment:
+      - TILED_SINGLE_USER_API_KEY=${TILED_SINGLE_USER_API_KEY}
+      - TILED_CATALOG_URI=postgresql://tiled:${POSTGRES_PASSWORD}@postgres:5432/tiled_catalog
+      - TILED_CATALOG_WRITABLE_STORAGE=["file:///storage", "postgresql://tiled:${POSTGRES_PASSWORD}@postgres:5432/tiled_storage"]
+      - TILED_STREAMING_CACHE_URI=redis://:${REDIS_PASSWORD}@redis:6379
+    volumes:
+      - tiled_data:/storage
+    ports:
+      - 8000:8000
+    restart: unless-stopped
+    depends_on:
+      postgres:
+        condition: service_healthy
+      redis:
+        condition: service_healthy
+    networks:
+      - backend
+    healthcheck:
+      test: curl --fail http://localhost:8000/healthz || exit 1
+      interval: 60s
+      timeout: 10s
+      retries: 3
+      start_period: 30s
+
+  postgres:
+    image: docker.io/postgres:16
+    environment:
+      - POSTGRES_USER=tiled
+      - POSTGRES_PASSWORD=${POSTGRES_PASSWORD}
+      # We create two databases, 'tiled_catalog' (metadata) and
+      # 'tiled_storage' (tabular data) below. But it is required to
+      # specify one here, so we use 'postgres' as a neutral default.
+      - POSTGRES_DB=postgres
+    volumes:
+      - postgres_data:/var/lib/postgresql/data
+      - ./initdb:/docker-entrypoint-initdb.d
+    restart: unless-stopped
+    networks:
+      - backend
+    healthcheck:
+      test: pg_isready -U tiled -d postgres
+      interval: 10s
+      timeout: 5s
+      retries: 5
+      start_period: 10s
+
+  redis:
+    image: docker.io/redis:7-alpine
+    command: redis-server --requirepass ${REDIS_PASSWORD}
+    volumes:
+      - redis_data:/data
+    restart: unless-stopped
+    networks:
+      - backend
+    healthcheck:
+      test: redis-cli -a ${REDIS_PASSWORD} ping
+      interval: 10s
+      timeout: 5s
+      retries: 5
+      start_period: 5s
+
+volumes:
+  tiled_data:
+  postgres_data:
+  redis_data:
+
+networks:
+  backend: {}

docker-compose.yml → compose.monitoring.yml

@@ -1,21 +1,5 @@
+---
 services:
-  tiled:
-    image: ghcr.io/bluesky/tiled:0.2.5
-    environment:
-      - TILED_SINGLE_USER_API_KEY=${TILED_SINGLE_USER_API_KEY}
-    ports:
-      - 8000:8000
-    restart: unless-stopped
-    healthcheck:
-      test: curl --fail http://localhost:8000/healthz || exit 1
-      interval: 60s
-      timeout: 10s
-      retries: 3
-      start_period: 30s
-
-  # Below we additionally configure monitoring with Prometheus and Grafana.
-  # This is optional; it is not required for Tiled to function.
-
   prometheus:
     image: docker.io/prom/prometheus:v2.42.0
     volumes:
@@ -42,9 +26,6 @@ services:
     networks:
       - backend
     restart: unless-stopped
-
-    # Disable Grafana login screen for dev/demo.
-    # DO NOT USE THESE SETTINGS IN PRODUCTION.
     environment:
       GF_SECURITY_DISABLE_INITIAL_ADMIN_CREATION: "true"
       GF_AUTH_ANONYMOUS_ENABLED: "true"

compose.override.example.yml

@@ -0,0 +1,7 @@
+---
+services:
+  tiled:
+    environment:
+      - TILED_CONFIG=/deploy/config
+    volumes:
+      - ./my-custom-config-dir:/deploy/config:ro

compose.yml

@@ -0,0 +1,72 @@
+---
+services:
+  tiled:
+    image: ghcr.io/bluesky/tiled:0.2.8
+    environment:
+      - TILED_SINGLE_USER_API_KEY=${TILED_SINGLE_USER_API_KEY}
+      - TILED_CATALOG_URI=postgresql://tiled:${POSTGRES_PASSWORD}@postgres:5432/tiled_catalog
+      - TILED_CATALOG_WRITABLE_STORAGE=["file:///storage", "postgresql://tiled:${POSTGRES_PASSWORD}@postgres:5432/tiled_storage"]
+      - TILED_STREAMING_CACHE_URI=redis://:${REDIS_PASSWORD}@redis:6379
+    volumes:
+      - tiled_data:/storage
+    ports:
+      - 8000:8000
+    restart: unless-stopped
+    depends_on:
+      postgres:
+        condition: service_healthy
+      redis:
+        condition: service_healthy
+    networks:
+      - backend
+    healthcheck:
+      test: curl --fail http://localhost:8000/healthz || exit 1
+      interval: 60s
+      timeout: 10s
+      retries: 3
+      start_period: 30s
+
+  postgres:
+    image: docker.io/postgres:16
+    environment:
+      - POSTGRES_USER=tiled
+      - POSTGRES_PASSWORD=${POSTGRES_PASSWORD}
+      # We create two databases, 'tiled_catalog' (metadata) and
+      # 'tiled_storage' (tabular data) below. But it is required to
+      # specify one here, so we use 'postgres' as a neutral default.
+      - POSTGRES_DB=postgres
+    volumes:
+      - postgres_data:/var/lib/postgresql/data
+      - ./initdb:/docker-entrypoint-initdb.d
+    restart: unless-stopped
+    networks:
+      - backend
+    healthcheck:
+      test: pg_isready -U tiled -d postgres
+      interval: 10s
+      timeout: 5s
+      retries: 5
+      start_period: 10s
+
+  redis:
+    image: docker.io/redis:7-alpine
+    command: redis-server --requirepass ${REDIS_PASSWORD}
+    volumes:
+      - redis_data:/data
+    restart: unless-stopped
+    networks:
+      - backend
+    healthcheck:
+      test: redis-cli -a ${REDIS_PASSWORD} ping
+      interval: 10s
+      timeout: 5s
+      retries: 5
+      start_period: 5s
+
+volumes:
+  tiled_data:
+  postgres_data:
+  redis_data:
+
+networks:
+  backend: {}