minmon/docs/run-instructions.md

Run Instructions

Project Description

Minmon is a student-friendly web dashboard for managing private servers, services, domains, and internal notes. The current implementation focuses on protected CRUD flows plus lightweight DNS A-record checking.

Current Main Features

• Admin sign-in with better-auth
• Root route (/) redirects automatically:
  • logged in -> /dashboard
  • not logged in -> /login
• Dashboard summary for:
  • total servers
  • total services
  • total domains
  • DNS match / mismatch / unresolved counts
  • inactive or down services
  • recent notes
• Server CRUD
• Service CRUD
• Domain CRUD
• Note CRUD
• Domain DNS check from:
  • domain list
  • domain detail page
• Server detail page includes notes that belong to that server
• Foreign-key form fields use select inputs for related records:
  • service -> server
  • domain -> service
  • note -> server
• Sample seeded admin and demo dataset

Current Route Structure

• / -> auth-based redirect
• /login -> sign-in page
• /dashboard -> summary page
• /dashboard/servers -> server list
• /dashboard/servers/new -> create server
• /dashboard/servers/$serverId -> server detail + edit + related notes
• /dashboard/services -> service list
• /dashboard/services/new -> create service
• /dashboard/services/$serviceId -> service detail + edit
• /dashboard/domains -> domain list
• /dashboard/domains/new -> create domain
• /dashboard/domains/$domainId -> domain detail + edit
• /dashboard/notes -> note list
• /dashboard/notes/new -> create note
• /dashboard/notes/$noteId -> note detail + edit

Local Setup

1. Install dependencies

bun install

2. Prepare environment file at apps/server/.env

Example values:

DATABASE_URL=postgresql://postgres:postgres@localhost:5432/minmon
BETTER_AUTH_SECRET=your-32-char-or-longer-secret-value-here
BETTER_AUTH_URL=http://localhost:3000
CORS_ORIGIN=http://localhost:5173
NODE_ENV=development

3. Prepare web environment at apps/web/.env

VITE_SERVER_URL=http://localhost:3000

4. Ensure the web app can reach the server

• The web client uses the better-auth client with env.VITE_SERVER_URL
• Make sure the web environment points to the running API server

5. Start PostgreSQL if needed

bun run db:start

6. Apply schema

bun run db:push

7. Seed sample data

bun run --filter @minmon/db db:seed

Seeded admin login:

• Email: admin@minmon.local
• Password: admin12345

8. Run the apps

bun run dev

9. Open the app

• Web: http://localhost:5173
• API: http://localhost:3000

Current Behavior Notes

List Ordering

• Main CRUD list pages are ordered by:
  • createdAt DESC
  • then id DESC
• This keeps row ordering deterministic after refetch.

Delete Actions

• List pages use a two-click destructive icon flow:
  • first click: trash icon
  • second click: check icon confirms delete
• Confirm state resets on blur and timeout.

Domain DNS Check

• Domain list uses the DNS status badge itself as the check trigger.
• Domain detail page also provides a DNS check action.
• DNS checking resolves IPv4 A records only.

Relationship Behavior

• Deleting a server removes related services, domains, and notes through cascade rules in the database.
• Deleting a service removes related domains through cascade rules.

Helpful Commands

bun run check-types
bun run db:push
bun run db:studio
bun run --filter web check-types
bun run --filter server check-types
bun x tsc --noEmit -p packages/api/tsconfig.json

Notes

• Full workspace typecheck may still fail because of a pre-existing apps/desktop typing issue for three.
• The verified implementation path is the web app + server app + database push + database seed.
• DNS checking is limited to A record / IPv4.
• This project is not a deployment platform and does not include SSH, Docker orchestration, or reverse proxy automation.