syahdan/minmon
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
minmon/docs/run-instructions.md

4.4 KiB
Raw Blame History

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
  1. 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
  1. Prepare web environment at apps/web/.env
VITE_SERVER_URL=http://localhost:3000
  1. 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
  1. Start PostgreSQL if needed
bun run db:start
  1. Apply schema
bun run db:push
  1. Seed sample data
bun run --filter @minmon/db db:seed

Seeded admin login:

  • Email: admin@minmon.local
  • Password: admin12345
  1. Run the apps
bun run dev
  1. Open the app
  • Web: http://localhost:5173
  • API: http://localhost:3000

Docker Compose Deployment

Run the deployable stack with one command:

cp .env.example .env
docker compose up -d

Default Docker endpoints:

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

The Compose stack starts PostgreSQL, applies the schema, and seeds the sample admin only if the users table is empty.

Docker Compose reads the root .env file automatically. Edit it before startup if you need different ports, public URLs, credentials, or secrets.

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.
  • Docker Compose is available for running the app stack; the app itself does not include SSH, reverse proxy, or host orchestration automation.