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.