Custom Domains

Appwrite custom domains feature allows you to use your self-owned domain name as your Appwrite API endpoint. A recent change made in modern browsers will not allow your web app to use 3rd party cookies. This change is done to protect your users' privacy from malicious web tracking services.

When accessing Appwrite from a 3rd party domain, like appwrite.io or example.com, some browsers will treat our secure cookies as 3rd party cookies and block them, as a fallback Appwrite will store your users' sessions on the browser localStorage.

Using localStorage is very convenient to help you get started quickly with Appwrite, but it is not the best practice for your users' security. The browser localStorage can't protect your users' sessions from being hijacked by a 3rd party script or an XSS vulnerability in your web app.

To overcome these issues and make sure your web application works securely on all browsers, Appwrite allows you to access the Appwrite API using your own private custom domain. When accessing Appwrite from the same domain as the one your app uses, Appwrite cookies will no longer be treated as 3rd party cookies by any browser and will store your users' sessions securely.

For example, if your app runs on my-app.com, you can set the subdomain appwrite.my-app.com to access the Appwrite API. This will allow browsers to respect the Appwrite sessions cookies as they are set on the same domain as your app.

Add Your Domain

You can set your domain name by adding it to your Appwrite project settings page under the 'Custom Domains' tab. After you added your new domain to your project settings from the dashboard, you will need to create a new CNAME DNS record at your DNS provider dashboard.

Add a CNAME Record

A CNAME record (or a Canonical Name record) is a type of resource record in the Domain Name System (DNS), which maps one domain name (an alias) to another.

Every DNS host has its own way of updating DNS settings, and, unfortunately, their dashboard interfaces usually aren't the most intuitive. We recommend that you read the help documentation of your DNS host, also do not hesitate to contact their support for help with their interface and settings.

Below, you'll find a list of registrars and links to their DNS setting documentation. If your domain provider isn't listed above, please contact us, and we'll include their settings as well.

Confirm and Verify Your Domain

Once you added your new CNAME record to your DNS settings, you will need to verify your new domain name from your Appwrite console. Enter your custom domains tab from your project settings, click the DNS Settings link and click on the 'Confirm and Verify" button. If everything went well, Appwrite will approve your domain and generate a new SSL certificate for it in the background.

Enjoy your Free SSL Certificate

Appwrite uses Let's Encrypt service to generate free and automated SSL certificates for your custom domains. Once your domain is verified, it will take the Appwrite server a few seconds to create a new SSL certificate for it. Once done, you will see your domain TLS setting marked as 'Enabled' in your Appwrite dashboard, and you will be able to connect the Appwrite API using your new domain.

Connect using Your Custom Domain

To connect with your Appwrite server using your new domain, you will have to use the 'setEndpoint' (or 'set_endpoint') method in your SDK of choice and pass your new domain value, for example:

// Init your Web SDK
var appwrite = new Appwrite();

appwrite
    .setEndpoint('https://appwrite.example.com/v1')
    .setProject('[PROJECT_ID]')
;