mirror of
https://github.com/caddyserver/website.git
synced 2025-04-21 20:46:15 -04:00
restructure the "build from source" page (#370)
* restructure the "build from source" page * partially address feedback * address feedback * Polishing, more cross-linking, update Docker Compose --------- Co-authored-by: Francis Lavoie <lavofr@gmail.com>
This commit is contained in:
Mohammed Al Sahaf
GitHub
parent
a57d9e3ea2
commit
6882c88152
3 changed files with 81 additions and 44 deletions
|
|
@ -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:
|
||||
|
||||
<pre><code class="cmd bash">git clone "https://github.com/caddyserver/caddy.git"</code></pre>
|
||||
|
|
@ -26,6 +41,17 @@ Due to [a bug in Go](https://github.com/golang/go/issues/29228), these basic ste
|
|||
|
||||
</aside>
|
||||
|
||||
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:
|
||||
|
||||
<pre><code class="cmd bash">GOOS=windows go build</code></pre>
|
||||
|
||||
Or similarly for Linux ARMv6 when you're not on Linux or on ARMv6:
|
||||
|
||||
<pre><code class="cmd bash">GOOS=linux GOARCH=arm GOARM=6 go build</code></pre>
|
||||
|
||||
|
||||
|
||||
## 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:
|
||||
|
||||
<pre><code class="cmd bash">GOOS=windows go build</code></pre>
|
||||
|
||||
Or similarly for Linux ARMv6 when you're not on Linux or on ARMv6:
|
||||
|
||||
<pre><code class="cmd bash">GOOS=linux GOARCH=arm GOARM=6 go build</code></pre>
|
||||
|
||||
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:
|
||||
|
||||
<pre><code class="cmd bash">GOOS=darwin xcaddy build</code></pre>
|
||||
|
||||
|
||||
|
||||
## Docker
|
||||
|
||||
You can use the `:builder` image as a short-cut to building a new Caddy binary with custom modules:
|
||||
|
||||
```Dockerfile
|
||||
FROM caddy:<version>-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:<version>
|
||||
|
||||
COPY --from=builder /usr/bin/caddy /usr/bin/caddy
|
||||
```
|
||||
|
||||
Make sure to replace `<version>` 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:
|
||||
<pre><code class="cmd"><span class="bash">sudo dpkg-divert --divert /usr/bin/caddy.default --rename /usr/bin/caddy</span>
|
||||
|
|
@ -88,13 +127,16 @@ Procedure:
|
|||
<span class="bash">sudo systemctl restart caddy</span>
|
||||
</code></pre>
|
||||
|
||||
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
|
||||
<pre><code class="cmd bash">update-alternatives --config caddy</code></pre>
|
||||
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.
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
||||
|
|
|
|||
|
|
@ -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"
|
||||
```
|
||||
<pre><code class="cmd bash">sc.exe create caddy start= auto binPath= "YOURPATH\caddy.exe run"</code></pre>
|
||||
|
||||
(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
|
||||
```
|
||||
<pre><code class="cmd bash">sc.exe start caddy</code></pre>
|
||||
|
||||
To stop:
|
||||
|
||||
```
|
||||
sc.exe stop caddy
|
||||
```
|
||||
<pre><code class="cmd bash">sc.exe stop caddy</code></pre>
|
||||
|
||||
|
||||
### 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:<version>
|
||||
|
|
@ -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
|
|||
|
||||
</aside>
|
||||
|
||||
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:
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue