Custom domains in Supabase - Deep Dive

Overview - Custom domains

What is it?

Custom domains let you use your own website address instead of a default one provided by a service. For example, instead of myapp.supabase.co, you can use www.myapp.com. This makes your site look professional and easier to remember. It involves linking your domain name to the service hosting your app.

Why it matters

Without custom domains, your app looks less trustworthy and harder to find. People might forget or mistrust long default URLs. Custom domains help build your brand and make your app feel like a real, polished product. They also enable secure connections with HTTPS under your own name.

Where it fits

Before learning custom domains, you should understand what domains and DNS are. After this, you can learn about SSL certificates and HTTPS setup. Later, you might explore advanced DNS features like subdomains and redirects.

Mental Model

Core Idea

A custom domain connects your own website name to the servers hosting your app, making your app reachable at a friendly address you control.

Think of it like...

It's like putting your own house number and street name on your mailbox instead of using a generic apartment number, so visitors find you easily and recognize your place.

┌───────────────┐       ┌───────────────┐       ┌───────────────┐
│ Your Domain   │──────▶│ DNS Provider  │──────▶│ Supabase App  │
│ (www.myapp.com)│       │ (Domain Setup)│       │ (Hosting)     │
└───────────────┘       └───────────────┘       └───────────────┘

Build-Up - 7 Steps

1

Foundation

What is a domain name?

Concept: Introduce the idea of domain names as human-friendly website addresses.

A domain name is the easy-to-remember name you type in a browser to visit a website, like example.com. It replaces hard-to-remember IP addresses, which are numbers computers use to find each other on the internet.

Result

You understand that domain names are the website addresses people use daily.

Knowing what a domain name is helps you see why custom domains matter for user experience.

2

Foundation

How DNS links domains to servers

Concept: Explain DNS as the system that translates domain names to server addresses.

DNS (Domain Name System) works like a phone book. When you type a domain, DNS tells your browser the IP address of the server hosting the site. This lets your browser connect to the right place.

Result

You see how typing a domain leads your browser to the correct server.

Understanding DNS is key to knowing how custom domains connect your name to your app.

3

Intermediate

Setting up a custom domain in Supabase

🤔Before reading on: Do you think setting a custom domain requires changing your app code or just DNS settings? Commit to your answer.

Concept: Learn that custom domains are set by configuring DNS records and Supabase settings, not by changing app code.

To use a custom domain with Supabase, you add your domain in the Supabase dashboard under 'Custom Domains'. Then, you update your domain's DNS records (usually CNAME or A records) to point to Supabase's servers. This links your domain to your app.

Result

Your domain name points to your Supabase app, making it accessible via your own website address.

Knowing that DNS changes, not code changes, enable custom domains helps avoid confusion and errors.

4

Intermediate

Understanding DNS record types for custom domains

🤔Before reading on: Which DNS record type do you think is most common for custom domains: A record or CNAME? Commit to your answer.

Concept: Explain the difference between A records and CNAME records and when to use each for custom domains.

An A record points your domain directly to an IP address. A CNAME record points your domain to another domain name. For Supabase, you usually use a CNAME record pointing to your Supabase app's domain. This makes management easier if the IP changes.

Result

You can correctly choose and set DNS records to link your domain to Supabase.

Understanding DNS record types prevents misconfiguration that can break your domain connection.

5

Intermediate

Adding SSL for secure custom domains

🤔Before reading on: Do you think SSL certificates for custom domains are manual or automatic in Supabase? Commit to your answer.

Concept: Learn how Supabase handles SSL certificates to secure your custom domain with HTTPS.

Supabase automatically provisions SSL certificates for your custom domain using Let's Encrypt. Once your DNS is set correctly, Supabase issues the certificate so your site is secure with HTTPS without extra steps.

Result

Your custom domain supports secure connections, protecting user data and building trust.

Knowing SSL is automatic in Supabase saves time and ensures security best practices.

6

Advanced

Troubleshooting common custom domain issues

🤔Before reading on: What do you think is the most common cause of custom domain setup failure: DNS delay, wrong record type, or missing SSL? Commit to your answer.

Concept: Identify typical problems like DNS propagation delay, incorrect DNS records, or SSL issues and how to fix them.

DNS changes can take time to spread worldwide (up to 48 hours). Using wrong record types or typos in DNS settings causes failures. SSL certificates won't issue if DNS isn't correct. Checking DNS status and waiting patiently solves most issues.

Result

You can diagnose and fix common problems when your custom domain doesn't work immediately.

Understanding delays and common errors helps avoid frustration and speeds up successful setup.

7

Expert

Advanced domain management and multi-environment setups

🤔Before reading on: Can you use multiple custom domains for different app environments (like staging and production) in Supabase? Commit to your answer.

Concept: Explore using multiple custom domains for different app versions and managing DNS for complex setups.

