Start with the smallest check that explains the problem. Do not reset or reinstall before you understand whether the issue is service health, DNS, license state, backup storage or user access.

Most DCIM host diagnostics start with dcimctl status. Run it before collecting logs or changing services.

First checks

dcimctl status
dcimctl license
systemctl is-active dcim-license-sync.timer

Dashboard is not opening

Confirm that the core services are running and then inspect the service logs. The expected services are api, dash, db and proxy.

Service logs

docker compose -f /opt/dcim/docker-compose.yml --project-directory /opt/dcim logs --tail=200 api dash proxy db

If only the dashboard domain is failing, check DNS and the proxy logs before changing the application.

SSL or certificate errors

SSL errors are usually caused by DNS pointing to the wrong server, closed ports, another service using ports 80 or 443, or the proxy not being able to request a certificate.

Proxy checks

dcimctl status
docker compose -f /opt/dcim/docker-compose.yml --project-directory /opt/dcim logs --tail=200 proxy

Confirm that the DNS A record points to the DCIM server public IP and that ports 80 and 443 are reachable from the internet.

Installer is blocked by apt

On a new VPS, cloud-init or unattended upgrades may still be running. If the installer reports an apt or dpkg lock, wait for the system package process to finish before running the installer again.

Apt lock checks

ps -ef | grep -E "apt|dpkg|unattended"
cloud-init status --wait

Installation already exists

If the installer says that /opt/dcim already contains a DCIM installation, it found an existing runtime. Do not delete files manually.

Use reset only when this server should be wiped before a fresh install:

Fresh install reset

sudo dcimctl reset

dcimctl reset removes the local installation, containers, volumes, images and the dcimctl symlink. It does not release the license instance. Contact support before installing again with the same license key.

License required after install

If the dashboard reports a license problem after installation, check the API logs and confirm that the license files exist on the host.

License checks

docker compose -f /opt/dcim/docker-compose.yml --project-directory /opt/dcim logs --tail=200 api
ls -la /opt/dcim/license

If billing, plan limits or license assignment changed recently, run sudo dcimctl license --sync and check dcimctl license again.

Lost admin password or email

The first admin password is printed once at install time. If it was lost, reset it from the DCIM server.

First admin recovery

sudo dcimctl reset-admin --password <new_password>
sudo dcimctl reset-admin --email <new_email>

Backup or R2 fails

For backup errors, check the API logs and the local backup folders. R2 failures are commonly caused by using a Cloudflare dashboard API token instead of S3-compatible R2 credentials, the wrong endpoint, the wrong bucket or missing read/write permission.

Backup checks

docker compose -f /opt/dcim/docker-compose.yml --project-directory /opt/dcim logs --tail=200 api
ls -la /opt/dcim/backups
ls -la /opt/dcim/backups/.tmp

The R2 endpoint should look like https://account-id.r2.cloudflarestorage.com. The R2 credentials must be Access Key ID and Secret Access Key from the R2 object storage credential flow.

The full backup configuration is explained in Backups & restore.

Restore fails

Restore must use a full backup archive generated by DCIM. Do not retry with a partial archive or files copied manually from another server.

Restore checks

dcimctl status
docker compose -f /opt/dcim/docker-compose.yml --project-directory /opt/dcim logs --tail=300 api dash proxy db
ls -la /opt/dcim/restore-safety

dcimctl restore creates a safety copy under /opt/dcim/restore-safety before replacing runtime files.

Support bundle

When support asks for diagnostics, create a support bundle from the host. The bundle is for diagnostics only and is not a backup.

Create support bundle

sudo dcimctl support-bundle
tar -tzf /opt/dcim/support/dcim-support-*.tar.gz

Review the archive list before sharing it externally. The bundle should contain service status, service logs, system details and redacted configuration, not raw database dumps, passwords, private keys, API tokens or R2 secrets.

Troubleshooting video

Temporary placeholder. This will be replaced with the real troubleshooting video.