Deployment Guide

This guide covers deploying the Poway Auto Jekyll site to GitHub Pages and setting up a local development environment for testing and customization.

GitHub Pages Deployment

Poway Auto is configured for automatic deployment to GitHub Pages using GitHub Actions.

Current Deployment

The site is already deployed at: https://ahaanv19.github.io/QAV_Frontend/

Repository: Ahaanv19/QAV_Frontend
Branch: main
Base URL: /QAV_Frontend
Theme: jekyll/minima (dark skin)

GitHub Actions Workflow

Deployment is automated via .github/workflows/jekyll-gh-pages.yml:

name: Deploy Jekyll with GitHub Pages dependencies preinstalled

on:
  push:
    branches: ["main"]
  workflow_dispatch:

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@v3
        
      - name: Set up Ruby
        uses: ruby/setup-ruby@v1
        with:
          ruby-version: '3.1'
          bundler-cache: true
          
      - name: Install Jekyll and dependencies
        run: |
          gem install bundler
          bundle install
          
      - name: Install Python dependencies
        run: |
          python -m venv venv
          source venv/bin/activate
          pip install -r requirements.txt
          
      - name: Execute conversion script
        run: |
          source venv/bin/activate
          python scripts/convert_notebooks.py
          
      - name: Build with Jekyll
        run: bundle exec jekyll build
        
      - 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

Automatic Trigger

Every push to the main branch automatically triggers the workflow.

Build Process

The workflow:

Installs Ruby 3.1 and Jekyll dependencies
Sets up Python virtual environment
Converts Jupyter notebooks to Markdown
Builds the Jekyll site

Deployment

The built site is deployed to GitHub Pages with proper permissions and artifact handling.

Deployment typically completes within 2-3 minutes after pushing changes.

Manual Deployment Trigger

You can also trigger deployment manually:

Navigate to Actions tab in the GitHub repository
Select Deploy Jekyll with GitHub Pages
Click Run workflow
Choose the main branch and click Run workflow

Local Development Setup

Set up Poway Auto locally for development and testing.

Prerequisites

Ruby

Ruby 3.1 or higher

ruby --version

Bundler

Gem package manager

gem install bundler

Python

Python 3.8+ with pip

python --version

Git

Version control

git --version

Installation Steps

Clone the Repository

git clone https://github.com/Ahaanv19/QAV_Frontend.git
cd QAV_Frontend

Install Ruby Dependencies

The project uses a Gemfile to manage Jekyll dependencies:

Gemfile

source "https://rubygems.org"

gem "github-pages", group: :jekyll_plugins
gem "webrick", "~> 1.7"
gem "execjs", "~> 2.8"

Install gems:

bundle install

Install Python Dependencies

For Jupyter notebook conversion and data processing:

requirements.txt

nbconvert
nbformat
pyyaml
notebook
requests
python-dotenv
pandas
seaborn
scikit-learn
progress

Install with pip:

pip install -r requirements.txt
# Or use virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -r requirements.txt

Convert Notebooks (if applicable)

If you have Jupyter notebooks in _notebooks/:

make convert

This runs the conversion script to generate Markdown posts.

Running the Development Server

The Makefile provides convenient commands for local development.

Default Server

Start the Jekyll development server:

make
# Or explicitly:
make server

This command:

Stops any existing server on the port
Converts Jupyter notebooks to Markdown
Starts Jekyll server on http://127.0.0.1:4887/flocker_frontend/
Watches for file changes and auto-regenerates

The default port is 4887. The server URL will be displayed in the terminal output.

Custom Port

Run on a different port:

make PORT=4000

Server Output

You’ll see output like:

Stopping server...
Converting notebooks...
Starting server...
Server PID: 12345
Terminal logging starting, watching server...
Server started in 3 seconds

Access the site at the URL shown in the logs.

Makefile Commands

The Makefile includes several useful targets:

make
# or
make server
# Starts development server with auto-reload

Makefile Configuration

Key variables in the Makefile:

