Skip to main content
Skip to content
Template Empire
Admin Dashboardv1.25.31
Live DemoView template

Last updated on 4 June 2026

Installation

This template ships as source code. Extract the ZIP, configure environment variables, install dependencies, migrate the database, seed demo data, and run the dev server.

Prerequisites

  • Node.js 22.13+ (matches CI and the pinned pnpm runtime)
  • pnpm 10+
  • PostgreSQL 15+ (Docker Desktop is enough for local development)
  • Git

Quick Start With Docker Compose

The demo compose file runs Postgres only. Next.js runs on the host via pnpm dev so hot reload works normally. It exposes Postgres on host port 55432 to avoid clashing with an existing local Postgres on 5432.

bash
# 1. Copy environment
# PowerShell:
Copy-Item .env.example .env -Force
# macOS/Linux:
cp -f .env.example .env

# 2. Start Postgres
docker compose -f docker-compose.demo.yml up -d

# 3. Install dependencies
pnpm install

# 4. Apply migrations (the script waits for Postgres to become reachable)
pnpm db:migrate

# 5. Seed demo admin data
pnpm db:seed:demo

# 6. Run the dev server
pnpm dev

Open http://localhost:3000.

Demo Login

  • Admin: admin@example.com / Password123!!
  • Demo user: demo@example.com / Password123!!

Set SEED_PASSWORD before seeding if the demo is publicly reachable.

Native Postgres

bash
createdb nexus_admin
cp .env.example .env
# Edit .env: DATABASE_URL="postgresql://<user>:<pass>@localhost:5432/nexus_admin"
# Or, if you are using the bundled Docker Compose file, leave .env unchanged.

pnpm install
pnpm db:migrate
pnpm db:seed:demo
pnpm dev

Environment Variables

Required in production:

  • DATABASE_URL or POSTGRES_USER, POSTGRES_PASSWORD, POSTGRES_HOST, POSTGRES_PORT, and POSTGRES_DB.
  • JWT_SECRET - generate with openssl rand -base64 48.
  • NEXT_PUBLIC_APP_URL - your canonical public URL.

Recommended:

  • SMTP_* values for invite, password-reset, and account-status emails.
  • WEBHOOK_ENCRYPTION_KEY - generate with openssl rand -hex 32.
  • DELETION_WEBHOOK_URL if downstream processors need erasure notifications.

Public-growth and checkout variables are intentionally absent from TL02. This family is invite-only admin tooling, with users created from the admin console.

Verifying The Install

After seeding, these should work:

  • http://localhost:3000 renders the Nexus showcase page.
  • http://localhost:3000/login accepts the demo credentials.
  • http://localhost:3000/dashboard loads after login.
  • http://localhost:3000/users, /roles, /data, /security, /system, and /audit-log render the admin surfaces.
  • http://localhost:3000/health returns status healthy.
  • http://localhost:3000/ready returns status ready when the database is reachable.
  • http://localhost:3000/api/docs renders the API reference.

Pre-flight Checks

The buyer ZIP ships as a clean runnable starter. Template Empire runs the regression suite before packaging; buyers should run the shipped app-level checks before customising:

bash
pnpm typecheck
pnpm lint
pnpm build
pnpm audit:prod

Common Issues

Native dependency install fails

Some dependencies compile native bindings.

  • macOS: xcode-select --install
  • Ubuntu/Debian: sudo apt install build-essential python3
  • Windows: install Visual Studio Build Tools with "Desktop development with C++"

Migrations fail with PostgreSQL is not reachable

docker compose up -d starts the container, but Postgres may still be warming up or the host port may not be reachable yet. The pnpm db:migrate and pnpm db:seed scripts wait up to 60 seconds before failing. If they still fail, inspect the container and port mapping:

bash
docker compose -f docker-compose.demo.yml ps
docker compose -f docker-compose.demo.yml logs postgres

Confirm .env matches the exposed compose port (POSTGRES_PORT) and that no other local Postgres/container is already bound to that port.

For the bundled Docker setup, those values should be:

env
POSTGRES_PORT="55432"
POSTGRES_DB="nexus_admin"

If login fails with a missing-column error such as users.role_id, .env is almost certainly pointing at another template's database. Reset this template's database and rerun the setup:

powershell
# PowerShell:
docker compose -f docker-compose.demo.yml down -v
Copy-Item .env.example .env -Force
docker compose -f docker-compose.demo.yml up -d
pnpm db:migrate
pnpm db:seed:demo
pnpm dev
bash
# macOS/Linux:
docker compose -f docker-compose.demo.yml down -v
cp -f .env.example .env
docker compose -f docker-compose.demo.yml up -d
pnpm db:migrate
pnpm db:seed:demo
pnpm dev

Migrations fail

Check that DATABASE_URL points at the same Postgres instance started by Docker or your native service. Use pnpm db:migrate for first run. pnpm db:push is only for schema experiments.

Emails do not send

Without SMTP configuration, transactional emails log in development. Configure SMTP_HOST, SMTP_PORT, SMTP_USER, SMTP_PASS, and SMTP_FROM for real delivery.

Port 3000 is already in use

Set PORT=3001 in .env, or stop the conflicting process.

Next Steps

  • CUSTOMIZATION.md - theme, branding, demo data, and legal pages.
  • DEPLOYMENT.md - production hosting, health checks, and maintenance.
  • COMPLIANCE.md - Gate 17 compliance scaffold.