Deploy to Netlify

Deploy to Netlify

Netlify is the recommended hosting for ForgeDocs. It’s free for personal projects, connects directly to GitHub, and includes Identity — which Decap CMS needs.

This guide walks you through the full deployment:

1. Connect your GitHub repo to Netlify
2. Configure the build settings
3. Enable Netlify Identity (for Decap CMS)
4. Enable Git Gateway
5. Invite yourself as an admin
6. Access the CMS

By the end, your site will be live on a Netlify subdomain. You can connect your own domain later.

What You Need

• A GitHub account with your ForgeDocs project pushed
• A Netlify account — sign up here (free)

If you haven’t pushed to GitHub yet, do that first:

→ Push to GitHub

Step 1 — Sign Up for Netlify

1. Go to app.netlify.com/signup
2. Click Sign up with GitHub
3. Authorize Netlify to access your GitHub account

Using GitHub sign-in makes the next step easier.

Step 2 — Add a New Site

1. From the Netlify dashboard, click Add new site → Import an existing project
2. Click Deploy with GitHub
3. If prompted, authorize Netlify to access your repositories
4. Search for your forgedocs repository
5. Click on it to select

Step 3 — Configure Build Settings

Netlify auto-detects Astro projects. Verify the settings:

Setting	Value
Branch to deploy	main
Build command	npm run build
Publish directory	dist

If Netlify doesn’t auto-detect, set these manually.

Optional — Environment variables:

If your project uses any environment variables (API keys, etc.), add them here. ForgeDocs doesn’t require any by default.

Step 4 — Deploy the Site

Click Deploy site.

Netlify starts building your site. This takes 1–3 minutes the first time.

You’ll see a build log. When it completes, you’ll see:

✓ Site is live

Netlify assigns a random subdomain like https://sparkly-cat-12345.netlify.app.

Step 5 — Rename the Site (Optional)

To change the subdomain:

1. Go to Site configuration → Site details
2. Click Change site name
3. Enter your preferred name (e.g., forgedocs-demo)
4. Click Save

Your site is now at https://your-name.netlify.app.

Step 6 — Enable Netlify Identity

Netlify Identity is required for Decap CMS. It handles user authentication.

1. From your site dashboard, click Identity in the top navigation
2. Click Enable Identity

Once enabled, you’ll see the Identity dashboard.

Step 7 — Configure Identity Settings

1. Click Identity → Settings and usage
2. Under Registration preferences, choose:
   • Invite only (recommended) — only invited users can sign up
   • Open — anyone can sign up
3. Under External providers, you can add Google, GitHub, or other providers (optional)
4. Under Services → Git Gateway, click Enable Git Gateway

Git Gateway is what lets Decap CMS commit to your GitHub repository without requiring users to have GitHub accounts.

Step 8 — Invite Yourself as Admin

1. Click Identity → Invite users
2. Enter your email address
3. Click Send

You’ll receive an email from Netlify with an invite link.

4. Click the link in the email
5. Set a password
6. You’re now a Netlify Identity user

Step 9 — Access the CMS

Open your browser and go to:

https://your-site.netlify.app/admin/

You should see the Decap CMS login screen.

1. Click Login with Netlify Identity
2. Enter the email and password you set in Step 8
3. You’re in

You can now edit all content from the browser. Every change commits to GitHub, and Netlify rebuilds the site automatically.

Step 10 — Connect a Custom Domain (Optional)

If you have your own domain:

1. Go to Site configuration → Domain management
2. Click Add a domain
3. Enter your domain (e.g., your-domain.com)
4. Click Verify → Add domain
5. Follow Netlify’s instructions to update your domain’s DNS records

Netlify provides free SSL (HTTPS) automatically.

DNS setup:

If your domain is registered elsewhere (Namecheap, GoDaddy, Cloudflare), you’ll need to:

• Either change your nameservers to Netlify’s
• Or add a CNAME record pointing to your Netlify subdomain

Netlify walks you through both options.

How Updates Work

After deployment, every push to GitHub triggers a rebuild:

You edit content → Decap CMS commits to GitHub → Netlify rebuilds → Changes go live

Rebuilds take 1–2 minutes. You can watch the progress in the Netlify dashboard under Deploys.

Managing Users

To add more CMS users:

1. Go to Identity → Invite users
2. Enter their email
3. Click Send

They’ll receive an invite and can log in at /admin/.

To remove a user:

1. Go to Identity
2. Click the user
3. Click Delete user

Common Issues

Build fails on Netlify

Check the build log for the error. Common causes:

• Missing dependency — verify package.json includes all dependencies
• Node.js version mismatch — set NODE_VERSION in environment variables to 18 or 20
• Build works locally but not on Netlify — check for case-sensitive file paths

CMS shows “Not Found”

Verify that:

• /admin/ exists (with trailing slash)
• public/admin/index.html and public/admin/config.yml are in your repo
• backend: name: git-gateway is set in config.yml

Identity invite email doesn’t arrive

Check your spam folder. If it’s still missing, go to Identity and click Resend invite.

“Git Gateway” is not an option

Git Gateway is only available when Identity is enabled. Go back to Step 6.

Changes committed but site doesn’t update

Check the Deploys tab. If a build is in progress, wait. If the build failed, check the log.

Site shows “Page not found”

Check the Publish directory setting. It should be dist, not public.

Build Settings Reference

Setting	Value
Build command	npm run build
Publish directory	dist
Node version	18 or 20
Branch	main

What’s Next

Your site is live. You can now:

• Edit content via /admin/
• Add a custom domain in Netlify settings
• Invite collaborators via Identity
• Monitor builds in the Deploys tab

If you want to deploy to a different host:

→ Deploy to Others

Need Help?

If you’re stuck:

• Check the FAQ
• Email creativebydre@gmail.com
• For custom work, hire me on Fiverr