PORT ?= 4887                    # Default development port
REPO_NAME ?= flocker_frontend   # Repository name for URLs
LOG_FILE = /tmp/jekyll$(PORT).log

Jekyll Configuration

The _config.yml file controls site settings:

title: Poway Auto
description: "An online program to find the best and most optimible route for traveling to Qualcomm"
owner_name: Ahaan Vaidyanathan
github_username: Ahaanv19
github_repo: "QAV_Frontend"
baseurl: "/QAV_Frontend"
future: true
remote_theme: jekyll/minima
minima:
  skin: dark
plugins:
  - jekyll-remote-theme
header_pages:
  - /search
  - /about
  - /blogs
  - /Readme4yml

Important Configuration Options

baseurl

Set to /QAV_Frontend for GitHub Pages deployment.For local development, Jekyll automatically handles this. All asset paths use {{site.baseurl}} for portability.

remote_theme

Uses jekyll/minima with dark skin. Alternative themes are commented out:

pages-themes/midnight
pages-themes/dinky
pages-themes/minimal
pages-themes/cayman
pages-themes/time-machine

Uncomment to switch themes.

future: true

Allows posts with future dates to be published. Useful during development.

Build Commands

Production Build

Build the site for production:

bundle exec jekyll build

Output is generated in _site/ directory.

Development Build with Watch

bundle exec jekyll serve -H 127.0.0.1 -P 4887

Options:

-H 127.0.0.1: Bind to localhost
-P 4887: Port number
Auto-regenerates on file changes
Live reload available

Build with Drafts

bundle exec jekyll serve --drafts

Includes posts from _drafts/ folder.

Project Structure

Understanding the directory layout:

QAV_Frontend/
├── _config.yml           # Jekyll configuration
├── _data/                # YAML data files
├── _includes/            # Reusable HTML components
├── _layouts/             # Page templates
├── _notebooks/           # Jupyter notebooks (converted to posts)
├── _posts/               # Blog posts and documentation
├── _sass/                # Sass stylesheets
├── assets/
│   └── js/
│       └── api/
│           └── config.js # API endpoint configuration
├── navigation/           # Feature pages
│   ├── verify.html       # Location verification
│   ├── dailyroutine.html # Schedule planner
│   ├── traffic.html      # Hazard reporting
│   ├── findBestRoute/    # Route finder
│   └── favoriteLocations/ # Saved locations
├── index.md              # Homepage
├── Gemfile               # Ruby dependencies
├── requirements.txt      # Python dependencies
├── Makefile              # Build automation
└── .github/
    └── workflows/
        └── jekyll-gh-pages.yml # CI/CD pipeline

API Configuration

The frontend connects to backend APIs defined in assets/js/api/config.js:

export var pythonURI;
if (location.hostname === "localhost") {
  pythonURI = "http://localhost:8888";
} else if (location.hostname === "127.0.0.1") {
  pythonURI = "http://127.0.0.1:8888";
} else {
  pythonURI = "https://autonomous.stu.nighthawkcodingsociety.com";
}

export const fetchOptions = {
  method: 'GET',
  mode: 'cors',
  cache: 'default',
  credentials: 'include',
  headers: {
    'Content-Type': 'application/json',
    'X-Origin': 'client'
  }
};

For local development with API features, ensure the backend server is running on port 8888, or update the configuration accordingly.

Troubleshooting

Common Issues

Port Already in Use

If port 4887 is occupied:

make stop  # Kill processes on the port
# Or use a different port:
make PORT=4000

Bundle Install Fails

Ensure you have the correct Ruby version:

ruby --version  # Should be 3.1+
gem install bundler
bundle install

On some systems, you may need:

bundle install --path vendor/bundle

Notebook Conversion Errors

If notebook conversion fails:

# Ensure Python dependencies are installed
pip install -r requirements.txt

# Check for corrupt notebooks
find _notebooks -name '*.ipynb' -exec jupyter nbconvert --to markdown {} \;

CSS/JS Not Loading

Ensure all asset paths use {{site.baseurl}}:

