Aller au contenu principal

Local Setup

This page covers the per-repository local dev setup. Common prerequisites are listed first.

Prerequisites (all repos)​

  • Node.js 20 LTS (use nvm)
  • pnpm 9.x (corepack enable && corepack use pnpm@9)
  • Git 2.40+
  • GitHub CLI (gh) configured with your GitHub account
  • Docker + Docker Compose for backend services
  • A .env.local per repo (template in each README.md; secrets via 1Password)

Secrets policy: never commit .env* files. Hooks in ~/.claude/hooks/ block commits that include known secret patterns. See security.

Repository layout​

noxys/
├── noxys-extension/   ← MV3 browser extension (Chrome/Edge/Firefox)
├── noxys-console/     ← Next.js admin SaaS
├── noxys-api/         ← FastAPI/Node.js backend
├── noxys-doc/         ← Docusaurus customer documentation (this site)
├── noxys-website/     ← marketing site + ADRs
├── noxys-infra/       ← Terraform + Ansible for VPS / staging / prod
├── noxys-vscode/      ← VS Code extension (early prototype)
└── noxys-mobile/      ← mobile shell (out-of-scope, placeholder)

Per-repo setup​

noxys-extension​

cd noxys-extension
pnpm install
pnpm dev          # builds MV3 to dist/, watch mode
# load dist/ as unpacked extension in chrome://extensions

Tests:

pnpm test          # vitest unit
pnpm test:e2e      # playwright against a staging tenant

noxys-console​

cd noxys-console
pnpm install
cp .env.example .env.local   # fill from 1Password
pnpm dev                      # http://localhost:3000

Backend dependency: requires noxys-api reachable at NEXT_PUBLIC_API_BASE.

noxys-api​

cd noxys-api
pnpm install
docker compose up -d postgres redis   # local infra
cp .env.example .env.local
pnpm migrate
pnpm dev          # http://localhost:4000, OpenAPI at /docs

noxys-doc​

cd noxys-doc
pnpm install
pnpm start        # http://localhost:3000 (or 3001 if console is up)
pnpm build        # static build to build/

noxys-website​

cd noxys-website
pnpm install
pnpm dev          # Next.js, http://localhost:3000

noxys-infra​

Read-only for most contributors. Production access is gated by SSH key + 1Password TOTP. See noxys-infra/README.md.

Verifying your setup​

After cloning, run the cross-repo health check:

cd noxys
./scripts/dev-doctor.sh   # checks node, pnpm, docker, git hooks, env vars

If dev-doctor.sh reports green, you are ready. If not, fix the listed issues before proceeding.

Editor setup​

  • VS Code is the supported IDE. Recommended extensions are in each repo's .vscode/extensions.json.
  • Prettier + ESLint run on save.
  • TypeScript strict mode is enforced — no any, no implicit-any escape hatches.

Troubleshooting​

  • PNPM lockfile drift → pnpm install --frozen-lockfile (CI uses this).
  • Docker volumes stale → docker compose down -v && docker compose up -d.
  • MV3 service worker not reloading → reload extension from chrome://extensions after each rebuild.

For environment-specific issues (PRoot-Distro, ARM64), see ~/.claude/docs/on-demand/proot-distro-environment.md.