docs_tfgrid_economics/docsarchive/ops/deployment.md

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