Setting up CORS for a Docly website Last updated: 14. May 2025

This document provides a step-by-step guide on how to configure Cross-Origin Resource Sharing (CORS) for your Docly website, enabling secure interactions with resources from different origins.

Understanding CORS and Its Importance

CORS is essential for web applications that need to make controlled cross-origin requests. For example, when you are creating an API that a website/webapp on another domain wants to access.

Security: CORS helps protect users by preventing malicious websites from making unauthorized requests to your domain
Controlled access: You can explicitly define which origins can access your resources
API integration: Allows your Docly site to securely interact with external APIs

Below is a reference table of the key CORS HTTP headers and their purposes:

HTTP Header	Purpose
Access-Control-Allow-Origin	Controls which origins can access your resources
Access-Control-Allow-Methods	Specifies which HTTP methods are permitted
Access-Control-Allow-Headers	Defines which headers can be included in requests

Prerequisite: How to Set Custom Headers in Docly

To define custom HTTP headers for your Docly website or web application, you first need to create the `#/Headers.json` file.

{
    "X-Custom-Header": "My custom value for all pages in this section",
    "Another-Header": "Another specific value"
}

In the `Headers.json` file, as shown in the example above, each top-level key (like `"X-Custom-Header"` or `"Another-Header"`) defines an HTTP header name, and its corresponding string value (like `"My custom value for all pages in this section"`) defines the HTTP header value.

These headers will be applied to the responses from your Docly site. This `Headers.json` mechanism is what you will use to add the necessary CORS headers, as detailed in the next chapter.

Step-by-Step: Configuring CORS Headers in Docly

With the `Headers.json` file in place (as described in the prerequisite chapter), you can now add the specific CORS headers required for your website. Below are common configurations to suit different security needs.

> Example 1: Allowing requests from a specific origin

This is the most secure approach if you know which domain(s) will be accessing your resources.

{
    "Access-Control-Allow-Origin": "https://your-client-domain.com",
    "Access-Control-Allow-Methods": "GET, POST, OPTIONS",
    "Access-Control-Allow-Headers": "Content-Type, Authorization, X-Requested-With",
    "Access-Control-Max-Age": "86400",
    "Vary": "Origin" 
}

Explanation of this configuration:

`Access-Control-Allow-Origin: "https://your-client-domain.com"`: Only allows requests originating from `https://your-client-domain.com`.
`Access-Control-Allow-Methods: "GET, POST, OPTIONS"`: Permits GET, POST, and preflight OPTIONS requests.
`Access-Control-Allow-Headers: "Content-Type, Authorization, X-Requested-With"`: Allows requests that include these headers.
`Access-Control-Max-Age: "86400"`: Allows the browser to cache the preflight (OPTIONS) response for 24 hours.
`Vary: "Origin"`: Advises caches that the response may differ based on the `Origin` request header, which is important for CORS.

> Example 2: Allowing requests from any origin (use with extreme caution)

This configuration is less secure and should generally be avoided unless your resources are explicitly public and pose no security risk. If you need to support credentials (cookies, HTTP authentication), `Access-Control-Allow-Origin: "*"` is incompatible with `Access-Control-Allow-Credentials: true`.

{
    "Access-Control-Allow-Origin": "*",
    "Access-Control-Allow-Methods": "GET, OPTIONS",
    "Access-Control-Allow-Headers": "Content-Type"
}

To apply, simply add these key-value pairs to your `Headers.json` file. If the file already contains other headers, add the CORS headers as new entries in the JSON object.

Verifying and Troubleshooting Your CORS Setup

After implementing CORS headers, it's crucial to test your configuration to ensure it works as intended and doesn't inadvertently block legitimate requests or expose resources too broadly.

> Using Browser Developer Tools:

Make a cross-origin request from your client application (or a test page) to your Docly site.
Open your browser's Developer Tools (usually F12) and navigate to the 'Network' tab.
Examine the request that was made to your Docly site. Check its 'Response Headers' section. You should see the `Access-Control-Allow-Origin` and other CORS headers you configured.
Check the 'Console' tab for any CORS-related error messages. Browsers provide descriptive errors if a CORS request is blocked (e.g., "No 'Access-Control-Allow-Origin' header is present on the requested resource.").

> 2. Using `curl` or similar tools:

You can send a request with a specific `Origin` header to simulate a cross-origin request:

curl -H "Origin: https://your-client-domain.com" -I https://your-docly-site.com/some-resource

Replace `https://your-client-domain.com` with the origin you intend to allow, and `https://your-docly-site.com/some-resource` with a URL on your Docly site.

The `-I` flag fetches headers only. Inspect the output for the CORS headers.

Common Troubleshooting Points:

Typos: Double-check header names and values in `Headers.json` for typos.
Specificity of `Access-Control-Allow-Origin`: If not using `*`, ensure the domain, protocol, and port (if non-standard) exactly match the `Origin` header sent by the client.
Preflight (OPTIONS) Requests: For requests with methods other than GET, HEAD, POST (with simple Content-Types), or that include custom headers, the browser first sends an OPTIONS request (preflight). Ensure your server responds correctly to OPTIONS requests, including the necessary `Access-Control-Allow-Methods` and `Access-Control-Allow-Headers`.
Caching: Browser or server-side caching might serve stale headers. Clear caches or use a private/incognito browsing window for testing. Remember the `Access-Control-Max-Age` directive for preflight response caching.
Server-side Issues: Ensure Docly (or any reverse proxy/CDN in front of it) is correctly reading and applying the `Headers.json` file. Check server logs if possible.