From e25b1ae179b60fd876eea7ebff150df78b5cbcc0 Mon Sep 17 00:00:00 2001
From: Francis Lavoie <lavofr@gmail.com>
Date: Sun, 4 Jul 2021 12:27:00 -0400
Subject: [PATCH] docs: Add new Linux Service page, moved from install.md

---
 src/docs/markdown/install.md    |  79 +++------------------
 src/docs/markdown/service.md    | 121 ++++++++++++++++++++++++++++++++
 src/docs/markdown/v2-upgrade.md |   7 +-
 src/includes/docs-nav.html      |   1 +
 4 files changed, 135 insertions(+), 73 deletions(-)
 create mode 100644 src/docs/markdown/service.md

diff --git a/src/docs/markdown/install.md b/src/docs/markdown/install.md
index 2ed8c77..f926e9b 100644
--- a/src/docs/markdown/install.md
+++ b/src/docs/markdown/install.md
@@ -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
diff --git a/src/docs/markdown/service.md b/src/docs/markdown/service.md
new file mode 100644
index 0000000..1f72073
--- /dev/null
+++ b/src/docs/markdown/service.md
@@ -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>
diff --git a/src/docs/markdown/v2-upgrade.md b/src/docs/markdown/v2-upgrade.md
index ab8b246..5a056f8 100644
--- a/src/docs/markdown/v2-upgrade.md
+++ b/src/docs/markdown/v2-upgrade.md
@@ -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
diff --git a/src/includes/docs-nav.html b/src/includes/docs-nav.html
index 9ad0166..e855ad8 100644
--- a/src/includes/docs-nav.html
+++ b/src/includes/docs-nav.html
@@ -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>