From 48645cedc167b2e46dd069710cf92059fb765a8f Mon Sep 17 00:00:00 2001 From: Francis Lavoie Date: Sun, 19 Nov 2023 18:48:19 -0500 Subject: [PATCH] Rewrite quick assist with AlpineJS, use markdown for contents --- new/docs/index.html | 14 +- new/includes/quick-assist/content.md | 136 +++++++ new/includes/quick-assist/core.html | 103 ++++++ new/includes/quick-assist/structure.html | 275 ++++++++++++++ new/resources/css/docs-home.css | 43 --- new/resources/css/docs.css | 51 ++- new/resources/js/docs-home.js | 448 ----------------------- 7 files changed, 566 insertions(+), 504 deletions(-) create mode 100644 new/includes/quick-assist/content.md create mode 100644 new/includes/quick-assist/core.html create mode 100644 new/includes/quick-assist/structure.html delete mode 100644 new/resources/css/docs-home.css delete mode 100644 new/resources/js/docs-home.js diff --git a/new/docs/index.html b/new/docs/index.html index 6204d9b..dc7ed50 100644 --- a/new/docs/index.html +++ b/new/docs/index.html @@ -5,13 +5,12 @@ {{import "/includes/head.html"}} {{template "head"}} - + - {{include "/includes/header.html" ""}} @@ -99,16 +98,7 @@

Documentation

-
-
- Quick Assist -
-
-

-
-
-
-
+ {{ include "/includes/quick-assist/core.html" }}

Getting Started

diff --git a/new/includes/quick-assist/content.md b/new/includes/quick-assist/content.md new file mode 100644 index 0000000..c2cbfab --- /dev/null +++ b/new/includes/quick-assist/content.md @@ -0,0 +1,136 @@ + + +
+ +
sudo apt install -y debian-keyring debian-archive-keyring apt-transport-https
+curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' | sudo gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg
+curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt' | sudo tee /etc/apt/sources.list.d/caddy-stable.list
+sudo apt update
+sudo apt install caddy
+ +
+
+ +
dnf install 'dnf-command(copr)'
+dnf copr enable @caddy/caddy
+dnf install caddy
+ +
+
+ +
pacman -Syu caddy
+ +
+
+ +
brew install caddy
+ +
+
+ +

Chocolatey:

choco install caddy
+

Scoop:

