GitHub Pages Deployment - RFS-Portable-BTS

🎯 GitHub Pages Overview

GitHub Pages provides a powerful platform for hosting static websites directly from your GitHub repository. This guide covers the complete setup of automated deployment for RFS-Portable-BTS documentation using GitHub Actions and custom domain configuration.

✅ Key Features

Automated CI/CD pipeline, custom domain support, SSL certificates, and professional documentation hosting for RFS-Portable-BTS.

🔧 Repository Setup

📁 Repository Structure

docs/ - Documentation files
.github/workflows/ - CI/CD pipelines
CNAME - Custom domain
.nojekyll - Jekyll bypass
robots.txt - SEO configuration
sitemap.xml - Search engine sitemap

⚙️ Configuration Files

_config.yml - Jekyll configuration
Gemfile - Ruby dependencies
package.json - Node.js dependencies
.gitignore - Version control exclusions
README.md - Project documentation
LICENSE - Project license

🎨 Assets

assets/ - Images and media
favicon/ - Website icons
css/ - Stylesheets
js/ - JavaScript files
fonts/ - Custom fonts
includes/ - Reusable components

🔄 CI/CD Pipeline

GitHub Actions Workflow

# .github/workflows/jekyll-gh-pages.yml
name: Deploy Jekyll site to Pages

on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]

permissions:
  contents: read
  pages: write
  id-token: write

concurrency:
  group: "pages"
  cancel-in-progress: false

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
        
      - name: Setup Ruby
        uses: ruby/setup-ruby@v1
        with:
          ruby-version: '3.1'
          bundler-cache: true
          
      - name: Setup Pages
        uses: actions/configure-pages@v4
        
      - name: Build with Jekyll
        uses: actions/jekyll-build-pages@v1
        with:
          source: ./docs
          destination: ./_site
          
      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3

  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    needs: build
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

Build Configuration

# docs/_config.yml
title: RFS-Portable-BTS
description: Portable NB-IoT/GSM/IoT Security Testing Platform
author: RFS - Revolutionary Future Systems
email: [email protected]
url: https://portable-bts.telco-sec.com
baseurl: ""

# Build settings
markdown: kramdown
highlighter: rouge
permalink: pretty
timezone: UTC

# Plugins
plugins:
  - jekyll-feed
  - jekyll-sitemap
  - jekyll-seo-tag

# Exclude files
exclude:
  - Gemfile
  - Gemfile.lock
  - node_modules
  - vendor
  - .sass-cache
  - .jekyll-cache
  - .jekyll-metadata
  - README.md

# Include files
include:
  - _redirects
  - .nojekyll
  - CNAME
  - robots.txt
  - sitemap.xml

# Collections
collections:
  docs:
    output: true
    permalink: /:collection/:name/

# Defaults
defaults:
  - scope:
      path: ""
      type: "pages"
    values:
      layout: "default"
      author: "RFS - Revolutionary Future Systems"

# SEO
seo:
  type: "WebSite"
  name: "RFS-Portable-BTS"
  description: "Portable NB-IoT/GSM/IoT Security Testing Platform"
  url: "https://portable-bts.telco-sec.com"
  image: "/assets/images/open-graph-main.png"
  twitter:
    username: "@TelcoSec"
  facebook:
    app_id: "123456789"
  google:
    site_verification: "your-google-verification-code"

🌐 Custom Domain Setup

🔧 Domain Configuration

Create CNAME file
Configure DNS records
Enable HTTPS
Set up redirects
Configure subdomains
SSL certificate management

📋 DNS Records

A records for root domain
CNAME for www subdomain
TXT records for verification
MX records for email
SPF records for security
DKIM records for authentication

CNAME Configuration

# Create docs/CNAME file
echo "portable-bts.telco-sec.com" > docs/CNAME

# Verify CNAME file
cat docs/CNAME
# Output: portable-bts.telco-sec.com

DNS Configuration

# DNS Records for portable-bts.telco-sec.com
# A Records (IPv4)
185.199.108.153
185.199.109.153
185.199.110.153
185.199.111.153

