CLAUDE.md

Code style

• Don't write comments that restate what the code already says.
• Comment only the "why" when something isn't obvious: workarounds, counterintuitive decisions, constraints from an external API.
• No section-divider comments like // --- Helpers ---.
• Don't leave comments describing the change you just made.

Ports and certificates

Порт 80 на серверах не открываем никогда. Сертификаты обновляются только через порт 443 (tlsChallenge). Не добавлять httpChallenge и публикацию порта 80 ни в код, ни в установщик.

Builds

Build commands in services/application.ts and services/compose.ts go through createBuildRunner (packages/server/src/utils/process/build-process.ts), not execAsyncRemote directly. It adds the time budget (buildTimeoutMinutes on server and webServerSettings, default 60), timeout on the server that builds, so a build stops there even after the panel lost the connection, and the dokploy-build:<appName> marker that Kill Build and the next build of the service use to find its processes. recordBuildFailure in the same file writes the failure to the log and never stops the status update when that server is out of reach. Every ssh2 connection a deployment waits on takes SSH_KEEPALIVE.

Pull requests

Every pull request targets AgentHits-Dev, including a PR that builds on another open PR. Checks run only for that base, so a PR stacked on another branch gets none. When one PR depends on another, say so in the description; do not change the base.

Releases

One GitHub release agenthits-vX.Y.Z covers a batch of work, not a single PR (owner's decision 2026-10-27). Every push to AgentHits-Dev builds the image through .github/workflows/agenthits-release.yml (agenthits-dev, agenthits-dev-<sha12>), and panels show such a build as agenthits-vX.Y.Z-N-g<sha12>: the previous release plus N commits. A push cuts the release once 20 PRs (RELEASE_EVERY, first-parent commits) have been merged since the previous release; to release a finished batch sooner, run gh workflow run agenthits-release.yml --repo TaskFlow-Systems/dokploy --ref AgentHits-Dev. Several PRs that belong together can also be merged as one combined PR. The agenthits- prefix keeps fork tags apart from upstream Dokploy v0.x tags. The version goes up by patch, by minor when a PR title in the batch starts with feat, and by major only through a manual run with bump: major. The release notes are the title and body of every PR merged since the previous release, so write each PR description for someone reading the release. The image of a release is ghcr.io/agenthits/dokploy:agenthits-vX.Y.Z and panels show that tag as the fork version; agenthits-dev always points at the newest build. After the GitHub release is published, .github/workflows/agenthits-stable-tag.yml points agenthits-stable at the release's manifest (same digest, no rebuild); the panel's Update follows agenthits-stable and never offers a release older than the running build. A manual run of that workflow with an older release moves the channel back; DOKPLOY_AGENTHITS_UPDATE_TAG=agenthits-dev on a panel's service makes it follow every build. install-agenthits.sh and update.sh still default to agenthits-dev. .github/workflows/agenthits-ghcr-retention.yml deletes old GHCR versions of both packages (the panel and monitoring) weekly but never a release tag, agenthits-dev, agenthits-stable or buildcache.

The servers' dokploy-monitoring service runs the fork's own image ghcr.io/agenthits/dokploy-monitoring:agenthits-dev (monitoring-setup.ts), not upstream's dokploy/monitoring. .github/workflows/agenthits-monitoring-image.yml builds it from Dockerfile.monitoring for amd64 and arm64 on pushes to AgentHits-Dev that touch apps/monitoring/** or Dockerfile.monitoring, checks that it pulls without a login and scans it. A server gets a new build only when its monitoring settings are saved again; DOKPLOY_MONITORING_IMAGE on the panel's service overrides the image. docs/server-components-update.md has the details.

Dependencies

.github/workflows/deps-auto-update.yml runs every day at 03:00 UTC (manually: gh workflow run deps-auto-update.yml --repo TaskFlow-Systems/dokploy --ref AgentHits-Dev). It runs bun update --recursive within the package.json ranges (minor and patch, direct and transitive packages, versions at least one day old), then bun audit, and keeps one PR зависимости: автообновление библиотек from deps/auto-update into AgentHits-Dev, rebuilt daily until it is merged. It starts pull-request.yml on the branch through workflow_dispatch; judge the PR by that run. It never merges. The same workflow runs in the owner's other projects; it replaced Dependabot for Bun, which moves only direct dependencies. It needs "Allow GitHub Actions to create and approve pull requests" in the repo's Actions settings.

• Held packages stay pinned to exact versions (better-auth, @better-auth/*, better-call, @better-fetch/fetch, stripe, @stepperize/react, @dokploy/trpc-openapi) or ~ (ssh2), in their package.json and in the root overrides, so the workflow does not move them. Keep new holds pinned the same way.
• Every other root override is a range >=<fixed version> <next major> (for 0.x, <next minor>), so the override keeps the fixed floor and the workflow still moves the package. A security override follows the same form; an exact version there freezes the package and can silently override a newer direct dependency.
• A package that packages/server and an app both declare takes the same range in both (@trpc/server, undici). With an exact version on one side and a range on the other, the daily update moves only the range and the lockfile keeps two copies; instanceof across them then fails, as a TRPCError thrown in packages/server did in the router tests.
• Major updates are done by hand, one PR each (the dokploy-upgrader agent), with bun add <pkg>@<ver> --minimum-release-age=86400.
• The one-day age is minimumReleaseAge in bunfig.toml and MIN_RELEASE_AGE in the workflow; change both together.
• A commit pushed to the branch of the open PR stops its daily rebuild until the PR is merged or closed.
• .github/workflows/dependency-audit.yml runs bun audit every Monday for advisories published between updates.
• bun audit does not see the image. Trivy scans the published agenthits-dev image and the pinned Traefik, Postgres and Redis images every Monday (.github/workflows/image-audit.yml), each agenthits-dev-<sha12> build once the release workflow has pushed it (same workflow), and the image a PR builds (bun-migration-docker-check.yml). All of them run .github/scripts/trivy-image-scan.sh, which writes the findings to the job summary, and fail on critical and high findings that have a fix in Debian packages, in the Go binaries of the bundled tools (Docker CLI, rclone, Railpack, pack) or in npm packages inside the image. .trivyignore.yaml holds findings whose latest tool release still carries them; each entry expires, so the audit fails again and the tool gets rechecked. Trivy is pinned by digest in both workflows; move them together. The organization's self-hosted Linux runners take no public repositories, so these scans run on GitHub-hosted runners.