Hosting Recommendations for Private Docusaurus Documentation

Overview

This guide provides recommendations for hosting the CTO onboarding documentation privately with GitHub authentication. We'll explore the top hosting platforms, security considerations, and implementation details.

Top 3 Recommended Hosting Platforms

1. Vercel (Recommended)

Pros:

Native GitHub integration with automatic deployments
Built-in authentication with GitHub OAuth via Next.js middleware
Excellent performance with global CDN
Generous free tier (100GB bandwidth/month)
Easy environment variable management
Preview deployments for PRs

Cons:

Authentication requires custom implementation
Limited to 100GB bandwidth on free tier
Serverless function limitations (10s timeout on free tier)

Cost: Free tier suitable for internal docs; Pro plan at $20/user/month if needed

2. Netlify

Pros:

Built-in Identity service with GitHub OAuth support
Simple authentication setup with Netlify Identity
Good performance and CDN
Form handling and serverless functions
Split testing capabilities

Cons:

Identity service limited to 1,000 users/month on free tier
More complex authentication setup than Vercel
Build minutes limited (300/month free)

Cost: Free tier available; Pro plan at $19/member/month

3. AWS Amplify

Pros:

Deep AWS integration
Built-in authentication with AWS Cognito
Scalable and enterprise-ready
Good CI/CD integration
Custom domain support

Cons:

More complex setup
AWS learning curve
Potentially higher costs at scale
Overkill for simple documentation sites

Cost: Pay-as-you-go; ~$0.01/GB served + compute costs

Step-by-Step Setup: Vercel with GitHub Authentication

Prerequisites

GitHub repository with Docusaurus project
Vercel account
GitHub OAuth App

Step 1: Create GitHub OAuth Application

Go to GitHub Settings > Developer settings > OAuth Apps
Click "New OAuth App"

Fill in the details:

Application name: CTO Onboarding Docs
Homepage URL: https://your-docs-domain.vercel.app
Authorization callback URL: https://your-docs-domain.vercel.app/api/auth/callback/github

Save Client ID and Client Secret

Step 2: Prepare Authentication Middleware

Create middleware.ts in your Docusaurus root:

import { NextResponse } from 'next/server'
import type { NextRequest } from 'next/server'
import { getToken } from 'next-auth/jwt'

export async function middleware(request: NextRequest) {
  const token = await getToken({ req: request })
  
  // Allow access to auth endpoints
  if (request.nextUrl.pathname.startsWith('/api/auth')) {
    return NextResponse.next()
  }
  
  // Redirect to login if not authenticated
  if (!token) {
    const url = new URL('/api/auth/signin', request.url)
    url.searchParams.set('callbackUrl', request.url)
    return NextResponse.redirect(url)
  }
  
  // Check if user is in allowed organization
  const allowedOrg = process.env.GITHUB_ALLOWED_ORG
  if (allowedOrg && token.orgs && !token.orgs.includes(allowedOrg)) {
    return NextResponse.redirect(new URL('/unauthorized', request.url))
  }
  
  return NextResponse.next()
}

export const config = {
  matcher: ['/((?!_next/static|favicon.ico|public).*)']
}

Step 3: Configure NextAuth.js

Install dependencies:

npm install next-auth @auth/core

Create app/api/auth/[...nextauth]/route.ts:

import NextAuth from 'next-auth'
import GitHubProvider from 'next-auth/providers/github'

const handler = NextAuth({
  providers: [
    GitHubProvider({
      clientId: process.env.GITHUB_CLIENT_ID!,
      clientSecret: process.env.GITHUB_CLIENT_SECRET!,
      authorization: {
        params: {
          scope: 'read:user user:email read:org'
        }
      }
    })
  ],
  callbacks: {
    async signIn({ user, account, profile }) {
      // Optional: Check if user belongs to specific org
      if (process.env.GITHUB_ALLOWED_ORG) {
        const res = await fetch('https://api.github.com/user/orgs', {
          headers: {
            Authorization: `token ${account?.access_token}`
          }
        })
        const orgs = await res.json()
        const allowedOrg = orgs.find((org: any) => 
          org.login === process.env.GITHUB_ALLOWED_ORG
        )
        return !!allowedOrg
      }
      return true
    },
    async jwt({ token, account, profile }) {
      if (account && profile) {
        token.accessToken = account.access_token
        token.profile = profile
      }
      return token
    },
    async session({ session, token }) {
      session.accessToken = token.accessToken
      session.profile = token.profile
      return session
    }
  },
  pages: {
    signIn: '/auth/signin',
    error: '/auth/error'
  }
})

export { handler as GET, handler as POST }

Step 4: Deploy to Vercel

Connect your GitHub repository to Vercel

Configure environment variables in Vercel dashboard:

GITHUB_CLIENT_ID=your_client_id
GITHUB_CLIENT_SECRET=your_client_secret
NEXTAUTH_URL=https://your-docs-domain.vercel.app
NEXTAUTH_SECRET=generate_random_secret
GITHUB_ALLOWED_ORG=your-github-org (optional)

Deploy:
```
vercel --prod
```

Step 5: Configure Custom Domain (Optional)

