Fix QueryService and MLService silent startup failures

[Copilot]

Users see docker-compose reporting "Running" but QueryService (8010) and MLService (8007) are unreachable because services fail silently inside the container due to misconfigured environment variables.

Changes

Pre-flight validation (validate_env.sh)

• Validates .env exists and critical variables are set
• Detects default placeholder passwords that cause auth failures
• Enforces password consistency across POSTGRES_PASSWORD, DB_PASSWORD, JWT_POSTGRES_DATABASE_PASSWORD
• Integrated into start_services.sh to block startup on invalid config

Service health verification

• Added /app/healthcheck.sh in container to verify supervisor + all services are actually running and listening
• Updated docker-compose healthcheck from simple port 8000 check to comprehensive all-service validation
• Added post-startup health check in start_services.sh that shows per-service status with commands to view logs on failure

Container startup

• Added environment variable validation in Dockerfile.unified startup script
• Shows which services are starting and log locations
• Warns about missing critical variables before services fail

Documentation

• Explicit .env setup requirements with password consistency rules
• Troubleshooting section with diagnostic commands for common failure modes

Example

Before:

$ ./start_services.sh
✔ Container brainkb-unified Running
# Services at localhost:8007, localhost:8010 don't respond - no indication why

After:

$ ./start_services.sh
❌ Validation failed with 8 error(s)
  ❌ POSTGRES_PASSWORD is still set to default value
  ❌ POSTGRES_PASSWORD and DB_PASSWORD do not match
Please fix the errors above before starting services.

Or if config is valid:

$ ./start_services.sh
Service Status:
  ✓ api_tokenmanager: RUNNING
  ✓ query_service: RUNNING
  ✗ ml_service: EXITED
    To view logs: docker exec brainkb-unified tail -n 50 /var/log/supervisor/ml_service.err.log

Original prompt

---

This section details on the original issue you should resolve

<issue_title>QueryService and MLService does not seem to be running.</issue_title>
<issue_description>

env.template			oxigraph			usermanagement_service
(myenv) sulimansharif@dhcp-10-29-220-78 BrainKB % ./start_services.sh
Ollama container is already running
Ollama model 'nomic-embed-text' is already loaded
[+] Running 5/5
 ✔ Container brainkb-oxigraph        Running                                                       0.0s
 ✔ Container brainkb-postgres        Healthy                                                       0.5s
 ✔ Container brainkb-oxigraph-nginx  Running                                                       0.0s
 ✔ Container brainkb-pgadmin         Running                                                       0.0s
 ✔ Container brainkb-unified         Running

On my macbook when I try to access localhost:8007 and localhost:8010, the services don't start however my terminal output says it is running what is going on here. or not found.
</issue_description>

Comments on the Issue (you are @copilot in this section)

• Fixes QueryService and MLService does not seem to be running. #55

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

[tekrajchhetri]

@Sulstice are you still working on it? It's marked as draft.