From 09fa366e6b26dc949037f32836ff9ee60ddcd9fc Mon Sep 17 00:00:00 2001
From: Div Arora <root@darora.com>
Date: Wed, 19 Oct 2022 13:43:17 +0800
Subject: [PATCH] chore: adds instructions for setting up custom hostnames

---
 .../docs/guides/cli/custom-hostnames.mdx      | 69 +++++++++++++++++++
 1 file changed, 69 insertions(+)
 create mode 100644 apps/reference/docs/guides/cli/custom-hostnames.mdx

diff --git a/apps/reference/docs/guides/cli/custom-hostnames.mdx b/apps/reference/docs/guides/cli/custom-hostnames.mdx
new file mode 100644
index 00000000000..15c8304a93b
--- /dev/null
+++ b/apps/reference/docs/guides/cli/custom-hostnames.mdx
@@ -0,0 +1,69 @@
+---
+id: custom-domains
+title: Custom Domains
+description: Configuring a Custom Domain for your Supabase project.
+---
+
+import Tabs from '@theme/Tabs'
+import TabItem from '@theme/TabItem'
+
+:::note
+
+Custom Domains are currently in beta, and are being slowly made available to projects.
+
+:::
+
+## Overview
+
+Custom domains allow you to present a branded experience to your users. You can also use a subdomain for the purposes of this guide.
+
+Before you start, here are some prerequisites:
+
+- [Install the Supabase CLI](/docs/guides/cli) 1.10.1+
+- Ensure that you've configured the CLI for your account
+- A Supabase project (create a new one if you don't already have one)
+- Ensure that you've subscribed to the Custom Domains add-on
+
+## Configure a Custom Domain
+
+Setting up a custom domain (`api.example.com`) for your Supabase project (ref `foobarbaz`, with assigned endpoints at `foobarbaz.supabase.co`) involves a few steps.
+
+1) Set up a CNAME record for `api.example.com`, resolving to `foobarbaz.supabase.co.`, with as low a TTL as possible.
+
+2) Use the `create` subcommand of the CLI to initiate the process:
+
+```bash
+supabase custom-hostname create --project-ref foobarbaz --custom-hostname api.example.com --experimental
+```
+
+3) The output of the `create` command includes two TXT records you will need to set up, in order to verify your control over the domain in question, and for us to issue SSL certificates for it. For example:
+
+```
+[...]
+Required outstanding validation records:
+        _cf-custom-hostname.api.example.com TXT -> 46BBC14D-D50A-409C-8DB5-F862CF5BA660
+        api.example.com TXT -> ca3-F1HvR9i938OgVwpCFwi1jTsbhe1hvT0Ic3efPY3Q
+```
+
+Set up both records as instructed, and then use the `reverify` command for the Supabase Platform to verify the records:
+
+```bash
+supabase custom-hostname reverify --project-ref foobarbaz --experimental
+```
+
+You might need to wait a few minutes before your updated DNS records get propagated, especially if the older records were using a high TTL. Upon successful verification, you will be able to proceed to the final activation step:
+
+```
+Custom hostname configuration complete, and ready for activation.
+```
+
+4) The final activation step reconfigures your project to start serving traffic on your custom domain (`api.example.com`). The auth service, in particular, will no longer work with the original URL (`foobarbaz.supabase.co`). As such, it is recommended that you schedule a downtime window of 20-30 minutes, depending on the complexity of your project, to update all the services that need to know about your custom domain:
+
+- any client code (e.g., frontends, mobile apps)
+- any OAuth providers (e.g., google, github)
+
+Additionally, update the DNS configuration for `api.example.com` to once more use a CNAME record that resolves to `foobarbaz.supabase.co`. Finally, you can use the `activate` subcommand to reconfigure your project:
+
+```bash
+supabase custom-hostname activate --project-ref foobarbaz --experimental
+```