Quick Start

This guide gets you from zero to a running Baan instance as fast as possible. You’ll have a local dev server with the admin panel ready in about 5 minutes.

Prerequisites

• Node.js 24.0.0 or higher — check with node -v
• npm 10 or higher — check with npm -v
• A terminal and basic familiarity with the command line

Option A: Run Locally (Node.js)

1. Clone the repository

git clone https://github.com/baan-press/baan
cd baan

2. Install dependencies

npm install

This installs all dependencies including Next.js, the database client, and AI SDK packages. Expect it to take 1–2 minutes on first run.

3. Start the development server

npm run dev

Before Next.js starts, two pre-build scripts run automatically:

• generate-theme-manifest — scans the themes/ directory and registers available themes
• prebuild-site-settings — syncs settings from the database to a generated JSON file for fast reads

Once you see ✓ Ready, the server is up. The default port is 3000. To use a different port:

PORT=3001 npm run dev

4. Complete the setup wizard

On a fresh install, opening any URL automatically redirects to the setup wizard — you don’t need to navigate there manually. Or go directly:

http://localhost:3000/baan-admin/setup

Note

The redirect happens because Baan checks whether setup is complete on every request. Setup is considered complete once an admin account and a secret admin path both exist in the database. Until then, all routes redirect to /baan-admin/setup.

The wizard walks you through 4 steps:

1. Environment — choose Self-hosted for local development
2. Account — create your admin username and password
3. Storage — choose Local to store articles on disk (no cloud credentials needed)
4. Done — your secret admin URL is displayed

Caution

Save the admin URL shown at step 4. It contains a 16+ character random path that protects your admin panel. If you lose it, you can find it in the database or environment variables.

5. Log in and create your first post

Navigate to the URL shown in step 4 (e.g. http://localhost:3000/baan-admin/xK9mP2qR.../login), log in with the credentials you created, and click New Post to start writing.

---

Option B: Run with Docker

If you prefer containers, Docker Compose handles everything:

1. Clone the repository

git clone https://github.com/baan-press/baan
cd baan

2. Create an environment file

cp .env.example .env

For a local-only quick start, the .env file can be left empty — the setup wizard configures the storage provider and saves it to the database. Add cloud storage or AI credentials only when you need them.

3. Start the container

docker compose up -d

The container builds the app and starts it. On first run this takes 2–3 minutes.

4. Complete setup

Open http://localhost:3000/baan-admin/setup and follow the same 4-step wizard as above.

Tip

Docker Compose mounts ./data for the SQLite database and ./content for articles, so your data persists across container restarts and updates.

---

What’s Next?

Once you’re up and running, here’s what to explore:

Goal	Where to go
Set up cloud storage (GCS / S3 / R2)	Storage Configuration
Deploy to production	Vercel · Docker
Connect an AI provider	AI Integration
Write in Obsidian or VSCode	External Editors
Import from WordPress or Hugo	Importing Content