Skip to content

Deploying the Documentation Site

This guide publishes the QBTime Manager documentation site to docs.qbtime.r2d2dev.com.

It assumes you have never done this before. Every tool you need to install and every click is spelled out. If a step says "you should see X," and you don't, stop and check the Troubleshooting section at the end before continuing.

The docs site is separate from the QBTime Manager application. It is a plain website built from the text files in the docs/ folder. Publishing it does not touch the app.

What you're about to do (plain-English overview)

  1. Install three free tools on your Windows PC: Python, Node.js, and Git (one-time).
  2. Build the website — turn the text files into a folder of web pages.
  3. Upload it to Cloudflare so it's live on the internet.
  4. Connect a friendly web address (docs.qbtime.r2d2dev.com).
  5. (Optional) Make future updates automatic so editing a file and saving it online republishes the site by itself.

Steps 1–4 are a one-time setup. After that, updating the site is quick.

You will need: the QBTime Manager project files on your PC (in C:\MSP\CowboyMSP\Dev\CCC-QBTime), a Cloudflare account that manages qbtime.r2d2dev.com, and (for the optional Step 5) access to the GitHub repository. If you don't have the Cloudflare or GitHub logins, get those from whoever set them up before starting.

Step 0 — Install the tools (one-time)

You'll use a program called PowerShell to run a few commands. Don't worry — you just copy and paste them...

0a. Open PowerShell

  1. Press the Windows key on your keyboard.
  2. Type powershell.
  3. Click Windows PowerShell in the results. A dark window with a blinking cursor opens. This is where you'll paste commands. To paste, right-click inside the window (or press Ctrl+V), then press Enter to run.

Keep this window open through the whole guide. If you close it, just reopen it the same way.

0b. Install Python

Python is what builds the website from the text files.

  1. In PowerShell, paste this and press Enter:
winget install Python.Python.3.12
  1. If Windows asks to allow it, click Yes. Wait until it says it succeeded.
  2. Close PowerShell and reopen it (Windows key → type powershell → Enter). This is required so Windows "sees" the newly installed Python.
  3. Confirm it worked — paste and Enter:
python --version

You should see something like Python 3.12.x. If you instead see an error or a Microsoft Store window opens, see Troubleshooting → "Python not found."

0c. Install Node.js

Node.js provides the wrangler tool that talks to Cloudflare, and is also used by the QBTime Manager app.

  1. Paste and Enter:
winget install OpenJS.NodeJS.LTS
  1. Click Yes if prompted. When it finishes, close and reopen PowerShell again.
  2. Confirm:
node --version

You should see something like v20.x.x or v22.x.x.

0d. Install Git

Git is only needed for the optional automatic-updates step (Step 5) and for getting the project files if you don't already have them. Install it now so it's ready.

  1. Paste and Enter:
winget install Git.Git
  1. Click Yes if prompted; accept the default options. Close and reopen PowerShell.
  2. Confirm:
git --version

You should see something like git version 2.x.

You now have all the tools. You won't need to install them again on this PC.

Step 1 — Go to the project folder

Everything below is run from the project's main folder (the "repo root"). For this project that is C:\MSP\CowboyMSP\Dev\CCC-QBTime.

  1. In PowerShell, paste and Enter:
cd C:\MSP\CowboyMSP\Dev\CCC-QBTime
  1. Confirm you're in the right place — paste and Enter:
dir mkdocs.yml

You should see a line listing mkdocs.yml. If it says "Cannot find path," the project isn't at that location — see Troubleshooting → "Project folder not found."

The prompt at the left of each line should now show ...\CCC-QBTime>. That means you're in the right folder. Stay here for the rest of the guide.

Step 2 — Build the website

This turns the text files in docs/ into a folder of real web pages called site.

  1. Install the builder (one-time per PC). Paste and Enter:
pip install -r docs-requirements.txt

Wait until it finishes (it prints Successfully installed ...).

  1. Build the site. Paste and Enter:
python -m mkdocs build

  1. Confirm it worked. You should see a line like Documentation built in 0.3 seconds. A new folder named site now exists inside C:\MSP\CowboyMSP\Dev\CCC-QBTime.

  2. Look inside it — open File Explorer (the folder icon on your taskbar), navigate to C:\MSP\CowboyMSP\Dev\CCC-QBTime\site, and confirm it contains index.html, an assets folder, an admin-guide folder, a user-guide folder, and a few others. This site folder is the finished website — it's what you upload next.

You'll repeat python -m mkdocs build whenever you change the docs and want to refresh the website. You never edit anything inside site by hand — it's regenerated each time.

If you got a red error instead of "Documentation built," see Troubleshooting → "mkdocs build failed."

Step 3 — Put the site on Cloudflare (first time)

