Skip to content

docs: expand Build from source with run, lint, and test details #16

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
ryans-posthog wants to merge 1 commit into from
Closed

docs: expand Build from source with run, lint, and test details #16

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 15 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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)...
Expand Down
Loading