fix(deploy): stop on unwritable .titano folders and document proxies and host networking

- Entrypoint: an existing .titano folder or subfolder that PUID:PGID cannot
  write stops the container with a one-line error instead of a restart loop;
  it is never chowned.
- Compose and README: with network_mode host, publish PostgreSQL on loopback
  and set TITANO_DB_HOST to 127.0.0.1; behind a proxy, list it in
  TITANO_TRUSTED_PROXIES (loopback only by default). Unraid template gains a
  Trusted proxies variable.
- README: what the Windows server requires of its data folder and archive.

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 11:08:12 +00:00
1 parent df2d4b4316
commit 23f43a505e
4 files changed
+25 -8

No files matched your search

+6 -4
View File
@@ -9,8 +9,9 @@ services:
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.
# host port. LAN discovery reaches clients only with "network_mode: host"; on this bridge network clients add the
# server by its address. With host networking drop "ports", give the postgres service
# ports: ["127.0.0.1:5432:5432"] and set TITANO_DB_HOST to 127.0.0.1: the name "postgres" no longer resolves there.
ports:
- "8080:8080"
- "8443:8443"
@@ -23,9 +24,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
# auto (self-signed), pem or proxy; behind a proxy, set TITANO_TRUSTED_PROXIES to its address or network (for a
# proxy container on this network, the network's subnet; only loopback is trusted otherwise)
TITANO_TLS_MODE: auto
# TITANO_TRUSTED_PROXIES: "172.18.0.0/16"
# TITANO_PUBLIC_HTTPS_PORT: "8443"
TITANO_SERVER_NAME: Titano Server
# Trace, Debug, Information, Warning or Error
+8
View File
@@ -35,6 +35,14 @@ if [ "$(id -u)" = "0" ]; then
exit 1
fi
fi
# The server writes into the archive's .titano folders at once (staging, trash, locks); one left to root by an
# earlier run as root, or copied in by root, would stop it in a restart loop. Reported, never chowned.
for dir in "$ARCHIVE/.titano" "$ARCHIVE/.titano"/*/; do
if [ -d "$dir" ] && ! as_user test -w "$dir"; then
echo "error: ${dir%/} is not writable by $PUID:$PGID; give that user write access to it on the host (for example chown -R $PUID:$PGID <archive>/.titano)" >&2
exit 1
fi
done
exec setpriv --reuid="$PUID" --regid="$PGID" --clear-groups -- dotnet /app/Titano.Server.dll "$@"
fi
+10 -4
View File
@@ -84,10 +84,14 @@ admin panel shows under Settings so you can compare them.
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.
server in Titano by its address. With `network_mode: host` the name `postgres` no longer resolves: remove the
`ports` of the `titano` service, publish PostgreSQL on loopback (`ports: ["127.0.0.1:5432:5432"]` under `postgres`)
and set `TITANO_DB_HOST: 127.0.0.1`.
- 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.
`X-Forwarded-*` headers. By default that is loopback only: other machines on your network reach the HTTP port
directly, so they must not choose the address the sign-in limit and the audit log see. List your proxy's address,
or the subnet of the Docker network it shares with Titano (for example `172.18.0.0/16`). The admin panel shows *Not
via proxy* when a page did not come through a trusted proxy over HTTPS.
## Titano Server on Unraid
@@ -109,7 +113,9 @@ Choose the *Server* component in the setup, or unpack `Titano-Server-win-x64-<ve
`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).
administrator prompt). Everything in it must belong to those accounts and nothing in it may be a link: otherwise the
server does not start and names the file to check. A new archive folder (default `C:\TitanoArchive`) can be changed
only by those accounts and read by other users; when other users can change an existing archive, the log says so.
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`). The service runs as LocalSystem, so it
+1
View File
@@ -35,6 +35,7 @@
<Config Name="Database password" Target="TITANO_DB_PASSWORD" Default="" Mode="" Description="PostgreSQL password." Type="Variable" Display="always" Required="true" Mask="true"/>
<Config Name="Database TLS" Target="TITANO_DB_SSLMODE" Default="prefer" Mode="" Description="disable, prefer, require or verify-full." Type="Variable" Display="advanced" Required="false" Mask="false">prefer</Config>
<Config Name="TLS mode" Target="TITANO_TLS_MODE" Default="auto" Mode="" Description="auto (self-signed), pem (own certificate) or proxy (behind a reverse proxy)." Type="Variable" Display="advanced" Required="false" Mask="false">auto</Config>
<Config Name="Trusted proxies" Target="TITANO_TRUSTED_PROXIES" Default="" Mode="" Description="TLS mode proxy: IP address or network of your reverse proxy (for example 172.17.0.0/16); only loopback is trusted otherwise." Type="Variable" Display="advanced" Required="false" Mask="false"/>
<Config Name="Server name" Target="TITANO_SERVER_NAME" Default="Titano Server" Mode="" Description="Name shown to clients." Type="Variable" Display="advanced" Required="false" Mask="false">Titano Server</Config>
<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>