Skip to content

AGENTS.md

Latest commit

 

History

History
96 lines (69 loc) · 3.7 KB

AGENTS.md

File metadata and controls

96 lines (69 loc) · 3.7 KB
Raw

AGENTS.md

Project Overview

Dockify is a self-hosted Docker app deployment platform — single Go binary, SQLite, SSH workers, Caddy + Cloudflare automation. Full project reference: SPEC.md.

Build

go build -o dockify ./cmd/dockify
./dockify serve        # start server
./dockify version      # print version

Development Workflow

This project uses Air for live-reload.

air                      # http://localhost:8080, auto-rebuilds on save

Air watches .go files in cmd/ and internal/ + .html templates. On build error the old server keeps running (stop_on_error = false). Data stored in ./data/ (SQLite, gitignored). Credentials in .env (gitignored). Config: .air.toml at project root.

Key Commands

go build ./...           # build all packages
go vet ./...             # lint
go mod tidy              # clean dependencies

# Run once (no auto-reload)
DOCKIFY_HOST=127.0.0.1 DOCKIFY_DATA_DIR=./data go run ./cmd/dockify serve

# Boost/PWA: page scripts must be idempotent (docs/DESIGN-SYSTEM.md §7.1); ui.mjs covers boosted navigation

# Verify templates parse
go test ./internal/http/... -run TestTemplates

# UI check (screenshots, overflow, nodes, nav timing, contrast, a11y); needs Playwright in ~/.local/share/pw-tools
DOCKIFY_DEV_MOCK=true DOCKIFY_PORT=18090 go run ./cmd/dockify serve &   # optional: DOCKIFY_ADMIN_PASSWORD=uji123 for the login screen
node tests/e2e/ui.mjs [BASE_URL] [OUT]   # env UI_USER/UI_PASS when auth is on; exit 1 on overflow/contrast/a11y failure

# Build and run with Docker
docker build -t dockify .
docker run -p 127.0.0.1:8080:8080 -e DOCKIFY_ALLOW_NO_AUTH=true -v $(pwd)/data:/var/lib/dockify dockify

Dev Mode

Set DOCKIFY_DEV_MOCK=true to use mock SSH client — no real VMs needed for UI development. Yellow "Dev Mock Mode" banner appears in the nav. Includes a mock interactive terminal for the SSH console.

UI Style Guide

UI work must follow docs/DESIGN-SYSTEM.md (3 palettes × light/dark/system tokens, shared partials, action hierarchy, PR checklist). The revamp plan and measurements: docs/UI-REVAMP-PLAN.md, docs/ui-revamp/. Styles live in internal/http/static/app.css; no CSS framework, no hex in templates (except xterm themes), no inline style="" except --w values. Run node tests/e2e/ui.mjs (see Key Commands) before opening a UI PR.

Git Workflow

Branch Strategy

  • main — stable, production-ready. Only updated via merge PR.
  • feat/* — new features
  • fix/* — bug fixes

Daily Flow

  1. Start task: git checkout main && git pull && git checkout -b feat/x
  2. Work: edit → commit → push (WIP commits allowed)
  3. Switch PC: commit + push first; git pull on new PC, git checkout feat/x
  4. Done: push final → gh pr create --fill
  5. User says "merge" → gh pr merge --merge --delete-branch && git branch -d feat/x && git checkout main
  6. Release (from main): ./scripts/release.sh patch

Commit Messages

feat: add dark mode toggle
fix: handle empty server list
refactor: extract deploy logic
docs: update README
wip: partial work (feature branch only, never on main)

Rules

  • Never commit/amend directly to main
  • Never force push
  • Never commit .env, tokens, or secrets
  • Remote branch auto-deletes after merge; delete local branch manually

Release

./scripts/release.sh patch    # bump 0.1.0 → 0.1.1
./scripts/release.sh minor    # bump 0.1.1 → 0.2.0
./scripts/release.sh major    # bump 0.2.0 → 1.0.0
./scripts/release.sh 1.5.0    # set exact version

Pushing a v* tag triggers CI which builds binary, creates GitHub Release, and pushes Docker image to ghcr.io/coderbuzz/dockify.