Skip to content

Commit 3df635f

Browse files
harshachharshach
committed
Add GitHub Pages deployment with custom domain support
 - Add GitHub Actions workflow for automated deployment - Configure custom domain (openmetadatastandards.org) - Add deployment documentation and setup checklist - Update README with deployment information
1 parent 2ae39bb commit 3df635f

File tree

6 files changed

+616
-0
lines changed

6 files changed

+616
-0
lines changed

‎.github/workflows/deploy-docs.yml‎

Lines changed: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,64 @@
1+
name: Deploy MkDocs to GitHub Pages
2+
3+
on:
4+
push:
5+
branches:
6+
- main
7+
workflow_dispatch:
8+
9+
permissions:
10+
contents: write
11+
pages: write
12+
id-token: write
13+
14+
concurrency:
15+
group: "pages"
16+
cancel-in-progress: false
17+
18+
jobs:
19+
build:
20+
runs-on: ubuntu-latest
21+
steps:
22+
- name: Checkout repository
23+
uses: actions/checkout@v4
24+
with:
25+
fetch-depth: 0
26+
27+
- name: Set up Python
28+
uses: actions/setup-python@v5
29+
with:
30+
python-version: '3.11'
31+
cache: 'pip'
32+
33+
- name: Install dependencies
34+
run: |
35+
pip install --upgrade pip
36+
pip install mkdocs-material
37+
pip install mkdocs-glightbox
38+
pip install mkdocs-minify-plugin
39+
pip install mkdocs-git-revision-date-localized-plugin
40+
41+
- name: Configure Git for gh-pages
42+
run: |
43+
git config user.name "github-actions[bot]"
44+
git config user.email "github-actions[bot]@users.noreply.github.com"
45+
46+
- name: Build and Deploy to GitHub Pages
47+
run: |
48+
mkdocs gh-deploy --force --clean --verbose
49+
50+
- name: Upload artifact
51+
uses: actions/upload-pages-artifact@v3
52+
with:
53+
path: './site'
54+
55+
deploy:
56+
needs: build
57+
runs-on: ubuntu-latest
58+
environment:
59+
name: github-pages
60+
url: ${{ steps.deployment.outputs.page_url }}
61+
steps:
62+
- name: Deploy to GitHub Pages
63+
id: deployment
64+
uses: actions/deploy-pages@v4

‎DEPLOYMENT.md‎

