Setting up an authenticated docker-compose Validator Node

Questions
1

I am trying to set up a DevNet validator node with Docker Compose and Auth0, but I keep running into issues such as containers constantly restarting, authentication errors, and problems accessing the Wallet UI. What are the most common pitfalls and how can I resolve them?

2

Setting up a DevNet validator node with Docker Compose can involve several tricky configuration steps. Follow the official documentation.
Here are the most common issues you can face and their solutions:

  • Environment Variables:
    Ensure all required environment variables are set correctly in your .env file.
    Pay special attention to LEDGER_API_AUTH_AUDIENCE and VALIDATOR_AUTH_AUDIENCE.
    The first one should be the identifier you set up in section 2.a of the Auth0 configuration.
    The second should be the same value, unless you configured a different audience Validator App API on section 3.
    The WALLET_ADMIN_USER must be the full user ID from Auth0 (e.g., auth0|43b68e1e4978b422caza222), not just the suffix or the client ID.

  • Onboarding Secret:
    The onboarding secret is single-use and expires after 48 hours. Always use a fresh secret when starting the validator.

  • User ID Format:
    If you get error in the participant logs like UserNotFound or User ID "" does not match regex ..., check that LEDGER_API_ADMIN_USER is set and properly quoted in your .env file (e.g., LEDGER_API_ADMIN_USER="$VALIDATOR_AUTH_CLIENT_ID@clients").

  • Version Mismatch:
    If you get a version mismatch error, ensure your local validator version matches the version of the remote service you are connecting to. Download and use the latest bundle if needed.

  • Volumes and Logs:
    If you encounter persistent issues, prune all Docker volumes and reset your setup to clear out old state and logs.

  • Wallet UI Access:
    For Docker Compose setups, the Wallet UI should be accessible at http://wallet.localhost/.

  • Debugging:
    If containers are restarting or you see initialization errors, check both the validator and participant logs for detailed error messages. Often, the root cause is a misconfigured environment variable or an expired onboarding secret.

By carefully checking these areas and ensuring your configuration matches the documentation and your Auth0 tenant, you can resolve most common issues with DevNet validator node setup. If problems persist, provide full logs from both the validator and participant containers to support for further troubleshooting.

4 Likes