Improve Podman Compose service discovery

.env.example

@@ -14,7 +14,8 @@
 APP_URL=http://localhost:8080
 
 # ── Database ─────────────────────────────────────────────────────────────────
-# DB_HOST must match the Compose service name (default: "db"). Do not change.
+# DB_HOST must resolve inside the Compose network. Default: "db".
+# If your Podman Compose setup cannot resolve "db", use "totpvault-db".
 DB_HOST=db
 DB_PORT=3306
 DB_NAME=totpvault
@@ -72,6 +73,8 @@ KEYCLOAK_SCOPE=openid email profile
 # KEYCLOAK_CLIENT_ID=totpvault
 # KEYCLOAK_CLIENT_SECRET=totpvault-dev-secret
 # KEYCLOAK_BASE_URL=http://localhost:8081
+# If your Podman Compose setup cannot resolve "keycloak", use
+# http://totpvault-keycloak:8080 instead.
 # KEYCLOAK_INTERNAL_BASE_URL=http://keycloak:8080
 # KEYCLOAK_REALM=totpvault
 # KEYCLOAK_REDIRECT_URI=http://localhost:8080/auth/callback/keycloak

README.md

@@ -515,6 +515,8 @@ docker compose up -d --build
 - Check that the `db` container is healthy: `docker compose ps`
 - Verify `DB_USER`, `DB_PASSWORD`, and `DB_NAME` match between the app and db service.
 - The app waits for the db healthcheck before starting (`depends_on: condition: service_healthy`).
+- If you use Podman Compose and see `getaddrinfo for db failed`, verify service DNS inside the app container: `podman exec totpvault-app getent hosts db`
+- If `db` does not resolve in Podman Compose, set `DB_HOST=totpvault-db`, restart the stack, and use `KEYCLOAK_INTERNAL_BASE_URL=http://totpvault-keycloak:8080` for the optional local Keycloak container.
 
 **Access denied for user — after changing `.env` passwords**
 - MariaDB only applies `MYSQL_USER`/`MYSQL_PASSWORD` on a **fresh** (empty) data volume. If the volume already exists with different credentials, the new values are ignored.

docker-compose.yml

@@ -54,7 +54,10 @@ services:
       db:
         condition: service_healthy
     networks:
-      - totpvault-net
+      totpvault-net:
+        aliases:
+          - app
+          - totpvault-app
     healthcheck:
       test: ["CMD", "curl", "-f", "-s", "-o", "/dev/null", "http://localhost:80/"]
       interval: 30s
@@ -82,7 +85,10 @@ services:
       - ./docker/keycloak/totpvault-realm.json:/opt/keycloak/data/import/totpvault-realm.json:ro
       - totpvault-keycloak-data:/opt/keycloak/data
     networks:
-      - totpvault-net
+      totpvault-net:
+        aliases:
+          - keycloak
+          - totpvault-keycloak
     healthcheck:
       test:
         [
@@ -115,7 +121,10 @@ services:
     # ports:
     #   - "3306:3306"
     networks:
-      - totpvault-net
+      totpvault-net:
+        aliases:
+          - db
+          - totpvault-db
     healthcheck:
       test: ["CMD", "healthcheck.sh", "--connect", "--innodb_initialized"]
       interval: 10s