Lines changed: 263 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,263 @@
1+
# Deployment Guide
2+
3+
This guide explains how to deploy the OpenMetadata Standards documentation to GitHub Pages with custom domains.
4+
5+
## Automated Deployment
6+
7+
The documentation is automatically deployed to GitHub Pages whenever changes are pushed to the `main` branch.
8+
9+
### GitHub Actions Workflow
10+
11+
The deployment workflow (`.github/workflows/deploy-docs.yml`) performs the following:
12+
13+
1. **Triggers**: Runs on every push to `main` branch or manual workflow dispatch
14+
2. **Build**: Installs Python dependencies and builds the MkDocs site
15+
3. **Deploy**: Deploys the built site to the `gh-pages` branch
16+
4. **Publish**: GitHub Pages serves the content from the `gh-pages` branch
17+
18+
### Required GitHub Settings
19+
20+
#### 1. Enable GitHub Pages
21+
22+
1. Go to repository **Settings** → **Pages**
23+
2. Under **Source**, select: `Deploy from a branch`
24+
3. Under **Branch**, select: `gh-pages` branch and `/ (root)` folder
25+
4. Click **Save**
26+
27+
#### 2. Configure Custom Domain
28+
29+
1. In **Settings** → **Pages** → **Custom domain**
30+
2. Enter: `openmetadatastandards.org`
31+
3. Click **Save**
32+
4. Check **Enforce HTTPS** (after DNS propagation)
33+
34+
#### 3. Set Workflow Permissions
35+
36+
1. Go to **Settings** → **Actions** → **General**
37+
2. Under **Workflow permissions**, select: `Read and write permissions`
38+
3. Check: `Allow GitHub Actions to create and approve pull requests`
39+
4. Click **Save**
40+
41+
---
42+
43+
## Custom Domain Configuration
44+
45+
### Primary Domain: openmetadatastandards.org
46+
47+
#### DNS Configuration (at your domain registrar)
48+
49+
Add the following DNS records for **openmetadatastandards.org**:
50+
51+
```
52+
Type Name Value TTL
53+
A @ 185.199.108.153 3600
54+
A @ 185.199.109.153 3600
55+
A @ 185.199.110.153 3600
56+
A @ 185.199.111.153 3600
57+
AAAA @ 2606:50c0:8000::153 3600
58+
AAAA @ 2606:50c0:8001::153 3600
59+
AAAA @ 2606:50c0:8002::153 3600
60+
AAAA @ 2606:50c0:8003::153 3600
61+
CNAME www open-metadata.github.io. 3600
62+
```
63+
64+
### Additional Domains (Redirects)
65+
66+
For **openmetadatastandards.com** and **openmetadatastandard.com**, configure redirects to the primary domain.
67+
68+
#### Option 1: DNS-Level Redirect (Recommended)
69+
70+
Most domain registrars offer URL forwarding/redirect features:
71+
72+
1. **openmetadatastandards.com**:
73+
- Set up URL forwarding to `https://openmetadatastandards.org`
74+
- Enable "301 Permanent Redirect"
75+
- Enable "Forward with masking" if you want the URL to remain unchanged
76+
77+
2. **openmetadatastandard.com** (singular):
78+
- Set up URL forwarding to `https://openmetadatastandards.org`
79+
- Enable "301 Permanent Redirect"
80+
81+
#### Option 2: DNS Records + GitHub Pages (Alternative)
82+
83+
If your registrar doesn't support redirects, you can point all domains to GitHub Pages:
84+
85+
**For openmetadatastandards.com**:
86+
```
87+
Type Name Value TTL
88+
A @ 185.199.108.153 3600
89+
A @ 185.199.109.153 3600
90+
A @ 185.199.110.153 3600
91+
A @ 185.199.111.153 3600
92+
CNAME www open-metadata.github.io. 3600
93+
```
94+
95+
**For openmetadatastandard.com**:
96+
```
97+
Type Name Value TTL
98+
A @ 185.199.108.153 3600
99+
A @ 185.199.109.153 3600
100+
A @ 185.199.110.153 3600
101+
A @ 185.199.111.153 3600
102+
CNAME www open-metadata.github.io. 3600
103+
```
104+
105+
Then add all domains in GitHub Pages settings (only one primary domain is supported, but GitHub will serve content on all configured domains).
106+
107+
---
108+
109+
## DNS Propagation
110+
111+
After configuring DNS records:
112+
113+
1. **Wait**: DNS changes can take 24-48 hours to propagate globally
114+
2. **Check**: Use [DNS Checker](https://dnschecker.org/) to verify propagation
115+
3. **Verify**: Visit your domain to ensure it loads the documentation
116+
4. **Enable HTTPS**: Return to GitHub Pages settings and enable "Enforce HTTPS"
117+
118+
---
119+
120+
## Local Testing
121+
122+
Test the documentation locally before pushing:
123+
124+
```bash
125+
# Install dependencies
126+
pip install mkdocs-material mkdocs-glightbox mkdocs-minify-plugin mkdocs-git-revision-date-localized-plugin
127+
128+
# Serve locally
129+
mkdocs serve
130+
131+
# Build locally
132+
mkdocs build
133+
134+
# Test the built site
135+
cd site && python -m http.server 8000
136+
```
137+
138+
---
139+
140+
## Deployment Workflow
141+
142+
### Automatic Deployment
143+
144+
1. Make changes to documentation files in `docs/`
145+
2. Commit and push to `main` branch:
146+
```bash
147+
git add .
148+
git commit -m "Update documentation"
149+
git push origin main
150+
```
151+
3. GitHub Actions automatically builds and deploys to GitHub Pages
152+
4. Changes are live at your custom domain within 1-2 minutes
153+
154+
### Manual Deployment
155+
156+
Trigger deployment manually from GitHub:
157+
158+
1. Go to **Actions** tab
159+
2. Select **Deploy MkDocs to GitHub Pages** workflow
160+
3. Click **Run workflow** → **Run workflow**
161+
162+
### Local Deployment (if needed)
163+
164+
```bash
165+
# Deploy directly from local machine (requires write access)
166+
mkdocs gh-deploy --force --clean
167+
```
168+
169+
---
170+
171+
## Monitoring
172+
173+
### Check Deployment Status
174+
175+
1. Go to **Actions** tab to see workflow runs
176+
2. Each push triggers a new deployment
177+
3. Green checkmark = successful deployment
178+
4. Red X = deployment failed (check logs)
179+
180+
### View Deployment Logs
181+
182+
1. Click on a workflow run
183+
2. Expand the job steps to see detailed logs
184+
3. Look for errors in the "Build and Deploy" step
185+
186+
---
187+
188+
## Troubleshooting
189+
190+
### Deployment Fails
191+
192+
**Error**: `Permission denied`
193+
- **Fix**: Enable write permissions in Settings → Actions → General → Workflow permissions
194+
195+
**Error**: `Module not found`
196+
- **Fix**: Add missing Python package to workflow's `pip install` step
197+
198+
### Custom Domain Not Working
199+
200+
**Error**: `DNS_PROBE_FINISHED_NXDOMAIN`
201+
- **Fix**: Wait for DNS propagation (24-48 hours)
202+
- **Check**: Verify DNS records at your registrar
203+
204+
**Error**: `Not Secure` / `SSL Certificate Invalid`
205+
- **Fix**: Wait for GitHub to provision SSL certificate (can take up to 24 hours after DNS propagation)
206+
- **Check**: Ensure "Enforce HTTPS" is enabled in GitHub Pages settings
207+
208+
### Site Not Updating
209+
210+
**Cause**: Browser cache
211+
- **Fix**: Hard refresh (Ctrl+Shift+R / Cmd+Shift+R)
212+
- **Clear**: Browser cache for your domain
213+
214+
**Cause**: CDN cache
215+
- **Fix**: Wait 5-10 minutes for GitHub's CDN to update
216+
- **Force**: Push another commit to trigger rebuild
217+
218+
---
219+
220+
## Repository Structure
221+
222+
```
223+
OpenMetadataStandards/
224+
├── .github/
225+
│ └── workflows/
226+
│ └── deploy-docs.yml # GitHub Actions workflow
227+
├── docs/
228+
│ ├── CNAME # Custom domain configuration
229+
│ ├── index.md # Homepage
230+
│ ├── assets/ # Images, logos, etc.
231+
│ ├── stylesheets/ # Custom CSS
232+
│ └── ... # Documentation pages
233+
├── mkdocs.yml # MkDocs configuration
234+
├── DEPLOYMENT.md # This file
235+
└── README.md # Project README
236+
```
237+
238+
---
239+
240+
## Security
241+
242+
### HTTPS
243+
244+
- GitHub Pages automatically provisions SSL certificates for custom domains
245+
- Always enable "Enforce HTTPS" in repository settings
246+
- All traffic is encrypted with TLS 1.2+
247+
248+
### Branch Protection
249+
250+
Consider enabling branch protection for `main`:
251+
252+
1. Go to **Settings** → **Branches**
253+
2. Add rule for `main` branch
254+
3. Enable: "Require status checks to pass before merging"
255+
4. Enable: "Require branches to be up to date before merging"
256+
257+
---
258+
259+
## Contact & Support
260+
261+
- **Issues**: Report problems at [GitHub Issues](https://github.com/open-metadata/OpenMetadataStandards/issues)
262+
- **Community**: Join [OpenMetadata Slack](https://slack.open-metadata.org)
263+
- **Documentation**: [MkDocs Material](https://squidfunk.github.io/mkdocs-material/)

‎README.md‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,7 @@
22

33
> Comprehensive schemas, ontologies, and specifications for metadata management
44
5+
[![Deploy Docs](https://github.com/open-metadata/OpenMetadataStandards/actions/workflows/deploy-docs.yml/badge.svg)](https://github.com/open-metadata/OpenMetadataStandards/actions/workflows/deploy-docs.yml)
56
[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
67
[![Documentation](https://img.shields.io/badge/docs-latest-brightgreen.svg)](https://openmetadatastandards.org)
78
[![Community](https://img.shields.io/badge/slack-join-orange.svg)](https://slack.open-metadata.org)
@@ -162,6 +163,21 @@ Full documentation available at [openmetadatastandards.org](https://openmetadata
162163
- [RDF & Ontologies](https://openmetadatastandards.org/rdf/overview/)
163164
- [Examples](https://openmetadatastandards.org/examples/)
164165

166+
## Deployment
167+
168+
This documentation is automatically deployed to GitHub Pages using GitHub Actions:
169+
170+
- **Live Site**: [openmetadatastandards.org](https://openmetadatastandards.org)
171+
- **Trigger**: Every push to `main` branch
172+
- **Workflow**: `.github/workflows/deploy-docs.yml`
173+
- **Deployment Guide**: See [DEPLOYMENT.md](DEPLOYMENT.md) for detailed instructions
174+
175+
### Custom Domains
176+
177+
The documentation is accessible via:
178+
- **Primary**: openmetadatastandards.org
179+
- **Redirects**: openmetadatastandards.com, openmetadatastandard.com
180+
165181
## Contributing
166182

167183
We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for details.

0 commit comments

Comments
 (0)