scoop install caddy
+ +
+
+ +- Package name: [`caddy`](https://search.nixos.org/packages?channel=unstable&show=caddy&query=caddy) +- NixOS module: [`services.caddy`](https://search.nixos.org/options?channel=unstable&show=services.caddy.enable&query=services.caddy) + +
+
+ +In Termux: 
pkg install caddy
+ +
+
+ +

Webi

+

Linux and macOS:

+
curl -sS https://webi.sh/caddy | sh
+

Windows:

+
curl.exe https://webi.ms/caddy | powershell
+

Ansible

+
ansible-galaxy install nvjacobo.caddy
+ +
+
+ +
docker pull caddy
+ +
+
+ +Make sure to have `git` and the latest version of [Go](https://go.dev) installed. + +
git clone "https://github.com/caddyserver/caddy.git"
+cd caddy/cmd/caddy/
+go build
+ +
+
+ + +[`xcaddy`](https://github.com/caddyserver/xcaddy) is a command line tool that helps you build Caddy with plugins. A basic build looks like: + +
xcaddy build
+ +To build with plugins, use `--with`: + +
xcaddy build \
+	--with github.com/caddyserver/nginx-adapter
+	--with github.com/caddyserver/ntlm-transport@v0.1.1
+ +
+
+ +1. Obtain a Caddy binary: + - [from releases on GitHub](https://github.com/caddyserver/caddy/releases) (expand "Assets") + - Refer to [Verifying Asset Signatures](/docs/signature-verification) for how to verify the asset signature + - [from our download page](/download) + - [by building from source](/docs/build) (either with `go` or `xcaddy`) +2. [Install Caddy as a system service.](/docs/running#manual-installation) This is strongly recommended, especially for production servers. + +Place the binary in one of your `$PATH` (or `%PATH%` on Windows) directories so you can run `caddy` without typing the full path of the executable file. (Run `echo $PATH` to see the list of directories that qualify.) + +You can upgrade static binaries by replacing them with newer versions and restarting Caddy. The [`caddy upgrade` command](/docs/command-line#caddy-upgrade) can make this easy. + +
+
+ +On-demand TLS is designed for situations when you either don't control the domain names, or you have too many certificates to load all at once when the server starts. For every other use case, standard TLS automation is likely better suited. + +
+
+ + +In order to prevent abuse, you must first configure an `ask` endpoint so Caddy can check whether it should get a certificate. Add this to your global options at the top: + +```caddy +{ + on_demand_tls { + ask http://localhost:5555/check + } +} +``` + +Change that endpoint to be something you've set up that will respond with HTTP 200 if the domain given in the `domain=` query parameter is allowed to have a certificate. + +Then create a site block that serves all sites/hosts on the TLS port: + +```caddy +https:// { + tls { + on_demand + } +} +``` + +This is the minimum config to enable Caddy to accept and service TLS connections for arbitrary hosts. This config doesn't invoke any handlers. Usually you'll also [`reverse_proxy`](/docs/caddyfile/directives/reverse_proxy) to your backend application. + +
diff --git a/new/includes/quick-assist/core.html b/new/includes/quick-assist/core.html new file mode 100644 index 0000000..2b960f9 --- /dev/null +++ b/new/includes/quick-assist/core.html @@ -0,0 +1,103 @@ +{{ include "/includes/quick-assist/structure.html" }} + + +
+
+ Quick Assist + +
+
+

+
+
+ + + Reset + +
+
+
+ + + +
+{{ markdown (include "/includes/quick-assist/content.md") }} +
diff --git a/new/includes/quick-assist/structure.html b/new/includes/quick-assist/structure.html new file mode 100644 index 0000000..060a815 --- /dev/null +++ b/new/includes/quick-assist/structure.html @@ -0,0 +1,275 @@ + diff --git a/new/resources/css/docs-home.css b/new/resources/css/docs-home.css deleted file mode 100644 index cd7469f..0000000 --- a/new/resources/css/docs-home.css +++ /dev/null @@ -1,43 +0,0 @@ -.quick-assist-history { - font-size: 90%; - - display: flex; - flex-wrap: wrap; - gap: .5em; -} - -.quick-assist-history > * { - display: inline-block; - color: var(--text-color-muted); - text-decoration: none; - cursor: pointer; -} - -.quick-assist-history > *:hover { - color: #216688; - text-decoration: underline; -} - -.quick-assist-history > :not(:first-child):before { - content: '>'; - margin-right: .5em; - display: inline-block; - color: #809783; -} - -h3.quick-assist-question { - font-size: 150%; -} - -.quick-assist-options { - margin-top: 1.5em; - display: grid; - gap: 1em; - grid-template-columns: repeat(auto-fill, minmax(200px, 1fr)); -} - -.quick-assist button, -.quick-assist .button { - font-size: 100%; - min-height: 3.5em; -} \ No newline at end of file diff --git a/new/resources/css/docs.css b/new/resources/css/docs.css index 45bd8fb..bb822b8 100644 --- a/new/resources/css/docs.css +++ b/new/resources/css/docs.css @@ -721,6 +721,55 @@ main nav ul > li:hover #autonav { +.quick-assist-history { + font-size: 90%; + + display: flex; + flex-wrap: wrap; + gap: .5em; +} + +.quick-assist-history > a { + display: inline-block; + color: var(--text-color-muted); + text-decoration: none; + cursor: pointer; +} + +.quick-assist-history > a:hover { + color: #216688; + text-decoration: underline; +} + +.quick-assist-history > a:not(:first-child):before { + content: '>'; + margin-right: .5em; + display: inline-block; + color: #809783; +} + +h3.quick-assist-question { + font-size: 150%; +} + +.quick-assist-options { + margin-top: 1.5em; + display: grid; + gap: 1em; + grid-template-columns: repeat(auto-fill, minmax(200px, 1fr)); +} + +.quick-assist-options > div { + display: contents; +} + +.quick-assist button, +.quick-assist .button { + font-size: 100%; + min-height: 3.5em; +} + + @@ -765,4 +814,4 @@ main nav ul > li:hover #autonav { main nav ul .heading { margin-top: 2.5em !important; } -} \ No newline at end of file +} diff --git a/new/resources/js/docs-home.js b/new/resources/js/docs-home.js deleted file mode 100644 index 54c4428..0000000 --- a/new/resources/js/docs-home.js +++ /dev/null @@ -1,448 +0,0 @@ -quickAssist = function() { - let history = []; - - const states = { - start: { - prompt: "What are you looking for?", - options: [ - { - text: "How to install Caddy", - next: "install" - }, - { - text: "Help configuring Caddy", - next: "configure" - }, - { - text: "A solution to a problem", - next: "solution" - }, - { - text: "An example for my use case", - next: "example" - } - ] - }, - install: { - prompt: "How do you want to install Caddy?", - options: [ - { - text: "OS package manager", - next: "install_pkgmgr" - }, - { - text: "Docker", - next: "install_docker" - }, - { - text: "Build from source", - next: "install_build" - }, - { - text: "Build with plugins", - next: "install_with_plugins" - }, - { - text: "Pre-built binary", - next: "install_binary" - } - ] - }, - install_pkgmgr: { - prompt: "Which OS are you using?", - options: [ - { - text: "Linux (Debian, Ubuntu, Raspbian)", - next: "install_dpkg" - }, - { - text: "Linux (Fedora, RedHat, CentOS)", - next: "install_rpm" - }, - { - text: "Linux (Arch, Manjaro, Parabola)", - next: "install_arch" - }, - { - text: "macOS", - next: "install_mac" - }, - { - text: "Windows", - next: "install_windows" - }, - { - text: "Nix/NixOS", - next: "install_nix" - }, - { - text: "Android", - next: "install_android" - }, - { - text: "Other", - next: "install_other" - } - ] - }, - install_dpkg: { - title: "Install Caddy on Debian-based systems", - content: `
sudo apt install -y debian-keyring debian-archive-keyring apt-transport-https
-curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' | sudo gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg
-curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt' | sudo tee /etc/apt/sources.list.d/caddy-stable.list
-sudo apt update
-sudo apt install caddy
`, - options: [ - { - text: "Learn more", - href: "/docs/install#debian-ubuntu-raspbian" - } - ] - }, - install_rpm: { - title: "Install Caddy via RPM", - content: `
dnf install 'dnf-command(copr)'
-dnf copr enable @caddy/caddy
-dnf install caddy
`, - options: [ - { - text: "Learn more", - href: "/docs/install#fedora-redhat-centos" - } - ] - }, - install_arch: { - title: "Install Caddy on Arch/Manjaro/Parabola Linux", - content: `
pacman -Syu caddy
`, - options: [ - { - text: "Learn more", - href: "/docs/install#arch-linux-manjaro-parabola" - } - ] - }, - install_mac: { - title: "Install Caddy on macOS", - content: `
brew install caddy
`, - options: [ - { - text: "Learn more", - href: "/docs/install#homebrew" - } - ] - }, - install_windows: { - title: "Install Caddy on Windows", - content: `

Chocolatey:

choco install caddy
-

Scoop:

scoop install caddy
`, - options: [ - { - text: "Learn more", - href: "/docs/install#windows" - } - ] - }, - install_nix: { - title: "Install Caddy on Nix/Nixpkgs/NixOS", - content: ``, - options: [ - { - text: "Learn more", - href: "/docs/install#nixnixpkgsnixos" - } - ] - }, - install_android: { - title: "Install Caddy on Android", - content: `In Termux: 
pkg install caddy
`, - options: [ - { - text: "Learn more", - href: "/docs/install#termux" - } - ] - }, - install_other: { - title: "Miscellaneous install methods", - content: `

Webi

-

Linux and macOS:

- 
curl -sS https://webi.sh/caddy | sh
-

Windows:

- 
curl.exe https://webi.ms/caddy | powershell
-

Ansible

- 
ansible-galaxy install nvjacobo.caddy
`, - options: [ - { - text: "Learn more", - href: "/docs/install#fedora-redhat-centos" - } - ] - }, - install_docker: { - title: "Official Docker image", - content: `
docker pull caddy
`, - options: [ - { - text: "Learn more", - href: "/docs/install#docker" - } - ] - }, - install_build: { - title: "Build Caddy from source", - content: `

Make sure to have git and the latest version of Go installed.

- 
git clone "https://github.com/caddyserver/caddy.git"
-cd caddy/cmd/caddy/
-go build
`, - options: [ - { - text: "Learn more", - href: "/docs/build" - } - ] - }, - install_with_plugins: { - title: "Build Caddy with plugins", - content: ` -

- xcaddy is a command line tool - that helps you build Caddy with plugins. A basic build looks like: -

- 
xcaddy build
-

- To build with plugins, use --with: -

- 
xcaddy build \\
-	--with github.com/caddyserver/nginx-adapter
-	--with github.com/caddyserver/ntlm-transport@v0.1.1
`, - options: [ - { - text: "Learn more", - href: "/docs/build#xcaddy" - } - ] - }, - install_binary: { - title: "Install Caddy binary manually", - content: ` -
    -
  1. - Obtain a Caddy binary: - -
    2. -
  2. - Install Caddy as a system service. This is strongly recommended, - especially for production servers. -
    3. -
-

Place the binary in one of your $PATH (or %PATH% on Windows) directories so you can run - caddy without typing the full path of the executable file. (Run echo $PATH to see the list - of directories that qualify.)

-

You can upgrade static binaries by replacing them with newer versions and restarting Caddy. The caddy upgrade command can make this easy.

`, - options: [ - { - text: "Learn more", - href: "/docs/build#xcaddy" - } - ] - }, - - configure: { - prompt: "What are you trying to configure?", - options: [ - { - text: "On-demand TLS", - next: "cfg_ondemand" - }, - { - text: "Authentication", - next: "cfg_authentication" - }, - { - text: "Load balancing", - next: "cfg_loadbalancing" - } - ] - }, - cfg_ondemand: { - prompt: "Do you control the (DNS records of) the domain names you're serving?", - options: [ - { - text: "Yes", - breadcrumb: "I control the domains", - next: "cfg_ondemand_havecontrol" - }, - { - text: "No", - breadcrumb: "DNS out of my control", - next: "cfg_ondemand_ok" - } - ] - }, - cfg_ondemand_havecontrol: { - prompt: "Do you have hundreds or thousands of your own domain names to serve?", - options: [ - { - text: "Yes", - breadcrumb: "Lots of domains", - next: "cfg_ondemand_ok" - }, - { - text: "No", - breadcrumb: "Small scale", - next: "cfg_ondemand_smallscale" - } - ] - }, - cfg_ondemand_smallscale: { - title: "You likely don't need on-demand TLS.", - content: `On-demand TLS is designed for situations when you either don't control the domain names, - or you have too many certificates to load all at once when the server starts. For every other - use case, standard TLS automation is likely better suited.`, - options: [ - { - text: "Learn more", - href: "/docs/automatic-https#on-demand-tls" - } - ] - }, - cfg_ondemand_ok: { - prompt: "Are you using the Caddyfile or JSON to configure Caddy?", - options: [ - { - text: "Caddyfile", - next: "cfg_ondemand_caddyfile" - }, - { - text: "JSON", - next: "cfg_ondemand_json" - } - ] - }, - cfg_ondemand_caddyfile: { - title: "Setting up On-Demand TLS", - content: ` -

In order to prevent abuse, you must first configure an ask endpoint so Caddy - can check whether it should get a certificate. Add this to your global options at the top:

- 
on_demand_tls {
-	ask http://localhost:5555/check
-}
-

Change that endpoint to be something you've set up that will respond with HTTP 200 if the - domain given in the domain= query parameter is allowed to have a certificate.

-

Then create a site block that serves all sites/hosts on the TLS port:

- 
https:// {
-	tls {
-		on_demand
-	}
-}
-

This is the minimum config to enable Caddy to accept and service TLS connections for arbitrary - hosts. This config doesn't invoke any handlers. Usually you'll also reverse_proxy - to your backend application.

`, - options: [ - { - text: "Learn more", - href: "/docs/automatic-https#on-demand-tls" - } - ] - }, - }; - - // show renders the given state into the quick assist box - function show(state) { - // reset & show prompt/content - $_('.quick-assist-question').innerHTML = state.prompt || state.title; - $_('.quick-assist-content').innerHTML = state.content || ''; - $_('.quick-assist-options').innerHTML = ''; - - // render options - let hasNext = false; - if (state.options) { - for (const opt of state.options) { - if (opt.next) { - hasNext = true; - } - const btn = document.createElement('a'); - btn.classList.add('button'); - btn.innerText = opt.text || ""; - if (opt.next) { - btn.dataset.next = opt.next; - btn.dataset.breadcrumb = opt.breadcrumb || opt.text; - } else if (opt.href) { - btn.href = opt.href; - } - $_('.quick-assist-options').append(btn); - } - } - - // if there's no "next" state, then this must be the end of - // assistance, so show a button to reset - if (!hasNext) { - const reset = document.createElement('a'); - reset.classList.add('button', 'reset'); - reset.innerText = "Reset"; - $_('.quick-assist-options').append(reset); - } - - history.push(state); - } - - // reset clears history and shows the start state; it does NOT delete things - // from the UI, however. - function reset() { - history = []; - show(states.start); - } - - // clicking breadcrumbs should take you to that point in the state machine - on('click', '.quick-assist-history a', event => { - // remove later breadcrumbs - for (let sibling = event.target.nextElementSibling; sibling != null; sibling = event.target.nextElementSibling) { - sibling.remove(); - history.pop(); - } - - // show the state represented by the breadcrumb clicked - if (event.target.dataset.index) { - show(history[Number(event.target.dataset.index)]); - } else { - reset(); - } - }); - - // when an option is selected, add breadcrumb and show that state - on('click', '.quick-assist-options a[data-next]', event => { - const link = document.createElement('a'); - link.innerText = event.target.dataset.breadcrumb || event.target.innerText; - link.dataset.index = history.length; - $_('.quick-assist-history').append(link); - show(states[event.target.dataset.next]); - }); - - on('click', '.quick-assist-options a.reset', event => { - $_('.quick-assist-history a:first-child').dispatchEvent(new Event('click', { bubbles: true })); - }) - - // when page loads, show the start of the quick assist - reset(); -}; - - - -ready(() => { - quickAssist(); -});