# AAAA Records (IPv6)
2606:50c0:8000::153
2606:50c0:8001::153
2606:50c0:8002::153
2606:50c0:8003::153

# CNAME Record
www.portable-bts.telco-sec.com -> portable-bts.telco-sec.com

# TXT Records
# GitHub Pages verification
_github-pages-challenge-telco-sec.com

# SPF Record
v=spf1 include:_spf.google.com ~all

# DKIM Record
default._domainkey.portable-bts.telco-sec.com

🔒 Security Configuration

🛡️ Security Headers

Content Security Policy
X-Frame-Options
X-Content-Type-Options
X-XSS-Protection
Strict-Transport-Security
Referrer-Policy

🔐 Access Control

robots.txt configuration
Security.txt file
Rate limiting
DDoS protection
Bot protection
Malware scanning

Security Headers

# docs/_includes/security-headers.html

Security.txt

# docs/security.txt
Contact: mailto:[email protected]
Contact: https://portable-bts.telco-sec.com/security.html
Expires: 2025-12-31T23:59:59.000Z
Encryption: https://portable-bts.telco-sec.com/pgp-key.txt
Acknowledgments: https://portable-bts.telco-sec.com/security.html
Preferred-Languages: en
Canonical: https://portable-bts.telco-sec.com/security.txt
Policy: https://portable-bts.telco-sec.com/security-policy.html

📊 Monitoring and Analytics

📈 Analytics Setup

Google Analytics 4
Google Search Console
Bing Webmaster Tools
GitHub Pages analytics
Custom event tracking
Performance monitoring

🔍 SEO Optimization

Meta tags optimization
Open Graph tags
Twitter Cards
Schema markup
Sitemap generation
Robots.txt configuration

Google Analytics Setup

# docs/_includes/google-analytics.html




# Add to _config.yml
google_analytics: GA_MEASUREMENT_ID

🔧 Troubleshooting

❌ Common Issues

Build failures
Custom domain not working
SSL certificate issues
DNS propagation delays
Jekyll build errors
Asset loading problems

🔍 Diagnostic Commands

DNS lookup verification
SSL certificate check
Build log analysis
Asset path verification
GitHub Pages status
Performance testing

Diagnostic Script

#!/bin/bash
# GitHub Pages Diagnostic Script

echo "=== GitHub Pages Diagnostics ==="

# Check DNS resolution
echo "1. DNS Resolution Check:"
nslookup portable-bts.telco-sec.com && echo "✓ DNS resolution OK" || echo "✗ DNS resolution failed"

# Check SSL certificate
echo "2. SSL Certificate Check:"
openssl s_client -connect portable-bts.telco-sec.com:443 -servername portable-bts.telco-sec.com < /dev/null 2>/dev/null | openssl x509 -noout -dates && echo "✓ SSL certificate OK" || echo "✗ SSL certificate issues"

# Check GitHub Pages status
echo "3. GitHub Pages Status:"
curl -s -o /dev/null -w "%{http_code}" https://portable-bts.telco-sec.com && echo "✓ Site accessible" || echo "✗ Site not accessible"

# Check build status
echo "4. Build Status Check:"
curl -s "https://api.github.com/repos/TelcoSec/RFS-Portable-BTS/pages" | grep -o '"status":"[^"]*"' && echo "✓ Build status retrieved" || echo "✗ Build status check failed"

# Check CNAME file
echo "5. CNAME File Check:"
curl -s https://portable-bts.telco-sec.com/CNAME && echo "✓ CNAME file accessible" || echo "✗ CNAME file not accessible"

# Check robots.txt
echo "6. Robots.txt Check:"
curl -s https://portable-bts.telco-sec.com/robots.txt && echo "✓ Robots.txt accessible" || echo "✗ Robots.txt not accessible"

# Check sitemap
echo "7. Sitemap Check:"
curl -s -o /dev/null -w "%{http_code}" https://portable-bts.telco-sec.com/sitemap.xml && echo "✓ Sitemap accessible" || echo "✗ Sitemap not accessible"

echo "=== Diagnostics Complete ==="

🚀 GitHub Pages Deployment