How to host a Digital Garden on Cloudflare

I’ve created a few sites using Ole’s GitHub – oleeskild/digitalgarden and Cloudflare Pages. When I was first getting setup, there were precious few guides out there on the matter, and nothing that was very concise or straightforward.

To that end, I’ve created this guide on configuring Cloudflare as a host for your Digital Garden

Update 01/22/2024: I updated the instructions below on how to CORRECTLY pass-through security headers for Cloudflare. The method described prior will get overwritten every time there is a template update, and the new instructions below will persist between updates. -Max

I’ll share the original guide I used, even though it gets a critical piece of information wrong. However, it’s still interesting, and I want to share it here for posterity: How I Published My Knowledge Base Online for Free If you used Sharaf’s guide on publishing to Cloudflare, the critical point he missed is the Build Configuration. Specifically, you need to set the “Build command” to npm run build and the “Build output directory” to /dist. I hope you’ll stick around anyway, because I touch on some security topics he never covered.

One last thing; I originally wrote this guide in Obsidian and published it with Digital Garden, but the pictures were too powerful and I moved it here. However, as I published this, I was waiting for my original notes to sync, and so some of the links were not updated. However, you can find the whole site at wisdump.work, and find other useful tidbits of information that are too small or dynamic to add to WordPress. Additionally, I’m still getting used to formatting in WordPress, so please bear with me. Cheers! -Max

Anyway, let’s get started.

Steps to Publish Cloudflare

Prep-work

In order to complete this project, you will need to do the following:

Install the Digital Garden plugin on your Obsidian app.
Create a GitHub account if you don’t already have one.
Create a Cloudflare account.

Setup GitHub Repository and Access Token

Now that you’ve got your accounts in order, you need to use the Digital Garden Repo Template to create your site’s repository (also known as a “repo”).

Create the Repo

Go to this repository, click “Use this Template,” and select “Create a new repository“

NOTE: If you don’t see the Template button, you may need to either maximize the page or zoom out.

On the following page, configure the repo as follows:

Do not check the box to “Include all branches“
Enter a name and description for the repository
Set the repository as Public or Private
1. This doesn’t have any impact on the function of the site, but you may or may not want to share the page source.

Example configuration for my idea-dumpsite, wisdump.work

Create an access token to the Repo for Digital Garden

Here is Oleeskild’s original guide to create a fine grained access token

To connect the plugin with your Repo, you will need to generate a Fine-Grained Access Token from GitHub.¹

From within GitHub, click on your profile icon at the top-right corner
1. Select “Settings“
2. In the left bar, select “Developer Settings“
3. In the left bar, expand “Personal access tokens” and select “Fine-grained tokens“
4. Click “Generate new token“
Configure the token with the following information:
1. Main settings
  1. Token name
  2. Token expiration date
    1. The expiration date cannot be further than a year.
    2. Once a token expires, it will need to be regenerated for the Digital Garden to maintain access.
    3. IIRC, you can just reactivate the token, but you may need to copy/paste the token back into the plugin.
2. Repository Access
  1. “Only select repositories” and select the repository
3. Repository Permissions
  1. Contents: Read and write
  2. Pull Requests: Read and write
Generate token – DO NOT EXIT THIS PAGE
1. This is the only time on GitHub that you will be able to see this token!
  1. If you DID navigate away from this page, it’s not a big deal; you just have to create another.
  2. Feel free to save it to your preferred password manager or copy it right into the Obsidian plugin.
Copy and paste the token from GitHub into the Digital Garden plugin in Obsidian.
1. Open Obsidian, then go to Settings, and in the left column under Community Plugins select Digital Garden, and enter the Repo name, your user account name, and the Fine-Grained Token you just created.

Configure Obsidian Plugin and Pages

Once you’ve got your Repo and Plugin connected, there are some settings you should adjust in the plugin to further customize your site.

If you made these changes before you connect to Cloudflare, you might have to re-apply them later. However, clicking “Apply” will make them all take effect at once, conserving the number of builds you use.

Configure the Plugin

Nothing here is hard and fast, but some observations I’ve made:

Features
1. I like turning almost all of the Features on, excluding Frontmatter, which can break the site
Appearance
1. I change the theme to match my current theme so I know what the site will look like
2. Enter a site name
3. Assign a favicon
  1. A favicon is the little picture in the tab of your browser.
  2. Unfortunately, the favicon needs to be an svg file and square, which can be difficult to find or make.
    1. There are some free SVG converters online, so if you already have an image, you could start there.
  3. If you update the Favicon after you create your site, you may need to purge your browser’s cache before you will see it take effect.
