Clustering Nodes
If you generated your project with mix phx.new on Phoenix 1.7 or later, clustering works out of the box on Gigalixir. The generated app already includes dns_cluster, and Gigalixir wires it up for you at runtime.
Once your nodes are clustered, distributed Phoenix Channels and Phoenix.PubSub just work — no additional configuration required.
Verifying clustering
Scale to two or more replicas and open a remote console:
gigalixir ps:scale -r 2
gigalixir ps:remote_console
Then call Node.list/0 — you should see the other replica(s):
iex(my-app@10.56.42.110)1> Node.list()
[:"my-app@10.56.38.235"]
Troubleshooting
If Node.list/0 comes back empty, work through the checks below from the same remote console.
Are there other replicas to cluster with?
iex> length(Node.list()) + 1
A single-replica app has nothing to connect to. Scale up with gigalixir ps:scale -r 2 and try again.
Is dns_cluster running?
iex> Process.whereis(DNSCluster)
#PID<0.1929.0>
If this returns nil, your supervision tree isn’t starting it. Open lib/<app>/application.ex and confirm there’s a {DNSCluster, query: ...} child. Apps generated before Phoenix 1.7 won’t have it — see adding dns_cluster to an existing app.
Is DNS_CLUSTER_QUERY set?
iex> System.get_env("DNS_CLUSTER_QUERY")
"epmd-...cluster-test.svc.cluster.local"
Gigalixir sets this for every release. If it’s nil, contact support — that’s a platform issue, not something you need to configure.
Is dns_cluster actually using that query?
In config/runtime.exs, the generated Phoenix config reads the env var into your app config:
config :my_app, :dns_cluster_query, System.get_env("DNS_CLUSTER_QUERY")
If you’ve customized runtime.exs, confirm this line is still present and runs in :prod.
If you’re still stuck, contact support with the output of the checks above.