You can assign different custom domains to separate Supabase projects or environments, like staging.myapp.com and www.myapp.com. Managing DNS records carefully ensures traffic goes to the right environment. Using subdomains and wildcard certificates can simplify this.

Result

You can run multiple app versions with distinct custom domains, improving testing and deployment workflows.

Knowing how to manage multiple domains and environments is crucial for professional app development and deployment.

Under the Hood

When you set a custom domain, DNS servers worldwide update their records to map your domain name to Supabase's hosting IP or domain. When a user types your domain, their browser queries DNS, finds Supabase's address, and connects. Supabase then serves your app and provides an SSL certificate to encrypt the connection, ensuring security and trust.

Why designed this way?

This design separates domain naming from hosting, allowing flexibility. DNS is a global, distributed system that efficiently routes users without needing to change app code. Automating SSL with Let's Encrypt reduces manual work and security risks. Alternatives like manual SSL or hardcoded IPs were more error-prone and less scalable.

┌───────────────┐       ┌───────────────┐       ┌───────────────┐       ┌───────────────┐
│ User Browser  │──────▶│ DNS Resolver  │──────▶│ Supabase DNS  │──────▶│ Supabase App  │
│ (requests    │       │ (finds domain)│       │ (returns IP)  │       │ (serves app)  │
│ www.myapp.com)│       └───────────────┘       └───────────────┘       └───────────────┘

Myth Busters - 4 Common Misconceptions

Quick: Do you think setting a custom domain requires changing your app's source code? Commit to yes or no.

Common Belief: You must change your app's code to use a custom domain.

Reality: Custom domains are set up by changing DNS records and Supabase settings, not by modifying app code.

Why it matters: Believing this causes unnecessary code changes and confusion, delaying deployment.

Quick: Do you think DNS changes take effect instantly? Commit to yes or no.

Common Belief: DNS updates happen immediately after saving changes.

Reality: DNS changes can take hours or even days to propagate worldwide due to caching.

Why it matters: Expecting instant changes leads to frustration and repeated incorrect troubleshooting.

Quick: Do you think SSL certificates for custom domains must be manually installed? Commit to yes or no.

Common Belief: You need to manually get and install SSL certificates for your custom domain.

Reality: Supabase automatically provisions SSL certificates for custom domains using Let's Encrypt.

Why it matters: Thinking SSL is manual causes wasted effort and potential security gaps.

Quick: Do you think you can use any DNS record type interchangeably for custom domains? Commit to yes or no.

Common Belief: Any DNS record type (A, CNAME, TXT) works the same for custom domain setup.

Reality: Only specific record types like CNAME or A records are valid for pointing domains; others won't work.

Why it matters: Using wrong record types breaks domain resolution, making your app unreachable.

Expert Zone

1

Some DNS providers cache old records aggressively, so even after correct setup, propagation can be delayed unpredictably.

2

Wildcard SSL certificates can simplify securing multiple subdomains but require careful DNS and certificate management.

3

Using CNAME flattening or ALIAS records can help root domains point to Supabase when CNAME is not allowed at the root.

When NOT to use

Custom domains are not suitable if you want to avoid DNS management or need instant domain changes; in such cases, using the default Supabase domain or a managed proxy service might be better.

Production Patterns

In production, teams use custom domains with automated DNS and SSL monitoring, multi-environment domains for staging and production, and integrate domain setup into CI/CD pipelines for smooth deployments.

Connections

DNS (Domain Name System)

Custom domains build directly on DNS by configuring domain-to-server mappings.

Understanding DNS deeply helps troubleshoot and optimize custom domain setups.

SSL/TLS Certificates

Custom domains require SSL certificates to secure connections via HTTPS.

Knowing how SSL works ensures your custom domain is safe and trusted by users.

Branding and Marketing

Custom domains are a key part of branding, making your app recognizable and trustworthy.

Seeing custom domains as branding tools connects technical setup to business impact.

Common Pitfalls

#1 Setting DNS records with wrong record type.

Wrong approach:

Adding a TXT record instead of a CNAME or A record to point the domain.

Correct approach:

Add a CNAME record pointing your domain to your Supabase app domain.

Root cause:

Confusing DNS record types and their purposes leads to misconfiguration.

#2 Expecting immediate domain availability after DNS change.

Wrong approach:

Changing DNS and immediately testing the domain without waiting for propagation.

Correct approach:

Wait up to 48 hours for DNS changes to propagate before testing the domain.

Root cause:

Not understanding DNS caching and propagation delays causes premature troubleshooting.

#3 Not verifying domain ownership in Supabase dashboard.

Wrong approach:

Skipping domain verification steps and assuming domain works automatically.

Correct approach:

Complete domain verification in Supabase by adding required DNS records.

Root cause:

Missing verification steps prevents SSL issuance and domain activation.

Key Takeaways

Custom domains let you use your own website name instead of a default service address, improving professionalism and trust.

Setting up a custom domain involves configuring DNS records to point your domain to Supabase's servers, without changing app code.

