179 lines
4.4 KiB
Markdown
179 lines
4.4 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
bun install
|
|
```
|
|
|
|
2. Prepare environment file at `apps/server/.env`
|
|
|
|
Example values:
|
|
|
|
```env
|
|
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`
|
|
|
|
```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
|
|
|
|
```bash
|
|
bun run db:start
|
|
```
|
|
|
|
6. Apply schema
|
|
|
|
```bash
|
|
bun run db:push
|
|
```
|
|
|
|
7. Seed sample data
|
|
|
|
```bash
|
|
bun run --filter @minmon/db db:seed
|
|
```
|
|
|
|
Seeded admin login:
|
|
|
|
- Email: `admin@minmon.local`
|
|
- Password: `admin12345`
|
|
|
|
8. Run the apps
|
|
|
|
```bash
|
|
bun run dev
|
|
```
|
|
|
|
9. Open the app
|
|
|
|
- Web: `http://localhost:5173`
|
|
- API: `http://localhost:3000`
|
|
|
|
## Docker Compose Deployment
|
|
|
|
Run the deployable stack with one command:
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
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.
|