This creates the website's home on Cloudflare by uploading the site folder.

  1. Open a web browser and go to https://dash.cloudflare.com. Sign in with the Cloudflare account that manages qbtime.r2d2dev.com.
  2. In the menu on the left, click Workers & Pages.
  3. Click the Create application button.
  4. Click the Pages tab, then find and click Upload assets (sometimes labeled "Upload assets directly").
  5. In the Project name box, type exactly:
qbtime-docs

Then click Create project. 6. You'll see a box that says you can drag files in. Now: - Open File Explorer and go to C:\MSP\CowboyMSP\Dev\CCC-QBTime\site. - Click any file inside, then press Ctrl+A to select everything inside site (the index.html file, the assets folder, the guide folders, etc.). - Drag that selection into the Cloudflare upload box and drop it. - Important: select the things inside site, not the site folder itself. The index.html file must end up at the top of the upload. 7. Wait for the files to finish uploading, then click Deploy site. 8. Cloudflare shows a temporary address like https://qbtime-docs.pages.dev. Click it — your documentation site should load. 🎉

If you don't see your site, see Troubleshooting → "Uploaded but site is blank."

Step 4 — Connect the friendly web address

Right now the site is at qbtime-docs.pages.dev. This step puts it at docs.qbtime.r2d2dev.com.

  1. Still in the Cloudflare dashboard, go to Workers & Pages and click your qbtime-docs project.
  2. Click the Custom domains tab.
  3. Click Set up a domain.
  4. Type exactly:
docs.qbtime.r2d2dev.com

Click Continue, then Activate domain. 5. Because qbtime.r2d2dev.com is already on this Cloudflare account, Cloudflare creates the needed DNS record for you — you don't have to add anything by hand. 6. Wait 1–2 minutes, then open https://docs.qbtime.r2d2dev.com in your browser. The site should load with a secure padlock. The setup is done.

At this point the site is live. If you only want to update it occasionally by hand, you can stop here and just repeat Step 2 (build) and a quick re-upload (Step 3, steps 6–7) whenever you change the docs. Step 5 below makes updates automatic instead.

Step 5 — (Optional) Make future updates automatic

This is optional and a little more advanced. Once set up, saving your doc changes to GitHub automatically rebuilds and republishes the site — no manual upload. Skip this if you're happy updating by hand.

It works by giving GitHub a "key" to deploy to Cloudflare on your behalf. You create the key in Cloudflare and paste it into GitHub.

5a. Create a Cloudflare key (API token)

  1. In the Cloudflare dashboard, click your profile icon (top-right corner) → My Profile.
  2. In the left menu click API Tokens, then click Create Token.
  3. In the list of templates, find "Edit Cloudflare Workers" and click Use template.
  4. Scroll to Account Resources and choose the account that owns qbtime-docs. Leave everything else as-is.
  5. Click Continue to summary, then Create Token.
  6. Cloudflare shows the token once. Click Copy and paste it temporarily into Notepad — you need it in step 5c and will not be able to see it again.

5b. Find your Cloudflare Account ID

  1. In the Cloudflare dashboard, click Workers & Pages in the left menu.
  2. On the right side of the page, find Account ID and click the copy icon next to it. Paste it into the same Notepad, labeled so you don't mix it up with the token.

5c. Give both to GitHub

  1. In a browser, open the QBTime Manager repository on https://github.com (the Quickbooks-Time-API repo). Sign in if asked.
  2. Click the Settings tab (near the top of the repo page).
  3. In the left menu, expand Secrets and variables and click Actions.
  4. Click New repository secret. Then:
  5. Name: type CLOUDFLARE_API_TOKEN
  6. Secret: paste the token from step 5a
  7. Click Add secret.
  8. Click New repository secret again. Then:
  9. Name: type CLOUDFLARE_ACCOUNT_ID
  10. Secret: paste the Account ID from step 5b
  11. Click Add secret.

The names must be typed exactly as shown (all capitals, with underscores).

That's it. From now on, whenever a change to the docs files is saved to the repository's main branch, the site rebuilds and republishes automatically within a couple of minutes. You can watch it happen on the repo's Actions tab (look for the Docs workflow turning green).

Updating the site later

If you set up Step 5 (automatic): edit the text files in the docs folder, then save/commit them to GitHub's main branch. The site updates itself in a minute or two.

If you did NOT set up Step 5 (manual): in PowerShell, from C:\MSP\CowboyMSP\Dev\CCC-QBTime, run mkdocs build again, then repeat the upload in Step 3 (steps 6–7) using the refreshed site folder. Cloudflare keeps the same project and domain — you don't redo Steps 3's project creation or Step 4.

The PRIVATE operations site (this site)

