Custom domains

A custom domain serves your application from a hostname you own instead of its gigadrive.app URL. You verify the domain once for your organization, point a DNS record at Gigadrive Network, and the platform issues the certificate and starts serving.

Before you begin

• You can change the DNS records of the domain at your DNS provider.
• Your plan has room for another custom domain. Starter includes one; the limits table has the rest.

Add a domain

1. In the console, open your application and go to Settings > Domains.
2. In Custom domains, click Add domain.
3. Enter the hostname, for example shop.example.com or the apex example.com.
4. Optional: in Serves, choose A branch to serve the latest deployment of a branch, or A redirect to send every request to another hostname. Production is the default.
5. Click Add domain. The domain appears with the DNS records to publish.
6. At your DNS provider, create each record the console lists. The Name column is relative to your domain, and @ stands for the apex.

Gigadrive Network checks the records automatically, so there is nothing to click after publishing them. A correctly configured domain usually goes live within a few minutes of DNS reaching public resolvers. Click Check again to check right away.

You can do the same from code, the CLI or the API. The CLI and TypeScript tabs attach shop.example.com and wait until it serves traffic. The REST commands exchange an API key for an access token, then attach shop.example.com and return the records to publish in requiredRecords. GIGADRIVE_CLIENT_ID and GIGADRIVE_CLIENT_SECRET are the ID and secret of an API key with the network:domains:write scope, as described in Authentication:

import { GigadriveClient } from '@gigadrive/sdk';

const client = new GigadriveClient();
const applicationId = '0197b2f1-2f4a-7a0b-8a2d-222222222222';

const domain = await client.applications.domains.add(applicationId, { hostname: 'shop.example.com' });
for (const record of domain.requiredRecords) {
  console.log(record.type, record.host, record.value);
}

await client.applications.domains.waitUntilActive(applicationId, domain.id);

GET /applications/{applicationId}/domains/{domainId} returns the current state and needs the network:domains:read scope. POST /applications/{applicationId}/domains/{domainId}/refresh checks again.

Which credentials you use changes what the API lets you do:

• A signed-in user or an organization API key can make every change. Adding a hostname also adds its domain, such as example.com, for verification in your organization, so one TXT record covers later hostnames below it.
• An application API key can add, update, check, and remove domains of its own application, but cannot claim a hostname. Adding a hostname with it does not add the domain for verification in your organization. Instead, requiredRecords lists a TXT record for that hostname alone, at _gigadrive-challenge.<hostname>, such as _gigadrive-challenge.shop.example.com.
• Deployment and Function tokens cannot add, update, check, claim, or remove custom domains. The API answers with 403 and forbidden.

Records to publish

Most domains need two records. DNS records has provider-specific notes.

You publish the TXT record once per domain. After example.com is verified, every hostname below it, such as shop.example.com and api.example.com, can be attached by any application of your organization without another TXT record. Keep the record in place.

Each domain you verify gets its own token, so copy the value the console or the API lists for that domain rather than reusing one from another domain.

If you control only a subdomain such as shop.example.com, and not example.com itself, verify the subdomain instead. Add it for verification with gigadrive domains owners add shop.example.com or POST /organizations/{organizationId}/domains, then publish the TXT record the response lists, at _gigadrive-challenge.shop.example.com. The verification covers shop.example.com and every hostname below it.

Apex domains

An apex domain such as example.com cannot have a CNAME record. Use the record your DNS provider offers instead of one: ALIAS, ANAME, or CNAME flattening. If your provider offers none of them, add www.example.com as your domain and redirect example.com to it at your provider.

Domain states

The console and the API show the state of each domain. Only Active and Needs attention serve traffic.

A domain that waits for 7 days on a problem you control, such as a missing DNS record, a blocking CAA record, or unverified ownership, fails, so it does not hold a slot forever. Problems on the Gigadrive Network side never fail a domain: it keeps retrying until the problem clears. An active domain is checked every 6 hours. It moves to Needs attention after 3 failed checks at least 15 minutes apart, so no sooner than 30 minutes after the first failure, or when its certificate expires within 14 days. A domain that stays Failed for 30 days is removed.

Custom domain errors explains every problem code.

What a domain serves

A domain serves the latest production deployment by default, and follows each new production deployment without any action from you. You can change this at any time in the API with PATCH /applications/{applicationId}/domains/{domainId}:

• A branch target follows the latest deployment of that branch.
• A redirect target answers every request with a redirect to another hostname. The status defaults to 308 and can be 301, 302, 307, or 308, and the path and query string are kept unless you turn that off. Redirects are available on paid plans.

