Deploy to Netlify with Decap CMS

Connect your GitHub repository to Netlify, enable Netlify Identity and Git Gateway, and set up a custom domain so Decap CMS works in production.

Deploy to Netlify with Decap CMS

Why Netlify for Decap CMS?

Decap CMS needs a backend to authenticate editors and commit content changes to your Git repository. Netlify provides three things that make this easy:

1. Static hosting — Netlify serves your built dist/ folder

2. Netlify Identity — user login and registration for your CMS editors

3. Git Gateway — a service that lets Decap CMS commit to your GitHub repo on behalf of authenticated users

This is the fastest path to a working Decap CMS in production.

Step 1: Connect GitHub Repo to Netlify

1. Go to app.netlify.com and sign in

2. Click Add new site → Import an existing project

3. Choose GitHub

4. Authorize Netlify to access your GitHub account

5. Select your Luax Pro repository

6. Configure the build settings:

SettingValue
Build commandchmod +x luax && ./luax build
Publish directorydist
Branch to deploymain

7. Click Deploy site

Netlify runs chmod +x luax && ./luax build, which makes the binary executable and builds the site. The output goes to dist/, which Netlify publishes.

Note: If the build fails with "cannot execute binary file", your local Luax binary was compiled for the wrong OS. Download the Linux binary from Gumroad or compile it on a Linux machine. Netlify runs Linux, so the binary must be Linux-compatible.

Step 2: Enable Netlify Identity

1. In your Netlify site dashboard, click Site configuration → Identity

2. Click Enable Identity

3. Under Registration preferences, choose Invite only (recommended for production)

4. Under Services → Git Gateway, click Enable Git Gateway

Git Gateway lets Decap CMS commit to your repo without exposing GitHub credentials to the browser.

Step 3: Update Decap CMS Config for Production

Open public/admin/config.yml. Change the backend from git-gateway to git-gateway (it is already correct), and remove local_backend: true for production:

backend:
  name: git-gateway
  branch: main
# local_backend: true   ← comment this out for production

When local_backend is enabled, Decap CMS ignores Git Gateway and tries to talk to localhost:8081. On a deployed site, that fails. You must disable it.

If you want to keep local editing for development, you can create two config files: config.yml for production and config-local.yml for local. Or simply toggle the line before deploying.

Step 4: Invite Editors

1. In Netlify dashboard, go to Identity → Invite users

2. Enter your editor's email address

3. They receive an email invitation

4. They click the link, set a password, and can log in at https://yoursite.netlify.app/admin/

Editors do not need GitHub accounts. They log in through Netlify Identity.

Step 5: Custom Domain

1. In Netlify dashboard, go to Domain management

2. Click Add custom domain

3. Enter your domain (e.g., luaxpro.axcora.com)

4. Netlify shows DNS records you need to add at your domain registrar

5. Add the records at your registrar (Cloudflare, Namecheap, GoDaddy, etc.)

6. Wait for DNS propagation (5 minutes to 24 hours)

7. Netlify automatically provisions a free SSL certificate

After the domain is active, update data/metadata.yaml:

url: https://luaxpro.axcora.com

Then update public/admin/config.yml:

site_url: https://luaxpro.axcora.com
display_url: https://luaxpro.axcora.com

Rebuild and redeploy for the changes to take effect.

Step 6: Test the CMS in Production

1. Go to https://yourdomain.com/admin/

2. You should see a login screen (Netlify Identity)

3. Log in with your invited email

4. Edit a page and click Publish

5. Wait 30 to 60 seconds for Netlify to rebuild

6. Refresh the live site to see the change

If the login screen shows "Git Gateway not found", check that Git Gateway is enabled in Netlify Identity settings.

How Changes Flow in Production

When an editor clicks Publish:

1. Decap CMS sends the change to Netlify's Git Gateway

2. Git Gateway commits the change to your GitHub repo

3. Netlify detects the new commit

4. Netlify runs chmod +x luax && ./luax build

5. Netlify publishes the new dist/ folder

6. The live site updates within 30 to 60 seconds

No manual rebuild needed. No server management. Fully automated.

Common Mistake: `local_backend: true` Left On

If you forget to remove local_backend: true, the production admin panel shows a blank screen or "Failed to connect to localhost". Always comment it out before deploying.

Common Mistake: Wrong Binary

If your build fails with "cannot execute binary file", your local luax binary was compiled for macOS or Windows. Netlify needs a Linux binary. Replace the binary in the repo with the Linux version from Gumroad, or compile it on Linux.

Next Step

Netlify is configured and Decap CMS works in production. The next guide covers deploying to Cloudflare Pages, Vercel, and static hosts without CMS.