mirror of
https://github.com/caddyserver/xcaddy.git
synced 2024-11-03 07:50:30 +00:00
dabafeef18
When I first wrote xcaddy I was on macOS which does not require permission to bind to low ports. Now I'm on Linux. The XCADDY_SETCAP env var will cause xcaddy to run setcap on the generated temporary binary before executing it so that it can bind to low ports. This requires sudo.
133 lines
3.9 KiB
Markdown
133 lines
3.9 KiB
Markdown
`xcaddy` - Custom Caddy Builder
|
|
===============================
|
|
|
|
This command line tool and associated Go package makes it easy to make custom builds of the [Caddy Web Server](https://github.com/caddyserver/caddy).
|
|
|
|
It is used heavily by Caddy plugin developers as well as anyone who wishes to make custom `caddy` binaries (with or without plugins).
|
|
|
|
⚠️ Still in development. Supports Caddy 2 only.
|
|
|
|
Stay updated, be aware of changes, and please submit feedback! Thanks!
|
|
|
|
## Requirements
|
|
|
|
- [Go installed](https://golang.org/doc/install)
|
|
|
|
## Install
|
|
|
|
You can [download binaries](https://github.com/caddyserver/xcaddy/releases) that are already compiled for your platform, or build `xcaddy` from source:
|
|
|
|
```bash
|
|
$ go get -u github.com/caddyserver/xcaddy/cmd/xcaddy
|
|
```
|
|
|
|
|
|
## Command usage
|
|
|
|
The `xcaddy` command has two primary uses:
|
|
|
|
1. Compile custom `caddy` binaries
|
|
2. A replacement for `go run` while developing Caddy plugins
|
|
|
|
The `xcaddy` command will use the latest version of Caddy by default. You can customize this for all invocations by setting the `CADDY_VERSION` environment variable.
|
|
|
|
As usual with `go` command, the `xcaddy` command will pass the `GOOS`, `GOARCH`, and `GOARM` environment variables through for cross-compilation.
|
|
|
|
|
|
### Custom builds
|
|
|
|
Syntax:
|
|
|
|
```
|
|
$ xcaddy build [<caddy_version>]
|
|
[--output <file>]
|
|
[--with <module[@version][=replacement]>...]
|
|
```
|
|
|
|
- `<caddy_version>` is the core Caddy version to build; defaults to `CADDY_VERSION` env variable or latest.
|
|
- `--output` changes the output file.
|
|
- `--with` can be used multiple times to add plugins by specifying the Go module name and optionally its version, similar to `go get`. Module name is required, but specific version and/or local replacement are optional.
|
|
|
|
Examples:
|
|
|
|
```bash
|
|
$ xcaddy build \
|
|
--with github.com/caddyserver/ntlm-transport
|
|
|
|
$ xcaddy build v2.0.1 \
|
|
--with github.com/caddyserver/ntlm-transport@v0.1.1
|
|
|
|
$ xcaddy build \
|
|
--with github.com/caddyserver/ntlm-transport=../../my-fork
|
|
|
|
$ xcaddy build \
|
|
--with github.com/caddyserver/ntlm-transport@v0.1.1=../../my-fork
|
|
```
|
|
|
|
You can even replace Caddy core using the `--with` flag:
|
|
|
|
```
|
|
$ xcaddy build \
|
|
--with github.com/caddyserver/caddy/v2=../../my-caddy-fork
|
|
```
|
|
|
|
This allows you to hack on Caddy core (and optionally plug in extra modules at the same time!) with relative ease.
|
|
|
|
### For plugin development
|
|
|
|
If you run `xcaddy` from within the folder of the Caddy plugin you're working on _without the `build` subcommand_, it will build Caddy with your current module and run it, as if you manually plugged it in and invoked `go run`.
|
|
|
|
The binary will be built and run from the current directory, then cleaned up.
|
|
|
|
The current working directory must be inside an initialized Go module.
|
|
|
|
Syntax:
|
|
|
|
```
|
|
$ xcaddy <args...>
|
|
```
|
|
- `<args...>` are passed through to the `caddy` command.
|
|
|
|
For example:
|
|
|
|
```bash
|
|
$ xcaddy list-modules
|
|
$ xcaddy run
|
|
$ xcaddy run --config caddy.json
|
|
```
|
|
|
|
The race detector can be enabled by setting `XCADDY_RACE_DETECTOR=1`.
|
|
|
|
|
|
## Library usage
|
|
|
|
```go
|
|
builder := xcaddy.Builder{
|
|
CaddyVersion: "v2.0.0",
|
|
Plugins: []xcaddy.Dependency{
|
|
{
|
|
ModulePath: "github.com/caddyserver/ntlm-transport",
|
|
Version: "v0.1.1",
|
|
},
|
|
},
|
|
}
|
|
err := builder.Build(context.Background(), "./caddy")
|
|
```
|
|
|
|
Versions can be anything compatible with `go get`.
|
|
|
|
|
|
|
|
## Environment variables
|
|
|
|
Because the subcommands and flags are constrained to benefit rapid plugin prototyping, xcaddy does read some environment variables to take cues for its behavior and/or configuration when there is no room for flags.
|
|
|
|
- `CADDY_VERSION` sets the version of Caddy to build.
|
|
- `XCADDY_RACE_DETECTOR=1` enables the Go race detector in the build.
|
|
- `XCADDY_SKIP_CLEANUP=1` causes xcaddy to leave build artifacts on disk after exiting.
|
|
- `XCADDY_SETCAP=1` will run `sudo setcap cap_net_bind_service=+ep` on the temporary binary before running it when in dev mode.
|
|
|
|
---
|
|
|
|
© 2020 Matthew Holt
|