Running Decap CMS Locally

Decap CMS is a headless content management system that lets you edit your website content without touching code. This guide will show you how to run it on your computer.

What Is Decap CMS

Decap CMS (formerly Netlify CMS) is an open-source CMS that works with Git-based websites. It provides a visual admin panel where you can:

• Edit text content
• Upload images
• Create new cars or blog posts
• Manage navigation menus
• Update site settings

All changes are saved directly to your content files. No database required.

Why Two Terminals

You need two terminal windows running at the same time:

• Terminal 1 — Runs the Gatsby server (your website preview)
• Terminal 2 — Runs the Decap CMS proxy server (the admin panel authentication)

They work together but run as separate processes. If you close one, the other will not work properly.

Important: Development vs Production Mode

There is a critical difference between gatsby develop and gatsby serve when accessing the CMS admin panel:

This means: To use Decap CMS locally, you must run gatsby build and gatsby serve, not gatsby develop.

This is a known behavior of Gatsby. It is not a bug in GatsbyCar.

Prerequisites

Before starting, make sure:

• Node.js is installed (from Documentation 2)
• Dependencies are installed (npm install already run)
• The project folder is open in VS Code

Step 1: Open Two Terminals in VS Code

1. Open VS Code with your GatsbyCar project folder
2. Click Terminal in the top menu
3. Click New Terminal
4. A terminal panel opens at the bottom
5. Click the + icon in the terminal panel to create a second terminal

You will now see two terminal tabs:

• bash (or powershell) — Terminal 1
• bash (or powershell) — Terminal 2

Click each tab to switch between them.

Step 2: Build the Site in Terminal 1

Click on Terminal 1 (the first tab).

Type:

npm run build

Press Enter. Wait until you see:

success Building static HTML for pages - 4.746s - 91/91 19.17/s
info Done building in 40.459890932 sec

This creates the public/ folder with all your production files, including admin/index.html.

Step 3: Serve the Site in Terminal 1

After the build completes, type:

npm run serve

Press Enter. Wait until you see:

You can now view gatsbycar in the browser.

  http://localhost:9000/

Note: The URL is localhost:9000, not localhost:8000. The serve command uses a different port.

Leave this terminal running. Do not close it.

Step 4: Start Decap CMS Proxy in Terminal 2

Click on Terminal 2 (the second tab).

Type:

npx decap-server

Press Enter. Wait until you see:

Decap CMS Proxy Server listening on port 8081

Leave this terminal running too. Do not close it.

Step 5: Access the Admin Panel

Open your browser and go to:

http://localhost:9000/admin/

Important: Use localhost:9000, not localhost:8000. The /admin/ path only works on the serve port.

You will see the Decap CMS login page.

In local development mode, you do not need to log in. The proxy server handles authentication automatically. You will be taken directly to the admin dashboard.

Step 6: Explore the Admin Panel

Once logged in, you will see the Decap CMS dashboard. The left sidebar shows these collections:

Click any collection to start editing.

Step 7: Edit Your First Content

Let's change the homepage title as a test.

1. Click Home Page in the left sidebar
2. Click Content Home Page
3. Find the Title field
4. Change the text to your website name
5. Click Save in the top right corner

Now open a new browser tab at http://localhost:9000 and refresh. Your new title should appear immediately.

Step 8: Upload an Image

Let's try uploading a logo.

1. Click Widget Setting in the left sidebar
2. Find the Logo Image field
3. Click Choose an image
4. Select an image file from your computer
5. Wait for the upload to complete
6. Click Save

The image is now saved to your project. The path is automatically updated in widget.json.

Step 9: Create a New Car Listing

Let's add a new car to your fleet.

1. Click Cars (Fleet) in the left sidebar
2. Click New Car at the top of the page
3. Fill in the fields:

4. Click Save
5. Click Publish to make it live

The new car will appear on your fleet page immediately.

Step 10: Create a New Blog Post

Let's write a blog article.

1. Click Blog Posts in the left sidebar
2. Click New Post
3. Fill in the fields:

4. Click Save
5. Click Publish

The article will appear on your blog page immediately.

How the Workflow Works

When you save in Decap CMS, here is what happens:

1. Content is updated in the JSON or Markdown file
2. The Decap CMS proxy server commits the change to your local repository
3. You need to rebuild the site (npm run build) to see the change in serve mode
4. In develop mode, changes are automatic

Note: Because CMS works best with serve mode, you need to rebuild after each content change. If you want automatic rebuilds, use gatsby develop and access the CMS at /admin/ (which returns 404 — see the "Important" section above).

The compromise: Use gatsby develop for coding and design work. Use gatsby build && gatsby serve when you need to edit content through the CMS.

Stopping the Servers

When you are done:

1. Go to Terminal 1 and press Ctrl + C to stop the serve server
2. Go to Terminal 2 and press Ctrl + C to stop Decap CMS

You can restart both anytime by following steps 2 through 4 again.

Common Issues and Solutions

Issue: /admin/ returns 404

This is expected behavior in gatsby develop mode. Gatsby does not serve static HTML files from static/ during development.

Solution: Use npm run build && npm run serve and access http://localhost:9000/admin/.

Issue: Port 8081 is already in use

Another Decap CMS server is already running.

Solution:

1. Close all terminals
2. Restart VS Code
3. Try again

Issue: Port 9000 is already in use

Another process is using port 9000.

Solution:

npm run serve -- --port 9001

Then access http://localhost:9001/admin/.

Issue: Changes do not appear on the website

In serve mode, changes require a rebuild.

Solution: Stop the server (Ctrl + C), run npm run build, then npm run serve again.

Issue: Image upload fails

Solution:

1. Check that media_folder and public_folder in static/admin/config.yml are correct
2. Make sure the static/images/ folder exists
3. Check that you have write permission to the folder

Issue: "Cannot find module 'decap-server'"

Solution: Install the Decap CMS server globally or use npx:

npx decap-server

Issue: Admin page shows blank screen

Solution:

1. Check browser console for errors (F12)
2. Check Terminal 2 for proxy server errors
3. Restart both terminals

Issue: Cannot log in

In local development mode, no login is required. If you see a login page:

1. Make sure Terminal 2 is running npx decap-server
2. Check that config.yml has local_backend: true
3. Try refreshing the page

Which Command Should I Use?

Recommendation: During development, use npm start for coding. When you need to edit content via CMS, switch to npm run build && npm run serve. This is the standard workflow for Gatsby + Decap CMS projects.

Understanding the Difference

gatsby develop (npm start):

• Fast rebuilds as you edit code
• Hot module reloading
• Does not serve static HTML files
• CMS at /admin/ returns 404

gatsby build && gatsby serve (npm run build && npm run serve):

• Slow rebuilds, requires manual restart
• No hot reloading
• Serves all files from public/
• CMS at /admin/ works

Next Step

You now know how to run and use Decap CMS. Proceed to:

Managing Content with Decap CMS

Need Help?

If you get stuck, contact us:

• Email: creativebydre@gmail.com
• Custom project: https://www.fiverr.com/creativitas/create-your-custom-website-and-app