Skip to main content

Installation Troubleshooting

Common issues encountered when setting up or updating Daployi.

System redirects to login screen instead of welcome setup​

After installing the Docker container using the install utility or any other method, the system might take you straight to a login screen instead of the welcome setup screen. This typically indicates that the web system cannot communicate with the backend.

Possible Causes & Solutions:

  • Invalid SSL Certificate: The system requires a valid SSL certificate. Ensure your certificates are valid and correctly configured.
  • Communication Failure: The web application might be unable to reach the API backend.

How to Diagnose: Check the logs of the web system container to see the specific error:

  1. Run docker ps to list running containers and find the ID of the web app container.
  2. Run docker logs <container_id> to view the logs and identify potential issues.

System cannot log in or no items show after update​

After updating using the deploy install utility, you can no longer log in, or no items are displayed in the dashboard. This happens when the web system can no longer connect to the backend, or the backend cannot authorize with the database.

Root Cause: This usually occurs if the install utility is executed from a different folder than the original installation. The installer generates unique secrets stored in the folder from which it is run. Running it from a different folder generates a new set of credentials that don't match the existing database.

Solution:

  • Consistent Execution Folder: Always run the install utility from the same folder where the initial installation was performed.
  • Static Location in Compose: To prevent this in the future, you can statically set the secrets location in your docker-compose.yml or Docker run command so that the installer always uses the same path.

Redis or MongoDB Authentication Failures​

If you are performing a fresh installation or an update and find that Redis or MongoDB services fail to authenticate or the system fails to start, it's often due to a mismatch between the .secrets/ directory and the persistent volumes.

This happens because if you simply remove the containers and reinstall, the secrets might be regenerated while the existing volumes still expect the old secrets.

Solution: If you are stuck in this state, you may need to:

  1. Ensure your credentials are consistent across .env and .secrets/.
  2. If you intend to start completely over and wipe all data, use the REINSTALL=true flag with the installer to ensure all old secrets and volumes are purged before the new ones are generated.
Data Destruction Warning

Using the REINSTALL=true flag will destroy all data in your installation, including database contents (MongoDB/Redis) and all generated secrets. This action is irreversible.

API not reachable on localhost:API_PORT​

  • Symptom: curl http://localhost:4000 fails or times out.
  • Checks:
    • docker ps — ensure daployi-server is running.
    • docker logs daployi-server — verify it started without errors and is listening on the configured port.
    • docker compose ps — confirm port mapping shows 0.0.0.0:4000->4000/tcp.
    • Confirm no host firewall is blocking the port.
  • Fix:
    • Ensure API_PORT is the same value in .env and used in the ports mapping.
    • If using another service on that port, change API_PORT and restart.

Web UI shows blank page or 502​

  • Symptom: http://localhost:3000 returns an error or blank page.
  • Checks:
    • docker logs daployi-web — confirm it can reach the API.
    • Verify NUXT_PUBLIC_API_BASE and NUXT_PUBLIC_WS_BASE point to the correct public URL for the API.
    • Ensure daployi-server is healthy.
  • Fix:
    • Update PUBLIC_API_BASE/WS_BASE in .env, then docker compose up -d to recreate web.

MongoDB authentication failed (Manual Check)​

  • Symptom: API logs contain authentication errors for MongoDB.
  • Checks:
    • Confirm MONGO_USER in .env matches MONGO_INITDB_ROOT_USERNAME for mongodb service.
    • Ensure MONGO_PASSWORD_ENC is the URL-encoded value of the password in .secrets/mongo_root_password.
    • Try connecting with the mongo shell using the same credentials.
  • Fix:
    • Regenerate MONGO_PASSWORD_ENC using the commands in the Installation (Compose) guide.
    • If you changed the Mongo root password, update .secrets/mongo_root_password and MONGO_PASSWORD_ENC, then restart.

Redis authentication required (Manual Check)​

  • Symptom: API/Worker cannot connect to Redis due to auth.
  • Checks:
    • redis-cli -h localhost -p 6378 -a $(cat .secrets/redis_password) PING should return PONG.
    • Verify REDIS_PASSWORD in .env matches .secrets/redis_password.
  • Fix:
    • Update REDIS_PASSWORD and restart API/Worker containers.

Static IP conflict on custom network​

  • Symptom: docker compose up fails with "Address already in use" or network conflict.
  • Checks:
    • docker network ls; docker network inspect daployi_daployi_net or the named network.
    • Ensure 10.99.0.0/24 isn’t used by another network.
  • Fix:
    • Change the subnet and static IPs in docker-compose.yml consistently.

Containers restart repeatedly​

  • Symptom: restart loops.
  • Checks:
    • docker logs <container> for the first failure cause.
    • Verify dependent services are reachable (e.g., server waits for Mongo, Redis).
  • Fix:
    • Start infrastructure first (Mongo, Redis). Use depends_on and retry policies or wait-for scripts if needed.