There are two documentation sites. The public one (above) is docs.qbtime.r2d2dev.com — User and Administrator guides, open to anyone. This operations site is ops.qbtime.r2d2dev.com — the deploy/backup/runbook guides — and it is access-restricted to the team via Cloudflare Access. It builds from docs-ops/ using mkdocs.ops.yml, and deploys to its own Pages project, qbtime-docs-ops, through the .github/workflows/docs-ops.yml workflow (the mirror of the public one).

Create the ops Pages project (one-time)

  1. In the Cloudflare dashboard, Workers & Pages → Create application → Pages → Upload assets (the same flow as the public site).
  2. Name the project exactly qbtime-docs-ops — the workflow deploys to that name (--project-name=qbtime-docs-ops). A different name will fail.
  3. On the "Upload your project assets" screen, do not drag any files. The GitHub workflow builds and uploads the real site for you. Just click Deploy site with nothing uploaded to create an empty placeholder project; the first real deploy overwrites it.

Connect the ops domain (one-time)

  1. Open the new qbtime-docs-ops project → Custom domains → Set up a custom domain.
  2. Enter ops.qbtime.r2d2dev.com and follow the prompts (DNS is automatic since Cloudflare manages the zone).

Lock it down with Cloudflare Access (one-time — this is what makes it private)

Until you do this, the ops site is public like the other one.

  1. Go to Zero Trust → Access → Applications → Add an application → Self-hosted.
  2. Application domain: ops.qbtime.r2d2dev.com.
  3. Add a policy: Action Allow, with a rule such as Emails ending in @r2d2dev.com (or a specific list of teammate emails).
  4. Pick a login method (one-time email code is simplest, or Google/GitHub).
  5. Save. Now visiting any ops page prompts a team login; non-team visitors are blocked.

The existing GitHub repo secrets CLOUDFLARE_API_TOKEN and CLOUDFLARE_ACCOUNT_ID are reused — no new secrets are needed. After the project exists, trigger the first real deploy by pushing to main (any change under docs-ops/) or via Actions → Docs (Ops) → Run workflow.

To preview the ops site locally: mkdocs serve -f mkdocs.ops.yml.

How this differs from deploying the APP

Publishing these docs does not publish the QBTime Manager application, and vice versa — they are two separate things. The app is shipped on purpose with its own commands (npm run deploy:staging / npm run deploy:prod); it does not auto-deploy when you push to GitHub. See the README's "Deployment" section for the app. This guide is only about the documentation website.

Troubleshooting

"Python not found" (or the Microsoft Store opens when you type python). Windows has a placeholder that hijacks python. Fix: press Windows key → search "Manage app execution aliases" → turn OFF the two toggles named "python.exe" and "python3.exe". Then close/reopen PowerShell and try python --version again. If still missing, reinstall with winget install Python.Python.3.12 and reopen PowerShell.

"pip not recognized." Python isn't fully installed or PowerShell wasn't reopened after installing. Close/reopen PowerShell. If it persists, run python -m pip install -r docs-requirements.txt instead of pip install ....

"Project folder not found" at Step 1. The project may be stored somewhere else (for example under OneDrive). Open File Explorer, find the folder that contains mkdocs.yml, copy its full path from the address bar, and use that after cd instead of the example path.

mkdocs build failed with a message about the configuration file / special characters. A stray hidden character may be in mkdocs.yml. Run this once, then build again:

(Get-Content mkdocs.yml -Raw) -replace "`0","" | Set-Content mkdocs.yml -NoNewline
mkdocs build

Build fails with "file in use" / permission errors and your project is in OneDrive. OneDrive can lock files while building. Pause OneDrive syncing (click the OneDrive cloud icon → Pause), run mkdocs build, then resume OneDrive.

Uploaded but the site is blank / "Nothing here yet." You likely uploaded the site folder itself instead of its contents. Redo Step 3 step 6: open the site folder, select the items inside it (so index.html is at the top of the upload), and re-upload.

Custom domain shows "not found" or won't secure. Give it a few minutes — DNS and the security certificate can take a moment. Re-open the Custom domains tab and confirm docs.qbtime.r2d2dev.com shows as Active.

(Step 5) The Actions workflow fails with an authentication error. The GitHub secrets are missing, misnamed, or the token is wrong. Re-check Step 5c: the names must be exactly CLOUDFLARE_API_TOKEN and CLOUDFLARE_ACCOUNT_ID. If unsure about the token, create a new one (5a) and update the secret.

(Step 5) "project not found" during the workflow. You must do Step 3 (create the qbtime-docs project) before automatic deploys can work.

(Step 5) Saving changes didn't trigger an update. The automatic build only runs when files under docs/, mkdocs.yml, or docs-requirements.txt change on the main branch. You can also trigger it manually: GitHub repo → Actions tab → Docs → Run workflow.