Private Doc Viewer

Share private GitHub repository documentation (Markdown and PDFs) behind a simple 6-digit access code. Built on Cloudflare's free tier with zero ongoing server costs.

Visitors see a landing page with a code input. After entering the correct code, they get a 24-hour session cookie and can browse the full rendered documentation site freely.

Architecture

┌─────────────────┐     ┌──────────────────────┐     ┌─────────────────────┐
│  Visitor Browser │────▶│  Cloudflare Worker    │────▶│  Cloudflare Pages   │
│                  │     │  (travel.example.com) │     │  (*.pages.dev)      │
│                  │     │                       │     │                     │
│  6-digit code ──▶│     │  • Auth gate          │     │  • Static HTML/PDF  │
│  Session cookie  │     │  • Session cookies    │     │  • Protected by     │
│                  │     │  • Brute-force lockout │     │    Access + Service │
│                  │     │  • Proxy with service  │     │    Token            │
│                  │     │    token auth          │     │                     │
└─────────────────┘     └──────────────────────┘     └─────────────────────┘

• Cloudflare Worker — intercepts all requests on the custom domain, enforces 6-digit code authentication, manages sessions, and proxies to Pages using a service token
• Cloudflare Pages — serves the rendered HTML documentation, PDFs, and images
• Cloudflare Access — blocks direct public access to *.pages.dev; only the worker's service token can reach the origin
• Terraform — provisions all Cloudflare infrastructure (Pages, Worker, KV, DNS, Access) with S3-backed remote state
• Cloudflare Provider v5 — uses the latest auto-generated Terraform provider

Prerequisites

• Terraform >= 1.0
• Node.js >= 18 (for Wrangler CLI)
• Python 3 (for the Markdown build pipeline)
• A Cloudflare account (free tier works)
• A Cloudflare API token with Workers, Pages, DNS, and Zero Trust permissions
• An AWS S3 bucket for Terraform state storage

Setup

1. Clone this repo

git clone <this-repo-url>
cd private-doc-viewer

2. Configure Terraform variables

Create terraform/terraform.tfvars:

cloudflare_account_id = "your-account-id"
cloudflare_api_token  = "your-api-token"
access_code           = "123456"
cookie_secret         = "a-long-random-secret-string"

# Required for custom domain
cloudflare_zone_id = "your-zone-id"
custom_domain      = "docs.example.com"

# Optional
webhook_url = "https://hooks.slack.com/services/..."

Update the S3 backend in terraform/main.tf to point to your bucket.

3. Provision infrastructure

cd terraform
terraform init
terraform apply

This creates:

• Cloudflare Pages project
• Worker script with KV bindings and secrets
• KV namespace for brute-force tracking
• Custom domain DNS record (CNAME)
• Access application + service token protecting the pages.dev origin

4. API token permissions

Your Cloudflare API token needs these permissions:

Scope	Permission	Access
Account	Workers Scripts	Edit
Account	Workers KV Storage	Edit
Account	Cloudflare Pages	Edit
Account	Access: Apps and Policies	Edit
Account	Access: Service Tokens	Edit
Zone	DNS	Edit

Deploying Documentation

There are two ways to deploy your source documentation to the site.

Option A: Local deploy (recommended for quick updates)

Use the included deploy.sh script to build and deploy from a local directory:

./deploy.sh ~/repos/my-private-docs

This will:

1. Install Python build dependencies
2. Convert all Markdown files to HTML (with link rewriting)
3. Copy PDFs and images as-is
4. Deploy the built _site/ to Cloudflare Pages via Wrangler

Your source repo should be a directory of Markdown files and assets:

my-private-docs/
├── README.md              → becomes index.html (home page)
├── guide.md               → becomes guide.html
├── subfolder/
│   ├── notes.md           → becomes subfolder/notes.html
│   └── receipt.pdf        → copied as subfolder/receipt.pdf
└── images/
    └── photo.jpg          → copied as images/photo.jpg

Option B: GitHub Actions (automated on push)

In your private documentation repository, add these GitHub Actions secrets:

Secret	Value
CLOUDFLARE_API_TOKEN	Cloudflare API token with Pages permission
CLOUDFLARE_ACCOUNT_ID	Your Cloudflare account ID

Copy the workflow and build files into your source repo:

cp build/deploy-docs.yml <source-repo>/.github/workflows/deploy-docs.yml
cp -r build/ <source-repo>/build/

Push to main and the workflow will build and deploy automatically.

Build details

The build pipeline (build/build.py):

• Converts .md files to styled HTML using markdown-it-py
• Rewrites relative .md links to .html (so inter-doc links work)
• Copies PDFs, PNGs, JPGs, GIFs, and SVGs as-is
• Root README.md becomes index.html with title "Home"
• All other files keep their name with .html extension

Changing the Access Code

Update access_code in terraform/terraform.tfvars and re-apply:

cd terraform
terraform apply

Existing sessions remain valid until their 24-hour cookie expires.

Project Structure

├── build/
│   ├── build.py              # Markdown-to-HTML build pipeline
│   ├── deploy-docs.yml       # GitHub Actions workflow (copy to source repo .github/workflows/)
│   └── requirements.txt      # Python build dependencies
├── deploy.sh                 # Local deploy script
├── terraform/
│   ├── main.tf               # S3 backend configuration
│   ├── providers.tf          # Cloudflare provider v5
│   ├── resources.tf          # Pages, Worker, KV, DNS resources
│   ├── access.tf             # Access application + service token
│   ├── variables.tf          # Input variables
│   └── outputs.tf            # Output values (URLs, IDs)
├── worker/
│   └── src/index.js          # Auth Worker source code
└── tests/                    # Unit and property-based tests

Security

• Access code auth — 6-digit code verified by the Worker
• Session cookies — HMAC-SHA256 signed, HttpOnly, Secure, SameSite=Strict, 24h expiry
• Brute-force protection — IP lockout after 8 failed attempts (30 min cooldown via KV)
• Cloudflare Access — blocks direct pages.dev access; only the worker's service token can reach the origin
• Admin alerts — optional webhook notification on lockout events

License

MIT