Login

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.").

>
  1. 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.