Skip to content

Commit 5896364

Browse files
FindHaofacebook-github-bot
authored andcommitted
Add GitHub Pages setup documentation and deployment workflows (#4)
Summary: Introduce a comprehensive guide for setting up automatic deployment to GitHub Pages for the TritonParse website, including two workflow options: standard and standalone deployment. The workflows are configured to handle deployments based on repository events and manual triggers. Pull Request resolved: #4 Reviewed By: davidberard98 Differential Revision: D75818950 Pulled By: FindHao fbshipit-source-id: a0fc523782ba1a4296550852a0f1412c3b0c2dd1
1 parent 28d87ec commit 5896364

File tree

3 files changed

+262
-0
lines changed

3 files changed

+262
-0
lines changed

.github/PAGES_SETUP.md

Lines changed: 141 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,141 @@
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+
```
Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
name: Deploy Standalone to GitHub Pages
2+
3+
on:
4+
# This workflow can be manually triggered
5+
workflow_dispatch:
6+
7+
# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
8+
permissions:
9+
contents: read
10+
pages: write
11+
id-token: write
12+
13+
# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
14+
concurrency:
15+
group: "pages-standalone"
16+
cancel-in-progress: false
17+
18+
jobs:
19+
build-and-deploy-standalone:
20+
environment:
21+
name: github-pages
22+
url: ${{ steps.deployment.outputs.page_url }}
23+
runs-on: ubuntu-latest
24+
25+
steps:
26+
- name: Checkout repository
27+
uses: actions/checkout@v4
28+
29+
- name: Setup Node.js
30+
uses: actions/setup-node@v4
31+
with:
32+
node-version: "22"
33+
cache: "npm"
34+
cache-dependency-path: "website/package-lock.json"
35+
36+
- name: Install dependencies
37+
working-directory: ./website
38+
run: npm ci
39+
40+
- name: Build standalone website
41+
working-directory: ./website
42+
run: npm run build:single
43+
44+
- name: Prepare standalone deployment
45+
run: |
46+
mkdir -p standalone-deploy
47+
cp website/dist/standalone.html standalone-deploy/index.html
48+
49+
- name: Setup Pages
50+
uses: actions/configure-pages@v4
51+
52+
- name: Upload artifact
53+
uses: actions/upload-pages-artifact@v3
54+
with:
55+
path: "./standalone-deploy"
56+
57+
- name: Deploy to GitHub Pages
58+
id: deployment
59+
uses: actions/deploy-pages@v4

.github/workflows/deploy-pages.yml

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,62 @@
1+
name: Deploy to GitHub Pages
2+
3+
on:
4+
# Trigger on push to main branch
5+
push:
6+
branches: [main]
7+
paths:
8+
- "website/**"
9+
- ".github/workflows/deploy-pages.yml"
10+
11+
# Allow manual trigger
12+
workflow_dispatch:
13+
14+
# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
15+
permissions:
16+
contents: read
17+
pages: write
18+
id-token: write
19+
20+
# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
21+
# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
22+
concurrency:
23+
group: "pages"
24+
cancel-in-progress: false
25+
26+
jobs:
27+
build-and-deploy:
28+
environment:
29+
name: github-pages
30+
url: ${{ steps.deployment.outputs.page_url }}
31+
runs-on: ubuntu-latest
32+
33+
steps:
34+
- name: Checkout repository
35+
uses: actions/checkout@v4
36+
37+
- name: Setup Node.js
38+
uses: actions/setup-node@v4
39+
with:
40+
node-version: "22"
41+
cache: "npm"
42+
cache-dependency-path: "website/package-lock.json"
43+
44+
- name: Install dependencies
45+
working-directory: ./website
46+
run: npm ci
47+
48+
- name: Build website
49+
working-directory: ./website
50+
run: npm run build
51+
52+
- name: Setup Pages
53+
uses: actions/configure-pages@v4
54+
55+
- name: Upload artifact
56+
uses: actions/upload-pages-artifact@v3
57+
with:
58+
path: "./website/dist"
59+
60+
- name: Deploy to GitHub Pages
61+
id: deployment
62+
uses: actions/deploy-pages@v4

0 commit comments

Comments
 (0)