mirror of
https://github.com/caddyserver/website.git
synced 2025-04-21 12:36:16 -04:00
docs: Expand install into multiple pages; add example to header docs
This commit is contained in:
Matthew Holt
parent
a03de998ef
commit
d3c420e5f2
9 changed files with 162 additions and 72 deletions
66
src/docs/markdown/build.md
Normal file
66
src/docs/markdown/build.md
Normal file
|
|
@ -0,0 +1,66 @@
|
|||
---
|
||||
title: "Build from source"
|
||||
---
|
||||
|
||||
# Build from source
|
||||
|
||||
Requirements:
|
||||
|
||||
- [Go](https://golang.org/dl) 1.14 or newer
|
||||
|
||||
Clone the repository:
|
||||
|
||||
<pre><code class="cmd bash">git clone "https://github.com/caddyserver/caddy.git"</code></pre>
|
||||
|
||||
If you don't have git, you can download the source code as a file archive [from GitHub](https://github.com/caddyserver/caddy). Each [release](https://github.com/caddyserver/caddy/releases) also has source snapshots.
|
||||
|
||||
Build:
|
||||
|
||||
<pre><code class="cmd"><span class="bash">cd caddy/cmd/caddy/</span>
|
||||
<span class="bash">go build</span></code></pre>
|
||||
|
||||
<aside class="tip">
|
||||
Due to <a href="https://github.com/golang/go/issues/29228">a bug in Go</a>, these basic steps do not embed version information. If you want the version (<code>caddy version</code>), you need to compile Caddy as a dependency rather than as the main module. Instructions for this are in Caddy's <a href="https://github.com/caddyserver/caddy/blob/master/cmd/caddy/main.go">main.go</a> file. Or, you can use <b>xcaddy</b> which automates this.
|
||||
</aside>
|
||||
|
||||
## xcaddy
|
||||
|
||||
The [`xcaddy` command](https://github.com/caddyserver/xcaddy) is the easiest way to build Caddy with version information and/or plugins.
|
||||
|
||||
Requirements:
|
||||
|
||||
- Go installed (see above)
|
||||
- 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).
|
||||
|
||||
Then building Caddy (with version information) is as easy as:
|
||||
|
||||
<pre><code class="cmd bash">xcaddy build</code></pre>
|
||||
|
||||
To build with plugins, use `--with`:
|
||||
|
||||
<pre><code class="cmd bash">xcaddy build \
|
||||
--with github.com/caddyserver/nginx-adapter
|
||||
--with github.com/caddyserver/ntlm-transport@v0.1.1</code></pre>
|
||||
|
||||
As you can see, you can customize the versions of plugins with `@` syntax. Versions can be a tag name or commit SHA.
|
||||
|
||||
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:
|
||||
|
||||
<pre><code class="cmd bash">GOOS=darwin xcaddy build</code></pre>
|
||||
|
|
@ -65,4 +65,13 @@ header {
|
|||
# keep referrer data off of HTTP connections
|
||||
Referrer-Policy no-referrer-when-downgrade
|
||||
}
|
||||
```
|
||||
```
|
||||
|
||||
Multiple header directives that are intended to be mutually-exclusive:
|
||||
|
||||
```
|
||||
route {
|
||||
header Cache-Control max=age=3600
|
||||
header /static/* Cache-Control max=age=31536000
|
||||
}
|
||||
```
|
||||
|
|
|
|||
60
src/docs/markdown/download.md
Normal file
60
src/docs/markdown/download.md
Normal file
|
|
@ -0,0 +1,60 @@
|
|||
---
|
||||
title: "Download Caddy"
|
||||
---
|
||||
|
||||
# Download Caddy
|
||||
|
||||
All our [official distributions](https://github.com/caddyserver/dist) come with only the standard modules. If you need third-party plugins, [build from source with xcaddy](/docs/build#xcaddy).
|
||||
|
||||
|
||||
|
||||
## Static binaries
|
||||
|
||||
You can **[download Caddy from GitHub](https://github.com/caddyserver/caddy/releases)**, where new releases are immediately published.
|
||||
|
||||
Using `curl`:
|
||||
|
||||
<pre><code class="cmd"><span class="bash">curl -OL "https://github.com/caddyserver/caddy/releases/latest/download/ASSET"</span></code></pre>
|
||||
|
||||
Using `wget`:
|
||||
|
||||
<pre><code class="cmd"><span class="bash">wget "https://github.com/caddyserver/caddy/releases/latest/download/ASSET"</span></code></pre>
|
||||
|
||||
|
||||
## Docker
|
||||
|
||||
<pre><code class="cmd bash">docker pull caddy</code></pre>
|
||||
|
||||
[**View on Docker Hub**](https://hub.docker.com/_/caddy)
|
||||
|
||||
|
||||
## Debian, Ubuntu, Raspbian
|
||||
|
||||
<pre><code class="cmd"><span class="bash">echo "deb [trusted=yes] https://apt.fury.io/caddy/ /" \
|
||||
| sudo tee -a /etc/apt/sources.list.d/caddy-fury.list</span>
|
||||
<span class="bash">sudo apt update</span>
|
||||
<span class="bash">sudo apt install caddy</span></code></pre>
|
||||
|
||||
Installing this package automatically starts and runs Caddy for you.
|
||||
|
||||
|
||||
## Fedora, RedHat, CentOS
|
||||
|
||||
Fedora or RHEL/CentOS 8:
|
||||
|
||||
<pre><code class="cmd"><span class="bash">dnf install 'dnf-command(copr)'</span>
|
||||
<span class="bash">dnf copr enable @caddy/caddy</span>
|
||||
<span class="bash">dnf install caddy</span></code></pre>
|
||||
|
||||
RHEL/CentOS 7:
|
||||
|
||||
<pre><code class="cmd"><span class="bash">yum install yum-plugin-copr</span>
|
||||
<span class="bash">yum copr enable @caddy/caddy</span>
|
||||
<span class="bash">yum install caddy</span></code></pre>
|
||||
|
||||
[**View the Caddy COPR**](https://copr.fedorainfracloud.org/coprs/g/caddy/caddy/)
|
||||
|
||||
|
||||
## DigitalOcean
|
||||
|
||||
[**Deploy a Caddy droplet on DigitalOcean**](https://marketplace.digitalocean.com/apps/caddy)
|
||||
|
|
@ -26,6 +26,8 @@ Welcome to Caddy! This tutorial will explore the basics of using Caddy and help
|
|||
|
||||
---
|
||||
|
||||
**If you [installed Caddy](/docs/download) from a package manager, Caddy might already be running as a service. If so, please stop the service before doing this tutorial.**
|
||||
|
||||
Let's start by running it:
|
||||
|
||||
<pre><code class="cmd bash">caddy</code></pre>
|
||||
|
|
@ -166,16 +168,16 @@ The Caddyfile seems easier than JSON, but should you always use it? There are pr
|
|||
|
||||
JSON | Caddyfile
|
||||
-----|----------
|
||||
Ubiquitous | Niche
|
||||
Full range of Caddy functionality | Most common parts of Caddy functionality
|
||||
Easy to generate | Easy to craft by hand
|
||||
Easily programmable | Difficult to automate
|
||||
Full range of Caddy functionality | Most common parts of Caddy functionality
|
||||
Extremely expressive | Moderately expressive
|
||||
Allows config traversal | Cannot traverse within Caddyfile
|
||||
Partial config changes | Whole config changes only
|
||||
Can be exported | Cannot be exported
|
||||
Compatible with all API endpoints | Compatible with some API endpoints
|
||||
Documentation generated automatically | Documentation is hand-written
|
||||
Ubiquitous | Niche
|
||||
More efficient | More computational
|
||||
Kind of boring | Kind of fun
|
||||
**Learn more: [JSON structure](/docs/json/)** | **Learn more: [Caddyfile docs](/docs/caddyfile)**
|
||||
|
|
|
|||
|
|
@ -4,46 +4,18 @@ title: "Install"
|
|||
|
||||
# Install
|
||||
|
||||
Caddy is available for every platform as a [static binary](https://github.com/caddyserver/caddy/releases) (it has no dependencies). You can also [build from source](#build-from-source) to customize your build.
|
||||
|
||||
|
||||
## Official packages
|
||||
|
||||
We maintain [official distributions](https://github.com/caddyserver/dist) for the following platforms:
|
||||
|
||||
### Docker
|
||||
|
||||
<pre><code class="cmd bash">docker pull caddy</code></pre>
|
||||
|
||||
[**View on Docker Hub**](https://hub.docker.com/_/caddy)
|
||||
|
||||
|
||||
### Debian, Ubuntu, Raspbian
|
||||
|
||||
<pre><code class="cmd"><span class="bash">echo "deb [trusted=yes] https://apt.fury.io/caddy/ /" \
|
||||
| sudo tee -a /etc/apt/sources.list.d/caddy-fury.list</span>
|
||||
<span class="bash">sudo apt update</span>
|
||||
<span class="bash">sudo apt install caddy</span></code></pre>
|
||||
|
||||
|
||||
### Fedora, RedHat, CentOS
|
||||
|
||||
Read how to [**install the Caddy COPR**](https://copr.fedorainfracloud.org/coprs/g/caddy/caddy/).
|
||||
|
||||
|
||||
### DigitalOcean
|
||||
|
||||
[**Create a Caddy droplet**](https://marketplace.digitalocean.com/apps/caddy) and get started in 90 seconds.
|
||||
This page describes how to manually install Caddy as a service.
|
||||
|
||||
<aside class="tip">
|
||||
If you <a href="/docs/download">downloaded Caddy</a> using a package manager such as <code>apt</code> or <code>dnf</code>, then Caddy is already installed, and you should jump to <a href="/docs/getting-started">Getting Started</a>.
|
||||
</aside>
|
||||
|
||||
|
||||
## Linux service
|
||||
|
||||
This section describes how to manually install Caddy as a Linux service.
|
||||
|
||||
Requirements:
|
||||
|
||||
- `caddy` binary that you downloaded or built from source
|
||||
- `caddy` binary that you [downloaded](/docs/download) or [built from source](/docs/build)
|
||||
- `systemctl --version` 232 or newer
|
||||
- `sudo` privileges
|
||||
|
||||
|
|
@ -100,27 +72,4 @@ You can stop the service with:
|
|||
Do not stop the service to change Caddy's configuration. Stopping the server will incur downtime. Use the reload command instead.
|
||||
</aside>
|
||||
|
||||
## Build from source
|
||||
|
||||
Requirements:
|
||||
|
||||
- [Go](https://golang.org/dl) 1.14 or newer
|
||||
- [Go modules](https://github.com/golang/go/wiki/Modules) enabled
|
||||
|
||||
Download the source code:
|
||||
|
||||
<pre><code class="cmd bash">git clone "https://github.com/caddyserver/caddy.git"</code></pre>
|
||||
|
||||
Build:
|
||||
|
||||
<pre><code class="cmd"><span class="bash">cd caddy/cmd/caddy/</span>
|
||||
<span class="bash">go build</span></code></pre>
|
||||
|
||||
|
||||
### With plugins
|
||||
|
||||
Using [xcaddy](https://github.com/caddyserver/xcaddy), you can compile Caddy with extra plugins, for example:
|
||||
|
||||
<pre><code class="cmd bash">xcaddy build \
|
||||
--with github.com/caddyserver/nginx-adapter
|
||||
--with github.com/caddyserver/ntlm-transport@v0.1.0</code></pre>
|
||||
Now that Caddy is installed, see our [Getting Started](/docs/getting-started) tutorial to learn how to use it!
|
||||
Loading…
Add table
Add a link
Reference in a new issue