<!-- Correct -->
<link rel="stylesheet" href="{{site.baseurl}}/navigation/findBestRoute/map.css">

<!-- Incorrect -->
<link rel="stylesheet" href="/navigation/findBestRoute/map.css">

API CORS Errors

The backend must have CORS enabled for the frontend domain:

# Backend should allow:
Access-Control-Allow-Origin: https://ahaanv19.github.io
Access-Control-Allow-Credentials: true

Production Checklist

Before deploying to production:

Test all routes locally with make server
Verify API endpoints are accessible
Check that all images and assets load correctly
Test responsive design on mobile devices
Ensure geolocation permissions work in target browsers
Validate all forms submit successfully
Review and update _config.yml settings
Test GitHub Actions workflow on a feature branch
Clear browser cache to test fresh deployment

Advanced Configuration

Custom Domain

To use a custom domain with GitHub Pages:

Add a CNAME file to the repository root:
```
powayauto.com
```

Update _config.yml:

url: "https://powayauto.com"
baseurl: ""

Configure DNS with your domain provider

Environment Variables

For sensitive configuration, use environment variables:

const API_KEY = process.env.MAPS_API_KEY || 'default-key';

In GitHub Actions:

env:
  MAPS_API_KEY: ${{ secrets.MAPS_API_KEY }}

Continuous Integration

The GitHub Actions workflow provides:

Automated builds on every push
Dependency caching for faster builds
Python notebook conversion before building
Artifact upload for deployment
Concurrent deployment prevention to avoid conflicts

Monitor the Actions tab in GitHub to track deployment status and debug any build failures.

Next Steps

After deployment:

Monitor Usage: Check GitHub Pages analytics
Update Content: Add new features and documentation
Optimize Performance: Minimize assets, enable caching
Gather Feedback: Collect user input for improvements
Iterate: Continuously enhance based on real-world usage

For feature usage instructions, see the Quickstart Guide.

Getting Started

Core Features

Components

Development

Deployment Guide

Deployment Guide

GitHub Pages Deployment

Current Deployment

GitHub Actions Workflow

Manual Deployment Trigger

Local Development Setup

Prerequisites

Ruby

Bundler

Python

Git

Installation Steps

Running the Development Server

Default Server

Custom Port

Server Output

Makefile Commands

Makefile Configuration

Jekyll Configuration

Important Configuration Options

Build Commands

Production Build

Development Build with Watch

Build with Drafts

Project Structure

API Configuration

Troubleshooting

Common Issues

Production Checklist

Advanced Configuration

Custom Domain

Environment Variables

Continuous Integration

Next Steps

Build docs developers (and LLMs) love

Getting Started

Core Features

Components

Development

​Deployment Guide

​GitHub Pages Deployment

​Current Deployment

​GitHub Actions Workflow

​Manual Deployment Trigger

​Local Development Setup

​Prerequisites

Ruby

Bundler

Python

Git

​Installation Steps

​Running the Development Server

​Default Server

​Custom Port

​Server Output

​Makefile Commands

​Makefile Configuration

​Jekyll Configuration

​Important Configuration Options

​Build Commands

​Production Build

​Development Build with Watch

​Build with Drafts

​Project Structure

​API Configuration

​Troubleshooting

​Common Issues

​Production Checklist

​Advanced Configuration

​Custom Domain

​Environment Variables

​Continuous Integration

​Next Steps

Build docs developers (and LLMs) love

Deployment Guide

GitHub Pages Deployment

Current Deployment

GitHub Actions Workflow

Manual Deployment Trigger

Local Development Setup

Prerequisites

Installation Steps

Running the Development Server

Default Server

Custom Port

Server Output

Makefile Commands

Makefile Configuration

Jekyll Configuration

Important Configuration Options

Build Commands

Production Build

Development Build with Watch

Build with Drafts

Project Structure

API Configuration

Troubleshooting

Common Issues

Production Checklist

Advanced Configuration

Custom Domain

Environment Variables

Continuous Integration

Next Steps