Skip to main content

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.

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

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:

TimeEvent
T+0sPush commit to main branch
T+10sGitHub Actions workflow starts
T+2minBuild completes, deploys to gh-pages branch
T+3minGitHub Pages processes update
T+5minSite live at plan.threefold.pro
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​