# GhostGrid

GhostGrid is an internal network lab and device inventory tool for managing hardware lab environments.

The application uses an Express backend and a Vite/React frontend running in a single Node.js process. Data is stored locally in a SQLite database using `better-sqlite3`.

GhostGrid is designed to run fully offline. Fonts are bundled locally through `@fontsource`, and the application does not load external code, assets, or CDN resources at runtime.

## Features

- **Dashboard**  
  Overview of active and upcoming reservations, plus a quick links widget for frequently used tools.

- **Bookings**  
  Reserve complete lab topologies or individual devices for a defined time period. Bookings include conflict detection and device status validation.

- **Inventory**  
  Manage lab devices, including emergency and rescue information. Live device status is retrieved from CheckMK.

- **Topology**  
  Visualize devices and connections for each lab environment.

- **Quick Links**  
  Shared link dashboard for internal tools such as CheckMK, Semaphore, documentation, or jump hosts.

- **Team**  
  Overview of all registered users.

- **Logbook**  
  Shared audit and maintenance journal for lab activity, operational notes, and troubleshooting history.

## Device Status

Device reachability is monitored in CheckMK and imported through the CheckMK API.

Each device can be linked to CheckMK using the **CheckMK Host URL** field. If no CheckMK binding is configured, the device status is set to `unknown`.

Devices with an `unknown` status are not available for booking.

## Local Development

### Requirements

- Node.js 20 LTS

### Setup

```bash
npm install
npm run dev
```

The application will be available at:

```text
http://localhost:3000
```

The development server runs the Express backend with Vite middleware.

## Available Scripts

```bash
npm run dev
```

Start the local development server.

```bash
npm run build
```

Build the frontend into `dist/` and bundle the server as `dist/server.cjs`.

```bash
npm start
```

Start the built production server. This expects `NODE_ENV=production`.

```bash
npm run lint
```

Run the TypeScript type check using `tsc --noEmit`.

## Configuration

Configuration is loaded from environment variables or a local `.env` file. See `.env.example` for reference.

| Variable | Description |
| --- | --- |
| `JWT_SECRET` | Secret used to sign JSON Web Tokens. This must be set explicitly in production. Without a value, the application falls back to an insecure default. |
| `PORT` | HTTP port used by the application. Defaults to `3000`. |

## Deployment

Production deployment is intended to run inside a Proxmox LXC container using systemd.

For detailed deployment instructions, see:

```text
DEPLOY.md
```

The container runs both branches in parallel:

| Branch | Purpose | Port |
| --- | --- | --- |
| `main` | Production | `3000` |
| `dev` | Staging | `3001` |

Each branch runs as a separate systemd service and uses its own database.