# Custom Domains

You can configure a custom domain to point to your Filebase Site, allowing visitors to access your IPFS-hosted content through your own branded URL.

## Prerequisites

Before setting up a custom domain, ensure you have:

* A **paid Filebase plan** (Starter, Pro, or Unlimited)
* A **registered domain name** with access to DNS settings
* An **existing Filebase Site** created and configured with content

## Setting Up a Custom Domain

### Step 1: Add the Custom Domain in Filebase

1. Navigate to the **Sites** section in the Filebase dashboard.
2. Select the site you want to configure with a custom domain.
3. Click **Add Custom Domain**.
4. Enter your custom domain (e.g., `www.example.com` or `docs.example.com`).
5. Click **Save**. Filebase will display the required DNS configuration.

### Step 2: Configure Your DNS

Add a CNAME record in your domain's DNS settings:

| Type  | Name                      | Value                         |
| ----- | ------------------------- | ----------------------------- |
| CNAME | `www` (or your subdomain) | `{site-name}.myfilebase.site` |

For example, if your site name is `my-dapp` and you want to use `www.example.com`:

| Type  | Name  | Value                     |
| ----- | ----- | ------------------------- |
| CNAME | `www` | `my-dapp.myfilebase.site` |

{% hint style="info" %}
DNS changes can take up to 48 hours to propagate globally, though most changes are visible within a few minutes to a few hours.
{% endhint %}

### Step 3: Verify Domain Configuration

1. Return to your site settings in Filebase.
2. The custom domain status will show as **Pending** while DNS propagates.
3. Once DNS is verified, the status will change to **Active**.
4. Filebase will automatically provision an SSL certificate for your domain.

### Step 4: SSL Certificate Provisioning

After DNS verification:

1. Filebase automatically requests an SSL certificate via cert-manager.
2. Certificate provisioning typically completes within a few minutes.
3. Once complete, your site will be accessible via HTTPS at your custom domain.

{% hint style="success" %}
SSL certificates are automatically renewed before expiration. No manual intervention is required.
{% endhint %}

## Using Apex Domains

If you want to use an apex domain (e.g., `example.com` without `www`), the configuration depends on your DNS provider:

### DNS Providers with CNAME Flattening

Some DNS providers support CNAME flattening or ALIAS records at the apex:

* **Cloudflare**: Use a CNAME record at the apex (automatically flattened)
* **DNSimple**: Use an ALIAS record
* **Route 53**: Use an ALIAS record
* **NS1**: Use a linked record

| Type        | Name | Value                         |
| ----------- | ---- | ----------------------------- |
| CNAME/ALIAS | `@`  | `{site-name}.myfilebase.site` |

### DNS Providers Without CNAME Flattening

If your DNS provider doesn't support apex CNAME records:

1. Use a subdomain like `www.example.com` for your Filebase Site
2. Set up a redirect from your apex domain to the www subdomain

{% hint style="warning" %}
Standard DNS does not allow CNAME records at the apex. Check if your DNS provider offers CNAME flattening, ALIAS, or ANAME records as alternatives.
{% endhint %}

## Troubleshooting

### Domain Shows as Pending

If your domain stays in "Pending" status:

1. **Verify DNS configuration**: Ensure the CNAME record is correctly set up
2. **Check propagation**: Use a tool like [dnschecker.org](https://dnschecker.org) to verify DNS propagation
3. **Wait for propagation**: DNS changes can take up to 48 hours
4. **Check for conflicts**: Ensure no other records conflict with your CNAME

### SSL Certificate Not Provisioning

If SSL certificate provisioning fails:

1. **Verify DNS is active**: The domain must resolve correctly before SSL can be provisioned
2. **Check for CAA records**: If you have CAA records, ensure they allow Let's Encrypt (`letsencrypt.org`)
3. **Wait and retry**: Certificate provisioning may take a few minutes

### Site Not Loading

If your custom domain isn't serving your site:

1. **Clear browser cache**: Try accessing in incognito mode
2. **Check HTTPS**: Ensure you're using `https://` not `http://`
3. **Verify site content**: Confirm your site has content associated with it
4. **Check DNS**: Verify the CNAME points to the correct Filebase subdomain

## Removing a Custom Domain

To remove a custom domain:

1. Navigate to your site settings in Filebase.
2. Click **Remove** next to the custom domain.
3. Confirm the removal.

After removal, the domain will no longer serve your site content. Remember to update or remove the DNS records at your domain registrar.

## Multiple Custom Domains

Currently, each site supports one custom domain. If you need multiple domains pointing to the same content:

1. Set up redirects at your DNS provider or use a redirect service
2. Create separate sites with the same CID for each domain needed