From 83482f5f7391f77149f4a84ff448755241e6e007 Mon Sep 17 00:00:00 2001
From: Employee 427 <test@posthog.com>
Date: Tue, 21 Apr 2026 17:06:59 +0000
Subject: [PATCH] docs: expand Build from source with run, lint, and test
 details
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Adds guidance to the top-level README's "Build from source → For
development" section so that a reader who just ran `go build` has a
path to actually running, testing, and linting the result:

- Show `./caddy version` and `./caddy run --config ...` after the
  build fence, and point at `./caddy help` / command-line docs
- Note macOS and Windows equivalents alongside the Linux setcap tip
- Mention the race-detector test run used by CI and the existing
  integration tests under caddytest/
- Document the repo's existing .golangci.yml and .pre-commit-config.yaml
  so contributors can discover and install them

No code or config is changed; only README.md.

Generated-By: PostHog Code
Task-Id: 4831e9d8-43a6-499c-8515-78be49215c18
---
 README.md | 15 +++++++++++++++
 1 file changed, 15 insertions(+)

diff --git a/README.md b/README.md
index 508352c5620..9032d43e7fd 100644
--- a/README.md
+++ b/README.md
@@ -117,8 +117,19 @@ $ cd caddy/cmd/caddy/
 $ go build
 ```
 
+Once built, you can verify the binary and run it against a config file:
+
+```bash
+$ ./caddy version
+$ ./caddy run --config /path/to/Caddyfile
+```
+
+`caddy run` runs in the foreground and blocks until stopped. For the full list of commands (including `start`, `stop`, `reload`, and `validate`), run `./caddy help` or see the [command-line docs](https://caddyserver.com/docs/command-line).
+
 When you run Caddy, it may try to bind to low ports unless otherwise specified in your config. If your OS requires elevated privileges for this, you will need to give your new binary permission to do so. On Linux, this can be done easily with: `sudo setcap cap_net_bind_service=+ep ./caddy`
 
+On macOS there is no `setcap` equivalent; either bind to ports ≥ 1024 in development, or run Caddy with `sudo`. On Windows no capability flag is needed, though you may be prompted for admin privileges or firewall approval the first time Caddy listens on a new port.
+
 If you prefer to use `go run` which only creates temporary binaries, you can still do this with the included `setcap.sh` like so:
 
 ```bash
@@ -140,6 +151,10 @@ $ go test ./...
 $ go test ./modules/caddyhttp/tracing/
 ```
 
+CI runs the suite with the race detector; you can do the same locally with `go test -race ./...`. Integration tests that exercise a running Caddy server live under [`caddytest/`](caddytest/) and run as part of `go test ./...`.
+
+This repo ships a [`.golangci.yml`](.golangci.yml) config, so [`golangci-lint run`](https://golangci-lint.run/) will lint the codebase with the project's preferred settings. A [`.pre-commit-config.yaml`](.pre-commit-config.yaml) is also provided — install [pre-commit](https://pre-commit.com/) and run `pre-commit install` once to wire up the hooks (gitleaks, golangci-lint, shellcheck, and whitespace/EOF fixers) so they run automatically on each commit.
+
 ### With version information and/or plugins
 
 Using [our builder tool, `xcaddy`](https://github.com/caddyserver/xcaddy)...