Local Development Setup

This guide explains how to set up StatusDock for local development.

Prerequisites

Node.js 20+
PostgreSQL 15+ (or Docker)
npm or pnpm

CMS Backend Choice

StatusDock supports both Payload CMS (default) and Strapi v5. This guide covers Payload CMS setup. For Strapi development, see the Strapi Setup Guide.

Quick Start with Docker (Payload CMS)

The easiest way to develop locally is using the included Docker Compose configuration.

# Clone the repository
git clone https://github.com/Docker-Hunterpedia/StatusDock.git
cd StatusDock

# Start the development environment
docker compose -f docker-compose.dev.yml up -d postgres  # Start only the database

# Install dependencies
npm install

# Run database migrations
npm run payload migrate

# Start the development server
npm run dev

Visit:

Status page: http://localhost:3333
Admin panel: http://localhost:3333/admin

Note: The dev compose file uses port 3333 to avoid conflicts with production on port 3000.

Manual Setup

1. Install PostgreSQL

# macOS with Homebrew
brew install postgresql@16
brew services start postgresql@16

# Create database
createdb statusdock_db

2. Clone and Install

git clone https://github.com/Docker-Hunterpedia/StatusDock.git
cd StatusDock
npm install

3. Configure Environment

cp .env.example .env

Edit .env:

DATABASE_URI=postgres://localhost:5432/statusdock_db
PAYLOAD_SECRET=your-development-secret-key
SERVER_URL=http://localhost:3000

4. Run Migrations

npm run payload migrate

5. Start Development Server

npm run dev

Development Scripts

Script	Description
`npm run dev`	Start development server with hot reload
`npm run build`	Build for production
`npm run start`	Start production server
`npm run payload migrate`	Run database migrations
`npm run payload generate:types`	Generate TypeScript types
`npm run payload generate:importmap`	Generate import map for custom components

Project Structure

status-page/
├── src/
│   ├── app/                    # Next.js App Router
│   │   ├── (frontend)/         # Public status pages
│   │   ├── (payload)/          # Admin panel
│   │   └── api/                # API routes
│   ├── collections/            # Payload CMS collections
│   ├── components/             # React components
│   │   ├── admin/              # Admin panel components
│   │   └── status/             # Status page components
│   ├── globals/                # Payload CMS globals
│   ├── lib/                    # Utility functions
│   └── tasks/                  # Background job handlers
├── public/                     # Static assets
├── payload.config.ts           # Payload CMS configuration
└── tailwind.config.ts          # Tailwind CSS configuration

Making Changes

Adding a Collection

Create a new file in src/collections/
Export the collection config
Import and add to payload.config.ts
Run npm run payload generate:types
Run migrations if needed

Adding a Custom Admin Component

Create component in src/components/admin/
Reference it in the collection config
Run npm run payload generate:importmap

Adding an API Endpoint

Create a route file in src/app/api/
Export GET, POST, etc. handlers

Testing

# Type checking
npm run typecheck

# Build test
npm run build

Debugging

Database Issues

# Connect to database
psql $DATABASE_URI

# Reset database
dropdb statusdock_db && createdb statusdock_db
npm run payload migrate

Clear Cache

rm -rf .next
npm run dev

Keyboard shortcuts

StatusDock