diff --git a/docs/recipes.md b/docs/recipes.md index c14f988..b85503a 100644 --- a/docs/recipes.md +++ b/docs/recipes.md @@ -6,3 +6,7 @@ This section of the manual gives you easy to follow recipes for common use cases ```{=include=} chapters html:into-file=//recipes-exposeService.html recipes/exposeService.md ``` + +```{=include=} chapters html:into-file=//recipes-serveStaticPages.html +recipes/serveStaticPages.md +``` diff --git a/docs/recipes/serveStaticPages.md b/docs/recipes/serveStaticPages.md new file mode 100644 index 0000000..a5ef5c5 --- /dev/null +++ b/docs/recipes/serveStaticPages.md @@ -0,0 +1,75 @@ + +# Serve Static Pages {#recipes-serveStaticPages} + +This recipe shows how to use SelfHostBlocks blocks to serve static web pages using the Nginx reverse proxy with SSL termination. + +In this recipe, we'll assume the pages to serve are found under the `/srv/my-website` path and will be served under the `my-website.example.com` fqdn. + +```nix +let + name = "my-website"; + subdomain = name; + domain = "example.com"; + fqdn = "${subdomain}.${domain}"; + user = "me"; +in +``` + +We also assume the static web pages are owned and updated by the user named `me`. + +## ZFS dataset {#recipes-serveStaticPages-zfs} + +We can create a ZFS dataset with: + +```nix +shb.zfs.datasets."safe/${name}".path = "/srv/${name}"; +``` + +## SSL Certificate {#recipes-serveStaticPages-ssl} + +Requesting an SSL certificate from Let's Encrypt is done by adding an entry to +the `extraDomains` option: + +```nix +shb.certs.certs.letsencrypt.${domain}.extraDomains = [ fqdn ]; +``` + +This assumes the `shb.certs` block has been configured: + +```nix +shb.certs.certs.letsencrypt.${domain} = { + inherit domain; + group = "nginx"; + reloadServices = [ "nginx.service" ]; + adminEmail = "admin@${domain}"; +}; +``` + +## Reverse Proxy {#recipes-serveStaticPages-nginx} + +First, we make the parent directory owned by the user which will upload them and `nginx`: + +```nix +systemd.tmpfiles.rules = lib.mkBefore [ + "d '/srv/${name}' 0750 ${user} nginx - -" +]; +``` + +Now, we can setup nginx. The following snippet serves files from the `/srv/${name}/` directory. + +```nix +services.nginx.enable = true; + +services.nginx.virtualHosts."skarabox.${domain}" = { + forceSSL = true; + sslCertificate = config.shb.certs.certs.letsencrypt."${domain}".paths.cert; + sslCertificateKey = config.shb.certs.certs.letsencrypt."${domain}".paths.key; + locations."/" = { + root = "/srv/${name}/"; + extraConfig = '' + add_header Strict-Transport-Security "max-age=63072000; includeSubDomains; preload"; + add_header Cache-Control "max-age=604800, stale-while-revalidate=86400, stale-if-error=86400, must-revalidate, public"; + ''; + }; +}; +``` diff --git a/docs/redirects.json b/docs/redirects.json index b89d06a..8dc33db 100644 --- a/docs/redirects.json +++ b/docs/redirects.json @@ -1670,6 +1670,18 @@ "recipes-exposeService-zfs": [ "recipes-exposeService.html#recipes-exposeService-zfs" ], + "recipes-serveStaticPages": [ + "recipes-serveStaticPages.html#recipes-serveStaticPages" + ], + "recipes-serveStaticPages-nginx": [ + "recipes-serveStaticPages.html#recipes-serveStaticPages-nginx" + ], + "recipes-serveStaticPages-ssl": [ + "recipes-serveStaticPages.html#recipes-serveStaticPages-ssl" + ], + "recipes-serveStaticPages-zfs": [ + "recipes-serveStaticPages.html#recipes-serveStaticPages-zfs" + ], "redirect-management": [ "service-implementation-guide.html#redirect-management" ],