diff --git a/src/docs/markdown/build.md b/src/docs/markdown/build.md index 78429bf..5bd222f 100644 --- a/src/docs/markdown/build.md +++ b/src/docs/markdown/build.md @@ -4,10 +4,25 @@ title: "Build from source" # Build from source +There are multiple options for building Caddy, if you need a customized build (e.g. with plugins): +- [Git](#git): Build from Git repo +- [`xcaddy`](#xcaddy): Build using `xcaddy` +- [Docker](#docker): Build a custom Docker image + Requirements: - [Go](https://golang.org/doc/install) 1.20 or newer +The [Package Support Files](#package-support-files-for-custom-builds-for-debianubunturaspbian) section contains instructions for users who installed Caddy using the APT command on Debian-derivative system yet need the custom build executable for their operations. + + + +## Git + +Requirements: + +- Go installed (see above) + Clone the repository: 
git clone "https://github.com/caddyserver/caddy.git"
@@ -26,6 +41,17 @@ Due to [a bug in Go](https://github.com/golang/go/issues/29228), these basic ste +Go programs are easy to compile for other platforms. Just set the `GOOS`, `GOARCH`, and/or `GOARM` environment variables that are different. ([See the go documentation for details.](https://golang.org/doc/install/source#environment)) + +For example, to compile Caddy for Windows when you're not on Windows: + +
GOOS=windows go build
+ +Or similarly for Linux ARMv6 when you're not on Linux or on ARMv6: + +
GOOS=linux GOARCH=arm GOARM=6 go build
+ + ## xcaddy @@ -34,7 +60,7 @@ The [`xcaddy` command](https://github.com/caddyserver/xcaddy) is the easiest way Requirements: - Go installed (see above) -- Make sure [`xcaddy`](https://github.com/caddyserver/xcaddy/releases) is in your PATH +- Make sure [`xcaddy`](https://github.com/caddyserver/xcaddy/releases) is in your `PATH` You do **not** need to download the Caddy source code (it will do that for you). @@ -50,25 +76,38 @@ To build with plugins, use `--with`: As you can see, you can customize the versions of plugins with `@` syntax. Versions can be a tag name, commit SHA, or branch. -Cross-platform compilation with `xcaddy` works the same as with the `go` command (see below). - - -## Cross-platform - -Go programs are easy to compile for other platforms. Just set the `GOOS`, `GOARCH`, and/or `GOARM` environment variables that are different. ([See the go documentation for details.](https://golang.org/doc/install/source#environment)) - -For example, to compile Caddy for Windows when you're not on Windows: - -
GOOS=windows go build
- -Or similarly for Linux ARMv6 when you're not on Linux or on ARMv6: - -
GOOS=linux GOARCH=arm GOARM=6 go build
- -The same works for `xcaddy`. To cross-compile for macOS: +Cross-platform compilation with `xcaddy` works the same as with the `go` command. For example, to cross-compile for macOS: 
GOOS=darwin xcaddy build
+ + +## Docker + +You can use the `:builder` image as a short-cut to building a new Caddy binary with custom modules: + +```Dockerfile +FROM caddy:-builder AS builder + +RUN xcaddy build \ + --with github.com/caddyserver/nginx-adapter \ + --with github.com/hairyhenderson/caddy-teapot-module@v0.0.3-0 + +FROM caddy: + +COPY --from=builder /usr/bin/caddy /usr/bin/caddy +``` + +Make sure to replace `` with the latest version of Caddy to start. + +Note the second `FROM` instruction — this produces a much smaller image by simply overlaying the newly-built binary on top of the regular `caddy` image. + +The builder uses `xcaddy` to Caddy with the provided modules, similar to the process [outlined above](#xcaddy). + +To use Docker Compose, see our recommended [`compose.yml`](/docs/running#docker-compose) and usage instructions. + + + ## Package support files for custom builds for Debian/Ubuntu/Raspbian This procedure aims to simplify running custom `caddy` binaries while keeping support files from the `caddy` package. @@ -76,9 +115,9 @@ This procedure aims to simplify running custom `caddy` binaries while keeping su This procedure allows users to take advantage of the default configuration, systemd service files and bash-completion from the official package. Requirements: -- Install `caddy` package according to these [instructions](/docs/install#debian-ubuntu-raspbian) -- Build your custom `caddy` binary according to the procedure listed in this document. (see above) -- Your custom `caddy` binary should be located in the current directory. +- Install the `caddy` package according to [these instructions](/docs/install#debian-ubuntu-raspbian) +- Build your custom `caddy` binary (see above sections), or [download](/download) a custom build +- Your custom `caddy` binary should be located in the current directory Procedure: 
sudo dpkg-divert --divert /usr/bin/caddy.default --rename /usr/bin/caddy
@@ -88,13 +127,16 @@ Procedure:
 sudo systemctl restart caddy
+Explanation: -`dpkg-divert` will move `/usr/bin/caddy` binary to `/usr/bin/caddy.default` and put a diversion in place in case any package want to install a file to this location. +- `dpkg-divert` will move `/usr/bin/caddy` binary to `/usr/bin/caddy.default` and put a diversion in place in case any package want to install a file to this location. -`update-alternatives` will create a symlink from the desired caddy binary to `/usr/bin/caddy` +- `update-alternatives` will create a symlink from the desired caddy binary to `/usr/bin/caddy` -`systemctl restart caddy` will shut down the default version of the Caddy server and start the custom one. +- `systemctl restart caddy` will shut down the default version of the Caddy server and start the custom one. + +You can change between the custom and default `caddy` binaries by executing the below, and following the on screen information. Then, restart the Caddy service. -You can change between the custom and default `caddy` binaries by executing 
update-alternatives --config caddy
-and following the on screen information, then restarting the Caddy service. + +To upgrade Caddy after this point, you may run [`caddy upgrade`](/docs/command-line#caddy-upgrade). This attempts to [download](/download) a build with the same plugins as your current build, with the latest version of Caddy, then replace the current binary with the new one. diff --git a/src/docs/markdown/metrics.md b/src/docs/markdown/metrics.md index a26c606..8dacd25 100644 --- a/src/docs/markdown/metrics.md +++ b/src/docs/markdown/metrics.md @@ -11,10 +11,9 @@ In other words, you're going to want to be able to _monitor_ Caddy. ## Enabling metrics -You'll need to turn metrics on. If using a Caddyfile, enable metrics [in global options](/docs/caddyfile/options#metrics): +You'll need to turn metrics on. -> **Note** -> Caddy 2.6 made metrics opt-in. To enable them, use either [Caddyfile global options](/docs/caddyfile/options#metrics) or [the `metrics` parameter](/docs/json/apps/http/servers/metrics/) of a server's JSON config. +If using a Caddyfile, enable metrics [in global options](/docs/caddyfile/options#metrics): ```caddy { @@ -24,7 +23,7 @@ You'll need to turn metrics on. If using a Caddyfile, enable metrics [in global } ``` -If using JSON, enable metrics in your [server configuration](/docs/json/apps/http/servers/) by adding `"metrics": {}`. +If using JSON, add `"metrics": {}` to your [`apps > http > servers` configuration](/docs/json/apps/http/servers/). ## Prometheus diff --git a/src/docs/markdown/running.md b/src/docs/markdown/running.md index b6ec3b5..af2c31a 100644 --- a/src/docs/markdown/running.md +++ b/src/docs/markdown/running.md @@ -188,29 +188,23 @@ To tag the `caddy` binary, you can use the following command: ## Windows service -There are two ways to run Caddy as a service on Windows: sc.exe or WinSW. +There are two ways to run Caddy as a service on Windows: [sc.exe](#scexe) or [WinSW](#winsw). ### sc.exe To create the service, run: -``` -sc.exe create caddy start= auto binPath= "YOURPATH\caddy.exe run" -``` +
sc.exe create caddy start= auto binPath= "YOURPATH\caddy.exe run"
-(replace YOURPATH with the actual path to your `caddy.exe`) +(replace `YOURPATH` with the actual path to your `caddy.exe`) To start: -``` -sc.exe start caddy -``` +
sc.exe start caddy
To stop: -``` -sc.exe stop caddy -``` +
sc.exe stop caddy
### WinSW @@ -270,11 +264,9 @@ This assumes you're using [Docker Compose V2](https://docs.docker.com/compose/re ### Setup -First, create a file `docker-compose.yml` (or add this service to your existing file): +First, create a file `compose.yml` (or add this service to your existing file): ```yaml -version: "3.9" - services: caddy: image: caddy: @@ -304,7 +296,7 @@ What this does: - Bind mounts the `site` directory to serve your site's static files from `/srv`. - Named volumes for `/data` and `/config` to [persist important information](/docs/conventions#file-locations). -Then, create a file named `Caddyfile` beside the `docker-compose.yml`, and write your [Caddyfile](/docs/caddyfile/concepts) configuration. +Then, create a file named `Caddyfile` beside the `compose.yml`, and write your [Caddyfile](/docs/caddyfile/concepts) config. If you have static files to serve, you may place them in a `site/` directory beside the configs, then set the [`root`](/docs/caddyfile/directives/root) using `root * /srv`. If you don't, then you may remove the `/srv` volume mount. @@ -314,6 +306,10 @@ If you're using Caddy to [reverse proxy](/docs/caddyfile/directives/reverse_prox +If you need a custom build of Caddy with plugins, follow the [Docker build instructions](/docs/build#docker) to create a custom Docker image. Create the `Dockerfile` beside your `compose.yml`, then replace the `image:` line in your `compose.yml` with `build: .` instead. + + + ### Usage Then, you can start the container: