fix(docker): start on a fresh archive folder and fix the Unraid defaults

A bind source Docker creates on demand (the compose default, a new
TITANO_ARCHIVE, the image's anonymous volume) is root-owned, so the server,
running as PUID:PGID, crash-looped with a stack trace (DOCKER-2). The
entrypoint now gives an archive mount root that user cannot write to
PUID:PGID when it is empty or owned by root (the folder only, never its
contents), and otherwise exits with a one-line error; it creates and owns
TITANO_DATA_PATH instead of a hard-coded /data (DEPLOY-1), and --help and
--healthcheck touch neither folder. The runtime image empties
ASPNETCORE_HTTP_PORTS, so Kestrel no longer warns "Overriding address(es)"
at every start (DOCKER-6).

Unraid template: the database host defaults to empty and required, since
container names do not resolve on the default bridge (SRS-08, DOCKER-3); a
Public HTTPS port variable goes with a remapped HTTPS port (DOCKER-4); the
time zone description no longer claims logs use it (DOCKER-8). Compose,
.env.example and the public README document the archive folder's owner,
public ports, trusted proxies, that LAN discovery needs host networking
(DOCKER-5), the Unraid database host, and that the Windows service
registers only from Program Files (SRS-06).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012iLMBNwBE2GnphAsu4cjaC
This commit is contained in:
Claude committed 2026-10-12 09:27:31 +00:00
1 parent 5ec59a2e96
commit 650a82a8f7
6 files changed
+69 -13

No files matched your search

+1
View File
@@ -1,5 +1,6 @@
TITANO_ADMIN_PASSWORD=change-me-at-first-login
TITANO_DB_PASSWORD=choose-a-long-random-password
# Folder of your archive, owned by PUID:PGID (an empty or root-owned folder is given to them at the first start)
TITANO_ARCHIVE=/mnt/user/Timelapse
TITANO_DATA=./data
TITANO_PGDATA=./pgdata
+3
View File
@@ -21,6 +21,8 @@ LABEL org.opencontainers.image.title="Titano Server" \
org.opencontainers.image.description="Time-lapse archive, uploads, jobs and rendering server" \
org.opencontainers.image.version="$TITANO_VERSION" \
org.opencontainers.image.licenses="LicenseRef-Titano-EULA"
# ASPNETCORE_HTTP_PORTS is emptied: the server binds its own ports, and the base image's 8080 only made Kestrel warn
# "Overriding address(es)" at every start.
ENV TITANO_ARCHIVE_PATH=/archive \
TITANO_DATA_PATH=/data \
TITANO_HTTP_PORT=8080 \
@@ -28,6 +30,7 @@ ENV TITANO_ARCHIVE_PATH=/archive \
TITANO_DB=postgres \
PUID=1000 \
PGID=1000 \
ASPNETCORE_HTTP_PORTS= \
DOTNET_gcServer=1 \
DOTNET_GCHeapAffinitizeMask= \
DOTNET_NOLOGO=1
+8
View File
@@ -8,6 +8,9 @@ services:
depends_on:
postgres:
condition: service_healthy
# Publishing a port as another host port ("18443:8443")? Set TITANO_PUBLIC_HTTPS_PORT (and _HTTP_PORT) below to the
# host port. LAN discovery reaches clients only with "network_mode: host" (then drop "ports"); on this bridge
# network clients add the server by its address.
ports:
- "8080:8080"
- "8443:8443"
@@ -20,7 +23,10 @@ services:
TITANO_DB_NAME: titano
TITANO_DB_USER: titano
TITANO_DB_PASSWORD: ${TITANO_DB_PASSWORD:?set TITANO_DB_PASSWORD in .env}
# auto (self-signed), pem or proxy; behind a proxy, TITANO_TRUSTED_PROXIES lists its address if it is not on a
# private network
TITANO_TLS_MODE: auto
# TITANO_PUBLIC_HTTPS_PORT: "8443"
TITANO_SERVER_NAME: Titano Server
# Trace, Debug, Information, Warning or Error
TITANO_LOG_LEVEL: Information
@@ -28,6 +34,8 @@ services:
PGID: ${PGID:-1000}
TZ: ${TZ:-UTC}
volumes:
# The archive folder should belong to PUID:PGID; an empty or root-owned one is given to them at start (the folder
# only, never its contents).
- ${TITANO_ARCHIVE:-./archive}:/archive
- ${TITANO_DATA:-./data}:/data
+28 -6
View File
@@ -1,17 +1,39 @@
#!/bin/sh
# Runs Titano Server as PUID:PGID (Unraid/NAS convention). /data is owned by that user; /archive is left as
# mounted (it may hold terabytes) and only checked for write access.
# Runs Titano Server as PUID:PGID (Unraid/NAS convention). The data folder is owned by that user. The archive is left
# as mounted (it may hold terabytes) and only checked for write access; only when that user cannot write it and the
# folder is empty or owned by root (Docker creates a missing bind source or a fresh volume that way) is the folder
# itself, never its contents, given to PUID:PGID.
set -eu
PUID="${PUID:-1000}"
PGID="${PGID:-1000}"
DATA="${TITANO_DATA_PATH:-/data}"
ARCHIVE="${TITANO_ARCHIVE_PATH:-/archive}"
umask 002
# Help and the health probe touch neither folder.
case "${1:-}" in
--help | -h | -\? | /\? | --healthcheck) exec dotnet /app/Titano.Server.dll "$@" ;;
esac
as_user() {
setpriv --reuid="$PUID" --regid="$PGID" --clear-groups -- "$@"
}
if [ "$(id -u)" = "0" ]; then
mkdir -p /data
chown -R "$PUID:$PGID" /data
if ! setpriv --reuid="$PUID" --regid="$PGID" --clear-groups -- test -w "${TITANO_ARCHIVE_PATH:-/archive}"; then
echo "warning: ${TITANO_ARCHIVE_PATH:-/archive} is not writable by $PUID:$PGID" >&2
mkdir -p "$DATA" "$ARCHIVE"
chown -R "$PUID:$PGID" "$DATA"
if ! as_user test -w "$ARCHIVE"; then
if [ -z "$(ls -A "$ARCHIVE")" ] || [ "$(stat -c %u "$ARCHIVE")" = "0" ]; then
owner="$(stat -c %u:%g "$ARCHIVE")"
if chown "$PUID:$PGID" "$ARCHIVE" 2>/dev/null; then
echo "titano: $ARCHIVE belonged to $owner; it now belongs to $PUID:$PGID (the folder only, not its contents)"
fi
fi
if ! as_user test -w "$ARCHIVE"; then
echo "error: $ARCHIVE is not writable by $PUID:$PGID; give that user write access to the archive folder on the host, or set PUID and PGID to its owner" >&2
exit 1
fi
fi
exec setpriv --reuid="$PUID" --regid="$PGID" --clear-groups -- dotnet /app/Titano.Server.dll "$@"
fi
+25 -4
View File
@@ -64,6 +64,10 @@ curl -L -o .env https://raw.githubusercontent.com/alby96/titano-releases/main/do
docker compose up -d
```
Create the archive folder owned by `PUID:PGID` first (for example `mkdir -p <folder> && chown 1000:1000 <folder>`). An
empty folder, or one owned by root (as Docker creates a missing one), is given to `PUID:PGID` at start: the folder
itself, never its contents. Any other folder that user cannot write stops the container with a one-line error.
Open `http://<host>:8080/admin`, sign in as `admin` with the password from `.env` and choose a new one. Titano
clients connect to `https://<host>:8443`; the first connection shows the server's certificate fingerprint, which the
admin panel shows under Settings so you can compare them.
@@ -75,6 +79,15 @@ admin panel shows under Settings so you can compare them.
- Upgrade: `docker compose pull && docker compose up -d`. Jobs in progress resume from their last checkpoint.
- All settings: environment variables `TITANO_*` (see `docker-compose.yml`) or `/data/server.json`. Run
`docker run --rm ghcr.io/alby96/titano-server:latest --help` for the list.
- Other host ports: when you publish the container's ports as other host ports (`18443:8443`), set
`TITANO_PUBLIC_HTTPS_PORT` (and `TITANO_PUBLIC_HTTP_PORT`) to the host ports, so the admin panel's redirect to HTTPS
and LAN discovery name the ports clients can reach.
- LAN discovery (`TITANO_DISCOVERY`, on by default) needs host networking (`network_mode: host` in compose, Network
type *Host* on Unraid): on a bridge network its broadcasts never leave the container's network. Without it, add the
server in Titano by its address.
- Behind a reverse proxy (`TITANO_TLS_MODE=proxy`), only the proxies listed in `TITANO_TRUSTED_PROXIES` may set
`X-Forwarded-*` headers (default: loopback and the private networks 10/8, 172.16/12, 192.168/16, fc00::/7). The admin
panel shows *Not via proxy* when a page did not come through a trusted proxy over HTTPS.
## Titano Server on Unraid
@@ -82,18 +95,26 @@ admin panel shows under Settings so you can compare them.
role `titano` (for example with `docker exec -it postgresql17 psql -U postgres -c "CREATE ROLE titano LOGIN
PASSWORD '…'" -c "CREATE DATABASE titano OWNER titano"`).
2. In Docker › *Template repositories* add `https://github.com/alby96/titano-releases` and save.
3. Docker › *Add container* › Template `titano-server`. Set the admin password, the database host (the PostgreSQL
container's name or IP), password and the archive share (default `/mnt/user/Timelapse`).
3. Docker › *Add container* › Template `titano-server`. Set the admin password, the database host, password and the
archive share (default `/mnt/user/Timelapse`). The database host is the Unraid server's IP address (the PostgreSQL
template publishes port 5432): container names resolve only when both containers are on the same custom Docker
network, not on the default *bridge*. If you change the HTTPS port, enter the same port in *Public HTTPS port*.
4. Open the WebUI (`http://[IP]:8080/admin`).
The template file is [`unraid/titano.xml`](unraid/titano.xml).
## Titano Server on Windows
Unpack `Titano-Server-win-x64-<version>.zip` (or choose the *Server* component in the setup). It uses SQLite in
Choose the *Server* component in the setup, or unpack `Titano-Server-win-x64-<version>.zip`. It uses SQLite in
`C:\ProgramData\Titano Server` by default, or PostgreSQL with `TITANO_DB=postgres` and the `TITANO_DB_*` variables.
The data folder is readable only by the server's account, SYSTEM and Administrators; without `TITANO_ADMIN_PASSWORD`
the first start writes a temporary admin password to `initial-admin-password.txt` there (open it from an
administrator prompt).
Run `Titano.Server.exe` in a console, or install it as a Windows service from an administrator prompt with
`Titano.Server.exe --install-service` (remove it with `--uninstall-service`).
`Titano.Server.exe --install-service` (remove it with `--uninstall-service`). The service runs as LocalSystem, so it
registers only from a copy inside `Program Files` that only administrators can change: install for *All users*, or
unpack the zip into a folder under `Program Files`.
## Translations
+4 -3
View File
@@ -22,12 +22,13 @@
<DonateLink/>
<Requires>A PostgreSQL 16 or 17 container (official "postgres" template) with a database and user for Titano.</Requires>
<Config Name="HTTP port" Target="8080" Default="8080" Mode="tcp" Description="Admin panel and API over HTTP." Type="Port" Display="always" Required="true" Mask="false">8080</Config>
<Config Name="HTTPS port" Target="8443" Default="8443" Mode="tcp" Description="API over TLS for Titano clients." Type="Port" Display="always" Required="true" Mask="false">8443</Config>
<Config Name="HTTPS port" Target="8443" Default="8443" Mode="tcp" Description="API over TLS for Titano clients. When you change it, enter the same port in Public HTTPS port." Type="Port" Display="always" Required="true" Mask="false">8443</Config>
<Config Name="Public HTTPS port" Target="TITANO_PUBLIC_HTTPS_PORT" Default="" Mode="" Description="The HTTPS port above, when it is not 8443; the admin panel redirects there." Type="Variable" Display="always" Required="false" Mask="false"/>
<Config Name="Archive" Target="/archive" Default="/mnt/user/Timelapse" Mode="rw" Description="Originals, sidecars, proxies and renders." Type="Path" Display="always" Required="true" Mask="false">/mnt/user/Timelapse</Config>
<Config Name="App data" Target="/data" Default="/mnt/user/appdata/titano" Mode="rw" Description="Settings, TLS certificate, uploads in progress and logs." Type="Path" Display="always" Required="true" Mask="false">/mnt/user/appdata/titano</Config>
<Config Name="Admin user" Target="TITANO_ADMIN_USER" Default="admin" Mode="" Description="Created at first start when no administrator exists." Type="Variable" Display="always" Required="true" Mask="false">admin</Config>
<Config Name="Admin password" Target="TITANO_ADMIN_PASSWORD" Default="" Mode="" Description="Initial password; a change is required at first sign-in." Type="Variable" Display="always" Required="true" Mask="true"/>
<Config Name="Database host" Target="TITANO_DB_HOST" Default="postgresql17" Mode="" Description="Host name or IP of the PostgreSQL container." Type="Variable" Display="always" Required="true" Mask="false">postgresql17</Config>
<Config Name="Database host" Target="TITANO_DB_HOST" Default="" Mode="" Description="IP address of the Unraid server (PostgreSQL's port mapped), or the PostgreSQL container's name when both containers are on the same custom network; names do not resolve on bridge." Type="Variable" Display="always" Required="true" Mask="false"/>
<Config Name="Database port" Target="TITANO_DB_PORT" Default="5432" Mode="" Description="PostgreSQL port." Type="Variable" Display="advanced" Required="true" Mask="false">5432</Config>
<Config Name="Database name" Target="TITANO_DB_NAME" Default="titano" Mode="" Description="Database owned by the Titano user." Type="Variable" Display="always" Required="true" Mask="false">titano</Config>
<Config Name="Database user" Target="TITANO_DB_USER" Default="titano" Mode="" Description="PostgreSQL role." Type="Variable" Display="always" Required="true" Mask="false">titano</Config>
@@ -38,5 +39,5 @@
<Config Name="Log level" Target="TITANO_LOG_LEVEL" Default="Information" Mode="" Description="Trace, Debug, Information, Warning or Error." Type="Variable" Display="advanced" Required="false" Mask="false">Information</Config>
<Config Name="PUID" Target="PUID" Default="99" Mode="" Description="User id that owns files." Type="Variable" Display="advanced" Required="true" Mask="false">99</Config>
<Config Name="PGID" Target="PGID" Default="100" Mode="" Description="Group id that owns files." Type="Variable" Display="advanced" Required="true" Mask="false">100</Config>
<Config Name="Time zone" Target="TZ" Default="Europe/Rome" Mode="" Description="Time zone of logs and schedules." Type="Variable" Display="advanced" Required="false" Mask="false">Europe/Rome</Config>
<Config Name="Time zone" Target="TZ" Default="Europe/Rome" Mode="" Description="Local time used to name folders of photos without a capture time; logs stay in UTC." Type="Variable" Display="advanced" Required="false" Mask="false">Europe/Rome</Config>
</Container>