Self-Hosting

Troubleshooting

Troubleshooting

Every command on this page is run from your install directory — the one holding docker-compose.yml and .env.

cd docu.nexus

Is it alive

curl -f http://localhost:3000/health

Returns {"status":"ok","timestamp":"..."}. The container has its own healthcheck hitting the same endpoint every 30 seconds, so docker compose ps reflects it too.

docker compose ps

Logs

# everything, following
docker compose logs -f

# just the app
docker compose logs -f app

# last 200 lines from Postgres
docker compose logs --tail 200 postgres

Service names are app, postgres, and redis. Container names are docunexus-app, docunexus-postgres, and docunexus-redis, so docker logs docunexus-app works too.

Raise detail with LOG_LEVEL=debug in .env, then restart the app container.

Common failures

Nobody can sign in

The shape of this: email and password sign-in is switched off because everyone uses the directory, and then the directory stops answering. It might have been unplugged, moved, or never have resolved from the server in the first place. The login page offers a directory tab that fails and no password form, and the admin panel that could switch password sign-in back on is behind the login page.

docu.nexus refuses a change that would leave no configured sign-in method, but “configured” means a connection is saved, not that anything answers it. Nothing can refuse a directory that stops working an hour after you saved it, so the way out is a command on the server rather than a guarantee in the product.

There is no page and no endpoint that does this, which is deliberate: an endpoint that re-enables password sign-in is an endpoint worth attacking. Recovery is a command on the server, and shell access to the server is the credential.

Run it from your install directory. It writes one key in the settings singleton — the same key the admin panel writes — and turns the email and password form back on:

docker compose exec -T postgres psql -U docunexus -d docunexus -c \
  "UPDATE instance_settings
      SET settings = jsonb_set(
            COALESCE(settings, '{}'::jsonb),
            '{auth,local,enabled}', 'true'::jsonb, true)
    WHERE id = 'singleton';"

It should print UPDATE 1. UPDATE 0 means the settings row does not exist yet, which on an instance that has had LDAP configured should not happen — stop there and contact support rather than creating one by hand.

Then reload the login page; no restart is needed, because sign-in modes are read from the database on every request. The password form is back, and any account that has a password can use it.

To see which accounts that is:

docker compose exec -T postgres psql -U docunexus -d docunexus -c \
  "SELECT email FROM users WHERE password_hash IS NOT NULL AND deactivated_at IS NULL;"

Accounts created by LDAP or by an SSO provider have no password at all, so an instance where every account came from the directory will list nothing here. Setting a password from the database is not something you can do by hand — the hash is argon2 and the database has no way to compute one — so that case needs support. Say that you have re-enabled local sign-in and that no account has a password; it is a short fix on our side, not a lost instance.

Once you are in, fix the directory or switch the LDAP mode off under Admin, then Authentication.

Nobody can administer

Different problem, easier answer. Sign-in works, but the last account with instance-administrator rights left, was deactivated, or lost the rights to a directory sync.

Add the address to .env and restart. The grant lands at boot and at every sign-in. The account must already exist: while an address is listed, nothing in the product will create an account for it.

cd docu.nexus
echo 'INSTANCE_ADMIN_EMAILS=owner@example.com' >> .env
docker compose up -d app
docker compose logs app | grep instance-admin

The grant is sticky, so you can take the line back out afterwards and it revokes nothing.

On an instance with no accounts at all, neither of these applies: the first-run setup wizard is still available and is the way in.