HomeDock

HomeDock is a sleek, self-hosted server launcher that turns ports and subdomains into a clean, categorized dashboard behind a single password. It is a Next.js + NestJS monorepo with a SQLite-backed configuration, designed for Linux/ARM and Docker Compose.

한국어 문서: README.ko.md

Features

• Password lock screen — a single ADMIN_PASSWORD gates the whole app (no user accounts); JWT HttpOnly cookie session with per-IP login rate limiting.
• Live service health — the API periodically pings each service URL and shows up / degraded / down on every tile, plus an online/down summary.
• Per-service password guard — flag sensitive services to require the password each time they are opened.
• Light / dark / system theme that follows the OS.
• Time + weather hero (Open-Meteo with IP auto-location or manual search) and a configurable system-summary card.
• Tabbed settings (General / Appearance / Widgets / Services) for brand, layout, widgets, and category/service editing.
• Category cards, service tiles with favicons, and a favorites dock.
• Built-in i18n: Korean, English, Japanese, Chinese.

Screenshots

Requirements

• Node.js 20+
• pnpm 9+ (via Corepack)
• Docker (optional, for Compose deployment)

Quickstart (Docker)

1. Clone and enter the repo:

git clone https://github.com/BeomSeokYu/HomeDock.git
cd HomeDock

2. Copy the environment template:

cp .env.example .env

3. Edit .env and set:

   • ADMIN_PASSWORD (lock-screen password), JWT_SECRET
   • WEB_ORIGIN (CORS allowlist)
   • NEXT_PUBLIC_API_BASE_URL (baked into the web build)
   • NEXT_PUBLIC_SITE_URL (used for sitemap and OG metadata)
   • Optional: API_PORT / WEB_PORT (custom ports), LOGIN_MAX_ATTEMPTS / LOGIN_WINDOW_SECONDS (login throttle), HEALTH_CHECK_ENABLED / HEALTH_CHECK_INTERVAL_SECONDS / HEALTH_CHECK_TIMEOUT_SECONDS (service pings), TRUST_PROXY (use the real client IP behind a reverse proxy)

4. Build and run:

docker compose up --build -d

5. Open http://localhost:3000.

Local Development

corepack enable
pnpm install
pnpm db:migrate
pnpm dev

Run separately if needed:

pnpm dev:web
pnpm dev:api

Default ports: web :3000, API :4000.

Contributing

Please read CONTRIBUTING.md before opening issues or pull requests. For community guidelines, see CODE_OF_CONDUCT.md. Security issues should be reported via SECURITY.md.

API Endpoints

• POST /api/auth/login -> verify password, set auth cookie (per-IP rate limited)
• POST /api/auth/logout -> clear auth cookie
• GET /api/auth/me -> current session
• GET /api/status -> service health (up/degraded/down) + summary
• GET /api/dashboard -> dashboard data
• GET /api/dashboard/admin -> dashboard data incl. guarded services (auth)
• PUT /api/dashboard/admin -> update config + categories (auth)
• GET /api/weather -> current weather + daily data
• GET /api/weather/locations?query=... -> location search

Notes

• Docker Compose stores SQLite at ./homedock-data/homedock.db on the host.
• The lock-screen password is checked directly against ADMIN_PASSWORD — there are no user accounts or seeded credentials. Repeated failures from an IP are throttled (LOGIN_MAX_ATTEMPTS / LOGIN_WINDOW_SECONDS).
• Service health checks run server-side, so the API must be able to reach each service URL. Behind a reverse proxy, set TRUST_PROXY so the real client IP is used for login throttling.
• API container applies migrations on startup when prisma/migrations exist.
• NEXT_PUBLIC_API_BASE_URL is baked into the web build; rebuild when it changes.
• Admin auth uses an HttpOnly cookie (default SameSite=Lax). If web and API run on different domains, set COOKIE_SAME_SITE=none and COOKIE_SECURE=true, and add CSRF protection.
• Dynamic OG/icon routes use the Next.js edge runtime; build warnings about edge runtime are expected when those routes are enabled.

Assets & Previews

Brand assets (favicon, app icons, OG preview) are generated from SVG templates. Run this after you tweak the UI or update the preview design:

pnpm assets:generate

Note: the generator uses sharp. If your environment lacks a compatible binary, run it in Linux/macOS or install the proper platform build.