Skip to content

Phase 0 — Documentation Setup

Goal: Get your live documentation site running at docs.ahanabipin.in before any other phase begins. This is the foundation everything else is documented into.

Time estimate: 2–3 hours
What you need: MacBook with admin rights, browser, Terminal
Prerequisites: None — this is the starting point

Overview

By the end of this phase you will have:

  • A single live documentation site at docs.ahanabipin.in covering everything — technical runbooks and family reference guides (MkDocs + Cloudflare Pages)
  • A GitHub repo storing all your documentation source files
  • Auto-deploy configured — every git push updates the live site within 90 seconds

Why one site for everything? MkDocs handles both technical runbooks and simple family reference pages equally well. Family guides are just pages written in plain language with screenshots — same engine, different tone. Keeps everything free, in one place, and under your control forever.

Why Cloudflare Pages instead of GitHub Pages? GitHub Pages requires a paid plan for private repositories. Cloudflare Pages is free and supports private repos natively. Since Cloudflare is already your DNS provider, everything stays in one place.

Step 1 — Buy Your Domain

  1. Go to namecheap.com and create an account
  2. Search for your domain name and confirm it is available
  3. Add to cart and purchase — .in domains are typically ₹800–1,200/yr
  4. During checkout — uncheck every upsell (WhoisGuard is free for .in so keep that, but skip everything else — hosting, SSL, email etc.)
  5. Once purchased, go to Domain List → Manage on your domain
  6. Under Nameservers, select Custom DNS — leave this open, you will fill in the values in the next step

Do not use Namecheap's default DNS. You are moving DNS management to Cloudflare for better control and free SSL.

Step 2 — Set Up Cloudflare

  1. Go to cloudflare.com and create a free account
  2. Click Add a Site → enter your domain name → select the Free plan
  3. Cloudflare will scan existing DNS records — click Continue
  4. Cloudflare will give you two nameserver addresses — they look like: aida.ns.cloudflare.com kurt.ns.cloudflare.com
  5. Copy these and paste them into the Custom DNS fields in Namecheap
  6. Save in Namecheap, then click Done, check nameservers in Cloudflare
  7. Propagation takes 10–30 minutes. Cloudflare will email you when active.

Step 3 — Plan Your Subdomains in Cloudflare

Once your domain is active in Cloudflare, you will add DNS records as you deploy each service. For now note the planned structure:

Subdomain Purpose Configured In
docs.ahanabipin.in Documentation site (this site) Phase 0
watch.ahanabipin.in Jellyfin streaming Phase 5
request.ahanabipin.in Overseerr request portal Phase 5

The docs subdomain DNS record is created automatically by Cloudflare Pages in Step 9 — you do not need to create it manually.

Step 4 — Set Up GitHub

  1. Go to github.com and create a free account if you do not have one
  2. Create a new repository:
  3. Name: ahanabipin-docs
  4. Visibility: Private
  5. Tick Add a README file
  6. Click Create repository

Step 5 — Generate a Personal Access Token

GitHub no longer accepts passwords for command line access. You need a Personal Access Token.

  1. Go to GitHub → click your profile picture → Settings
  2. Scroll to the bottom of the left sidebar → Developer settings
  3. Click Personal access tokens → Tokens (classic)
  4. Click Generate new token → Generate new token (classic)
  5. Fill in:
  6. Note: ahanabipin-docs
  7. Expiration: No expiration
  8. Scopes: tick repo and workflow (both are required)
  9. Click Generate token
  10. Copy the token immediately — GitHub only shows it once. It looks like ghp_xxxxxxxxxxxxxxxxxxxx

Important: Store this token in a password manager like Bitwarden. You will need it every time you push from a new machine.

If you forgot to tick workflow scope: Go back to your token, click Edit, and tick the workflow scope. No new token is generated — the existing token is updated silently and retains the same value.

Step 6 — Install Prerequisites on MacBook

Open Terminal and run the following commands one at a time:

Install Homebrew (skip if already installed):

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Install Python:

brew install python

Verify Python:

python3 --version

You should see Python 3.x.x

Install pipx (required for MkDocs on Python 3.14+):

brew install pipx
pipx ensurepath
source ~/.zshrc

Install MkDocs and Material theme via pipx:

pipx install mkdocs
pipx inject mkdocs mkdocs-material

Verify MkDocs:

mkdocs --version

You should see mkdocs, version 1.6.x from ...

Why pipx instead of pip? Python 3.14 on Homebrew enforces strict environment isolation and blocks system-wide pip installs with an externally-managed-environment error. pipx is the correct, recommended way to install Python CLI applications on modern macOS — it manages isolated environments automatically with no extra effort.

Step 7 — Clone Your Repo and Build the Structure

Clone your GitHub repo:

cd ~/Documents
git clone https://YOURTOKEN@github.com/YOURGITHUBUSERNAME/ahanabipin-docs.git
cd ahanabipin-docs

Replace YOURTOKEN with your Personal Access Token and YOURGITHUBUSERNAME with your actual GitHub username. For example:

git clone https://ghp_abc123@github.com/bipintest/ahanabipin-docs.git

