Decap CMS — Local Setup

Decap CMS — Local Setup

This guide is for the Code + Decap CMS package. If you bought the Code Only package, you can skip this section.

Decap CMS (formerly Netlify CMS) is a Git-based content management system. It gives you a browser admin panel to edit all your content — landing page, docs, blog, and static pages — without touching code.

In this guide, you’ll set up Decap CMS to run on your local machine. After that, you’ll deploy it to Netlify so you can use it from anywhere.

What Is Decap CMS?

Decap CMS is a static CMS. That means:

• Content is stored in your Git repository as Markdown and JSON files
• Editing happens in a browser admin panel
• Changes are committed to Git automatically
• No database, no server runtime

When you edit content in Decap CMS, it commits the change to your Git repo. Your hosting provider then rebuilds the site automatically.

How It Works

You edit in browser → Decap CMS commits to GitHub → Netlify rebuilds site → Changes go live

There’s no database. No admin server. Just Git.

Before You Start

Make sure you have:

• The Code + Decap CMS package installed and running locally
• A GitHub account
• Your project folder open in a terminal

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

→ Push to GitHub

Step 1 — Check the CMS Configuration

Decap CMS configuration lives in public/admin/config.yml. Open it and verify the backend section:

backend:
  name: git-gateway
  branch: main

For local development, change it to:

backend:
  name: git-gateway
  branch: main

local_backend: true

For production, you’ll remove local_backend: true later. For now, keep it — it lets you test the CMS locally without deploying.

Step 2 — Install the Local Backend Proxy

Decap CMS needs a local proxy to talk to your Git repository during development. Install it:

npm install --save-dev decap-server

Then add a script to package.json to run it:

{
  "scripts": {
    "dev": "astro dev",
    "build": "astro build",
    "preview": "astro preview",
    "cms": "decap-server"
  }
}

Step 3 — Run Decap CMS Locally

Open two terminal windows in your project folder.

Terminal 1 — Run the Astro dev server:

npm run dev

Terminal 2 — Run the Decap CMS proxy:

npm run cms

You’ll see output like:

Decap CMS Proxy Server listening on port 8081

Step 4 — Open the Admin Panel

Open your browser and go to:

http://localhost:4321/admin/

You should see the Decap CMS login screen. Since local_backend: true is set, you’ll log in without credentials — the local proxy handles authentication.

Step 5 — Explore the CMS

Once logged in, you’ll see collections:

• Pages — static pages (About, FAQ, Terms, Privacy)
• Blog — blog posts
• Docs — documentation
• Home — landing page content
• Site Config — site metadata, navigation, footer

Click any collection to see the entries. Click an entry to edit it.

Step 6 — Edit Content

Try editing a blog post:

1. Click Blog in the sidebar
2. Click any post
3. Change the title or description
4. Click Save (top right)
5. Click Publish → Publish now

Decap CMS commits the change to your Git repository. The Astro dev server picks up the change and reloads the page.

Step 7 — Media Uploads

Decap CMS stores uploaded media in public/uploads/. The configuration is:

media_folder: "public/uploads"
public_folder: "/uploads"

When you upload an image in the CMS, it goes to public/uploads/ and is referenced as /uploads/filename.jpg.

Collections Reference

Here’s what each collection controls:

Pages Collection

Folder: src/content/pages/

Fields:

• title — Page title
• description — SEO description
• image — Hero image
• layoutType — Layout style (default, faq, legal, contact)
• showInNav — Show in navigation
• navOrder — Navigation order
• body — Page content

Blog Collection

Folder: src/content/blog/

Fields:

• title — Post title
• description — SEO description
• date — Publish date
• tags — Tags (array)
• image — Featured image
• body — Post content

Docs Collection

Folder: src/content/docs/

Fields:

• title — Doc title
• description — Doc description
• body — Doc content

Home Collection

File: src/data/home.json

Fields:

• Hero section (badge, title, description, actions)
• Features section
• Pricing section
• CTA section

Site Config Collection

Files:

• src/data/seo.json
• src/data/site.json
• src/data/navbar.json
• src/data/footer.json

Common Issues

CMS shows “Not Found”

Make sure you’re accessing /admin/ (with trailing slash). Also verify that public/admin/index.html and public/admin/config.yml exist.

Login screen loops

Check that local_backend: true is in config.yml and that the Decap proxy is running (npm run cms).

Changes don’t appear

Decap CMS commits to Git, but the Astro dev server may need a moment to pick up the change. Wait a few seconds and refresh.

Uploaded images don’t show

Verify the media folder exists: public/uploads/. If it doesn’t, create it.

What’s Next

Now that Decap CMS works locally, you can:

• Edit all your content from the browser
• Preview changes before publishing
• Deploy to Netlify to use the CMS from anywhere

→ Decap CMS — Update Content

→ Deploy to Netlify

Need Help?

If you’re stuck:

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