Standalone Deployment Cloud Database Not Working

[MaxwellGrant90]

I ran into a blocker trying to deploy the router in standalone mode with a Docker container using a Redis sidecar and cloud postgres database. When i run curl http://localhost:8080/health/ready I keep getting this error: {"error":{"type":"api","message":"Database health check failed with error: Error while connecting to database","code":"HE_00"}}. Is it possible to use a cloud database? I was able to run the migration from my CLI just fine. After trying Claude Code for debugging, it came to the conclusion that it needs a local database. Is that true or am I not configuring this correctly?

[SanchithHegde]

Hey @MaxwellGrant90, could you please provide information on how exactly you've deployed / you're running the Hyperswitch router container: is it via our Docker Compose setup, in Kubernetes via Helm, or something else? It just looks like the database not configured correctly.

If it's via the Docker Compose setup (based on the docker-compose.yml file), you would have to update the database credentials in the config file, config/docker_compose.toml. Specifically, you would have to update the [master_database] and [replica_database] sections.

[MaxwellGrant90]

Standalone Docker containers. One is from juspaydotin/hyperswitch-router:2026.01.07.0-hotfix4-standalone- and the other is redis:7-alpine. The database env config I used are

ARG ROUTER__MASTER_DATABASE__USERNAME ARG ROUTER__MASTER_DATABASE__PASSWORD ARG ROUTER__MASTER_DATABASE__HOST ARG ROUTER__MASTER_DATABASE__PORT ARG ROUTER__MASTER_DATABASE__DBNAME ARG ROUTER__REPLICA_DATABASE__USERNAME ARG ROUTER__REPLICA_DATABASE__PASSWORD ARG ROUTER__REPLICA_DATABASE__HOST ARG ROUTER__REPLICA_DATABASE__PORT ARG ROUTER__REPLICA_DATABASE__DBNAME

I also updated the database credentials in the config file. The server doesn't start without them. But - with all these config options, the health/ready check does not pass. I'm using a cloud postgres database too.

[SanchithHegde]

1. Why the ARG, are you trying to build another Docker image based on ours? Or would you be able to provide the command that you are using to run the containers?

I also updated the database credentials in the config file.

2. About the config file, since you're not using the Docker compose setup, ensure that the file is mounted in the container at a suitable path. Once that's done, you would have to override the command run in the container to inform router to read the specific config file. Refer:

   hyperswitch/docker-compose.yml

   Line 94 in 5840551

   command: /local/bin/router -f /local/config/docker_compose.toml

3. Also, is there any specific reason you're using one of the nightly images such as juspaydotin/hyperswitch-router:2026.01.07.0-hotfix4-standalone over our stable (monthly) release images like juspaydotin/hyperswitch-router:v1.120.0-standalone?

[MaxwellGrant90]

1. I wouldn't say I'm building another one - but rather breaking it up for a serverless runtime on Google Cloud Run.
   My Dockerfile pretty much looks like this minus the Arg variables that I mentioned:

FROM juspaydotin/hyperswitch-router:2026.01.07.0-hotfix4-standalone COPY docker.toml /local/config/docker.toml WORKDIR /local/bin ENV PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/local/bin ENTRYPOINT ["/local/bin/router"] CMD ["--config-path", "/local/config/docker.toml"]
Also note, that there was a architecture diagram somewhere that shows PostgrSQL could be an option in substitute for Redis, but you cannot start the server without a Redis connection and I couldn't find any config for PostgreSQL only configuration. That would make the server a truly standalone deployment with a cloud db.

2. No to Docker compose - doesn't work with this deployment.

3. No specific reason.

[SanchithHegde]

I wouldn't say I'm building another one - but rather breaking it up for a serverless runtime on Google Cloud Run.
My Dockerfile pretty much looks like this minus the Arg variables that I mentioned

Oh in that case, you could try to mount the config file if possible. Otherwise, you would have to include the file in the image as you have tried.

Note that ARG instructions won't be part of the built image, as per the Docker docs:

Unlike an ARG instruction, ENV values are always persisted in the built image. [...]

Also note, that there was a architecture diagram somewhere that shows PostgrSQL could be an option in substitute for Redis, [...]

I don't remember this being the case, we've always required Postgres and Redis at least. Would you be able to share a link to where you found this?

Also, one possible optimization, you can just copy the config file to /local/config/sandbox.toml and you need not have any of the WORKDIR, ENV PATH=..., ENTRYPOINT or CMD lines, the router should be able to pick it up automatically. Alternatively, if you set the RUN_ENV environment variable to production (this is set to sandbox by default in our Docker image), then the corresponding config file path (which the router automatically reads) would be /local/config/production.toml.

Do note that with this way of deploying, you would be required to build new images every time you want to modify the config file.

I would also suggest you to use the monthly stable release images (such as v1.120.0) over the nightly ones.

[MaxwellGrant90]

I also set the var from the Dockerfile with

ENV ROUTER__MASTER_DATABASE__USERNAME=${ROUTER__MASTER_DATABASE__USERNAME}.

from the .env file - and I tested copying the .env file into the image itself. So my config file has:

[master_database] host = "${ROUTER__MASTER_DATABASE__HOST}"

I went into interactive mode and the env variables are there so I don't think it is about mounting, but which config variables or the config.toml itself. But I could be wrong.

To clarify, HyperSwitch should be able to use a cloud Postgresql database?

[SanchithHegde]

If your question is whether Hyperswitch can work with Postgres running outside Docker / Kubernetes, yes, it does. We have tried out deployments where the application runs within Kubernetes but the Postgres and Redis servers are AWS managed ones (AWS RDS / Aurora and ElastiCache), running outside Kubernetes.

So my config file has:

[master_database] host = "${ROUTER__MASTER_DATABASE__HOST}"

This however won't work, router doesn't substitute the value of the environment variable when reading the TOML file, it would read it as the literal string "${ROUTER__MASTER_DATABASE__HOST}".

Either specify the value directly in the TOML file, or via the equivalent environment variables. In case a value is provided in both the TOML file and environment variable, the environment variable has higher priority. The application also prints out the full config it has read at startup, so you should be able to see the value it has read in the application logs.

For the /health/ready failures as well, you should be able to find more information about what went wrong in the application logs.

[MaxwellGrant90]

I tried all your recommendations, and still no luck. Which folder exactly are the app logs? I have debug mode on and it's outputting to console the message above. Can I troubleshoot the connection from inside the container with the cli? If so, how?

I can talk more about my connection off of GitHub. I submitted a support ticket about this two days ago, please reach out to that email.