Zum Hauptinhalt springen

Update Troubleshooting

"Control Plane unreachable" warning​

The Atrium instance can't reach the Control Plane at cp.atrium.sprocksystems.de.

Check:

  1. Outbound HTTPS connectivity: curl -v https://cp.atrium.sprocksystems.de/health from the server.
  2. DNS resolution: dig cp.atrium.sprocksystems.de.
  3. Proxy/firewall: Ensure outbound HTTPS to this domain is allowed.

Impact: The instance continues to operate normally during the grace period (default: 30 days). No updates are available until connectivity is restored.

Update available but not applying (notify mode)​

In notify mode, updates require manual approval:

  1. Check the admin dashboard for the update notification.
  2. Review the version information and release notes.
  3. Click Apply Update.

If you don't see the notification, check that you're logged in as a Tenant-Admin — only Tenant-Admins can approve updates.

Update failed — automatic rollback​

If the Update Agent detects that containers are unhealthy after applying an update, it automatically rolls back to the previous version:

  1. The previous Docker Compose file is restored from a local backup.
  2. docker compose up -d runs with the previous configuration.
  3. The failure is reported to the Control Plane on the next check-in.

After a rollback:

  • Check the Update Agent logs: docker logs atrium-updater.
  • Common causes: disk space exhaustion (images couldn't be pulled fully), database migration failure, or a container crash loop.
  • The failed update won't be retried automatically. Resolve the underlying issue, then trigger the update again.

Update stuck — containers in restart loop​

If containers are restarting repeatedly after an update:

  1. Check container logs: docker logs atrium-backend, docker logs atrium-frontend.
  2. Common cause: database migration failure. Check for migration errors in the backend logs.
  3. If the migration failed partway, you may need to inspect the database state and apply the migration manually, or roll back.

Manual rollback:

# Stop everything
docker compose down

# Restore the previous compose file (if the Update Agent didn't auto-rollback)
cp docker-compose.yaml.bak docker-compose.yaml

# Pull previous images and restart
docker compose pull
docker compose up -d

Can't pull images — registry authentication error​

If docker compose pull fails with authentication errors:

  1. Verify ghcr.io login: docker login ghcr.io.
  2. If the login token expired, re-authenticate with a valid token.
  3. For self-hosted deployments, the registry credentials are typically provisioned during setup. Contact support if you need new credentials.

Version mismatch between components​

All Atrium components (backend, frontend, agent) are versioned together as a platform release. If components are at different versions (e.g., backend updated but frontend didn't), you may see unexpected behavior.

Fix: Ensure all components are updated together. The Docker Compose template pins all images to the same platform version. Running docker compose pull && docker compose up -d updates everything atomically.