Skip to content

Website Setup & Deployment

This document explains how the CRED Wiki website works, its deployment architecture, and how developers can understand and modify the setup.

Overview

The CRED Wiki is a documentation website built with MkDocs and deployed using GitHub Actions to Netlify. It features GitHub OAuth and Google SSO authentication and is accessible at https://docs.internal.credplatform.com.

The deployment process has been modernized to use GitHub Actions as the CI/CD system, with Netlify serving as a pure hosting platform. This approach provides better control, transparency, and cost efficiency.

Architecture

Components

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   GitHub Repo   │    │ GitHub Actions  │    │     Netlify     │    │   DNS Provider  │
│                 │    │                 │    │                 │    │                 │
│ • MkDocs source │───▶│ • CI/CD builds  │───▶│ • Static hosting│───▶│ • CNAME record  │
│ • OAuth config  │    │ • Dependency mgmt│    │ • CDN delivery  │    │ • SSL cert      │
│ • Google SSO   │    │ • Deploy to prod │    │ • Serverless    │    │ • Domain proxy  │
│ • Netlify funcs │    │ • Preview deploys│    │ • Functions     │    │                 │
└─────────────────┘    └─────────────────┘    └─────────────────┘    └─────────────────┘

Technology Stack

  • Static Site Generator: MkDocs with Material theme
  • CI/CD Platform: GitHub Actions
  • Deployment Platform: Netlify (hosting only)
  • Authentication: GitHub OAuth 2.0 and Google SSO
  • Backend Functions: Netlify Functions (Node.js)
  • Domain: docs.internal.credplatform.com

Deployment Flow

1. Source Code

  • Repository: GitHub repository containing MkDocs source
  • Build Command: pip install -r requirements.txt && python -m mkdocs build
  • Output Directory: site/ (generated by MkDocs)

2. GitHub Actions CI/CD

  • Workflow File: .github/workflows/deploy.yml
  • Triggers:
    • Push to main branch (production deployment)
    • Pull requests to main branch (preview deployments)
  • Build Process:
    1. Checkout repository code
    2. Setup Python 3.11 environment with pip caching
    3. Install dependencies from requirements.txt
    4. Build MkDocs site to ./site directory
    5. Setup Node.js for Netlify CLI
    6. Deploy to Netlify using CLI
  • Environment Variables: Stored in GitHub repository secrets
  • Concurrency Control: Prevents multiple deployments from running simultaneously

3. Netlify Integration

  • Account Access: Netlify account registered for dev@credinvestments.com with Google SSO
  • Hosting Role: Pure static hosting and CDN delivery
  • Deployment Method: GitHub Actions pushes built site via Netlify CLI
  • Environment Variables:
    • GitHub secrets: NETLIFY_AUTH_TOKEN, NETLIFY_SITE_ID (for deployment)
    • Netlify dashboard: Authentication variables, function environment variables
  • Functions: Serverless functions in netlify/functions/ (still hosted by Netlify)

4. DNS Configuration

  • Domain: docs.internal.credplatform.com
  • CNAME Record: Points to Netlify's CDN
  • SSL Certificate: Automatically provisioned by Netlify

Benefits of GitHub Actions Deployment

The migration from Netlify's built-in CI/CD to GitHub Actions provides several key advantages:

Cost Efficiency

  • Single Netlify Pro Account: Only one Netlify Pro account needed (no extra seats or build minutes)
  • Reduced Netlify Usage: Netlify is used purely for hosting, not for build processes
  • GitHub Actions: Leverages GitHub's generous free tier for CI/CD

Enhanced Control & Transparency

  • Full Build Visibility: All build logic and logs live in GitHub Actions
  • Centralized Configuration: Build settings managed in version-controlled workflow files
  • Detailed Logging: Complete transparency into every step of the build and deployment process
  • Easy Debugging: Build failures and issues are clearly visible in GitHub's interface

Advanced CI/CD Features

  • Caching: GitHub Actions provides intelligent caching for dependencies and build artifacts
  • Concurrency Control: Prevents multiple deployments from running simultaneously
  • Custom Workflows: Full control over build steps, testing, and deployment logic
  • Environment Management: Secrets and environment variables managed through GitHub's secure system

