Troubleshooting

Image pull reports `manifest unknown`

Confirm that the v1.0.0 Release has been published and that .env contains the immutable production tag:

CONDUCTOR_IMAGE=gitea.skeletonworks.online/vwiebe/conductor
CONDUCTOR_VERSION=v1.0.0

Do not substitute latest. The production release must pull anonymously; if the registry requests a login after publication, report a release-distribution failure rather than adding private credentials to the installation.

Image pull reports no matching platform

The v1.0.0 production image supports Linux/AMD64 only. Confirm uname -m reports x86_64. ARM64 is not a supported v1.0.0 target.

Container exits immediately

Inspect logs. Production intentionally refuses to start when CONDUCTOR_SECRET_KEY is not a valid 32-byte base64/hex value or CONDUCTOR_SESSION_KEY is shorter than 32 bytes.

Container is unhealthy

docker compose --env-file .env -f compose.production.yml ps
docker compose --env-file .env -f compose.production.yml logs --tail=200 conductor
curl -v http://127.0.0.1:8080/api/health

Confirm /data is writable by UID/GID 10001. Restore tooling resets database ownership to 10001:10001 and mode 0600.

Production cookies are marked Secure. Use the final https:// hostname, not a plain-HTTP server IP or hostname. The loopback HTTP endpoint exists for host health checks.

Stored credential no longer works after restore

The restored database and CONDUCTOR_SECRET_KEY likely do not match. Restore the complete archive, including its .env/.secrets. Credential encryption cannot be bypassed or recovered without the original key.

Published deep link returns proxy 404

The reverse proxy must send all non-API paths to Conductor rather than serving static files independently. Test the container directly at /apps/<app>/<page> and use the Caddy/NGINX examples in docs/INSTALL.md.

REST request is blocked

Read the safe error code and docs/PROXY_SECURITY.md. Private/internal destinations are denied unless their exact origin is configured in CONDUCTOR_PROXY_INTERNAL_ORIGINS. Do not add broad exceptions.

Browser shows old controls after upgrade

Confirm the running image tag/digest, then perform a hard browser refresh. The production index.html is sent with no-cache; hashed assets may be cached safely.

Backup refuses to run

The application container must be running and the environment file must exist because it contains recovery keys. Check Compose project selection and paths. SkeletonWorks commands require the exact --fqdn used during setup.

2.6 KiB Raw Blame History