Until the application has a deployment for the domain's target, the domain answers with a 404 page carrying EDGE_DOMAIN_NO_DEPLOYMENT. Deploy the application, or the branch the domain serves, to fix it.

The CDN never caches a redirect, but browsers can reuse one for up to 60 seconds. The edge picks up a newly active domain, or a changed or removed redirect, within about a minute.

Make primary marks the domain as the application's main URL. An application has at most one primary domain, and a redirect domain cannot be primary.

HTTPS

Gigadrive Network issues a Let's Encrypt certificate for each custom domain and renews it before it expires. Plain http:// requests are redirected to https://.

If your domain has CAA records, one of them must allow Let's Encrypt, for example 0 issue "letsencrypt.org". Otherwise the certificate cannot be issued and the domain fails with cert_blocked_caa. SSL certificates lists what a CAA record must contain.

Limits

Custom domains are included in every plan, up to these limits:

Domains in every state except removal count toward the limit, and a domain you add and then remove still counts toward the daily limit. Claiming a hostname counts toward both limits, like adding one. Wildcard domains such as *.example.com are not supported, and a request to add or claim one fails with invalid_domain.

Going over the limits

If your organization moves to a plan with a lower limit, it can end up with more domains than the plan allows. Adding a domain is refused from then on, and the domains you already have are handled as follows:

1. The organization gets a warning email that lists the domains over the limit. The domains keep serving for 14 days from that email.
2. A reminder email goes out 3 days before the grace period ends.
3. When the grace period ends, the domains beyond the limit are suspended with the reason plan_limit, and the organization gets an email that lists them.

Both the per-organization and the per-application limit apply. Domains that serve traffic, meaning Active and Needs attention, keep their place first, then the oldest domains. An organization whose quota override has no limit never has domains suspended.

A suspended domain resumes automatically once the organization is within its limits again, whether you upgrade the plan or remove other domains. It starts over at the DNS check, so it serves again once the check passes. A suspended primary domain stays primary, so it is the application's main URL again when it resumes.

Email notifications

Gigadrive Network emails your organization's owners and admins about custom domains, as well as the member who added the domain if they still belong to the organization. An email goes out when:

• A domain goes live for the first time, or recovers after it failed.
• A domain has needed attention for an hour. While it still needs attention, a reminder follows every 7 days.
• A domain recovers after needing attention. This email waits until 24 hours have passed since the previous one, so a domain that switches back and forth does not send an email each time.
• A domain fails. If it fails again, the next email waits until 24 hours have passed since the previous one.
• Another organization claims the hostname. The email says the domain moved to another organization.
• The organization goes over its limits, 3 days before domains are suspended, and when they are suspended.

Problems on the Gigadrive Network side, such as platform_capacity, send no email, because there is nothing for you to fix.

Remove a domain

1. In Settings > Domains, click Remove next to the domain. The control is a trash icon.
2. Confirm with Remove. If you have not signed in within the last 15 minutes, the console asks you to confirm your identity first.

The domain stops serving your application immediately. Your organization keeps the domain verification, so you can attach the hostname again later without a new TXT record. A domain that Gigadrive staff suspended cannot be removed; contact support.

Move a domain from another organization

A hostname can be attached to one application at a time across Gigadrive Network. If another organization attached a hostname you control, verify the domain for your organization, then claim the hostname for your application. The console has no control for this, so use the CLI or the API:

1. Add the domain for verification with gigadrive domains owners add example.com, or with POST /organizations/{organizationId}/domains and the body {"name": "example.com"}. The response lists the TXT record to publish. Skip this step if your organization already added the domain.
2. At your DNS provider, publish the TXT record.
3. Verify the domain with gigadrive domains owners verify example.com, or with POST /organizations/{organizationId}/domains/{domainId}/verify. If your organization verified the domain earlier, this checks the record again. A failed check leaves the domain verified and shows the problem in the domain's error, for example with the code ownership_record_missing when the record is gone.
4. Claim the hostname with gigadrive domains claim shop.example.com, or with POST /applications/{applicationId}/domains/claim and the body {"hostname": "shop.example.com"}.

Keep the TXT record published. The claim looks the record up again when you make it, and is refused with ownership_not_live if the record is missing, however recently you verified. These calls need a signed-in user or an organization API key; other credentials get 403 with forbidden. A claim made with an application API key also carries reason set to actor_not_allowed. The hostname then serves your application, and the previous attachment stops serving immediately.