Table of Contents
- Why Netlify for Decap CMS?
- Step 1: Connect GitHub Repo to Netlify
- Step 2: Enable Netlify Identity
- Step 3: Update Decap CMS Config for Production
- Step 4: Invite Editors
- Step 5: Custom Domain
- Step 6: Test the CMS in Production
- How Changes Flow in Production
- Common Mistake: `local_backend: true` Left On
- Common Mistake: Wrong Binary
- Next Step
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:
| Setting | Value |
|---|---|
| Build command | chmod +x luax && ./luax build |
| Publish directory | dist |
| Branch to deploy | main |
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.