John

Senior Cloud Engineer & Technical Lead

Deployment Guide

This guide explains how the johnoct.github.io website is deployed and how to manage the deployment process.

Deployment Overview

The site uses GitHub Pages for hosting with automatic deployment from the master branch. This provides a seamless, zero-configuration deployment process.

Key Features

Architecture

GitHub Pages Build Process

Local Development → Git Push → GitHub Actions → Jekyll Build → Static Files → Live Site
  1. Local Changes: Make modifications locally and test with bundle exec jekyll serve
  2. Git Push: Push commits to the master branch
  3. GitHub Actions: Automatic build process starts
  4. Jekyll Build: GitHub’s Jekyll runner generates static files
  5. Site Deployment: Static files are served at johnoct.github.io
  6. Cache Invalidation: CDN cache refreshes for instant updates

Build Environment

GitHub Pages uses:

Deployment Workflow

Standard Development Cycle

# 1. Make changes locally
vim _posts/2025-07-27-new-post.md

# 2. Test locally
bundle exec jekyll serve --host 0.0.0.0 --port 4000

# 3. Verify changes at http://localhost:4000

# 4. Commit changes
git add _posts/2025-07-27-new-post.md
git commit -m "Add new technical post about container optimization"

# 5. Deploy to production
git push origin master

# 6. Verify deployment (1-2 minutes later)
# Visit https://johnoct.github.io

Automated Content Deployment

For GitHub stars automation:

# 1. Run automation script
./scripts/daily-stars.sh

# 2. Review generated content
cat _posts/$(date +%Y-%m-%d)-daily-github-stars.md

# 3. Commit and deploy
git add _posts/
git commit -m "Add daily GitHub stars collection"
git push origin master

Configuration

GitHub Pages Settings

The repository is configured with:

# In repository settings > Pages:
Source: Deploy from a branch
Branch: master
Folder: / (root)
Custom domain: (optional)
Enforce HTTPS: ✓ Enabled

Jekyll Configuration (_config.yml)

Production-specific settings:

# Site URL for GitHub Pages
url: "https://johnoct.github.io"
baseurl: ""

# Build settings for GitHub Pages
markdown: kramdown
highlighter: rouge
theme: minima

# Plugins (GitHub Pages approved)
plugins:
  - jekyll-feed
  - jekyll-sitemap

# Exclude development files from builds
exclude:
  - Gemfile
  - Gemfile.lock
  - node_modules
  - vendor/
  - .sass-cache/
  - .jekyll-cache/
  - gemfiles/
  - docs/
  - scripts/
  - README.md

Build Optimization

GitHub Pages automatically:

Monitoring Deployment

GitHub Actions Tab

Monitor build status at: https://github.com/johnoct/johnoct.github.io/actions

Build Status Indicators

Common Build Information

Build Logs

Access detailed logs by clicking on any build in GitHub Actions:

Run actions/jekyll-build-pages@v1
/usr/bin/docker run --name ghcrioactionsjekyllbuildpagesv1...
Configuration file: /github/workspace/_config.yml
            Source: /github/workspace
       Destination: /github/workspace/_site
 Incremental build: disabled. Enable with --incremental
      Generating... 
                    done in 2.847 seconds.
 Auto-regeneration: disabled. Use --watch to enable.

Troubleshooting

Common Deployment Issues

Build Failures

Syntax Errors in Markdown:

Error: The file '_posts/2025-07-27-post.md' appears to have invalid front matter

Solution:

Plugin Errors:

Error: The plugin 'jekyll-custom-plugin' is not allowed

Solution:

Content Issues

Missing Posts:

Broken Links:

CSS/Styling Problems:

Deployment Verification

Automated Checks

Create a simple verification script:

#!/bin/bash
# verify-deployment.sh

SITE_URL="https://johnoct.github.io"
EXPECTED_TITLE="John - Senior Cloud Engineer"

echo "Checking deployment status..."

# Check if site is accessible
HTTP_STATUS=$(curl -s -o /dev/null -w "%{http_code}" "$SITE_URL")