4. Add Timestamps to pages
  1. WARNING: If you have a lot of pages and choose to update this later on, it will update every page as its own job.
  2. WARNING: If you use a tool like Resilio Sync to share your vault between computers, it will change the metadata of the file, and you are likely to get unexpected changes to the Created and Modified dates of your files.

If you have any questions about other settings, check out the Digital Garden guide or join the Discord server

Add Properties to Pages

Now that the plugin has been configured, we can start adding pages to be published. We do this by adding specific properties to every page we want to publish, and while there are several properties you can use to configure your pages, there are two that are required for you to have a functioning site.

dg-home
1. You need exactly one page with this property set to True (or with a checked box).
  1. This sets the home page for your site, and you can’t have two home pages.
2. NOTE: If you want a title on your homepage, you will have to use a heading as the file name won’t be visible.
dg-publish
1. You need this set to True on every page you wish to publish

I you do not see a “Properties” section at the top of your page, you can create one in a few different ways.

Using three dashes --- in the first line
Clicking the three-dot menu at the top right, and selecting “Add Property”
Hitting Ctrl+; on your keyboard
Opening the Command Palette and choosing one of several options:
1. Add file property
2. Add publish flag
3. … Probably others, but I’ll let you do the research.

Once you’ve created a Property, you need to set it as a checkbox.

When you’re ready to publish, you have a few options.

You could open the Command Palette and select Publish all notes or Publish single note.

NOTE: You can configure hotkeys in Obsidian’s Settings to make publication easier. The combination here is intuitive for me, and doesn’t have any overlapping uses.

Or you could use the Digital Garden Publication Center and pick from a more nuanced-selection of options.

Configure Cloudflare

Now that your Vault is ready for Prime Time, let’s get it setup in Cloudflare

Create the Pages Application

Log in to Cloudflare, expand the left menu bar, expand Workers and Pages, select Overview, and click Create Application.

Connect it to your GIT account, and select the Repo you created from the Digital Garden template.

NOTE: If you’ve done this before, you’ll have to select “Add account” for the new repo to appear.

Configure your First Deployment

Enter the project name (default is the Repo name)
Set production branch to Main
Leave the Framework preset as default or set to Eleventy
1. I don’t think this matters, as we immediately change the commands afterward
Set the Build command to npm run build
Set the Build output directory to dist

Then click Finish (or something, I completely forgot to screencap this part), and it will do the first build for your site! If you’re going to run into problems, you’re likely to run into them here. Check out the Troubleshooting section at the very end for help.

Also, you may need to re-apply your features or appearance customizations you set earlier.

(OPT): Register and Assign a Custom Domain

In order to configure various Cloudflare security features (but not custom headers), you will need to register a domain name and link it to your Pages project on Cloudflare.

In my opinion, the security features offered by Cloudflare are a big reason I picked it as a host over other services, so I don’t really think this is an optional step. Also, for how cheap you can get a domain ($10 for a year), it’s not all that expensive.

Transfer the Nameservers or Register a New Domain

It’s easiest if you register the domain through Cloudflare, but it’s not a requirement.

Expand Domain Registration in the slide-out menu on the left, and choose Register Domain
Search for the domain you want to buy and purchase it.
1. NOTE: Some of the more obscure TLDs (i.e. Top Level Domains, like .work or .online) are cheaper than .com or .io. If you don’t care too much about branding, you could save a few bucks by choosing one of the less common ones.
Back under your application, select the Custom domains tab, and click “Setup a custom domain” Follow the steps, and you should be golden.

If you already own a domain with a different registrar, you can either change the domain’s Name Servers to Cloudflare’s, or you can transfer the domain (which I won’t get into right now, and is different from DNS Transfer). The steps are very similar to the one’s above; however, begin by navigating to your Cloudflare Pages app and click Custom domains.

Enter the domain you want to use, and then click Begin DNS transfer
Re-enter the name you want to use, and select whichever tier plan you want to use
1. NOTE: Free is perfectly acceptable.
Follow the steps on the page, and update your domain registrar’s Nameserver entries to Cloudflare’s servers
Once the Nameserver update has been completed, you can add the domain as a Custom domain for your Digital Garden.

Add Cloudflare Security and Optimization Features

Now that we’ve connected our domain to Cloudflare, we can view it under Websites at the top of the left-side slideout menu, and make a host of performance and security upgrades. From your Cloudflare dashboard, you should be able to see the domain you just registered, and a little green checkmark with Active next to it.

Click on your domain, and let’s get started with the Quick Start Guide from the main panel.

Click “Review Settings” in the Quick Start Guide pane
Enable Automatic HTTPS rewrites
Enable Always Use HTTPS
Your choice whether to enable or disable Brotli compression; I couldn’t find anything indicating it was insecure to use, and is apparently a A Fast Alternative to GZIP Compression

