docs_tfgrid_economics/docsarchive/ops/deployment.md

sidebar_position

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

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:

# 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:

   dig plan.threefold.pro
   

3. Try accessing from different network/device (might be local DNS cache)
4. Flush your local DNS cache:

   # 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:

# 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 - Test changes before deploying
• Content Updates - How to edit and add content