Cockpit Dashboard

Administration Dashboard for grounds.gg.

Overview

Cockpit is a modern web dashboard for administering grounds.gg, built with Next.js 16, TypeScript, and Tailwind CSS.

Installation

# Install dependencies
pnpm install

Development

# Start development server
pnpm dev

The application is then available at http://localhost:3000.

Docker

The project can be built and run with Docker:

# Build (BuildKit is standard from Docker 23.0+, for older versions: DOCKER_BUILDKIT=1)
docker build -t cockpit .

# Or explicitly with buildx (recommended for Multi-Platform Builds)
docker buildx build -t cockpit .

# Run
docker run -p 3000:3000 cockpit

The Dockerfile uses multi-stage builds for optimized image size and production-ready deployment. For optimal performance, BuildKit cache mounts are used, which enable faster reuse of dependencies between builds.

Configuration

Environment Variables

Authentication (BetterAuth)

• BETTER_AUTH_URL - Base URL for Better Auth (optional, if different from NEXT_PUBLIC_BETTER_AUTH_URL)
• NEXT_PUBLIC_BETTER_AUTH_URL - Public Base URL for Better Auth
• BETTER_AUTH_SECRET - Secret for Better Auth Session Encryption
• DATABASE_URL - PostgreSQL Connection String

Email/Password Authentication

• No additional variables required (enabled by default)

OIDC Authentication

OIDC authentication is provided via the Generic OAuth Plugin from BetterAuth. The following environment variables are required:

Required:

• OIDC_PROVIDER_ID - Unique provider ID for the OIDC provider (e.g. "trusted-oidc")
• NEXT_PUBLIC_OIDC_PROVIDER_ID - Same provider ID, must also be set as a public variable (for client-side)
• OIDC_CLIENT_ID - OAuth Client ID from the OIDC provider
• OIDC_CLIENT_SECRET - OAuth Client Secret from the OIDC provider
• OIDC_DISCOVERY_URL - OIDC Discovery Endpoint URL (e.g. "https://auth.example.com/.well-known/openid-configuration")

Optional:

• OIDC_SCOPES - Comma-separated list of scopes (default: "openid,profile,email")
• OIDC_ROLES_CLAIM - Claim path in the token that contains the roles (default: "roles")
  • Supports nested paths with dot notation (e.g. "realm_access.roles")
• OIDC_ROLE_MAPPING - JSON object for mapping OIDC roles to Cockpit roles
  • Example: {"Admin":"admin","User":"user","PowerUser":"admin"}

Role Mapping:

• Roles are extracted from the OIDC token and mapped to Cockpit roles
• Supported Cockpit roles: "admin" and "user"
• If no valid role is found, "user" is used by default
• If multiple roles are present, "admin" is prioritized if available