Once done, we should go down the options in left slide-out menu and enable a bunch of other security and optimization features.

DNS
1. Click on Enable DNSSEC
  1. In short, DNSSEC (link to Cloudflare docs) effectively protects your domain from getting hijacked in an on-path attack.
SSL/TLS
1. SSL/TLS is used to encrypt traffic between servers and clients, ensuring the data is authentic and confidential.
2. Under “Overview“, select “Full (Strict)”
  1. If you’re squeamish, choose “Full“
  2. Because the whole site is hosted on Cloudflare, you shouldn’t have to create any additional certificates
3. Under “Edge Certificates”
  1. Enable “HTTP Strict Transport Security (HSTS)“;²³ this brings up a big scary menu. Check the box and click Next, and choose the options in the following menu:
    1. Enable HSTS
    2. Max Age – 1 Year
      1. Required for Preload
    3. Enable Apply HSTS Policy to Subdomains
    4. Enable Preload
    5. Enable No-Sniff Header
      1. This prevents us from having to add it manually later on
  2. Set “Minimum TLS Version” to TLS 1.3 (or minimum TLS 1.2)
    1. The default TLS 1.0 and 1.1 are busted, with TLS 1.1 being deprecated in 2021.
    2. TLS 1.2 is less secure and slower than 1.3, but you may have a use-case for needing it (but that’s unlikely).
Security
1. The Security section is mostly about how your site handles suspicious clients.
2. Security level: Low or Medium
  1. Choose what level of visitors should receive a Challenge (like a CAPTCHA or similar) if they are deemed sufficiently threatening
  2. Default is Essentially Off, and going from Low to High increases the likelihood of suspicious visitors getting prompted
  3. I would advocate Medium and doing some testing from different browsers, using a VPN, etc., and downgrading if you feel it’s necessary
3. Challenge Passage: Your preference (Default 30 minutes)
  1. If a suspicious visitor gets past the challenge, this dictates how frequently they are re-challenged
  2. Default is 30 minutes, and based on your testing for Security Level (e.g., if it trips when you’re using a VPN), I would set the time period higher⁴
Speed
1. This largely deals with helping clients connect faster.
2. Some of these features are locked behind a Pro subscription or higher.
3. Enable or disable options here as you feel comfortable.

(OPT): Configure Dependabot on GitHub and Create Custom Headers

Now that we have Cloudflare configured securely, let’s make sure we’re not publishing obsolete and vulnerable code.

WARNING: Deploying patches outside of Digital Garden updates may break your site. This has not happened to me yet, but if it happens to you, you can revert Dependabot branch merges and easily roll-back the problem.
NOTE: Because the Digital Garden is a static site (e.g., there’s no user input), theoretically there isn’t a great risk of exploitation, but I prefer to stay on the safe side. However, you do you.

Additionally, I strongly recommended that you familiarize yourself with Visual Studio Code, Node.js, and GitHub Desktop⁵. But rather than make this already long guide longer, you can find more information on this under How to update packages for Digital Gardens.

Configure Security and Dependency Updates in GitHub

NOTE: If you apply updates through Dependabot, Digital Garden updates overwrite them, and you may be required to re-apply them. However, it’s better to be running patched than unpatched, and it’s not that hard.

In the Repo, navigate to “Settings,” Code security and analysis, and enable Dependabot Alerts and Security Updates.

When there is a dependency update or security issue, Dependabot will create a pull request, and Cloudflare will test the build in a preview to make sure it builds correctly.

To merge the pull request, click the green button above and then click confirm merge.

And it’s updated! Whoo-raaay! But if you haven’t already, I highly recommend you check out my guide on How to update packages for Digital Gardens. It covers instances where Dependabot finds a security vulnerability it can’t fix for you automatically.

Custom Security Headers

Cloudflare allows you to install custom headers⁶ on your site without much fuss.

Installing security headers critical, as it improves your site’s security and reduces the likelihood an attacker will use your site to hack your visitors. Don’t enable attackers.

Don’t believe me? You can check your site’s headers and see how an attacker can take advantage of your site with securityheaders.com

To add security headers, you need to first create a file called _headers⁷ in the folder /src/site in your GitHub Repo, then modify the /src/helpers/userSetup.js configuration file to pass the headers file through to Cloudflare.

The quickest way to create the file is to navigate to the folder in GitHub, and select Add file from the top right.

Name the file _headers, and insert the following text:

