Setting Up DecapCMS with Cloudflare Pages: A Practical Guide

Published on November 17, 2024

Lukas Himsel Lukas Himsel

DecapCMS stands out as a git-based content management system that brings the best of both worlds - the simplicity of a traditional CMS with the power of version control. Its key advantage lies in allowing content editors to work in a user-friendly interface while storing all content directly in your Git repository.

We at biralo.studio use DecapCMS as a simple solution for content management to our clients across most of our sites.

We deploy it on Cloudflare Pages along our static sites. Here is why and how we are doing it:

Why Choose Cloudflare Pages?

Cloudflare Pages offers several compelling benefits for hosting DecapCMS:

  • Global CDN deployment ensures fast loading times worldwide
  • Seamless Git integration
  • Generous free tier with automatic builds
  • Built-in DDoS protection

Step-by-Step Setup Guide

This is a refined version of an initial approach to run DecapCMS on Cloudflare Pages by Jeremy Nixon.

1. Initial Setup

  1. Create a new repository on GitHub
  2. Clone the repository to your local machine
  3. Initialize a new project with your preferred static site generator

2. Configure DecapCMS

Create a new admin folder in your public directory (the directory that gets published). For Jekyll this would mean, adding it to the project root and making sure the admin folder and its contents are present in the output directory (_site). Then add these files:

Make sure to check the DecapCMS releases on Github and change the version in the index.html file if necessary.

Make sure, that site_domain and base_url don’t end in a slash /.

3. Deploy to Cloudflare Pages

  1. Log into your Cloudflare dashboard
  2. Navigate to Pages
  3. Click “Create a project”
  4. Select your repository
  5. Configure build settings:
    • Build command: Your static site generator’s build command
    • Build output directory: Your public directory
  6. Click “Save and Deploy”

You need to create your Cloudflare Page deployment first without the functioning CMS, to be able to configure OAuth in the next step.

4. Enable GitHub OAuth

  1. Go to GitHub Developer Settings
  2. Create a new OAuth application
  3. Set the homepage URL to your Cloudflare Pages domain incl. the DecapCMS path https://your-site.pages.dev/admin.
  4. Set the authorization callback URL to https://your-site.pages.dev
  5. Add the OAuth credentials to your Cloudflare Pages environment variables:
    • GITHUB_CLIENT_ID
    • GITHUB_CLIENT_SECRET

5. Adding Serverless Functions

Cloudflare Pages Functions are serverless functions that run alongside your static site, enabling server-side functionality without managing traditional servers. They’re perfect for handling authentication, form submissions, and API integrations - making them ideal for DecapCMS’s GitHub OAuth requirements.

Setting Up Functions

  1. Create a functions/api directory in your project root. This means the actual top-level of the project itself, not the top level of your output directory. So, if you’re using Jekyll, functions goes at the top of the project next to your collections, _layouts, _includes and so forth, not inside the output (_site) or assets directory.

  2. Add the OAuth handler functions:

  1. Make sure the necessary environment variables (GITHUB_CLIENT_ID and OAUTH_CLIENT_SECRET) are accessible to the functions in your Cloudflare Pages Functions.

The functions will automatically be deployed with your site and handle the OAuth authentication flow at the /api/auth endpoint. Cloudflare will automatically detect and deploy your functions, making them available globally across their network.

This serverless approach eliminates the need for a separate authentication server while maintaining high performance and security.

6. Check DecapCMS Configuration Options

Now you can configure all your collections and content schema. DecapCMS offers a range of settings for content management that can be found here.

Best Practices

This setup provides a robust, scalable solution for content management that grows with your needs while maintaining security and performance standards.

Previous Home Next