القائمة
Guide for developing features in the Vite + React Router frontend.
التثبيت باستخدام Codex أو Claude انسخ هذا Prompt والصقه في Codex أو Claude أو مساعد آخر ليراجع صفحة Skill ويثبّتها لك.
استنادا إلى تصنيف SOC المهني
Guide for server management, system APIs, backups, and maintenance operations.
Guide to Docklift's automated release pipeline using semantic-release.
Guide for setting up, running, and developing the Docklift project.
Guide for setting up and managing Docklift's GitHub App integration.
Coolify/Dokploy-style managed databases with Dokku-style app linking.
Security patterns, guards, and best practices enforced across the Docklift codebase.
| name | Frontend Development |
| description | Guide for developing features in the Vite + React Router frontend. |
Docklift uses Vite + React + React Router for its dashboard (static SPA in production).
frontend/src/)| Route | File | Description |
|---|---|---|
/ | pages/Dashboard.tsx | Projects list (mobile cards / desktop table, filters, pagination) |
/sign-in | pages/SignIn.tsx | Login page |
/setup | pages/Setup.tsx | First-run registration |
/projects/new | pages/NewProject.tsx | Project creation wizard (PageHeader, brand chips/cards) |
/projects/:id | pages/ProjectDetail.tsx | Project detail tabs |
/logs | pages/Logs.tsx | System logs (SSE) — compact header, one-viewport fill |
/terminal | pages/Terminal.tsx | Web terminal (xterm.js) — compact header, one-viewport fill |
/system | pages/System.tsx | Host metrics (SystemOverview) — compact Operate header, page scrolls (not one-viewport) |
/ports | pages/Ports.tsx | Docker port mapping — compact header, one-viewport fill |
/databases | pages/Databases.tsx | Managed DBs (Projects-style filters, mobile cards / desktop table) |
/databases/new | pages/NewDatabase.tsx | Full-width create + sticky CTA (matches New Project) |
| — | components/databases/* | Connection, link, attach panels |
/settings | pages/Settings.tsx | Settings + GitHub |
| Docs | external | https://docklift.dev (VitePress site in website/) |
Router: src/app/router.tsx (lazy route chunks). /sign-in and /setup render
bare; every other route is nested under app/AppShell.tsx.
components/shell/)All navigation lives in a fixed left rail. Pages render only their own content —
they must not add a page header bar, footer, or outer container/min-h-screen
wrapper, because AppShell already supplies the top bar, max width and padding.
| Component | Purpose |
|---|---|
AppShell.tsx (app/) | Fixed rail, mobile drawer, top bar, content <main> |
Sidebar.tsx | Brand, New Project, grouped nav, Settings tree, version footer |
navigation.ts | Nav groups + breadcrumbs — add new pages here once. Each item’s section prefixes keep the rail selected on nested routes (/projects/*, /databases/new, /settings, …) |
lib/settingsNav.ts | Settings section ids/labels shared by rail tree + Settings page |
AccountMenu.tsx | Header account menu: identity, profile, sign out (theme is TopBar toggle) |
SidebarStatus.tsx | Version + upgrade prompt (star cache shared with TopBar) |
TopBar.tsx | Breadcrumbs, search, GitHub star, theme toggle, account menu |
CommandPalette.tsx | Ctrl/Cmd+K: pages, projects, actions |
PageHeader.tsx | PageHeader + StatChip for consistent page titles |
Shortcuts: Ctrl/Cmd+K opens the palette, Ctrl/Cmd+B collapses the rail
(persisted in docklift_sidebar_collapsed).
Sticky page elements sit below the 3.5rem top bar — use top-14 for flush
elements and top-20 for spaced ones.
| Component | Location | Purpose |
|---|---|---|
LogViewer.tsx | components/ | Shared log viewer (search, copy, download, clear, fullscreen) — used for project/service runtime logs and System Logs |
SystemLogsPanel.tsx | components/ | SSE system logs |
TerminalView.tsx | components/ | xterm.js + WS terminal |
FileEditor.tsx | components/ | Full-screen IDE Monaco editor (dirty state, Ctrl/⌘S, Esc) |
AuthProvider.tsx | components/ | Auth + route redirects |
ServiceDomainCard.tsx | components/domains/ | Project service domain list + SSL (serial mutation queue) |
PanelDomainCard.tsx | components/domains/ | Settings → Domain panel hostname + SSL (same UX as service card) |
DnsGuideCard.tsx | components/domains/ | Shared “Point DNS at this server” guide |
authFetch() from lib/auth.ts (401 → logout). Do not use raw fetch +
getAuthHeaders() for authenticated endpoints — check res.ok before treating data as success
(Ports, Databases, GitHub disconnect, etc.).lib/streamProgress.ts (consumeProgressStream) — require
res.ok and treat [ERROR] lines as failure before toasting success.password) for step-up auth.lib/focusTrap.ts (useFocusTrap) for command palette + mobile drawer.degraded (partial fleet) — StatusBadge / ProjectCard must show it;
treat like running for stop/restart actions.publish_host_port checkbox (default off) — host ports are opt-in.IP:null or link until serverIP is real.
If no host port and no domain, show Private by default with clear copy: prefer a
domain; avoid sharing IP:port (exposes origin IP / easier to scan). Key
“awaiting host port / Redeploy” off persisted project.publish_host_port — never
the unsaved Build checkbox (publishHostPort form state). Secondary CTA when not
awaiting: Build settings (navigates; does not publish). If Publish is already
saved on but svc.port is still null, say redeploy is required. No “Workspace” badge.DnsGuideCard highlights “Point DNS at this server”
with short Cloudflare tips (no accordion). Empty-state: private-by-default + domain
preferred; mention Build → Publish host ports + redeploy as the opt-in IP:port path./settings?tab=domain): same guide + inline add (no popup),
SSL status pills, Check DNS, Retry HTTPS, and Let’s Encrypt activity log via
PanelDomainCard — mirror project Domain, not a table/dialog.is_secret) when is_build_arg is on.PORT in frontend/.env)/api and /ws → http://127.0.0.1:8000VITE_API_URL empty for same-origin / proxybun run build → dist/docklift-frontend serves static files with nginx on 3000nginx.conf proxies / → docklift-frontend:3000 and keeps /api, /ws/, SSE rules