|
| 1 | +# GitHub Pages Setup for TritonParse |
| 2 | + |
| 3 | +This document explains how to set up automatic deployment to GitHub Pages for the TritonParse website. |
| 4 | + |
| 5 | +## Prerequisites |
| 6 | + |
| 7 | +1. Enable GitHub Pages in your repository settings |
| 8 | +2. Set the source to "GitHub Actions" (not "Deploy from a branch") |
| 9 | + |
| 10 | +## Workflow Options |
| 11 | + |
| 12 | +### Option 1: Standard Deployment (Recommended) |
| 13 | + |
| 14 | +- **File**: `.github/workflows/deploy-pages.yml` |
| 15 | +- **Trigger**: Automatic on push to `main` branch when website files change |
| 16 | +- **Output**: Standard Vite build with separate CSS/JS files |
| 17 | +- **Use case**: Standard web hosting with multiple files |
| 18 | + |
| 19 | +### Option 2: Standalone Deployment |
| 20 | + |
| 21 | +- **File**: `.github/workflows/deploy-pages-standalone.yml` |
| 22 | +- **Trigger**: Manual dispatch only |
| 23 | +- **Output**: Single HTML file with all assets inlined |
| 24 | +- **Use case**: Single-file deployment, easier hosting on simple servers |
| 25 | + |
| 26 | +## Setup Steps |
| 27 | + |
| 28 | +### 1. Repository Settings |
| 29 | + |
| 30 | +1. Go to your repository → Settings → Pages |
| 31 | +2. Under "Source", select "GitHub Actions" |
| 32 | +3. Save the settings |
| 33 | + |
| 34 | +### 2. Workflow Files |
| 35 | + |
| 36 | +The workflow files are already created in `.github/workflows/`: |
| 37 | + |
| 38 | +- `deploy-pages.yml` - Standard deployment |
| 39 | +- `deploy-pages-standalone.yml` - Standalone deployment |
| 40 | + |
| 41 | +### 3. Branch Protection (Optional but Recommended) |
| 42 | + |
| 43 | +1. Go to Settings → Branches |
| 44 | +2. Add a branch protection rule for `main` |
| 45 | +3. Require status checks to pass before merging |
| 46 | +4. Include the "build-and-deploy" check |
| 47 | + |
| 48 | +## How It Works |
| 49 | + |
| 50 | +### Standard Deployment Workflow: |
| 51 | + |
| 52 | +1. Triggered when files in `website/` directory are pushed to `main` |
| 53 | +2. Sets up Node.js 22 |
| 54 | +3. Installs dependencies with `npm ci` |
| 55 | +4. Builds the website with `npm run build` |
| 56 | +5. Uploads the `dist` folder to GitHub Pages |
| 57 | +6. Deploys automatically |
| 58 | + |
| 59 | +### Standalone Deployment Workflow: |
| 60 | + |
| 61 | +1. Must be triggered manually from the Actions tab |
| 62 | +2. Builds using `npm run build:single` |
| 63 | +3. Creates a single `index.html` file with all assets inlined |
| 64 | +4. Deploys the standalone file |
| 65 | + |
| 66 | +## Manual Deployment |
| 67 | + |
| 68 | +To manually trigger a deployment: |
| 69 | + |
| 70 | +1. Go to Actions tab in your repository |
| 71 | +2. Select the workflow you want to run |
| 72 | +3. Click "Run workflow" |
| 73 | +4. Select the branch (usually `main`) |
| 74 | +5. Click "Run workflow" |
| 75 | + |
| 76 | +## Troubleshooting |
| 77 | + |
| 78 | +### Common Issues: |
| 79 | + |
| 80 | +1. **"Pages not enabled"**: Enable Pages in repository settings and set source to "GitHub Actions" |
| 81 | + |
| 82 | +2. **"Permission denied"**: Ensure the repository has the necessary permissions: |
| 83 | + |
| 84 | + - Go to Settings → Actions → General |
| 85 | + - Under "Workflow permissions", select "Read and write permissions" |
| 86 | + |
| 87 | +3. **"Build fails"**: Check the Actions tab for detailed error logs |
| 88 | + |
| 89 | + - Common causes: Missing dependencies, Node.js version mismatch |
| 90 | + |
| 91 | +4. **"404 after deployment"**: |
| 92 | + - Check if the base URL is correct in `vite.config.ts` |
| 93 | + - Ensure the `base: './'` setting is appropriate for your GitHub Pages URL |
| 94 | + |
| 95 | +### Build Configuration |
| 96 | + |
| 97 | +The website is configured with: |
| 98 | + |
| 99 | +- **Base URL**: `./` (relative paths for GitHub Pages compatibility) |
| 100 | +- **Output format**: IIFE (Immediately Invoked Function Expression) |
| 101 | +- **Asset naming**: Includes hash for cache busting |
| 102 | + |
| 103 | +## Environment Variables |
| 104 | + |
| 105 | +No special environment variables are needed for the basic setup. The workflows use: |
| 106 | + |
| 107 | +- `GITHUB_TOKEN`: Automatically provided by GitHub Actions |
| 108 | +- Node.js 22: Specified in the workflow |
| 109 | + |
| 110 | +## Custom Domain (Optional) |
| 111 | + |
| 112 | +To use a custom domain: |
| 113 | + |
| 114 | +1. Add a `CNAME` file to the `website/public/` directory |
| 115 | +2. Put your domain name in the file (e.g., `tritonparse.example.com`) |
| 116 | +3. Configure DNS settings with your domain provider |
| 117 | +4. Enable "Enforce HTTPS" in Pages settings |
| 118 | + |
| 119 | +## Monitoring |
| 120 | + |
| 121 | +- Check the Actions tab to monitor deployment status |
| 122 | +- GitHub Pages deployments are visible in the repository's Environments section |
| 123 | +- Each successful deployment will show the live URL |
| 124 | + |
| 125 | +## Local Testing |
| 126 | + |
| 127 | +Before deploying, test locally: |
| 128 | + |
| 129 | +```bash |
| 130 | +cd website |
| 131 | +npm install |
| 132 | +npm run build |
| 133 | +npm run preview |
| 134 | +``` |
| 135 | + |
| 136 | +For standalone version: |
| 137 | + |
| 138 | +```bash |
| 139 | +npm run build:single |
| 140 | +# Open dist/standalone.html in a browser |
| 141 | +``` |
0 commit comments