if [ "$HTTP_STATUS" -eq 200 ]; then
    echo "✅ Site is accessible (Status: $HTTP_STATUS)"
else
    echo "❌ Site access failed (Status: $HTTP_STATUS)"
    exit 1
fi

# Check if content is correct
TITLE=$(curl -s "$SITE_URL" | grep -o "<title>[^<]*" | sed 's/<title>//')

if [[ "$TITLE" == *"$EXPECTED_TITLE"* ]]; then
    echo "✅ Site title is correct"
else
    echo "❌ Site title mismatch. Expected: $EXPECTED_TITLE, Got: $TITLE"
fi

# Check RSS feed
RSS_STATUS=$(curl -s -o /dev/null -w "%{http_code}" "$SITE_URL/feed.xml")

if [ "$RSS_STATUS" -eq 200 ]; then
    echo "✅ RSS feed is accessible"
else
    echo "❌ RSS feed failed (Status: $RSS_STATUS)"
fi

echo "Deployment verification complete"

Manual Verification Checklist

After each deployment:

Performance Optimization

Build Performance

Optimize Build Times:

Content Optimization:

Site Performance

GitHub Pages automatically provides:

Additional Optimizations:

# _config.yml
sass:
  style: compressed

# Optimize plugin configuration
plugins:
  - jekyll-sitemap
  - jekyll-feed

Security Considerations

GitHub Pages Security

Built-in security features:

Content Security

Best Practices:

Repository Security:

# Check for sensitive data
git log --all --full-history -- "*/secrets/*" "*/config/*" "*/.env*"

# Use .gitignore for sensitive files
echo "*.log" >> .gitignore
echo ".env*" >> .gitignore
echo "node_modules/" >> .gitignore

Backup and Recovery

Content Backup

Git provides automatic backup:

Disaster Recovery

Full Site Recovery:

# Clone repository
git clone https://github.com/johnoct/johnoct.github.io.git

# Install dependencies
bundle install

# Restore local development
bundle exec jekyll serve

Content Recovery:

# Restore specific post
git checkout HEAD~1 -- _posts/2025-07-27-post.md

# Restore entire posts directory
git checkout HEAD~1 -- _posts/

# Restore to previous commit
git reset --hard HEAD~1
git push --force-with-lease origin master

Advanced Deployment

Custom Domain Setup

To use a custom domain:

  1. Add CNAME file: 
    echo "yourdomain.com" > CNAME
git add CNAME
git commit -m "Add custom domain"
git push origin master
  2. Configure DNS: ```

    A records

    @ 185.199.108.153 @ 185.199.109.153 @ 185.199.110.153 @ 185.199.111.153

CNAME record (for www subdomain)

www yourdomain.com


3. **Enable HTTPS in repository settings**

### Environment-Specific Configuration

Use Jekyll environments for different configurations:

```yaml
# _config.yml (production)
url: "https://johnoct.github.io"
google_analytics: "GA-TRACKING-ID"

# _config_development.yml (local development)
url: "http://localhost:4000"
# google_analytics: # disabled for development

Run development with specific config:

bundle exec jekyll serve --config _config.yml,_config_development.yml

Continuous Integration

Automated Testing

Although GitHub Pages handles builds, you can add testing:

# .github/workflows/test.yml
name: Test
on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: ruby/setup-ruby@v1
        with:
          ruby-version: 3.1
          bundler-cache: true
      - name: Build site
        run: bundle exec jekyll build
      - name: Test links
        run: bundle exec htmlproofer ./_site --disable-external

Deployment Notifications

Set up Slack notifications for deployments:

# Add to GitHub Actions workflow
- name: Notify Slack
  if: always()
  uses: 8398a7/action-slack@v3
  with:
    status: $
    text: "Site deployment $"
  env:
    SLACK_WEBHOOK_URL: $

Deployment Status: The site deploys automatically on every push to master. Monitor the GitHub Actions tab for build status and logs.