Improved Developer Experience

  • Familiar Interface: Developers already use GitHub for code management
  • Integrated Workflow: CI/CD runs in the same platform as code reviews and issue tracking
  • Preview Deployments: Pull request previews automatically generated for testing
  • Rollback Capability: Easy to revert deployments through GitHub's interface

Separation of Concerns

  • GitHub: Handles source control, CI/CD, and automation
  • Netlify: Focuses purely on static hosting, CDN delivery, and serverless functions
  • Clear Boundaries: Each platform handles what it does best

File Structure

CREDWiki/
├── docs/                          # MkDocs source files
│   ├── assets/                    # Static assets
│   │   ├── auth.html             # Login page
│   │   ├── auth-callback.html    # OAuth callback
│   │   ├── google-auth-callback.html # Google OAuth callback
│   │   └── auth-check.js         # Authentication script
│   ├── authentication/           # Auth documentation
│   └── [other content]           # Wiki content
├── netlify/                      # Netlify configuration
│   └── functions/                # Serverless functions
│       ├── github-oauth.js       # GitHub OAuth handler
│       └── google-oauth.js      # Google OAuth handler
├── site/                         # Built site (generated)
├── mkdocs.yml                    # MkDocs configuration
├── netlify.toml                   # Netlify configuration
└── requirements.txt              # Python dependencies

Configuration Files

mkdocs.yml

  • Purpose: MkDocs site configuration
  • Contains: Navigation, theme settings, plugins
  • Key Sections:
    • nav: Site navigation structure
    • theme: Material theme configuration
    • plugins: Search and other plugins

netlify.toml

  • Purpose: Netlify deployment configuration
  • Contains: Build settings and environment variables
  • Key Settings:
    • Build command and directory
    • Environment variables (OAuth credentials)
    • Function settings

requirements.txt

  • Purpose: Python dependencies for MkDocs
  • Contains: MkDocs, Material theme, plugins

DNS & Domain Setup

Current Configuration

  • Domain: docs.internal.credplatform.com
  • Type: CNAME record
  • Target: Netlify CDN endpoint
  • SSL: Automatic via Netlify

How It Works

  1. DNS Lookup: User visits docs.internal.credplatform.com
  2. CNAME Resolution: DNS returns Netlify CDN IP
  3. CDN Routing: Netlify routes to appropriate site
  4. SSL Termination: HTTPS handled by Netlify
  5. Content Delivery: Static files served from CDN

Development Workflow

Local Development

# Install dependencies
pip install -r requirements.txt

# Serve locally (bypasses authentication)
mkdocs serve

# Access at http://localhost:8000

Deployment Process

  1. Code Changes: Push to GitHub repository or create pull request
  2. GitHub Actions Trigger: Workflow automatically starts based on branch/event
  3. Build Process: GitHub Actions runs mkdocs build in isolated environment
  4. Deploy: GitHub Actions pushes built site to Netlify via CLI
  5. CDN Update: Netlify propagates content globally
  6. Preview URLs: Pull requests get preview deployments for testing

Modifying the Setup

Adding New Content

  1. Create Markdown: Add files to docs/ directory
  2. Update Navigation: Modify mkdocs.yml nav section
  3. Commit & Push: Changes trigger GitHub Actions deployment

Changing Authentication

  1. Update OAuth Apps: Modify GitHub OAuth app settings and Google OAuth app settings
  2. Update Environment:
    • Change GitHub repository secrets for deployment (NETLIFY_AUTH_TOKEN, NETLIFY_SITE_ID)
    • Update Netlify dashboard environment variables for authentication
  3. Update Code: Modify authentication files if needed

Changing Domain

  1. Update DNS: Change CNAME record to new target
  2. Update OAuth: Modify GitHub OAuth app callback URL and Google OAuth app callback URL
  3. Update Environment: Change GITHUB_REDIRECT_URI and GOOGLE_REDIRECT_URI in GitHub repository secrets
  4. Update Code: Modify hardcoded URLs in auth files

Adding New Functions

  1. Create Function: Add to netlify/functions/
  2. Update Environment: Add required environment variables to GitHub repository secrets
  3. Test Locally: Use netlify dev to test
  4. Deploy: Push changes to trigger GitHub Actions deployment