Installation

This page covers everything you need to install and run Baan in a Node.js environment. If you prefer containers, see Deploy with Docker.

System Requirements

Requirement	Minimum	Notes
Node.js	24.0.0	Check with node -v
npm	10.0.0	Check with npm -v
Disk space	~500 MB	Includes node_modules
RAM	512 MB	1 GB+ recommended for builds
OS	Linux, macOS, Windows (WSL2)	Native Windows not tested

Step 1 — Clone the Repository

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

Step 2 — Install Dependencies

npm install

Note

Installation includes native binaries for Sharp (image processing) and the libSQL database client. On Ubuntu/Debian you may need build-essential. On macOS, Xcode Command Line Tools are required (xcode-select --install).

Step 3 — Configure Environment Variables

Baan uses two principles for configuration:

• Secrets (API keys, credentials) → stored in .env / environment variables
• Settings (site title, theme, language) → stored in the database, managed via the admin panel

Create a .env.local file in the project root:

Minimum (local filesystem, self-hosted)

No storage environment variables needed — the setup wizard configures the provider and stores it in the database.

Full Reference

# ── Storage ──────────────────────────────────────────────
# The provider type is configured via the setup wizard (saved to DB). Add only the credentials for your provider.

# Google Cloud Storage
GOOGLE_CLOUD_PROJECT_ID=your-project-id
GCS_BUCKET_NAME=your-bucket-name
GOOGLE_CLOUD_CREDENTIALS_BASE64=base64-encoded-service-account-json

# Amazon S3
AWS_REGION=ap-northeast-1
AWS_S3_BUCKET_NAME=your-bucket-name
AWS_ACCESS_KEY_ID=your-access-key
AWS_SECRET_ACCESS_KEY=your-secret-key

# Cloudflare R2
CF_ACCOUNT_ID=your-cloudflare-account-id
CF_R2_BUCKET_NAME=your-bucket-name
CF_R2_ACCESS_KEY_ID=your-access-key
CF_R2_SECRET_ACCESS_KEY=your-secret-key

# ── AI (optional) ────────────────────────────────────────
ANTHROPIC_API_KEY=sk-ant-...
OPENAI_API_KEY=sk-...
GEMINI_API_KEY=AI...

# ── Database (serverless / Turso only) ───────────────────
DATABASE_URL=libsql://your-db.turso.io
DATABASE_AUTH_TOKEN=...

The admin URL path and user accounts are not env vars — the setup wizard writes them directly to data/app.db (self-hosted) or your Turso database (serverless).

Caution

Never commit .env.local to version control. It contains storage credentials and AI API keys. The file is .gitignored by default.

Step 4 — Run the Setup Wizard

Start the development server:

npm run dev

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

1. generate-theme-manifest — scans themes/ and registers available themes in lib/generated/theme-manifest.json
2. prebuild-site-settings — reads settings from the database and writes lib/generated/site-settings.json for fast access at runtime

Once you see ✓ Ready, open your browser at:

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

The default port is 3000. To use a different port, set the PORT environment variable:

PORT=3001 npm run dev

The 4-step wizard creates the database schema, your admin user, and the secret admin URL. All values are saved directly to data/app.db — no .env.local editing required after setup. The wizard redirects you straight to the login page when done.

Step 5 — Production Build

npm run build
npm start

The build runs the same pre-build scripts, then compiles the Next.js app. Watch for any errors — a successful build is required before deployment.

Caution

Always verify npm run build completes without errors before deploying. The build step validates theme components and generates static files that the runtime depends on.

Updating Baan

git pull
npm install        # picks up any new or updated dependencies
npm run build
npm start          # or restart your PM2 / systemd process

Database migrations run automatically on the first database access after an update — no manual migration step is needed. Migrations are idempotent and check the actual database state directly before applying changes.

Useful Commands

npm run dev              # Development server with hot reload
npm run build            # Production build
npm run start            # Start production server
npm run clean            # Remove build cache (.next)
npm test                 # Run all unit tests (Vitest)
npm run test:security    # Security-focused tests
npm run test:e2e         # End-to-end tests (Playwright)

To fully reset the project to a clean state (removes the database, build cache, and dependencies):

rm -rf .next .next-test node_modules data .test-output
npm install

After this, run npm run dev and complete the setup wizard at /baan-admin/setup.