mirrors/caddy-website
1
0
Fork 0
mirror of https://github.com/caddyserver/website.git synced 2025-05-07 12:17:15 -04:00
Code Issues Projects Releases Packages Wiki Activity Actions

docs: Add new Linux Service page, moved from install.md

Browse source
This commit is contained in:
Francis Lavoie 2021-07-04 12:27:00 -04:00
parent 275cce9403
commit e25b1ae179
No known key found for this signature in database
GPG key ID: E73DB3ECE64E7885
4 changed files with 135 additions and 73 deletions
Download patch file Download diff file Expand all files Collapse all files

79
src/docs/markdown/install.md
View file

@ -14,7 +14,6 @@ This page describes various methods for installing Caddy on your system.
- [Arch Linux, Manjaro, Parabola](#arch-linux-manjaro-parabola)
- [Docker](#docker)
- [DigitalOcean](#digitalocean)
- [Linux service](#linux-service)
<aside class="tip">
Our <a href="https://github.com/caddyserver/dist">official packages</a> come only with the standard modules. If you need third-party plugins, <a href="/docs/build#xcaddy">build from source with <code>xcaddy</code></a> or use <a href="/download">our download page</a>.
@ -34,7 +33,7 @@ This page describes various methods for installing Caddy on your system.
## Static binaries
Simply downloading a Caddy binary does not <a href="#linux-service">install it as a service</a>, but can be useful in dev or when upgrading an existing installation.
Simply downloading a Caddy binary does not [install it as a service](/docs/service#manual-installation), but can be useful in dev or when upgrading an existing installation.
- [**View releases on GitHub**](https://github.com/caddyserver/caddy/releases) (expand "Assets")
- [**Use our download page**](/download)
@ -42,9 +41,7 @@ Simply downloading a Caddy binary does not <a href="#linux-service">install it a
## Debian, Ubuntu, Raspbian
Installing this package automatically starts and runs Caddy for you as a systemd service named `caddy` using our official [`caddy.service`](https://github.com/caddyserver/dist/blob/master/init/caddy.service) unit file.
This package also comes with a `caddy-api` systemd service using our official [`caddy-api.service`](https://github.com/caddyserver/dist/blob/master/init/caddy-api.service) unit file, which is disabled by default. If you plan to configure Caddy solely through its [API](/docs/api), then you should disable the `caddy` service, and enable the `caddy-api` service.
Installing this package automatically starts and runs Caddy as a [systemd service](/docs/service) named `caddy`, and also comes with a `caddy-api` service which is _not_ enabled by default, should you need it.
Stable releases:
@ -64,10 +61,13 @@ Testing releases (includes betas and release candidates):
[**View the Cloudsmith repos**](https://cloudsmith.io/~caddy/repos/)
If you wish to use the packaged support files (systemd services, bash completion and default configuration) with a custom Caddy build, instructions can be found [here](https://caddyserver.com/docs/build#package-support-files-for-custom-builds-for-debian-ubuntu-raspbian).
If you wish to use the packaged support files (systemd services, bash completion and default configuration) with a custom Caddy build, instructions can be [found here](https://caddyserver.com/docs/build#package-support-files-for-custom-builds-for-debian-ubuntu-raspbian).
## Fedora, RedHat, CentOS
This package comes with both of Caddy's [systemd service](/docs/service) unit files, but does not enable them by default.
Fedora or RHEL/CentOS 8:
<pre><code class="cmd"><span class="bash">dnf install 'dnf-command(copr)'</span>
@ -82,8 +82,11 @@ RHEL/CentOS 7:
[**View the Caddy COPR**](https://copr.fedorainfracloud.org/coprs/g/caddy/caddy/)
## Arch Linux, Manjaro, Parabola
This package comes with both of Caddy's [systemd service](/docs/service) unit files, but does not enable them by default.
<pre><code class="cmd"><span class="bash">pacman -Syu caddy</span></code></pre>
[**View Caddy in the Arch Linux repositories**](https://archlinux.org/packages/community/x86_64/caddy/)
@ -95,72 +98,12 @@ RHEL/CentOS 7:
[**View on Docker Hub**](https://hub.docker.com/_/caddy)
## DigitalOcean
[**Deploy a Caddy droplet on DigitalOcean**](https://marketplace.digitalocean.com/apps/caddy)
## Linux service
Manually install Caddy as a service on Linux with these instructions.
**Requirements:**
- `caddy` binary that you [downloaded](/download) or [built from source](/docs/build)
- `systemctl --version` 232 or newer
- `sudo` privileges
Move the caddy binary into your `$PATH`, for example:
<pre><code class="cmd bash">sudo mv caddy /usr/bin/</code></pre>
Test that it worked:
<pre><code class="cmd bash">caddy version</code></pre>
Create a group named `caddy`:
<pre><code class="cmd bash">sudo groupadd --system caddy</code></pre>
Create a user named `caddy`, with a writeable home folder:
<pre><code class="cmd bash">sudo useradd --system \
--gid caddy \
--create-home \
--home-dir /var/lib/caddy \
--shell /usr/sbin/nologin \
--comment "Caddy web server" \
caddy</code></pre>
If using a config file, be sure it is readable by the `caddy` user you just created.
Next, [choose a systemd service file](https://github.com/caddyserver/dist/blob/master/init) based on your use case:
- [**`caddy.service`**](https://github.com/caddyserver/dist/blob/master/init/caddy.service) if you configure Caddy with a file.
- [**`caddy-api.service`**](https://github.com/caddyserver/dist/blob/master/init/caddy-api.service) if you configure Caddy solely through its API.
They are very similar but have minor differences in the ExecStart and ExecReload commands to accommodate your workflow. Customize the file accordingly.
**Double-check the `ExecStart` and `ExecReload` directives.** Make sure the binary's location and command line arguments are correct for your installation! For example: if using a config file, change your `--config` path if it is different from our example.
The usual place to save the service file is: `/etc/systemd/system/caddy.service`
After saving your service file, you can start the service for the first time with the usual systemctl dance:
<pre><code class="cmd"><span class="bash">sudo systemctl daemon-reload</span>
<span class="bash">sudo systemctl enable caddy</span>
<span class="bash">sudo systemctl start caddy</span></code></pre>
Verify that it is running:
<pre><code class="cmd bash">systemctl status caddy</code></pre>
When running with our official service file, Caddy's output will be redirected to `journalctl`:
<pre><code class="cmd bash">journalctl -u caddy --no-pager | less</code></pre>
If using a config file, you can gracefully apply any changes:
<pre><code class="cmd bash">sudo systemctl reload caddy</code></pre>
You can stop the service with:
<pre><code class="cmd bash">sudo systemctl stop caddy</code></pre>
<aside class="advice">
Do not stop the service to change Caddy's configuration. Stopping the server will incur downtime. Use the reload command instead.
</aside>
The droplet is preconfigured to run Caddy as a [systemd service](/docs/service) via being installed with the [`apt` repo](#debian-ubuntu-raspbian).
## Homebrew

121
src/docs/markdown/service.md Normal file
View file

@ -0,0 +1,121 @@
---
title: Linux Service
---
Linux Service
=============
The recommended way to run Caddy on Linux distributions with systemd is with our official systemd unit files.
- [Unit Files](#unit-files)
- [Using the Service](#using-the-service)
- [Manual Installation](#manual-installation)
- [Overrides](#overrides)
## Unit Files
We provide two different systemd unit files that you can choose between, depending on your usecase:
- [**`caddy.service`**](https://github.com/caddyserver/dist/blob/master/init/caddy.service) if you configure Caddy with a [Caddyfile](/docs/caddyfile). If you prefer to use a JSON config file, you may [override](#overrides) the `ExecStart` and `ExecReload` commands.
- [**`caddy-api.service`**](https://github.com/caddyserver/dist/blob/master/init/caddy-api.service) if you configure Caddy solely through its [API](/docs/api). This service uses the [`--resume`](/docs/command-line#caddy-run) option which will start Caddy using the `autosave.json` which is [persisted](/docs/json/admin/config/) by default.
They are very similar, but differ in the `ExecStart` and `ExecReload` commands to accommodate the workflows.
If you need to switch between the services, you should disable the previous one before enabling the other. For example, to switch from the `caddy` service to the `caddy-api` service:
<pre><code class="cmd"><span class="bash">sudo systemctl disable caddy</span>
<span class="bash">sudo systemctl enable caddy-api</span>
<span class="bash">sudo systemctl start caddy-api</span></code></pre>
## Using the Service
To verify that the service is running:
<pre><code class="cmd bash">systemctl status caddy</code></pre>
The status command will also show the location of the currently running service file.
When running with our official service file, Caddy's output will be redirected to `journalctl`. To read your full logs and to avoid lines being truncated:
<pre><code class="cmd bash">journalctl -u caddy --no-pager | less</code></pre>
If using a config file, you can gracefully reload Caddy after making any changes:
<pre><code class="cmd bash">sudo systemctl reload caddy</code></pre>
You can stop the service with:
<pre><code class="cmd bash">sudo systemctl stop caddy</code></pre>
<aside class="advice">
Do not stop the service to change Caddy's configuration. Stopping the server will incur downtime. Use the reload command instead.
</aside>
## Manual Installation
Some [installation methods](/docs/install) automatically set up Caddy to run as a service. If you chose a method that did not, you may follow these instructions to do so:
**Requirements:**
- `caddy` binary that you [downloaded](/download) or [built from source](/docs/build)
- `systemctl --version` 232 or newer
- `sudo` privileges
Move the caddy binary into your `$PATH`, for example:
<pre><code class="cmd bash">sudo mv caddy /usr/bin/</code></pre>
Test that it worked:
<pre><code class="cmd bash">caddy version</code></pre>
Create a group named `caddy`:
<pre><code class="cmd bash">sudo groupadd --system caddy</code></pre>
Create a user named `caddy`, with a writeable home directory:
<pre><code class="cmd bash">sudo useradd --system \
--gid caddy \
--create-home \
--home-dir /var/lib/caddy \
--shell /usr/sbin/nologin \
--comment "Caddy web server" \
caddy</code></pre>
If using a config file, be sure it is readable by the `caddy` user you just created.
Next, [choose a systemd unit file](#unit-files) based on your use case.
**Double-check the `ExecStart` and `ExecReload` directives.** Make sure the binary's location and command line arguments are correct for your installation! For example: if using a config file, change your `--config` path if it is different from the defaults.
The usual place to save the service file is: `/etc/systemd/system/caddy.service`
After saving your service file, you can start the service for the first time with the usual systemctl dance:
<pre><code class="cmd"><span class="bash">sudo systemctl daemon-reload</span>
<span class="bash">sudo systemctl enable caddy</span>
<span class="bash">sudo systemctl start caddy</span></code></pre>
Verify that it is running:
<pre><code class="cmd bash">systemctl status caddy</code></pre>
Now you're ready to [use the service](#using-the-service)!
## Overrides
The best way to override aspects of the service files is with this command:
<pre><code class="cmd bash">sudo systemctl edit caddy</code></pre>
This will open a blank file with your default terminal text editor in which you can override or add directives to the unit definition.
For example, if you need to define environment variables for use in your config, you may do so like this:
```systemd
[Service]
Environment="CF_API_TOKEN=super-secret-cloudflare-tokenvalue"
```
Or, for example if you need to change the config file from the default of the Caddyfile, to instead using a JSON file:
```systemd
[Service]
ExecStart=/usr/bin/caddy run --environ --config /etc/caddy/caddy.json
ExecReload=/usr/bin/caddy reload --config /etc/caddy/caddy.json
```
Then, save the file and exit the text editor, and restart the service for it to take effect:
<pre><code class="cmd bash">sudo systemctl restart caddy</code></pre>

7
src/docs/markdown/v2-upgrade.md
View file

@ -373,12 +373,9 @@ Most sites will not need this directive at all.
## Service files
We recommend using [one of our official service files](https://github.com/caddyserver/dist/blob/master/init) for Caddy deployments.
If you need a custom service file, base it off of ours. It has been carefully tuned to what it is for good reasons! Be sure to customize yours if needed.
See [install instructions](/docs/install#linux-service) for details.
We recommend using [one of our official systemd service files](/docs/service) for Caddy deployments.
If you need a custom service file, base it off of ours. They've been carefully tuned to what it is for good reasons! Be sure to customize yours if needed.
## Plugins

1
src/includes/docs-nav.html
View file

@ -46,6 +46,7 @@
<li><a href="/docs/logging">How Logging Works</a></li>
<li><a href="/docs/metrics">Monitoring Caddy</a></li>
<li><a href="/docs/architecture">Caddy Architecture</a></li>
<li><a href="/docs/service">Linux Service</a></li>
<li class="heading">Developers</li>
<li>