Create the MkDocs config file:

touch mkdocs.yml

Create all folders and empty markdown files in one go:

mkdir -p docs/homelab docs/automation docs/solar docs/family

# Root files
touch docs/index.md docs/about.md

# Home Lab
touch docs/homelab/overview.md docs/homelab/phase-0.md \
  docs/homelab/phase-1.md docs/homelab/phase-2.md \
  docs/homelab/phase-3.md docs/homelab/phase-4.md \
  docs/homelab/phase-5.md docs/homelab/phase-6.md \
  docs/homelab/phase-7.md docs/homelab/troubleshooting.md

# Home Automation
touch docs/automation/overview.md docs/automation/lighting.md \
  docs/automation/cameras.md docs/automation/locks.md \
  docs/automation/climate.md docs/automation/solar.md \
  docs/automation/iot.md docs/automation/troubleshooting.md

# Solar
touch docs/solar/overview.md docs/solar/installation.md \
  docs/solar/monitoring.md

# Family Guides
touch docs/family/index.md docs/family/request-movie.md \
  docs/family/watch.md docs/family/photos.md \
  docs/family/emergency-contacts.md docs/family/breaker-box.md \
  docs/family/vendors.md docs/family/warranties.md

Verify the structure:

find docs -type f | sort

You should see 30 files listed across 5 folders.

Step 8 — Configure MkDocs

Open mkdocs.yml in a text editor. If you have VS Code:

code mkdocs.yml

Or use nano:

nano mkdocs.yml

Paste the following:

site_name: Ahana & Bipin's Home
site_url: https://docs.ahanabipin.in
theme:
  name: material
  palette:
    scheme: default
    primary: teal
    accent: teal
  features:
    - navigation.tabs
    - navigation.sections
    - navigation.top
    - search.suggest
    - search.highlight
    - toc.integrate

nav:
  - Home: index.md
  - Home Lab:
    - Overview: homelab/overview.md
    - Phase 0 - Documentation Setup: homelab/phase-0.md
    - Phase 1 - NAS Setup: homelab/phase-1.md
    - Phase 2 - Data Migration: homelab/phase-2.md
    - Phase 3 - Photo Backup: homelab/phase-3.md
    - Phase 4 - Remote Access: homelab/phase-4.md
    - Phase 5 - Media Library: homelab/phase-5.md
    - Phase 6 - Family Onboarding: homelab/phase-6.md
    - Phase 7 - NAS Backup: homelab/phase-7.md
    - Troubleshooting: homelab/troubleshooting.md
  - Home Automation:
    - Overview: automation/overview.md
    - Lighting & Switches: automation/lighting.md
    - Security Cameras: automation/cameras.md
    - Door Locks & Access: automation/locks.md
    - AC & Climate Control: automation/climate.md
    - Solar Monitoring: automation/solar.md
    - Other Sensors & IoT: automation/iot.md
    - Troubleshooting: automation/troubleshooting.md
  - Solar:
    - Overview: solar/overview.md
    - Installation Details: solar/installation.md
    - Monitoring Setup: solar/monitoring.md
  - Family Guides:
    - Start Here: family/index.md
    - How to Request a Movie: family/request-movie.md
    - How to Watch on TV or Phone: family/watch.md
    - How to Access Family Photos: family/photos.md
    - Emergency Contacts: family/emergency-contacts.md
    - Breaker Box Map: family/breaker-box.md
    - Vendor & AMC Contacts: family/vendors.md
    - Warranties & Documents: family/warranties.md
  - About: about.md

If using nano: save with Ctrl+O → Enter → Ctrl+X to exit. If using VS Code: save with Cmd+S.

Add a basic homepage — open docs/index.md and paste:

# Welcome to Ahana & Bipin's Home

This is the central documentation for everything at our home —
technical runbooks, home automation, solar, and family reference guides.

---

## Sections

- **Home Lab** — NAS setup, media server, remote access, backups
- **Home Automation** — Lighting, cameras, door locks, AC, solar monitoring
- **Solar** — Installation details and monitoring setup
- **Family Guides** — How to watch movies, request content,
  emergency contacts, warranties

Preview locally to confirm everything builds correctly:

mkdocs serve

Open http://127.0.0.1:8000 in your browser. You should see the full site with all navigation tabs. Press Ctrl+C to stop the preview.

Step 9 — Deploy to Cloudflare Pages

We use Cloudflare Pages rather than GitHub Pages because GitHub Pages requires a paid plan for private repositories. The setup has two parts: create the project via direct upload, then configure GitHub Actions for auto-deploy on every subsequent push.

9A — Build the Site Locally

mkdocs build

This creates a site/ folder containing the generated HTML.

9B — Create the Cloudflare Pages Project

  1. In Cloudflare → left sidebar → Workers & Pages
  2. Click Create
  3. Click the "Looking to deploy pages" link at the bottom
  4. Click Direct Upload
  5. Project name: ahanabipin-docs
  6. Upload the contents of the site/ folder from your repo directory
  7. Click Deploy

You now have a Cloudflare Pages project at ahanabipin-docs.pages.dev.

