Troubleshooting

General diagnostics

Start every troubleshooting session with these two commands. They tell you the current state of all containers and stream recent log output.

# Check the status of both containers
docker compose ps

# Stream logs from all containers
docker compose logs -f

# Stream logs from a specific service only
docker compose logs -f dreamphase
docker compose logs -f postgres

Container won't start

If one or more containers exit immediately after docker compose up -d:

• Run docker compose logs <service> to see the error message from the failing container.
• Check that all required environment variables are present in your .env file, a missing variable is the most common cause.
• Confirm the image was pulled successfully with docker compose pull before retrying.
• Try a clean restart: docker compose down && docker compose up -d

Port conflicts

If a container fails with an error like "port is already allocated" or "address already in use":

• Another process is bound to the same port. Find it with ss -tlnp | grep <port> (Linux) or lsof -i :<port> (macOS).
• Stop the conflicting process, or change the port the stack uses by editing API_PORT or POSTGRES_PORT in your .env file and restarting the stack.

# After editing .env, restart the stack to apply changes
docker compose down && docker compose up -d

Mobile app can't reach the API

If the Dreamphase app reports a connection error after you've set the server URL:

• Confirm the stack is running: docker compose ps should show all services as running.
• Verify the URL format. It must include the scheme and port, e.g. http://192.168.1.42:8543. A missing scheme or wrong port is the most common mistake.
• If the phone and the host machine are on the same Wi-Fi network, make sure the host's firewall is not blocking the API port.
• Test reachability from a browser on the same device: navigate to http://<host>:<port> and confirm you get a response.
• If the host is your laptop on a different network segment from your phone, you may need to use the host's network IP rather than localhost.

Web UI not loading

If the bundled web UI is not accessible at http://localhost:<API_PORT>:

• Check the dreamphase container is running: docker compose ps
• Check for errors in the server logs: docker compose logs dreamphase
• Confirm API_PORT in your .env matches the port you're visiting in the browser. The web UI is served by the dreamphase container on the same port as the HTTP API.

Data persistence / volume issues

If data is not persisting across container restarts, or you want to reset to a clean state:

• Data should survive a plain docker compose down && docker compose up -d because it lives in named Docker volumes, not inside the container filesystem.
• Confirm the volumes exist with docker volume ls.
• If you accidentally ran docker compose down -v, the volumes and all data have been deleted, there is no recovery from this without a backup.
• To intentionally reset to a clean state: docker compose down -v && docker compose up -d

# Stop containers, keep volumes (data safe)
docker compose down

# Stop containers AND delete volumes (data lost, use with caution)
docker compose down -v

Getting help

If none of the above resolves your issue, contact support at info@gestaltmind.dev with the output of docker compose ps and the relevant logs from docker compose logs <service>.