Domains

How to Set Up a Custom Domain

After your first deploy, you can see your app by visiting its default domain, https://$APP_NAME.gigalixirapp.com, unless you have disabled it. If you want, you can also point your own domain such as www.example.com to your app.

To do this, run the following command and follow the instructions:

gigalixir domains:add www.example.com

This will do a few things, mainly:

  • It registers your fully qualified domain name in the load balancer so that it knows to direct traffic to your containers.
  • It sets up SSL/TLS encryption for you and provisions a certificate.

After running this command, you will need to configure a CNAME record with your DNS provider pointing to yourdomain.gigalixirdns.com.

Common Mistake
Point your CNAME to yourdomain.gigalixirdns.com, not appname.gigalixirapp.com. Pointing to the .gigalixirapp.com address is a common mistake that results in a misleading “We are still setting up the load balancer” error message.

For more information on how SSL/TLS works, see How SSL & TLS Works.

Important

If you want both the apex domain and a subdomain such as www, be sure to run gigalixir domains:add for each one.

Note

Per the RFC spec, many DNS providers (such as GoDaddy and AWS Route 53) do not allow CNAME records for apex domains. If you are using a DNS provider that supports ALIAS records (such as Namecheap), you may define an ALIAS record for your apex domain that points to your corresponding gigalixir DNS domain, e.g. example.com.gigalixirdns.com.

Alternatively, you can use a redirect service such as redirect.pizza to securely forward requests for your apex domain to your www. sub-domain.

Note

If you need a wildcard domain, feel free to contact us and we can help you get set up, but you will have to provide your own wildcard certificate.

Phoenix LiveView / WebSocket Users

If you use Phoenix LiveView or WebSockets, you must configure check_origin to allow your custom domain. By default, Phoenix rejects WebSocket connections whose origin does not match PHX_HOST. If you set PHX_HOST to your custom domain but access the app via the default .gigalixirapp.com URL (or vice versa), WebSocket connections will fail silently.

To allow both your custom domain and the default Gigalixir domain, add something like this to your endpoint configuration in runtime.exs:

config :my_app, MyAppWeb.Endpoint,
  check_origin: [
    "https://www.example.com",
    "https://#{System.get_env("APP_NAME")}.gigalixirapp.com"
  ]

If you have disabled the default domain, nobody can reach your app on it, so you can leave the .gigalixirapp.com entry out and list only your custom domains.

For more details, see the Phoenix Endpoint runtime configuration.

How to Disable the Default Domain

Every app gets a default domain, $APP_NAME.gigalixirapp.com. If your app is served only on your own custom domains, you can disable the default domain so the app no longer answers on it. You can enable it again at any time.

From the console

  1. Open your app in the console and go to the Domains page.
  2. In the Default domain section, you will see the host (a link while the default domain is enabled) and its status, Enabled or Disabled.
  3. Click Disable (or Enable) and confirm in the dialog.

If the app has no custom domains, the disable dialog warns you that disabling the default domain leaves the app with no public host. Your custom domains are listed in the Custom domains section of the same page.

While the default domain is disabled, the app’s Open button shows a dialog listing your custom domains instead of opening the default host.

From the CLI

gigalixir domains:default:disable
gigalixir domains:default:enable

Both commands take the usual -a $APP_NAME flag. If the app has no custom domains, domains:default:disable asks you to confirm first, because the app becomes unreachable. Declining exits with status 0 and changes nothing. Pass -y to skip the prompt:

gigalixir domains:default:disable -y

When the app has at least one custom domain, disable does not prompt.

Make sure you have a custom domain first
An app with no custom domains has no other way to be reached. Run gigalixir domains:add and finish the DNS setup above before you disable the default domain.

Note
A canary app cannot disable its default domain, because its traffic split is served through that domain. The API refuses with a 422 error: “The default domain cannot be disabled on a canary app, because its traffic split is served through that domain. Disable it on the primary app instead.”

What visitors see

Visitors to the default host of a disabled app get the same not-found page they get for any host Gigalixir does not serve. Disabling does not remove the DNS record or the TLS certificate for the default domain, so the host still resolves. It just stops serving your app. Enabling the default domain restores it.

Troubleshooting Custom Domains

If your custom domain is not working after setup, check the following:

  1. Verify your CNAME target. Your DNS CNAME record must point to yourdomain.gigalixirdns.com, not appname.gigalixirapp.com.
    dig www.example.com CNAME +short
    # should return: www.example.com.gigalixirdns.com.
    
  2. “Still setting up the load balancer” message. This usually means the CNAME is pointing to the wrong target. See the warning above about using .gigalixirdns.com.

  3. DNS propagation delays. After changing DNS records, it can take up to 24-48 hours for changes to fully propagate, though most updates take only a few minutes.

  4. SSL certificate not provisioning. SSL certificates are provisioned automatically after DNS is configured correctly. If the certificate is not provisioning, verify that DNS is resolving correctly. If issues persist, contact support.

  5. Verify the domain is registered with Gigalixir. Run gigalixir domains to confirm your domain is listed.

How to Set Up SSL/TLS

SSL/TLS certificates are set up for you automatically assuming your custom domain is set up properly. Note that your application will continue to be served on http as well as https.

If you want to force your users to use https by redirecting any http requests, specify that in your config/prod.exs:

config :my_app, MyAppWeb.Endpoint,
   force_ssl: [rewrite_on: [:x_forwarded_proto]]

This configures your app to check the x-forwarded-proto header set by Gigalixir, and redirect to https, if appropriate.

For more information on how this works internally, see How SSL & TLS Works in Gigalixir.

What’s Next?