Troubleshooting
The problems that actually come up, and the one-line fix for each.
“The image could not be found”
The tag doesn't exist. Use ghcr.io/mddanishyusuf/piqo-selfhost:0. There is no :1 until a 1.0 release. If a platform asks for registry credentials, leave them blank: the image is public.
“Application failed to respond” or a 502 from the proxy
The app is running on a different port than the proxy expects. Check the log for [piqo] ready on http://0.0.0.0:<port> and make the proxy target match, or set PORT=3000 explicitly. Railway in particular injects PORT=8080 when none is defined.
Container exits immediately with “Missing required environment variables: AUTH_SECRET”
Set AUTH_SECRET to at least 32 characters. In production the app refuses to start with a shorter value.
openssl rand -base64 48“[geoip] downloading GeoLite2... error: 401” in the log
MAXMIND_LICENSE_KEY is set but not valid. The app continues without city-level geo. Fix the key or remove the variable to silence the message.
“APP_URL is not set to a public hostname” on the activation screen
Activation registers the hostname in APP_URL. Set it to the real public address (not localhost, not an IP) and restart, then try again.
“This license is already active on its maximum number of installs”
A previous install, or the same one under an old hostname, holds the slot. Remove it from your licenses page and activate again. See License & activation.
Banner says the install can't reach piqo.app
The daily check-in is failing, usually because outbound HTTPS is blocked. The dashboard keeps working for 14 days from the last success. Allow outbound traffic to piqo.app and the banner clears on the next check.
I don't see myself in Realtime
- The script URL must be your install's domain, e.g.
https://analytics.example.com/piqo.js, not piqo.app. - Open DevTools → Network and look for a request to
/api/eventon your domain. A 204 means it was accepted. - Check
data-sitematches the site key in the dashboard.
Invites and password resets don't send email
No SMTP is configured. Set SMTP_URL and EMAIL_FROM. Until then the app shows invite links for you to copy, and password resets are done by the owner from Settings → Team.
Everything vanished after a redeploy
The volume wasn't mounted at /app/data, so the database lived inside the container. Mount one and restore from a backup if you have it. See Updates & backups.
Health check
GET /api/health returns 200 when the database answers and 503 otherwise, with the build version, license state and each cron job's last run in the body. Point uptime monitors at the status code.
APP_URL.