DNS changes take time to propagate, so patience and correct record types are essential for success.

Supabase automates SSL certificate provisioning for custom domains, securing your site with HTTPS effortlessly.

Advanced setups can use multiple custom domains for different environments, requiring careful DNS and SSL management.

Practice

1. What is the main purpose of setting a custom domain in Supabase?

easy

A. To enable faster query execution

B. To increase database storage capacity

C. To create multiple user accounts automatically

D. To use your own website address instead of a default Supabase URL

Solution

1. Step 1: Understand what a custom domain is

   A custom domain lets you use your own website address instead of a generic one provided by a service.

2. Step 2: Relate to Supabase usage

   In Supabase, setting a custom domain means your app uses your own URL, making it look professional and branded.

3. Final Answer:

   To use your own website address instead of a default Supabase URL -> Option D

4. Quick Check:

   Custom domain = Own website address [OK]

Hint: Custom domain means your own website address [OK]

Common Mistakes:

• Thinking it increases database size
• Confusing with performance features
• Assuming it creates user accounts

2. Which DNS record type must you add to point your custom domain to Supabase?

easy

A. CNAME record

B. MX record

C. TXT record

D. SRV record

Solution

1. Step 1: Identify DNS record types for domain pointing

   CNAME records are used to alias one domain name to another, commonly used to point custom domains to services.

2. Step 2: Match with Supabase custom domain setup

   Supabase requires a CNAME record to link your custom domain to their servers.

3. Final Answer:

   CNAME record -> Option A

4. Quick Check:

   Custom domain pointing uses CNAME [OK]

Hint: Use CNAME to point domain to Supabase [OK]

Common Mistakes:

• Using MX record which is for email
• Using TXT record meant for verification
• Confusing SRV record with domain pointing

3. Given this Supabase custom domain setup snippet:

domain: "app.example.com"
records: [
  { type: "CNAME", value: "db.supabase.co" }
]

What happens when a user visits app.example.com?

medium

A. They are redirected to the Supabase database interface

B. Their browser connects to Supabase hosting for the app

C. They get an email verification prompt

D. They see a DNS error because CNAME is incorrect

Solution

1. Step 1: Understand CNAME effect

   The CNAME record points the domain to Supabase's hosting address, so requests go there.

2. Step 2: Interpret user visit behavior

   When visiting app.example.com, the browser connects to Supabase hosting serving the app, not the database interface or errors.

3. Final Answer:

   Their browser connects to Supabase hosting for the app -> Option B

4. Quick Check:

   CNAME directs browser to Supabase hosting [OK]

Hint: CNAME points domain to hosting, not email or errors [OK]

Common Mistakes:

• Confusing database interface with hosting
• Assuming DNS error from correct CNAME
• Thinking email verification appears on visit

4. You set a custom domain in Supabase but get a security warning in browsers. What is the most likely cause?

medium

A. You did not add an MX record

B. You used an invalid domain name format

C. You forgot to enable SSL for the custom domain

D. You set the CNAME to the wrong IP address

Solution

1. Step 1: Identify cause of browser security warnings

   Security warnings usually happen when SSL (secure connection) is missing or invalid.

2. Step 2: Relate to Supabase custom domain setup

   Supabase requires enabling SSL for custom domains to avoid browser warnings.

3. Final Answer:

   You forgot to enable SSL for the custom domain -> Option C

4. Quick Check:

   Missing SSL causes browser security warnings [OK]

Hint: Always enable SSL for custom domains [OK]

Common Mistakes:

• Confusing MX record with SSL
• Thinking domain format causes security warning
• Assuming CNAME IP address is used instead of hostname

5. You want to set up a custom domain dashboard.myapp.com for your Supabase project. Which steps must you follow to ensure it works correctly and securely?

hard

A. Buy the domain, add a CNAME DNS record pointing to Supabase, then enable SSL in Supabase settings

B. Buy the domain, add an MX record pointing to Supabase, then enable SSL in Supabase settings

C. Buy the domain, add a TXT record for verification, then disable SSL to avoid errors

D. Buy the domain, add an A record pointing to Supabase IP, then skip SSL setup

Solution

1. Step 1: Purchase domain and configure DNS

   First, buy your domain (dashboard.myapp.com) and add a CNAME record pointing to Supabase's domain to route traffic correctly.

2. Step 2: Enable SSL for secure connections

   Then, enable SSL in Supabase settings to secure the connection and avoid browser warnings.

3. Final Answer:

   Buy the domain, add a CNAME DNS record pointing to Supabase, then enable SSL in Supabase settings -> Option A

4. Quick Check:

   Domain + CNAME + SSL = Correct setup [OK]

Hint: Domain + CNAME + SSL = working custom domain [OK]

Common Mistakes:

• Using MX or TXT records incorrectly
• Skipping SSL causing security warnings
• Using A record instead of CNAME for Supabase