9C — Get Your Cloudflare API Token

  1. In Cloudflare → click your profile icon (top right) → My Profile
  2. Left sidebar → API Tokens → Create Token
  3. Click Use template next to Cloudflare Pages — Edit
  4. Under Account Resources → select your account
  5. Click Continue to summary → Create Token
  6. Copy the token — you only see it once

Also copy your Account ID — found in the right sidebar of your Cloudflare dashboard homepage under Account ID.

9D — Add Secrets to GitHub

  1. Go to your ahanabipin-docs repo on GitHub
  2. Click Settings → Secrets and variables → Actions
  3. Click New repository secret and add both of these:
Name Value
CLOUDFLARE_API_TOKEN your Cloudflare API token
CLOUDFLARE_ACCOUNT_ID your Cloudflare account ID

9E — Create the GitHub Actions Workflow

mkdir -p .github/workflows
nano .github/workflows/deploy.yml

Paste the following:

name: Deploy to Cloudflare Pages

on:
  push:
    branches:
      - main

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install MkDocs
        run: pip install mkdocs mkdocs-material

      - name: Build MkDocs site
        run: mkdocs build

      - name: Deploy to Cloudflare Pages
        uses: cloudflare/wrangler-action@v3
        with:
          apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
          accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
          command: pages deploy site --project-name=ahanabipin-docs

Save with Ctrl+O → Enter → Ctrl+X.

9F — Push Everything to GitHub

git add .
git commit -m "Add Cloudflare Pages deployment workflow"
git push origin main

Go to your GitHub repo → Actions tab. You will see the workflow running. When it shows a green tick, your site is live at ahanabipin-docs.pages.dev.

Step 10 — Add Custom Domain

  1. In Cloudflare → Workers & Pages → click ahanabipin-docs
  2. Click the Custom domains tab
  3. Click Set up a custom domain
  4. Enter docs.ahanabipin.in → click Continue
  5. Click Activate domain

Since your domain is already managed by Cloudflare DNS, the record is created automatically — no manual DNS changes needed. Wait 2–3 minutes then visit:

https://docs.ahanabipin.in

HTTPS is enabled automatically by Cloudflare — no additional configuration needed.

How to Add Documentation Going Forward

Every time you complete a phase or want to add content to the docs:

cd ~/Documents/ahanabipin-docs
# Edit the relevant file, for example:
code docs/homelab/phase-1.md
# When done, push to deploy:
git add .
git commit -m "Add Phase 1 — NAS Setup documentation"
git push origin main

The site updates automatically within 90 seconds of every push.

Verification Checklist

  • [ ] Domain ahanabipin.in purchased on Namecheap
  • [ ] Cloudflare account active, domain showing as active
  • [ ] Nameservers updated in Namecheap to point to Cloudflare
  • [ ] GitHub repo ahanabipin-docs created (private)
  • [ ] Personal Access Token generated with repo and workflow scopes
  • [ ] Python and pipx installed on MacBook
  • [ ] MkDocs 1.6.x installed and verified via mkdocs --version
  • [ ] Full folder structure created — 30 files across 5 sections
  • [ ] mkdocs.yml configured with full nav structure
  • [ ] Site previews correctly locally at http://127.0.0.1:8000
  • [ ] Cloudflare Pages project ahanabipin-docs created
  • [ ] CLOUDFLARE_API_TOKEN and CLOUDFLARE_ACCOUNT_ID added to GitHub repo secrets
  • [ ] GitHub Actions workflow deploying successfully (green tick)
  • [ ] docs.ahanabipin.in loading live MkDocs site with HTTPS ✅

Troubleshooting

zsh: command not found: mkdocs after install: This happens because pip installs into a location not on your PATH, or the install silently failed. Use pipx instead — see Step 6.

error: externally-managed-environment when running pip install: Expected on Python 3.14 with Homebrew. Use pipx as described in Step 6. Do not use the --break-system-packages flag — it can corrupt Homebrew.

No module named mkdocs when running python3 -m mkdocs: MkDocs was not actually installed. Run pip3 show mkdocs to check. If missing, reinstall using pipx as described in Step 6.

GitHub push rejected — workflow scope error: Your Personal Access Token is missing the workflow scope. Go to GitHub → Settings → Developer settings → Tokens (classic) → edit your token → tick workflow → Update token. No new token is generated, the existing token is updated silently. Retry the push.

GitHub push rejected — repository not found: The clone URL contains placeholder text. Make sure you replaced YOURTOKEN and YOURGITHUBUSERNAME with your actual values.

GitHub Actions failing: Go to the Actions tab → click the failed run → read the error log. Most common cause is a missing or incorrectly named secret. Confirm both CLOUDFLARE_API_TOKEN and CLOUDFLARE_ACCOUNT_ID are added correctly in repo Settings → Secrets and variables → Actions.

Custom domain not resolving: DNS propagation can take up to 24 hours in rare cases. Check progress at dnschecker.org. Confirm the custom domain is added in Cloudflare Pages → Custom domains tab.

Phase 0 complete. Proceed to Phase 1 — NAS Setup.