This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
Nexploy — Self-hosted alternative to Vercel/Netlify, powered by Docker. It deploys applications from Git repositories (GitHub/GitLab) to Docker containers with Traefik as a reverse proxy.
# Start both nexploy and docker-api (recommended for full development)
pnpm dev
# Start only the main Next.js app (port 3000)
pnpm dev:nexploy
# Start only the Docker API service (port 3300)
pnpm dev:docker-api
# Build all apps using Turbo
pnpm build
# Build specific app
pnpm --filter=nexploy build
pnpm --filter=docker-api build# Run migrations in development (creates migration files)
pnpm --filter=nexploy db:migrate:dev
# Apply migrations in production
pnpm --filter=nexploy db:migrate:prod
# Generate Prisma client after schema changes
pnpm --filter=nexploy db:generate
# Create migration file without applying
pnpm --filter=nexploy db:migrate:only
# Reset database and re-run all migrations
pnpm --filter=nexploy db:reset
# Open Prisma Studio (database GUI)
pnpm --filter=nexploy db:studioLinting and formatting are handled by Biome (biome.json at the repo root, single config for the whole monorepo).
# Lint the whole repo
pnpm lint
# Lint and apply safe fixes
pnpm lint:fix
# Format all code
pnpm format
# Lint + format + import sorting in one pass
pnpm check
# Same, applying every safe fix
pnpm check:fix
# Type check all TypeScript
pnpm typesThis is a pnpm + Turborepo monorepo with workspace packages:
Apps:
apps/nexploy- Main Next.js 16 app (port 3000) with custom server, handles UI and orchestrationapps/docker-api- Hono.js API service (port 3300) that manages all Docker operationsapps/desktop- Electron app sharing UI components
Packages:
@workspace/ui- Shared shadcn/ui components (Radix UI + Tailwind)@workspace/schemas-zod- Zod validation schemas@workspace/typescript-interface- Shared TypeScript types@workspace/i18n- Internationalization utilities@workspace/typescript-config- Shared TypeScript config
Primary API pattern using next-safe-action with Zod validation:
Location: /apps/nexploy/src/actions/**/*.action.ts
Pattern:
export const myAction = authActionServer
.inputSchema(mySchema)
.action(async ({ parsedInput, ctx }) => {
// ctx.user - authenticated user
// parsedInput - validated input
});Middleware chain: Error handling → Authentication → Session context
Rule: Server actions are for mutations only (POST/PUT/DELETE). GET operations MUST use Next.js API routes.
- Server actions → create, update, delete, trigger side effects
- Next.js API routes (
/app/api/) → all read/GET operations (fetching data on demand from client components)
API route pattern (/apps/nexploy/src/app/api/**/*.ts):
export const GET = route
.use(authRouteServer)
.use(requirePermission('resource', 'read'))
.handler(async (request, { params }) => {
const { id } = await params;
// ...
return NextResponse.json(data);
});Client-side call: fetch('/api/my-resource/${id}') instead of a server action.
Client-side (Zustand + SSE):
- Location:
/apps/nexploy/src/stores/** - Pattern: Zustand stores connected to SSE via
SSEMultiplexer - Real-time sync: Docker state → SSE → Zustand → React re-render
- Example stores:
useContainersStore,useDockerStore,useRequestsStore
Server-side (State Managers):
- Location:
/apps/docker-api/src/managers/** - Base class:
BaseStateManagerwith polling/reconnect logic - Pattern: In-memory Map + Event emitter + Docker event listener
- Examples:
containersStateManager,imagesStateManager,traefikLogsManager
SSE Multiplexer:
- Single EventSource connection multiplexes multiple channels
- URL pattern:
/api/events/multiplexed?channels=containers,images,docker - Server maintains WebSocket-to-REST proxy for Docker terminal access
- Custom WebSocket routing in
server.tsproxies to docker-api
nexploy (Next.js):
- Server Actions: Primary pattern for mutations
- API Routes:
/apps/nexploy/src/app/api/**/api/[...all]/route.ts- Better Auth endpoints/api/inngest/route.ts- Background job webhook- Webhooks for GitHub/GitLab
- SSE multiplexer for real-time updates
docker-api (Hono.js):
- REST API with route modularization
- Pattern: Manager → Route → SSE Events
- Managers poll Docker daemon and emit SSE updates
Location: /apps/nexploy/prisma/schema.prisma
Core Models:
User- Authentication (Better Auth)Repository- Git repositories to deployBuild- Build history with status tracking (QUEUED → BUILDING → DEPLOYING → COMPLETED/FAILED/CANCELLED)Log- Build logs per stepEnvVariable- Encrypted environment variables (AES-256-GCM)Session/Account/Verification/TwoFactor- Auth tables
Key Patterns:
- Single Prisma instance:
/apps/nexploy/prisma/prisma.ts - Service layer:
/apps/nexploy/src/services/**/*.service.ts - Migrations:
/apps/nexploy/prisma/migrations/ - Generated client:
/apps/nexploy/generated/client/
Implementation: /apps/nexploy/src/lib/auth/auth.ts
Features:
- Email/password + OAuth (GitHub, GitLab)
- Two-factor authentication (TOTP) with backup codes
- Admin plugin for user management
- Session-based with cookie auth
Authorization:
- Server Action middleware:
authActionServerwrapper - Session context passed to authenticated actions
- OAuth token refresh via
getValidToken()
Security:
- Encrypted environment variables (AES-256-GCM) - see
/apps/nexploy/src/lib/encryption.ts - Webhook secrets for Git provider callbacks
- CSRF protection via Better Auth
Location: /apps/nexploy/src/inngest/
Build Pipeline Function:
- ID:
build-pipeline - Trigger:
build/startevent - Cancellation:
build/cancelevent
Build Steps (resumable):
clone-repository- Git clone with OAuth tokenprepare-dockerfile- Copy/validate Dockerfilewrite-env-file- Create .env from encrypted variablesbuild-docker-image- Docker build via docker-api SSE streamdeploy-container- Create and start containercleanup- Remove temporary filesfinalize-logs- Mark build complete
Key Features:
- Step-by-step execution with durability
- Real-time log streaming via channels (
build:{buildId}) - Resume from any failed step (stored in
Build.lastCompletedStep) - Abort controller for cancellation
Development (docker-compose.dev.yml):
- PostgreSQL: Port 5433
- Inngest Dev Server: Port 8288
- Traefik: Ports 80 (HTTP), 8080 (dashboard)
Traefik:
- Dynamic file provider: watches
/infra/traefik/service/ - Docker provider: watches Docker socket
- Per-repository config files with routers/middlewares
- Let's Encrypt certificate resolver
WebSocket Proxy:
- Custom Next.js server handles WebSocket upgrades
- Routes:
/api/ws/docker/terminal/:containerId/:shell→ docker-api - Proxies Docker terminal/attach WebSockets
- Create/modify manager in
/apps/docker-api/src/managers/ - Add route handler in
/apps/docker-api/src/routes/ - Update frontend store in
/apps/nexploy/src/stores/ - Add UI components using shadcn/ui
- Subscribe to SSE channel in multiplexer
- Update Prisma schema if needed
- Run
pnpm --filter=nexploy db:migrate:dev - Create Zod schema in
@workspace/schemas-zod - Create server action in
/apps/nexploy/src/actions/repository/ - Create service method in
/apps/nexploy/src/services/repository.service.ts - Update UI components and forms
Environment variables are encrypted at rest:
- Encryption implementation:
/apps/nexploy/src/lib/encryption.ts - Schema:
/packages/schemas-zod/src/repository/envVariable.schema.ts - Action:
/apps/nexploy/src/actions/repository/envVariable.action.ts - Written to
.envfile during build step in Inngest
- Create function in
/apps/nexploy/src/inngest/functions/ - Register in
/apps/nexploy/src/inngest/client.ts - Trigger with
inngest.send({ name: "event/name", data: {} }) - Use
step.run()for resumable steps - Use channels for real-time updates
Never write comments in the code. Write self-explanatory code with clear naming instead. Do not add explanatory, sectioning, or TODO comments — keep the source free of comments.
User Action → Server Action → Prisma/Inngest → docker-api → Docker Daemon
↓
Docker Events → State Manager → SSE → SSEMultiplexer → Zustand → UI
Recent migration (check git history):
- "Projects" was renamed to "Repositories" across the codebase
- Search for both terms when exploring older code/migrations
The nexploy app uses a custom server (server.ts) for:
- WebSocket proxy to docker-api
- Custom middleware before Next.js request handling
- Port: 3000 (dev), configurable via PORT env var
Environment variables are encrypted using keys from:
ENCRYPTION_KEY- Main encryption key (32 bytes hex)- See
/apps/nexploy/src/lib/encryption.tsfor implementation
- Docker API must be running for full integration testing
- Use Prisma Studio to inspect database state during development
- Inngest dev server provides UI at http://localhost:8288
Use shadcn/ui components from @workspace/ui:
- Add new components:
pnpm dlx shadcn@latest add <component> -c apps/nexploy - Components placed in
/packages/ui/src/components/ - Import:
import { Button } from '@workspace/ui/components/button'
Every new user-facing text MUST be translated via next-intl. Never hardcode strings in components.
- Uses
next-intlfor i18n - Locale prefix in routes:
/[locale]/(auth|app)/... - Translations in
@workspace/i18npackage
Available languages (all must be updated):
en(English) -packages/i18n/locales/en/fr(French) -packages/i18n/locales/fr/es(Spanish) -packages/i18n/locales/es/it(Italian) -packages/i18n/locales/it/
The authoritative list is appLocales in packages/i18n/index.ts. When a new locale is added, this list in AGENTS.md must be updated too.
Translation namespaces:
common, auth, navigation, repository, docker, monitoring, integrations, account, admin, ai, notifications, requests, errors, organization, swarm
Rules:
- When adding any new text visible to users, add the translation key to the appropriate namespace JSON file in every locale listed above
- Use
useTranslations("namespace")in client components andgetTranslations("namespace")in server components - Choose the namespace that best matches the feature area. Create a new namespace only if none fit
- Keep translation keys in camelCase and logically grouped (e.g.,
"backups.create","backups.restore") - Never commit a component with hardcoded user-facing strings — always use
t("key") - docker-api translations: Important user-facing messages returned by
docker-api(error messages, status labels, notifications) must also be translated. Use the@workspace/i18npackage to ensure these texts are available in every locale - Formal address (MANDATORY): Never address the user informally in any locale. Use the formal register consistently:
fr— vouvoiement only: "vous", "votre", "vos", and the vous-form imperative ("Choisissez", "Sélectionnez"). Never "tu", "ton/ta/tes", "toi"es— usted only: "su", "sus", "usted", and the usted imperative ("Seleccione", "Introduzca", "Gestione"). Never "tú", "tu/tus", "ti", or tú imperatives ("Selecciona", "Introduce")it— Lei only: "suo/sua/suoi/sue" and the Lei imperative ("Selezioni", "Inserisca", "Gestisca"), or the impersonal infinitive for selector placeholders ("Selezionare un driver"). Never "tu", "tuo/tua/tuoi/tue", "puoi/vuoi/devi"- Email placeholders follow the same rule:
vous@exemple.com(fr),usuario@example.com(es),nome@example.com(it) - Descriptions of what a toggle or option does stay in the third person ("Muestra un contador", "Verifica se esiste già una rete") — they describe behavior, they do not address the user
- Short action labels on buttons stay as they are ("Aggiungi", "Eliminar", "Enregistrer") — they are commands the user issues, not address
OAuth scopes required:
- GitHub:
repo(full repository access) - GitLab:
api(API access) - Token refresh handled by
getValidToken()in services - Webhook configuration stored per repository
This repo lives inside a larger workspace at ../ (i.e. nexploy/), alongside sibling projects:
../nodes—@nexploy/nodes, the pipeline node library (published package, consumed here as a dependency)../shared—@nexploy/shared, shared runtime helpers (actor, Docker constants, path safety)../cli— the Nexploy CLI../agent—@nexploy/agent, the Docker agent: thenexploy/agentDocker image plus the tunnel protocol this repo imports as@nexploy/agent/protocol(published package, own release workflow). Switch it to the local checkout withpnpm agent:localand back withpnpm agent:npm../build-runner—@nexploy/build-runner, the remote build runner published asnexploy/build-runner../docs— the fumadocs documentation site../website— the marketing website
You may read from and write to these sibling repositories when a change requires it. Note that @nexploy/nodes, @nexploy/shared and @nexploy/agent are installed here as published versions, not workspace links — editing their source under ../nodes/src or ../shared/src does not affect this repo until the package is rebuilt, republished, and the dependency version bumped (or pnpm <name>:local is used). Say so explicitly when a change spans that boundary.