Victor Wiebe
498003f83d
Some checks failed
Release production image / production-image (push) Has been cancelled
55 lines
2.6 KiB
Markdown
55 lines
2.6 KiB
Markdown
# Troubleshooting
|
|
|
|
## Image pull reports `manifest unknown`
|
|
|
|
Confirm that the `v1.0.0` Release has been published and that `.env` contains the immutable production tag:
|
|
|
|
```dotenv
|
|
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
|
|
|
|
```bash
|
|
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`.
|
|
|
|
## Setup or login does not persist in the browser
|
|
|
|
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.
|