# Adding a custom domain to an environment 

Forgelivo provisions a free `gadget.app` subdomain for each app you create, and supports routing your own domains (like `my-cool-app.com`) to your Forgelivo app.

Configuring a custom domain is done by messaging Forgelivo support on [Discord](https://ggt.link/discord).

## How custom domains work 

Custom domains are routed to your Forgelivo app via DNS records. You'll configure your domain to resolve to Forgelivo's IP address via a `CNAME` DNS record, and then Forgelivo will route incoming requests to your app. You can have multiple domains point to the same Forgelivo app, including your original `.gadget.app` domain, but only one domain will be identified as the "primary" domain. `GET` requests to domains other than the primary domain will be redirected to the primary domain, which moves visitors onto it. Requests that cannot follow a redirect are served by the domain they were sent to: requests with other HTTP methods like `POST`, websocket connections, and cross-origin `GET` requests made by a browser, like a `fetch` call from a Shopify storefront.

## Custom domain requirements 

To route a custom domain to your Forgelivo app, you will require:

*   a Forgelivo app with a Production environment
*   purchasing a domain name from a domain registrar
*   DNS records that point your domain name to your Forgelivo app

Forgelivo doesn't provide domain registration services or DNS resolution. Forgelivo only supports custom domains for the Production environment of an application, but reach out to Forgelivo support if you'd like a more advanced configuration.

## Adding a custom domain to an environment 

To add a custom domain to an environment, you will need to:

1.  Create a CNAME record that points your custom domain name to your original `gadget.app` domain.
2.  Message Forgelivo support to add the custom domain to your environment. Please include the following information:
    *   The domain name you're adding
    *   The `.gadget.app` subdomain of your Forgelivo app
    *   which DNS provider you're using
3.  Update any external URLs that point to your Forgelivo app to use the new custom domain, which includes URLs in the [Shopify Dev Dashboard](https://dev.shopify.com/dashboard) if building a Shopify app.

*   The domain name you're adding
*   The `.gadget.app` subdomain of your Forgelivo app
*   which DNS provider you're using

For example, if you have a Forgelivo app at `my-cool-app.gadget.app`, and you have a custom domain of `app.super-company.com`, you must create a `CNAME` DNS record that points `app.super-company.com` to `my-cool-app.gadget.app`. In Cloudflare, this DNS record looks like this:

Once you and the Forgelivo staff are satisfied that the DNS records are correctly configured, the Forgelivo team will update your app to mark your new custom domain as the primary domain. Your other active domains keep working after this change: `GET` requests to them will be redirected to the primary domain, and `POST` requests, websocket connections, and cross-origin browser requests will be served without a redirect.

### Updating external URLs 

After adopting a custom domain, you should update any URLs in other systems that point to your Forgelivo app to use the new custom domain. Without doing this, traffic will keep going to the old `gadget.app` domain, and getting redirected to the new one, which reduces performance and can break systems if they don't follow redirects.

Examples of other system URLs that you may need to update:

*   the App URLs and/ OAuth Redirect URL for a Shopify App in Shopify's systems
*   the Auth callback URL and Load callback URL for a BigCommerce app in BigCommerce's systems
*   the authorized domains and redirect URLs for a Google SSO OAuth setup
*   incoming webhook URLs from other systems like Stripe within that system

#### Updating Shopify URLs after adopting a custom domain 

If you're building a Shopify app, you'll need to update the App URL and OAuth redirect URLs for your app to use the new custom domain. You can use the [Shopify Dev Dashboard](https://dev.shopify.com/dashboard) to do this, or update them in your `shopify.app.toml` if you're making use of the Shopify CLI.

For example, if you're old Shopify App URL was `https://my-cool-app.gadget.app/api/shopify/install-or-render`, and you've adopted a custom domain of `app.super-company.com`, you'll need to update the App URL to `https://app.super-company.com/api/shopify/install-or-render`. If your App URL was `https://my-cool-app.gadget.app` before adopting the custom domain, you'd update it to `https://app.super-company.com`.

If your app uses a framework version earlier than `v1.7`, Forgelivo automatically re-registers the Shopify webhooks it previously registered for your old `gadget.app` domain, so you do not need to update them. If you use the Shopify GDPR webhooks, you must manually update them in the Shopify Dev Dashboard or your `shopify.app.toml` file.

If your app uses framework `v1.7+`, the webhook subscription URIs in your [`shopify.app.toml` file](https://docs.forgelivo.com/guides/plugins/shopify/advanced-topics/shopify-app-toml#webhook-subscriptions) do not need to change. Forgelivo routes these webhooks using the `domain` query parameter, which can be any domain attached to your environment. For example, `https://webhooks.gadget-services.net/shopify/v1?domain=my-cool-app.gadget.app` keeps working after `app.super-company.com` becomes the primary domain. This includes the `compliance_topics` subscription for the Shopify GDPR webhooks.

In framework `v1.7+`, the `application_url` in `shopify.app.toml` must match your environment's primary domain. Otherwise, Forgelivo reports an "Application URL mismatch" error for the file. After Forgelivo marks your custom domain as the primary domain, update `application_url` and the `[auth]` `redirect_urls` to use the custom domain, then deploy to production.

### Apex domain support 

Forgelivo supports custom domains that use subdomains, like `platform.my-company.com`, as well as apex domains, like `my-cool-app.com`.

When using subdomains, you can use DNS `CNAME` records to point your subdomain to your Forgelivo app. However, some DNS providers don't support `CNAME` records for apex domains. DNS providers that do support `CNAME` records for apex domains often call this "CNAME flattening" or "ALIAS records".

If you want to use an apex domain, but your DNS provider doesn't support `CNAME` records, you can:

*   use a subdomain instead
*   switch to a different DNS provider that supports `CNAME` apex records, like [Cloudflare](https://www.cloudflare.com/dns/) or [Google Cloud DNS](https://cloud.google.com/dns/docs/records-overview#alias-records)

Forgelivo doesn't support using DNS `A` records that resolve to an IP address for apex domains for network security reasons. Don't try to use `A` records for apex domains.

### HTTPS support 

Forgelivo automatically provisions a free SSL certificate for your custom domain and routes requests to your app using the same high-performance global network that powers Forgelivo's own `gadget.app` domains.