/*
  X-Frame-Options: SAMEORIGIN
  Permissions-Policy: document-domain=(self)

I’ve tested this against all of my sites, and it hasn’t caused any issues so far.

Next, modify the userSetup.js file to add a passthrough for the _headers file. You can also make this change through GitHub.

NOTE: The guide originally instructed you to modify the .eleventy.js configuration file, which would get overwritten whenever you updated the Digital Garden template. oleeskild designed this file to pass through functions during the site build, so you don’t have to update the .eleventy.js file every time you update the template.

Open the file /src/helpers/userSetup.js by navigating to the helpers folder and clicking on its name, and at the top-right corner of the code, clicking the drop-down menu next to the pen and selecting Edit in place.

Within the “function userEleventySetup(eleventyConfig)” brackets, add the following line:

eleventyConfig.addPassthroughCopy("src/site/_headers");

To verify that your headers have been added, under “Deployment Details“, you can click on the Headers tab and see what was added.

Example output of when successfully adding headers.

Failed addition of headers:

You can also go to Security Header Scanner by Probely to view your site’s current headers after the deployment succeeds.

And you’re set! Well, almost. You may have noticed when you run the header security scan that you’ll get warnings about a missing “Content Security Policy (CSP)“, and I can hear you screaming at me through your browsers “Max you JERK, HOW could you have led me astray?!?” Instead, you should thank me for sparing you from the madness that is CSP and Digital Garden.

Digital Garden is absolutely broken when it comes to CSP
1. There are tons of on-page scripts make it effectively impossible to implement.
2. Additionally, there are tons of remotely-hosted scripts, and literally nothing I try works.

Feel free to experiment with something like Csper, though it’s going to require constant maintenance whenever there’s an update.⁸ For reference, here was my “CSP” policy after several rounds (see version=5 at the end, but I only started counting when I experimented with Csper).

Just adding the domain that hosted the scrips should have worked, without spelling out the specific scripts⁹, but I just could not get it working. If you use Csper¹⁰ to generate CSP code for your site, you will only have a 24-hour evaluation period before it’s $50 a month minimum.

Also with Csper, you install the extension and add the CSP policy to your headers, you will need to make it all one line, and add a ?v=1 to the end of the report-uri (like endpoint.csper.io?v=1;) to track changes in policy. This is important for when you try to update your code with Csper, and for some reason doesn’t happen by default. Once added, the version increments automatically.

And that’s it! Finally! Now go write some stuff and publish it.

Troubleshooting

I was going to put my troubleshooting steps here, but I guarantee that I will want to update them more frequently than I will want to log in to my WordPress. So instead, I’ll create a page on my wisdom-dumpsite, wisdump.work, and link it here once it updates.

You see a bunch of Failed deployments in Cloudflare to “Filetree”
1. This probably only happened if you included the branches from the template
2. Make sure the Main branch is set as “Default” in GitHub
You were working with file structure in your Obsidian Vault, and now deployments are failing.
1. This was probably caused when renaming a file, or if the file ended with a special character (like an exclamation mark or question mark), but you should receive an email an email from GitHub/Cloudflare when there’s a build issue.
2. Access the build log to identify the problem files.
  1. GitHub: open the Repo, click on Actions, then under “Jobs” or “Annotations” click on “build (20.x)” (or something similar), and it will expand the build log.
  2. Cloudflare: Navigate to Workers and Pages, select the failing build, and scroll down to the log.
  3. Analyzing the log: Find where the “[11ty]” output begins, and near the top it should say that there was an output conflict, and list the files (and their locations) in a numbered list.
3. With the names of the bad files, go to GitHub and delete them.
  1. Navigate to your GitHub repo and under Code, navigate to the files in question (usually under src/site/notes)
  2. Click the file name to open it, then select the 3-dot menu at the top-right, and click “Delete file“
  3. NOTE: This is also easily done with GitHub Desktop; just delete the file, commit to main, and then publish changes.
4. Once the files are deleted, you can Publish to Digital Garden from Obsidian and it should update the correct file.

Footnotes

You could do a regular token, but that’s a bad idea and you should feel bad for having it. ↩︎
The HTTPS-Only Standard – HTTP Strict Transport Security ↩︎
HSTS Preload List Submission ↩︎
Life of a Tor user : r/TOR ↩︎
What, you thought you were signing up for some free and easy way to upload your notes to the internet? Well with great power comes great security risks, and if you don’t want some script kiddie owning your base, you should assume the people making free tools have overlooked something. Sometimes you gotta fix dependencies yourself for security updates, and boy howdy, knowing how these tools work is key ↩︎
Headers · Cloudflare Pages docs ↩︎
Not _headers.txt, not headers, and for godsake not TheseAreMySecurityHeadersForMyCloudflareSite.txt.xml.zip.tar.gz ↩︎
You can find additional CSP source values here: CSP source values – HTTP | MDN ↩︎
I know adding other domains is less secure, but it could have required extra steps for an attacker ↩︎
Which has plugins for Chrome (CSP) Generator and Firefox (CSP) Generator ↩︎