From 5f09f05e0825f0835691788699d32698faa55a54 Mon Sep 17 00:00:00 2001
From: Francis Lavoie <lavofr@gmail.com>
Date: Wed, 11 Aug 2021 19:08:47 -0400
Subject: [PATCH] docs: Add new "Keep Caddy Running" page, moved from
 install.md (#181)

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

* Apply suggestions from code review

Co-authored-by: Carl George <carl@george.computer>

* Add note regarding resetting Exec*

* Updates to make the page more generalized


Docker

* Polish the Windows Service docs a bit

Co-authored-by: Carl George <carl@george.computer>
---
 src/docs/markdown/command-line.md |   2 +-
 src/docs/markdown/install.md      | 128 ++----------------
 src/docs/markdown/running.md      | 214 ++++++++++++++++++++++++++++++
 src/docs/markdown/v2-upgrade.md   |   7 +-
 src/includes/docs-nav.html        |   1 +
 5 files changed, 229 insertions(+), 123 deletions(-)
 create mode 100644 src/docs/markdown/running.md

diff --git a/src/docs/markdown/command-line.md b/src/docs/markdown/command-line.md
index 6b7ea4f..7f577c1 100644
--- a/src/docs/markdown/command-line.md
+++ b/src/docs/markdown/command-line.md
@@ -311,7 +311,7 @@ Same as [`caddy run`](#caddy-run), but in the background. This command only bloc
 
 Note: the flag `--config` doesn't support `-` to read the config from stdin.
 
-Use of this command is discouraged with system services or on Windows. On Windows, the child process will remain attached to the terminal, so closing the window will forcefully stop Caddy, which is not obvious.
+Use of this command is discouraged with system services or on Windows. On Windows, the child process will remain attached to the terminal, so closing the window will forcefully stop Caddy, which is not obvious. Consider running Caddy [as a service](/docs/running) instead.
 
 Once started, you can use [`caddy stop`](#caddy-stop) or [the /stop API endpoint](/docs/api#post-stop) to exit the background process.
 
diff --git a/src/docs/markdown/install.md b/src/docs/markdown/install.md
index 2ed8c77..36f3082 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>.
@@ -29,12 +28,11 @@ This page describes various methods for installing Caddy on your system.
 - [Ansible](#ansible)
 - [Scoop](#scoop)
 - [Termux](#termux)
-- [Windows service](#windows-service)
 
 
 ## 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/running#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 +40,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/running#linux-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 +60,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-debianubunturaspbian).
+
 
 ## Fedora, RedHat, CentOS
 
+This package comes with both of Caddy's [systemd service](/docs/running#linux-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 +81,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/running#linux-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 +97,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/running#linux-service) via being installed with the [`apt` repo](#debian-ubuntu-raspbian).
 
 
 ## Homebrew
@@ -224,51 +166,3 @@ _Note: This is a community-maintained installation method._
 
 [**View the Termux build.sh file**](https://github.com/termux/termux-packages/blob/master/packages/caddy/build.sh)
 
-
-## Windows service
-
-_Note: This is a community-maintained installation method._
-
-Install Caddy as a service on Windows with these instructions.
-
-**Requirements:**
-
-- `caddy.exe` binary that you [downloaded](/download) or [built from source](/docs/build)
-- Any exe from the latest release of the
-  [WinSW](https://github.com/winsw/winsw/releases/latest) service wrapper (Stay
-  on a v2.x release for now)
-
-Put all files into a service directory. In the following examples, we use `c:\caddy`.
-
-Rename the WinSW exe file to `caddy-service.exe`.
-
-Add a `caddy-service.xml` in the directory:
-
-<pre><code class="cmd">&lt;service>
-  &lt;id>caddy&lt;/id>
-  &lt;!-- Display name of the service -->
-  &lt;name>Caddy Web Server (powered by WinSW)&lt;/name>
-  &lt;!-- Service description -->
-  &lt;description>Caddy Web Server (https://caddyserver.com/)&lt;/description>
-  &lt;executable>%BASE%\caddy.exe&lt;/executable>
-  &lt;arguments>run&lt;/arguments>
-  &lt;log mode="roll-by-time">
-    &lt;pattern>yyyy-MM-dd&lt;/pattern>
-  &lt;/log>
-&lt;/service>
-</code></pre>
-
-You can now install the service using:
-<pre><code class="cmd">caddy-service install</code></pre>
-
-You might want to start the Windows Services Console to see if the service is runnnig correctly:
-<pre><code class="cmd">services.msc</code></pre>
-
-Be aware that Windows services cannot be reloaded, so you have to tell caddy directly to relaod:
-<pre><code class="cmd">caddy reload</code></pre>
-
-Restarting is possible via the normal Windows services commands.
-
-For customizing the service wrapper, see the [WinSW documentation](https://github.com/winsw/winsw/tree/master#usage)
-
-
diff --git a/src/docs/markdown/running.md b/src/docs/markdown/running.md
new file mode 100644
index 0000000..fbc2a46
--- /dev/null
+++ b/src/docs/markdown/running.md
@@ -0,0 +1,214 @@
+---
+title: Keep Caddy Running
+---
+
+# Keep Caddy Running
+
+While Caddy can be run successfully by directly using its [Command Line Interface](/docs/command-line), there are numerous advantages to using a service manager to keep it running, such as ensuring it starts back up when the system boots, and to capture stdout/stderr logging.
+
+
+- [Linux Service](#linux-service)
+  - [Unit Files](#unit-files)
+  - [Using the Service](#using-the-service)
+  - [Manual Installation](#manual-installation)
+  - [Overrides](#overrides)
+- [Windows Service](#windows-service)
+- [Docker Compose](#docker-compose)
+
+
+## Linux Service
+
+The recommended way to run Caddy on Linux distributions with systemd is with our official systemd unit files.
+
+
+### 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 and stop the previous one before enabling and starting 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 --now caddy</span>
+<span class="bash">sudo systemctl enable --now 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 --now 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 (note that `Exec*` directives [must be reset with empty strings](https://www.freedesktop.org/software/systemd/man/systemd.service.html#ExecStart=) before setting a new value):
+```systemd
+[Service]
+ExecStart=
+ExecStart=/usr/bin/caddy run --environ --config /etc/caddy/caddy.json
+ExecReload=
+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>
+
+
+## Windows service
+
+Install Caddy as a service on Windows with these instructions.
+
+**Requirements:**
+
+- `caddy.exe` binary that you [downloaded](/download) or [built from source](/docs/build)
+- Any `.exe` from the latest release of the
+  [WinSW](https://github.com/winsw/winsw/releases/latest) service wrapper (the below service config is written for v2.x releases)
+
+Put all files into a service directory. In the following examples, we use `C:\caddy`.
+
+Rename the `WinSW-x64.exe` file to `caddy-service.exe`.
+
+Add a `caddy-service.xml` in the same directory:
+
+```xml
+<service>
+  <id>caddy</id>
+  <!-- Display name of the service -->
+  <name>Caddy Web Server (powered by WinSW)</name>
+  <!-- Service description -->
+  <description>Caddy Web Server (https://caddyserver.com/)</description>
+  <executable>%BASE%\caddy.exe</executable>
+  <arguments>run</arguments>
+  <log mode="roll-by-time">
+    <pattern>yyyy-MM-dd</pattern>
+  </log>
+</service>
+```
+
+You can now install the service using:
+<pre><code class="cmd bash">caddy-service install</code></pre>
+
+You might want to start the Windows Services Console to see if the service is runnnig correctly:
+<pre><code class="cmd bash">services.msc</code></pre>
+
+Be aware that Windows services cannot be reloaded, so you have to tell caddy directly to relaod:
+<pre><code class="cmd bash">caddy reload</code></pre>
+
+Restarting is possible via the normal Windows services commands, for example via the Task Manager's "Services" tab.
+
+For customizing the service wrapper, see the [WinSW documentation](https://github.com/winsw/winsw/tree/master#usage)
+
+
+## Docker Compose
+
+The simplest way to get up and running with Docker is to use Docker Compose. _The below is only an excerpt, see the docs on [Docker Hub](https://hub.docker.com/_/caddy) for more details_.
+
+First, create a file `docker-compose.yml` (or add this service to your existing file):
+
+```yaml
+version: "3.7"
+
+services:
+  caddy:
+    image: caddy:<version>
+    restart: unless-stopped
+    ports:
+      - "80:80"
+      - "443:443"
+    volumes:
+      - $PWD/Caddyfile:/etc/caddy/Caddyfile
+      - $PWD/site:/srv
+      - caddy_data:/data
+      - caddy_config:/config
+
+volumes:
+  caddy_data:
+  caddy_config:
+```
+
+Make sure to fill in `<version>` with the latest version number, which you can find listed on [Docker Hub](https://hub.docker.com/_/caddy) under the "Tags" section.
+
+Then, you can start the container:
+<pre><code class="cmd bash">docker-compose up -d</code></pre>
+
+To reload Caddy after making changes to your Caddyfile:
+<pre><code class="cmd bash">docker-compose exec -w /etc/caddy caddy caddy reload</code></pre>
+
+To see Caddy's logs:
+<pre><code class="cmd bash">docker-compose logs caddy</code></pre>
+
diff --git a/src/docs/markdown/v2-upgrade.md b/src/docs/markdown/v2-upgrade.md
index ab8b246..a9563cd 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/running#linux-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..6785945 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/running">Keep Caddy Running</a></li>
 
 		<li class="heading">Developers</li>
 		<li>