Skip to content

Local Codex Site Deployment

This guide walks you through getting a local copy of the site running on a windows 11 machine — from installing the tools to seeing the site live in your browser.

Step 1 — Install Git

Git is used to download a local copy of the site files from GitHub.

  1. Go to https://git-scm.com/download/win and download the installer.
  2. Run the installer — the default options are fine for all steps.
  3. Once installed, open a terminal and confirm it worked:
git --version

You should see something like git version 2.x.x.

Step 2 — Install VS Code

VS Code is the editor you'll use to work with the site files and run the local server.

  1. Go to https://code.visualstudio.com and download the installer for Windows.
  2. Run the installer — tick "Add to PATH" when prompted (this is important).
  3. Once installed, open VS Code to confirm it launches correctly.

Step 3 — Clone the repository

This downloads a local copy of the Codex files to your machine.

  1. Open VS Code.
  2. Press Ctrl+Shift+P to open the Command Palette.
  3. Type Git: Clone and select it.
  4. Paste in the repository URL when prompted and press Enter.
  5. Choose a folder on your machine to save it into (e.g. C:\Github\Codex).
  6. When VS Code asks "Would you like to open the cloned repository?", click Open.

Tip

If you haven't linked VS Code to GitHub before, a browser window will open asking you to sign in. Follow the prompts to authorise VS Code — you only need to do this once.

Step 4 — Run the setup script

The setup script installs everything the site needs to run locally. You only need to do this once.

Note

This script requires winget, if for some reason your PC does not have winget installed, you can use the command below in powershell. 

# Requires NuGet provider
Install-PackageProvider -Name NuGet -Force
Install-Module -Name Microsoft.WinGet.Client -Force
Repair-WinGetPackageManager

  1. In VS Code, open the integrated terminal: Ctrl+`
  2. Make sure you're in the root of the cloned folder (the terminal prompt should show the Codex folder path).
  3. Run the setup script:
.\setup.ps1

The script will:

  • Install Python 3.12 if it isn't already present
  • Install the GTK3 runtime (you may see a UAC prompt — click Yes and you will need to click through the installer, all the defaults are fine)
  • Create a local Python virtual environment (.venv)
  • Install all required site packages

Note

If PowerShell blocks the script with an execution policy error, run this first, then retry: 

Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned

Step 5 — Start the local server

Once setup is complete, run:

.\serve.ps1

The site will build and open automatically in your default browser at http://127.0.0.1:8000. Any changes you save to a file will refresh the browser instantly.

Tip

You can also start the server from the VS Code Command Palette: Ctrl+Shift+P → Tasks: Run Task → Serve docs (properdocs).

When running properdocs serve in a local Windows development environment (such as VS Code), you may encounter a stream of warnings in your console resembling the following:

WARNING - Couldn't create symbolic link: assets/external/...

This occurs because the privacy plugin attempts to create symbolic links to manage downloaded assets (like fonts and scripts) locally, but Windows restricts symlink creation to administrators by default.

You can resolve this warning permanently by temporarily enabling Developer Mode.

Step-by-Step Fix

  • Navigate to Windows Settings - System - Advanced
  • Toggle Developer Mode to On
  • Serve properdocs, let it create the required symlink
  • Toggle Developer Mode to Off to keep Windows secure
Note: This may be required in future if fonts or other changes occur

You're done

The site is now running locally. You can edit any .md file in the docs/ folder and see your changes live in the browser as you save.