From 3ea3c176100a7ea8fc568c6dbb493b6e7d98a622 Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 16 Apr 2026 16:39:21 +0530 Subject: [PATCH] docs: add domain status workflows and protocol management coverage Document the domain verification and certificate status lifecycle (created/verifying/verified/unverified) across Sites, Functions, and project custom domains so users can troubleshoot domain setup issues. Add new Protocols docs page for per-project REST/GraphQL/WebSocket enable/disable. Add changelog entry covering both features. Co-Authored-By: Claude Opus 4.6 (1M context) --- .../changelog/(entries)/2026-04-16.markdoc | 20 ++++ .../docs/advanced/platform/+layout.svelte | 4 + .../docs/advanced/platform/+page.markdoc | 8 +- .../platform/custom-domains/+page.markdoc | 36 +++++++ .../advanced/platform/protocols/+page.markdoc | 101 ++++++++++++++++++ .../products/functions/domains/+page.markdoc | 38 ++++++- .../docs/products/sites/domains/+page.markdoc | 40 ++++++- 7 files changed, 244 insertions(+), 3 deletions(-) create mode 100644 src/routes/changelog/(entries)/2026-04-16.markdoc create mode 100644 src/routes/docs/advanced/platform/protocols/+page.markdoc diff --git a/src/routes/changelog/(entries)/2026-04-16.markdoc b/src/routes/changelog/(entries)/2026-04-16.markdoc new file mode 100644 index 0000000000..3a49a4caa3 --- /dev/null +++ b/src/routes/changelog/(entries)/2026-04-16.markdoc @@ -0,0 +1,20 @@ +--- +layout: changelog +title: "Domain status workflows and protocol management in project settings" +date: 2026-04-16 +--- + +Appwrite now provides clearer visibility into **domain verification and certificate status** across Sites, Functions, and project custom domains. The Console displays real-time status indicators so you can track each domain through its lifecycle: + +- **Verification failed** — DNS records have not been verified yet. Check your CNAME or NS record configuration and retry. +- **Generating certificate** — DNS verified successfully; a TLS certificate is being issued. +- **Certificate generation failed** — Certificate issuance did not complete. Retry verification or check your CAA records. +- **Verified** — Domain is fully active with a valid TLS certificate. + +These statuses appear in the **Domains** tab for Sites, Functions, and project settings, along with timestamps showing when the status was last checked or updated. + +Additionally, you can now **enable or disable individual protocols** (REST, GraphQL, and WebSocket) per project from the project settings. This gives you fine-grained control over which API protocols are accessible for your project. + +{% arrow_link href="/docs/products/sites/domains" %} +Learn more about domain status workflows +{% /arrow_link %} diff --git a/src/routes/docs/advanced/platform/+layout.svelte b/src/routes/docs/advanced/platform/+layout.svelte index 5e1739b622..08e49b2828 100644 --- a/src/routes/docs/advanced/platform/+layout.svelte +++ b/src/routes/docs/advanced/platform/+layout.svelte @@ -126,6 +126,10 @@ label: 'Custom domains', href: '/docs/advanced/platform/custom-domains' }, + { + label: 'Protocols', + href: '/docs/advanced/platform/protocols' + }, { label: 'Message templates', href: '/docs/advanced/platform/message-templates' diff --git a/src/routes/docs/advanced/platform/+page.markdoc b/src/routes/docs/advanced/platform/+page.markdoc index d85400548e..2f2659fae9 100644 --- a/src/routes/docs/advanced/platform/+page.markdoc +++ b/src/routes/docs/advanced/platform/+page.markdoc @@ -87,7 +87,7 @@ Appwrite provides special plans for open source projects. # Configuration {% #configuration %} -Configure custom domains and customize communication templates. +Configure custom domains, API protocols, and customize communication templates. {% cards %} {% cards_item @@ -96,6 +96,12 @@ Configure custom domains and customize communication templates. Add a custom domain for your Appwrite APIs. {% /cards_item %} +{% cards_item + href="/docs/advanced/platform/protocols" + title="Protocols" %} +Enable or disable REST, GraphQL, and WebSocket protocols for your project. +{% /cards_item %} + {% cards_item href="/docs/advanced/platform/message-templates" title="Message templates" %} diff --git a/src/routes/docs/advanced/platform/custom-domains/+page.markdoc b/src/routes/docs/advanced/platform/custom-domains/+page.markdoc index a0bd9bb743..c85f612827 100644 --- a/src/routes/docs/advanced/platform/custom-domains/+page.markdoc +++ b/src/routes/docs/advanced/platform/custom-domains/+page.markdoc @@ -37,6 +37,42 @@ This will allow browsers to respect the Appwrite sessions cookies as they are se With these steps, your Appwrite project will accept API requests from your custom domain. +# Domain status {% #domain-status %} + +After adding a custom domain, the Console tracks the domain through its verification and certificate lifecycle. The following statuses may appear in the **Custom domains** section of your project settings: + +{% table %} + +- Status +- Description +- Action + +--- + +- Verification failed +- DNS records have not been verified. The CNAME record is missing or points to the wrong target. +- Verify that the CNAME record has been added correctly at your domain registrar and retry. DNS propagation can take up to 48 hours. + +--- + +- Generating certificate +- DNS verification succeeded and a TLS certificate is being issued. +- No action needed. Certificate generation typically completes within a few minutes. + +--- + +- Certificate generation failed +- The TLS certificate could not be issued. This can happen if a CAA record restricts which certificate authorities can issue for your domain. +- Ensure that your DNS provider allows `certainly.com` as an authorized certificate authority in your CAA records. Retry verification from the Console. + +--- + +- Verified +- The domain is fully active with a valid TLS certificate. +- No action needed. Your Appwrite API endpoint is ready on this domain. + +{% /table %} + If you encounter any issues during the setup process or have questions, don't hesitate to [contact us](/contact-us), and we'll be happy to assist you. # Add a CNAME record {% #cname-record %} diff --git a/src/routes/docs/advanced/platform/protocols/+page.markdoc b/src/routes/docs/advanced/platform/protocols/+page.markdoc new file mode 100644 index 0000000000..a5ff1dfe73 --- /dev/null +++ b/src/routes/docs/advanced/platform/protocols/+page.markdoc @@ -0,0 +1,101 @@ +--- +layout: article +title: Protocols +description: Learn how to enable or disable API protocols like REST, GraphQL, and WebSocket for your Appwrite project. +--- + +Appwrite exposes three protocols for interacting with your project: REST, GraphQL, and WebSocket (Realtime). Each protocol can be independently enabled or disabled per project, giving you control over which access methods are available to your application. + +By default, all three protocols are enabled when you create a new project. + +# Available protocols {% #available-protocols %} + +{% table %} + +- Protocol +- Description +- Default + +--- + +- REST +- HTTP-based API for standard request-response interactions. Used by all Appwrite SDKs and the Console. +- Enabled + +--- + +- GraphQL +- Query language API available at `/v1/graphql`. Supports queries and mutations for all Appwrite resources except OAuth. +- Enabled + +--- + +- WebSocket +- Persistent connection protocol powering the [Realtime](/docs/apis/realtime) service. Enables live subscriptions to Appwrite events. +- Enabled + +{% /table %} + +# Enable or disable a protocol {% #enable-or-disable %} + +You can toggle individual protocols from the Appwrite Console or using a Server SDK. + +## Console + +1. Navigate to your project in the [Appwrite Console](https://cloud.appwrite.io). +2. Click **Settings** in the left sidebar. +3. Under the **Protocols** section, toggle each protocol on or off. +4. Changes take effect immediately. + +## Server SDK + +You can also update protocol status programmatically using the `updateProtocolStatus` method on the Project service. + +{% multicode %} +```server-nodejs +const { Client, Project, ProtocolId } = require('node-appwrite'); + +const client = new Client() + .setEndpoint('https://.cloud.appwrite.io/v1') + .setProject('') + .setKey(''); + +const project = new Project(client); + +// Disable GraphQL for this project +await project.updateProtocolStatus( + ProtocolId.Graphql, // protocolId + false // enabled +); +``` +```server-python +from appwrite.client import Client +from appwrite.services.project import Project +from appwrite.enums import ProtocolId + +client = (Client() + .set_endpoint('https://.cloud.appwrite.io/v1') + .set_project('') + .set_key('')) + +project = Project(client) + +# Disable GraphQL for this project +project.update_protocol_status( + protocol_id=ProtocolId.GRAPHQL, + enabled=False +) +``` +{% /multicode %} + +The `protocolId` parameter accepts one of: `rest`, `graphql`, or `websocket`. + +{% info title="Disabling REST" %} +The Appwrite Console and all Appwrite SDKs rely on the REST protocol. Disabling REST will prevent Console access and SDK operations for the project. Only disable REST if your project is accessed exclusively through GraphQL or Realtime. +{% /info %} + +# Use cases {% #use-cases %} + +- **Security hardening** — Disable protocols your application does not use to reduce the project's attack surface. For example, if your app only uses REST, disable GraphQL and WebSocket. +- **Compliance** — Some environments require restricting available network protocols. Protocol management lets you enforce these requirements at the project level. +- **Development workflow** — Enable all protocols during development for flexibility, then disable unused protocols before moving to production. diff --git a/src/routes/docs/products/functions/domains/+page.markdoc b/src/routes/docs/products/functions/domains/+page.markdoc index bcf3a9bcae..2d2c89bdfd 100644 --- a/src/routes/docs/products/functions/domains/+page.markdoc +++ b/src/routes/docs/products/functions/domains/+page.markdoc @@ -61,4 +61,40 @@ Learn more about edge network DNS records can take up to 48 hours to propagate. -When both **VERIFICATION STATUS** and **CERTIFICATE STATUS** are green, the new domain is ready to use. +# Domain status {% #domain-status %} + +After adding a custom domain, the Console displays a status indicator tracking the domain through verification and certificate issuance. These statuses help you understand where a domain is in the setup process and troubleshoot issues. + +{% table %} + +- Status +- Description +- Action + +--- + +- Verification failed +- DNS records have not been verified. The CNAME record is missing or misconfigured. +- Check that the CNAME record has been added at your domain registrar and retry verification. DNS changes can take up to 48 hours to propagate. + +--- + +- Generating certificate +- DNS verification succeeded and a TLS certificate is being issued for your domain. +- No action needed. Certificate generation typically completes within a few minutes. + +--- + +- Certificate generation failed +- The TLS certificate could not be issued. This can happen if a CAA record restricts which certificate authorities can issue certificates for your domain. +- Ensure that your DNS provider allows `certainly.com` as an authorized certificate authority in your CAA records. Retry verification from the Console. + +--- + +- Verified +- The domain is fully active with a valid TLS certificate. No status badge is shown. +- No action needed. The domain is ready to serve traffic. + +{% /table %} + +If verification or certificate generation fails, you can retry from the domain's row in the **Domains** tab. The Console also displays a timestamp showing when the status was last checked or updated. diff --git a/src/routes/docs/products/sites/domains/+page.markdoc b/src/routes/docs/products/sites/domains/+page.markdoc index 685d922909..4c67033018 100644 --- a/src/routes/docs/products/sites/domains/+page.markdoc +++ b/src/routes/docs/products/sites/domains/+page.markdoc @@ -126,7 +126,45 @@ To add a subdomain: DNS records can take up to 48 hours to propagate. Once verified, the domain is ready to use. -## Domain rule types +## Domain status {% #domain-status %} + +After adding a custom domain, the Appwrite Console displays a status indicator that tracks the domain through its verification and certificate lifecycle. Understanding these statuses helps you troubleshoot domain setup issues. + +{% table %} + +- Status +- Description +- Action + +--- + +- Verification failed +- DNS records have not been verified. The CNAME, NS, or ALIAS record is missing or misconfigured. +- Check that the correct DNS record has been added at your domain registrar and retry verification. DNS changes can take up to 48 hours to propagate. + +--- + +- Generating certificate +- DNS verification succeeded and a TLS certificate is being issued for your domain. +- No action needed. Certificate generation typically completes within a few minutes. + +--- + +- Certificate generation failed +- The TLS certificate could not be issued. This can happen if a CAA record restricts which certificate authorities can issue certificates for your domain. +- Ensure that your DNS provider allows `certainly.com` as an authorized certificate authority in your CAA records. Retry verification from the Console. + +--- + +- Verified +- The domain is fully active with a valid TLS certificate. No status badge is shown. +- No action needed. The domain is ready to serve traffic. + +{% /table %} + +The Console also displays a timestamp showing when the status was last checked or updated. If verification or certificate generation fails, you can retry from the domain's row in the **Domains** tab. + +## Domain rule types {% #domain-rule-types %} When adding a custom domain to your Appwrite site, you'll need to select one of the following rule types that determine how your domain will behave: