Build a Headless Site with dotCMS

Set Up Your Project

In this chapter you'll spin up a local dotCMS instance with the learning starter content pre-loaded, then clone the frontend project. By the end you'll have both running locally.

Before you start#

---

Make sure Docker Desktop is installed and running. Look for the Docker icon in your system tray or menu bar. If it's not running, start it before continuing.

Step 1: Start dotCMS#

---

Run this command to download and start a local dotCMS instance with the learning starter content:

npx @dotcms/create-app my-banking-site -d ./my-banking-site --local --starter https://repo.dotcms.com/artifactory/libs-release-local/com/dotcms/starter-learning/20260326/starter-learning-20260326.zip

What each flag does:

• my-banking-site — the project name
• -d ./my-banking-site — the folder to create
• --local — spins up dotCMS locally using Docker
• --starter — loads the learning starter content into dotCMS (the banking site content you'll build against)

The CLI runs through the setup automatically:

✔ Docker is available
✔ All required ports are available
✔ Docker Compose configuration downloaded
✔ dotCMS containers started successfully
✔ dotCMS is running locally at http://localhost:8082
✔ Default credentials: admin@dotcms.com / admin
✅ Project setup complete!

This takes 2–5 minutes on the first run — Docker needs to download the dotCMS images.

Note: When using --starter, the CLI sets up dotCMS only. Frontend scaffolding is skipped — you'll clone the frontend in the next step.

Troubleshooting#

---

Docker is not available

Make sure Docker Desktop is installed and running. Check for the Docker icon in your system tray, then run the command again.

Ports are already in use

You likely have another dotCMS instance running. Stop it with:

docker compose down

Then run the command again.

Step 2: Clone the frontend#

---

The learning starter frontend lives at github.com/dotCMS/dotcms-learning-nextjs. Clone the main branch — that's the starting point you'll build from:

git clone https://github.com/dotCMS/dotcms-learning-nextjs.git my-banking-site/frontend
cd my-banking-site/frontend
npm install

Stuck? The solution branch contains the completed project. Use it as a reference if you need to check your work.

Step 3: Start the frontend#

---

npm run dev

What you now have#

---

Checkpoint#

---

• Open http://localhost:8082/c — you should see the dotCMS login page
• Open http://localhost:3000 — you should see the starter placeholder page

Both running? You're ready for the next chapter.