In Vercel dashboard, go to Settings > Domains
Add your custom domain
Update DNS records as instructed
Update GitHub OAuth App URLs

Security Considerations

1. Authentication Security

Use strong NEXTAUTH_SECRET (minimum 32 characters)
Enable HTTPS only (automatic on Vercel)
Implement proper session management
Set appropriate token expiration times

2. Access Control

Restrict by GitHub organization membership
Implement role-based access if needed
Audit authentication logs regularly
Use environment-specific OAuth apps

3. Content Security

Implement CSP headers
Sanitize user inputs
Avoid exposing sensitive information in client-side code
Regular security updates

4. Infrastructure Security

Enable 2FA on hosting platform
Restrict deployment permissions
Use secret management for sensitive values
Regular security audits

Cost Analysis

Vercel (Recommended)

Free Tier: Sufficient for most internal documentation
- 100GB bandwidth
- Unlimited sites
- Automatic HTTPS
Pro: $20/user/month
- 1TB bandwidth
- Advanced analytics
- Priority support

Netlify

Free Tier: Good for small teams
- 100GB bandwidth
- 300 build minutes
- 1,000 identity users
Pro: $19/member/month
- 400GB bandwidth
- 1,000 build minutes
- 5,000 identity users

AWS Amplify

Pay-as-you-go:
- Build & Deploy: $0.01 per build minute
- Hosting: $0.15 per GB served
- Typically $5-20/month for documentation sites

Integration with CI/CD Pipeline

GitHub Actions Integration

Create .github/workflows/deploy.yml:

name: Deploy to Vercel

on:
  push:
    branches: [main]
  pull_request:
    types: [opened, synchronize]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '18'
          cache: 'npm'
      
      - name: Install dependencies
        run: npm ci
      
      - name: Build Docusaurus
        run: npm run build
        
      - name: Deploy to Vercel
        uses: amondnet/vercel-action@v25
        with:
          vercel-token: ${{ secrets.VERCEL_TOKEN }}
          vercel-args: ${{ github.event_name == 'push' && '--prod' || '' }}
          vercel-org-id: ${{ secrets.VERCEL_ORG_ID }}
          vercel-project-id: ${{ secrets.VERCEL_PROJECT_ID }}

Pre-deployment Checks

Add to your CI/CD pipeline:

- name: Run security checks
  run: |
    npm audit
    npm run lint
    npm run type-check

- name: Test authentication
  run: npm run test:auth

- name: Build preview
  if: github.event_name == 'pull_request'
  run: echo "Preview URL will be available after deployment"

Monitoring and Maintenance

1. Setup Monitoring

Enable Vercel Analytics for traffic insights
Set up uptime monitoring (e.g., UptimeRobot)
Configure error tracking (e.g., Sentry)

2. Regular Maintenance

Update dependencies monthly
Review authentication logs
Monitor bandwidth usage
Update documentation as needed

3. Backup Strategy

GitHub repository serves as primary backup
Consider periodic exports of analytics data
Document configuration and secrets securely

Conclusion

Vercel provides the best balance of ease-of-use, performance, and cost-effectiveness for hosting private Docusaurus documentation with GitHub authentication. The setup process is straightforward, and the platform handles most of the infrastructure complexity, allowing you to focus on creating great documentation.

For enterprise needs or specific compliance requirements, consider AWS Amplify or a self-hosted solution on your existing infrastructure.

Overview​

Top 3 Recommended Hosting Platforms​

1. Vercel (Recommended)​

2. Netlify​

3. AWS Amplify​

Step-by-Step Setup: Vercel with GitHub Authentication​

Prerequisites​

Step 1: Create GitHub OAuth Application​

Step 2: Prepare Authentication Middleware​

Step 3: Configure NextAuth.js​

Step 4: Deploy to Vercel​

Step 5: Configure Custom Domain (Optional)​

Security Considerations​

1. Authentication Security​

2. Access Control​

3. Content Security​

4. Infrastructure Security​

Cost Analysis​

Vercel (Recommended)​

Netlify​

AWS Amplify​

Integration with CI/CD Pipeline​

GitHub Actions Integration​

Pre-deployment Checks​

Monitoring and Maintenance​

1. Setup Monitoring​

2. Regular Maintenance​

3. Backup Strategy​

Conclusion​

Quick Navigation

Overview

Top 3 Recommended Hosting Platforms

1. Vercel (Recommended)

2. Netlify

3. AWS Amplify

Step-by-Step Setup: Vercel with GitHub Authentication

Prerequisites

Step 1: Create GitHub OAuth Application

Step 2: Prepare Authentication Middleware

Step 3: Configure NextAuth.js

Step 4: Deploy to Vercel

Step 5: Configure Custom Domain (Optional)

Security Considerations

1. Authentication Security

2. Access Control

3. Content Security

4. Infrastructure Security

Cost Analysis

Vercel (Recommended)

Netlify

AWS Amplify

Integration with CI/CD Pipeline

GitHub Actions Integration

Pre-deployment Checks

Monitoring and Maintenance

1. Setup Monitoring

2. Regular Maintenance

3. Backup Strategy

Conclusion