This commit is contained in:
298
docsarchive/ops/deployment.md
Normal file
298
docsarchive/ops/deployment.md
Normal file
@@ -0,0 +1,298 @@
|
||||
---
|
||||
sidebar_position: 1
|
||||
---
|
||||
|
||||
# Deployment to plan.threefold.pro
|
||||
|
||||
This guide covers how to deploy the TFT Minting Transition Plan site to the custom domain `plan.threefold.pro` using GitHub Pages.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- GitHub repository: `https://github.com/mik-tf/minting_plan`
|
||||
- Access to DNS provider for `threefold.pro` domain
|
||||
- GitHub Pages enabled on the repository
|
||||
- Node.js 18+ installed locally (for testing before deployment)
|
||||
|
||||
---
|
||||
|
||||
## DNS Configuration
|
||||
|
||||
Configure your DNS settings at your domain provider to point `plan.threefold.pro` to GitHub Pages.
|
||||
|
||||
### Option 1: CNAME Record (Recommended)
|
||||
|
||||
Add the following DNS record:
|
||||
|
||||
```
|
||||
Type: CNAME
|
||||
Name: plan
|
||||
Value: mik-tf.github.io
|
||||
TTL: 3600 (or your provider's default)
|
||||
```
|
||||
|
||||
### Option 2: A Records (Alternative)
|
||||
|
||||
If your DNS provider doesn't support CNAME for subdomains, use A records:
|
||||
|
||||
```
|
||||
Type: A
|
||||
Name: plan
|
||||
Value: 185.199.108.153
|
||||
TTL: 3600
|
||||
|
||||
Type: A
|
||||
Name: plan
|
||||
Value: 185.199.109.153
|
||||
TTL: 3600
|
||||
|
||||
Type: A
|
||||
Name: plan
|
||||
Value: 185.199.110.153
|
||||
TTL: 3600
|
||||
|
||||
Type: A
|
||||
Name: plan
|
||||
Value: 185.199.111.153
|
||||
TTL: 3600
|
||||
```
|
||||
|
||||
:::tip DNS Propagation
|
||||
DNS changes can take anywhere from 5 minutes to 48 hours to propagate globally. Typically it's 15-30 minutes.
|
||||
:::
|
||||
|
||||
---
|
||||
|
||||
## GitHub Repository Settings
|
||||
|
||||
### 1. Enable GitHub Pages
|
||||
|
||||
1. Go to your repository: `https://github.com/mik-tf/minting_plan`
|
||||
2. Click **Settings** → **Pages** (left sidebar)
|
||||
3. Under "Source", select:
|
||||
- **Branch**: `gh-pages`
|
||||
- **Folder**: `/ (root)`
|
||||
4. Click **Save**
|
||||
|
||||
### 2. Configure Custom Domain
|
||||
|
||||
1. Still in the Pages settings
|
||||
2. Under "Custom domain", enter: `plan.threefold.pro`
|
||||
3. Click **Save**
|
||||
4. Wait for DNS check (green checkmark ✓ will appear)
|
||||
5. Once verified, check **Enforce HTTPS** (automatic SSL certificate)
|
||||
|
||||
:::warning Important
|
||||
The CNAME file in the `static/` folder ensures the custom domain persists after each deployment. Don't delete it!
|
||||
:::
|
||||
|
||||
---
|
||||
|
||||
## GitHub Actions Workflow
|
||||
|
||||
The repository includes an automated deployment workflow at `.github/workflows/deploy.yml`. This workflow:
|
||||
|
||||
- Triggers automatically on push to `main` branch
|
||||
- Installs dependencies
|
||||
- Builds the Docusaurus site
|
||||
- Deploys to `gh-pages` branch
|
||||
|
||||
### How It Works
|
||||
|
||||
```yaml
|
||||
name: Deploy to GitHub Pages
|
||||
|
||||
on:
|
||||
push:
|
||||
branches:
|
||||
- main
|
||||
|
||||
jobs:
|
||||
deploy:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
- uses: actions/setup-node@v4
|
||||
with:
|
||||
node-version: 18
|
||||
cache: npm
|
||||
- name: Install dependencies
|
||||
run: npm ci
|
||||
- name: Build website
|
||||
run: npm run build
|
||||
- name: Deploy to GitHub Pages
|
||||
uses: peaceiris/actions-gh-pages@v3
|
||||
with:
|
||||
github_token: ${{ secrets.GITHUB_TOKEN }}
|
||||
publish_dir: ./build
|
||||
```
|
||||
|
||||
### Manual Deployment (if needed)
|
||||
|
||||
If you need to deploy manually:
|
||||
|
||||
```bash
|
||||
# Build the site
|
||||
npm run build
|
||||
|
||||
# Deploy to GitHub Pages
|
||||
npm run deploy
|
||||
```
|
||||
|
||||
:::info Automatic Deployment
|
||||
With GitHub Actions, you don't need to manually deploy. Just push to `main` and the site updates automatically in 2-3 minutes.
|
||||
:::
|
||||
|
||||
---
|
||||
|
||||
## Verification Steps
|
||||
|
||||
After deployment, verify everything works:
|
||||
|
||||
### 1. Check GitHub Actions
|
||||
|
||||
1. Go to repository → **Actions** tab
|
||||
2. Verify the latest workflow run succeeded (green checkmark)
|
||||
3. If failed, click to see error logs
|
||||
|
||||
### 2. Check GitHub Pages Status
|
||||
|
||||
1. Go to repository → **Settings** → **Pages**
|
||||
2. You should see: "Your site is live at https://plan.threefold.pro"
|
||||
3. Green checkmark next to custom domain
|
||||
|
||||
### 3. Test the Website
|
||||
|
||||
Visit these URLs and verify they work:
|
||||
|
||||
- https://plan.threefold.pro (homepage/intro)
|
||||
- https://plan.threefold.pro/core-concepts/token-system
|
||||
- https://plan.threefold.pro/ops/deployment (this page!)
|
||||
|
||||
### 4. Verify SSL Certificate
|
||||
|
||||
- Ensure the site loads with `https://` (not `http://`)
|
||||
- Check browser shows padlock icon (secure connection)
|
||||
- Certificate should be issued by GitHub
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### DNS Not Resolving
|
||||
|
||||
**Symptoms**: Site doesn't load, "DNS_PROBE_FINISHED_NXDOMAIN" error
|
||||
|
||||
**Solutions**:
|
||||
1. Wait longer for DNS propagation (up to 48 hours)
|
||||
2. Check DNS records are correct using:
|
||||
```bash
|
||||
dig plan.threefold.pro
|
||||
```
|
||||
3. Try accessing from different network/device (might be local DNS cache)
|
||||
4. Flush your local DNS cache:
|
||||
```bash
|
||||
# Linux
|
||||
sudo systemd-resolve --flush-caches
|
||||
|
||||
# macOS
|
||||
sudo dscacheutil -flushcache
|
||||
```
|
||||
|
||||
### 404 Errors
|
||||
|
||||
**Symptoms**: Homepage loads but inner pages show 404
|
||||
|
||||
**Solutions**:
|
||||
1. Verify `trailingSlash: false` in `docusaurus.config.js`
|
||||
2. Check GitHub Pages is deploying from `gh-pages` branch root
|
||||
3. Wait a few minutes after deployment completes
|
||||
|
||||
### Build Failures
|
||||
|
||||
**Symptoms**: GitHub Actions workflow fails
|
||||
|
||||
**Solutions**:
|
||||
1. Check Actions tab for error logs
|
||||
2. Verify `package.json` has correct dependencies
|
||||
3. Test build locally: `npm run build`
|
||||
4. Check for broken links in markdown files
|
||||
|
||||
### Custom Domain Not Persisting
|
||||
|
||||
**Symptoms**: Custom domain resets after deployment
|
||||
|
||||
**Solutions**:
|
||||
1. Ensure `static/CNAME` file exists with content: `plan.threefold.pro`
|
||||
2. The CNAME file should be committed to git
|
||||
3. After build, verify `build/CNAME` exists
|
||||
|
||||
---
|
||||
|
||||
## Deployment Timeline
|
||||
|
||||
Understanding what happens when you push changes:
|
||||
|
||||
| Time | Event |
|
||||
|------|-------|
|
||||
| T+0s | Push commit to `main` branch |
|
||||
| T+10s | GitHub Actions workflow starts |
|
||||
| T+2min | Build completes, deploys to `gh-pages` branch |
|
||||
| T+3min | GitHub Pages processes update |
|
||||
| T+5min | Site live at plan.threefold.pro |
|
||||
|
||||
:::tip Quick Updates
|
||||
For urgent fixes, monitor the Actions tab to see when deployment completes, then verify changes immediately.
|
||||
:::
|
||||
|
||||
---
|
||||
|
||||
## Security Considerations
|
||||
|
||||
### HTTPS/SSL
|
||||
- GitHub Pages provides automatic SSL via Let's Encrypt
|
||||
- Certificate renews automatically
|
||||
- Always enforce HTTPS in settings
|
||||
|
||||
### Branch Protection
|
||||
Consider protecting the `main` branch:
|
||||
1. Settings → Branches → Add rule
|
||||
2. Require pull request reviews
|
||||
3. Require status checks to pass
|
||||
|
||||
### Access Control
|
||||
- Only repository collaborators can push to `main`
|
||||
- Manage access in Settings → Collaborators
|
||||
|
||||
---
|
||||
|
||||
## Maintenance
|
||||
|
||||
### Regular Updates
|
||||
|
||||
Keep Docusaurus and dependencies updated:
|
||||
|
||||
```bash
|
||||
# Check for updates
|
||||
npm outdated
|
||||
|
||||
# Update dependencies
|
||||
npm update
|
||||
|
||||
# Update Docusaurus to latest
|
||||
npm install @docusaurus/core@latest @docusaurus/preset-classic@latest
|
||||
```
|
||||
|
||||
### Monitoring
|
||||
|
||||
Monitor these regularly:
|
||||
- GitHub Actions workflow status
|
||||
- Site accessibility at plan.threefold.pro
|
||||
- SSL certificate validity (automatic but good to check)
|
||||
- Build times (should stay under 3 minutes)
|
||||
|
||||
---
|
||||
|
||||
## Next Steps
|
||||
|
||||
- [Local Development](./local-development.md) - Test changes before deploying
|
||||
- [Content Updates](./content-updates.md) - How to edit and add content
|
||||
Reference in New Issue
Block a user