\nII Chef’s Favorites (Docker)

The following recipes are the chef’s current favorites - these are recipes actively in use and updated by @funkypenguin

hero: AutoPirate - A fully-featured recipe to automate finding, downloading, and organising your media

",{"_482":483,"_43":44,"_47":48,"_45":46,"_65":66,"_484":485,"_565":480},"previewContent","

\n \n
- \n 1 What is this?\n
- \n 2 How to read this book\n
- \n 3 CHANGELOG\n
- \n 4 Welcome to Funky Penguin’s Geek Cookbook\n
\n
\n I HA Docker Swarm\n
- \n 5 Design\n
- \n 6 Nodes\n
- \n 7 Shared Storage (Ceph)\n
- \n 8 Shared Storage (GlusterFS)\n
- \n 9 Keepalived\n
- \n 10 Docker Swarm Mode\n
- \n 11 Traefik\n
- \n 12 Traefik Forward Auth\n
- \n 13 Using Traefik Forward Auth with KeyCloak\n
- \n 14 Create registry mirror\n
\n
\n II Chef’s Favorites (Docker)\n
- \n 15 AutoPirate\n
- \n 16 SABnzbd\n
- \n 17 NZBGet\n
- \n 18 RTorrent / ruTorrent\n
- \n 19 Sonarr\n
- \n 20 Radarr\n
- \n 21 Mylar\n
- \n 22 LazyLibrarian\n
- \n 23 Headphones\n
- \n 24 Lidarr\n
- \n 25 NZBHydra\n
- \n 26 NZBHydra 2\n
- \n 27 Ombi\n
- \n 28 Jackett\n
- \n 29 Heimdall\n
- \n 30 Duplicity\n
- \n 31 Elkar Backup\n
- \n 32 Emby\n
- \n 33 Home Assistant\n
- \n 34 iBeacons with Home assistant\n
- \n 35 Huginn\n
- \n 36 Kanboard\n
- \n 37 Miniflux\n
- \n 38 Munin\n
- \n 39 NextCloud\n
- \n 40 OwnTracks\n
- \n 41 phpIPAM\n
- \n 42 Plex\n
- \n 43 PrivateBin\n
- \n 44 Swarmprom\n
\n
\n III Recipies (Docker)\n
- \n 45 Bitwarden\n
- \n 46 BookStack\n
- \n 47 Calibre-Web\n
- \n 48 Collabora Online\n
- \n 49 Ghost\n
- \n 50 GitLab\n
- \n 51 Gitlab Runner\n
- \n 52 Gollum\n
- \n 53 InstaPy\n
- \n 54 KeyCloak\n
- \n 55 Create KeyCloak Users\n
- \n 56 Authenticate KeyCloak against OpenLDAP\n
- \n 57 Add OIDC Provider to KeyCloak\n
- \n 58 OpenLDAP\n
- \n 59 Mail Server\n
- \n 60 Minio\n
- \n 61 Piwik\n
- \n 62 Portainer\n
- \n 63 Realms\n
- \n 64 Tiny Tiny RSS\n
- \n 65 Wallabag\n
- \n 66 Wekan\n
- \n 67 Wetty\n
\n
\n IV Reference\n
- \n 68 OAuth proxy\n
- \n 69 Data layout\n
- \n 70 Networks\n
- \n 71 Introduction\n
- \n 72 OpenVPN\n
- \n 73 Troubleshooting\n
\n
\n Notes\n

\n1 What is this?

\n\n

Funky Penguin’s “Geek Cookbook” is a collection of how-to guides for establishing your own container-based self-hosting platform, using either Docker Swarm or Kubernetes.

\n\n

Running such a platform enables you to run self-hosted tools such as AutoPirate (Radarr, Sonarr, NZBGet and friends), Plex, NextCloud, and includes elements such as:

\n\n

\nAutomatic SSL-secured access to all services (with LetsEncrypt)
\nSSO / authentication layer to protect unsecured / vulnerable services
\nAutomated backup of configuration and data
\nMonitoring and metrics collection, graphing and alerting

\n\n

Recent updates and additions are posted on the CHANGELOG, and there’s a friendly community of like-minded geeks in the Discord server.

\n\n

\n1.1 Who is this for?

\n\n

You already have a familiarity with concepts such as virtual machines, Docker containers, LetsEncrypt SSL certificates, databases, and command-line interfaces.

\n\n

You’ve probably played with self-hosting some mainstream apps yourself, like Plex, NextCloud, Wordpress or Ghost.

\n\n

\n1.2 Why should I read this?

\n\n

So if you’re familiar enough with the concepts above, and you’ve done self-hosting before, why would you read any further?

\n\n

You want to upskill. You want to work with container orchestration, Prometheus and Grafana, Kubernetes
You want to play. You want a safe sandbox to test new tools, keeping the ones you want and tossing the ones you don’t.
You want reliability. Once you go from playing with a tool to actually using it, you want it to be available when you need it. Having to “quickly ssh into the basement server and restart plex” doesn’t cut it when you finally convince your wife to sit down with you to watch sci-fi.

\n\n <blockquote class=”twitter-tweet”><p lang=”en” dir=”ltr”>.<a href=”https://twitter.com/funkypenguin?ref_src=twsrc%5Etfw”>@funkypenguin</a> One of the surprising realizations from following Funky Penguins cookbooks <a href=”https://t.co/XvZ2qLJa5N”>https://t.co/XvZ2qLJa5N</a> for so long is how useful the recipes are for people just getting started with containers and how it gives them real, interesting usecases to attach to their learning</p>— DevOps Daniel (@DanielSHouston) <a href=”https://twitter.com/DanielSHouston/status/1213419203379773442?ref_src=twsrc%5Etfw”>January 4, 2020</a></blockquote> <script async src=”https://platform.twitter.com/widgets.js” charset=”utf-8”></script>
\n

\n1.3 What have you done for me lately? (CHANGELOG)

\n\n

Check out recent change at CHANGELOG

\n\n

\n1.4 What do you want from me?

\n\n

I want your support, either in the financial sense, or as a member of our friendly geek community (or both!)

\n\n

\nGet in touch

\n\n

Come and say hi to me and the friendly geeks in the Discord chat or the Discourse forums - say hi, ask a question, or suggest a new recipe!
Tweet me up, I’m @funkypenguin!
\nContact me by a variety of channels

\n\n

\n Sponsor / Patronize me

\n\n

The best way to support this work is to become a GitHub Sponsor / Patreon patron. You get:

\n\n

warm fuzzies,
access to the pre-mix repo,
an anonymous plug you can pull at any time,
and a bunch more loot based on tier

\n\n

.. and I get some pocket money every month to buy wine, cheese, and cryptocurrency!

\n\n

Impulsively click here (NOW quick do it!) to sponsor me via GitHub, or patronize me via Patreon!

\n\n

\nWork with me

\n\n

Need some Cloud / Microservices / DevOps / Infrastructure design work done? I’m a full-time AWS-certified consultant, this stuff is my bread and butter! :breadfork_and_knife: Get in touch, and let’s talk business!

\n\n By the time I had enlisted Funky Penguin’s help, I’d architected myself into a bit of a nightmare with Kubernetes. I knew what I wanted to achieve, but I’d made a mess of it. Funky Penguin (David) was able to jump right in and offer a vital second-think on everything I’d done, pointing out where things could be simplified and streamlined, and better alternatives.
\n He unblocked me on all the technical hurdles to launching my SaaS in GKE!
\n With him delivering the container/Kubernetes architecture and helm CI/CD workflow, I was freed up to focus on coding and design, which fast-tracked me to launching on time. And now I have a simple deployment process that is easy for me to execute and maintain as a solo founder.
\n I have no hesitation in recommending him for your project, and I’ll certainly be calling on him again in the future.
\n – John McDowall, Founder, kiso.io
\n

\nBuy my book

\n\n

I’m publishing the Geek Cookbook as a formal eBook (PDF, mobi, epub), on Leanpub (https://leanpub.com/geek-cookbook). Check it out!

\n\n\n

\n2 How to read this book

\n\n

\n2.1 Structure

\n\n

“Recipes” generally follow on from each other. I.e., if a particular recipe requires a mail server, that mail server would have been described in an earlier recipe.
Each recipe contains enough detail in a single page to take a project from start to completion.
When there are optional add-ons/integrations possible to a project (i.e., the addition of “smart LED bulbs” to Home Assistant), this will be reflected either as a brief “Chef’s note” after the recipe, or if they’re substantial enough, as a sub-page of the main project

\n\n

\n2.2 Conventions

\n\n

When creating swarm networks, we always explicitly set the subnet in the overlay network, to avoid potential conflicts (which docker won’t prevent, but which will generate errors) (https://github.com/moby/moby/issues/26912)

\n\n\n

\n3 CHANGELOG

\n\n\n\n

Email : Sign up here (double-opt-in) to receive email updates on new and improve recipes!
Mastodon: https://mastodon.social/@geekcookbook_changes
RSS: https://mastodon.social/@geekcookbook_changes.rss
The #changelog channel in our Discord server\n

\n\n

\n3.2 Recent additions to work-in-progress

\n\n

Kubernetes recipes for UniFi controller, Miniflux, Kanboard and PrivateBin coming in March! (19 Mar 2019)

\n\n

\n3.3 Recently added recipes

Overhauled Ceph (Shared Storage) recipe for Ceph Octopus (v15) (25 May 2020)
Added recipe for making your own DIY Kubernetes Cluster (14 December 2019)
Added recipe for authenticating Traefik Forward Auth against KeyCloak (16 May 2019)
Added Bitwarden, an awesome open-source password manager, with great mobile sync support (14 May 2019)
Added Traefik Forward Auth, replacing function of multiple oauth_proxies with a single, 7MB Go application, which can authenticate against Google, KeyCloak, and other OIDC providers (10 May 2019)

\n\n

\n3.4 Recent improvements

\n\n

Added recipe for automated snapshots of Kubernetes Persistent Volumes, instructions for using Helm, and recipe for deploying Traefik, which completes the Kubernetes cluster design! (9 Feb 2019)
Added detailed description (and diagram) of our Kubernetes design, plus a simple load-balancer design to avoid the complexities/costs of permitting ingress access to a cluster (7 Feb 2019)
Added an introductory/explanatory page, including a children’s story, on Kubernetes (29 Jan 2019)
\nNextCloud updated to fix CalDAV/CardDAV service discovery behind Traefik reverse proxy (12 Dec 2018)

\n\n\n

\n4 Welcome to Funky Penguin’s Geek Cookbook

\n\n

\n4.1 Hello world,

\n\n

I’m David.

\n\n

I’m a contracting IT consultant, with a broad range of experience and skills. I’m an AWS Certified Solution Architect (Professional), a remote worker, I’ve had a book published, and I blog on topics that interest me.

\n\n

\n4.2 Why Funky Penguin?

\n\n

My first “real” job, out of high-school, was working the IT helpdesk in a typical pre-2000 organization in South Africa. I enjoyed experimenting with Linux, and cut my teeth by replacing the organization’s Exchange 5.5 mail platform with a 15-site qmail-ldap cluster, with amavis virus-scanning.

\n\n

One of our suppliers asked me to quote to do the same for their organization. With nothing to loose, and half-expecting to be turned down, I quoted a generous fee, and chose a cheeky company name. The supplier immediately accepted my quote, and the name (“Funky Penguin”) stuck.

\n\n

\n4.3 Technical Documentation

\n\n

During the same “real” job above, I wanted to deploy jabberd, for internal instant messaging within the organization, and as a means to control the sprawl of ad-hoc instant-messaging among staff, using ICQ, MSN, and Yahoo Messenger.

\n\n

To get management approval to deploy, I wrote a logger (with web UI) for jabber conversations (Bandersnatch), and a 75-page user manual (in Docbook XML) for a spunky Russian WinXP jabber client, JAJC.

\n\n

Due to my contributions to phpList, I was approached in 2011 by Packt Publishing, to write a book about using PHPList.

\n\n

\n4.4 Work with me

\n\n

Need some Cloud / Microservices / DevOps / Infrastructure design work done? I’m a full-time [AWS-certified][aws_cert] consultant, this stuff is my bread and butter! :breadfork_and_knife: [Get in touch][contact], and let’s talk business!

\n\n

[plex]:\t https://www.plex.tv/
[nextcloud]: https://nextcloud.com/
[wordpress]:\t https://wordpress.org/
[ghost]:\t https://ghost.io/
[discord]: http://chat.funkypenguin.co.nz
[patreon]:\t https://www.patreon.com/bePatron?u=6982506
[github_sponsor]: https://github.com/sponsors/funkypenguin
[github]: https://github.com/sponsors/funkypenguin
[discourse]:\t https://discourse.geek-kitchen.funkypenguin.co.nz/
[twitter]:\t https://twitter.com/funkypenguin
[contact]:\t https://www.funkypenguin.co.nz
[aws_cert]:\t https://www.certmetrics.com/amazon/public/badge.aspx?i=4&t=c&d=2019-02-22&ci=AWS00794574

\n4.5 Contact Me

\n\n

Contact me by:

\n\n

Jumping into our Discord server\n
Email (davidy@funkypenguin.co.nz)
Twitter (@funkypenguin)

\n\n

Or by using the form below:

\n\n

\n\n\n

\nI HA Docker Swarm

\n\n

This section introduces the HA Docker Swarm, which will be the basis for all the recipes discussed.

\n\n\n

\n5 Design

\n\n

In the design described below, our “private cloud” platform is:

\n\n

\nHighly-available (can tolerate the failure of a single component)
\nScalable (can add resource or capacity as required)
\nPortable (run it on your garage server today, run it in AWS tomorrow)
\nSecure (access protected with LetsEncrypt certificates and optional OIDC with 2FA)
\nAutomated (requires minimal care and feeding)

\n\n

\n5.1 Design Decisions

\n\n

Where possible, services will be highly available.

\n\n

This means that:

\n\n

At least 3 docker swarm manager nodes are required, to provide fault-tolerance of a single failure.
\nCeph is employed for share storage, because it too can be made tolerant of a single failure.

\n\n An exception to the 3-nodes decision is running a single-node configuration. If you only have one node, then obviously your swarm is only as resilient as that node. It’s still a perfectly valid swarm configuration, ideal for starting your self-hosting journey. In fact, under the single-node configuration, you don’t need ceph either, and you can simply use the local volume on your host for storage. You’ll be able to migrate to ceph/more nodes if/when you expand.
\n

Where multiple solutions to a requirement exist, preference will be given to the most portable solution.

\n\n

This means that:

\n\n

Services are defined using docker-compose v3 YAML syntax
Services are portable, meaning a particular stack could be shut down and moved to a new provider with minimal effort.

\n\n

\n5.2 Security

\n\n

Under this design, the only inbound connections we’re permitting to our docker swarm in a minimal configuration (you may add custom services later, like UniFi Controller) are:

\n\n

\nNetwork Flows

\n\n

\nHTTP (TCP 80) : Redirects to https
\nHTTPS (TCP 443) : Serves individual docker containers via SSL-encrypted reverse proxy

\n\n

\nAuthentication

\n\n

Where the hosted application provides a trusted level of authentication (i.e., NextCloud), or where the application requires public exposure (i.e. Privatebin), no additional layer of authentication will be required.
Where the hosted application provides inadequate (i.e. NZBGet) or no authentication (i.e. Gollum), a further authentication against an OAuth provider will be required.

\n\n

\n5.3 High availability

\n\n

\nNormal function

\n\n

Assuming a 3-node configuration, under normal circumstances the following is illustrated:

\n\n

All 3 nodes provide shared storage via Ceph, which is provided by a docker container on each node.
All 3 nodes participate in the Docker Swarm as managers.
The various containers belonging to the application “stacks” deployed within Docker Swarm are automatically distributed amongst the swarm nodes.
Persistent storage for the containers is provide via cephfs mount.
The traefik service (in swarm mode) receives incoming requests (on HTTP and HTTPS), and forwards them to individual containers. Traefik knows the containers names because it’s able to read the docker socket.
All 3 nodes run keepalived, at varying priorities. Since traefik is running as a swarm service and listening on TCP 80/443, requests made to the keepalived VIP and arriving at any of the swarm nodes will be forwarded to the traefik container (no matter which node it’s on), and then onto the target backend.

\n\n

\n\n\n

\nNode failure

\n\n

In the case of a failure (or scheduled maintenance) of one of the nodes, the following is illustrated:

\n\n

The failed node no longer participates in Ceph, but the remaining nodes provide enough fault-tolerance for the cluster to operate.
The remaining two nodes in Docker Swarm achieve a quorum and agree that the failed node is to be removed.
The (possibly new) leader manager node reschedules the containers known to be running on the failed node, onto other nodes.
The traefik service is either restarted or unaffected, and as the backend containers stop/start and change IP, traefik is aware and updates accordingly.
The keepalived VIP continues to function on the remaining nodes, and docker swarm continues to forward any traffic received on TCP 80/443 to the appropriate node.

\n\n

\n\n\n

\nNode restore

\n\n

When the failed (or upgraded) host is restored to service, the following is illustrated:

\n\n

Ceph regains full redundancy
Docker Swarm managers become aware of the recovered node, and will use it for scheduling new containers
Existing containers which were migrated off the node are not migrated backend
Keepalived VIP regains full redundancy

\n\n

\n\n\n

\nTotal cluster failure

\n\n

A day after writing this, my environment suffered a fault whereby all 3 VMs were unexpectedly and simultaneously powered off.

\n\n

Upon restore, docker failed to start on one of the VMs due to local disk space issue¹. However, the other two VMs started, established the swarm, mounted their shared storage, and started up all the containers (services) which were managed by the swarm.

\n\n

In summary, although I suffered an unplanned power outage to all of my infrastructure, followed by a failure of a third of my hosts… ==all my platforms are 100% available with absolutely no manual intervention==.

\n\n

\n5.4 Chef’s Notes

\n\n\n

\n6 Nodes

\n\n

Let’s start building our cluster. You can use either bare-metal machines or virtual machines - the configuration would be the same. To avoid confusion, I’ll be referring to these as “nodes” from now on.

\n\n In 2017, I initially chose the “Atomic” CentOS/Fedora image for the swarm hosts, but later found its outdated version of Docker to be problematic with advanced features like GPU transcoding (in Plex), Swarmprom, etc. In the end, I went mainstream and simply preferred a modern Ubuntu installation.
\n

\n6.1 Ingredients

\n\n New in this recipe:
\n * [ ] 3 x nodes (bare-metal or VMs), each with:
* A mainstream Linux OS (tested on either CentOS 7+ or Ubuntu 16.04+)
* At least 2GB RAM
* At least 20GB disk space (but it’ll be tight)
* [ ] Connectivity to each other within the same subnet, and on a low-latency link (i.e., no WAN links)
\n

\n6.2 Preparation

\n\n

\nPermit connectivity

\n\n

Most modern Linux distributions include firewall rules which only only permit minimal required incoming connections (like SSH). We’ll want to allow all traffic between our nodes. The steps to achieve this in CentOS/Ubuntu are a little different…

\n\n

\nCentOS

\n\n

Add something like this to /etc/sysconfig/iptables:

\n\n\n

# Allow all inter-node communication\n-A INPUT -s 192.168.31.0/24 -j ACCEPT\n

\n\n\n\n\n

And restart iptables with systemctl restart iptables

\n\n

\nUbuntu

\n\n

Install the (non-default) persistent iptables tools, by running apt-get install iptables-persistent, establishing some default rules (dkpg will prompt you to save current ruleset), and then add something like this to /etc/iptables/rules.v4:

\n\n\n

# Allow all inter-node communication\n-A INPUT -s 192.168.31.0/24 -j ACCEPT\n

\n\n\n\n\n

And refresh your running iptables rules with iptables-restore < /etc/iptables/rules.v4

\n\n

\nEnable hostname resolution

\n\n

Depending on your hosting environment, you may have DNS automatically setup for your VMs. If not, it’s useful to set up static entries in /etc/hosts for the nodes. For example, I setup the following:

\n\n\n

192.168.31.11   ds1     ds1.funkypenguin.co.nz\n192.168.31.12   ds2     ds2.funkypenguin.co.nz\n192.168.31.13   ds3     ds3.funkypenguin.co.nz\n

\n\n\n\n\n

\nSet timezone

\n\n

Set your local timezone, by running:

\n\n\n

ln -sf /usr/share/zoneinfo/<your timezone> /etc/localtime\n

\n\n\n\n\n

\n6.3 Serving

\n\n

After completing the above, you should have:

\n\n Deployed in this recipe:
\n * [X] 3 x nodes (bare-metal or VMs), each with:
* A mainstream Linux OS (tested on either CentOS 7+ or Ubuntu 16.04+)
* At least 2GB RAM
* At least 20GB disk space (but it’ll be tight)
* [X] Connectivity to each other within the same subnet, and on a low-latency link (i.e., no WAN links)
\n

\n6.4 Chef’s Notes

\n\n\n

\n7 Shared Storage (Ceph)

\n\n

While Docker Swarm is great for keeping containers running (and restarting those that fail), it does nothing for persistent storage. This means if you actually want your containers to keep any data persistent across restarts (hint: you do!), you need to provide shared storage to every docker node.

\n\n

\n\n\n

\n7.1 Ingredients

\n\n 3 x Virtual Machines (configured earlier), each with:
\n * [X] Support for “modern” versions of Python and LVM
* [X] At least 1GB RAM
* [X] At least 20GB disk space (but it’ll be tight)
* [X] Connectivity to each other within the same subnet, and on a low-latency link (i.e., no WAN links)
* [X] A second disk dedicated to the Ceph OSD
* [X] Each node should have the IP of every other participating node hard-coded in /etc/hosts (including its own IP)
\n

\n7.2 Preparation

\n\n Earlier iterations of this recipe (based on Ceph Jewel) required significant manual effort to install Ceph in a Docker environment. In the 2+ years since Jewel was released, significant improvements have been made to the ceph “deploy-in-docker” process, including the introduction of the cephadm tool. Cephadm is the tool which now does all the heavy lifting, below, for the current version of ceph, codenamed “Octopus”.
\n

\nPick a master node

\n\n

One of your nodes will become the cephadm “master” node. Although all nodes will participate in the Ceph cluster, the master node will be the node which we bootstrap ceph on. It’s also the node which will run the Ceph dashboard, and on which future upgrades will be processed. It doesn’t matter which node you pick, and the cluster itself will operate in the event of a loss of the master node (although you won’t see the dashboard)

\n\n

\nInstall cephadm on master node

\n\n

Run the following on the ==master== node:

\n\n\n

MYIP=`ip route get 1.1.1.1 | grep -oP 'src \\K\\S+'`\ncurl --silent --remote-name --location https://github.com/ceph/ceph/raw/octop\\\nus/src/cephadm/cephadm\nchmod +x cephadm\nmkdir -p /etc/ceph\n./cephadm bootstrap --mon-ip $MYIP\n

\n\n\n\n\n

The process takes about 30 seconds, after which, you’ll have a MVC (Minimum Viable Cluster)¹, encompassing a single monitor and mgr instance on your chosen node. Here’s the complete output from a fresh install:

\n\n

??? “Example output from a fresh cephadm bootstrap”

\n\n

    root@raphael:~# MYIP=`ip route get 1.1.1.1 | grep -oP 'src \\K\\S+'`\n    root@raphael:~# curl --silent --remote-name --location https://github.com\\\n/ceph/ceph/raw/octopus/src/cephadm/cephadm\n\n    root@raphael:~# chmod +x cephadm\n    root@raphael:~# mkdir -p /etc/ceph\n    root@raphael:~# ./cephadm bootstrap --mon-ip $MYIP\n    INFO:cephadm:Verifying podman|docker is present...\n    INFO:cephadm:Verifying lvm2 is present...\n    INFO:cephadm:Verifying time synchronization is in place...\n    INFO:cephadm:Unit systemd-timesyncd.service is enabled and running\n    INFO:cephadm:Repeating the final host check...\n    INFO:cephadm:podman|docker (/usr/bin/docker) is present\n    INFO:cephadm:systemctl is present\n    INFO:cephadm:lvcreate is present\n    INFO:cephadm:Unit systemd-timesyncd.service is enabled and running\n    INFO:cephadm:Host looks OK\n    INFO:root:Cluster fsid: bf3eff78-9e27-11ea-b40a-525400380101\n    INFO:cephadm:Verifying IP 192.168.38.101 port 3300 ...\n    INFO:cephadm:Verifying IP 192.168.38.101 port 6789 ...\n    INFO:cephadm:Mon IP 192.168.38.101 is in CIDR network 192.168.38.0/24\n    INFO:cephadm:Pulling latest docker.io/ceph/ceph:v15 container...\n    INFO:cephadm:Extracting ceph user uid/gid from container image...\n    INFO:cephadm:Creating initial keys...\n    INFO:cephadm:Creating initial monmap...\n    INFO:cephadm:Creating mon...\n    INFO:cephadm:Waiting for mon to start...\n    INFO:cephadm:Waiting for mon...\n    INFO:cephadm:mon is available\n    INFO:cephadm:Assimilating anything we can from ceph.conf...\n    INFO:cephadm:Generating new minimal ceph.conf...\n    INFO:cephadm:Restarting the monitor...\n    INFO:cephadm:Setting mon public_network...\n    INFO:cephadm:Creating mgr...\n    INFO:cephadm:Wrote keyring to /etc/ceph/ceph.client.admin.keyring\n    INFO:cephadm:Wrote config to /etc/ceph/ceph.conf\n    INFO:cephadm:Waiting for mgr to start...\n    INFO:cephadm:Waiting for mgr...\n    INFO:cephadm:mgr not available, waiting (1/10)...\n    INFO:cephadm:mgr not available, waiting (2/10)...\n    INFO:cephadm:mgr not available, waiting (3/10)...\n    INFO:cephadm:mgr is available\n    INFO:cephadm:Enabling cephadm module...\n    INFO:cephadm:Waiting for the mgr to restart...\n    INFO:cephadm:Waiting for Mgr epoch 5...\n    INFO:cephadm:Mgr epoch 5 is available\n    INFO:cephadm:Setting orchestrator backend to cephadm...\n    INFO:cephadm:Generating ssh key...\n    INFO:cephadm:Wrote public SSH key to to /etc/ceph/ceph.pub\n    INFO:cephadm:Adding key to root@localhost's authorized_keys...\n    INFO:cephadm:Adding host raphael...\n    INFO:cephadm:Deploying mon service with default placement...\n    INFO:cephadm:Deploying mgr service with default placement...\n    INFO:cephadm:Deploying crash service with default placement...\n    INFO:cephadm:Enabling mgr prometheus module...\n    INFO:cephadm:Deploying prometheus service with default placement...\n    INFO:cephadm:Deploying grafana service with default placement...\n    INFO:cephadm:Deploying node-exporter service with default placement...\n    INFO:cephadm:Deploying alertmanager service with default placement...\n    INFO:cephadm:Enabling the dashboard module...\n    INFO:cephadm:Waiting for the mgr to restart...\n    INFO:cephadm:Waiting for Mgr epoch 13...\n    INFO:cephadm:Mgr epoch 13 is available\n    INFO:cephadm:Generating a dashboard self-signed certificate...\n    INFO:cephadm:Creating initial admin user...\n    INFO:cephadm:Fetching dashboard port number...\n    INFO:cephadm:Ceph Dashboard is now available at:\n\n            URL: https://raphael:8443/\n            User: admin\n        Password: mid28k0yg5\n\n    INFO:cephadm:You can access the Ceph CLI with:\n\n        sudo ./cephadm shell --fsid bf3eff78-9e27-11ea-b40a-525400380101 -c /\\\netc/ceph/ceph.conf -k /etc/ceph/ceph.client.admin.keyring\n\n    INFO:cephadm:Please consider enabling telemetry to help improve Ceph:\n\n        ceph telemetry on\n\n    For more information see:\n\n        https://docs.ceph.com/docs/master/mgr/telemetry/\n\n    INFO:cephadm:Bootstrap complete.\n    root@raphael:~#\n

\n\n\n\n\n

\nPrepare other nodes

\n\n

It’s now necessary to tranfer the following files to your ==other== nodes, so that cephadm can add them to your cluster, and so that they’ll be able to mount the cephfs when we’re done:

\n\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n\n

Path on master	Path on non-master
`/etc/ceph/ceph.conf`	`/etc/ceph/ceph.conf`
`/etc/ceph/ceph.client.admin.keyring`	`/etc/ceph/ceph.client.admin.keyring`
`/etc/ceph/ceph.pub`	\n`/root/.ssh/authorized_keys` (append to anything existing)

\n\n

Back on the ==master== node, run ceph orch host add <node-name> once for each other node you want to join to the cluster. You can validate the results by running ceph orch host ls

\n\n Not really. Docker is inherently insecure at the host-level anyway (think what would happen if you launched a global-mode stack with a malicious container image which mounted /root/.ssh), so worrying about cephadm seems a little barn-door-after-horses-bolted. If you take host-level security seriously, consider switching to Kubernetes :)
\n

\nAdd OSDs

\n\n

Now the best improvement since the days of ceph-deploy and manual disks.. on the ==master== node, run ceph orch apply osd --all-available-devices. This will identify any unloved (unpartitioned, unmounted) disks attached to each participating node, and configure these disks as OSDs.

\n\n

\nSetup CephFS

\n\n

On the ==master== node, create a cephfs volume in your cluster, by running ceph fs volume create data. Ceph will handle the necessary orchestration itself, creating the necessary pool, mds daemon, etc.

\n\n

You can watch the progress by running ceph fs ls (to see the fs is configured), and ceph -s to wait for HEALTH_OK

\n\n

\nMount CephFS volume

\n\n

On ==every== node, create a mountpoint for the data, by running mkdir /var/data, add an entry to fstab to ensure the volume is auto-mounted on boot, and ensure the volume is actually mounted if there’s a network / boot delay getting access to the gluster volume:

\n\n\n

mkdir /var/data\n\nMYNODES=\"<node1>,<node2>,<node3>\" # Add your own nodes here, comma-delimited\nMYHOST=`ip route get 1.1.1.1 | grep -oP 'src \\K\\S+'`\necho -e \"\n# Mount cephfs volume \\n\nraphael,donatello,leonardo:/ /var/data ceph name=admin,noatime,_netdev 0 0\" >\\\n> /etc/fstab\nmount -a\n

\n\n\n\n\n

\n7.3 Serving

\n\n

\nSprinkle with tools

\n\n

Although it’s possible to use cephadm shell to exec into a container with the necessary ceph tools, it’s more convenient to use the native CLI tools. To this end, on each node, run the following, which will install the appropriate apt repository, and install the latest ceph CLI tools:

\n\n\n

curl -L https://download.ceph.com/keys/release.asc | sudo apt-key add -\ncephadm add-repo --release octopus\ncephadm install ceph-common\n

\n\n\n\n\n

\nDrool over dashboard

\n\n

Ceph now includes a comprehensive dashboard, provided by the mgr daemon. The dashboard will be accessible at https://[IP of your ceph master node]:8443, but you’ll need to run ceph dashboard ac-user-create <username> <password> administrator first, to create an administrator account:

\n\n\n

root@raphael:~# ceph dashboard ac-user-create batman supermansucks administra\\\ntor\n{\"username\": \"batman\", \"password\": \"$2b$12$3HkjY85mav.dq3HHAZiWP.KkMiuoV2TURZ\\\nFH.6WFfo/BPZCT/0gr.\", \"roles\": [\"administrator\"], \"name\": null, \"email\": null\\\n, \"lastUpdate\": 1590372281, \"enabled\": true, \"pwdExpirationDate\": null, \"pwdU\\\npdateRequired\": false}\nroot@raphael:~#\n

\n\n\n\n\n

\n7.4 Summary

\n\n

What have we achieved?

\n\n Created:
\n * [X] Persistent storage available to every node
* [X] Resiliency in the event of the failure of a single node
* [X] Beautiful dashboard
\n

\n7.5 The easy, 5-minute install

\n\n

I share (with [sponsors][github_sponsor] and [patrons][patreon]) a private “premix” GitHub repository, which includes an ansible playbook for deploying the entire Geek’s Cookbook stack, automatically. This means that members can create the entire environment with just a git pull and an ansible-playbook deploy.yml

\n\n

Here’s a screencast of the playbook in action. I sped up the boring parts, it actually takes ==5 min== (you can tell by the timestamps on the prompt):

\n\n

[patreon]:\t https://www.patreon.com/bePatron?u=6982506
[github_sponsor]: https://github.com/sponsors/funkypenguin

\n\n

\n7.6 Chef’s Notes

\n\n\n

\n8 Shared Storage (GlusterFS)

\n\n

\n\n This recipe is deprecated. It didn’t work well in 2017, and it’s not likely to work any better now. It remains here as a reference. I now recommend the use of Ceph for shared storage instead. - 2019 Chef
\n

\n8.1 Design

\n\n

\nWhy GlusterFS?

\n\n

This GlusterFS recipe was my original design for shared storage, but I found it to be flawed, and I replaced it with a design which employs Ceph instead. This recipe is an alternate to the Ceph design, if you happen to prefer GlusterFS.

\n\n

\n8.2 Ingredients

\n\n 3 x Virtual Machines (configured earlier), each with:
\n * [X] CentOS/Fedora Atomic
* [X] At least 1GB RAM
* [X] At least 20GB disk space (but it’ll be tight)
* [X] Connectivity to each other within the same subnet, and on a low-latency link (i.e., no WAN links)
* [ ] A second disk, or adequate space on the primary disk for a dedicated data partition
\n

\n8.3 Preparation

\n\n

\nCreate Gluster “bricks”

\n\n

To build our Gluster volume, we need 2 out of the 3 VMs to provide one “brick”. The bricks will be used to create the replicated volume. Assuming a replica count of 2 (i.e., 2 copies of the data are kept in gluster), our total number of bricks must be divisible by our replica count. (I.e., you can’t have 3 bricks if you want 2 replicas. You can have 4 though - We have to have minimum 3 swarm manager nodes for fault-tolerance, but only 2 of those nodes need to run as gluster servers.)

\n\n

On each host, run a variation following to create your bricks, adjusted for the path to your disk.

\n\n\n

(\necho o # Create a new empty DOS partition table\necho n # Add a new partition\necho p # Primary partition\necho 1 # Partition number\necho   # First sector (Accept default: 1)\necho   # Last sector (Accept default: varies)\necho w # Write changes\n) | sudo fdisk /dev/vdb\n\nmkfs.xfs -i size=512 /dev/vdb1\nmkdir -p /var/no-direct-write-here/brick1\necho '' >> /etc/fstab >> /etc/fstab\necho '# Mount /dev/vdb1 so that it can be used as a glusterfs volume' >> /etc\\\n/fstab\necho '/dev/vdb1 /var/no-direct-write-here/brick1 xfs defaults 1 2' >> /etc/fs\\\ntab\nmount -a && mount\n

\n\n\n\n\n Atomic uses LVM to store docker data, and automatically grows Docker’s volumes as requried. If you commit all your free LVM space to your brick, you’ll quickly find (as I did) that docker will start to fail with error messages about insufficient space. If you’re going to slice off a portion of your LVM space in /dev/atomicos, make sure you leave enough space for Docker storage, where “enough” depends on how much you plan to pull images, make volumes, etc. I ate through 20GB very quickly doing development, so I ended up provisioning 50GB for atomic alone, with a separate volume for the brick.
\n

\nCreate glusterfs container

\n\n

Atomic doesn’t include the Gluster server components. This means we’ll have to run glusterd from within a container, with privileged access to the host. Although convoluted, I’ve come to prefer this design since it once again makes the OS “disposable”, moving all the config into containers and code.

\n\n

Run the following on each host:

\n\n\n

docker run \\\n   -h glusterfs-server \\\n   -v /etc/glusterfs:/etc/glusterfs:z \\\n   -v /var/lib/glusterd:/var/lib/glusterd:z \\\n   -v /var/log/glusterfs:/var/log/glusterfs:z \\\n   -v /sys/fs/cgroup:/sys/fs/cgroup:ro \\\n   -v /var/no-direct-write-here/brick1:/var/no-direct-write-here/brick1 \\\n   -d --privileged=true --net=host \\\n   --restart=always \\\n   --name=\"glusterfs-server\" \\\n   gluster/gluster-centos\n

\n\n\n\n\n

\nCreate trusted pool

\n\n

On a single node (doesn’t matter which), run docker exec -it glusterfs-server bash to launch a shell inside the container.

\n\n

From the node, run gluster peer probe <other host>.

\n\n

Example output:

\n\n\n

[root@glusterfs-server /]# gluster peer probe ds1\npeer probe: success.\n[root@glusterfs-server /]#\n

\n\n\n\n\n

Run gluster peer status on both nodes to confirm that they’re properly connected to each other:

\n\n

Example output:

\n\n\n

[root@glusterfs-server /]# gluster peer status\nNumber of Peers: 1\n\nHostname: ds3\nUuid: 3e115ba9-6a4f-48dd-87d7-e843170ff499\nState: Peer in Cluster (Connected)\n[root@glusterfs-server /]#\n

\n\n\n\n\n

\nCreate gluster volume

\n\n

Now we create a replicated volume out of our individual “bricks”.

\n\n

Create the gluster volume by running:

\n\n\n

gluster volume create gv0 replica 2 \\\n server1:/var/no-direct-write-here/brick1 \\\n server2:/var/no-direct-write-here/brick1\n

\n\n\n\n\n

Example output:

\n\n\n

[root@glusterfs-server /]# gluster volume create gv0 replica 2 ds1:/var/no-di\\\nrect-write-here/brick1/gv0  ds3:/var/no-direct-write-here/brick1/gv0\nvolume create: gv0: success: please start the volume to access data\n[root@glusterfs-server /]#\n

\n\n\n\n\n

Start the volume by running gluster volume start gv0

\n\n\n

[root@glusterfs-server /]# gluster volume start gv0\nvolume start: gv0: success\n[root@glusterfs-server /]#\n

\n\n\n\n\n

The volume is only present on the host you’re shelled into though. To add the other hosts to the volume, run gluster peer probe <servername>. Don’t probe host from itself.

\n\n

From one other host, run docker exec -it glusterfs-server bash to shell into the gluster-server container, and run gluster peer probe <original server name> to update the name of the host which started the volume.

\n\n

\nMount gluster volume

\n\n

On the host (i.e., outside of the container - type exit if you’re still shelled in), create a mountpoint for the data, by running mkdir /var/data, add an entry to fstab to ensure the volume is auto-mounted on boot, and ensure the volume is actually mounted if there’s a network / boot delay getting access to the gluster volume:

\n\n\n

mkdir /var/data\nMYHOST=`hostname -s`\necho '' >> /etc/fstab >> /etc/fstab\necho '# Mount glusterfs volume' >> /etc/fstab\necho \"$MYHOST:/gv0                /var/data      glusterfs       defaults,_ne\\\ntdev,context=\"system_u:object_r:svirt_sandbox_file_t:s0\"  0  0\"  >> /etc/fsta\\\nb\nmount -a\n

\n\n\n\n\n

For some reason, my nodes won’t auto-mount this volume on boot. I even tried the trickery below, but they stubbornly refuse to automount:

\n\n\n

echo -e \"\\n\\n# Give GlusterFS 10s to start before \\\nmounting\\nsleep 10s && mount -a\" >> /etc/rc.local\nsystemctl enable rc-local.service\n

\n\n\n\n\n

For non-gluster nodes, you’ll need to replace $MYHOST above with the name of one of the gluster hosts (I haven’t worked out how to make this fully HA yet)

\n\n

\n8.4 Serving

\n\n

After completing the above, you should have:

\n\n

[X] Persistent storage available to every node
[X] Resiliency in the event of the failure of a single (gluster) node

\n\n

\n8.5 Chef’s Notes

\n\n

Future enhancements to this recipe include:

\n\n

Migration of shared storage from GlusterFS to Ceph ()#2)
Correct the fact that volumes don’t automount on boot (#3)

\n\n\n

\n9 Keepalived

\n\n

While having a self-healing, scalable docker swarm is great for availability and scalability, none of that is any good if nobody can connect to your cluster.

\n\n

In order to provide seamless external access to clustered resources, regardless of which node they’re on and tolerant of node failure, you need to present a single IP to the world for external access.

\n\n

Normally this is done using a HA loadbalancer, but since Docker Swarm aready provides the load-balancing capabilities (routing mesh), all we need for seamless HA is a virtual IP which will be provided by more than one docker node.

\n\n

This is accomplished with the use of keepalived on at least two nodes.

\n\n

\n9.1 Ingredients

\n\n Already deployed:
\n * [X] At least 2 x swarm nodes
* [X] low-latency link (i.e., no WAN links)
\n New:
\n * [ ] At least 3 x IPv4 addresses (one for each node and one for the virtual IP)
\n

\n9.2 Preparation

\n\n

\nEnable IPVS module

\n\n

On all nodes which will participate in keepalived, we need the “ip_vs” kernel module, in order to permit serivces to bind to non-local interface addresses.

\n\n

Set this up once for both the primary and secondary nodes, by running:

\n\n\n

echo \"modprobe ip_vs\" >> /etc/rc.local\nmodprobe ip_vs\n

\n\n\n\n\n

\nSetup nodes

\n\n

Assuming your IPs are as follows:

\n\n

192.168.4.1 : Primary
192.168.4.2 : Secondary
192.168.4.3 : Virtual

\n\n

Run the following on the primary

\n\n

docker run -d --name keepalived --restart=always \\\n  --cap-add=NET_ADMIN --net=host \\\n  -e KEEPALIVED_UNICAST_PEERS=\"#PYTHON2BASH:['192.168.4.1', '192.168.4.2']\" \\\n  -e KEEPALIVED_VIRTUAL_IPS=192.168.4.3 \\\n  -e KEEPALIVED_PRIORITY=200 \\\n  osixia/keepalived:1.3.5\n

\n\n\n\n\n

And on the secondary:

\n\n

docker run -d --name keepalived --restart=always \\\n  --cap-add=NET_ADMIN --net=host \\\n  -e KEEPALIVED_UNICAST_PEERS=\"#PYTHON2BASH:['192.168.4.1', '192.168.4.2']\" \\\n  -e KEEPALIVED_VIRTUAL_IPS=192.168.4.3 \\\n  -e KEEPALIVED_PRIORITY=100 \\\n  osixia/keepalived:1.3.5\n

\n\n\n\n\n

\n9.3 Serving

\n\n

That’s it. Each node will talk to the other via unicast (no need to un-firewall multicast addresses), and the node with the highest priority gets to be the master. When ingress traffic arrives on the master node via the VIP, docker’s routing mesh will deliver it to the appropriate docker node.

\n\n

\n9.4 Chef’s notes

\n\n

Some hosting platforms (OpenStack, for one) won’t allow you to simply “claim” a virtual IP. Each node is only able to receive traffic targetted to its unique IP, unless certain security controls are disabled by the cloud administrator. In this case, keepalived is not the right solution, and a platform-specific load-balancing solution should be used. In OpenStack, this is Neutron’s “Load Balancer As A Service” (LBAAS) component. AWS, GCP and Azure would likely include similar protections.
More than 2 nodes can participate in keepalived. Simply ensure that each node has the appropriate priority set, and the node with the highest priority will become the master.

\n\n\n

\n10 Docker Swarm Mode

\n\n

For truly highly-available services with Docker containers, we need an orchestration system. Docker Swarm (as defined at 1.13) is the simplest way to achieve redundancy, such that a single docker host could be turned off, and none of our services will be interrupted.

\n\n

\n10.1 Ingredients

\n\n Existing
\n * [X] 3 x nodes (bare-metal or VMs), each with:
* A mainstream Linux OS (tested on either CentOS 7+ or Ubuntu 16.04+)
* At least 2GB RAM
* At least 20GB disk space (but it’ll be tight)
* [X] Connectivity to each other within the same subnet, and on a low-latency link (i.e., no WAN links)
\n

\n10.2 Preparation

\n\n

\nBash auto-completion

\n\n

Add some handy bash auto-completion for docker. Without this, you’ll get annoyed that you can’t autocomplete docker stack deploy <blah> -c <blah.yml> commands.

\n\n\n

cd /etc/bash_completion.d/\ncurl -O https://raw.githubusercontent.com/docker/cli/b75596e1e4d5295ac69b9934\\\nd1bd8aff691a0de8/contrib/completion/bash/docker\n

\n\n\n\n\n

Install some useful bash aliases on each host

\n\n

cd ~\ncurl -O https://raw.githubusercontent.com/funkypenguin/geek-cookbook/master/e\\\nxamples/scripts/gcb-aliases.sh\necho 'source ~/gcb-aliases.sh' >> ~/.bash_profile\n

\n\n\n\n\n

\n10.3 Serving

\n\n

\nRelease the swarm!

\n\n

Now, to launch a swarm. Pick a target node, and run docker swarm init

\n\n

Yeah, that was it. Seriously. Now we have a 1-node swarm.

\n\n\n

[root@ds1 ~]# docker swarm init\nSwarm initialized: current node (b54vls3wf8xztwfz79nlkivt8) is now a manager.\n\nTo add a worker to this swarm, run the following command:\n\n    docker swarm join \\\n    --token SWMTKN-1-2orjbzjzjvm1bbo736xxmxzwaf4rffxwi0tu3zopal4xk4mja0-bsud7\\\nxnvhv4cicwi7l6c9s6l0 \\\n    202.170.164.47:2377\n\nTo add a manager to this swarm, run 'docker swarm join-token manager' and fol\\\nlow the instructions.\n\n[root@ds1 ~]#\n

\n\n\n\n\n

Run docker node ls to confirm that you have a 1-node swarm:

\n\n\n

[root@ds1 ~]# docker node ls\nID                           HOSTNAME                STATUS  AVAILABILITY  MA\\\nNAGER STATUS\nb54vls3wf8xztwfz79nlkivt8 *  ds1.funkypenguin.co.nz  Ready   Active        Le\\\nader\n[root@ds1 ~]#\n

\n\n\n\n\n

Note that when you run docker swarm init above, the CLI output gives youe a command to run to join further nodes to my swarm. This command would join the nodes as workers (as opposed to managers). Workers can easily be promoted to managers (and demoted again), but since we know that we want our other two nodes to be managers too, it’s simpler just to add them to the swarm as managers immediately.

\n\n

On the first swarm node, generate the necessary token to join another manager by running docker swarm join-token manager:

\n\n\n

[root@ds1 ~]# docker swarm join-token manager\nTo add a manager to this swarm, run the following command:\n\n    docker swarm join \\\n    --token SWMTKN-1-2orjbzjzjvm1bbo736xxmxzwaf4rffxwi0tu3zopal4xk4mja0-cfm24\\\nbq2zvfkcwujwlp5zqxta \\\n    202.170.164.47:2377\n\n[root@ds1 ~]#\n

\n\n\n\n\n

Run the command provided on your other nodes to join them to the swarm as managers. After addition of a node, the output of docker node ls (on either host) should reflect all the nodes:

\n\n\n

[root@ds2 davidy]# docker node ls\nID                           HOSTNAME                STATUS  AVAILABILITY  MA\\\nNAGER STATUS\nb54vls3wf8xztwfz79nlkivt8    ds1.funkypenguin.co.nz  Ready   Active        Le\\\nader\nxmw49jt5a1j87a6ihul76gbgy *  ds2.funkypenguin.co.nz  Ready   Active        Re\\\nachable\n[root@ds2 davidy]#\n

\n\n\n\n\n

\nSetup automated cleanup

\n\n

Docker swarm doesn’t do any cleanup of old images, so as you experiment with various stacks, and as updated containers are released upstream, you’ll soon find yourself loosing gigabytes of disk space to old, unused images.

\n\n

To address this, we’ll run the “meltwater/docker-cleanup” container on all of our nodes. The container will clean up unused images after 30 minutes.

\n\n

First, create docker-cleanup.env (mine is under /var/data/config/docker-cleanup), and exclude container images we know we want to keep:

\n\n\n

KEEP_IMAGES=traefik,keepalived,docker-mailserver\nDEBUG=1\n

\n\n\n\n\n

Then create a docker-compose.yml as follows:

\n\n\n

version: \"3\"\n\nservices:\n  docker-cleanup:\n    image: meltwater/docker-cleanup:latest\n    volumes:\n      - /var/run/docker.sock:/var/run/docker.sock\n      - /var/lib/docker:/var/lib/docker\n    networks:\n      - internal\n    deploy:\n      mode: global\n    env_file: /var/data/config/docker-cleanup/docker-cleanup.env\n\nnetworks:\n  internal:\n    driver: overlay\n    ipam:\n      config:\n        - subnet: 172.16.0.0/24\n

\n\n\n\n\n Setup unique static subnets for every stack you deploy. This avoids IP/gateway conflicts which can otherwise occur when you’re creating/removing stacks a lot. See my list here.
\n

Launch the cleanup stack by running docker stack deploy docker-cleanup -c <path-to-docker-compose.yml>

\n\n

\nSetup automatic updates

\n\n

If your swarm runs for a long time, you might find yourself running older container images, after newer versions have been released. If you’re the sort of geek who wants to live on the edge, configure shepherd to auto-update your container images regularly.

\n\n

Create /var/data/config/shepherd/shepherd.env as follows:

\n\n\n

# Don't auto-update Plex or Emby, I might be watching a movie! (Customize thi\\\ns for the containers you _don't_ want to auto-update)\nBLACKLIST_SERVICES=\"plex_plex emby_emby\"\n# Run every 24 hours. Note that SLEEP_TIME appears to be in seconds.\nSLEEP_TIME=86400\n

\n\n\n\n\n

Then create /var/data/config/shepherd/shepherd.yml as follows:

\n\n\n

version: \"3\"\n\nservices:\n  shepherd-app:\n    image: mazzolino/shepherd\n    env_file : /var/data/config/shepherd/shepherd.env\n    volumes:\n      - /var/run/docker.sock:/var/run/docker.sock:ro\n    labels:\n      - \"traefik.enable=false\"\n    deploy:\n      placement:\n        constraints: [node.role == manager]\n

\n\n\n\n\n

Launch shepherd by running docker stack deploy shepherd -c /var/data/config/shepherd/shepherd.yml, and then just forget about it, comfortable in the knowledge that every day, Shepherd will check that your images are the latest available, and if not, will destroy and recreate the container on the latest available image.

\n\n

\nSummary

\n\n

After completing the above, you should have:

\n\n

[X] Docker swarm cluster\n

\n\n

\n10.4 Chef’s Notes

\n\n\n

\n11 Traefik

\n\n

The platforms we plan to run on our cloud are generally web-based, and each listening on their own unique TCP port. When a container in a swarm exposes a port, then connecting to any swarm member on that port will result in your request being forwarded to the appropriate host running the container. (Docker calls this the swarm “routing mesh“)

\n\n

So we get a rudimentary load balancer built into swarm. We could stop there, just exposing a series of ports on our hosts, and making them HA using keepalived.

\n\n

There are some gaps to this approach though:

\n\n

No consideration is given to HTTPS. Implementation would have to be done manually, per-container.
No mechanism is provided for authentication outside of that which the container providers. We may not want to expose every interface on every container to the world, especially if we are playing with tools or containers whose quality and origin are unknown.

\n\n

To deal with these gaps, we need a front-end load-balancer, and in this design, that role is provided by Traefik.

\n\n

\n\n\n

\n11.1 Ingredients

\n\n Existing
\n * [X] Docker swarm cluster with persistent shared storage
\n New
\n * [ ] Access to update your DNS records for manual/automated LetsEncrypt DNS-01 validation, or ingress HTTP/HTTPS for HTTP-01 validation
\n

\n11.2 Preparation

\n\n

\nPrepare the host

\n\n

The traefik container is aware of the other docker containers in the swarm, because it has access to the docker socket at /var/run/docker.sock. This allows traefik to dynamically configure itself based on the labels found on containers in the swarm, which is hugely useful. To make this functionality work on a SELinux-enabled CentOS7 host, we need to add custom SELinux policy.

\n\n The following is only necessary if you’re using SELinux!
\n

Run the following to build and activate policy to permit containers to access docker.sock:

\n\n\n

mkdir ~/dockersock\ncd ~/dockersock\ncurl -O https://raw.githubusercontent.com/dpw/\\\nselinux-dockersock/master/Makefile\ncurl -O https://raw.githubusercontent.com/dpw/\\\nselinux-dockersock/master/dockersock.te\nmake && semodule -i dockersock.pp\n

\n\n\n\n\n

\nPrepare traefik.toml

\n\n

While it’s possible to configure traefik via docker command arguments, I prefer to create a config file (traefik.toml). This allows me to change traefik’s behaviour by simply changing the file, and keeps my docker config simple.

\n\n

Create /var/data/traefik/traefik.toml as follows:

\n\n\n

checkNewVersion = true\ndefaultEntryPoints = [\"http\", \"https\"]\n\n# This section enable LetsEncrypt automatic certificate generation / renewal\n[acme]\nemail = \"<your LetsEncrypt email address>\"\nstorage = \"acme.json\" # or \"traefik/acme/account\" if using KV store\nentryPoint = \"https\"\nacmeLogging = true\nonDemand = true\nOnHostRule = true\n\n# Request wildcard certificates per https://docs.traefik.io/configuration/acm\\\ne/#wildcard-domains\n[[acme.domains]]\n  main = \"*.example.com\"\n  sans = [\"example.com\"]\n\n# Redirect all HTTP to HTTPS (why wouldn't you?)\n[entryPoints]\n  [entryPoints.http]\n  address = \":80\"\n    [entryPoints.http.redirect]\n      entryPoint = \"https\"\n  [entryPoints.https]\n  address = \":443\"\n    [entryPoints.https.tls]\n\n[web]\naddress = \":8080\"\nwatch = true\n\n[docker]\nendpoint = \"tcp://127.0.0.1:2375\"\ndomain = \"example.com\"\nwatch = true\nswarmmode = true\n

\n\n\n\n\n

\nPrepare the docker service config

\n\n “We’ll want an overlay network, independent of our traefik stack, so that we can attach/detach all our other stacks (including traefik) to the overlay network. This way, we can undeploy/redepoly the traefik stack without having to bring every other stack first!” - voice of experience
\n

Create /var/data/config/traefik/traefik.yml as follows:

\n\n\n

version: \"3.2\"\n\n# What is this?\n#\n# This stack exists solely to deploy the traefik_public overlay network, so t\\\nhat\n# other stacks (including traefik-app) can attach to it\n\nservices:\n  scratch:\n    image: scratch\n    deploy:\n      replicas: 0\n    networks:\n      - public\n\nnetworks:\n  public:\n    driver: overlay\n    attachable: true\n    ipam:\n      config:\n        - subnet: 172.16.200.0/24\n

\n\n\n\n\n I share (with my patreon patrons) a private “premix” git repository, which includes necessary docker-compose and env files for all published recipes. This means that patrons can launch any recipe with just a git pull and a docker stack deploy
\n

Create /var/data/config/traefik/traefik-app.yml as follows:

\n\n\n

version: \"3\"\n\nservices:\n  traefik:\n    image: traefik\n    command: --web --docker --docker.swarmmode --docker.watch --docker.domain\\\n=example.com --logLevel=DEBUG\n    # Note below that we use host mode to avoid source nat being applied to o\\\nur ingress HTTP/HTTPS sessions\n    # Without host mode, all inbound sessions would have the source IP of the\\\n swarm nodes, rather than the\n    # original source IP, which would impact logging. If you don't care about\\\n this, you can expose ports the\n    # \"minimal\" way instead\n    ports:\n      - target: 80\n        published: 80\n        protocol: tcp\n        mode: host\n      - target: 443\n        published: 443\n        protocol: tcp\n        mode: host\n      - target: 8080\n        published: 8080\n        protocol: tcp\n    volumes:\n      - /var/run/docker.sock:/var/run/docker.sock:ro\n      - /var/data/config/traefik:/etc/traefik\n      - /var/data/traefik/traefik.log:/traefik.log\n      - /var/data/traefik/acme.json:/acme.json\n    networks:\n      - traefik_public\n    # Global mode makes an instance of traefik listen on _every_ node, so tha\\\nt regardless of which\n    # node the request arrives on, it'll be forwarded to the correct backend \\\nservice.\n    deploy:\n      labels:\n        - \"traefik.enable=false\"\n      mode: global\n      placement:\n        constraints: [node.role == manager]\n      restart_policy:\n        condition: on-failure     \n\nnetworks:\n  traefik_public:\n    external: true\n

\n\n\n\n\n

Docker won’t start a service with a bind-mount to a non-existent file, so prepare an empty acme.json (with the appropriate permissions) by running:

\n\n\n

touch /var/data/traefik/acme.json\nchmod 600 /var/data/traefik/acme.json\n

\n\n\n\n\n Pay attention above. You must set acme.json’s permissions to owner-readable-only, else the container will fail to start with an ID-10T error!
\n

Traefik will populate acme.json itself when it runs, but it needs to exist before the container will start (Chicken, meet egg.)

\n\n

\n11.3 Serving

\n\n

\nLaunch

\n\n

First, launch the traefik stack, which will do nothing other than create an overlay network by running docker stack deploy traefik -c /var/data/traefik/traefik.yml

\n\n\n

[root@kvm ~]# docker stack deploy traefik -c traefik.yml\nCreating network traefik_public\nCreating service traefik_scratch\n[root@kvm ~]#\n

\n\n\n\n\n

Now deploy the traefik appliation itself (which will attach to the overlay network) by running docker stack deploy traefik-app -c /var/data/traefik/traefik-app.yml

\n\n\n

[root@kvm ~]# docker stack deploy traefik-app -c traefik-app.yml\nCreating service traefik-app_app\n[root@kvm ~]#\n

\n\n\n\n\n

Confirm traefik is running with docker stack ps traefik-app:

\n\n\n

[root@kvm ~]# docker stack ps traefik-app\nID                  NAME                                        IMAGE        \\\n       NODE                     DESIRED STATE       CURRENT STATE            \\\nERROR               PORTS\n74uipz4sgasm        traefik-app_app.t4vcm8siwc9s1xj4c2o4orhtx   traefik:alpin\\\ne      kvm.funkypenguin.co.nz   Running             Running 33 seconds ago   \\\n                    *:443->443/tcp,*:80->80/tcp\n[root@kvm ~]#\n

\n\n\n\n\n

\nCheck Traefik Dashboard

\n\n

You should now be able to access your traefik instance on http://<node IP>:8080 - It’ll look a little lonely currently (below), but we’ll populate it as we add recipes :)

\n\n

\"\" — Screenshot of Traefik, post-launch

\n\n\n

\nSummary

\n\n We’ve achieved:
\n * [X] An overlay network to permit traefik to access all future stacks we deploy
* [X] Frontend proxy which will dynamically configure itself for new backend containers
* [X] Automatic SSL support for all proxied resources
\n

\n11.4 Chef’s Notes

\n\n

Did you notice how no authentication was required to view the Traefik dashboard? Eek! We’ll tackle that in the next section, regarding Traefik Forward Authentication!

\n\n\n

\n12 Traefik Forward Auth

\n\n

Now that we have Traefik deployed, automatically exposing SSL access to our Docker Swarm services using LetsEncrypt wildcard certificates, let’s pause to consider that we may not want some services exposed directly to the internet…

\n\n

..Wait, why not? Well, Traefik doesn’t provide any form of authentication, it simply secures the transmission of the service between Docker Swarm and the end user. If you were to deploy a service with no native security (Radarr or Sonarr come to mind), then anybody would be able to use it! Even services which may have a layer of authentication might not be safe to expose publically - often open source projects may be maintained by enthusiasts who happily add extra features, but just pay lip service to security, on the basis that “it’s the user’s problem to secure it in their own network”.

\n\n

To give us confidence that we can access our services, but BadGuys(tm) cannot, we’ll deploy a layer of authentication in front of Traefik, using Forward Authentication. You can use your own KeyCloak instance for authentication, but to lower the barrier to entry, this recipe will assume you’re authenticating against your own Google account.

\n\n

\n12.1 Ingredients

\n\n Existing:
\n * [X] Docker swarm cluster with persistent shared storage
* [X] Traefik configured per design
\n New:
\n * [ ] Client ID and secret from an OpenID-Connect provider (Google, KeyCloak, Microsoft, etc..)
\n

\n12.2 Preparation

\n\n

\nObtain OAuth credentials

\n\n This recipe will demonstrate using Google OAuth for traefik forward authentication, but it’s also possible to use a self-hosted KeyCloak instance - see the KeyCloak OIDC Provider recipe for more details!
\n

Log into https://console.developers.google.com/, create a new project then search for and select “Credentials” in the search bar.

\n\n

Fill out the “OAuth Consent Screen” tab, and then click, “Create Credentials” > “OAuth client ID”. Select “Web Application”, fill in the name of your app, skip “Authorized JavaScript origins” and fill “Authorized redirect URIs” with either all the domains you will allow authentication from, appended with the url-path (e.g. https://radarr.example.com/_oauth, https://radarr.example.com/_oauth, etc), or if you don’t like frustration, use a “auth host” URL instead, like “https://auth.example.com/_oauth” (see below for details)

\n\n

Store your client ID and secret safely - you’ll need them for the next step.

\n\n

\nPrepare environment

\n\n

Create /var/data/config/traefik/traefik-forward-auth.env as follows:

\n\n\n

CLIENT_ID=<your client id>\nCLIENT_SECRET=<your client secret>\nOIDC_ISSUER=https://accounts.google.com\nSECRET=<a random string, make it up>\n# uncomment this to use a single auth host instead of individual redirect_uri\\\ns (recommended but advanced)\n#AUTH_HOST=auth.example.com\nCOOKIE_DOMAINS=example.com\n

\n\n\n\n\n

\nPrepare the docker service config

\n\n

This is a small container, you can simply add the following content to the existing traefik-app.yml deployed in the previous Traefik recipe:

\n\n\n

  traefik-forward-auth:\n    image: funkypenguin/traefik-forward-auth\n    env_file: /var/data/config/traefik/traefik-forward-auth.env\n    networks:\n      - traefik_public\n    # Uncomment these lines if you're using auth host mode\n    #deploy:\n    #  labels:\n    #    - traefik.port=4181\n    #    - traefik.frontend.rule=Host:auth.example.com\n    #    - traefik.frontend.auth.forward.address=http://traefik-forward-auth:\\\n4181\n    #    - traefik.frontend.auth.forward.trustForwardHeader=true\n

\n\n\n\n\n

If you’re not confident that forward authentication is working, add a simple “whoami” test container, to help debug traefik forward auth, before attempting to add it to a more complex container.

\n\n\n

  # This simply validates that traefik forward authentication is working\n  whoami:\n    image: containous/whoami\n    networks:\n      - traefik_public\n    deploy:\n      labels:\n        - traefik.frontend.rule=Host:whoami.example.com\n        - traefik.port=80\n        - traefik.frontend.auth.forward.address=http://traefik-forward-auth:4\\\n181\n        - traefik.frontend.auth.forward.authResponseHeaders=X-Forwarded-User\n        - traefik.frontend.auth.forward.trustForwardHeader=true\n

\n12.3 Serving

\n\n

\nLaunch

\n\n

Redeploy traefik with docker stack deploy traefik-app -c /var/data/traefik/traeifk-app.yml, to launch the traefik-forward-auth container.

\n\n

\nTest

\n\n

Browse to https://whoami.example.com (obviously, customized for your domain and having created a DNS record), and all going according to plan, you should be redirected to a Google login. Once successfully logged in, you’ll be directed to the basic whoami page.

\n\n

\n12.4 Summary

\n\n

What have we achieved? By adding an additional three simple labels to any service, we can secure any service behind our choice of OAuth provider, with minimal processing / handling overhead.

\n\n Created:
\n * [X] Traefik-forward-auth configured to authenticate against an OIDC provider
\n

\n12.5 Chef’s Notes

\n\n

Traefik forward auth replaces the use of oauth_proxy containers found in some of the existing recipes
\n@thomaseddon’s original version of traefik-forward-auth only works with Google currently, but I’ve created a fork of a fork, which implements generic OIDC providers.
I reviewed several implementations of forward authenticators for Traefik, but found most to be rather heavy-handed, or specific to a single auth provider. @thomaseddon’s go-based docker image is 7MB in size, and with the generic OIDC patch (above), it can be extended to work with any OIDC provider.
No, not github natively, but you can ferderate GitHub into KeyCloak, and then use KeyCloak as the OIDC provider.

\n\n\n

\n13 Using Traefik Forward Auth with KeyCloak

\n\n

While the Traefik Forward Auth recipe demonstrated a quick way to protect a set of explicitly-specified URLs using OIDC credentials from a Google account, this recipe will illustrate how to use your own KeyCloak instance to secure any URLs within your DNS domain.

\n\n

\n13.1 Ingredients

\n\n Existing:
\n * [X] KeyCloak recipe deployed successfully, with a local user and an OIDC client
\n New:
\n * [ ] DNS entry for your auth host (“auth.yourdomain.com” is a good choice), pointed to your keepalived IP
\n

\n13.2 Preparation

\n\n

\nWhat is AuthHost mode

\n\n

Under normal OIDC auth, you have to tell your auth provider which URLs it may redirect an authenticated user back to, post-authentication. This is a security feture of the OIDC spec, preventing a malicious landing page from capturing your session and using it to impersonate you. When you’re securing many URLs though, explicitly listing them can be a PITA.

\n\n

@thomaseddon’s traefik-forward-auth includes an ingenious mechanism to simulate an “auth host” in your OIDC authentication, so that you can protect an unlimited amount of DNS names (with a common domain suffix), without having to manually maintain a list.

\n\n

\nHow does it work?

\n\n

Say you’re protecting radarr.example.com. When you first browse to https://radarr.example.com, Traefik forwards your session to traefik-forward-auth, to be authenticated. Traefik-forward-auth redirects you to your OIDC provider’s login (KeyCloak, in this case), but instructs the OIDC provider to redirect a successfully authenticated session back to https://auth.example.com/_oauth, rather than to https://radarr.example.com/_oauth.

\n\n

When you successfully authenticate against the OIDC provider, you are redirected to the “redirect_uri” of https://auth.example.com. Again, your request hits Traefik, whichforwards the session to traefik-forward-auth, which knows that you’ve just been authenticated (cookies have a role to play here). Traefik-forward-auth also knows the URL of your original request (thanks to the X-Forwarded-Whatever header). Traefik-forward-auth redirects you to your original destination, and everybody is happy.

\n\n

This clever workaround only works under 2 conditions:

\n\n

Your “auth host” has the same domain name as the hosts you’re protecting (i.e., auth.example.com protecting radarr.example.com)
You explictly tell traefik-forward-auth to use a cookie authenticating your whole domain (i.e. example.com)

\n\n

\nSetup environment

\n\n

Create /var/data/config/traefik/traefik-forward-auth.env as follows (change “master” if you created a different realm):

\n\n\n

CLIENT_ID=<your keycloak client name>\nCLIENT_SECRET=<your keycloak client secret>\nOIDC_ISSUER=https://<your keycloak URL>/auth/realms/master\nSECRET=<a random string to secure your cookie>\nAUTH_HOST=<the FQDN to use for your auth host>\nCOOKIE_DOMAIN=<the root FQDN of your domain>\n

\n\n\n\n\n

\nPrepare the docker service config

\n\n

This is a small container, you can simply add the following content to the existing traefik-app.yml deployed in the previous Traefik recipe:

\n\n\n

  traefik-forward-auth:\n    image: funkypenguin/traefik-forward-auth\n    env_file: /var/data/config/traefik/traefik-forward-auth.env\n    networks:\n      - traefik_public\n    deploy:\n      labels:\n        - traefik.port=4181\n        - traefik.frontend.rule=Host:auth.example.com\n        - traefik.frontend.auth.forward.address=http://traefik-forward-auth:4\\\n181\n        - traefik.frontend.auth.forward.trustForwardHeader=true\n

\n\n\n\n\n

\n\n\n

  # This simply validates that traefik forward authentication is working\n  whoami:\n    image: containous/whoami\n    networks:\n      - traefik_public\n    deploy:\n      labels:\n        - traefik.frontend.rule=Host:whoami.example.com\n        - traefik.port=80\n        - traefik.frontend.auth.forward.address=http://traefik-forward-auth:4\\\n181\n        - traefik.frontend.auth.forward.authResponseHeaders=X-Forwarded-User\n        - traefik.frontend.auth.forward.trustForwardHeader=true\n

\n13.3 Serving

\n\n

\nLaunch

\n\n

Redeploy traefik with docker stack deploy traefik-app -c /var/data/traefik/traeifk-app.yml, to launch the traefik-forward-auth container.

\n\n

\nTest

\n\n

Browse to https://whoami.example.com (obviously, customized for your domain and having created a DNS record), and all going according to plan, you’ll be redirected to a KeyCloak login. Once successfully logged in, you’ll be directed to the basic whoami page.

\n\n

\nProtect services

\n\n

To protect any other service, ensure the service itself is exposed by Traefik (if you were previously using an oauth_proxy for this, you may have to migrate some labels from the oauth_proxy serivce to the service itself). Add the following 3 labels:

\n\n\n

- traefik.frontend.auth.forward.address=http://traefik-forward-auth:4181\n- traefik.frontend.auth.forward.authResponseHeaders=X-Forwarded-User\n- traefik.frontend.auth.forward.trustForwardHeader=true\n

\n\n\n\n\n

And re-deploy your services :)

\n\n

\n13.4 Summary

\n\n

What have we achieved? By adding an additional three simple labels to any service, we can secure any service behind our KeyCloak OIDC provider, with minimal processing / handling overhead.

\n\n Created:
\n * [X] Traefik-forward-auth configured to authenticate against KeyCloak
\n

\n13.5 Chef’s Notes

\n\n

KeyCloak is very powerful. You can add 2FA and all other clever things outside of the scope of this simple recipe ;)

\n\n\n

\n14 Create registry mirror

\n\n

Although we now have shared storage for our persistent container data, our docker nodes don’t share any other docker data, such as container images. This results in an inefficiency - every node which participates in the swarm will, at some point, need the docker image for every container deployed in the swarm.

\n\n

When dealing with large container (looking at you, GitLab!), this can result in several gigabytes of wasted bandwidth per-node, and long delays when restarting containers on an alternate node. (It also wastes disk space on each node, but we’ll get to that in the next section)

\n\n

The solution is to run an official Docker registry container as a “pull-through” cache, or “registry mirror”. By using our persistent storage for the registry cache, we can ensure we have a single copy of all the containers we’ve pulled at least once. After the first pull, any subsequent pulls from our nodes will use the cached version from our registry mirror. As a result, services are available more quickly when restarting container nodes, and we can be more aggressive about cleaning up unused containers on our nodes (more later)

\n\n

The registry mirror runs as a swarm stack, using a simple docker-compose.yml. Customize your mirror FQDN below, so that Traefik will generate the appropriate LetsEncrypt certificates for it, and make it available via HTTPS.

\n\n

\n14.1 Ingredients

\n\n

\nDocker swarm cluster with persistent shared storage\n
\nTraefik configured per design
DNS entry for the hostname you intend to use, pointed to your keepalived IP

\n\n

\n14.2 Preparation

\n\n

Create /var/data/config/registry/registry.yml as follows:

\n\n\n

version: \"3\"\n\nservices:\n\n  registry-mirror:\n    image: registry:2\n    networks:\n      - traefik_public\n    deploy:\n      labels:\n        - traefik.frontend.rule=Host:<your mirror FQDN>\n        - traefik.docker.network=traefik_public\n        - traefik.port=5000\n    ports:\n      - 5000:5000\n    volumes:\n      - /var/data/registry/registry-mirror-data:/var/lib/registry\n      - /var/data/registry/registry-mirror-config.yml:/etc/docker/registry/co\\\nnfig.yml\n\nnetworks:\n  traefik_public:\n    external: true\n

\n\n\n\n\n We create this registry without consideration for SSL, which will fail if we attempt to use the registry directly. However, we’re going to use the HTTPS-proxied version via Traefik, leveraging Traefik to manage the LetsEncrypt certificates required.
\n

Create /var/data/registry/registry-mirror-config.yml as follows:

\n\n

version: 0.1\nlog:\n  fields:\n    service: registry\nstorage:\n  cache:\n    blobdescriptor: inmemory\n  filesystem:\n    rootdirectory: /var/lib/registry\n  delete:\n    enabled: true\nhttp:\n  addr5000\n  headers:\n    X-Content-Type-Options: [nosniff]\nhealth:\n  storagedriver:\n    enabled: true\n    interval: 10s\n    threshold: 3\nproxy:\n  remoteurl: https://registry-1.docker.io\n

\n\n\n\n\n

\n14.3 Serving

\n\n

\nLaunch registry stack

\n\n

Launch the registry stack by running docker stack deploy registry -c <path-to-docker-compose.yml>

\n\n

\nEnable registry mirror and experimental features

\n\n

To tell docker to use the registry mirror, and (while we’re here) in order to be able to watch the logs of any service from any manager node (an experimental feature in the current Atomic docker build), edit /etc/docker-latest/daemon.json on each node, and change from:

\n\n\n

{\n    \"log-driver\": \"journald\",\n    \"signature-verification\": false\n}\n

\n\n\n\n\n

To:

\n\n\n

{\n    \"log-driver\": \"journald\",\n    \"signature-verification\": false,\n    \"experimental\": true,\n    \"registry-mirrors\": [\"https://<your registry mirror FQDN>\"]\n}\n

\n\n\n\n\n

Then restart docker by running:

\n\n

systemctl restart docker-latest\n

\n\n\n\n\n Note the extra comma required after “false” above
\n

\n14.4 Chef’s notes

\n\n\n

\nII Chef’s Favorites (Docker)

\n\n

The following recipes are the chef’s current favorites - these are recipes actively in use and updated by @funkypenguin

\n\n\n

hero: AutoPirate - A fully-featured recipe to automate finding, downloading, and organising your media

\n\n

\n15 AutoPirate

\n\n

Once the cutting edge of the “internet” (pre-world-wide-web and mosiac days), Usenet is now a murky, geeky alternative to torrents for file-sharing. However, it’s cool geeky, especially if you’re into having a fully automated media platform.

\n\n

A good starter for the usenet scene is https://www.reddit.com/r/usenet/. Because it’s so damn complicated, a host of automated tools exist to automate the process of finding, downloading, and managing content. The tools included in this recipe are as follows:

\n\n

\n\n\n

This recipe presents a method to combine these tools into a single swarm deployment, and make them available securely.

\n\n\n\n

Tools included in the AutoPirate stack are:

\n\n

\nSABnzbd : downloads data from usenet servers based on .nzb definitions
\nNZBGet : downloads data from usenet servers based on .nzb definitions, but written in C++ and designed with performance in mind to achieve maximum download speed by using very little system resources (this is a popular alternative to SABnzbd)
\nRTorrent is a CLI-based torrent client, which when combined with ruTorrent becomes a powerful and fully browser-managed torrent client. (Yes, it’s not Usenet, but Sonarr/Radarr will let fulfill your watchlist using either Usenet or torrents, so it’s worth including)
\nNZBHydra : acts as a “meta-indexer”, so that your downloading tools (radarr, sonarr, etc) only need to be setup for a single indexes. Also produces interesting stats on indexers, which helps when evaluating which indexers are performing well.
\nNZBHydra2 : is a high-performance rewrite of the original NZBHydra, with extra features. While still in beta, this NZBHydra2 will eventually supercede NZBHydra
\nSonarr : finds, downloads and manages TV shows
\nRadarr : finds, downloads and manages movies
\nMylar : finds, downloads and manages comic books
\nHeadphones : finds, downloads and manages music
\nLazy Librarian : finds, downloads and manages ebooks
\nOmbi : provides an interface to request additions to a Plex/Emby library using the above tools
\nJackett : Provides an local, caching, API-based interface to torrent trackers, simplifying the way your tools search for torrents.

\n\n

Since this recipe is so long, and so many of the tools are optional to the final result (i.e., if you’re not interested in comics, you won’t want Mylar), I’ve described each individual tool on its own sub-recipe page (below), even though most of them are deployed very similarly.

\n\n

\n15.2 Ingredients

\n\n

\nDocker swarm cluster with persistent shared storage\n
\nTraefik configured per design
Access to NZB indexers and Usenet servers
DNS entries configured for each of the NZB tools in this recipe that you want to use

\n\n

\n15.3 Preparation

\n\n

\nSetup data locations

\n\n

We’ll need a unique directories for each tool in the stack, bind-mounted into our containers, so create them upfront, in /var/data/autopirate:

\n\n\n

mkdir /var/data/autopirate\ncd /var/data/autopirate\nmkdir -p {lazylibrarian,mylar,ombi,sonarr,radarr,headphones,plexpy,nzbhydra,s\\\nabnzbd,nzbget,rtorrent,jackett}\n

\n\n\n\n\n

Create a directory for the storage of your downloaded media, i.e., something like:

\n\n\n

mkdir /var/data/media\n

\n\n\n\n\n

Create a user to “own” the above directories, and note the uid and gid of the created user. You’ll need to specify the UID/GID in the environment variables passed to the container (in the example below, I used 4242 - twice the meaning of life).

\n\n

\nSecure public access

\n\n

What you’ll quickly notice about this recipe is that every web interface is protected by an OAuth proxy.

\n\n

Why? Because these tools are developed by a handful of volunteer developers who are focused on adding features, not necessarily implementing robust security. Most users wouldn’t expose these tools directly to the internet, so the tools have rudimentary (if any) access control.

\n\n

To mitigate the risk associated with public exposure of these tools (you’re on your smartphone and you want to add a movie to your watchlist, what do you do, hotshot?), in order to gain access to each tool you’ll first need to authenticate against your given OAuth provider.

\n\n

This is tedious, but you only have to do it once. Each tool (Sonarr, Radarr, etc) to be protected by an OAuth proxy, requires unique configuration. I use github to provide my oauth, giving each tool a unique logo while I’m at it (make up your own random string for OAUTH2PROXYCOOKIE_SECRET)

\n\n

For each tool, create /var/data/autopirate/<tool>.env, and set the following:

\n\n\n

OAUTH2_PROXY_CLIENT_ID=\nOAUTH2_PROXY_CLIENT_SECRET=\nOAUTH2_PROXY_COOKIE_SECRET=\nPUID=4242\nPGID=4242\n

\n\n\n\n\n

Create at least /var/data/autopirate/authenticated-emails.txt, containing at least your own email address with your OAuth provider. If you wanted to grant access to a specific tool to other users, you’d need a unique authenticated-emails-<tool>.txt which included both normal email address as well as any addresses to be granted tool-specific access.

\n\n

\nSetup components

\n\n

\nStack basics

\n\n

Start with a swarm config file in docker-compose syntax, like this:

\n\n\n

version: '3'\n\nservices:\n

\n\n\n\n\n

And end with a stanza like this:

\n\n\n

networks:\n  traefik_public:\n    external: true\n  internal:\n    driver: overlay\n    ipam:\n      config:\n        - subnet: 172.16.11.0/24\n

\n\n\n\n\n Setup unique static subnets for every stack you deploy. This avoids IP/gateway conflicts which can otherwise occur when you’re creating/removing stacks a lot. See my list here.
\n

\nAssemble the tools..

\n\n

Now work your way through the list of tools below, adding whichever tools your want to use, and finishing with the end section:

\n\n

SABnzbd
NZBGet
RTorrent
Sonarr
Radarr
Mylar
Lazy Librarian
Headphones
NZBHydra
NZBHydra2
Ombi
Jackett
\nEnd (launch the stack)

\n\n\n This is not a complete recipe - it’s a component of the AutoPirate “uber-recipe”, but has been split into its own page to reduce complexity.
\n

\n16 SABnzbd

\n\n

\n16.1 Introduction

\n\n

SABnzbd is the workhorse of the stack. It takes .nzb files as input (manually or from other autopirate stack tools), then connects to your chosen Usenet provider, downloads all the individual binaries referenced by the .nzb, and then tests/repairs/combines/uncompresses them all into the final result - media files.

\n\n

\n\n\n SABnzbd is one of my sponsored projects - a project I financially support on a regular basis because of its utility to me. It’s not sexy, but it’s consistent and reliable, and I enjoy the fruits of its labor near-daily.
\n

\n16.2 Inclusion into AutoPirate

\n\n

To include SABnzbd in your AutoPirate stack
(The only reason you wouldn’t use SABnzbd, would be if you were using NZBGet instead), include the following in your autopirate.yml stack definition file:

\n\n I share (with my patreon patrons) a private “premix” git repository, which includes necessary docker-compose and env files for all published recipes. This means that patrons can launch any recipe with just a git pull and a docker stack deploy
\n\n

sabnzbd:\n  image: linuxserver/sabnzbd:latest\n  env_file : /var/data/config/autopirate/sabnzbd.env  \n  volumes:\n   - /var/data/autopirate/sabnzbd:/config\n   - /var/data/media:/media\n  networks:\n  - internal\n\nsabnzbd_proxy:\n  image: a5huynh/oauth2_proxy\n  env_file : /var/data/config/autopirate/sabnzbd.env\n  networks:\n    - internal\n    - traefik_public\n  deploy:\n    labels:\n      - traefik.frontend.rule=Host:sabnzbd.example.com\n      - traefik.docker.network=traefik_public\n      - traefik.port=4180\n  volumes:\n    - /var/data/config/autopirate/authenticated-emails.txt:/authenticated-ema\\\nils.txt\n  command: |\n    -cookie-secure=false\n    -upstream=http://sabnzbd:8080\n    -redirect-url=https://sabnzbd.example.com\n    -http-address=http://0.0.0.0:4180\n    -email-domain=example.com\n    -provider=github\n    -authenticated-emails-file=/authenticated-emails.txt\n

\n\n\n\n\n (Updated 10 June 2018) : In SABnzbd 2.3.3, hostname verification was added as a mandatory check. SABnzbd will refuse inbound connections which weren’t addressed to its own (initially, autodetected) hostname. This presents a problem within Docker Swarm, where container hostnames are random and disposable.
\n You’ll need to edit sabnzbd.ini (only created after your first launch), and replace the value in host_whitelist configuration (it’s comma-separated) with the name of your service within the swarm definition, as well as your FQDN as accessed via traefik.
\n For example, mine simply reads host_whitelist = sabnzbd.funkypenguin.co.nz, sabnzbd
\n

\n16.3 Assemble more tools..

\n\n

Continue through the list of tools below, adding whichever tools your want to use, and finishing with the end section:

\n\n

SABnzbd (this page)
NZBGet
RTorrent
Sonarr
Radarr
Mylar
Lazy Librarian
Headphones
Lidarr
NZBHydra
NZBHydra2
Ombi
Jackett
Heimdall
\nEnd (launch the stack)

\n\n

\n16.4 Chef’s Notes

\n\n

In many cases, tools will integrate with each other. I.e., Radarr needs to talk to SABnzbd and NZBHydra, Ombi needs to talk to Radarr, etc. Since each tool runs within the stack under its own name, just refer to each tool by name (i.e. “radarr”), and docker swarm will resolve the name to the appropriate container. You can identify the tool-specific port by looking at the docker-compose service definition.

\n\n\n This is not a complete recipe - it’s a component of the AutoPirate “uber-recipe”, but has been split into its own page to reduce complexity.
\n

\n17 NZBGet

\n\n

\n17.1 Introduction

\n\n

NZBGet performs the same function as SABnzbd (downloading content from Usenet servers), but it’s lightweight and fast(er), written in C++ (as opposed to Python).

\n\n

\n\n\n

\n17.2 Inclusion into AutoPirate

\n\n

To include NZBGet in your AutoPirate stack
(The only reason you wouldn’t use NZBGet, would be if you were using SABnzbd instead), include the following in your autopirate.yml stack definition file:

nzbget:\n  image: linuxserver/nzbget\n  env_file : /var/data/config/autopirate/nzbget.env  \n  volumes:\n   - /var/data/autopirate/nzbget:/config\n   - /var/data/media:/data\n  networks:\n  - internal\n\nnzbget_proxy:\n  image: a5huynh/oauth2_proxy\n  env_file : /var/data/config/autopirate/nzbget.env\n  networks:\n    - internal\n    - traefik_public\n  deploy:\n    labels:\n      - traefik.frontend.rule=Host:nzbget.example.com\n      - traefik.docker.network=traefik_public\n      - traefik.port=4180\n  volumes:\n    - /var/data/config/autopirate/authenticated-emails.txt:/authenticated-ema\\\nils.txt\n  command: |\n    -cookie-secure=false\n    -upstream=http://nzbget:6789\n    -redirect-url=https://nzbget.example.com\n    -http-address=http://0.0.0.0:4180\n    -email-domain=example.com\n    -provider=github\n    -authenticated-emails-file=/authenticated-emails.txt\n

\n\n\n\n\n NZBGet uses a 401 header to prompt for authentication. When you use OAuth2_proxy, this seems to break. Since we trust OAuth to authenticate us, we can just disable NZGet’s own authentication, by changing ControlPassword to null in nzbget.conf (i.e. ControlPassword=)
\n

\n17.3 Assemble more tools..

\n\n

Continue through the list of tools below, adding whichever tools your want to use, and finishing with the end section:

\n\n

SABnzbd
NZBGet (this page)
RTorrent
Sonarr
Radarr
Mylar
Lazy Librarian
Headphones
Lidarr
NZBHydra
NZBHydra2
Ombi
Jackett
Heimdall
\nEnd (launch the stack)

\n\n

\n17.4 Chef’s Notes

\n\n

In many cases, tools will integrate with each other. I.e., Radarr needs to talk to SABnzbd and NZBHydra, Ombi needs to talk to Radarr, etc. Since each tool runs within the stack under its own name, just refer to each tool by name (i.e. “radarr”), and docker swarm will resolve the name to the appropriate container. You can identify the tool-specific port by looking at the docker-compose service definition.

\n\n\n This is not a complete recipe - it’s a component of the AutoPirate “uber-recipe”, but has been split into its own page to reduce complexity.
\n

\n18 RTorrent / ruTorrent

\n\n

RTorrent is a popular CLI-based bittorrent client, and ruTorrent is a powerful web interface for rtorrent.

\n\n

\n\n\n

\n18.1 Choose incoming port

\n\n

When using a torrent client from behind NAT (which swarm, by nature, is), you typically need to set a static port for inbound torrent communications. In the example below, I’ve set the port to 36258. You’ll need to configure /var/data/autopirate/rtorrent/rtorrent/rtorrent.rc with the equivalent port.

\n\n

\n18.2 Inclusion into AutoPirate

\n\n

To include ruTorrent in your AutoPirate stack, include the following in your autopirate.yml stack definition file:

\n\n\n

rtorrent:\n  image: linuxserver/rutorrent\n  env_file : /var/data/config/autopirate/rtorrent.env\n  ports:\n   - 36258:36258\n  volumes:\n   - /var/data/media/:/media\n   - /var/data/autopirate/rtorrent:/config\n  networks:\n  - internal\n\nrtorrent_proxy:\n  image: skippy/oauth2_proxy\n  env_file : /var/data/config/autopirate/rtorrent.env\n  networks:\n    - internal\n    - traefik_public\n  deploy:\n    labels:\n      - traefik.frontend.rule=Host:rtorrent.example.com\n      - traefik.docker.network=traefik_public\n      - traefik.port=4180\n  volumes:\n    - /var/data/config/autopirate/authenticated-emails.txt:/authenticated-ema\\\nils.txt\n  command: |\n    -cookie-secure=false\n    -upstream=http://rtorrent:80\n    -redirect-url=https://rtorrent.example.com\n    -http-address=http://0.0.0.0:4180\n    -email-domain=example.com\n    -provider=github\n    -authenticated-emails-file=/authenticated-emails.txt\n

\n18.3 Assemble more tools..

\n\n

Continue through the list of tools below, adding whichever tools your want to use, and finishing with the end section:

\n\n

SABnzbd
NZBGet
RTorrent (this page)
Sonarr
Radarr
Mylar
Lazy Librarian
Headphones
Lidarr
NZBHydra
NZBHydra2
Ombi
Jackett
Heimdall
\nEnd (launch the stack)

\n\n

\n18.4 Chef’s Notes

\n\n

In many cases, tools will integrate with each other. I.e., Radarr needs to talk to SABnzbd and NZBHydra, Ombi needs to talk to Radarr, etc. Since each tool runs within the stack under its own name, just refer to each tool by name (i.e. “radarr”), and docker swarm will resolve the name to the appropriate container. You can identify the tool-specific port by looking at the docker-compose service definition.

\n\n\n This is not a complete recipe - it’s a component of the AutoPirate “uber-recipe”, but has been split into its own page to reduce complexity.
\n

\n19 Sonarr

\n\n

Sonarr is a tool for finding, downloading and managing your TV series.

\n\n

\n\n\n Sonarr is one of my sponsored projects - a project I financially support on a regular basis because of its utility to me. I forget it’s there until I (reliably) receive an email with new and exciting updates
\n

\n19.1 Inclusion into AutoPirate

\n\n

To include Sonarr in your AutoPirate stack, include the following in your autopirate.yml stack definition file:

\n\n\n

sonarr:\n  image: linuxserver/sonarr:latest\n  env_file : /var/data/config/autopirate/sonarr.env\n  volumes:\n   - /var/data/autopirate/sonarr:/config\n   - /var/data/media:/media\n  networks:\n  - internal\n\nsonarr_proxy:\n  image: a5huynh/oauth2_proxy\n  env_file : /var/data/config/autopirate/sonarr.env\n  networks:\n    - internal\n    - traefik_public\n  deploy:\n    labels:\n      - traefik.frontend.rule=Host:sonarr.example.com\n      - traefik.docker.network=traefik_public\n      - traefik.port=4180\n  volumes:\n    - /var/data/config/autopirate/authenticated-emails.txt:/authenticated-ema\\\nils.txt\n  command: |\n    -cookie-secure=false\n    -upstream=http://sonarr:8989\n    -redirect-url=https://sonarr.example.com\n    -http-address=http://0.0.0.0:4180\n    -email-domain=example.com\n    -provider=github\n    -authenticated-emails-file=/authenticated-emails.txt\n

\n19.2 Assemble more tools..

\n\n

Continue through the list of tools below, adding whichever tools your want to use, and finishing with the end section:

\n\n

SABnzbd
NZBGet
RTorrent
Sonarr (this page)
Radarr
Mylar
Lazy Librarian
Headphones
Lidarr
NZBHydra
NZBHydra2
Ombi
Jackett
Heimdall
\nEnd (launch the stack)

\n\n

\n19.3 Chef’s Notes

\n\n

In many cases, tools will integrate with each other. I.e., Radarr needs to talk to SABnzbd and NZBHydra, Ombi needs to talk to Radarr, etc. Since each tool runs within the stack under its own name, just refer to each tool by name (i.e. “radarr”), and docker swarm will resolve the name to the appropriate container. You can identify the tool-specific port by looking at the docker-compose service definition.

\n\n\n This is not a complete recipe - it’s a component of the AutoPirate “uber-recipe”, but has been split into its own page to reduce complexity.
\n

\n20 Radarr

\n\n

Radarr is a tool for finding, downloading and managing movies. Features include:

\n\n

Adding new movies with lots of information, such as trailers, ratings, etc.
Can watch for better quality of the movies you have and do an automatic upgrade. eg. from DVD to Blu-Ray
Automatic failed download handling will try another release if one fails
Manual search so you can pick any release or to see why a release was not downloaded automatically
Full integration with SABnzbd and NZBGet
Automatically searching for releases as well as RSS Sync
Automatically importing downloaded movies
Recognizing Special Editions, Director’s Cut, etc.
Identifying releases with hardcoded subs
Importing movies from various online sources, such as IMDb Watchlists (A complete list can be found here)
Full integration with Kodi, Plex (notification, library update)
And a beautiful UI
Importing Metadata such as trailers or subtitles

\n\n

\n20.1 Inclusion into AutoPirate

\n\n

To include Radarr in your AutoPirate stack, include the following in your autopirate.yml stack definition file:

\n\n\n

radarr:\n  image: linuxserver/radarr:latest\n  env_file : /var/data/config/autopirate/radarr.env\n  volumes:\n   - /var/data/autopirate/radarr:/config\n   - /var/data/media:/media\n  networks:\n  - internal\n\nradarr_proxy:\n  image: a5huynh/oauth2_proxy\n  env_file : /var/data/config/autopirate/radarr.env\n  networks:\n    - internal\n    - traefik_public\n  deploy:\n    labels:\n      - traefik.frontend.rule=Host:radarr.example.com\n      - traefik.docker.network=traefik_public\n      - traefik.port=4180\n  volumes:\n    - /var/data/config/autopirate/authenticated-emails.txt:/authenticated-ema\\\nils.txt\n  command: |\n    -cookie-secure=false\n    -upstream=http://radarr:7878\n    -redirect-url=https://radarr.example.com\n    -http-address=http://0.0.0.0:4180\n    -email-domain=example.com\n    -provider=github\n    -authenticated-emails-file=/authenticated-emails.txt\n

\n20.2 Assemble more tools..

\n\n

Continue through the list of tools below, adding whichever tools your want to use, and finishing with the end section:

\n\n

SABnzbd
NZBGet
RTorrent
Sonarr
Radarr (this page)
Mylar
Lazy Librarian
Headphones
Lidarr
NZBHydra
NZBHydra2
Ombi
Jackett
Heimdall
\nEnd (launch the stack)

\n\n

\n20.3 Chef’s Notes

\n\n

In many cases, tools will integrate with each other. I.e., Radarr needs to talk to SABnzbd and NZBHydra, Ombi needs to talk to Radarr, etc. Since each tool runs within the stack under its own name, just refer to each tool by name (i.e. “radarr”), and docker swarm will resolve the name to the appropriate container. You can identify the tool-specific port by looking at the docker-compose service definition.

\n\n\n This is not a complete recipe - it’s a component of the autopirate “uber-recipe”, but has been split into its own page to reduce complexity.
\n

\n21 Mylar

\n\n

Mylar is a tool for downloading and managing digital comic books.

\n\n

\n\n\n

\n21.1 Inclusion into AutoPirate

\n\n

To include Mylar in your AutoPirate stack, include the following in your autopirate.yml stack definition file:

\n\n\n

mylar:\n  image: linuxserver/mylar:latest\n  env_file : /var/data/config/autopirate/mylar.env\n  volumes:\n   - /var/data/autopirate/mylar:/config\n   - /var/data/media:/media\n  networks:\n  - internal\n\nmylar_proxy:\n  image: a5huynh/oauth2_proxy\n  env_file : /var/data/config/autopirate/mylar.env\n  networks:\n    - internal\n    - traefik_public\n  deploy:\n    labels:\n      - traefik.frontend.rule=Host:mylar.example.com\n      - traefik.docker.network=traefik_public\n      - traefik.port=4180\n  volumes:\n    - /var/data/config/autopirate/authenticated-emails.txt:/authenticated-ema\\\nils.txt\n  command: |\n    -cookie-secure=false\n    -upstream=http://mylar:8090\n    -redirect-url=https://mylar.example.com\n    -http-address=http://0.0.0.0:4180\n    -email-domain=example.com\n    -provider=github\n    -authenticated-emails-file=/authenticated-emails.txt\n

\n21.2 Assemble more tools..

\n\n

Continue through the list of tools below, adding whichever tools your want to use, and finishing with the end section:

\n\n

SABnzbd
NZBGet
RTorrent
Sonarr
Radarr
Mylar (this page)
Lazy Librarian
Headphones
Lidarr
NZBHydra
NZBHydra2
Ombi
Jackett
Heimdall
\nEnd (launch the stack)

\n\n

\n21.3 Chef’s Notes

\n\n

In many cases, tools will integrate with each other. I.e., Radarr needs to talk to SABnzbd and NZBHydra, Ombi needs to talk to Radarr, etc. Since each tool runs within the stack under its own name, just refer to each tool by name (i.e. “radarr”), and docker swarm will resolve the name to the appropriate container. You can identify the tool-specific port by looking at the docker-compose service definition.
If you intend to configure Mylar to perform its own NZB searches and push the hits to a downloader such as SABnzbd, then in addition to configuring the connection to SAB with host, port and api key, you will need to set the parameter host_return parameter to the fully qualified Mylar address (e.g. http://mylar:8090).\n
This will provide the link to the downloader necessary to initiate the download. This parameter is not presented in the user interface so the config file ($MYLAR_HOME/config.ini) will need to be manually updated. The parameter can be found under the [Interface] section of the file. (Details)
\n

\n\n\n This is not a complete recipe - it’s a component of the autopirate “uber-recipe”, but has been split into its own page to reduce complexity.
\n

\n22 LazyLibrarian

\n\n

LazyLibrarian is a tool to follow authors and grab metadata for all your digital reading needs. It uses a combination of Goodreads Librarything and optionally GoogleBooks as sources for author info and book info. Features include:

\n\n

Find authors and add them to the database
List all books of an author and mark ebooks or audiobooks as ‘wanted’.
When processing the downloaded books it will save a cover picture (if available) and save all metadata into metadata.opf next to the bookfile (calibre compatible format)
AutoAdd feature for book management tools like Calibre which must have books in flattened directory structure, or use calibre to import your books into an existing calibre library
LazyLibrarian can also be used to search for and download magazines, and monitor for new issues

\n\n

\n\n\n

\n22.1 Inclusion into AutoPirate

\n\n

To include LazyLibrarian in your AutoPirate stack, include the following in your autopirate.yml stack definition file:

\n\n\n

lazylibrarian:\n  image: linuxserver/lazylibrarian:latest\n  env_file : /var/data/config/autopirate/lazylibrarian.env\n  volumes:\n   - /var/data/autopirate/lazylibrarian:/config\n   - /var/data/media:/media\n  networks:\n  - internal\n\nlazylibrarian_proxy:\n  image: a5huynh/oauth2_proxy\n  env_file : /var/data/config/autopirate/lazylibrarian.env\n  networks:\n    - internal\n    - traefik_public\n  deploy:\n    labels:\n      - traefik.frontend.rule=Host:lazylibrarian.example.com\n      - traefik.docker.network=traefik_public\n      - traefik.port=4180\n  volumes:\n    - /var/data/config/autopirate/authenticated-emails.txt:/authenticated-ema\\\nils.txt\n  command: |\n    -cookie-secure=false\n    -upstream=http://lazylibrarian:5299\n    -redirect-url=https://lazylibrarian.example.com\n    -http-address=http://0.0.0.0:4180\n    -email-domain=example.com\n    -provider=github\n    -authenticated-emails-file=/authenticated-emails.txt\n\ncalibre-server:\n  image: regueiro/calibre-server\n  volumes:\n   - /var/data/media/Ebooks/calibre/:/opt/calibre/library\n  networks:\n  - internal    \n

\n22.2 Assemble more tools..

\n\n

Continue through the list of tools below, adding whichever tools your want to use, and finishing with the end section:

\n\n

SABnzbd
NZBGet
RTorrent
Sonarr
Radarr
Mylar
Lazy Librarian (this page)
Headphones
Lidarr
NZBHydra
NZBHydra2
Ombi
Jackett
Heimdall
\nEnd (launch the stack)

\n\n

\n22.3 Chef’s Notes

\n\n

The calibre-server container co-exists within the Lazy Librarian (LL) containers so that LL can automatically add a book to Calibre using the calibre-server interface. The calibre library can then be properly viewed using the calibre-web recipe.
In many cases, tools will integrate with each other. I.e., Radarr needs to talk to SABnzbd and NZBHydra, Ombi needs to talk to Radarr, etc. Since each tool runs within the stack under its own name, just refer to each tool by name (i.e. “radarr”), and docker swarm will resolve the name to the appropriate container. You can identify the tool-specific port by looking at the docker-compose service definition.

\n\n\n

hero: AutoPirate - A fully-featured recipe to automate finding, downloading, and organising your media

\n\n This is not a complete recipe - it’s a component of the autopirate “uber-recipe”, but has been split into its own page to reduce complexity.
\n

\n23 Headphones

\n\n

Headphones is an automated music downloader for NZB and Torrent, written in Python. It supports SABnzbd, NZBget, Transmission, Torrent, Deluge and Blackhole.

\n\n

\n\n\n

\n23.1 Inclusion into AutoPirate

\n\n

To include Headphones in your AutoPirate stack, include the following in your autopirate.yml stack definition file:

\n\n\n

headphones:\n  image: linuxserver/headphones:latest\n  env_file : /var/data/config/autopirate/headphones.env\n  volumes:\n   - /var/data/autopirate/headphones:/config\n   - /var/data/media:/media\n  networks:\n  - internal\n\nheadphones_proxy:\n  image: a5huynh/oauth2_proxy\n  env_file : /var/data/config/autopirate/headphones.env\n  networks:\n    - internal\n    - traefik_public\n  deploy:\n    labels:\n      - traefik.frontend.rule=Host:headphones.example.com\n      - traefik.docker.network=traefik_public\n      - traefik.port=4180\n  volumes:\n    - /var/data/config/autopirate/authenticated-emails.txt:/authenticated-ema\\\nils.txt\n  command: |\n    -cookie-secure=false\n    -upstream=http://headphones:8181\n    -redirect-url=https://headphones.example.com\n    -http-address=http://0.0.0.0:4180\n    -email-domain=example.com\n    -provider=github\n    -authenticated-emails-file=/authenticated-emails.txt\n

\n23.2 Assemble more tools..

\n\n

Continue through the list of tools below, adding whichever tools your want to use, and finishing with the end section:

\n\n

SABnzbd
NZBGet
RTorrent
Sonarr
Radarr
Mylar
Lazy Librarian
Headphones (this page)
Lidarr
NZBHydra
NZBHydra2
Ombi
Jackett
Heimdall
\nEnd (launch the stack)

\n\n

\n23.3 Chef’s Notes

\n\n

In many cases, tools will integrate with each other. I.e., Radarr needs to talk to SABnzbd and NZBHydra, Ombi needs to talk to Radarr, etc. Since each tool runs within the stack under its own name, just refer to each tool by name (i.e. “radarr”), and docker swarm will resolve the name to the appropriate container. You can identify the tool-specific port by looking at the docker-compose service definition.

\n\n\n

hero: AutoPirate - A fully-featured recipe to automate finding, downloading, and organising your media

\n\n This is not a complete recipe - it’s a component of the autopirate “uber-recipe”, but has been split into its own page to reduce complexity.
\n

\n24 Lidarr

\n\n

Lidarr is an automated music downloader for NZB and Torrent. It performs the same function as Headphones, but is written using the same(ish) codebase as Radarr and Sonarr. It’s blazingly fast, and includes beautiful album/artist art. Lidarr supports SABnzbd, NZBGet, Transmission, Torrent, Deluge and Blackhole (just like Sonarr / Radarr)

\n\n

\n\n\n

\n24.1 Inclusion into AutoPirate

\n\n

To include Lidarr in your AutoPirate stack, include the following in your autopirate.yml stack definition file:

\n\n\n

lidarr:\n  image: linuxserver/lidarr:latest\n  env_file : /var/data/config/autopirate/lidarr.env\n  volumes:\n   - /var/data/autopirate/lidarr:/config\n   - /var/data/media:/media\n  networks:\n  - internal\n\nlidarr_proxy:\n  image: a5huynh/oauth2_proxy\n  env_file : /var/data/config/autopirate/lidarr.env\n  networks:\n    - internal\n    - traefik_public\n  deploy:\n    labels:\n      - traefik.frontend.rule=Host:lidarr.example.com\n      - traefik.docker.network=traefik_public\n      - traefik.port=4180\n  volumes:\n    - /var/data/config/autopirate/authenticated-emails.txt:/authenticated-ema\\\nils.txt\n  command: |\n    -cookie-secure=false\n    -upstream=http://lidarr:8181\n    -redirect-url=https://lidarr.example.com\n    -http-address=http://0.0.0.0:4180\n    -email-domain=example.com\n    -provider=github\n    -authenticated-emails-file=/authenticated-emails.txt\n

\n24.2 Assemble more tools..

\n\n

Continue through the list of tools below, adding whichever tools your want to use, and finishing with the end section:

\n\n

SABnzbd
NZBGet
RTorrent
Sonarr
Radarr
Mylar
Lazy Librarian
Headphones
Lidarr (this page)
NZBHydra
NZBHydra
NZBHydra2
Ombi
Jackett
Heimdall
\nEnd (launch the stack)

\n\n

\n24.3 Chef’s Notes

\n\n

In many cases, tools will integrate with each other. I.e., Radarr needs to talk to SABnzbd and NZBHydra, Ombi needs to talk to Radarr, etc. Since each tool runs within the stack under its own name, just refer to each tool by name (i.e. “radarr”), and docker swarm will resolve the name to the appropriate container. You can identify the tool-specific port by looking at the docker-compose service definition.
The addition of the Lidarr recipe was contributed by our very own @gpulido in Discord (http://chat.funkypenguin.co.nz) - Thanks Gabriel!

\n\n\n This is not a complete recipe - it’s a component of the AutoPirate “uber-recipe”, but has been split into its own page to reduce complexity.
\n

\n25 NZBHydra

\n\n

NZBHydra is a meta search for NZB indexers. It provides easy access to a number of raw and newznab based indexers. You can search all your indexers from one place and use it as indexer source for tools like Sonarr or CouchPotato. Features include:

\n\n

Search by IMDB, TMDB, TVDB, TVRage and TVMaze ID (including season and episode) and filter by age and size. If an ID is not supported by an indexer it is attempted to be converted (e.g. TMDB to IMDB)
Query generation, meaning when you search for a movie using e.g. an IMDB ID a query will be generated for raw indexers. Searching for a series season 1 episode 2 will also generate queries for raw indexers, like s01e02 and 1x02
Grouping of results with the same title and of duplicate results, accounting for result posting time, size, group and poster. By default only one of the duplicates is shown. You can provide an indexer score to influence which one that might be
Compatible with Sonarr, CP, NZB 360, SickBeard, Mylar and Lazy Librarian (and others)
Statistics on indexers (average response time, share of results, access errors), searches and downloads per time of day and day of week, NZB download history and search history (both via internal GUI and API)

\n\n

\n\n\n

\n25.1 Inclusion into AutoPirate

\n\n

To include NZBHydra in your AutoPirate stack, include the following in your autopirate.yml stack definition file:

\n\n\n

nzbhydra:\n  image: linuxserver/hydra:latest\n  env_file : /var/data/config/autopirate/nzbhydra.env\n  volumes:\n   - /var/data/autopirate/nzbhydra:/config\n  networks:\n  - internal\n\nnzbhydra_proxy:\n  image: a5huynh/oauth2_proxy\n  env_file : /var/data/config/autopirate/nzbhydra.env\n  networks:\n    - internal\n    - traefik_public\n  deploy:\n    labels:\n      - traefik.frontend.rule=Host:nzbhydra.example.com\n      - traefik.docker.network=traefik_public\n      - traefik.port=4180\n  volumes:\n    - /var/data/config/autopirate/authenticated-emails.txt:/authenticated-ema\\\nils.txt\n  command: |\n    -cookie-secure=false\n    -upstream=http://nzbhydra:5075\n    -redirect-url=https://nzbhydra.example.com\n    -http-address=http://0.0.0.0:4180\n    -email-domain=example.com\n    -provider=github\n    -authenticated-emails-file=/authenticated-emails.txt\n

\n25.2 Assemble more tools..

\n\n

Continue through the list of tools below, adding whichever tools your want to use, and finishing with the end section:

\n\n

SABnzbd
NZBGet
RTorrent
Sonarr
Radarr
Mylar
Lazy Librarian
Headphones
Lidarr
NZBHydra (this page)
NZBHydra2
Ombi
Jackett
Heimdall
\nEnd (launch the stack)

\n\n

\n25.3 Chef’s Notes

\n\n

In many cases, tools will integrate with each other. I.e., Radarr needs to talk to SABnzbd and NZBHydra, Ombi needs to talk to Radarr, etc. Since each tool runs within the stack under its own name, just refer to each tool by name (i.e. “radarr”), and docker swarm will resolve the name to the appropriate container. You can identify the tool-specific port by looking at the docker-compose service definition.

\n\n\n This is not a complete recipe - it’s a component of the AutoPirate “uber-recipe”, but has been split into its own page to reduce complexity.
\n

\n26 NZBHydra 2

\n\n

NZBHydra 2 is a meta search for NZB indexers. It provides easy access to a number of raw and newznab based indexers. You can search all your indexers from one place and use it as an indexer source for tools like Sonarr, Radarr or CouchPotato.

\n\n NZBHydra 2 is a complete rewrite of NZBHydra (1). It’s currently in Beta. It works mostly fine but some functions might not be completely done and incompatibilities with some tools might still exist. You might want to run both in parallel for migration / testing purposes, but ultimately you’ll probably want to switch over to NZBHydra 2 exclusively.
\n

\n\n\n

Features include:

\n\n

Searches Anizb, BinSearch, NZBIndex and any newznab compatible indexers. Merges all results, filters them by a number of configurable restrictions, recognizes duplicates and returns them all in one place
Add results to NZBGet or SABnzbd\n
Support for all relevant media IDs (IMDB, TMDB, TVDB, TVRage, TVMaze) and conversion between them
Query generation, meaning a query will be generated if only a media ID is provided in the search and the indexer doesn’t support the ID or if no results were found
Compatible with Sonarr, Radarr, NZBGet, SABnzbd, nzb360, CouchPotato, Mylar, Lazy Librarian, Sick Beard, Jackett/Cardigann, Watcher, etc.
Search and download history and extensive stats. E.g. indexer response times, download shares, NZB age, etc.
Authentication and multi-user support
Automatic update of NZB download status by querying configured downloaders
RSS support with configurable cache times
Torrent support (Although I prefer Jackett for this):
* For GUI searches, allowing you to download torrents to a blackhole folder
* A separate Torznab compatible endpoint for API requests, allowing you to merge multiple trackers
Extensive configurability
Migration of database and settings from v1

\n\n

\n26.1 Inclusion into AutoPirate

\n\n

To include NZBHydra2 in your AutoPirate stack, include the following in your autopirate.yml stack definition file:

\n\n\n

nzbhydra2:\n  image: linuxserver/hydra2:latest\n  env_file : /var/data/config/autopirate/nzbhydra2.env\n  volumes:\n   - /var/data/autopirate/nzbhydra2:/config\n  networks:\n  - internal\n\nnzbhydra2_proxy:\n  image: a5huynh/oauth2_proxy\n  env_file : /var/data/config/autopirate/nzbhydra2.env\n  networks:\n    - internal\n    - traefik_public\n  deploy:\n    labels:\n      - traefik.frontend.rule=Host:nzbhydra2.example.com\n      - traefik.docker.network=traefik_public\n      - traefik.port=4180\n  volumes:\n    - /var/data/config/autopirate/authenticated-emails.txt:/authenticated-ema\\\nils.txt\n  command: |\n    -cookie-secure=false\n    -upstream=http://nzbhydra2:5076\n    -redirect-url=https://nzbhydra2.example.com\n    -http-address=http://0.0.0.0:4180\n    -email-domain=example.com\n    -provider=github\n    -authenticated-emails-file=/authenticated-emails.txt\n

\n26.2 Assemble more tools..

\n\n

Continue through the list of tools below, adding whichever tools your want to use, and finishing with the end section:

\n\n

SABnzbd
NZBGet
RTorrent
Sonarr
Radarr
Mylar
Lazy Librarian
Headphones
Lidarr
NZBHydra
NZBHydra2 (this page)
Ombi
Jackett
Heimdall
\nEnd (launch the stack)

\n\n

\n26.3 Chef’s Notes

\n\n

In many cases, tools will integrate with each other. I.e., Radarr needs to talk to SABnzbd and NZBHydra2, Ombi needs to talk to Radarr, etc. Since each tool runs within the stack under its own name, just refer to each tool by name (i.e. “radarr”), and docker swarm will resolve the name to the appropriate container. You can identify the tool-specific port by looking at the docker-compose service definition.
Note that NZBHydra2 can co-exist with NZBHydra (1), but if you want your tools (Sonarr, Radarr, etc) to use NZBHydra2, you’ll need to change both the target hostname (to “hydra2”) and the target port (to 5076).

\n\n\n This is not a complete recipe - it’s a component of the AutoPirate “uber-recipe”, but has been split into its own page to reduce complexity.
\n

\n27 Ombi

\n\n

Ombi is a useful addition to the autopirate stack. Features include:

\n\n

Lets users request Movies and TV Shows (whether it being the entire series, an entire season, or even single episodes.)
Easily manage your requests

User management system (supports plex.tv, Emby and local accounts)

A landing page that will give you the availability of your Plex/Emby server and also add custom notification text to inform your users of downtime.
Allows your users to get custom notifications!
Will show if the request is already on plex or even if it’s already monitored.

Automatically updates the status of requests when they are available on Plex/Emby

\n\n

\n\n\n

\n27.1 Inclusion into AutoPirate

\n\n

To include Ombi in your AutoPirate stack, include the following in your autopirate.yml stack definition file:

\n\n\n

ombi:\n  image: linuxserver/ombi:latest\n  env_file : /var/data/config/autopirate/ombi.env\n  volumes:\n   - /var/data/autopirate/ombi:/config\n  networks:\n  - internal\n\nombi_proxy:\n  image: a5huynh/oauth2_proxy\n  env_file : /var/data/config/autopirate/ombi.env\n  networks:\n    - internal\n    - traefik_public\n  deploy:\n    labels:\n      - traefik.frontend.rule=Host:ombi.example.com\n      - traefik.docker.network=traefik_public\n      - traefik.port=4180\n  volumes:\n    - /var/data/config/autopirate/authenticated-emails.txt:/authenticated-ema\\\nils.txt\n  command: |\n    -cookie-secure=false\n    -upstream=http://ombi:3579\n    -redirect-url=https://ombi.example.com\n    -http-address=http://0.0.0.0:4180\n    -email-domain=example.com\n    -provider=github\n    -authenticated-emails-file=/authenticated-emails.txt\n

\n27.2 Assemble more tools..

\n\n

Continue through the list of tools below, adding whichever tools your want to use, and finishing with the end section:

\n\n

SABnzbd
NZBGet
RTorrent
Sonarr
Radarr
Mylar
Lazy Librarian
Headphones
Lidarr
NZBHydra
NZBHydra2
Ombi (this page)
Jackett
Heimdall
\nEnd (launch the stack)

\n\n

\n27.3 Chef’s Notes

\n\n

In many cases, tools will integrate with each other. I.e., Radarr needs to talk to SABnzbd and NZBHydra, Ombi needs to talk to Radarr, etc. Since each tool runs within the stack under its own name, just refer to each tool by name (i.e. “radarr”), and docker swarm will resolve the name to the appropriate container. You can identify the tool-specific port by looking at the docker-compose service definition.

\n\n\n This is not a complete recipe - it’s a component of the autopirate “uber-recipe”, but has been split into its own page to reduce complexity.
\n

\n28 Jackett

\n\n

Jackett works as a proxy server: it translates queries from apps (Sonarr, Radarr, Mylar, etc) into tracker-site-specific http queries, parses the html response, then sends results back to the requesting software.

\n\n

This allows for getting recent uploads (like RSS) and performing searches. Jackett is a single repository of maintained indexer scraping & translation logic - removing the burden from other apps.

\n\n

\n\n\n

\n28.1 Inclusion into AutoPirate

\n\n

To include Jackett in your AutoPirate stack, include the following in your autopirate.yml stack definition file:

\n\n\n

jackett:\n  image: linuxserver/jackett:latest\n  env_file : /var/data/config/autopirate/jackett.env\n  volumes:\n   - /var/data/autopirate/jackett:/config\n  networks:\n  - internal\n\njackett_proxy:\n  image: a5huynh/oauth2_proxy\n  env_file : /var/data/config/autopirate/jackett.env\n  networks:\n    - internal\n    - traefik_public\n  deploy:\n    labels:\n      - traefik.frontend.rule=Host:jackett.example.com\n      - traefik.docker.network=traefik_public\n      - traefik.port=4180\n  volumes:\n    - /var/data/config/autopirate/authenticated-emails.txt:/authenticated-ema\\\nils.txt\n  command: |\n    -cookie-secure=false\n    -upstream=http://jackett:9117\n    -redirect-url=https://jackett.example.com\n    -http-address=http://0.0.0.0:4180\n    -email-domain=example.com\n    -provider=github\n    -authenticated-emails-file=/authenticated-emails.txt\n

\n28.2 Assemble more tools..

\n\n

Continue through the list of tools below, adding whichever tools your want to use, and finishing with the end section:

\n\n

SABnzbd
NZBGet
RTorrent
Sonarr
Radarr
Mylar
Lazy Librarian
Headphones
Lidarr
NZBHydra
NZBHydra2
Ombi
Jackett (this page)
Heimdall
\nEnd (launch the stack)

\n\n

\n28.3 Chef’s Notes

\n\n

In many cases, tools will integrate with each other. I.e., Radarr needs to talk to SABnzbd and NZBHydra, Ombi needs to talk to Radarr, etc. Since each tool runs within the stack under its own name, just refer to each tool by name (i.e. “radarr”), and docker swarm will resolve the name to the appropriate container. You can identify the tool-specific port by looking at the docker-compose service definition.

\n\n\n This is not a complete recipe - it’s a component of the autopirate “uber-recipe”, but has been split into its own page to reduce complexity.
\n

\n29 Heimdall

\n\n

Heimdall Application Dashboard is a dashboard for all your web applications. It doesn’t need to be limited to applications though, you can add links to anything you like.

\n\n

Heimdall is an elegant solution to organise all your web applications. Its dedicated to this purpose so you wont lose your links in a sea of bookmarks.

\n\n

Heimdall provides a single URL to manage access to all of your autopirate tools, and includes “enhanced” (i.e., display stats within Heimdall without launching the app) access to NZBGet, SABnzbd, and friends.

\n\n

\n\n\n

\n29.1 Inclusion into AutoPirate

\n\n

To include Heimdall in your AutoPirate stack, include the following in your autopirate.yml stack definition file:

\n\n\n

  heimdall:\n    image: linuxserver/heimdall:latest\n    env_file: /var/data/config/autopirate/heimdall.env\n    volumes:\n      - /etc/localtime:/etc/localtime:ro      \n      - /var/data/heimdall:/config\n    networks:\n      - internal\n\n  heimdall_proxy:\n    image: funkypenguin/oauth2_proxy:latest\n    env_file : /var/data/config/autopirate/heimdall.env\n    networks:\n      - internal\n      - traefik_public\n    deploy:\n      labels:\n        - traefik.frontend.rule=Host:heimdall.example.com\n        - traefik.docker.network=traefik_public\n        - traefik.port=4180\n    volumes:\n      - /etc/localtime:/etc/localtime:ro  \n      - /var/data/config/autopirate/authenticated-emails.txt:/authenticated-e\\\nmails.txt\n    command: |\n      -cookie-secure=false\n      -upstream=http://heimdall:80\n      -redirect-url=https://heimdall.example.com\n      -http-address=http://0.0.0.0:4180\n      -email-domain=example.com\n      -provider=github\n      -authenticated-emails-file=/authenticated-emails.txt\n

\n29.2 Assemble more tools..

\n\n

Continue through the list of tools below, adding whichever tools your want to use, and finishing with the end section:

\n\n

SABnzbd
NZBGet
RTorrent
Sonarr
Radarr
Mylar
Lazy Librarian
Headphones
Lidarr
NZBHydra
NZBHydra2
Ombi
Jackett
Heimdall (this page)
\nEnd (launch the stack)

\n\n

\n29.3 Chef’s Notes

\n\n

In many cases, tools will integrate with each other. I.e., Radarr needs to talk to SABnzbd and NZBHydra, Ombi needs to talk to Radarr, etc. Since each tool runs within the stack under its own name, just refer to each tool by name (i.e. “radarr”), and docker swarm will resolve the name to the appropriate container. You can identify the tool-specific port by looking at the docker-compose service definition.
The inclusion of Heimdall was due to the efforts of @gkoerk in our Discord server. Thanks gkoerk!

\n\n\n This is not a complete recipe - it’s the conclusion to the AutoPirate “uber-recipe”, but has been split into its own page to reduce complexity.
\n

\nLaunch Autopirate stack

\n\n

Launch the AutoPirate stack by running docker stack deploy autopirate -c <path -to-docker-compose.yml>

\n\n

Confirm the container status by running “docker stack ps autopirate”, and wait for all containers to enter the “Running” state.

\n\n

Log into each of your new tools at its respective HTTPS URL. You’ll be prompted to authenticate against your OAuth provider, and upon success, redirected to the tool’s UI.

\n\n

\n29.4 Chef’s Notes

\n\n

This is a complex stack. Sing out in the comments if you found a flaw or need a hand :)

\n\n\n

hero: Duplicity - A boring recipe to backup your exciting stuff. Boring is good.

\n\n

\n30 Duplicity

\n\n

Intro

\n\n

\n\n\n

Duplicity backs directories by producing encrypted tar-format volumes and uploading them to a remote or local file server. Because duplicity uses librsync, the incremental archives are space efficient and only record the parts of files that have changed since the last backup. Because duplicity uses GnuPG to encrypt and/or sign these archives, they will be safe from spying and/or modification by the server.

\n\n

So what does this mean for our stack? It means we can leverage Duplicity to backup all our data-at-rest to a wide variety of cloud providers, including, but not limited to:

\n\n

acd_cli
Amazon S3
Backblaze B2
DropBox
ftp
Google Docs
Google Drive
Microsoft Azure
Microsoft Onedrive
Rackspace Cloudfiles
rsync
ssh/scp
SwiftStack

\n\n

\n30.1 Ingredients

\n\n

\nDocker swarm cluster with persistent shared storage\n
Credentials for one of the Duplicity’s supported upload destinations

\n\n

\n30.2 Preparation

\n\n

\nSetup data locations

\n\n

We’ll need a folder to store a docker-compose .yml file, and an associated .env file. If you’re following my filesystem layout, create /var/data/config/duplicity (for the config), and /var/data/duplicity (for the metadata) as follows:

\n\n\n

mkdir /var/data/config/duplicity\nmkdir /var/data/duplicity\ncd /var/data/config/duplicity\n

\n\n\n\n\n

\n(Optional) Create Google Cloud Storage bucket

\n\n

I didn’t already have an archival/backup provider, so I chose Google Cloud “cloud” storage for the low price-point - 0.7 cents per GB/month (Plus you start with $300 credit even when signing up for the free tier). You can use any destination supported by Duplicity’s URL scheme though, just make sure you specify the necessary environment variables.

\n\n

\nSign up, create an empty project, enable billing, and create a bucket. Give your bucket a unique name, example “jack-and-jills-bucket” (it’s unique across the entire Google Cloud)
Under “Storage” section > “Settings” > “Interoperability” tab > click “Enable interoperable access” and then “Create a new key” button and note both Access Key and Secret.

\n\n

\nPrepare environment

\n\n

Generate a random passphrase to use to encrypt your data. Save this somewhere safe, without it you won’t be able to restore!
Seriously, save. it. somewhere. safe.
Create duplicity.env, and populate with the following variables

\n\n

SRC=/var/data/\nDST=gs://jack-and-jills-bucket/yes-you-can-have-subdirectories\nTMPDIR=/tmp\nGS_ACCESS_KEY_ID=<YOUR GS ACCESS KEY>\nGS_SECRET_ACCESS_KEY=<YOUR GS SECRET ACCESS KEY>\n\nOPTIONS=--allow-source-mismatch --exclude /var/data/runtime --exclude /var/da\\\nta/registry --exclude /var/data/duplicity --archive-dir=/archive\nPASSPHRASE=<YOUR CHOSEN PASSPHRASE>\n

\n\n\n\n\n See the data layout reference for an explanation of the included/excluded paths above.
\n

\nRun a test backup

\n\n

Before we launch the automated daily backups, let’s run a test backup, as follows:

\n\n\n

docker run --env-file duplicity.env -it --rm -v \\\n/var/data:/var/data:ro -v /var/data/duplicity/tmp:/tmp -v \\\n/var/data/duplicity/archive:/archive tecnativa/duplicity \\\n/etc/periodic/daily/jobrunner\n

\n\n\n\n\n

You should see some activity, with a summary of bytes transferred at the end.

\n\n

\nRun a test restore

\n\n

Repeat after me: “If you don’t verify your backup, it’s not a backup”.

\n\n Depending on what tier of storage you chose from your provider (i.e., Google Coldline, or Amazon S3), you may be charged for downloading data.
\n

Run a variation of the following to confirm a file you expect to be backed up, is backed up. (I used traefik.yml from the traefik recipie, since this is likely to exist for every reader).

\n\n\n

docker run --env-file duplicity.env -it --rm \\\n-v /var/data:/var/data:ro \\\n-v /var/data/duplicity/tmp:/tmp \\\n-v /var/data/duplicity/archive:/archive tecnativa/duplicity \\\nduplicity list-current-files \\\n\\$DST | grep traefik.yml\n

\n\n\n\n

Once you’ve identified a file to test-restore, use a variation of the following to restore it to /tmp (from the perspective of the container - it’s actually /var/data/duplicity/tmp)

\n\n\n

docker run --env-file duplicity.env -it --rm \\\n-v /var/data:/var/data:ro \\\n-v /var/data/duplicity/tmp:/tmp \\\n-v /var/data/duplicity/archive:/archive \\\ntecnativa/duplicity duplicity restore \\\n--file-to-restore config/traefik/traefik.yml \\\n\\$DST /tmp/traefik-restored.yml\n

\n\n\n\n\n

Examine the contents of /var/data/duplicity/tmp/traefik-restored.yml to confirm it contains valid data.

\n\n

\nSetup Docker Swarm

\n\n

Now that we have confidence in our backup/restore process, let’s automate it by creating a docker swarm config file in docker-compose syntax (v3), something like this:

version: \"3\"\n\nservices:\n    backup:\n        image: tecnativa/duplicity\n        env_file: /var/data/config/duplicity/duplicity.env\n        networks:\n          - internal\n        volumes:\n          - /etc/localtime:/etc/localtime:ro\n          - /var/data:/var/data:ro\n          - /var/data/duplicity/tmp:/tmp\n          - /var/data/duplicity/archive:/archive\n\n\nnetworks:\n  internal:\n    driver: overlay\n    ipam:\n      config:\n        - subnet: 172.16.10.0/24\n

\n\n\n\n\n Setup unique static subnets for every stack you deploy. This avoids IP/gateway conflicts which can otherwise occur when you’re creating/removing stacks a lot. See my list here.
\n

\n30.3 Serving

\n\n

\nLaunch Duplicity stack

\n\n

Launch Duplicity stack by running docker stack deploy duplicity -c <path -to-docker-compose.yml>

\n\n

Nothing will happen. Very boring. But when the cron script fires (daily), duplicity will do its thing, and backup everything in /var/data to your cloud destination.

\n\n

\n30.4 Chef’s Notes

\n\n

Automatic backup can still fail if nobody checks that it’s running successfully. I’ll be working on an upcoming recipe to monitor the elements of the stack, including the success/failure of duplicity jobs.
The container provides the facility to specify an SMTP host and port, but not credentials, which makes it close to useless. As a result, I’ve left SMTP out of this recipe. To enable email notifications (if your SMTP server doesn’t require auth), add SMTP_HOST, SMTP_PORT, EMAIL_FROM and EMAIL_TO variables to duplicity.env

\n\n\n

hero: Real heroes backup their

\n\n

\n31 Elkar Backup

\n\n

Don’t be like Cameron. Backup your stuff.

\n\n

\n\n Ongoing development of this recipe is sponsored by The Common Observatory. Thanks guys!
\n [

\n\n](https://www.observe.global/)
\n

ElkarBackup is a free open-source backup solution based on RSync/RSnapshot. It’s basically a web wrapper around rsync/rsnapshot, which means that your backups are just files on a filesystem, utilising hardlinks for tracking incremental changes. I find this result more reassuring than a blob of compressed, (encrypted?) data that more sophisticated backup solutions would produce for you.

\n\n

\n\n\n

\n31.1 Details

\n\n

\n31.2 Ingredients

\n\n

\nDocker swarm cluster with persistent shared storage\n
\nTraefik configured per design
DNS entry for the hostname you intend to use, pointed to your keepalived IP

\n\n

\n31.3 Preparation

\n\n

\nSetup data locations

\n\n

We’ll need several directories to bind-mount into our container, so create them in /var/data/elkarbackup:

\n\n\n

mkdir -p /var/data/elkarbackup/{backups,uploads,sshkeys,database-dump}\nmkdir -p /var/data/runtime/elkarbackup/db\nmkdir -p /var/data/config/elkarbackup\n

\n\n\n\n\n

\nPrepare environment

\n\n

Create /var/data/config/elkarbackup/elkarbackup.env, and populate with the following variables

\n\n

SYMFONY__DATABASE__PASSWORD=password\nEB_CRON=enabled\nTZ='Etc/UTC'\n\n#SMTP - Populate these if you want email notifications\n#SYMFONY__MAILER__HOST=\n#SYMFONY__MAILER__USER=\n#SYMFONY__MAILER__PASSWORD=\n#SYMFONY__MAILER__FROM=\n\n# For mysql\nMYSQL_ROOT_PASSWORD=password\n\n#oauth2_proxy\nOAUTH2_PROXY_CLIENT_ID=\nOAUTH2_PROXY_CLIENT_SECRET=\nOAUTH2_PROXY_COOKIE_SECRET=\n

\n\n\n\n\n

Create /var/data/config/elkarbackup/elkarbackup-db-backup.env, and populate with the following, to setup the nightly database dump.

\n\n Running a daily database dump might be considered overkill, since ElkarBackup can be configured to backup its own database. However, making my own backup keeps the operation of this stack consistent with other stacks which employ MariaDB.
\n Also, did you ever hear about the guy who said “_I wish I had fewer backups”?
\n No, me either :shrug:
\n\n

# For database backup (keep 7 days daily backups)\nMYSQL_PWD=<same as SYMFONY__DATABASE__PASSWORD above>\nMYSQL_USER=root\nBACKUP_NUM_KEEP=7\nBACKUP_FREQUENCY=1d\n

\n\n\n\n\n

\nSetup Docker Swarm

\n\n

Create a docker swarm config file in docker-compose syntax (v3), something like this:

version: \"3\"\n\nservices:\n  db:\n    image: mariadb:10.4\n    env_file: /var/data/config/elkarbackup/elkarbackup.env\n    networks:\n      - internal\n    volumes:\n      - /etc/localtime:/etc/localtime:ro\n      - /var/data/runtime/elkarbackup/db:/var/lib/mysql\n\n  db-backup:\n    image: mariadb:10.4\n    env_file: /var/data/config/elkarbackup/elkarbackup-db-backup.env\n    volumes:\n      - /var/data/elkarbackup/database-dump:/dump\n      - /etc/localtime:/etc/localtime:ro\n    entrypoint: |\n      bash -c 'bash -s <<EOF\n      trap \"break;exit\" SIGHUP SIGINT SIGTERM\n      sleep 2m\n      while /bin/true; do\n        mysqldump -h db --all-databases | gzip -c > /dump/dump_\\`date +%d-%m-\\\n%Y\"_\"%H_%M_%S\\`.sql.gz\n        (ls -t /dump/dump*.sql.gz|head -n $$BACKUP_NUM_KEEP;ls /dump/dump*.sq\\\nl.gz)|sort|uniq -u|xargs rm -- {}\n        sleep $$BACKUP_FREQUENCY\n      done\n      EOF'\n    networks:\n    - internal\n\n  app:\n    image: elkarbackup/elkarbackup\n    env_file: /var/data/config/elkarbackup/elkarbackup.env\n    networks:\n      - internal\n    volumes:\n       - /etc/localtime:/etc/localtime:ro\n       - /var/data/:/var/data\n       - /var/data/elkarbackup/backups:/app/backups\n       - /var/data/elkarbackup/uploads:/app/uploads\n       - /var/data/elkarbackup/sshkeys:/app/.ssh\n\n   proxy:\n     image: funkypenguin/oauth2_proxy\n     env_file: /var/data/config/elkarbackup/elkarbackup.env\n     networks:\n       - traefik_public\n       - internal\n     deploy:\n       labels:\n         - traefik.frontend.rule=Host:elkarbackup.example.com\n         - traefik.port=4180\n     volumes:\n       - /var/data/config/traefik/authenticated-emails.txt:/authenticated-ema\\\nils.txt\n     command: |\n       -cookie-secure=false\n       -upstream=http://app:80\n       -redirect-url=https://elkarbackup.example.com\n       -http-address=http://0.0.0.0:4180\n       -email-domain=example.com\n       -provider=github\n       -authenticated-emails-file=/authenticated-emails.txt\n\nnetworks:\n  traefik_public:\n    external: true\n  internal:\n    driver: overlay\n    ipam:\n      config:\n        - subnet: 172.16.36.0/24\n

\n\n\n\n\n Setup unique static subnets for every stack you deploy. This avoids IP/gateway conflicts which can otherwise occur when you’re creating/removing stacks a lot. See my list here.
\n

\n31.4 Serving

\n\n

\nLaunch ElkarBackup stack

\n\n

Launch the ElkarBackup stack by running docker stack deploy elkarbackup -c <path -to-docker-compose.yml>

\n\n

Log into your new instance at https://YOUR-FQDN, with user “root” and the password default password “root”:

\n\n

\n\n\n

First thing you do, change your password, using the gear icon, and “Change Password” link:

\n\n

\n\n\n

Have a read of the Elkarbackup Docs - they introduce the concept of clients (hosts containing data to be backed up), jobs (what data gets backed up), policies (when is data backed up and how long is it kept).

\n\n

At the very least, you want to setup a client called “localhost” with an empty path (i.e., the job path will be accessed locally, without SSH), and then add a job to this client to backup /var/data, excluding /var/data/runtime and /var/data/elkarbackup/backup (unless you like “backup-ception”)

\n\n

\nCopying your backup data offsite

\n\n

From the WebUI, you can download a script intended to be executed on a remote host, to backup your backup data to an offsite location. This is a Good Idea(tm), but needs some massaging for a Docker swarm deployment.

\n\n

Here’s a variation to the standard script, which I’ve employed:

\n\n\n

#!/bin/bash\n\nREPOSITORY=/var/data/elkarbackup/backups\nSERVER=<target host member of docker swarm>\nSERVER_USER=elkarbackup\nUPLOADS=/var/data/elkarbackup/uploads\nTARGET=/srv/backup/elkarbackup\n\necho \"Starting backup...\"\necho \"Date: \" `date \"+%Y-%m-%d (%H:%M)\"`\n\nssh \"$SERVER_USER@$SERVER\" \"cd '$REPOSITORY'; find . -maxdepth 2 -mindepth 2\"\\\n | sed s/^..// | while read jobId\ndo\n    echo Backing up job $jobId\n    mkdir -p $TARGET/$jobId 2>/dev/null\n    rsync -aH --delete \"$SERVER_USER@$SERVER:$REPOSITORY/$jobId/\" $TARGET/$jo\\\nbId\ndone\n\necho Backing up uploads\nrsync -aH --delete \"$SERVER_USER@$SERVER\":\"$UPLOADS/\" $TARGET/uploads\n\nUSED=`df -h . | awk 'NR==2 { print $3 }'`\nUSE=`df -h . | awk 'NR==2 { print $5 }'`\nAVAILABLE=`df -h . | awk 'NR==2 { print $4 }'`\n\necho \"Backup finished succesfully!\"\necho \"Date: \" `date \"+%Y-%m-%d (%H:%M)\"`\necho \"\"\necho \"**** INFO ****\"\necho \"Used disk space: $USED ($USE)\"\necho \"Available disk space: $AVAILABLE\"\necho \"\"\n

\n\n\n\n\n You’ll note that I don’t use the script to create a mysql dump (since Elkar is running within a container anyway), rather I just rely on the database dump which is made nightly into /var/data/elkarbackup/database-dump/
\n

\nRestoring data

\n\n

Repeat after me : “It’s not a backup unless you’ve tested a restore”

\n\n I had some difficulty making restoring work well in the webUI. My attempts to “Restore to client” failed with an SSH error about “localhost” not found. I was able to download the backup from my web browser, so I considered it a successful restore, since I can retrieve the backed-up data either from the webUI or from the filesystem directly.
\n

To restore files form a job, click on the “Restore” button in the WebUI, while on the Jobs tab:

\n\n

\n\n\n

This takes you to a list of backup names and file paths. You can choose to download the entire contents of the backup from your browser as a .tar.gz, or to restore the backup to the client. If you click on the name of the backup, you can also drill down into the file structure, choosing to restore a single file or directory.

\n\n Ongoing development of this recipe is sponsored by The Common Observatory. Thanks guys!
\n [

\n\n](https://www.observe.global/)
\n

\n31.5 Chef’s Notes

\n\n

If you wanted to expose the ElkarBackup UI directly, you could remove the oauth2_proxy from the design, and move the traefik_public-related labels directly to the app service. You’d also need to add the traefik_public network to the app service.
The original inclusion of ElkarBackup was due to the efforts of @gpulido in our Discord server. Thanks Gabriel!

\n\n\n

\n32 Emby

\n\n

Emby (think “M.B.” or “Media Browser”) is best described as “like Plex but different” - It’s a bit geekier and less polished than Plex, but it allows for more flexibility and customization.

\n\n

\n\n\n

I’ve started experimenting with Emby as an alternative to Plex, because of the advanced parental controls it offers. Based on my experimentation thus far, I have a “kid-safe” profile which automatically logs in, and only displays kid-safe content, based on ratings.

\n\n

\n32.1 Ingredients

\n\n

\nDocker swarm cluster with persistent shared storage\n
\nTraefik configured per design
DNS entry for the hostname you intend to use, pointed to your keepalived IP

\n\n

\n32.2 Preparation

\n\n

\nSetup data locations

\n\n

We’ll need a location to store Emby’s library data, config files, logs and temporary transcoding space, so create /var/data/emby, and make sure it’s owned by the user and group who also own your media data.

\n\n\n

mkdir /var/data/emby\n

\n\n\n\n\n

\nPrepare environment

\n\n

Create emby.env, and populate with PUID/GUID for the user who owns the /var/data/emby directory (above) and your actual media content (in this example, the media content is at /srv/data)

\n\n\n

PUID=\nGUID=\n

\n\n\n\n\n

\nSetup Docker Swarm

\n\n

Create a docker swarm config file in docker-compose syntax (v3), something like this:

version: \"3.0\"\n\nservices:\n  emby:\n    image: emby/emby-server\n    env_file: /var/data/config/emby/emby.env\n    volumes:\n      - /var/data/emby/emby:/config\n      - /srv/data/:/data\n    deploy:\n      labels:\n        - traefik.frontend.rule=Host:emby.example.com\n        - traefik.docker.network=traefik_public\n        - traefik.port=8096\n    networks:\n        - traefik_public\n        - internal\n    ports:\n      - 8096:8096\n\nnetworks:\n  traefik_public:\n    external: true\n  internal:\n    driver: overlay\n    ipam:\n      config:\n        - subnet: 172.16.17.0/24\n

\n\n\n\n\n Setup unique static subnets for every stack you deploy. This avoids IP/gateway conflicts which can otherwise occur when you’re creating/removing stacks a lot. See my list here.
\n

\n32.3 Serving

\n\n

\nLaunch Emby stack

\n\n

Launch the stack by running docker stack deploy emby -c <path -to-docker-compose.yml>

\n\n

Log into your new instance at https://YOUR-FQDN, and complete the wizard-based setup to complete deploying your Emby.

\n\n

\n32.4 Chef’s Notes

\n\n

I didn’t use an oauth2_proxy for this stack, because it would interfere with mobile client support.
Got an NVIDIA GPU? See this blog post re how to use your GPU to transcode your media!
We don’t bother exposing the HTTPS port for Emby, since Traefik is doing the SSL termination for us already.

\n\n\n

\n33 Home Assistant

\n\n

Home Assistant is a home automation platform written in Python, with extensive support for 3rd-party home-automation platforms including Xaomi, Phillips Hue, and a bazillion others.

\n\n

\n\n\n

This recipie combines the extensibility of Home Assistant with the flexibility of InfluxDB (for time series data store) and Grafana (for beautiful visualisation of that data).

\n\n

\n33.1 Ingredients

\n\n

\nDocker swarm cluster with persistent shared storage\n
\nTraefik configured per design
DNS entry for the hostname you intend to use, pointed to your keepalived IP

\n\n

\n33.2 Preparation

\n\n

\nSetup data locations

\n\n

We’ll need several directories to bind-mount into our container, so create them in /var/data/homeassistant:

\n\n\n

mkdir /var/data/homeassistant\ncd /var/data/homeassistant\nmkdir -p {homeassistant,grafana,influxdb-backup}\n

\n\n\n\n\n

Now create a directory for the influxdb realtime data:

\n\n\n

mkdir /var/data/runtime/homeassistant/influxdb\n

\n\n\n\n\n

\nPrepare environment

\n\n

Create /var/data/config/homeassistant/grafana.env, and populate with the following - this is to enable grafana to work with oauth2_proxy without requiring an additional level of authentication:

\n\n

GF_AUTH_BASIC_ENABLED=false\n

\n\n\n\n\n

\nSetup Docker Swarm

\n\n

Create a docker swarm config file in docker-compose syntax (v3), something like this:

version: \"3\"\n\nservices:\n    influxdb:\n      image: influxdb\n      networks:\n        - internal\n      volumes:\n        - /var/data/homeassistant/influxdb:/var/lib/influxdb\n        - /etc/localtime:/etc/localtime:ro\n\n    homeassistant:\n      image: homeassistant/home-assistant\n      dns_search: hq.example.com\n      volumes:\n        - /var/data/homeassistant/homeassistant:/config\n        - /etc/localtime:/etc/localtime:ro\n      deploy:\n        labels:\n          - traefik.frontend.rule=Host:homeassistant.example.com\n          - traefik.docker.network=traefik_public\n          - traefik.port=8123\n      networks:\n        - traefik_public\n        - internal\n      ports:\n        - 8123:8123\n\n    grafana-app:\n      image: grafana/grafana\n      env_file : /var/data/config/homeassistant/grafana.env\n      volumes:\n        - /var/data/homeassistant/grafana:/var/lib/grafana\n        - /etc/localtime:/etc/localtime:ro\n      networks:\n        - internal\n\n    grafana-proxy:\n      image: a5huynh/oauth2_proxy\n      env_file : /var/data/config/homeassistant/grafana.env\n      dns_search: hq.example.com\n      networks:\n        - internal\n        - traefik_public\n      deploy:\n        labels:\n          - traefik.frontend.rule=Host:grafana.example.com\n          - traefik.docker.network=traefik_public\n          - traefik.port=4180\n      volumes:\n        - /var/data/config/homeassistant/authenticated-emails.txt:/authentica\\\nted-emails.txt\n      command: |\n        -cookie-secure=false\n        -upstream=http://grafana-app:3000\n        -redirect-url=https://grafana.example.com\n        -http-address=http://0.0.0.0:4180\n        -email-domain=example.com\n        -provider=github\n        -authenticated-emails-file=/authenticated-emails.txt\n\nnetworks:\n  traefik_public:\n    external: true\n  internal:\n    driver: overlay\n    ipam:\n      config:\n        - subnet: 172.16.13.0/24\n

\n\n\n\n\n Setup unique static subnets for every stack you deploy. This avoids IP/gateway conflicts which can otherwise occur when you’re creating/removing stacks a lot. See my list here.
\n

\n33.3 Serving

\n\n

\nLaunch Home Assistant stack

\n\n

Launch the Home Assistant stack by running docker stack deploy homeassistant -c <path -to-docker-compose.yml>

\n\n

Log into your new instance at https://YOUR-FQDN, the password you created in configuration.yml as “frontend - api_key”. Then setup a bunch of sensors, and log into https://grafana.YOUR FQDN and create some beautiful graphs :)

\n\n

\n33.4 Chef’s Notes

\n\n

I tried to protect Home Assistant using oauth2_proxy, but HA is incompatible with the websockets implementation used by Home Assistant. Until this can be fixed, I suggest that geeks set frontend: api_key to a long and complex string, and rely on this to prevent malevolent internet miscreants from turning their lights on at 2am!

\n\n\n

\n34 iBeacons with Home assistant

\n\n This is not a complete recipe - it’s an optional additional of the HomeAssistant “recipe”, since it only applies to a subset of users
\n

One of the most useful features of Home Assistant is location awareness. I don’t care if someone opens my office door when I’m home, but you bet I care about (and want to be notified) it if I’m away!

\n\n

\n34.1 Ingredients

\n\n

1. HomeAssistant per recipe
2. iBeacon(s) - This recipe is for https://s.click.aliexpress.com/e/bzyLCnAp

LightBlue Explorer

\n\n

\n34.2 Preparation

\n\n

\nWrite UUID to iBeacon

\n\n

The iBeacons come with no UUID. We use the LightBlue Explorer app to pair with them (code is “123456”), and assign own own UUID.

\n\n

Generate your own UUID, or get a random one at https://www.uuidgenerator.net/

\n\n

Plug in your iBeacon, launch LightBlue Explorer, and find your iBeacon. The first time you attempt to interrogate it, you’ll be prompted to pair. Although it’s not recorded anywhere in the documentation (grr!), the pairing code is 123456

\n\n

Having paired, you’ll be able to see the vital statistics of your iBeacon.

\n\n

\n34.3 Chef’s Notes

\n\n\n

hero: Huginn - A recipe for self-hosted, hackable version of IFFTT / Zapier

\n\n

\n35 Huginn

\n\n

Huginn is a system for building agents that perform automated tasks for you online. They can read the web, watch for events, and take actions on your behalf. Huginn’s Agents create and consume events, propagating them along a directed graph. Think of it as a hackable version of IFTTT or Zapier on your own server.

\n\n

\n\n

\n35.1 Ingredients

\n\n

\nDocker swarm cluster with persistent shared storage\n
\nTraefik configured per design

\n\n

\n35.2 Preparation

\n\n

\nSetup data locations

\n\n

Create the location for the bind-mount of the database, so that it’s persistent:

\n\n\n

mkdir -p /var/data/huginn/database\n

\n\n\n\n\n

\nCreate email address

\n\n

Strictly speaking, you don’t have to integrate Huginn with email. However, since we created our own mailserver stack earlier, it’s worth using it to enable emails within Huginn.

\n\n\n

cd /var/data/docker-mailserver/\n./setup.sh email add huginn@huginn.example.com my-password-here\n# Setup MX and DKIM if they don't already exist:\n./setup.sh config dkim\ncat config/opendkim/keys/huginn.example.com/mail.txt\n

\n\n\n\n\n

\nPrepare environment

\n\n

Create /var/data/huginn/huginn.env, and populate with the following variables. Set the “INVITATION_CODE” variable if you want to require users to enter a code to sign up (protects the UI from abuse) (The full list of Huginn environment variables is available here)

\n\n\n

# For huginn/huginn - essential\nSMTP_DOMAIN=your-domain-here.com\nSMTP_USER_NAME=you@gmail.com\nSMTP_PASSWORD=somepassword\nSMTP_SERVER=your-mailserver-here.com\nSMTP_PORT=587\nSMTP_AUTHENTICATION=plain\nSMTP_ENABLE_STARTTLS_AUTO=true\nINVITATION_CODE=<set an invitation code here>\nPOSTGRES_PORT_5432_TCP_ADDR=db\nPOSTGRES_PORT_5432_TCP_PORT=5432\nDATABASE_USERNAME=huginn\nDATABASE_PASSWORD=<database password>\nDATABASE_ADAPTER=postgresql\n\n# Optional extras for huginn/huginn, customize or append based on .env.exampl\\\ne lined above\nTWITTER_OAUTH_KEY=\nTWITTER_OAUTH_SECRET=\n\n# For postgres/postgres\nPOSTGRES_USER=huginn\nPOSTGRES_PASSWORD=<database password>\nBACKUP_NUM_KEEP=7\nBACKUP_FREQUENCY=1d\n

\n\n\n\n\n

\nSetup Docker Swarm

\n\n

Create a docker swarm config file in docker-compose syntax (v3), something like this:

version: '3'\n\nservices:\n\n  huginn:\n    image: huginn/huginn\n    env_file: /var/data/config/huginn/huginn.env\n    volumes:\n    - /etc/localtime:/etc/localtime:ro\n    networks:\n    - internal\n    - traefik\n    deploy:\n      labels:\n        - traefik.frontend.rule=Host:huginn.funkypenguin.co.nz\n        - traefik.docker.network=traefik\n        - traefik.port=3000\n\n  db:\n    env_file: /var/data/config/huginn/huginn.env\n    image: postgres:latest\n    volumes:\n      - /var/data/runtime/huginn/database:/var/lib/postgresql/data\n      - /etc/localtime:/etc/localtime:ro\n    networks:\n      - internal\n\n  db-backup:\n    image: postgres:latest\n    env_file: /var/data/config/huginn/huginn.env\n    volumes:\n      - /var/data/huginn/database-dump:/dump\n      - /etc/localtime:/etc/localtime:ro\n    entrypoint: |\n      bash -c 'bash -s <<EOF\n      trap \"break;exit\" SIGHUP SIGINT SIGTERM\n      sleep 2m\n      while /bin/true; do\n        pg_dump -Fc > /dump/dump_\\`date +%d-%m-%Y\"_\"%H_%M_%S\\`.psql\n        (ls -t /dump/dump*.psql|head -n $$BACKUP_NUM_KEEP;ls /dump/dump*.psql\\\n)|sort|uniq -u|xargs rm -- {}\n        sleep $$BACKUP_FREQUENCY\n      done\n      EOF'\n    networks:\n    - internal\n\nnetworks:\n  traefik:\n    external: true\n  internal:\n    driver: overlay\n    ipam:\n      config:\n        - subnet: 172.16.6.0/24\n

\n\n\n\n\n Setup unique static subnets for every stack you deploy. This avoids IP/gateway conflicts which can otherwise occur when you’re creating/removing stacks a lot. See my list here.
\n

\n35.3 Serving

\n\n

\nLaunch Huginn stack

\n\n

Launch the Huginn stack by running docker stack deploy huginn -c <path -to-docker-compose.yml>

\n\n

Log into your new instance at https://YOUR-FQDN. You’ll need to use the “Sign Up” button, and (optionally) enter your invitation code in order to create your account.

\n\n

\n35.4 Chef’s Notes

\n\n

1. I initially considered putting an oauth proxy in front of Huginn, but since the invitation code logic prevents untrusted access, and since using a proxy would break oauth for sevices like Twitter integration, I left it out.

\n\n\n

hero: Kanboard - A recipe to get your personal kanban on

\n\n

\n36 Kanboard

\n\n

Kanboard is a Kanban tool, developed by Frdric Guillot. (Who also happens to be the developer of my favorite RSS reader, Miniflux)

\n\n Kanboard is one of my sponsored projects - a project I financially support on a regular basis because of its utility to me. I use it both in my DayJob(tm), and to manage my overflowing, overly-optimistic personal commitments!
\n

Features include:

\n\n

Visualize your work
Limit your work in progress to be more efficient
Customize your boards according to your business activities
Multiple projects with the ability to drag and drop tasks
Reports and analytics
Fast and simple to use
Access from anywhere with a modern browser
Plugins and integrations with external services
Free, open source and self-hosted
Super simple installation

\n\n

\n\n\n

\n36.1 Ingredients

\n\n

\nDocker swarm cluster with persistent shared storage\n
\nTraefik configured per design
DNS entry pointing your NextCloud url (kanboard.example.com) to your keepalived IP

\n\n

\n36.2 Preparation

\n\n

\nSetup data locations

\n\n

Create the location for the bind-mount of the application data, so that it’s persistent:

\n\n\n

mkdir -p /var/data/kanboard\n

\n\n\n\n\n

\nSetup Environment

\n\n

If you intend to use an OAuth proxy to further secure public access to your instance, create a kanboard.env file to hold your environment variables, and populate with your OAuth provider’s details (the cookie secret you can just make up):

\n\n\n

# If you decide to protect kanboard with an oauth_proxy, complete these\nOAUTH2_PROXY_CLIENT_ID=\nOAUTH2_PROXY_CLIENT_SECRET=\nOAUTH2_PROXY_COOKIE_SECRET=\n

\n\n\n\n\n

\nSetup Docker Swarm

\n\n

Create a docker swarm config file in docker-compose syntax (v3), something like this:

version: '3'\n\nservices:\n  kanboard:\n    image: kanboard/kanboard\n    volumes:\n     - /var/data/kanboard/data:/var/www/app/data\n     - /var/data/kanboard/plugins:/var/www/app/plugins\n    networks:\n    - internal\n    deploy:\n      labels:\n        - traefik.frontend.rule=Host:kanboard.example.com\n        - traefik.docker.network=traefik_public\n        - traefik.port=80\n\n    proxy:\n      image: a5huynh/oauth2_proxy\n      env_file : /var/data/config/kanboard/kanboard.env\n      networks:\n        - internal\n        - traefik_public\n      deploy:\n        labels:\n          - traefik.frontend.rule=Host:kanboard.example.com\n          - traefik.docker.network=traefik_public\n          - traefik.port=4180\n      volumes:\n        - /var/data/config/kanboard/authenticated-emails.txt:/authenticated-e\\\nmails.txt\n      command: |\n        -cookie-secure=false\n        -upstream=http://app\n        -redirect-url=https://kanboard.example.com\n        -http-address=http://0.0.0.0:4180\n        -email-domain=example.com\n        -provider=github\n        -authenticated-emails-file=/authenticated-emails.txt\n\nnetworks:\n  traefik_public:\n    external: true\n  internal:\n    driver: overlay\n    ipam:\n      config:\n        - subnet: 172.16.8.0/24    \n

\n\n\n\n\n

\n36.3 Serving

\n\n

\nLaunch Kanboard stack

\n\n

Launch the Kanboard stack by running docker stack deploy kanboard -c <path -to-docker-compose.yml>

\n\n

Log into your new instance at https://YOUR-FQDN. Default credentials are admin/admin, after which you can change (under ‘profile’) and add more users.

\n\n

\n36.4 Chef’s Notes

\n\n

The default theme can be significantly improved by applying the ThemePlus plugin.
Kanboard becomes more useful when you integrate in/outbound email with MailGun, SendGrid, or Postmark.

\n\n\n

hero: Miniflux - A recipe for a lightweight minimalist RSS reader

\n\n

\n37 Miniflux

\n\n

Miniflux is a lightweight RSS reader, developed by Frdric Guillot. (Who also happens to be the developer of the favorite Open Source Kanban app, Kanboard)

\n\n

\n\n\n Miniflux is one of my sponsored projects - a project I financially support on a regular basis because of its utility to me. Although I get to process my RSS feeds less frequently than I’d like to!
\n

I’ve reviewed Miniflux in detail on my blog, but features (among many) that I appreciate:

\n\n

Compatible with the Fever API, read your feeds through existing mobile and desktop clients (This is the killer feature for me. I hardly ever read RSS on my desktop, I typically read on my iPhone or iPad, using Fiery Feeds or my new squeeze, Unread)
Send your bookmarks to Pinboard, Wallabag, Shaarli or Instapaper (I use this to automatically pin my bookmarks for collection on my blog)
Feeds can be configured to download a “full” version of the content (rather than an excerpt)
Use the Bookmarklet to subscribe to a website directly from any browsers

\n\n Some things changed when Miniflux 2.0 was released. For one thing, the only supported database is now postgresql (no more SQLite). External themes are gone, as is PHP (in favor of golang). It’s been a controversial change, but I’m keen on minimal and single-purpose, so I’m still very happy with the direction of development. The developer has laid out his opinions re the decisions he’s made in the course of development.
\n

\n37.1 Ingredients

\n\n

\nDocker swarm cluster with persistent shared storage\n
\nTraefik configured per design
DNS entry pointing your Miniflux url (i.e. miniflux.example.com) to your keepalived IP

\n\n

\n37.2 Preparation

\n\n

\nSetup data locations

\n\n

Create the location for the bind-mount of the application data, so that it’s persistent:

\n\n\n

mkdir -p /var/data/miniflux/database-dump\nmkdir -p /var/data/runtime/miniflux/database\n

\n\n\n\n\n

\nSetup environment

\n\n

Create /var/data/config/miniflux/miniflux.env something like this:

\n\n\n

DATABASE_URL=postgres://miniflux:secret@db/miniflux?sslmode=disable\nPOSTGRES_USER=miniflux\nPOSTGRES_PASSWORD=secret\n\n# This is necessary for the miniflux to update the db schema, even on an empt\\\ny DB\nRUN_MIGRATIONS=1\n\n# Uncomment this on first run, else leave it commented out after adding your \\\nown user account\nCREATE_ADMIN=1\nADMIN_USERNAME=admin\nADMIN_PASSWORD=test1234\n\n# For backups\nPGUSER=miniflux\nPGPASSWORD=secret\nPGHOST=db\nBACKUP_NUM_KEEP=7\nBACKUP_FREQUENCY=1d\n

\n\n\n\n\n

The entire application is configured using environment variables, including the initial username. Once you’ve successfully deployed once, comment out CREATE_ADMIN and the two successive lines.

\n\n

\nSetup Docker Swarm

\n\n

Create a docker swarm config file in docker-compose syntax (v3), something like this:

version: '3'\n\nservices:\n  miniflux:\n    image: miniflux/miniflux:2.0.7\n    env_file: /var/data/config/miniflux/miniflux.env\n    volumes:\n     - /etc/localtime:/etc/localtime:ro\n    networks:\n    - internal\n    - traefik_public\n    deploy:\n      labels:\n        - traefik.frontend.rule=Host:miniflux.example.com\n        - traefik.port=8080\n        - traefik.docker.network=traefik_public\n\n  db:\n    env_file: /var/data/config/miniflux/miniflux.env\n    image: postgres:10.1\n    volumes:\n      - /var/data/runtime/miniflux/database:/var/lib/postgresql/data\n      - /etc/localtime:/etc/localtime:ro\n    networks:\n      - internal\n\n  db-backup:\n    image: postgres:10.1\n    env_file: /var/data/config/miniflux/miniflux.env\n    volumes:\n      - /var/data/miniflux/database-dump:/dump\n      - /etc/localtime:/etc/localtime:ro\n    entrypoint: |\n      bash -c 'bash -s <<EOF\n      trap \"break;exit\" SIGHUP SIGINT SIGTERM\n      sleep 2m\n      while /bin/true; do\n        pg_dump -Fc > /dump/dump_\\`date +%d-%m-%Y\"_\"%H_%M_%S\\`.psql\n        (ls -t /dump/dump*.psql|head -n $$BACKUP_NUM_KEEP;ls /dump/dump*.psql\\\n)|sort|uniq -u|xargs rm -- {}\n        sleep $$BACKUP_FREQUENCY\n      done\n      EOF'\n    networks:\n    - internal\n\nnetworks:\n  traefik_public:\n    external: true\n  internal:\n    driver: overlay\n    ipam:\n      config:\n        - subnet: 172.16.22.0/24\n

\n\n\n\n\n

\n37.3 Serving

\n\n

\nLaunch Miniflux stack

\n\n

Launch the Miniflux stack by running docker stack deploy miniflux -c <path -to-docker-compose.yml>

\n\n

Log into your new instance at https://YOUR-FQDN, using the credentials you setup in the environment flie. After this, change your user/password as you see fit, and comment out the CREATE_ADMIN line in the env file (if you don’t, then an additional admin will be created the next time you deploy)

\n\n

\n37.4 Chef’s Notes

\n\n

1. Find the bookmarklet under the Settings -> Integration page.

\n\n\n

\n38 Munin

\n\n

Munin is a networked resource monitoring tool that can help analyze resource trends and “what just happened to kill our performance?” problems. It is designed to be very plug and play. A default installation provides a lot of graphs with almost no work.

\n\n

\n\n\n

Using Munin you can easily monitor the performance of your computers, networks, SANs, applications, weather measurements and whatever comes to mind. It makes it easy to determine “what’s different today” when a performance problem crops up. It makes it easy to see how you’re doing capacity-wise on any resources.

\n\n

Munin uses the excellent RRDTool (written by Tobi Oetiker) and the framework is written in Perl, while plugins may be written in any language. Munin has a master/node architecture in which the master connects to all the nodes at regular intervals and asks them for data. It then stores the data in RRD files, and (if needed) updates the graphs. One of the main goals has been ease of creating new plugins (graphs).

\n\n

\n38.1 Ingredients

\n\n

\nDocker swarm cluster with persistent shared storage\n
\nTraefik configured per design
DNS entry for the hostname you intend to use, pointed to your keepalived IP

\n\n

\n38.2 Preparation

\n\n

\nPrepare target nodes

\n\n

Depending on what you want to monitor, you’ll want to install munin-node. On Ubuntu/Debian, you’ll use apt-get install munin-node, and on RHEL/CentOS, run yum install munin-node. Remember to edit /etc/munin/munin-node.conf, and set your node to allow the server to poll it, by adding cidr_allow x.x.x.x/x.

\n\n

On CentOS Atomic, of course, you can’t install munin-node directly, but you can run it as a containerized instance. In this case, you can’t use swarm since you need the container running in privileged mode, so launch a munin-node container on each atomic host using:

\n\n\n

docker run -d --name munin-node --restart=always \\\n  --privileged --net=host \\\n  -v /:/rootfs:ro \\\n  -v /sys:/sys:ro \\\n  -e ALLOW=\"cidr_allow 0.0.0.0/0\" \\\n  -p 4949:4949 \\\n  --restart=always \\\n  funkypenguin/munin-node\n

\n\n\n\n\n

\nSetup data locations

\n\n

We’ll need several directories to bind-mount into our container, so create them in /var/data/munin:

\n\n\n

mkdir /var/data/munin\ncd /var/data/munin\nmkdir -p {log,lib,run,cache}\n

\n\n\n\n\n

\nPrepare environment

\n\n

Create /var/data/config/munin/munin.env, and populate with the following variables. Use the OAUTH2 variables if you plan to use an oauth2_proxy to protect munin, and set at a minimum the MUNIN_USER, MUNIN_PASSWORD, and NODES values:

\n\n\n

# Use these if you plan to protect the webUI with an oauth_proxy\nOAUTH2_PROXY_CLIENT_ID=\nOAUTH2_PROXY_CLIENT_SECRET=\nOAUTH2_PROXY_COOKIE_SECRET=\n\nMUNIN_USER=odin\nMUNIN_PASSWORD=lokiisadopted\nSMTP_HOST=smtp.example.com\nSMTP_PORT=587\nSMTP_USERNAME=smtp-username\nSMTP_PASSWORD=smtp-password\nSMTP_USE_TLS=false\nSMTP_ALWAYS_SEND=false\nSMTP_MESSAGE='[${var:group};${var:host}] -> ${var:graph_title} -> warnings: $\\\n{loop<,>:wfields  ${var:label}=${var:value}} / criticals: ${loop<,>:cfields  \\\n${var:label}=${var:value}}'\nALERT_RECIPIENT=monitoring@example.com\nALERT_SENDER=alerts@example.com\nNODES=\"node1:192.168.1.1 node2:192.168.1.2 node3:192.168.1.3\"\nSNMP_NODES=\"router1:10.0.0.254:9999\"\n

\n\n\n\n\n

\nSetup Docker Swarm

\n\n

Create a docker swarm config file in docker-compose syntax (v3), something like this:

version: '3'\n\nservices:\n\n  munin:\n    image: funkypenguin/munin-server\n    env_file: /var/data/config/munin/munin.env    \n    networks:\n      - internal\n    volumes:\n      - /var/data/munin/log:/var/log/munin\n      - /var/data/munin/lib:/var/lib/munin\n      - /var/data/munin/run:/var/run/munin\n      - /var/data/munin/cache:/var/cache/munin  \n\n  proxy:\n    image: funkypenguin/oauth2_proxy\n    env_file: /var/data/config/munin/munin.env\n    networks:\n      - traefik_public\n      - internal\n    deploy:\n      labels:\n        - traefik.frontend.rule=Host:munin.example.com\n        - traefik.docker.network=traefik\n        - traefik.port=4180\n    command: |\n      -cookie-secure=false\n      -upstream=http://munin:8080\n      -redirect-url=https://munin.example.com\n      -http-address=http://0.0.0.0:4180\n      -email-domain=example.com\n      -provider=github\n\nnetworks:\n  traefik_public:\n    external: true\n  internal:\n    driver: overlay\n    ipam:\n      config:\n        - subnet: 172.16.24.0/24\n

\n\n\n\n\n Setup unique static subnets for every stack you deploy. This avoids IP/gateway conflicts which can otherwise occur when you’re creating/removing stacks a lot. See my list here.
\n

\n38.3 Serving

\n\n

\nLaunch Munin stack

\n\n

Launch the Munin stack by running docker stack deploy munin -c <path -to-docker-compose.yml>

\n\n

Log into your new instance at https://YOUR-FQDN, with user and password password you specified in munin.env above.

\n\n

\n38.4 Chef’s Notes

\n\n

1. If you wanted to expose the Munin UI directly, you could remove the oauth2_proxy from the design, and move the traefik-related labels directly to the munin container. You’d also need to add the traefik_public network to the munin container.

\n\n\n

hero: Backup all your stuff. Share it. Privately.

\n\n

\n39 NextCloud

\n\n Ongoing development of this recipe is sponsored by The Common Observatory. Thanks guys!
\n [

\n\n](https://www.observe.global/)
\n

NextCloud (a fork of OwnCloud, led by original developer Frank Karlitschek) is a suite of client-server software for creating and using file hosting services. It is functionally similar to Dropbox, although Nextcloud is free and open-source, allowing anyone to install and operate it on a private server.
- https://en.wikipedia.org/wiki/Nextcloud

\n\n

\n\n\n

This recipe is based on the official NextCloud docker image, but includes seprate containers ofor the database (MariaDB), Redis (for transactional locking), Apache Solr (for full-text searching), automated database backup, (you do backup the stuff you care about, right?) and a separate cron container for running NextCloud’s 15-min crons.

\n\n

\n39.1 Ingredients

\n\n

\nDocker swarm cluster with persistent shared storage\n
\nTraefik configured per design
DNS entry pointing your NextCloud url (nextcloud.example.com) to your keepalived IP

\n\n

\n39.2 Preparation

\n\n

\nSetup data locations

\n\n

We’ll need several directories for static data to bind-mount into our container, so create them in /var/data/nextcloud (so that they can be backed up)

\n\n\n

mkdir /var/data/nextcloud\ncd /var/data/nextcloud\nmkdir -p {html,apps,config,data,database-dump}\n

\n\n\n\n\n

Now make more directories for runtime data (so that they can be not backed-up):

\n\n\n

mkdir /var/data/runtime/nextcloud\ncd /var/data/runtime/nextcloud\nmkdir -p {db,redis}\n

\n\n\n\n\n

\nPrepare environment

\n\n

Create nextcloud.env, and populate with the following variables

\n\n

NEXTCLOUD_ADMIN_USER=admin\nNEXTCLOUD_ADMIN_PASSWORD=FVuojphozxMVyaYCUWomiP9b\nMYSQL_HOST=db\n\n# For mysql\nMYSQL_ROOT_PASSWORD=<set to something secure>\nMYSQL_DATABASE=nextcloud\nMYSQL_USER=nextcloud\nMYSQL_PASSWORD=set to something secure>\n

\n\n\n\n\n

Now create a separate nextcloud-db-backup.env file, to capture the environment variables necessary to perform the backup. (If the same variables are shared with the mariadb container, they cause issues with database access)

\n\n\n

# For database backup (keep 7 days daily backups)\nMYSQL_PWD=<set to something secure, same as MYSQL_ROOT_PASSWORD above>\nMYSQL_USER=root\nBACKUP_NUM_KEEP=7\nBACKUP_FREQUENCY=1d\n

\n\n\n\n\n

\nSetup Docker Swarm

\n\n

Create a docker swarm config file in docker-compose syntax (v3), something like this:

version: \"3.0\"\n\nservices:\n  nextcloud:\n    image: nextcloud\n    env_file: /var/data/config/nextcloud/nextcloud.env\n    networks:\n      - internal\n      - traefik_public\n    deploy:\n      labels:\n        - traefik.frontend.rule=Host:nextcloud.example.com\n        - traefik.docker.network=traefik_public\n        - traefik.port=80\n    volumes:\n    - /var/data/nextcloud/html:/var/www/html\n    - /var/data/nextcloud/apps:/var/www/html/custom_apps\n    - /var/data/nextcloud/config:/var/www/html/config\n    - /var/data/nextcloud/data:/var/www/html/data\n\n  db:\n    image: mariadb:10\n    env_file: /var/data/config/nextcloud/nextcloud.env\n    networks:\n      - internal\n    volumes:\n      - /var/data/runtime/nextcloud/db:/var/lib/mysql\n\n  db-backup:\n    image: mariadb:10\n    env_file: /var/data/config/nextcloud/nextcloud.env\n    volumes:\n      - /var/data/nextcloud/database-dump:/dump\n      - /etc/localtime:/etc/localtime:ro\n    entrypoint: |\n      bash -c 'bash -s <<EOF\n      trap \"break;exit\" SIGHUP SIGINT SIGTERM\n      sleep 2m\n      while /bin/true; do\n        mysqldump -h db --all-databases | gzip -c > /dump/dump_\\`date +%d-%m-\\\n%Y\"_\"%H_%M_%S\\`.sql.gz\n        (ls -t /dump/dump*.sql.gz|head -n $$BACKUP_NUM_KEEP;ls /dump/dump*.sq\\\nl.gz)|sort|uniq -u|xargs rm -- {}\n        sleep $$BACKUP_FREQUENCY\n      done\n      EOF'\n    networks:\n    - internal\n\n  redis:\n    image: redis:alpine\n    networks:\n      - internal\n    volumes:\n      - /var/data/runtime/nextcloud/redis:/data\n\n  cron:\n    image: nextcloud\n    volumes:\n      - /var/data/nextcloud/:/var/www/html\n    user: www-data\n    networks:\n      - internal\n    entrypoint: |\n      bash -c 'bash -s <<EOF\n        trap \"break;exit\" SIGHUP SIGINT SIGTERM\n        while [ ! -f /var/www/html/config/config.php ]; do\n          sleep 1\n        done\n        while true; do\n          php -f /var/www/html/cron.php\n          sleep 15m\n        done\n      EOF'\n\nnetworks:\n  traefik_public:\n    external: true\n  internal:\n    driver: overlay\n    ipam:\n      config:\n        - subnet: 172.16.12.0/24\n

\n\n\n\n\n Setup unique static subnets for every stack you deploy. This avoids IP/gateway conflicts which can otherwise occur when you’re creating/removing stacks a lot. See my list here.
\n

\n39.3 Serving

\n\n

\nLaunch NextCloud stack

\n\n

Launch the NextCloud stack by running docker stack deploy nextcloud -c <path -to-docker-compose.yml>

\n\n

Log into your new instance at https://YOUR-FQDN, with user “admin” and the password you specified in nextcloud.env.

\n\n

\nEnable redis

\n\n

To make NextCloud a little snappier, edit /var/data/nextcloud/config/config.php (now that it’s been created on the first container launch), and add the following:

\n\n\n

  'redis' => array(\n     'host' => 'redis',\n     'port' => 6379,\n      ),\n

\n\n\n\n\n

\nUse service discovery

\n\n

Want to use Calendar/Contacts on your iOS device? Want to avoid dictating long, rambling URL strings to your users, like https://nextcloud.batcave.com/remote.php/dav/principals/users/USERNAME/ ?

\n\n

Huzzah! NextCloud supports service discovery for CalDAV/CardDAV, allowing you to simply tell your device the primary URL of your server (nextcloud.batcave.org, for example), and have the device figure out the correct WebDAV path to use.

\n\n

We (and anyone else using the NextCloud Docker image) are using an SSL-terminating reverse proxy (Traefik) in front of our NextCloud container. In fact, it’s not possible to setup SSL within the NextCloud container.

\n\n

When using a reverse proxy, your device requests a URL from your proxy (https://nextcloud.batcave.com/.well-known/caldav), and the reverse proxy then passes that request unencrypted to the internal URL of the NextCloud instance (i.e., http://172.16.12.123/.well-known/caldav)

\n\n

The Apache webserver on the NextCloud container (knowing it was spoken to via HTTP), responds with a 301 redirect to http://nextcloud.batcave.com/remote.php/dav/. See the problem? You requested an HTTPS (encrypted) url, and in return, you received a redirect to an HTTP (unencrypted) URL. Any sensible client (iOS included) will refuse such schenanigans.

\n\n

To correct this, we need to tell NextCloud to always redirect the .well-known URLs to an HTTPS location. This can only be done after deploying NextCloud, since it’s only on first launch of the container that the .htaccess file is created in the first place.

\n\n

To make NextCloud service discovery work with Traefik reverse proxy, edit /var/data/nextcloud/html/.htaccess, and change this:

\n\n\n

RewriteRule ^\\.well-known/carddav /remote.php/dav/ [R=301,L]\nRewriteRule ^\\.well-known/caldav /remote.php/dav/ [R=301,L]\n

\n\n\n\n\n

To this:

\n\n\n

RewriteRule ^\\.well-known/carddav https://%{SERVER_NAME}/remote.php/dav/ [R=3\\\n01,L]\nRewriteRule ^\\.well-known/caldav https://%{SERVER_NAME}/remote.php/dav/ [R=30\\\n1,L]\n

\n\n\n\n\n

Then restart your container with docker service update nextcloud_nextcloud --force to restart apache.

\n\n

Your can test for success by running curl -i https://nextcloud.batcave.org/.well-known/carddav. You should get a 301 redirect to your equivalent of https://nextcloud.batcave.org/remote.php/dav/, as below:

\n\n\n

[davidy:~] % curl -i https://nextcloud.batcave.org/.well-known/carddav\nHTTP/2 301\ncontent-type: text/html; charset=iso-8859-1\ndate: Wed, 12 Dec 2018 08:30:11 GMT\nlocation: https://nextcloud.batcave.org/remote.php/dav/\n

\n\n\n\n\n

Note that this .htaccess can be overwritten by NextCloud, and you may have to reapply the change in future. I’ve created an issue requesting a permanent fix.

\n\n Ongoing development of this recipe is sponsored by The Common Observatory. Thanks guys!
\n [

\n\n](https://www.observe.global/)
\n

\n39.4 Chef’s Notes

\n\n

Since many of my other recipes use PostgreSQL, I’d have preferred to use Postgres over MariaDB, but MariaDB seems to be the preferred database type.
I’m not the first user to stumble across the service discovery bug with reverse proxies.

\n\n\n

\n40 OwnTracks

\n\n

OwnTracks allows you to keep track of your own location. You can build your private location diary or share it with your family and friends. OwnTracks is open-source and uses open protocols for communication so you can be sure your data stays secure and private.

\n\n

\n\n\n

Using a smartphone app, OwnTracks allows you to collect and analyse your own location data without sharing this data with a cloud provider (i.e. Apple, Google). Potential use cases are:

\n\n

Sharing family locations without relying on Apple Find-My-friends
Performing automated actions in HomeAssistant when you arrive/leave home

\n\n

\n40.1 Ingredients

\n\n

\nDocker swarm cluster with persistent shared storage\n
\nTraefik configured per design
DNS entry for the hostname you intend to use, pointed to your keepalived IP

\n\n

\n40.2 Preparation

\n\n

\nSetup data locations

\n\n

We’ll need a directory so store OwnTracks’ data , so create /var/data/owntracks:

\n\n\n

mkdir /var/data/owntracks\n

\n\n\n\n\n

\nPrepare environment

\n\n

Create owntracks.env, and populate with the following variables

\n\n\n

OAUTH2_PROXY_CLIENT_ID=\nOAUTH2_PROXY_CLIENT_SECRET=\nOAUTH2_PROXY_COOKIE_SECRET=\n\nOTR_USER=recorder\nOTR_PASS=yourpassword\nOTR_HOST=owntracks.example.com\n

\n\n\n\n\n

\nSetup Docker Swarm

\n\n

Create a docker swarm config file in docker-compose syntax (v3), something like this:

version: \"3.0\"\n\nservices:\n    owntracks-app:\n      image: funkypenguin/owntracks\n      env_file : /var/data/config/owntracks/owntracks.env\n      volumes:\n        - /var/data/owntracks:/owntracks\n      networks:\n        - internal\n      ports:\n        - 1883:1883\n        - 8883:8883\n        - 8083:8083\n\n    owntracks-proxy:\n      image: a5huynh/oauth2_proxy\n      env_file : /var/data/config/owntracks/owntracks.env\n      networks:\n        - internal\n        - traefik_public\n      deploy:\n        labels:\n              - traefik.frontend.rule=Host:owntracks.example.com\n          - traefik.docker.network=traefik_public\n          - traefik.port=4180\n      volumes:\n        - /var/data/config/owntracks/authenticated-emails.txt:/authenticated-\\\nemails.txt\n      command: |\n        -cookie-secure=false\n        -upstream=http://owntracks-app:8083\n        -redirect-url=https://owntracks.example.com\n        -http-address=http://0.0.0.0:4180\n        -email-domain=example.com\n        -provider=github\n        -authenticated-emails-file=/authenticated-emails.txt\n\nnetworks:\n  traefik_public:\n    external: true\n  internal:\n    driver: overlay\n    ipam:\n      config:\n        - subnet: 172.16.15.0/24\n

\n\n\n\n\n Setup unique static subnets for every stack you deploy. This avoids IP/gateway conflicts which can otherwise occur when you’re creating/removing stacks a lot. See my list here.
\n

\n40.3 Serving

\n\n

\nLaunch OwnTracks stack

\n\n

Launch the OwnTracks stack by running docker stack deploy owntracks -c <path -to-docker-compose.yml>

\n\n

Log into your new instance at https://YOUR-FQDN, with user “root” and the password you specified in gitlab.env.

\n\n

\n40.4 Chef’s Notes

\n\n

If you wanted to expose the OwnTracks Web UI directly, you could remove the oauth2_proxy from the design, and move the traefik-related labels directly to the wekan container. You’d also need to add the traefik network to the owntracks container.
I’m using my own image rather than owntracks/recorderd, because of a potentially swarm-breaking bug I found in the official container. If this gets resolved (or if I was mistaken) I’ll update the recipe accordingly.
By default, you’ll get a fully accessible, unprotected MQTT broker. This may not be suitable for public exposure, so you’ll want to look into securing mosquitto with TLS and ACLs.

\n\n\n

\n41 phpIPAM

\n\n

phpIPAM is an open-source web IP address management application (IPAM). Its goal is to provide light, modern and useful IP address management. It is php-based application with MySQL database backend, using jQuery libraries, ajax and HTML5/CSS3 features.

\n\n

\n\n\n

phpIPAM fulfils a non-sexy, but important role - It helps you manage your IP address allocation.

\n\n

\n41.1 Why should you care about this?

\n\n

You probably have a home network, with 20-30 IP addresses, for your family devices, your , your smart TV, etc. If you want to (a) monitor them, and (b) audit who does what, you care about what IPs they’re assigned by your DHCP server.

\n\n

You could simple keep track of all devices with leases in your DHCP server, but what happens if your (hypothetical?) Ubiquity Edge Router X crashes and burns due to lack of disk space, and you loose track of all your leases? Well, you have to start from scratch, is what!

\n\n

And that HomeAssistant config, which you so carefully compiled, refers to each device by IP/DNS name, so you’d better make sure you recreate it consistently!

\n\n

Enter phpIPAM. A tool designed to help home keeps as well as large organisations keep track of their IP (and VLAN, VRF, and AS number) allocations.

\n\n

\n41.2 Ingredients

\n\n

\nDocker swarm cluster with persistent shared storage\n
\nTraefik configured per design
DNS entry for the hostname (i.e. “phpipam.your-domain.com”) you intend to use for phpIPAM, pointed to your keepalived IPIP

\n\n

\n41.3 Preparation

\n\n

\nSetup data locations

\n\n

We’ll need several directories to bind-mount into our container, so create them in /var/data/phpipam:

\n\n\n

mkdir /var/data/phpipam/databases-dump -p\nmkdir /var/data/runtime/phpipam -p\n

\n\n\n\n\n

\nPrepare environment

\n\n

Create phpipam.env, and populate with the following variables

\n\n

# Setup for github, phpipam application\nOAUTH2_PROXY_CLIENT_ID=\nOAUTH2_PROXY_CLIENT_SECRET=\nOAUTH2_PROXY_COOKIE_SECRET=\n\n# For MariaDB/MySQL database\nMYSQL_ROOT_PASSWORD=imtoosecretformyshorts\nMYSQL_DATABASE=phpipam\nMYSQL_USER=phpipam\nMYSQL_PASSWORD=secret\n\n# phpIPAM-specific variables\nMYSQL_ENV_MYSQL_USER=phpipam\nMYSQL_ENV_MYSQL_PASSWORD=secret\nMYSQL_ENV_MYSQL_DB=phpipam\nMYSQL_ENV_MYSQL_HOST=db\n\n# For backup\nBACKUP_NUM_KEEP=7\nBACKUP_FREQUENCY=1d\n

\n\n\n\n\n

Additionally, create phpipam-backup.env, and populate with the following variables:

\n\n\n

# For MariaDB/MySQL database\nMYSQL_ROOT_PASSWORD=imtoosecretformyshorts\nMYSQL_DATABASE=phpipam\nMYSQL_USER=phpipam\nMYSQL_PASSWORD=secret\n\n# For backup\nBACKUP_NUM_KEEP=7\nBACKUP_FREQUENCY=1d\n

\n\n\n\n\n

\nCreate nginx.conf

\n\n

I usually protect my stacks using an oauth proxy container in front of the app. This protects me from either accidentally exposing a platform to the world, or having a insecure platform accessed and abused.

\n\n

In the case of phpIPAM, the oauth_proxy creates an additional complexity, since it passes the “Authorization” HTTP header to the phpIPAM container. phpIPAH then examines the header, determines that the provided username (my email address associated with my oauth provider) doesn’t match a local user account, and denies me access without the opportunity to retry.

\n\n

The (dirty) solution I’ve come up with is to insert an Nginx instance in the path between the oauth_proxy and the phpIPAM container itself. Nginx can remove the authorization header, so that phpIPAM can prompt me to login with a web-based form.

\n\n

Create /var/data/phpipam/nginx.conf as follows:

\n\n\n

upstream app-upstream {\n    server app:80;\n}\n\nserver {\n    listen 80;\n    server_name ~.;\n\n    # Just redirect everything to the upstream\n    # Yes, it's embarassing. We are just a mechanism to strip an AUTH header \\\n:(\n    location ^~ / {\n        proxy_pass http://app-upstream;\n\tproxy_set_header       Authorization \"\";\n    }\n\n}\n

\n\n\n\n\n

\nSetup Docker Swarm

\n\n

Create a docker swarm config file in docker-compose syntax (v3), something like this:

version: '3'\n\nservices:\n\n  db:\n    image: mariadb:10\n    env_file: /var/data/config/phpipam/phpipam.env\n    networks:\n      - internal\n    volumes:\n      - /var/data/runtime/phpipam/db:/var/lib/mysql\n\n  proxy:\n    image: funkypenguin/oauth2_proxy\n    env_file: /var/data/config/phpipam/phpipam.env\n    networks:\n      - internal\n      - traefik_public\n    deploy:\n      labels:\n        - traefik.frontend.rule=Host:phpipam.example.com\n        - traefik.docker.network=traefik_public\n        - traefik.port=4180\n    volumes:\n      - /var/data/config/phpipam/authenticated-emails.txt:/authenticated-emai\\\nls.txt\n    command: |\n      -cookie-secure=false\n      -upstream=http://nginx\n      -redirect-url=https://phpipam.example.com\n      -http-address=http://0.0.0.0:4180\n      -email-domain=example.com\n      -provider=github\n      -authenticated-emails-file=/authenticated-emails.txt\n\n  # Wait, what? Why do we have an oauth_proxy _and_ an nginx frontend for a s\\\nimple webapp?\n  # Well, it's a long story. Basically, the phpipam container sees the \"auth\"\\\n headers passed by the\n  # oauth_proxy, and decides to use these exclusively to authenticate users. \\\nSo no web-based login form, just \"access denied\"\n  # To work around this, we add nginx reverse proxy to the mix. A PITA, but a\\\nn easy way to solve without altering the PHPIPAM code\n  nginx:\n    image: nginx:latest\n    networks:\n      - internal\n    volumes:\n      - /var/data/phpipam/nginx.conf:/etc/nginx/conf.d/default.conf:ro\n\n  app:\n    image: pierrecdn/phpipam\n    env_file: /var/data/config/phpipam/phpipam.env\n    networks:\n      - internal\n\n  db-backup:\n    image: mariadb:10\n    env_file: /var/data/config/phpipam/phpipam.env\n    volumes:\n      - /var/data/phpipam/database-dump:/dump\n      - /etc/localtime:/etc/localtime:ro\n    entrypoint: |\n      bash -c 'bash -s <<EOF\n      trap \"break;exit\" SIGHUP SIGINT SIGTERM\n      sleep 2m\n      while /bin/true; do\n        mysqldump -h db --all-databases | gzip -c > /dump/dump_\\`date +%d-%m-\\\n%Y\"_\"%H_%M_%S\\`.sql.gz\n        (ls -t /dump/dump*.sql.gz|head -n $$BACKUP_NUM_KEEP;ls /dump/dump*.sq\\\nl.gz)|sort|uniq -u|xargs rm -- {}\n        sleep $$BACKUP_FREQUENCY\n      done\n      EOF'\n    networks:\n      - internal\n\nnetworks:\n  traefik_public:\n    external: true\n  internal:\n    driver: overlay\n    ipam:\n      config:\n        - subnet: 172.16.47.0/24\n

\n\n\n\n\n Setup unique static subnets for every stack you deploy. This avoids IP/gateway conflicts which can otherwise occur when you’re creating/removing stacks a lot. See my list here.
\n

\n41.4 Serving

\n\n

\nLaunch phpIPAM stack

\n\n

Launch the phpIPAM stack by running docker stack deploy phpipam -c <path -to-docker-compose.yml>

\n\n

Log into your new instance at https://YOUR-FQDN, and follow the on-screen prompts to set your first user/password.

\n\n

\n41.5 Chef’s Notes

\n\n

1. If you wanted to expose the phpIPAM UI directly, you could remove the oauth2_proxy and the nginx services from the design, and move the traefik_public-related labels directly to the phpipam container. You’d also need to add the traefik_public network to the phpipam container.

\n\n\n

hero: A recipe to manage your Media

\n\n

\n42 Plex

\n\n

Plex is a client-server media player system and software suite comprising two main components (a media server and client applications)

\n\n

\n\n\n

\n42.1 Ingredients

\n\n

\nDocker swarm cluster with persistent shared storage\n
\nTraefik configured per design
A DNS entry for the hostname you intend to use, pointed to your keepalived IP

\n\n

\n42.2 Preparation

\n\n

\nSetup data locations

\n\n

We’ll need a directories to bind-mount into our container for Plex to store its library, so create /var/data/plex:

\n\n\n

mkdir /var/data/plex\n

\n\n\n\n\n

\nPrepare environment

\n\n

Create plex.env, and populate with the following variables. Set PUID and GUID to the UID and GID of the user who owns your media files, on the local filesystem

\n\n\n

EDGE=1\nVERSION=latest\nPUID=42\nPGID=42\n

\n\n\n\n\n

\nSetup Docker Swarm

\n\n

Create a docker swarm config file in docker-compose syntax (v3), something like this:

version: \"3.0\"\n\nservices:\n  plex:\n    image: linuxserver/plex\n    env_file: plex.env\n    volumes:\n      - /var/data/config/plex:/config\n      - /var/data/media:/media\n    deploy:\n      labels:\n        - traefik.frontend.rule=Host:plex.example.com\n        - traefik.docker.network=traefik_public\n        - traefik.port=32400\n    networks:\n        - traefik_public\n        - internal\n    ports:\n      - 32469:32469\n      - 32400:32400\n      - 32401:32401\n      - 3005:3005\n      - 8324:8324\n      - 1900:1900/udp\n      - 32410:32410/udp\n      - 32412:32412/udp\n      - 32413:32413/udp\n      - 32414:32414/udp\n\nnetworks:\n  traefik_public:\n    external: true\n  internal:\n    driver: overlay\n    ipam:\n      config:\n        - subnet: 172.16.16.0/24\n

\n\n\n\n\n Setup unique static subnets for every stack you deploy. This avoids IP/gateway conflicts which can otherwise occur when you’re creating/removing stacks a lot. See my list here.
\n

\n42.3 Serving

\n\n

\nLaunch Plex stack

\n\n

Launch the Plex stack by running docker stack deploy plex -c <path -to-docker-compose.yml>

\n\n

Log into your new instance at https://YOUR-FQDN (You’ll need to setup a plex.tv login for remote access / discovery to work from certain clients)

\n\n

\n42.4 Chef’s Notes

\n\n

Plex uses port 32400 for remote access, using your plex.tv user/password to authenticate you. The inclusion of the traefik proxy in this recipe is simply to allow you to use the web client (as opposed to a client app) by connecting directly to your instance, as opposed to browsing your media via https://plex.tv/web
Got an NVIDIA GPU? See this blog post re how to use your GPU to transcode your media!

\n\n\n

\n43 PrivateBin

\n\n

PrivateBin is a minimalist, open source online pastebin where the server (can) has zero knowledge of pasted data. We all need to paste data / log files somewhere when it doesn’t make sense to paste it inline. With PasteBin, you can own the hosting, access, and eventual deletion of this data.

\n\n

\n\n\n

\n43.1 Ingredients

\n\n

\nDocker swarm cluster with persistent shared storage\n
\nTraefik configured per design
DNS entry for the hostname you intend to use, pointed to your keepalived IP

\n\n

\n43.2 Preparation

\n\n

\nSetup data locations

\n\n

We’ll need a single location to bind-mount into our container, so create /var/data/privatebin, and make it world-writable (there might be a more secure way to do this!)

\n\n\n

mkdir /var/data/privatebin\nchmod 777 /var/data/privatebin/\n

\n\n\n\n\n

\nSetup Docker Swarm

\n\n

Create a docker swarm config file in docker-compose syntax (v3), something like this:

version: '3'\n\nservices:\n  app:\n    image: privatebin/nginx-fpm-alpine\n    volumes:\n      - /var/data/privatebin:/srv/data\n    networks:\n      - traefik_public\n    deploy:\n      labels:\n        - traefik.frontend.rule=Host:privatebin.example.com\n        - traefik.docker.network=traefik_public\n        - traefik.port=4180\n\nnetworks:\n  traefik_public:\n    external: true\n

\n\n\n\n\n

\n43.3 Serving

\n\n

\nLaunch PrivateBin stack

\n\n

Launch the PrivateBin stack by running docker stack deploy privatebin -c <path -to-docker-compose.yml>

\n\n

Log into your new instance at https://YOUR-FQDN, with user “root” and the password you specified in gitlab.env.

\n\n

\n43.4 Chef’s Notes

\n\n

The PrivateBin repo explains how to tweak configuration options, or to use a database instead of file storage, if your volume justifies it :)
The inclusion of PrivateBin was due to the efforts of @gkoerk in our Discord server. Thanks Jerry!!

\n\n\n

\n44 Swarmprom

\n\n

Swarmprom is a starter kit for Docker Swarm monitoring with Prometheus, Grafana, cAdvisor, Node Exporter, Alert Manager and Unsee. And it’s damn sexy. See for yourself:

\n\n

\n\n\n

So what do all these components do?

\n\n

\nPrometheus is an open-source systems monitoring and alerting toolkit originally built at SoundCloud.
\nGrafana is a tool to make data beautiful.
cAdvisor

cAdvisor (Container Advisor) provides container users an understanding of the resource usage and performance characteristics of their running containers. It is a running daemon that collects, aggregates, processes, and exports information about running containers.

\nNode Exporter is a Prometheus exporter for hardware and OS metrics
\nAlert Manager Alertmanager handles alerts sent by client applications such as the Prometheus server. It takes care of deduplicating, grouping, and routing them to the correct receiver integrations such as email, Slack, etc.
\nUnsee is an alert dashboard for Alert Manager

\n\n

\n44.1 How does this magic work?

\n\n

I’d encourage you to spend some time reading https://github.com/stefanprodan/swarmprom. Stefan has included detailed explanations about which elements perform which functions, as well as how to customize your stack. (This is only a starting point, after all)

\n\n

\n44.2 Ingredients

\n\n

\nDocker swarm cluster on 17.09.0 or newer (doesn’t work with CentOS Atomic, unfortunately) with persistent shared storage\n
\nTraefik configured per design
DNS entry for the hostnames you intend to use, pointed to your keepalived IP

\n\n

\n44.3 Preparation

\n\n

This is basically a rehash of stefanprodan’s instructions to match the way I’ve configured other recipes.

\n\n

\nSetup oauth provider

\n\n

Grafana includes decent login protections, but from what I can see, Prometheus, AlertManager, and Unsee do no authentication. In order to expose these publicly for your own consumption (my assumption for the rest of this recipe), you’ll want to prepare to run oauth_proxy containers in front of each of the 4 web UIs in this recipe.

\n\n

\nSetup metrics

\n\n

Edit (or create, depending on your OS) /etc/docker/daemon.json, and add the following, to enable the experimental export of metrics to Prometheus:

\n\n\n

{\n  \"metrics-addr\" : \"0.0.0.0:9323\",\n  \"experimental\" : true\n}\n

\n\n\n\n\n

Restart docker with systemctl restart docker

\n\n

\nSetup and populate data locations

\n\n

We’ll need several files to bind-mount into our containers, so create directories for them and get the latest copies:

\n\n\n

mkdir -p /var/data/swarmprom/dockerd-exporter/\ncd /var/data/swarmprom/dockerd-exporter/\nwget https://raw.githubusercontent.com/stefanprodan/swarmprom/master/dockerd-\\\nexporter/Caddyfile\n\nmkdir -p /var/data/swarmprom/prometheus/rules/\ncd /var/data/swarmprom/prometheus/rules/\nwget https://raw.githubusercontent.com/stefanprodan/swarmprom/master/promethe\\\nus/rules/swarm_task.rules.yml\nwget https://raw.githubusercontent.com/stefanprodan/swarmprom/master/promethe\\\nus/rules/swarm_node.rules.yml\n\n# Directories for holding runtime data\nmkdir /var/data/runtime/swarmprom/grafana/\nmkdir /var/data/runtime/swarmprom/alertmanager/\nmkdir /var/data/runtime/prometheus\n\nchown nobody:nogroup /var/data/runtime/prometheus\n

\n\n\n\n\n

\nPrepare Grafana

\n\n

Grafana will make all the data we collect from our swarm beautiful.

\n\n

Create /var/data/swarmprom/grafana.env, and populate with the following variables

\n\n

OAUTH2_PROXY_CLIENT_ID=\nOAUTH2_PROXY_CLIENT_SECRET=\nOAUTH2_PROXY_COOKIE_SECRET=\n\n# Disable basic auth (it conflicts with oauth_proxy)\nGF_AUTH_BASIC_ENABLED=false\n\n# Set this to the real-world URL to your grafana install (else you get screwy\\\n CSS thanks to oauth_proxy)\nGF_SERVER_ROOT_URL=https://grafana.example.com\nGF_SERVER_DOMAIN=grafana.example.com\n\n# Set your default admin/pass here\nGF_SECURITY_ADMIN_USER=admin\nGF_SECURITY_ADMIN_PASSWORD=ilovemybatmanunderpants\n

\n\n\n\n\n

\nSetup Docker Swarm

\n\n

Create a docker swarm config file in docker-compose syntax (v3), based on the original swarmprom docker-compose.yml file

\n\n

???+ note “This example is 274 lines long. Click here to collapse it for better readability”

      version: \"3.3\"\n\n      networks:\n        net:\n          driver: overlay\n          attachable: true\n\n      volumes:\n          prometheus: {}\n          grafana: {}\n          alertmanager: {}\n\n      configs:\n        dockerd_config:\n          file: /var/data/swarmprom/dockerd-exporter/Caddyfile\n        node_rules:\n          file: /var/data/swarmprom/prometheus/rules/swarm_node.rules.yml\n        task_rules:\n          file: /var/data/swarmprom/prometheus/rules/swarm_task.rules.yml\n\n      services:\n        dockerd-exporter:\n          image: stefanprodan/caddy\n          networks:\n            - internal\n          environment:\n            - DOCKER_GWBRIDGE_IP=172.18.0.1\n          configs:\n            - source: dockerd_config\n              target: /etc/caddy/Caddyfile\n          deploy:\n            mode: global\n            resources:\n              limits:\n                memory: 128M\n              reservations:\n                memory: 64M\n\n        cadvisor:\n          image: google/cadvisor\n          networks:\n            - internal\n          command: -logtostderr -docker_only\n          volumes:\n            - /var/run/docker.sock:/var/run/docker.sock:ro\n            - /:/rootfs:ro\n            - /var/run:/var/run\n            - /sys:/sys:ro\n            - /var/lib/docker/:/var/lib/docker:ro\n          deploy:\n            mode: global\n            resources:\n              limits:\n                memory: 128M\n              reservations:\n                memory: 64M\n\n        grafana:\n          image: stefanprodan/swarmprom-grafana:5.3.4\n          networks:\n            - internal\n          env_file: /var/data/config/swarmprom/grafana.env\n          environment:\n            - GF_USERS_ALLOW_SIGN_UP=false\n            - GF_SMTP_ENABLED=${GF_SMTP_ENABLED:-false}\n            - GF_SMTP_FROM_ADDRESS=${GF_SMTP_FROM_ADDRESS:-grafana@test.com}\n            - GF_SMTP_FROM_NAME=${GF_SMTP_FROM_NAME:-Grafana}\n            - GF_SMTP_HOST=${GF_SMTP_HOST:-smtp:25}\n            - GF_SMTP_USER=${GF_SMTP_USER}\n            - GF_SMTP_PASSWORD=${GF_SMTP_PASSWORD}\n          volumes:\n            - /var/data/runtime/swarmprom/grafana:/var/lib/grafana\n          deploy:\n            mode: replicated\n            replicas: 1\n            placement:\n              constraints:\n                - node.role == manager\n            resources:\n              limits:\n                memory: 128M\n              reservations:\n                memory: 64M\n\n        grafana-proxy:\n          image: a5huynh/oauth2_proxy\n          env_file : /var/data/config/swarmprom/grafana.env\n          networks:\n            - internal\n            - traefik_public\n          deploy:\n            labels:\n              - traefik.frontend.rule=Host:grafana.swarmprom.example.com\n              - traefik.docker.network=traefik_public\n              - traefik.port=4180\n          volumes:\n            - /var/data/config/swarmprom/authenticated-emails.txt:/authentica\\\nted-emails.txt\n          command: |\n            -cookie-secure=false\n            -upstream=http://grafana:3000\n            -redirect-url=https://grafana.swarmprom.example.com\n            -http-address=http://0.0.0.0:4180\n            -email-domain=example.com\n            -provider=github\n            -authenticated-emails-file=/authenticated-emails.txt\n\n        alertmanager:\n          image: stefanprodan/swarmprom-alertmanager:v0.14.0\n          networks:\n            - internal\n          environment:\n            - SLACK_URL=${SLACK_URL:-https://hooks.slack.com/services/TOKEN}\n            - SLACK_CHANNEL=${SLACK_CHANNEL:-general}\n            - SLACK_USER=${SLACK_USER:-alertmanager}\n          command:\n            - '--config.file=/etc/alertmanager/alertmanager.yml'\n            - '--storage.path=/alertmanager'\n          volumes:\n            - /var/data/runtime/swarmprom/alertmanager:/alertmanager\n          deploy:\n            mode: replicated\n            replicas: 1\n            placement:\n              constraints:\n                - node.role == manager\n            resources:\n              limits:\n                memory: 128M\n              reservations:\n                memory: 64M\n\n        alertmanager-proxy:\n          image: a5huynh/oauth2_proxy\n          env_file : /var/data/config/swarmprom/alertmanager.env\n          networks:\n            - internal\n            - traefik_public\n          deploy:\n            labels:\n              - traefik.frontend.rule=Host:alertmanager.swarmprom.example.com\n              - traefik.docker.network=traefik_public\n              - traefik.port=4180\n          volumes:\n            - /var/data/config/swarmprom/authenticated-emails.txt:/authentica\\\nted-emails.txt\n          command: |\n            -cookie-secure=false\n            -upstream=http://alertmanager:9093\n            -redirect-url=https://alertmanager.swarmprom.example.com\n            -http-address=http://0.0.0.0:4180\n            -email-domain=example.com\n            -provider=github\n            -authenticated-emails-file=/authenticated-emails.txt\n\n        unsee:\n          image: cloudflare/unsee:v0.8.0\n          networks:\n            - internal\n          environment:\n            - \"ALERTMANAGER_URIS=default:http://alertmanager:9093\"\n          deploy:\n            mode: replicated\n            replicas: 1\n\n        unsee-proxy:\n          image: a5huynh/oauth2_proxy\n          env_file : /var/data/config/swarmprom/unsee.env\n          networks:\n            - internal\n            - traefik_public\n          deploy:\n            labels:\n              - traefik.frontend.rule=Host:unsee.swarmprom.example.com\n              - traefik.docker.network=traefik_public\n              - traefik.port=4180\n          volumes:\n            - /var/data/config/swarmprom/authenticated-emails.txt:/authentica\\\nted-emails.txt\n          command: |\n            -cookie-secure=false\n            -upstream=http://unsee:8080\n            -redirect-url=https://unsee.swarmprom.example.com\n            -http-address=http://0.0.0.0:4180\n            -email-domain=example.com\n            -provider=github\n            -authenticated-emails-file=/authenticated-emails.txt\n\n\n        node-exporter:\n          image: stefanprodan/swarmprom-node-exporter:v0.16.0\n          networks:\n            - internal\n          environment:\n            - NODE_ID={{.Node.ID}}\n          volumes:\n            - /proc:/host/proc:ro\n            - /sys:/host/sys:ro\n            - /:/rootfs:ro\n            - /etc/hostname:/etc/nodename\n          command:\n            - '--path.sysfs=/host/sys'\n            - '--path.procfs=/host/proc'\n            - '--collector.textfile.directory=/etc/node-exporter/'\n            - '--collector.filesystem.ignored-mount-points=^/(sys|proc|dev|ho\\\nst|etc)($$|/)'\n            # no collectors are explicitely enabled here, because the default\\\ns are just fine,\n            # see https://github.com/prometheus/node_exporter\n            # disable ipvs collector because it barfs the node-exporter logs \\\nfull with errors on my centos 7 vm's\n            - '--no-collector.ipvs'\n          deploy:\n            mode: global\n            resources:\n              limits:\n                memory: 128M\n              reservations:\n                memory: 64M\n\n        prometheus:\n          image: stefanprodan/swarmprom-prometheus:v2.5.0\n          networks:\n            - internal\n          command:\n            - '--config.file=/etc/prometheus/prometheus.yml'\n            - '--web.console.libraries=/etc/prometheus/console_libraries'\n            - '--web.console.templates=/etc/prometheus/consoles'\n            - '--storage.tsdb.path=/prometheus'\n            - '--storage.tsdb.retention=24h'\n          volumes:\n            - /var/data/runtime/swarmprom/prometheus:/prometheus\n          configs:\n            - source: node_rules\n              target: /etc/prometheus/swarm_node.rules.yml\n            - source: task_rules\n              target: /etc/prometheus/swarm_task.rules.yml\n          deploy:\n            mode: replicated\n            replicas: 1\n            placement:\n              constraints:\n                - node.role == manager\n            resources:\n              limits:\n                memory: 2048M\n              reservations:\n                memory: 128M\n\n        prometheus-proxy:\n          image: a5huynh/oauth2_proxy\n          env_file : /var/data/config/swarmprom/prometheus.env\n          networks:\n            - internal\n            - traefik_public\n          deploy:\n            labels:\n              - traefik.frontend.rule=Host:prometheus.swarmprom.example.com\n              - traefik.docker.network=traefik_public\n              - traefik.port=4180\n          volumes:\n            - /var/data/config/swarmprom/authenticated-emails.txt:/authentica\\\nted-emails.txt\n          command: |\n            -cookie-secure=false\n            -upstream=http://prometheus:9090\n            -redirect-url=https://prometheus.swarmprom.example.com\n            -http-address=http://0.0.0.0:4180\n            -email-domain=example.com\n            -provider=github\n            -authenticated-emails-file=/authenticated-emails.txt\n\n\n      networks:\n        traefik_public:\n          external: true\n        internal:\n          driver: overlay\n          ipam:\n            config:\n              - subnet: 172.16.29.0/24\n

\n\n\n\n\n Setup unique static subnets for every stack you deploy. This avoids IP/gateway conflicts which can otherwise occur when you’re creating/removing stacks a lot. See my list here.
\n

\n44.4 Serving

\n\n

\nLaunch Swarmprom stack

\n\n

Launch the Swarm stack by running docker stack deploy swarmprom -c <path -to-docker-compose.yml>

\n\n

Log into your new grafana instance, check out your beautiful graphs. Move onto drooling over Prometheus, AlertManager, and Unsee.

\n\n

\n44.5 Chef’s Notes

\n\n

1. Pay close attention to the grafana.env config. If you encounter errors about basic auth failed, or failed CSS, it’s likely due to misconfiguration of one of the grafana environment variables.

\n\n\n

\nIII Recipies (Docker)

\n\n

Now follows individual recipes.

\n\n\n

\n45 Bitwarden

\n\n

Heard about the latest password breach (since lunch)? HaveYouBeenPowned yet (today)? Passwords are broken, and as the amount of sites for which you need to store credentials grows exponetially, so does the risk of using a common password.

\n\n

“Duh, use a password manager”, you say. Sure, but be aware that even password managers have security flaws.

\n\n

OK, look smartass.. no software is perfect, and there will always be a risk of your credentials being exposed in ways you didn’t intend. You can at least minimize the impact of such exposure by using a password manager to store unique credentials per-site. While 1Password is king of the commercial password manager, BitWarden is king of the open-source, self-hosted password manager.

\n\n

Enter Bitwarden..

\n\n

\n\n\n

Bitwarden is a free and open source password management solution for individuals, teams, and business organizations. While Bitwarden does offer a paid / hosted version, the free version comes with the following (better than any other free password manager!):

\n\n

Access & install all Bitwarden apps
Sync all of your devices, no limits!
Store unlimited items in your vault
Logins, secure notes, credit cards, & identities
Two-step authentication (2FA)
Secure password generator
Self-host on your own server (optional)

\n\n

\n45.1 Ingredients

\n\n Existing:
\n 1. [X] Docker swarm cluster with persistent shared storage
2. [X] Traefik configured per design
3. [X] DNS entry for the hostname you intend to use, pointed to your keepalived IP
\n

\n45.2 Preparation

\n\n

\nSetup data locations

\n\n

We’ll need to create a directory to bind-mount into our container, so create /var/data/bitwarden:

\n\n\n

mkdir /var/data/bitwarden\n

\n\n\n\n

### Setup environment

\n\n

Create /var/data/config/bitwarden/bitwarden.env, and leave it empty for now.

\n\n What, why an empty env file? Well, the container supports lots of customizations via environment variables, for things like toggling self-registration, 2FA, etc. These are too complex to go into for this recipe, but readers are recommended to review the dani-garcia/bitwarden_rs wiki, and customize their installation to suite.
\n

\nSetup Docker Swarm

\n\n

Create a docker swarm config file in docker-compose syntax (v3), something like this:

version: \"3\"\nservices:\n  bitwarden:\n    image: bitwardenrs/server\n    env_file: /var/data/config/bitwarden/bitwarden.env\n    volumes:\n      - /etc/localtime:/etc/localtime:ro\n      - /var/data/bitwarden:/data/:rw\n    deploy:\n      labels:\n        - traefik.enable=true\n        - traefik.web.frontend.rule=Host:bitwarden.example.com\n        - traefik.web.port=80\n        - traefik.hub.frontend.rule=Host:bitwarden.example.com;Path:/notifica\\\ntions/hub\n        - traefik.hub.port=3012\n        - traefik.docker.network=traefik_public\n    networks:\n        - traefik_public\n\nnetworks:\n  traefik_public:\n    external: true\n

\n\n\n\n\n Note the clever use of two Traefik frontends to expose the notifications hub on port 3012. Thanks @gkoerk!
\n

\n45.3 Serving

\n\n

\nLaunch Bitwarden stack

\n\n

Launch the Bitwarden stack by running docker stack deploy bitwarden -c <path -to-docker-compose.yml>

\n\n

Browse to your new instance at https://YOUR-FQDN, and create a new user account and master password (Just click the Create Account button without filling in your email address or master password)

\n\n

\nGet the apps / extensions

\n\n

Once you’ve created your account, jump over to https://bitwarden.com/#download and download the apps for your mobile and browser, and start adding your logins!

\n\n

\n45.4 Chef’s Notes

\n\n

You’ll notice we’re not using the official container images (all 6 of them required!), but rather a more lightweight version ideal for self-hosting. All of the elements are contained within a single container, and SQLite is used for the database backend.
As mentioned above, readers should refer to the dani-garcia/bitwarden_rs wiki for details on customizing the behaviour of Bitwarden.
The inclusion of Bitwarden was due to the efforts of @gkoerk in our Discord server- Thanks Gerry!

\n\n\n

\n46 BookStack

\n\n

BookStack is a simple, self-hosted, easy-to-use platform for organising and storing information.

\n\n

A friendly middle ground between heavyweights like MediaWiki or Confluence and Gollum, BookStack relies on a database backend (so searching and versioning is easy), but limits itself to a pre-defined, 3-tier structure (book, chapter, page). The result is a lightweight, approachable personal documentation stack, which includes search and Markdown editing.

\n\n

\n\n\n

I like to protect my public-facing web UIs with an oauth_proxy, ensuring that if an application bug (or a user misconfiguration) exposes the app to unplanned public scrutiny, I have a second layer of defense.

\n\n

\n46.1 Ingredients

\n\n

\nDocker swarm cluster with persistent shared storage\n
\nTraefik configured per design
DNS entry for the hostname you intend to use, pointed to your keepalived IP

\n\n

\n46.2 Preparation

\n\n

\nSetup data locations

\n\n

We’ll need several directories to bind-mount into our container, so create them in /var/data/bookstack:

\n\n\n

mkdir -p /var/data/bookstack/database-dump\nmkdir -p /var/data/runtime/bookstack/db\n

\n\n\n\n\n

\nPrepare environment

\n\n

Create bookstack.env, and populate with the following variables. Set the oauth_proxy variables provided by your OAuth provider (if applicable.)

\n\n\n

# For oauth-proxy (optional)\nOAUTH2_PROXY_CLIENT_ID=\nOAUTH2_PROXY_CLIENT_SECRET=\nOAUTH2_PROXY_COOKIE_SECRET=\n\n# For MariaDB/MySQL database\nMYSQL_RANDOM_ROOT_PASSWORD=true\nMYSQL_DATABASE=bookstack\nMYSQL_USER=bookstack\nMYSQL_PASSWORD=secret\n\n# Bookstack-specific variables\nDB_HOST=bookstack_db:3306\nDB_DATABASE=bookstack\nDB_USERNAME=bookstack\nDB_PASSWORD=secret\n

\n\n\n\n\n

\nSetup Docker Swarm

\n\n

Create a docker swarm config file in docker-compose syntax (v3), something like this:

version: '3'\n\nservices:\n\n  db:\n    image: mariadb:10\n    env_file: /var/data/config/bookstack/bookstack.env\n    networks:\n      - internal\n    volumes:\n      - /var/data/runtime/bookstack/db:/var/lib/mysql\n\n  proxy:\n    image: a5huynh/oauth2_proxy\n    env_file : /var/data/config/bookstack/bookstack.env\n    networks:\n      - internal\n      - traefik_public\n    deploy:\n      labels:\n        - traefik.frontend.rule=Host:bookstack.example.com\n        - traefik.docker.network=traefik_public\n        - traefik.port=4180\n    volumes:\n      - /var/data/config/bookstack/authenticated-emails.txt:/authenticated-em\\\nails.txt\n    command: |\n      -cookie-secure=false\n      -upstream=http://app\n      -redirect-url=https://bookstack.example.com\n      -http-address=http://0.0.0.0:4180\n      -email-domain=example.com\n      -provider=github\n      -authenticated-emails-file=/authenticated-emails.txt\n\n  app:\n    image: solidnerd/bookstack\n    env_file: /var/data/config/bookstack/bookstack.env\n    networks:\n      - internal\n\n  db-backup:\n    image: mariadb:10\n    env_file: /var/data/config/bookstack/bookstack.env\n    volumes:\n      - /var/data/bookstack/database-dump:/dump\n      - /etc/localtime:/etc/localtime:ro\n    entrypoint: |\n      bash -c 'bash -s <<EOF\n      trap \"break;exit\" SIGHUP SIGINT SIGTERM\n      sleep 2m\n      while /bin/true; do\n        mysqldump -h db --all-databases | gzip -c > /dump/dump_\\`date +%d-%m-\\\n%Y\"_\"%H_%M_%S\\`.sql.gz\n        (ls -t /dump/dump*.sql.gz|head -n $$BACKUP_NUM_KEEP;ls /dump/dump*.sq\\\nl.gz)|sort|uniq -u|xargs rm -- {}\n        sleep $$BACKUP_FREQUENCY\n      done\n      EOF'\n    networks:\n    - internal\n\nnetworks:\n  traefik_public:\n    external: true\n  internal:\n    driver: overlay\n    ipam:\n      config:\n        - subnet: 172.16.33.0/24\n

\n\n\n\n\n Setup unique static subnets for every stack you deploy. This avoids IP/gateway conflicts which can otherwise occur when you’re creating/removing stacks a lot. See my list here.
\n

\n46.3 Serving

\n\n

\nLaunch Bookstack stack

\n\n

Launch the BookStack stack by running docker stack deploy bookstack -c <path -to-docker-compose.yml>

\n\n

Log into your new instance at https://YOUR-FQDN, authenticate with oauth_proxy, and then login with username ‘admin@admin.com’ and password ‘password’.

\n\n

\n46.4 Chef’s Notes

\n\n

1. If you wanted to expose the BookStack UI directly, you could remove the oauth2_proxy from the design, and move the traefik_public-related labels directly to the bookstack container. You’d also need to add the traefik_public network to the bookstack container.

\n\n\n

hero: Manage your ebook collection. Like a BOSS.

\n\n

\n47 Calibre-Web

\n\n

The AutoPirate recipe includes Lazy Librarian, a tool for tracking, finding, and downloading eBooks. However, after the eBooks are downloaded, Lazy Librarian is not much use for organising, tracking, and actually reading them.

\n\n

Calibre-Web could be described as “Plex (or Emby) for eBooks” - it’s a web-based interface to manage your eBook library, screenshot below:

\n\n

\n\n\n

Of course, you probably already manage your eBooks using the excellent Calibre, but this is primarily a (powerful) desktop application. Calibre-Web is an alternative way to manage / view your existing Calibre database, meaning you can continue to use Calibre on your desktop if you wish.

\n\n

As a long-time Kindle user, Calibre-Web brings (among others) the following features which appeal to me:

\n\n

Filter and search by titles, authors, tags, series and language
Create custom book collection (shelves)

Support for editing eBook metadata and deleting eBooks from Calibre library

Support for converting eBooks from EPUB to Kindle format (mobi/azw)
Send eBooks to Kindle devices with the click of a button
Support for reading eBooks directly in the browser (.txt, .epub, .pdf, .cbr, .cbt, .cbz)
Upload new books in PDF, epub, fb2 format

\n\n

\n47.1 Ingredients

\n\n

\nDocker swarm cluster with persistent shared storage\n
\nTraefik configured per design
DNS entry for the hostname you intend to use, pointed to your keepalived IP

\n\n

\n47.2 Preparation

\n\n

\nSetup data locations

\n\n

We’ll need a directory to store some config data for Calibre-Web, container, so create /var/data/calibre-web, and ensure the directory is owned by the same use which owns your Calibre data (below)

\n\n\n

mkdir /var/data/calibre-web\nchown calibre:calibre /var/data/calibre-web # for example\n

\n\n\n\n\n

Ensure that your Calibre library is accessible to the swarm (i.e., exists on shared storage), and that the same user who owns the config directory above, also owns the actual calibre library data (including the ebooks managed by Calibre).

\n\n

\nPrepare environment

\n\n

We’ll use an oauth-proxy to protect the UI from public access, so create calibre-web.env, and populate with the following variables:

\n\n\n

OAUTH2_PROXY_CLIENT_ID=\nOAUTH2_PROXY_CLIENT_SECRET=\nOAUTH2_PROXY_COOKIE_SECRET=<make this a random string>\nPUID=\nPGID=\n

\n\n\n\n\n

Follow the instructions to setup your oauth provider. You need to setup a unique key/secret for each instance of the proxy you want to run, since in each case the callback URL will differ.

\n\n

\nSetup Docker Swarm

\n\n

Create a docker swarm config file in docker-compose syntax (v3), something like this:

version: '3'\n\nservices:\n  app:\n    image: technosoft2000/calibre-web\n    env_file : /var/data/config/calibre-web/calibre-web.env\n    volumes:\n     - /var/data/calibre-web:/config\n     - /srv/data/Archive/Ebooks/calibre:/books\n    networks:\n    - internal\n\n  proxy:\n    image: a5huynh/oauth2_proxy\n    env_file : /var/data/config/calibre-web/calibre-web.env\n    dns_search: hq.example.com\n    networks:\n      - internal\n      - traefik_public\n    deploy:\n      labels:\n        - traefik.frontend.rule=Host:calibre-web.example.com\n        - traefik.docker.network=traefik_public\n        - traefik.port=4180\n    volumes:\n      - /var/data/config/calibre-web/authenticated-emails.txt:/authenticated-\\\nemails.txt\n    command: |\n      -cookie-secure=false\n      -upstream=http://app:8083\n      -redirect-url=https://calibre-web.example.com\n      -http-address=http://0.0.0.0:4180\n      -email-domain=example.com\n      -provider=github\n      -authenticated-emails-file=/authenticated-emails.txt\n\nnetworks:\n  traefik_public:\n    external: true\n  internal:\n    driver: overlay\n    ipam:\n      config:\n        - subnet: 172.16.18.0/24\n

\n\n\n\n\n Setup unique static subnets for every stack you deploy. This avoids IP/gateway conflicts which can otherwise occur when you’re creating/removing stacks a lot. See my list here.
\n

\n47.3 Serving

\n\n

\nLaunch Calibre-Web

\n\n

Launch the Calibre-Web stack by running docker stack deploy calibre-web -c <path -to-docker-compose.yml>

\n\n

Log into your new instance at https://YOUR-FQDN. You’ll be directed to the initial GUI configuraition. Set the first field (Location of Calibre database) to “/books/”, and when complete, login using defaults username of “admin” with password “admin123”.

\n\n

\n47.4 Chef’s Notes

\n\n

Yes, Calibre does provide a server component. But it’s not as fully-featured as Calibre-Web (i.e., you can’t use it to send ebooks directly to your Kindle)
A future enhancement might be integrating this recipe with the filestore for NextCloud, so that the desktop database (Calibre) can be kept synced with Calibre-Web.

\n\n\n

\n48 Collabora Online

\n\n Development of this recipe is sponsored by The Common Observatory. Thanks guys!
\n [

\n\n](https://www.observe.global/)
\n

Collabora Online Development Edition (or “CODE”), is the lightweight, or “home” edition of the commercially-supported Collabora Online platform. It

\n\n

It’s basically the LibreOffice interface in a web-browser. CODE is not a standalone app, it’s a backend intended to be accessed via “WOPI” from an existing interface (in our case, NextCloud)

\n\n

\n\n\n

\n48.1 Ingredients

\n\n

\nDocker swarm cluster with persistent shared storage\n
\nTraefik configured per design
DNS entry for the hostname (i.e. “collabora.your-domain.com”) you intend to use for LDAP Account Manager, pointed to your keepalived IP
\nNextCloud installed and operational
\nDocker-compose installed on your node(s) - this is a special case which needs to run outside of Docker Swarm

\n\n

\n48.2 Preparation

\n\n

\nExplanation for complexity

\n\n

Due to the clever magic that Collabora does to present a “headless” LibreOffice UI to the browser, the CODE docker container requires system capabilities which cannot be granted under Docker Swarm (specifically, MKNOD).

\n\n

So we have to run Collabora itself in the next best thing to Docker swarm - a docker-compose stack. Using docker-compose will at least provide us with consistent and version-able configuration files.

\n\n

This presents another problem though - Docker Swarm with Traefik is superb at making all our stacks “just work” with ingress routing and LetsEncyrpt certificates. We don’t want to have to do this manually (like a cave-man), so we engage in some trickery to allow us to still use our swarmed Traefik to terminate SSL.

\n\n

We run a single swarmed Nginx instance, which forwards all requests to an upstream, with the target IP of the docker0 interface, on port 9980 (the port exposed by the CODE container)

\n\n

We attach the necessary labels to the Nginx container to instruct Trafeik to setup a front/backend for collabora.<ourdomain>. Now incoming requests to https://collabora.<ourdomain> will hit Traefik, be forwarded to nginx (wherever in the swarm it’s running), and then to port 9980 on the same node that nginx is running on.

\n\n

What if we’re running multiple nodes in our swarm, and nginx ends up on a different node to the one running Collabora via docker-compose? Well, either constrain nginx to the same node as Collabora (example below), or just launch an instance of Collabora on every node then. It’s just a rendering / GUI engine after all, it doesn’t hold any persistent data.

\n\n

Here’s a (highly technical) diagram to illustrate:

\n\n

\n\n\n

\nSetup data locations

\n\n

We’ll need a directory for holding config to bind-mount into our containers, so create /var/data/collabora, and /var/data/config/collabora for holding the docker/swarm config

\n\n\n

mkdir /var/data/collabora/\nmkdir /var/data/config/collabora/\n

\n\n\n\n\n

\nPrepare environment

\n\n

Create /var/data/config/collabora/collabora.env, and populate with the following variables, customized for your installation.

\n\n Note the following:
\n 1. Variables are in lower-case, unlike our standard convention. This is to align with the CODE container
2. Set domain to your NextCloud domain, and escape all the periods as per the example
3. Set your server_name to collabora.<yourdomain>. Escaping periods is unnecessary
4. Your password cannot include triangular brackets - the entrypoint script will insert this password into an XML document, and triangular brackets will make bad(tm) things happen
\n\n

username=admin\npassword=ilovemypassword\ndomain=nextcloud\\.batcave\\.com\nserver_name=collabora.batcave.com\ntermination=true\n

\n\n\n\n\n

\nCreate docker-compose.yml

\n\n

Create /var/data/config/collabora/docker-compose.yml as follows:

\n\n\n

version: \"3.0\"\n\nservices:\n  local-collabora:\n    image: funkypenguin/collabora\n    # the funkypenguin version has a patch to include \"termination\" behind SS\\\nL-terminating reverse proxy (traefik), see CODE PR #50.\n    # Once merged, the official container can be used again.\n    #image: collabora/code\n    env_file: /var/data/config/collabora/collabora.env\n    volumes:\n      - /var/data/collabora/loolwsd.xml:/etc/loolwsd/loolwsd.xml-new\n    cap_add:\n      - MKNOD\n    ports:\n      - 9980:9980\n

\n\n\n\n\n

\nCreate nginx.conf

\n\n

Create /var/data/config/collabora/nginx.conf as follows, changing the server_name value to match the environment variable you established above:

\n\n\n

upstream collabora-upstream {\n    # Run collabora under docker-compose, since it needs MKNOD cap, which can\\\n't be provided by Docker Swarm.\n    # The IP here is the typical IP of docker0 - change if yours is different.\n    server 172.17.0.1:9980;\n}\n\nserver {\n    listen 80;\n    server_name collabora.batcave.com;\n\n    # static files\n    location ^~ /loleaflet {\n        proxy_pass http://collabora-upstream;\n        proxy_set_header Host $http_host;\n    }\n\n    # WOPI discovery URL\n    location ^~ /hosting/discovery {\n        proxy_pass http://collabora-upstream;\n        proxy_set_header Host $http_host;\n    }\n\n    # Main websocket\n    location ~ /lool/(.*)/ws$ {\n        proxy_pass http://collabora-upstream;\n        proxy_set_header Upgrade $http_upgrade;\n        proxy_set_header Connection \"Upgrade\";\n        proxy_set_header Host $http_host;\n        proxy_read_timeout 36000s;\n    }\n\n    # Admin Console websocket\n    location ^~ /lool/adminws {\n\tproxy_buffering off;\n        proxy_pass http://collabora-upstream;\n        proxy_set_header Upgrade $http_upgrade;\n        proxy_set_header Connection \"Upgrade\";\n        proxy_set_header Host $http_host;\n        proxy_read_timeout 36000s;\n    }\n\n    # download, presentation and image upload\n    location ~ /lool {\n        proxy_pass https://collabora-upstream;\n        proxy_set_header Host $http_host;\n    }\n}\n

\n\n\n\n\n

\nCreate loolwsd.xml

\n\n

Until we understand how to pass trusted network parameters to the entrypoint script using environment variables, we have to maintain a manually edited version of loolwsd.xml, and bind-mount it into our collabora container.

\n\n

The way we do this is we mount
/var/data/collabora/loolwsd.xml as /etc/loolwsd/loolwsd.xml-new, then allow the container to create its default /etc/loolwsd/loolwsd.xml, copy this default over our /var/data/collabora/loolwsd.xml as /etc/loolwsd/loolwsd.xml-new, and then update the container to use our /var/data/collabora/loolwsd.xml as /etc/loolwsd/loolwsd.xml instead (confused yet?)

\n\n

Create an empty /var/data/collabora/loolwsd.xml by running touch /var/data/collabora/loolwsd.xml. We’ll populate this in the next section…

\n\n

\nSetup Docker Swarm

\n\n

Create /var/data/config/collabora/collabora.yml as follows, changing the traefik frontend_rule as necessary:

version: \"3.0\"\n\nservices:\n\n  nginx:\n    image: nginx:latest\n    networks:\n      - traefik_public\n    deploy:\n      labels:\n        - traefik.frontend.rule=Host:collabora.batcave.com\n        - traefik.docker.network=traefik_public\n        - traefik.port=80\n        - traefik.frontend.passHostHeader=true\n        # uncomment this line if you want to force nginx to always run on one\\\n node (i.e., the one running collabora)\n      #placement:\n      #  constraints:\n      #     - node.hostname == ds1\n    volumes:\n      - /var/data/collabora/nginx.conf:/etc/nginx/conf.d/default.conf:ro\n\nnetworks:\n  traefik_public:\n    external: true\n

\n\n\n\n\n

\n48.3 Serving

\n\n

\nGenerate loolwsd.xml

\n\n

Well. This is awkward. There’s no documented way to make Collabora work with Docker Swarm, so we’re doing a bit of a hack here, until I understand how to pass these arguments via environment variables.

\n\n

Launching Collabora is (for now) a 2-step process. First.. we launch collabora itself, by running:

\n\n\n

cd /var/data/config/collabora/\ndocker-compose -d up\n

\n\n\n\n\n

Output looks something like this:

\n\n\n

root@ds1:/var/data/config/collabora# docker-compose up -d\nWARNING: The Docker Engine you're using is running in swarm mode.\n\nCompose does not use swarm mode to deploy services to multiple nodes in a swa\\\nrm. All containers will be scheduled on the current node.\n\nTo deploy your application across the swarm, use `docker stack deploy`.\n\nPulling local-collabora (funkypenguin/collabora:latest)...\nlatest: Pulling from funkypenguin/collabora\n7b8b6451c85f: Pull complete\nab4d1096d9ba: Pull complete\ne6797d1788ac: Pull complete\ne25c5c290bde: Pull complete\n4b8e1b074e06: Pull complete\nf51a3d1fb75e: Pull complete\n8b826e2ae5ad: Pull complete\nDigest: sha256:6cd38cb5cbd170da0e3f0af85cecf07a6bc366e44555c236f81d5b433421a3\\\n9d\nStatus: Downloaded newer image for funkypenguin/collabora:latest\nCreating collabora_local-collabora_1 ...\nCreating collabora_local-collabora_1 ... done\nroot@ds1:/var/data/config/collabora#\n

\n\n\n\n\n

Now exec into the container (from another shell session), by running exec <container name> -it /bin/bash. Make a copy of /etc/loolwsd/loolwsd, by running cp /etc/loolwsd/loolwsd.xml /etc/loolwsd/loolwsd.xml-new, and then exit the container with exit.

\n\n

Delete the collabora container by hitting CTRL-C in the docker-compose shell, running docker-compose rm, and then altering this line in docker-compose.yml:

\n\n\n

      - /var/data/collabora/loolwsd.xml:/etc/loolwsd/loolwsd.xml-new\n

\n\n\n\n\n

To this:

\n\n\n

      - /var/data/collabora/loolwsd.xml:/etc/loolwsd/loolwsd.xml\n

\n\n\n\n\n

Edit /var/data/collabora/loolwsd.xml, find the storage.filesystem.wopi section, and add lines like this to the existing allow rules (to allow IPv6-enabled hosts to still connect with their IPv4 addreses):

\n\n\n

<host desc=\"Regex pattern of hostname to allow or deny.\" allow=\"true\">::ffff:\\\n10\\.[0-9]{1,3}\\.[0-9]{1,3}\\.[0-9]{1,3}</host>\n<host desc=\"Regex pattern of hostname to allow or deny.\" allow=\"true\">::ffff:\\\n172\\.1[6789]\\.[0-9]{1,3}\\.[0-9]{1,3}</host>\n<host desc=\"Regex pattern of hostname to allow or deny.\" allow=\"true\">::ffff:\\\n172\\.2[0-9]\\.[0-9]{1,3}\\.[0-9]{1,3}</host>\n<host desc=\"Regex pattern of hostname to allow or deny.\" allow=\"true\">::ffff:\\\n172\\.3[01]\\.[0-9]{1,3}\\.[0-9]{1,3}</host>\n<host desc=\"Regex pattern of hostname to allow or deny.\" allow=\"true\">::ffff:\\\n192\\.168\\.[0-9]{1,3}\\.[0-9]{1,3}</host>\n

\n\n\n\n\n

Find the net.post_allow section, and add a line like this:

\n\n\n

<host desc=\"RFC1918 private addressing in inet6 format\">::ffff:10\\.[0-9]{1,3}\\\n\\.[0-9]{1,3}\\.[0-9]{1,3}</host>\n<host desc=\"RFC1918 private addressing in inet6 format\">::ffff:172\\.1[6789]\\.\\\n[0-9]{1,3}\\.[0-9]{1,3}</host>\n<host desc=\"RFC1918 private addressing in inet6 format\">::ffff:172\\.2[0-9]\\.[\\\n0-9]{1,3}\\.[0-9]{1,3}</host>\n<host desc=\"RFC1918 private addressing in inet6 format\">::ffff:172\\.3[01]\\.[0\\\n-9]{1,3}\\.[0-9]{1,3}</host>\n<host desc=\"RFC1918 private addressing in inet6 format\">::ffff:192\\.168\\.[0-9\\\n]{1,3}\\.[0-9]{1,3}</host>            \n

\n\n\n\n\n

Find these 2 lines:

\n\n\n

<ssl desc=\"SSL settings\">\n    <enable type=\"bool\" default=\"true\">true</enable>\n

\n\n\n\n\n

And change to:

\n\n\n

<ssl desc=\"SSL settings\">\n    <enable type=\"bool\" default=\"true\">false</enable>\n

\n\n\n\n\n

Now re-launch collabora (with the correct with loolwsd.xml) under docker-compose, by running:

\n\n\n

docker-compose -d up\n

\n\n\n\n\n

Once collabora is up, we launch the swarm stack, by running:

\n\n\n

docker stack deploy collabora -c /var/data/config/collabora/collabora.yml\n

\n\n\n\n\n

Visit https://collabora.<yourdomain>/l/loleaflet/dist/admin/admin.html and confirm you can login with the user/password you specified in collabora.env

\n\n

\nIntegrate into NextCloud

\n\n

In NextCloud, Install the Collabora Online app (https://apps.nextcloud.com/apps/richdocuments), and then under Settings -> Collabora Online, set your Collabora Online Server to https://collabora.<your domain>

\n\n

\n\n\n

Now browse your NextCloud files. Click the plus (+) sign to create a new document, and create either a new document, spreadsheet, or presentation. Name your document and then click on it. If Collabora is setup correctly, you’ll shortly enter into the rich editing interface provided by Collabora :)

\n\n Development of this recipe is sponsored by The Common Observatory. Thanks guys!
\n [

\n\n](https://www.observe.global/)
\n

\n48.4 Chef’s Notes

\n\n

1. Yes, this recipe is complicated. And you probably only care if you feel strongly about using Open Source rich document editing in the browser, vs using something like Google Docs. It works impressively well however, once it works. I hope to make this recipe simpler once the CODE developers have documented how to pass optional parameters as environment variables.

\n\n\n

hero: Ghost - A recipe for beautiful online publication.

\n\n

\n49 Ghost

\n\n

Ghost is “a fully open source, hackable platform for building and running a modern online publication.”

\n\n

\n\n\n

\n49.1 Ingredients

\n\n Existing:
\n 1. [X] Docker swarm cluster with persistent shared storage
2. [X] Traefik configured per design
3. [X] DNS entry for the hostname you intend to use, pointed to your keepalived IP
\n

\n49.2 Preparation

\n\n

\nSetup data locations

\n\n

Create the location for the bind-mount of the application data, so that it’s persistent:

\n\n\n

mkdir -p /var/data/ghost\n

\n\n\n\n\n

\nSetup Docker Swarm

\n\n

Create a docker swarm config file in docker-compose syntax (v3), something like this:

version: '3'\n\nservices:\n  ghost:\n    image: ghost:1-alpine\n    volumes:\n     - /etc/localtime:/etc/localtime:ro\n     - /var/data/ghost/:/var/lib/ghost/content\n    networks:\n    - traefik_public\n    deploy:\n      labels:\n        - traefik.frontend.rule=Host:ghost.example.com\n        - traefik.docker.network=traefik\n        - traefik.port=2368\n\nnetworks:\n  traefik_public:\n    external: true\n

\n\n\n\n\n

\n49.3 Serving

\n\n

\nLaunch Ghost stack

\n\n

Launch the Ghost stack by running docker stack deploy ghost -c <path -to-docker-compose.yml>

\n\n

Create your first administrative account at https://YOUR-FQDN/admin/

\n\n

\n49.4 Chef’s Notes

\n\n

If I wasn’t committed to a static-site-generated blog, Ghost is the platform I’d use for my blog.
A default using the SQlite database takes 548k of space:

\n\n

[root@ds1 ghost]# du -sh /var/data/ghost/\n548K\t/var/data/ghost/\n[root@ds1 ghost]#\n

\n\n\n\n\n\n

hero: Gitlab - A recipe for a self-hosted GitHub alternative

\n\n

\n50 GitLab

\n\n

GitLab is a self-hosted alternative to GitHub. The most common use case is (a set of) developers with the desire for the rich feature-set of GitHub, but with unlimited private repositories.

\n\n

Docker does maintain an official “Omnibus” container, but for this recipe I prefer the “dockerized gitlab” project, since it allows distribution of the various Gitlab components across multiple swarm nodes.

\n\n

\n50.1 Ingredients

\n\n Existing:
\n 1. [X] Docker swarm cluster with persistent shared storage
2. [X] Traefik configured per design
3. [X] DNS entry for the hostname you intend to use, pointed to your keepalived IP
\n

\n50.2 Preparation

\n\n

\nSetup data locations

\n\n

We’ll need several directories to bind-mount into our container, so create them in /var/data/gitlab:

\n\n\n

cd /var/data\nmkdir gitlab\ncd gitlab\nmkdir -p {postgresql,redis,gitlab}\n

\n\n\n\n\n

\nPrepare environment

\n\n

You’ll need to know the following:

\n\n

1. Choose a password for postgresql, you’ll need it for DB_PASS in the compose file (below)
2. Generate 3 passwords using pwgen -Bsv1 64. You’ll use these for the XXX_KEY_BASE environment variables below

Create gitlab.env, and populate with at least the following variables (the full set is available at https://github.com/sameersbn/docker-gitlab#available-configuration-parameters):

\n\n

DB_USER=gitlab\nDB_PASS=gitlabdbpass\nDB_NAME=gitlabhq_production\nDB_EXTENSION=pg_trgm\nDB_ADAPTER=postgresql\nDB_HOST=postgresql\nTZ=Pacific/Auckland\nREDIS_HOST=redis\nREDIS_PORT=6379\nGITLAB_TIMEZONE=Auckland\nGITLAB_HTTPS=true\nSSL_SELF_SIGNED=false\nGITLAB_HOST=gitlab.example.com\nGITLAB_PORT=443\nGITLAB_SSH_PORT=2222\nGITLAB_SECRETS_DB_KEY_BASE=CFf7sS3kV2nGXBtMHDsTcjkRX8PWLlKTPJMc3lRc6GCzJDdVlj\\\nZ85NkkzJ8mZbM5\nGITLAB_SECRETS_SECRET_KEY_BASE=h2LBVffktDgb6BxM3B97mDSjhnSNwLc5VL2Hqzq9cdrvBt\\\nVw48WSp5wKj5HZrJM5\nGITLAB_SECRETS_OTP_KEY_BASE=t9LPjnLzbkJ7Nt6LZJj6hptdpgG58MPJPwnMMMDdx27KSwLWH\\\nDrz9bMWXQMjq5mp\nGITLAB_ROOT_PASSWORD=changeme\n

\n\n\n\n\n

\nSetup Docker Swarm

\n\n

Create a docker swarm config file in docker-compose syntax (v3), something like this:

version: '3'\n\nservices:\n  redis:\n    image: sameersbn/redis:latest\n    command:\n    - --loglevel warning\n    volumes:\n    - /var/data/gitlab/redis:/var/lib/redis:Z\n    networks:\n    - internal\n\n  postgresql:\n    image: sameersbn/postgresql:9.6-2\n    env_file: /var/data/config/gitlab/gitlab.env\n    volumes:\n    - /var/data/gitlab/postgresql:/var/lib/postgresql:Z\n    networks:\n    - internal\n\n  gitlab:\n    image: sameersbn/gitlab:latest\n    env_file: /var/data/config/gitlab/gitlab.env\n    networks:\n    - internal\n    - traefik_public\n    deploy:\n      labels:\n        - traefik.frontend.rule=Host:gitlab.example.com\n        - traefik.docker.network=traefik\n        - traefik.port=80\n      restart_policy:\n        delay: 10s\n        max_attempts: 10\n        window: 60s\n    ports:\n    - \"2222:22\"\n    volumes:\n    - /var/data/gitlab/gitlab:/home/git/data:Z\n\nnetworks:\n  traefik_public:\n    external: true\n  internal:\n    driver: overlay\n    ipam:\n      config:\n        - subnet: 172.16.2.0/24\n

\n\n\n\n\n Setup unique static subnets for every stack you deploy. This avoids IP/gateway conflicts which can otherwise occur when you’re creating/removing stacks a lot. See my list here.
\n

\n50.3 Serving

\n\n

\nLaunch gitlab

\n\n

Launch the mail server stack by running docker stack deploy gitlab -c <path -to-docker-compose.yml>

\n\n

Log into your new instance at https://[your FQDN], with user “root” and the password you specified in gitlab.env.

\n\n

\n50.4 Chef’s Notes

\n\n

A few comments on decisions taken in this design:

\n\n

I use the sameersbn/gitlab:latest image, rather than a specific version. This lets me execute updates simply by redeploying the stack (and why wouldn’t I want the latest version?)

\n\n\n

\n51 Gitlab Runner

\n\n

Some features of GitLab require a “runner” (in the sense of a “gopher” or a “minion”). A runner “registers” itself with a GitLab instance, and is given tasks to run. Tasks include running Continuous Integration (CI) builds, and building container images.

\n\n

While a runner isn’t strictly required to use GitLab, if you want to do CI, you’ll need at least one. There are many ways to deploy a runner - this recipe focuses on the docker container model.

\n\n

\n51.1 Ingredients

\n\n Existing:
\n 1. [X] Docker swarm cluster with persistent shared storage
2. [X] Traefik configured per design
3. [X] DNS entry for the hostname you intend to use, pointed to your keepalived IP
4. [X] GitLab installation (see previous recipe)
\n

\n51.2 Preparation

\n\n

\nSetup data locations

\n\n

We’ll need several directories to bind-mount into our runner containers, so create them in /var/data/gitlab:

\n\n\n

cd /var/data\nmkdir gitlab\ncd gitlab\nmkdir -p {runners/1,runners/2}\n

\n\n\n\n\n

\nSetup Docker Swarm

\n\n

Create a docker swarm config file in docker-compose syntax (v3), something like this:

version: '3'\n\nservices:\n  thing1:\n    image: gitlab/gitlab-runner\n    volumes:\n    - /var/data/gitlab/runners/1:/etc/gitlab-runner\n    networks:\n    - internal\n\n  thing2:\n    image: gitlab/gitlab-runner\n    volumes:\n    - /var/data/gitlab/runners/2:/etc/gitlab-runner\n    networks:\n    - internal\n\nnetworks:\n  internal:\n    driver: overlay\n    ipam:\n      config:\n        - subnet: 172.16.23.0/24\n

\n\n\n\n\n

\nConfigure runners

\n\n

From your GitLab UI, you can retrieve a “token” necessary to register a new runner. To register the runner, you can either create config.toml in each runner’s bind-mounted folder (example below), or just docker exec into each runner container and execute gitlab-runner register to interactively generate config.toml.

\n\n

Sample runner config.toml:

\n\n\n

concurrent = 1\ncheck_interval = 0\n\n[[runners]]\n  name = \"myrunner1\"\n  url = \"https://gitlab.example.com\"\n  token = \"<long string here>\"\n  executor = \"docker\"\n  [runners.docker]\n    tls_verify = false\n    image = \"ruby:2.1\"\n    privileged = false\n    disable_cache = false\n    volumes = [\"/cache\"]\n    shm_size = 0\n  [runners.cache]\n

\n\n\n\n\n

\n51.3 Serving

\n\n

\nLaunch runners

\n\n

Launch the mail server stack by running docker stack deploy gitlab-runner -c <path -to-docker-compose.yml>

\n\n

Log into your new instance at https://YOUR-FQDN, with user “root” and the password you specified in gitlab.env.

\n\n

\n51.4 Chef’s Notes

\n\n

You’ll note that I setup 2 runners. One is locked to a single project (this cookbook build), and the other is a shared runner. I wanted to ensure that one runner was always available to run CI for this project, even if I’d tied up another runner on something heavy-duty, like a container build. Customize this to your use case.
Originally I deployed runners in the same stack as GitLab, but I found that they would frequently fail to start properly when I launched the stack. I think that this was because the runners started so quickly (and GitLab starts sooo slowly!), that they always started up reporting that the GitLab instance was invalid or unavailable. I had issues with CI builds stuck permanently in a “pending” state, which were only resolved by restarting the runner. Having the runners deployed in a separate stack to GitLab avoids this problem.

\n\n\n

hero: Gollum - A recipe for your own git-based wiki

\n\n

\n52 Gollum

\n\n

Gollum is a simple wiki system built on top of Git. A Gollum Wiki is simply a git repository (either bare or regular) of a specific nature:

\n\n

A Gollum repository’s contents are human-editable, unless the repository is bare.
Pages are unique text files which may be organized into directories any way you choose.
Other content can also be included, for example images, PDFs and headers/footers for your pages.

\n\n

Gollum pages:

\n\n

May be written in a variety of markups.
Can be edited with your favourite system editor or IDE (changes will be visible after committing) or with the built-in web interface.
Can be displayed in all versions (commits).

\n\n

\n\n\n

As you’ll note in the (real world) screenshot above, my requirements for a personal wiki are:

\n\n

Portable across my devices
Supports images
Full-text search
Supports inter-note links
Revision control

\n\n

Gollum meets all these requirements, and as an added bonus, is extremely fast and lightweight.

\n\n Since Gollum itself offers no user authentication, this design secures gollum behind an oauth2 proxy, so that in order to gain access to the Gollum UI at all, oauth2 authentication (to GitHub, GitLab, Google, etc) must have already occurred.
\n

\n52.1 Ingredients

\n\n Existing:
\n 1. [X] Docker swarm cluster with persistent shared storage
2. [X] Traefik configured per design
3. [X] DNS entry for the hostname you intend to use, pointed to your keepalived IP
\n

\n52.2 Preparation

\n\n

\nSetup data locations

\n\n

We’ll need an empty git repository in /var/data/gollum for our data:

\n\n\n

mkdir /var/data/gollum\ncd /var/data/gollum\ngit init\n

\n\n\n\n\n

\nPrepare environment

\n\n

Choose an oauth provider, and obtain a client ID and secret
Create gollum.env, and populate with the following variables (you can make the cookie secret whatever you like)

\n\n\n

OAUTH2_PROXY_CLIENT_ID=\nOAUTH2_PROXY_CLIENT_SECRET=\nOAUTH2_PROXY_COOKIE_SECRET=\n

\n\n\n\n\n

\nSetup Docker Swarm

\n\n

Create a docker swarm config file in docker-compose syntax (v3), something like this:

version: '3'\n\nservices:\n  app:\n    image: dakue/gollum\n    volumes:\n     - /var/data/gollum:/gollum\n    networks:\n    - internal\n    command: |\n      --allow-uploads\n      --emoji\n      --user-icons gravatar\n\n  proxy:\n    image: a5huynh/oauth2_proxy\n    env_file : /var/data/config/gollum/gollum.env\n    networks:\n      - internal\n      - traefik_public\n    deploy:\n      labels:\n        - traefik.frontend.rule=Host:gollum.example.com\n        - traefik.docker.network=traefik_public\n        - traefik.port=4180\n    volumes:\n      - /var/data/config/gollum/authenticated-emails.txt:/authenticated-email\\\ns.txt\n    command: |\n      -cookie-secure=false\n      -upstream=http://app:4567\n      -redirect-url=https://gollum.example.com\n      -http-address=http://0.0.0.0:4180\n      -email-domain=example.com\n      -provider=github\n      -authenticated-emails-file=/authenticated-emails.txt\n\nnetworks:\n  traefik_public:\n    external: true\n  internal:\n    driver: overlay\n    ipam:\n      config:\n        - subnet: 172.16.9.0/24\n

\n\n\n\n\n Setup unique static subnets for every stack you deploy. This avoids IP/gateway conflicts which can otherwise occur when you’re creating/removing stacks a lot. See my list here.
\n

\n52.3 Serving

\n\n

\nLaunch Gollum stack

\n\n

Launch the Gollum stack by running docker stack deploy gollum -c <path-to-docker-compose.yml>

\n\n

Authenticate against your OAuth provider, and then start editing your wiki!

\n\n

\n52.4 Chef’s Notes

\n\n

1. In the current implementation, Gollum is a “single user” tool only. The contents of the wiki are saved as markdown files under /var/data/gollum, and all the git commits are currently “Anonymous”

\n\n\n

\n53 InstaPy

\n\n

InstaPy is an Instagram bot, developed by Tim Grossman. Tim describes his motivation and experiences developing the bot here.

\n\n

What’s an Instagram bot? Basically, you feed the bot your Instagram user/password, and it executes follows/unfollows/likes/comments on your behalf based on rules you set. (I set my bot to like one photo tagged with “#penguin” per-run)

\n\n

\n\n\n

Great power, right? A client (yes, you can hire me!) asked me to integrate InstaPy into their swarm, and this recipe is the result.

\n\n

\n53.1 Ingredients

\n\n Existing:
\n 1. [X] Docker swarm cluster with persistent shared storage
2. [X] Traefik configured per design
3. [X] DNS entry for the hostname you intend to use, pointed to your keepalived IP
\n

\n53.2 Preparation

\n\n

\nSetup data locations

\n\n

We need a data location to store InstaPy’s config, as well as its log files. Create /var/data/instapy per below

\n\n\n

mkdir -p /var/data/instapy/logs\n

\n\n\n\n\n

\nSetup Docker Swarm

\n\n

Create a docker swarm config file in docker-compose syntax (v3), something like this:

version: '3'\nservices:\n  web:\n    command: [\"./wait-for\", \"selenium:4444\", \"--\", \"python\", \"docker_quicksta\\\nrt.py\"]\n    environment:\n      - PYTHONUNBUFFERED=0\n\n    # Modify the image to whatever Tim's image tag ends up as. I used funkype\\\nnguin/instapy for my build\n    image: funkypenguin/instapy:latest\n\n    # When using swarm, you can't use relative paths, so the following needs \\\nto be set to the full filesystem path to your logs and docker_quickstart.py\n    # Bind-mount docker_quickstart.py, since now that we're using a public im\\\nage, we can't \"bake\" our credentials into the image anymore\n    volumes:\n      - /var/data/instapy/logs:/code/logs\n      - var/data/instapy/instapy.py:/code/docker_quickstart.py:ro\n\n    # This section allows docker to restart the container when it exits (eith\\\ner normally or abnormally), which ensures that\n    # InstaPy keeps re-running. Tweak the delay to avoid being banned for exc\\\nessive activity\n    deploy:\n      restart_policy:\n        condition: any\n        delay: 3600s\n\n\n  selenium:\n    image: selenium/standalone-chrome-debug\n    ports:\n      - \"5900:5900\"\n

\n\n\n\n\n Setup unique static subnets for every stack you deploy. This avoids IP/gateway conflicts which can otherwise occur when you’re creating/removing stacks a lot. See my list here.
\n

\nCommand your bot

\n\n

Create a variation of https://github.com/timgrossmann/InstaPy/blob/master/docker_quickstart.py at /var/data/instapy/instapy.py (the file we bind-mounted in the swarm config above)

\n\n

Change at least the following:

\n\n\n

insta_username = ''\ninsta_password = ''\n

\n\n\n\n\n

Here’s an example of my config, set to like a single penguin-pic per run:

\n\n\n

insta_username = 'funkypenguin'\ninsta_password = 'followmemypersonalbrandisawesome'\n\ndont_like = ['food','girl','batman','gotham','dead','nsfw','porn','slut','bab\\\ny','tv','athlete','nhl','hockey','estate','music','band','clothes']\nfriend_list = ['therock','ruinporn']\n\n# If you want to enter your Instagram Credentials directly just enter\n# username=<your-username-here> and password=<your-password> into InstaPy\n# e.g like so InstaPy(username=\"instagram\", password=\"test1234\")\n\nbot = InstaPy(username='insta_username', password='insta_password', selenium_\\\nlocal_session=False)\nbot.set_selenium_remote_session(selenium_url='http://selenium:4444/wd/hub')\nbot.login()\nbot.set_upper_follower_count(limit=10000)\nbot.set_lower_follower_count(limit=10)\nbot.set_comments([u'Cool :penguin:!', u'Awesome :penguin:!!', u'Nice :penguin\\\n:!!'])\nbot.set_dont_include(friend_list)\nbot.set_dont_like(dont_like)\n#bot.set_ignore_if_contains(ignore_words)\n\n# OK, so go through my feed and like stuff, interacting with people I follow\n# bot.like_by_feed(amount=3, randomize=True, unfollow=True, interact=True)\n\n# Now find posts tagged as #penguin, and like 'em, commenting 50% of the time\nbot.set_do_comment(True, percentage=50)\nbot.set_comments([u'Cool :penguin:!', u'Awesome :penguin:!!', u'Nice :penguin\\\n:!!'])\nbot.like_by_tags(['#penguin'], amount=1)\n\n# goodnight, sweet bot\nbot.end()\n

\n\n\n\n\n

\n53.3 Serving

\n\n

\nDestroy all humans

\n\n

Launch the bot by running docker stack deploy instapy -c <path -to-docker-compose.yml>

\n\n

While you’re waiting for Docker to pull down the images, educate yourself on the risk of a robotic uprising:

\n\n

\n\n

After swarm deploys, you won’t see much, but you can monitor what InstaPy is doing, by running docker service logs instapy_web.

\n\n

You can also watch the bot at work by VNCing to your docker swarm, password “secret”. You’ll see Selenium browser window cycling away, interacting with all your real/fake friends on Instagram :)

\n\n

\n53.4 Chef’s Notes

\n\n

1. Amazingly, my bot has ended up tagging more non-penguins than actual penguins. I don’t understand how Instagrammers come up with their hashtags!

\n\n\n

\n54 KeyCloak

\n\n

KeyCloak is “an open source identity and access management solution”. Using a local database, or a variety of backends (think OpenLDAP), you can provide Single Sign-On (SSO) using OpenID, OAuth 2.0, and SAML. KeyCloak’s OpenID provider can be used in combination with Traefik Forward Auth, to protect vulnerable services with an extra layer of authentication.

\n\n Initial development of this recipe was sponsored by The Common Observatory. Thanks guys!
\n [

\n\n](https://www.observe.global/)
\n

\n\n\n

\n54.1 Ingredients

\n\n Existing:
\n * [X] Docker swarm cluster with persistent shared storage
* [X] Traefik configured per design
* [X] DNS entry for the hostname (i.e. “keycloak.your-domain.com”) you intend to use, pointed to your keepalived IP
\n

\n54.2 Preparation

\n\n

\nSetup data locations

\n\n

We’ll need several directories to bind-mount into our container for both runtime and backup data, so create them as follows

\n\n\n

mkdir -p /var/data/runtime/keycloak/database\nmkdir -p /var/data/keycloak/database-dump\n

\n\n\n\n\n

\nPrepare environment

\n\n

Create /var/data/keycloak/keycloak.env, and populate with the following variables, customized for your own domain structure.

\n\n\n

# Technically, this could be auto-detected, but we prefer to be prescriptive\nDB_VENDOR=postgres\nDB_DATABASE=keycloak\nDB_ADDR=keycloak-db\nDB_USER=keycloak\nDB_PASSWORD=myuberpassword\nKEYCLOAK_USER=admin\nKEYCLOAK_PASSWORD=ilovepasswords\n\n# This is required to run keycloak behind traefik\nPROXY_ADDRESS_FORWARDING=true\n\n# What's our hostname?\nKEYCLOAK_HOSTNAME=keycloak.batcave.com\n\n# Tell Postgress what user/password to create\nPOSTGRES_USER=keycloak\nPOSTGRES_PASSWORD=myuberpassword\n

\n\n\n\n\n

Create /var/data/keycloak/keycloak-backup.env, and populate with the following, so that your database can be backed up to the filesystem, daily:

\n\n\n

PGHOST=keycloak-db\nPGUSER=keycloak\nPGPASSWORD=myuberpassword\nBACKUP_NUM_KEEP=7\nBACKUP_FREQUENCY=1d\n

\n\n\n\n\n

\nSetup Docker Swarm

\n\n

Create a docker swarm config file in docker-compose syntax (v3), something like this:

version: '3'\n\nservices:\n  keycloak:\n    image: jboss/keycloak\n    env_file: /var/data/config/keycloak/keycloak.env\n    volumes:\n      - /etc/localtime:/etc/localtime:ro    \n    networks:\n      - traefik_public\n      - internal\n    deploy:\n      labels:\n        - traefik.frontend.rule=Host:keycloak.batcave.com\n        - traefik.port=8080\n        - traefik.docker.network=traefik_public\n\n  keycloak-db:\n    env_file: /var/data/config/keycloak/keycloak.env\n    image: postgres:10.1\n    volumes:\n      - /var/data/runtime/keycloak/database:/var/lib/postgresql/data\n      - /etc/localtime:/etc/localtime:ro    \n    networks:\n      - internal\n\n  keycloak-db-backup:\n    image: postgres:10.1\n    env_file: /var/data/config/keycloak/keycloak-backup.env\n    volumes:\n      - /var/data/keycloak/database-dump:/dump\n      - /etc/localtime:/etc/localtime:ro\n    entrypoint: |\n      bash -c 'bash -s <<EOF\n      trap \"break;exit\" SIGHUP SIGINT SIGTERM\n      sleep 2m\n      while /bin/true; do\n        pg_dump -Fc > /dump/dump_\\`date +%d-%m-%Y\"_\"%H_%M_%S\\`.psql\n        (ls -t /dump/dump*.psql|head -n $$BACKUP_NUM_KEEP;ls /dump/dump*.psql\\\n)|sort|uniq -u|xargs rm -- {}\n        sleep $$BACKUP_FREQUENCY\n      done\n      EOF'\n    networks:\n      - internal\n\nnetworks:\n  traefik_public:\n    external: true\n  internal:\n    driver: overlay\n    ipam:\n      config:\n        - subnet: 172.16.49.0/24    \n

\n\n\n\n\n Setup unique static subnets for every stack you deploy. This avoids IP/gateway conflicts which can otherwise occur when you’re creating/removing stacks a lot. See my list here.
\n

\n54.3 Serving

\n\n

\nLaunch KeyCloak stack

\n\n

Launch the KeyCloak stack by running docker stack deploy keycloak -c <path -to-docker-compose.yml>

\n\n

Log into your new instance at https://YOUR-FQDN, and login with the user/password you defined in keycloak.env.

\n\n Initial development of this recipe was sponsored by The Common Observatory. Thanks guys!
\n [

\n\n](https://www.observe.global/)
\n

\n54.4 Chef’s Notes

\n\n\n

\n55 Create KeyCloak Users

\n\n This is not a complete recipe - it’s an optional component of the Keycloak recipe, but has been split into its own page to reduce complexity.
\n

Unless you plan to authenticate against an outside provider (OpenLDAP, below, for example), you’ll want to create some local users..

\n\n

\n55.1 Ingredients

\n\n Existing:
\n * [X] KeyCloak recipe deployed successfully
\n

\nCreate User

\n\n

Within the “Master” realm (no need for more realms yet), navigate to Manage -> Users, and then click Add User at the top right:

\n\n

\"\" — Navigating to the add user interface in Keycloak

\n\n\n

Populate your new user’s username (it’s the only mandatory field)

\n\n

\"\" — Populating a username in the add user interface in Keycloak

\n\n\n

\nSet User Credentials

\n\n

Once your user is created, to set their password, click on the “Credentials” tab, and procede to reset it. Set the password to non-temporary, unless you like extra work!

\n\n

\"\" — Resetting a user’s password in Keycloak

\n\n\n

\n55.2 Summary

\n\n

We’ve setup users in KeyCloak, which we can now use to authenticate to KeyCloak, when it’s used as an OIDC Provider, potentially to secure vulnerable services using Traefik Forward Auth.

\n\n Created:
\n * [X] Username / password to authenticate against KeyCloak
\n\n

\n56 Authenticate KeyCloak against OpenLDAP

\n\n This is not a complete recipe - it’s an optional component of the Keycloak recipe, but has been split into its own page to reduce complexity.
\n

KeyCloak gets really sexy when you integrate it into your OpenLDAP stack (also, it’s great not to have to play with ugly LDAP tree UIs). Note that OpenLDAP integration is not necessary if you want to use KeyCloak with Traefik Forward Auth - all you need for that is local users, and an OIDC client.

\n\n

\n56.1 Ingredients

\n\n Existing:
\n * [X] KeyCloak recipe deployed successfully
\n New:
\n * [ ] An OpenLDAP server (assuming you want to authenticate against it)
\n

\n56.2 Preparation

\n\n

You’ll need to have completed the OpenLDAP recipe

\n\n

You start in the “Master” realm - but mouseover the realm name, to a dropdown box allowing you add an new realm:

\n\n

\nCreate Realm

\n\n

\n\n\n

Enter a name for your new realm, and click “Create”:

\n\n

\n\n\n

\nSetup User Federation

\n\n

Once in the desired realm, click on User Federation, and click Add Provider. On the next page (“Required Settings”), set the following:

\n\n

\nEdit Mode : Writeable
\nVendor : Other
\nConnection URL : ldap://openldap
\nUsers DN : ou=People,<your base DN>
\nAuthentication Type : simple
\nBind DN : cn=admin,<your base DN>
\nBind Credential : <your chosen admin password>

\n\n

Save your changes, and then navigate back to “User Federation” > Your LDAP name > Mappers:

\n\n

\n\n\n

For each of the following mappers, click the name, and set the “Read Only” flag to “Off” (this enables 2-way sync between KeyCloak and OpenLDAP)

\n\n

last name
username
email
first name

\n\n

\n\n\n

\n56.3 Summary

\n\n

We’ve setup a new realm in KeyCloak, and configured read-write federation to an OpenLDAP backend. We can now manage our LDAP users using either KeyCloak or LDAP directly, and we can protect vulnerable services using Traefik Forward Auth.

\n\n Created:
\n * [X] KeyCloak realm in read-write federation with OpenLDAP directory
\n

\n56.4 Chef’s Notes

\n\n\n

\n57 Add OIDC Provider to KeyCloak

\n\n This is not a complete recipe - it’s an optional component of the Keycloak recipe, but has been split into its own page to reduce complexity.
\n

Having an authentication provider is not much use until you start authenticating things against it! In order to authenticate against KeyCloak using OpenID Connect (OIDC), which is required for Traefik Forward Auth, we’ll setup a client in KeyCloak…

\n\n

\n57.1 Ingredients

\n\n Existing:
\n * [X] KeyCloak recipe deployed successfully
\n New:
\n * [ ] The URI(s) to protect with the OIDC provider. Refer to the Traefik Forward Auth recipe for more information
\n

\n57.2 Preparation

\n\n

\nCreate Client

\n\n

Within the “Master” realm (no need for more realms yet), navigate to Clients, and then click Create at the top right:

\n\n

\"\" — Navigating to the add user interface in Keycloak

\n\n\n

Enter a name for your client (remember, we’re authenticating applications now, not users, so use an application-specific name):

\n\n

\n\n\n

\nConfigure Client

\n\n

Once your client is created, set at least the following, and click Save

\n\n

\nAccess Type : Confidential
\nValid Redirect URIs : <The URIs you want to protect>

\n\n

\"\" — Set KeyCloak client to confidential access type, add redirect URIs

\n\n\n

\nRetrieve Client Secret

\n\n

Now that you’ve changed the access type, and clicked Save, an additional Credentials tab appears at the top of the window. Click on the tab, and capture the KeyCloak-generated secret. This secret, plus your client name, is required to authenticate against KeyCloak via OIDC.

\n\n

\"\" — Capture client secret from KeyCloak

\n\n\n

\n57.3 Summary

\n\n

We’ve setup an OIDC client in KeyCloak, which we can now use to protect vulnerable services using Traefik Forward Auth. The OIDC URL provided by KeyCloak in the master realm, is https://<your-keycloak-url>/realms/master/.well-known/openid-configuration

\n\n Created:
\n * [X] Client ID and Client Secret used to authenticate against KeyCloak with OpenID Connect
\n

\n57.4 Chef’s Notes

\n\n\n

\n58 OpenLDAP

\n\n Development of this recipe is sponsored by The Common Observatory. Thanks guys!
\n [

\n\n](https://www.observe.global/)
\n

LDAP is probably the most ubiquitous authentication backend, before the current era of “stupid social sign-ons”. Many of the recipes featured in the cookbook (NextCloud, Kanboard, Gitlab, etc) offer LDAP integration.

\n\n

\n58.1 Big deal, who cares?

\n\n

If you’re the only user of your tools, it probably doesn’t bother you too much to setup new user accounts for every tool. As soon as you start sharing tools with collaborators (think 10 staff using NextCloud), you suddenly feel the pain of managing a growing collection of local user accounts per-service.

\n\n

Enter OpenLDAP - the most crusty, PITA, fiddly platform to setup (yes, I’m a little bitter, dynamic configuration backend!), but hugely useful for one job - a Lightweight Protocol for managing a Directory used for Access (see what I did there?)

\n\n

The nice thing about OpenLDAP is, like MySQL, once you’ve setup the server, you probably never have to interact directly with it. There are many tools which will let you interact with your LDAP database via a(n ugly) UI.

\n\n

This recipe combines the raw power of OpenLDAP with the flexibility and featureset of LDAP Account Manager.

\n\n

\n\n\n

\n58.2 What’s the takeaway?

\n\n

What you’ll end up with is a directory structure which will allow integration with popular tools (NextCloud, Kanboard, Gitlab, etc), as well as with KeyCloak (an upcoming recipe), for true SSO.

\n\n

\n58.3 Ingredients

\n\n

\nDocker swarm cluster with persistent shared storage\n
\nTraefik configured per design
DNS entry for the hostname (i.e. “lam.your-domain.com”) you intend to use for LDAP Account Manager, pointed to your keepalived IP

\n\n

\n58.4 Preparation

\n\n

\nSetup data locations

\n\n

We’ll need several directories to bind-mount into our container, so create them in /var/data/openldap:

\n\n\n

mkdir /var/data/openldap/openldap\nmkdir /var/data/runtime/openldap/\n

\n\n\n\n\n For rationale, see my data layout explanation
\n

\nPrepare environment

\n\n

Create /var/data/openldap/openldap.env, and populate with the following variables, customized for your own domain structure. Take care with LDAP_DOMAIN, this is core to your directory structure, and can’t easily be changed later.

\n\n\n

LDAP_DOMAIN=batcave.gotham\nLDAP_ORGANISATION=BatCave Inc\nLDAP_ADMIN_PASSWORD=supermansucks\nLDAP_TLS=false\n\n# Use these if you plan to protect the LDAP Account Manager webUI with an oau\\\nth_proxy\nOAUTH2_PROXY_CLIENT_ID=\nOAUTH2_PROXY_CLIENT_SECRET=\nOAUTH2_PROXY_COOKIE_SECRET=\n

\n\n\n\n\n I use an OAuth proxy to protect access to the web UI, when the sensitivity of the protected data (i.e. my authentication store) warrants it, or if I don’t necessarily trust the security of the webUI.
\n

Create authenticated-emails.txt, and populate with the email addresses (matched to GitHub user accounts, in my case) to which you want grant access, using OAuth2.

\n\n

\nCreate config.cfg

\n\n

The Dockerized version of LDAP Account Manager is a little fiddly. In order to maintain a config file which persists across container restarts, we need to present the container with a copy of /var/www/html/config/lam.conf, tweaked for our own requirements.

\n\n

Create /var/data/openldap/lam/config/config.cfg as follows:

\n\n

???+ note “Much scroll, very text. Click here to collapse it for better readability”

\n\n\n

    # password to add/delete/rename configuration profiles (default: lam)\n    password: {SSHA}D6AaX93kPmck9wAxNlq3GF93S7A= R7gkjQ==\n\n    # default profile, without \".conf\"\n    default: batcave\n\n    # log level\n    logLevel: 4\n\n    # log destination\n    logDestination: SYSLOG\n\n    # session timeout in minutes\n    sessionTimeout: 30\n\n    # list of hosts which may access LAM\n    allowedHosts:\n\n    # list of hosts which may access LAM Pro self service\n    allowedHostsSelfService:\n\n    # encrypt session data\n    encryptSession: true\n\n    # Password: minimum password length\n    passwordMinLength: 0\n\n    # Password: minimum uppercase characters\n    passwordMinUpper: 0\n\n    # Password: minimum lowercase characters\n    passwordMinLower: 0\n\n    # Password: minimum numeric characters\n    passwordMinNumeric: 0\n\n    # Password: minimum symbolic characters\n    passwordMinSymbol: 0\n\n    # Password: minimum character classes (0-4)\n    passwordMinClasses: 0\n\n    # Password: checked rules\n    checkedRulesCount: -1\n\n    # Password: must not contain part of user name\n    passwordMustNotContain3Chars: false\n\n    # Password: must not contain user name\n    passwordMustNotContainUser: false\n\n    # Email format (default/unix)\n    mailEOL: default\n\n    # PHP error reporting (default/system)\n    errorReporting: default\n\n    # License\n    license:\n

\n\n\n\n\n

\nCreate <profile>.cfg

\n\n

While config.cfg (above) defines application-level configuration, <profile>.cfg is used to configure “domain-specific” configuration. You probably only need a single profile, but LAM could theoretically be used to administer several totally unrelated LDAP servers, ergo the concept of “profiles”.

\n\n

Create yours profile (you chose a default profile in config.cfg above, remember?) by creating /var/data/openldap/lam/config/<profile>.conf, as follows:

\n\n

???+ note “Much scroll, very text. Click here to collapse it for better readability”

\n\n\n

    # LDAP Account Manager configuration\n    #\n    # Please do not modify this file manually. The configuration can be done \\\ncompletely by the LAM GUI.\n    #\n    #########################################################################\\\n##########################\n\n    # server address (e.g. ldap://localhost:389 or ldaps://localhost:636)\n    ServerURL: ldap://openldap:389\n\n    # list of users who are allowed to use LDAP Account Manager\n    # names have to be separated by semicolons\n    # e.g. admins: cn=admin,dc=yourdomain,dc=org;cn=root,dc=yourdomain,dc=org\n    Admins: cn=admin,dc=batcave,dc=gotham\n\n    # password to change these preferences via webfrontend (default: lam)\n    Passwd: {SSHA}h39N9+gg/Qf1K/986VkKrjWlkcI= S/IAUQ==\n\n    # suffix of tree view\n    # e.g. dc=yourdomain,dc=org\n    treesuffix: dc=batcave,dc=gotham\n\n    # default language (a line from config/language)\n    defaultLanguage: en_GB.utf8\n\n    # Path to external Script\n    scriptPath:\n\n    # Server of external Script\n    scriptServer:\n\n    # Access rights for home directories\n    scriptRights: 750\n\n    # Number of minutes LAM caches LDAP searches.\n    cachetimeout: 5\n\n    # LDAP search limit.\n    searchLimit: 0\n\n    # Module settings\n\n    modules: posixAccount_user_minUID: 10000\n    modules: posixAccount_user_maxUID: 30000\n    modules: posixAccount_host_minMachine: 50000\n    modules: posixAccount_host_maxMachine: 60000\n    modules: posixGroup_group_minGID: 10000\n    modules: posixGroup_group_maxGID: 20000\n    modules: posixGroup_pwdHash: SSHA\n    modules: posixAccount_pwdHash: SSHA\n\n    # List of active account types.\n    activeTypes: user,group\n\n\n    types: suffix_user: ou=People,dc=batcave,dc=gotham\n    types: attr_user: #uid;#givenName;#sn;#uidNumber;#gidNumber\n    types: modules_user: inetOrgPerson,posixAccount,shadowAccount\n\n    types: suffix_group: ou=Groups,dc=batcave,dc=gotham\n    types: attr_group: #cn;#gidNumber;#memberUID;#description\n    types: modules_group: posixGroup\n\n    # Password mail subject\n    lamProMailSubject: Your password was reset\n\n    # Password mail text\n    lamProMailText: Dear @@givenName@@ @@sn@@,+::++::+your password was reset\\\n to: @@newPassword@@+::++::++::+Best regards+::++::+deskside support+::+\n\n    serverDisplayName:\n\n\n    # enable TLS encryption\n    useTLS: no\n\n\n    # follow referrals\n    followReferrals: false\n\n\n    # paged results\n    pagedResults: false\n\n    referentialIntegrityOverlay: false\n\n\n    # time zone\n    timeZone: Europe/London\n\n    scriptUserName:\n\n    scriptSSHKey:\n\n    scriptSSHKeyPassword:\n\n\n    # Access level for this profile.\n    accessLevel: 100\n\n\n    # Login method.\n    loginMethod: list\n\n\n    # Search suffix for LAM login.\n    loginSearchSuffix: dc=batcave,dc=gotham\n\n\n    # Search filter for LAM login.\n    loginSearchFilter: uid=%USER%\n\n\n    # Bind DN for login search.\n    loginSearchDN:\n\n\n    # Bind password for login search.\n    loginSearchPassword:\n\n\n    # HTTP authentication for LAM login.\n    httpAuthentication: false\n\n\n    # Password mail from\n    lamProMailFrom:\n\n\n    # Password mail reply-to\n    lamProMailReplyTo:\n\n\n    # Password mail is HTML\n    lamProMailIsHTML: false\n\n\n    # Allow alternate address\n    lamProMailAllowAlternateAddress: true\n\n    jobsBindPassword:\n\n    jobsBindUser:\n\n    jobsDatabase:\n\n    jobsDBHost:\n\n    jobsDBPort:\n\n    jobsDBUser:\n\n    jobsDBPassword:\n\n    jobsDBName:\n\n    jobToken: 190339140545\n\n    pwdResetAllowSpecificPassword: true\n\n    pwdResetAllowScreenPassword: true\n\n    pwdResetForcePasswordChange: true\n\n    pwdResetDefaultPasswordOutput: 2\n\n    twoFactorAuthentication: none\n\n    twoFactorAuthenticationURL: https://localhost\n\n    twoFactorAuthenticationInsecure:\n\n    twoFactorAuthenticationLabel:\n\n    twoFactorAuthenticationOptional:\n\n    twoFactorAuthenticationCaption:\n    tools: tool_hide_toolOUEditor: false\n    tools: tool_hide_toolProfileEditor: false\n    tools: tool_hide_toolSchemaBrowser: false\n    tools: tool_hide_toolServerInformation: false\n    tools: tool_hide_toolTests: false\n    tools: tool_hide_toolPDFEditor: false\n    tools: tool_hide_toolFileUpload: false\n    tools: tool_hide_toolMultiEdit: false\n

\n\n\n\n\n

\nSetup Docker Swarm

\n\n

Create a docker swarm config file in docker-compose syntax (v3), something like this, at (/var/data/config/openldap/openldap.yml)

version: '3'\n\nservices:\n  openldap:\n    image: osixia/openldap\n    env_file: /var/data/config/openldap/openldap.env\n    networks:\n    - traefik_public\n    - auth_internal\n    volumes:\n    - /var/data/runtime/openldap/:/var/lib/ldap\n    - /var/data/openldap/openldap/:/etc/ldap/slapd.d\n\n  lam:\n    image: jacksgt/ldap-account-manager\n    networks:\n    - auth_internal\n    volumes:\n    - /var/data/openldap/lam/config/config.cfg:/var/www/html/config/config.cfg\n    - /var/data/openldap/lam/config/batcave.conf:/var/www/html/config/batcave\\\n.conf\n\n  lam-proxy:\n    image: funkypenguin/oauth2_proxy\n    env_file: /var/data/config/openldap/openldap.env\n    networks:\n      - traefik_public\n      - auth_internal\n    deploy:\n      labels:\n        - traefik.frontend.rule=Host:lam.batcave.com\n        - traefik.docker.network=traefik_public\n        - traefik.port=4180\n    command: |\n      -cookie-secure=false\n      -upstream=http://lam:8080\n      -redirect-url=https://lam.batcave.com\n      -http-address=http://0.0.0.0:4180\n      -email-domain=batcave.com\n      -provider=github\n\n\nnetworks:\n  # Used to expose lam-proxy to external access, and openldap to keycloak\n  traefik_public:\n    external: true\n\n  # Used to expose openldap to other apps which want to talk to LDAP, includi\\\nng LAM\n  auth_internal:\n    external: true    \n

\n\n\n\n\n Normally, we set unique static subnets for every stack you deploy, and put the non-public facing components (like databases) in an dedicated <stack>_internal network. This avoids IP/gateway conflicts which can otherwise occur when you’re creating/removing stacks a lot. See my list here.
\n However, you’re likely to want to use OpenLdap with KeyCloak, whose JBOSS startup script assumes a single interface, and will crash in a ball of if you try to assign multiple interfaces to the container.
\n Since we’re going to want KeyCloak to be able to talk to OpenLDAP, we have no choice but to leave the OpenLDAP container on the “traefik_public” network. We can, however, create another overlay network (auth_internal, see below), add it to the openldap container, and use it to provide OpenLDAP access to our other stacks.
\n

Create another stack config file (/var/data/config/openldap/auth.yml) containing just the auth_internal network, and a dummy container:

\n\n\n

version: \"3.2\"\n\n# What is this?\n#\n# This stack exists solely to deploy the auth_internal overlay network, so th\\\nat\n# other stacks (including keycloak and openldap) can attach to it\n\nservices:\n  scratch:\n    image: scratch\n    deploy:\n      replicas: 0\n    networks:\n      - internal\n\nnetworks:\n  internal:\n    driver: overlay\n    attachable: true\n    ipam:\n      config:\n        - subnet: 172.16.39.0/24\n

\n\n\n\n\n

\n58.5 Serving

\n\n

\nLaunch OpenLDAP stack

\n\n

Create the auth_internal overlay network, by running docker stack deploy auth -c /var/data/config/openldap/auth.yml, then launch the OpenLDAP stack by running docker stack deploy openldap -c /var/data/config/openldap/openldap.yml

\n\n

Log into your new LAM instance at https://YOUR-FQDN.

\n\n

On first login, you’ll be prompted to create the “ou=People” and “ou=Group” elements. Proceed to create these.

\n\n

You’ve now setup your OpenLDAP directory structure, and your administration interface, and hopefully won’t have to interact with the “special” LDAP Account Manager interface much again!

\n\n

Create your users using the “New User” button.

\n\n Development of this recipe is sponsored by The Common Observatory. Thanks guys!
\n [

\n\n](https://www.observe.global/)
\n

\n58.6 Chef’s Notes

\n\n

\nThe KeyCloak recipe illustrates how to integrate KeyCloak with your LDAP directory, giving you a cleaner interface to manage users, and a raft of SSO / OAuth features.

\n\n\n

hero: Docker-mailserver - A recipe for a self-contained mailserver and friends

\n\n

\n59 Mail Server

\n\n

Many of the recipes that follow require email access of some kind. It’s normally possible to use a hosted service such as SendGrid, or just a gmail account. If (like me) you’d like to self-host email for your stacks, then the following recipe provides a full-stack mail server running on the docker HA swarm.

\n\n

Of value to me in choosing docker-mailserver were:

\n\n

Automatically renews LetsEncrypt certificates
Creation of email accounts across multiple domains (i.e., the same container gives me mailbox wekan@wekan.example.com, and gitlab@gitlab.example.com)
The entire configuration is based on flat files, so there’s no database or persistence to worry about

\n\n

docker-mailserver doesn’t include a webmail client, and one is not strictly needed. Rainloop can be added either as another service within the stack, or as a standalone service. Rainloop will be covered in a future recipe.

\n\n

\n59.1 Ingredients

\n\n

\nDocker swarm cluster with persistent shared storage\n
\nTraefik configured per design
LetsEncrypt authorized email address for domain
Access to manage DNS records for domains

\n\n

\n59.2 Preparation

\n\n

\nSetup data locations

\n\n

We’ll need several directories to bind-mount into our container, so create them in /var/data/docker-mailserver:

\n\n\n

cd /var/data\nmkdir docker-mailserver\ncd docker-mailserver\nmkdir {maildata,mailstate,config,letsencrypt,rainloop}\n

\n\n\n\n\n

\nGet LetsEncrypt certificate

\n\n

Decide on the FQDN to assign to your mailserver. You can service multiple domains from a single mailserver - i.e., bob@dev.example.com and daphne@prod.example.com can both be served by mail.example.com.

\n\n

The docker-mailserver container can renew our LetsEncrypt certs for us, but it can’t generate them. To do this, we need to run certbot (from a container) to request the initial certs and create the appropriate directory structure.

\n\n

In the example below, since I’m already using Traefik to manage the LE certs for my web platforms, I opted to use the DNS challenge to prove my ownership of the domain. The certbot client will prompt you to add a DNS record for domain verification.

\n\n\n

docker run -ti --rm -v \\\n\"$(pwd)\"/letsencrypt:/etc/letsencrypt certbot/certbot \\\n--manual --preferred-challenges dns certonly \\\n-d mail.example.com\n

\n\n\n\n\n

\nGet setup.sh

\n\n

docker-mailserver comes with a handy bash script for managing the stack (which is just really a wrapper around the container.) It’ll make our setup easier, so download it into the root of your configuration/data directory, and make it executable:

\n\n\n

curl -o setup.sh \\\nhttps://raw.githubusercontent.com/tomav/docker-mailserver/master/setup.sh \\\nchmod a+x ./setup.sh\n

\n\n\n\n

### Create email accounts

\n\n

For every email address required, run ./setup.sh email add <email> <password> to create the account. The command returns no output.

\n\n

You can run ./setup.sh email list to confirm all of your addresses have been created.

\n\n

\nCreate DKIM DNS entries

\n\n

Run ./setup.sh config dkim to create the necessary DKIM entries. The command returns no output.

\n\n

Examine the keys created by opendkim to identify the DNS TXT records required:

\n\n\n

for i in `find config/opendkim/keys/ -name mail.txt`; do \\\necho $i; \\\ncat $i; \\\ndone\n

\n\n\n\n\n

You’ll end up with something like this:

\n\n\n

config/opendkim/keys/gitlab.example.com/mail.txt\nmail._domainkey\tIN\tTXT\t( \"v=DKIM1; k=rsa; \"\n\t  \"p=MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQCYuQqDg2ZG8ZOfI1PvarF1Gcr5cJnCR8B\\\neCj5HYgeRohSrxKL5utPEF/AWAxXYwnKpgYN837fu74GfqsIuOhu70lPhGV+O2gFVgpXYWHELvIiT\\\nqqO0QgarIN63WE2gzE4s0FckfLrMuxMoXr882wuzuJhXywGxOavybmjpnNHhbQIDAQAB\" )  ; --\\\n--- DKIM key mail for gitlab.example.com\n[root@ds1 mail]#\n

\n\n\n\n\n

Create the necessary DNS TXT entries for your domain(s). Note that although opendkim splits the record across two lines, the actual record should be concatenated on creation. I.e., the DNS TXT record above should read:

\n\n\n

\"v=DKIM1; k=rsa; p=MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQCYuQqDg2ZG8ZOfI1Pvar\\\nF1Gcr5cJnCR8BeCj5HYgeRohSrxKL5utPEF/AWAxXYwnKpgYN837fu74GfqsIuOhu70lPhGV+O2gF\\\nVgpXYWHELvIiTqqO0QgarIN63WE2gzE4s0FckfLrMuxMoXr882wuzuJhXywGxOavybmjpnNHhbQID\\\nAQAB\"\n

\n\n\n\n\n

\nSetup Docker Swarm

\n\n

Create a docker swarm config file in docker-compose syntax (v3.2 - because we need to expose mail ports in “host mode”), something like this:

version: '3.2'\n\nservices:\n  mail:\n    image: tvial/docker-mailserver:latest\n    ports:\n      - target: 25\n        published: 25\n        protocol: tcp\n        mode: host\n      - target: 587\n        published: 587\n        protocol: tcp\n        mode: host\n      - target: 993\n        published: 993\n        protocol: tcp\n        mode: host\n      - target: 995\n        published: 995\n        protocol: tcp\n        mode: host\n    volumes:\n      - /var/data/docker-mailserver/maildata:/var/mail\n      - /var/data/docker-mailserver/mailstate:/var/mail-state\n      - /var/data/docker-mailserver/config:/tmp/docker-mailserver\n      - /var/data/docker-mailserver/letsencrypt:/etc/letsencrypt\n    env_file: /var/data/docker-mailserver/docker-mailserver.env\n    networks:\n      - internal\n    deploy:\n      replicas: 1\n\n\trainloop:\n    image: hardware/rainloop\n    networks:\n      - internal\n      - traefik_public\n    deploy:\n      labels:\n        - traefik.frontend.rule=Host:rainloop.example.com\n        - traefik.docker.network=traefik_public\n        - traefik.port=8888\n    volumes:\n      - /var/data/mailserver/rainloop:/rainloop/data\n\nnetworks:\n  traefik_public:\n    external: true\n  internal:\n    driver: overlay\n    ipam:\n      config:\n        - subnet: 172.16.2.0/24\n

\n\n\n\n\n Setup unique static subnets for every stack you deploy. This avoids IP/gateway conflicts which can otherwise occur when you’re creating/removing stacks a lot.
\n

A sample docker-mailserver.env file looks like this:

\n\n\n

ENABLE_SPAMASSASSIN=1\nENABLE_CLAMAV=1\nENABLE_POSTGREY=1\nONE_DIR=1\nOVERRIDE_HOSTNAME=mail.example.com\nOVERRIDE_DOMAINNAME=mail.example.com\nPOSTMASTER_ADDRESS=admin@example.com\nPERMIT_DOCKER=network\nSSL_TYPE=letsencrypt\n

\n\n\n\n\n

\n59.3 Serving

\n\n

\nLaunch mailserver

\n\n

Launch the mail server stack by running docker stack deploy docker-mailserver -c <path-to-docker-mailserver.yml>

\n\n

\n59.4 Chef’s Notes

\n\n

One of the elements of this design which I didn’t appreciate at first is that since the config is entirely file-based, setup.sh can be run on any container host, provided it has the shared data mounted. This means that even though docker-mailserver was not designed with docker swarm in mind, it works perfectl with swarm. I.e., from any node, regardless of where the container is actually running, you’re able to add/delete email addresses, view logs, etc.
If you’re using sieve with Rainloop, take note of the workaround identified by ggilley\n

\n\n\n

\n60 Minio

\n\n

Minio is a high performance distributed object storage server, designed for
large-scale private cloud infrastructure.

\n\n

However, at its simplest, Minio allows you to expose a local filestructure via the Amazon S3 API. You could, for example, use it to provide access to “buckets” (folders) of data on your filestore, secured by access/secret keys, just like AWS S3. You can further interact with your “buckets” with common tools, just as if they were hosted on S3.

\n\n

Under a more advanced configuration, Minio runs in distributed mode, with features including high-availability, mirroring, erasure-coding, and “bitrot detection”.

\n\n

\n\n\n

Possible use-cases:

\n\n

Sharing files (protected by user accounts with secrets) via HTTPS, either as read-only or read-write, in such a way that the bucket could be mounted to a remote filesystem using common S3-compatible tools, like goofys. Ever wanted to share a folder with friends, but didn’t want to open additional firewall ports etc?
Simulating S3 in a dev environment
Mirroring an S3 bucket locally

\n\n

\n60.1 Ingredients

\n\n

\nDocker swarm cluster with persistent shared storage\n
\nTraefik configured per design
DNS entry for the hostname you intend to use, pointed to your keepalived IP

\n\n

\n60.2 Preparation

\n\n

\nSetup data locations

\n\n

We’ll need a directory to hold our minio file store, as well as our minio client config, so create a structure at /var/data/minio:

\n\n\n

mkdir /var/data/minio\ncd /var/data/minio\nmkdir -p {mc,data}\n

\n\n\n\n\n

\nPrepare environment

\n\n

Create minio.env, and populate with the following variables

\n\n

MINIO_ACCESS_KEY=<some random, complex string>\nMINIO_SECRET_KEY=<another random, complex string>\n

\n\n\n\n\n

\nSetup Docker Swarm

\n\n

Create a docker swarm config file in docker-compose syntax (v3), something like this:

version: '3.1'\n\nservices:\n  app:\n    image: minio/minio\n    env_file: /var/data/config/minio/minio.env\n    volumes:\n     - /var/data/minio/data:/data\n    networks:\n      - traefik_public\n    deploy:\n      labels:\n        - traefik.frontend.rule=Host:minio.example.com\n        - traefik.port=9000\n    command:  minio server /data\n\nnetworks:\n  traefik_public:\n    external: true\n

\n\n\n\n\n

\n60.3 Serving

\n\n

\nLaunch Minio stack

\n\n

Launch the Minio stack by running docker stack deploy minio -c <path -to-docker-compose.yml>

\n\n

Log into your new instance at https://YOUR-FQDN, with the access key and secret key you specified in minio.env.

\n\n

If you created /var/data/minio, you’ll see nothing. If you referenced existing data, you should see all subdirectories in your existing folder represented as buckets.

\n\n

If all you need is single-user access to your data, you’re done!

\n\n

If, however, you want to expose data to multiple users, at different privilege levels, you’ll need the minio client to create some users and (potentially) policies…

\n\n

\nSetup minio client

\n\n

To administer the Minio server, we need the Minio client. While it’s possible to download the minio client and run it locally, it’s just as easy to do it within a small (5Mb) container.

\n\n

I created an alias on my docker nodes, allowing me to run mc quickly:

\n\n\n

alias mc='docker run -it -v /docker/minio/mc/:/root/.mc/ --network traefik_pu\\\nblic minio/mc'\n

\n\n\n\n\n

Now I use the alias to launch the client shell, and connect to my minio instance (I could also use the external, traefik-provided URL)

\n\n\n

root@ds1:~# mc config host add minio http://app:9000 admin iambatman\nmc: Configuration written to `/root/.mc/config.json`. Please update your acce\\\nss credentials.\nmc: Successfully created `/root/.mc/share`.\nmc: Initialized share uploads `/root/.mc/share/uploads.json` file.\nmc: Initialized share downloads `/root/.mc/share/downloads.json` file.\nAdded `minio` successfully.\nroot@ds1:~#\n

\n\n\n\n\n

\nAdd (readonly) user

\n\n

Use mc to add a (readonly or readwrite) user, by running mc admin user add minio <access key> <secret key> <access level>

\n\n

Example:

\n\n\n

root@ds1:~# mc admin user add minio spiderman peterparker readonly\nAdded user `spiderman` successfully.\nroot@ds1:~#\n

\n\n\n\n\n

Confirm by listing your users (admin is excluded from the list):

\n\n\n

root@node1:~# mc admin user list minio\nenabled    spiderman             readonly\nroot@node1:~#\n

\n\n\n\n\n

\nMake a bucket accessible to users

\n\n

By default, all buckets have no “policies” attached to them, and so can only be accessed by the administrative user. Having created some readonly/read-write users above, you’ll be wanting to grant them access to buckets.

\n\n

The simplest permission scheme is “on or off”. Either a bucket has a policy, or it doesn’t. (I believe you can apply policies to subdirectories of buckets in a more advanced configuration)

\n\n

After no policy, the most restrictive policy you can attach to a bucket is “download”. This policy will allow authenticated users to download contents from the bucket. Apply the “download” policy to a bucket by running mc policy download minio/<bucket name>, i.e.:

\n\n\n

root@ds1:# mc policy download minio/comics\nAccess permission for `minio/comics` is set to `download`\nroot@ds1:#\n

\n\n\n\n\n

\nAdvanced bucketing

\n\n

There are some clever complexities you can achieve with user/bucket policies, including:

\n\n

A public bucket, which requires no authentication to read or even write (for a public dropbox, for example)
A special bucket, hidden from most users, but available to VIP users by application of a custom “canned policy”

\n\n\n\n

Having setup your buckets, users, and policies - you can give out your minio external URL, and user access keys to your remote users, and they can S3-mount your buckets, interacting with them based on their user policy (read-only or read/write)

\n\n

I tested the S3 mount using goofys, “a high-performance, POSIX-ish Amazon S3 file system written in Go”.

\n\n

First, I created ~/.aws/credentials, as follows:

\n\n\n

[default]\naws_access_key_id=spiderman\naws_secret_access_key=peterparker\n

\n\n\n\n\n

And then I ran (in the foreground, for debugging), goofys --f -debug_s3 --debug_fuse --endpoint=https://traefik.example.com <bucketname> <local mount point>

\n\n

To permanently mount an S3 bucket using goofys, I’d add something like this to /etc/fstab:

\n\n\n

goofys#bucket   /mnt/mountpoint        fuse     _netdev,allow_other,--file-mo\\\nde=0666    0       0\n

\n\n\n\n\n

\n60.4 Chef’s Notes

\n\n

There are many S3-filesystem-mounting tools available, I just picked Goofys because it’s simple. Google is your friend :)
Some applications (like NextCloud) can natively mount S3 buckets
Some backup tools (like Duplicity) can backup directly to S3 buckets

\n\n\n

\n61 Piwik

\n\n

Piwik is a rich open-source web analytics platform, which can be coupled with commercial plugins for additional features. It’s most simply described as “self-hosted Google Analytics”.

\n\n

\n\n\n

\n61.1 Ingredients

\n\n

\nDocker swarm cluster with persistent shared storage\n
\nTraefik configured per design

\n\n

\n61.2 Preparation

\n\n

\nLimitation of docker-swarm

\n\n

The docker-swarm load-balancer is a problem for deploying piwik, since it rewrites the source address of every incoming packet to whichever docker node received the packet into the swarm. Which is a PITA for analytics, since the original source IP of the request is obscured.

\n\n

The issue is tracked at #25526, and there is a workaround, but it requires running the piwik “app” container on every swarm node…

\n\n

\nPrepare environment

\n\n

Create piwik.env, and populate with the following variables

\n\n\n

MYSQL_ROOT_PASSWORD=set-me-and-use-me-when-setting-up-piwik\n

\n\n\n\n\n

\nSetup docker swarm

\n\n

Create a docker swarm config file in docker-compose syntax (v3), something like this:

version: '3'\n\nservices:\n  db:\n    image: mysql\n    volumes:\n      - /var/data/piwik/mysql/runtime:/var/lib/mysql\n    env_file: /var/data/piwik/piwik.env\n    networks:\n    - internal\n  app:\n    image: piwik:apache\n    volumes:\n      - /var/data/piwik/config:/var/www/html/config\n    networks:\n    - internal\n    - traefik\n    deploy:\n      mode: global\n      labels:\n        - traefik.frontend.rule=Host:piwik.example.com\n        - traefik.docker.network=traefik\n        - traefik.port=80\n  cron:\n    image: piwik:apache\n    volumes:\n      - /var/data/piwik/config:/var/www/html/config\n    entrypoint: |\n      bash -c 'bash -s <<EOF\n      trap \"break;exit\" SIGHUP SIGINT SIGTERM\n      while /bin/true; do\n        su -s \"/bin/bash\" -c \"/usr/local/bin/php /var/www/html/console core:a\\\nrchive\" www-data\n        sleep 3600\n      done\n      EOF'\n    networks:\n    - internal\n\nnetworks:\n  traefik:\n    external: true\n  internal:\n    driver: overlay\n    ipam:\n      config:\n        - subnet: 172.16.4.0/24\n

\n\n\n\n\n Setup unique static subnets for every stack you deploy. This avoids IP/gateway conflicts which can otherwise occur when you’re creating/removing stacks a lot. See my list here.
\n

\n61.3 Serving

\n\n

Launch the Piwik stack by running docker stack deploy piwik -c <path -to-docker-compose.yml>

\n\n

Log into your new instance at https://YOUR-FQDN, and follow the wizard to complete the setup.

\n\n\n

hero: A recipe for a sexy view of your Docker Swarm

\n\n

\n62 Portainer

\n\n

Portainer is a lightweight sexy UI for visualizing your docker environment. It also happens to integrate well with Docker Swarm clusters, which makes it a great fit for our stack.

\n\n

\n\n\n

This is a “lightweight” recipe, because Portainer is so “lightweight”. But it is shiny…

\n\n

\n62.1 Ingredients

\n\n

\nDocker swarm cluster with persistent shared storage\n
\nTraefik configured per design
DNS entry for the hostname you intend to use, pointed to your keepalived IP

\n\n

\n62.2 Preparation

\n\n

\nSetup data locations

\n\n

Create a folder to store portainer’s persistent data:

\n\n\n

mkdir /var/data/portainer\n

\n\n\n\n\n

\nSetup Docker Swarm

\n\n

Create a docker swarm config file in docker-compose syntax (v3), something like this:

version: \"3\"\n\nservices:\n  app:\n    image: portainer/portainer\n    volumes:\n      - /var/run/docker.sock:/var/run/docker.sock\n      - /var/data/portainer:/data\n    networks:\n      - traefik_public\n    deploy:\n      labels:\n        - traefik.frontend.rule=Host:portainer.funkypenguin.co.nz\n        - traefik.port=9000\n      placement:\n        constraints: [node.role == manager]\n    command: -H unix:///var/run/docker.sock\n\nnetworks:\n  traefik_public:\n    external: true\n

\n\n\n\n\n

\n62.3 Serving

\n\n

\nLaunch Portainer stack

\n\n

Launch the Portainer stack by running docker stack deploy portainer -c <path -to-docker-compose.yml>

\n\n

Log into your new instance at https://YOUR-FQDN. You’ll be prompted to set your admin user/password.

\n\n

\n62.4 Chef’s Notes

\n\n

1. I wanted to use oauth2_proxy to provide an additional layer of security for Portainer, but the proxy seems to break the authentication mechanism, effectively making the stack so secure, that it can’t be logged into!

\n\n\n

\n63 Realms

\n\n

Realms is a git-based wiki (like Gollum, but with basic authentication and registration)

\n\n

\n\n\n

Features include:

\n\n

Built with Bootstrap 3.
Markdown (w/ HTML Support).
Syntax highlighting (Ace Editor).
Live preview.
Collaboration (TogetherJS / Firepad).
Drafts saved to local storage.
Handlebars for templates and logic.

\n\n In my limited trial, Realms seems less useful than Gollum for my particular use-case (i.e., you’re limited to markdown syntax only), but other users may enjoy the basic user authentication and registration features, which Gollum lacks.
\n Also of note is that the docker image is 1.17GB in size, and the handful of commits to the source GitHub repo in the past year has listed TravisCI build failures. This has many of the hallmarks of an abandoned project, to my mind.
\n

\n63.1 Ingredients

\n\n

\nDocker swarm cluster with persistent shared storage\n
\nTraefik configured per design
DNS entry for the hostname you intend to use, pointed to your keepalived IP

\n\n

\n63.2 Preparation

\n\n

\nSetup data locations

\n\n

Since we’ll start with a basic Realms install, let’s just create a single directory to hold the realms (SQLite) data:

\n\n\n

mkdir /var/data/realms/\n

\n\n\n\n\n

Create realms.env, and populate with the following variables (if you intend to use an oauth_proxy to double-secure your installation, which I recommend)

\n\n

OAUTH2_PROXY_CLIENT_ID=\nOAUTH2_PROXY_CLIENT_SECRET=\nOAUTH2_PROXY_COOKIE_SECRET=\n

\n\n\n\n\n

\nSetup Docker Swarm

\n\n

Create a docker swarm config file in docker-compose syntax (v3), something like this:

version: \"3\"\n\nservices:\n  realms:\n    image: realms/realms-wiki:latest\n    env_file: /var/data/config/realms/realms.env\n    volumes:\n      - /var/data/realms:/home/wiki/data\n    networks:\n      - internal\n\n  realms_proxy:\n    image: funkypenguin/oauth2_proxy:latest\n    env_file : /var/data/config/realms/realms.env\n    networks:\n      - internal\n      - traefik_public\n    deploy:\n      labels:\n        - traefik.frontend.rule=Host:realms.funkypenguin.co.nz\n        - traefik.docker.network=traefik_public\n        - traefik.port=4180\n    volumes:\n      - /var/data/config/realms/authenticated-emails.txt:/authenticated-email\\\ns.txt\n    command: |\n      -cookie-secure=false\n      -upstream=http://realms:5000\n      -redirect-url=https://realms.funkypenguin.co.nz\n      -http-address=http://0.0.0.0:4180\n      -email-domain=funkypenguin.co.nz\n      -provider=github\n      -authenticated-emails-file=/authenticated-emails.txt\n\nnetworks:\n  traefik_public:\n    external: true\n  internal:\n    driver: overlay\n    ipam:\n      config:\n        - subnet: 172.16.35.0/24\n

\n\n\n\n\n Setup unique static subnets for every stack you deploy. This avoids IP/gateway conflicts which can otherwise occur when you’re creating/removing stacks a lot. See my list here.
\n

\n63.3 Serving

\n\n

\nLaunch Realms stack

\n\n

Launch the Wekan stack by running docker stack deploy realms -c <path -to-docker-compose.yml>

\n\n

Log into your new instance at https://YOUR-FQDN, authenticate against oauth_proxy, and you’re immediately presented with Realms wiki, waiting for a fresh edit ;)

\n\n

\n63.4 Chef’s Notes

\n\n

If you wanted to expose the Realms UI directly, you could remove the oauth2_proxy from the design, and move the traefik_public-related labels directly to the realms container. You’d also need to add the traefik_public network to the realms container.
The inclusion of Realms was due to the efforts of @gkoerk in our Discord server. Thanks gkoerk!

\n\n\n

\n64 Tiny Tiny RSS

\n\n

Tiny Tiny RSS is a self-hosted, AJAX-based RSS reader, which rose to popularity as a replacement for Google Reader. It supports geeky advanced features, such as:

\n\n

Plugins and themeing in a drop-in fashion
Filtering (discard all articles with title matching “trump”)
Sharing articles via a unique public URL/feed

\n\n

\n\n\n

\n64.1 Ingredients

\n\n

\nDocker swarm cluster with persistent shared storage\n
\nTraefik configured per design

\n\n

\n64.2 Preparation

\n\n

\nSetup data locations

\n\n

We’ll need several directories to bind-mount into our container, so create them in /var/data/ttrss:

\n\n\n

mkdir /var/data/ttrss\ncd /var/data/ttrss\nmkdir -p {database,database-dump}\n

\n\n\n\n\n

\nPrepare environment

\n\n

Create ttrss.env, and populate with the following variables, customizing at least the database password (POSTGRES_PASSWORD and DB_PASS) and the TTRSS_SELF_URL to point to your installation.

\n\n\n

# Variables for postgres:latest\nPOSTGRES_USER=ttrss\nPOSTGRES_PASSWORD=mypassword\nDB_EXTENSION=pg_trgm\n\n# Variables for pg_dump running in postgres/latest (used for db-backup)\nPGUSER=ttrss\nPGPASSWORD=mypassword\nPGHOST=db\nBACKUP_NUM_KEEP=3\nBACKUP_FREQUENCY=1d\n\n# Variables for funkypenguin/docker-ttrss\nDB_USER=ttrss\nDB_PASS=mypassword\nDB_PORT=5432\nDB_PORT_5432_TCP_ADDR=db\nDB_PORT_5432_TCP_PORT=5432\nTTRSS_SELF_URL=https://ttrss.example.com\nTTRSS_REPO=https://github.com/funkypenguin/tt-rss.git\nS6_BEHAVIOUR_IF_STAGE2_FAILS=2\n

\n\n\n\n\n

\nSetup docker swarm

\n\n

Create a docker swarm config file in docker-compose syntax (v3), something like this:

version: '3'\n\nservices:\n    db:\n      image: postgres:latest\n      env_file: /var/data/ttrss/ttrss.env\n      volumes:\n        - /var/data/ttrss/database:/var/lib/postgresql/data\n      networks:\n        - internal\n\n    app:\n      image: funkypenguin/docker-ttrss\n      env_file: /var/data/ttrss/ttrss.env\n      deploy:\n        labels:\n          - traefik.frontend.rule=Host:ttrss.funkypenguin.co.nz\n          - traefik.docker.network=traefik\n          - traefik.port=8080\n      networks:\n        - internal\n        - traefik\n\n    db-backup:\n      image: postgres:latest\n      env_file: /var/data/ttrss/ttrss.env\n      volumes:\n        - /var/data/ttrss/database-dump:/dump\n        - /etc/localtime:/etc/localtime:ro\n      entrypoint: |\n        bash -c 'bash -s <<EOF\n        trap \"break;exit\" SIGHUP SIGINT SIGTERM\n        sleep 2m\n        while /bin/true; do\n          pg_dump -Fc > /dump/dump_\\`date +%d-%m-%Y\"_\"%H_%M_%S\\`.psql\n          (ls -t /dump/dump*.psql|head -n $$BACKUP_NUM_KEEP;ls /dump/dump*.ps\\\nql)|sort|uniq -u|xargs rm -- {}\n          sleep $$BACKUP_FREQUENCY\n        done\n        EOF'\n      networks:\n      - internal\n\nnetworks:\n  traefik:\n    external: true\n  internal:\n    driver: overlay\n    ipam:\n      config:\n        - subnet: 172.16.5.0/24\n

\n\n\n\n\n Setup unique static subnets for every stack you deploy. This avoids IP/gateway conflicts which can otherwise occur when you’re creating/removing stacks a lot. See my list here.
\n

\n64.3 Serving

\n\n

\nLaunch TTRSS stack

\n\n

Launch the TTRSS stack by running docker stack deploy ttrss -c <path -to-docker-compose.yml>

\n\n

Log into your new instance at https://YOUR-FQDN - the first user you create will be an administrative user.

\n\n

\n64.4 Chef’s Notes

\n\n

There are several TTRSS containers available on docker hub, none of them “official”. I chose x86dev’s container for its features - such as my favorite skins and plugins, and the daily automatic updates from the “rolling release” master. Some of the features of the container I use are due to a PR I submitted:

\n\n

Docker swarm looses the docker-compose concept of “dependencies” between containers. In the case of this stack, the application server typically starts up before the database container, which causes the database autoconfiguration scripts to fail, and brings up the app in a broken state. To prevent this, I include “wait-for”, which (combined with “S6_BEHAVIOUR_IF_STAGE2_FAILS=2”), will cause the app container to restart (and attempt to auto-configure itself) until the database is ready.
The upstream git URL changed recently, but my experience of the new repository is that it’s SO slow, that the initial “git clone” on setup of the container times out. To work around this, I created my own repo, cloned upstream, pushed it into my repo, and pointed the container at my own repo with TTRSS_REPO. I don’t get the latest code changes, but at least the app container starts up. When upstream git is performing properly, I’ll remove TTRSS_REPO to revert back to the “rolling release”.

\n\n\n

hero: Read-it-later, mate!

\n\n

\n65 Wallabag

\n\n

Wallabag is a self-hosted webapp which allows you to save URLs to “read later”, similar to Instapaper or Pocket. Like Instapaper (but not Pocket, sadly), Wallabag allows you to annotate any pages you grab for your own reference.

\n\n

All saved data (pages, annotations, images, tags, etc) are stored on your own server, and can be shared/exported in a variety of formats, including ePub and PDF.

\n\n

\n\n\n

There are plugins for Chrome and Firefox, as well as apps for iOS, Android, etc. Wallabag will also integrate nicely with my favorite RSS reader, Miniflux (for which there is an existing recipe).

\n\n

Here’s a video which shows off the UI a bit more.

\n\n

\n65.1 Ingredients

\n\n

\nDocker swarm cluster with persistent shared storage\n
\nTraefik configured per design
DNS entry for the hostname you intend to use, pointed to your keepalived IP

\n\n

\n65.2 Preparation

\n\n

\nSetup data locations

\n\n

We need a filesystem location to store images that Wallabag downloads from the original sources, to re-display when you read your articles, as well as nightly database dumps (which you should backup), so create something like this:

\n\n\n

mkdir -p /var/data/wallabag\ncd /var/data/wallabag\nmkdir -p {images,db-dump}\n

\n\n\n\n\n

\nPrepare environment

\n\n

Create wallabag.env, and populate with the following variables. The only variable you have to change is SYMFONY__ENV__DOMAIN_NAME - this must be the URL that your Wallabag instance will be available at (else you’ll have no CSS)

\n\n

# For the DB container\nPOSTGRES_PASSWORD=wallabag\nPOSTGRES_USER=wallabag\n\n# For the wallabag container\nSYMFONY__ENV__DATABASE_DRIVER=pdo_pgsql\nSYMFONY__ENV__DATABASE_HOST=db\nSYMFONY__ENV__DATABASE_PORT=5432\nSYMFONY__ENV__DATABASE_NAME=wallabag\nSYMFONY__ENV__DATABASE_USER=wallabag\nSYMFONY__ENV__DATABASE_PASSWORD=wallabag\nSYMFONY__ENV__DOMAIN_NAME=https://wallabag.example.com\nSYMFONY__ENV__DATABASE_DRIVER_CLASS=Wallabag\\CoreBundle\\Doctrine\\DBAL\\Driver\\\\\nCustomPostgreSQLDriver\nSYMFONY__ENV__MAILER_HOST=127.0.0.1\nSYMFONY__ENV__MAILER_USER=~\nSYMFONY__ENV__MAILER_PASSWORD=~\nSYMFONY__ENV__FROM_EMAIL=wallabag@example.com\nSYMFONY__ENV__FOSUSER_REGISTRATION=false\n\n\n# If you decide to protect wallabag with an oauth_proxy, complete these\nOAUTH2_PROXY_CLIENT_ID=\nOAUTH2_PROXY_CLIENT_SECRET=\nOAUTH2_PROXY_COOKIE_SECRET=\n

\n\n\n\n\n

Now create wallabag-backup.env in the same folder, with the following contents. (This is necessary to prevent environment variables required for backup from breaking the DB container)

\n\n\n

# For database backups\nPGUSER=wallabag\nPGPASSWORD=wallabag\nPGHOST=db\nBACKUP_NUM_KEEP=7\nBACKUP_FREQUENCY=1d\n

\n\n\n\n\n

\nSetup Docker Swarm

\n\n

Create a docker swarm config file in docker-compose syntax (v3), something like this:

version: '3'\nservices:\n\n  wallabag:\n    image: wallabag/wallabag\n    env_file: /var/data/config/wallabag/wallabag.env\n    networks:\n      - internal\n    volumes:\n      - /var/data/wallabag/images:/var/www/wallabag/web/assets/images\n\n  wallabag_proxy:\n   image: a5huynh/oauth2_proxy\n   env_file: /var/data/config/wallabag/wallabag.env\n   networks:\n     - internal\n     - traefik_public\n   deploy:\n     labels:\n       - traefik.frontend.rule=Host:wallabag.example.com\n       - traefik.docker.network=traefik_public\n       - traefik.port=4180\n   volumes:\n     - /var/data/config/wallabag/authenticated-emails.txt:/authenticated-emai\\\nls.txt\n   command: |\n     -cookie-secure=false\n     -upstream=http://wallabag:80\n     -redirect-url=https://wallabag.example.com\n     -http-address=http://0.0.0.0:4180\n     -email-domain=example.com\n     -provider=github\n     -authenticated-emails-file=/authenticated-emails.txt\n\n  db:\n    image: postgres\n    env_file: /var/data/config/wallabag/wallabag.env\n    dns_search:\n      - hq.example.com\n    volumes:\n      - /var/data/runtime/wallabag/data:/var/lib/postgresql/data\n    networks:\n      - internal\n\n  db-backup:\n    image: postgres:latest\n    env_file: /var/data/config/wallabag/wallabag-backup.env\n    volumes:\n      - /var/data/wallabag/database-dump:/dump\n      - /etc/localtime:/etc/localtime:ro\n    entrypoint: |\n      bash -c 'bash -s <<EOF\n      trap \"break;exit\" SIGHUP SIGINT SIGTERM\n      sleep 2m\n      while /bin/true; do\n        pg_dump -Fc > /dump/dump_\\`date +%d-%m-%Y\"_\"%H_%M_%S\\`.psql\n        (ls -t /dump/dump*.psql|head -n $$BACKUP_NUM_KEEP;ls /dump/dump*.psql\\\n)|sort|uniq -u|xargs rm -- {}\n        sleep $$BACKUP_FREQUENCY\n      done\n      EOF'\n    networks:\n    - internal\n\n  redis:\n    image: redis:alpine\n    networks:\n      - internal\n\n  import-instapaper:\n    image: wallabag/wallabag\n    env_file: /var/data/config/wallabag/wallabag.env\n    networks:\n      - internal\n    command: |\n      import instapaper\n\n  import-pocket:\n    image: wallabag/wallabag\n    env_file: /var/data/config/wallabag/wallabag.env\n    networks:\n      - internal\n    command: |\n      import pocket\n\nnetworks:\n  traefik_public:\n    external: true\n  internal:\n    driver: overlay\n    ipam:\n      config:\n        - subnet: 172.16.21.0/24\n

\n\n\n\n\n Setup unique static subnets for every stack you deploy. This avoids IP/gateway conflicts which can otherwise occur when you’re creating/removing stacks a lot. See my list here.
\n

\n65.3 Serving

\n\n

\nLaunch Wallabag stack

\n\n

Launch the Wallabag stack by running docker stack deploy wallabag -c <path -to-docker-compose.yml>

\n\n

Log into your new instance at https://YOUR-FQDN, with user “wallabag” and default password “wallabag”.

\n\n

\nEnable asynchronous imports

\n\n

You’ll have noticed redis, plus the pocket/instapaper-importing containers included in the .yml above. Redis is there to allow asynchronous imports, and pocket and instapaper are there since they’re likely the most popular platform you’d want to import from. Other possibilities (you’ll need to adjust the .yml) are readability, firefox, chrome, and wallabag_v1 and wallabag_v2.

\n\n

Even with all these elements in place, you still need to enable Redis under Internal Settings -> Import, via the admin user in the webUI. Here’s a screenshot to help you find it:

\n\n

\n\n\n

\n65.4 Chef’s Notes

\n\n

If you wanted to expose the Wallabag UI directly (required for the iOS/Android apps), you could remove the oauth2_proxy from the design, and move the traefik-related labels directly to the wallabag container. You’d also need to add the traefik_public network to the wallabag container. I found the iOS app to be unreliable and clunky, so elected to leave my oauth_proxy enabled, and to simply use the webUI on my mobile devices instead. YMMMV.
I’ve not tested the email integration, but you’d need an SMTP server listening on port 25 (since we can’t change the port) to use it

\n\n\n

\n66 Wekan

\n\n

Wekan is an open-source kanban board which allows a card-based task and to-do management, similar to tools like WorkFlowy or Trello.

\n\n

\n\n\n

Wekan allows to create Boards, on which Cards can be moved around between a number of Columns. Boards can have many members, allowing for easy collaboration, just add everyone that should be able to work with you on the board to it, and you are good to go! You can assign colored Labels to cards to facilitate grouping and filtering, additionally you can add members to a card, for example to assign a task to someone.

\n\n

There’s a video of the developer showing off the app, as well as a functional demo.

\n\n For added privacy, this design secures wekan behind an oauth2 proxy, so that in order to gain access to the wekan UI at all, oauth2 authentication (to GitHub, GitLab, Google, etc) must have already occurred.
\n

\n66.1 Ingredients

\n\n

\nDocker swarm cluster with persistent shared storage\n
\nTraefik configured per design

\n\n

\n66.2 Preparation

\n\n

\nSetup data locations

\n\n

We’ll need several directories to bind-mount into our container, so create them in /var/data/wekan:

\n\n\n

mkdir /var/data/wekan\ncd /var/data/wekan\nmkdir -p {wekan-db,wekan-db-dump}\n

\n\n\n\n\n

\nPrepare environment

\n\n

You’ll need to know the following:

\n\n

Choose an oauth provider, and obtain a client ID and secret
Create wekan.env, and populate with the following variables

\n\n\n

OAUTH2_PROXY_CLIENT_ID=\nOAUTH2_PROXY_CLIENT_SECRET=\nOAUTH2_PROXY_COOKIE_SECRET=\nMONGO_URL=mongodb://wekandb:27017/wekan\nROOT_URL=https://wekan.example.com\nMAIL_URL=smtp://wekan@wekan.example.com:password@mail.example.com:587/\nMAIL_FROM=\"Wekan <wekan@wekan.example.com>\"\n\n# Mongodb specific database dump details\nBACKUP_NUM_KEEP=7\nBACKUP_FREQUENCY=1d\n

\n\n\n\n\n

\nSetup Docker Swarm

\n\n

Create a docker swarm config file in docker-compose syntax (v3), something like this:

version: '3'\n\nservices:\n\n  wekandb:\n    image: mongo:latest\n    command: mongod --smallfiles --oplogSize 128\n    networks:\n      - internal\n    volumes:\n      - /var/data/runtime/wekan/database:/data/db\n      - /var/data/wekan/database-dump:/dump\n\n  proxy:\n    image: a5huynh/oauth2_proxy\n    env_file: /var/data/config/wekan/wekan.env\n    networks:\n      - traefik\n      - internal\n    volumes:\n      - /var/data/oauth_proxy/authenticated-emails.txt:/authenticated-emails.\\\ntxt\n    deploy:\n      labels:\n        - traefik.frontend.rule=Host:wekan.example.com\n        - traefik.docker.network=traefik\n        - traefik.port=4180\n    command: |\n      -cookie-secure=false\n      -upstream=http://wekan:80\n      -redirect-url=https://wekan.example.com\n      -http-address=http://0.0.0.0:4180\n      -email-domain=example.com\n      -provider=github\n      -authenticated-emails-file=/authenticated-emails.txt\n\n  wekan:\n    image: wekanteam/wekan:latest\n    networks:\n      - internal\n    env_file: /var/data/config/wekan/wekan.env\n\n  db-backup:\n    image: mongo:latest\n    env_file : /var/data/config/wekan/wekan.env\n    volumes:\n      - /var/data/wekan/database-dump:/dump\n      - /etc/localtime:/etc/localtime:ro\n    entrypoint: |\n      bash -c 'bash -s <<EOF\n      trap \"break;exit\" SIGHUP SIGINT SIGTERM\n      sleep 2m\n      while /bin/true; do\n        mongodump -h db --gzip --archive=/dump/dump_\\`date +%d-%m-%Y\"_\"%H_%M_\\\n%S\\`.mongo.gz\n        (ls -t /dump/dump*.mongo.gz|head -n $$BACKUP_NUM_KEEP;ls /dump/dump*.\\\nmongo.gz)|sort|uniq -u|xargs rm -- {}\n        sleep $$BACKUP_FREQUENCY\n      done\n      EOF'\n    networks:\n    - internal    \n\nnetworks:\n  traefik:\n    external: true\n  internal:\n    driver: overlay\n    ipam:\n      config:\n        - subnet: 172.16.3.0/24\n

\n\n\n\n\n Setup unique static subnets for every stack you deploy. This avoids IP/gateway conflicts which can otherwise occur when you’re creating/removing stacks a lot. See my list here.
\n

\n66.3 Serving

\n\n

\nLaunch Wekan stack

\n\n

Launch the Wekan stack by running docker stack deploy wekan -c <path -to-docker-compose.yml>

\n\n

Log into your new instance at https://YOUR-FQDN, with user “root” and the password you specified in gitlab.env.

\n\n

\n66.4 Chef’s Notes

\n\n

1. If you wanted to expose the Wekan UI directly, you could remove the oauth2_proxy from the design, and move the traefik-related labels directly to the wekan container. You’d also need to add the traefik network to the wekan container.

\n\n\n

hero: Terminal in a browser, baby!

\n\n

\n67 Wetty

\n\n

Wetty is a responsive, modern terminal, in your web browser. Yes, your browser. When combined with secure authentication and SSL encryption, it becomes a useful tool for quick and easy remote access.

\n\n

\n\n\n

\n67.1 Why would you need SSH in a browser window?

\n\n

Need shell access to a node with no external access? Deploy Wetty behind an oauth_proxy with a SSL-terminating reverse proxy (traefik), and suddenly you have the means to SSH to your private host from any web browser (protected by your oauth_proxy of course, and your OAuth provider’s 2FA)

\n\n

Here are some other possible use cases:

\n\n

Access to SSH / CLI from an environment where outgoing SSH is locked down, or SSH client isn’t / can’t be installed. (i.e., a corporate network)
Access to long-running processes inside a tmux session (like irrsi)
Remote access to a VM / container running Kali linux, for penetration testing

\n\n

\n67.2 Ingredients

\n\n

\nDocker swarm cluster with persistent shared storage\n
\nTraefik configured per design
DNS entry for the hostname you intend to use, pointed to your keepalived IP

\n\n

\n67.3 Preparation

\n\n

\nPrepare environment

\n\n

Create wetty.env, and populate with the following variables per the oauth_proxy instructions:

\n\n

OAUTH2_PROXY_CLIENT_ID=\nOAUTH2_PROXY_CLIENT_SECRET=\nOAUTH2_PROXY_COOKIE_SECRET=\n\n# To use WeTTY to SSH to a host besides the (mostly useless) alpine container\\\n it comes with\nSSHHOST=batcomputer.batcave.com\nSSHUSER=batman\n

\n\n\n\n\n

\nSetup Docker Swarm

\n\n

Create a docker swarm config file in docker-compose syntax (v3), something like this:

version: \"3\"\nservices:\n  wetty:\n    image: krishnasrinivas/wetty\n    env_file : /var/data/config/wetty/wetty.env\n    networks:\n        - internal\n  proxy:\n    image: funkypenguin/oauth2_proxy:latest\n    env_file: /var/data/config/wetty/wetty.env\n    networks:\n      - internal\n      - traefik_public\n    deploy:\n      labels:\n        - traefik.frontend.rule=Host:wetty.funkypenguin.co.nz\n        - traefik.docker.network=traefik_public\n        - traefik.port=4180\n    volumes:\n      - /etc/localtime:/etc/localtime:ro\n      - /var/data/config/wetty/authenticated-emails.txt:/authenticated-emails\\\n.txt\n    command: |\n      -cookie-secure=false\n      -upstream=http://wetty:3000\n      -redirect-url=https://wetty.funkypenguin.co.nz\n      -http-address=http://0.0.0.0:4180\n      -provider=github\n      -authenticated-emails-file=/authenticated-emails.txt\n\nnetworks:\n  traefik_public:\n    external: true\n  internal:\n    driver: overlay\n    ipam:\n      config:\n        - subnet: 172.16.45.0/24\n

\n\n\n\n\n Setup unique static subnets for every stack you deploy. This avoids IP/gateway conflicts which can otherwise occur when you’re creating/removing stacks a lot. See my list here.
\n

\n67.4 Serving

\n\n

\nLaunch Wetty stack

\n\n

Launch the Wetty stack by running docker stack deploy wetty -c <path -to-docker-compose.yml>

\n\n

Browse to your new browser-cli-terminal at https://YOUR-FQDN. Authenticate with your OAuth provider, and then proceed to login, either to the remote host you specified (batcomputer.batcave.com, in the example above), or using user and password “term” to log directly into the Wetty alpine container (from which you can establish egress SSH)

\n\n

\n67.5 Chef’s Notes

\n\n

You could set SSHHOST to the IP of the “docker0” interface on your host, which is normally 172.17.0.1. (Or run /sbin/ip route|awk '/default/ { print $3 }' in the container) This would then provide you the ability to remote-manage your swarm with only web access to Wetty.
The inclusion of Wetty was due to the efforts of @gpulido in our Discord server. Thanks Gabriel!

\n\n\n

\nIV Reference

\n\n

Now follows useful elements which are not full recipes.

\n\n\n

\n68 OAuth proxy

\n\n

Some of the platforms we use on our swarm may have strong, proven security to prevent abuse. Techniques such as rate-limiting (to defeat brute force attacks) or even support 2-factor authentication (tiny-tiny-rss or Wallabag support this).

\n\n

Other platforms may provide no authentication (Traefik’s web UI for example), or minimal, un-proven UI authentication which may have been added as an afterthought.

\n\n

Still platforms may hold such sensitive data (i.e., NextCloud), that we’ll feel more secure by putting an additional authentication layer in front of them.

\n\n

This is the role of the OAuth proxy.

\n\n

\n68.1 How does it work?

\n\n

Normally, Traefik proxies web requests directly to individual web apps running in containers. The user talks directly to the webapp, and the webapp is responsible for ensuring appropriate authentication.

\n\n

When employing the OAuth proxy , the proxy sits in the middle of this transaction - traefik sends the web client to the OAuth proxy, the proxy authenticates the user against a 3rd-party source (GitHub, Google, etc), and then passes authenticated requests on to the web app in the container.

\n\n

Illustrated below:

\n\n\n

The advantage under this design is additional security. If I’m deploying a web app which I expect only myself to require access to, I’ll put the oauth_proxy in front of it. The overhead is negligible, and the additional layer of security is well-worth it.

\n\n

\n68.2 Ingredients

\n\n

\n68.3 Preparation

\n\n

\nOAuth provider

\n\n

OAuth Proxy currently supports the following OAuth providers:

\n\n

Google (default)
Azure
Facebook
GitHub
GitLab
LinkedIn
MyUSA

\n\n

Follow the instructions to setup your oauth provider. You need to setup a unique key/secret for each instance of the proxy you want to run, since in each case the callback URL will differ.

\n\n

\nAuthorized emails file

\n\n

There are a variety of options with oauth_proxy re which email addresses (authenticated against your oauth provider) should be permitted access. You can permit access based on email domain (*@gmail.com), individual email address (batman@gmail.com), or based on provider-specific groups (i.e., a GitHub organization)

\n\n

The most restrictive configuration allows access on a per-email address basis, which is illustrated below:

\n\n

I created /var/data/oauth_proxy/authenticated-emails.txt, and add my own email address to the first line.

\n\n

\nConfigure stack

\n\n

You’ll need to define a service for the oauth_proxy in every stack which you want to protect. Here’s an example from the Wekan recipe:

\n\n\n

proxy:\n  image: a5huynh/oauth2_proxy\n  env_file : /var/data/wekan/wekan.env\n  networks:\n    - traefik\n    - internal\n  deploy:\n    labels:\n      - traefik.frontend.rule=Host:wekan.funkypenguin.co.nz\n      - traefik.docker.network=traefik\n      - traefik.port=4180\n  volumes:\n    - /var/data/oauth_proxy/authenticated-emails.txt:/authenticated-emails.txt\n  command: |\n    -cookie-secure=false\n    -upstream=http://wekan:80\n    -redirect-url=https://wekan.funkypenguin.co.nz\n    -http-address=http://0.0.0.0:4180\n    -email-domain=funkypenguin.co.nz\n    -provider=github\n    -authenticated-emails-file=/authenticated-emails.txt\n

\n\n\n\n\n

Note above how:

Labels are required to tell Traefik to forward the traffic to the proxy, rather than the backend container running the app
An environment file is defined, but..
The redirect URL must still be passed to the oauth_proxy in the command argument

\n\n\n

\n69 Data layout

\n\n

The applications deployed in the stack utilize a combination of data-at-rest (static config, files, etc) and runtime data (live database files). The realtime data can’t be backed up with a simple copy-paste, so where we employ databases, we also include containers to perform a regular export of database data to a filesystem location.

\n\n

So that we can confidently backup all our data, I’ve setup a data layout as follows:

\n\n

\n69.1 Configuration data

\n\n

Configuration data goes into /var/data/config/[recipe name], and is typically only a docker-compose .yml, and a .env file

\n\n

\n69.2 Runtime data

\n\n

Realtime data (typically database files or files-in-use) are stored in /var/data/realtime/[recipe-name], and are excluded from backup (They change constantly, and cannot be safely restored).

\n\n

\n69.3 Static data

\n\n

Static data goes into /var/data/[recipe name], and includes anything that can be safely backed up while a container is running. This includes database exports of the runtime data above.

\n\n\n

\n70 Networks

\n\n

In order to avoid IP addressing conflicts as we bring swarm networks up/down, we will statically address each docker overlay network, and record the details below:

\n\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n\n

Network	Range
Traefik	unspecified
Docker-cleanup	172.16.0.0/24
Mail Server	172.16.1.0/24
Gitlab	172.16.2.0/24
Wekan	172.16.3.0/24
Piwik	172.16.4.0/24
Tiny Tiny RSS	172.16.5.0/24
Huginn	172.16.6.0/24
Unifi	172.16.7.0/24
Kanboard	172.16.8.0/24
Gollum	172.16.9.0/24
Duplicity	172.16.10.0/24
Autopirate	172.16.11.0/24
Nextcloud	172.16.12.0/24
Portainer	172.16.13.0/24
Home-Assistant	172.16.14.0/24
OwnTracks	172.16.15.0/24
Plex	172.16.16.0/24
Emby	172.16.17.0/24
Calibre-Web	172.16.18.0/24
Wallabag	172.16.19.0/24
InstaPy	172.16.20.0/24
Turtle Pool	172.16.21.0/24
MiniFlux	172.16.22.0/24
Gitlab Runner	172.16.23.0/24
Munin	172.16.24.0/24
Bookstack	172.16.33.0/24
Swarmprom	172.16.34.0/24
Realms	172.16.35.0/24
ElkarBackup	172.16.36.0/24
Mayan EDMS	172.16.37.0/24
Shaarli	172.16.38.0/24
OpenLDAP	172.16.39.0/24
MatterMost	172.16.40.0/24
PrivateBin	172.16.41.0/24
Mayan EDMS	172.16.42.0/24
Hack MD	172.16.43.0/24
FlightAirMap	172.16.44.0/24
Wetty	172.16.45.0/24
FileBrowser	172.16.46.0/24
phpIPAM	172.16.47.0/24
Dozzle	172.16.48.0/24
KeyCloak	172.16.49.0/24
Sensu	172.16.50.0/24
Magento	172.16.51.0/24
Graylog	172.16.52.0/24
Harbor	172.16.53.0/24
Harbor-Clair	172.16.54.0/24

\n\n\n

\n71 Introduction

\n\n

Our HA platform design relies on Atomic OS, which only contains bare minimum elements to run containers.

\n\n

So how can we use git on this system, to push/pull the changes we make to config files? With a container, of course!

\n\n

\n71.1 git-docker

\n\n

I made a simple container which just basically executes git in the CWD:

\n\n

To use it transparently, add an alias for the “git” command, or just download it with the rest of the handy aliases:

\n\n\n

alias git='docker run -v $PWD:/var/data -v \\\n/var/data/git-docker/data/.ssh:/root/.ssh funkypenguin/git-docker git'\n

\n\n\n\n\n

\n71.2 Setup SSH key

\n\n

If you plan to actually push using git, you’ll need to setup an SSH keypair. You could copy across whatever keypair you currently use, but it’s probably more appropriate to generate a specific keypair for this purpose.

\n\n

Generate your new SSH keypair by running:

\n\n\n

mkdir -p /var/data/git-docker/data/.ssh\nchmod 600 /var/data/git-docker/data/.ssh\ndocker run -v /var/data/git-docker/data/.ssh:/root/.ssh funkypenguin/git-dock\\\ner ssh-keygen -t ed25519 -f /root/.ssh/id_ed25519\n

\n\n\n\n\n

The output will look something like this:

\n\n

Generating public/private ed25519 key pair.\nEnter passphrase (empty for no passphrase): Enter same passphrase again: Crea\\\nted directory '/root/.ssh'.\nYour identification has been saved in /root/.ssh/id_ed25519.\nYour public key has been saved in /root/.ssh/id_ed25519.pub.\nThe key fingerprint is:\nSHA256:uZtriS7ypx7Q4kr+w++nHhHpcRfpf5MhxP3Wpx3H3hk root@a230749d8d8a\nThe key's randomart image is:\n+--[ED25519 256]--+\n|         .o .    |\n|      .  ..o .   |\n|     + ....   ...|\n|   .. + .o . . E=|\n|  o .o  S . . ++B|\n| . o  .  . . +..+|\n| .o .. ...  . .  |\n|o..o..+.oo       |\n|...=OX+.+.       |\n+----[SHA256]-----+\n

\n\n\n\n\n

Now add the contents of /var/data/git-docker/data/.ssh/id_ed25519.pub to your git account, and off you go - just run “git” from your Atomic host as usual, and pretend that you have the client installed!

\n\n\n

\n72 OpenVPN

\n\n

Sometimes you need an OpenVPN tunnel between your docker hosts and some other environment. I needed this to provide connectivity between swarm-deployed services like Home Assistant, and my IOT devices within my home LAN.

\n\n

OpenVPN is one application which doesn’t really work in a swarm-type deployment, since each host will typically require a unique certificate/key to connect to the VPN anyway.

\n\n

In my case, I needed each docker node to connect via OpenVPN back to a pfsense instance, but there were a few gotchas related to OpenVPN at CentOS Atomic which I needed to address first.

\n\n

\n72.1 SELinux for OpenVPN

\n\n

Yes, SELinux. Install a custom policy permitting a docker container to create tun interfaces, like this:

\n\n\n

cat << EOF > docker-openvpn.te\nmodule docker-openvpn 1.0;\n\nrequire {\n\ttype svirt_lxc_net_t;\n\tclass tun_socket create;\n}\n\n#============= svirt_lxc_net_t ==============\nallow svirt_lxc_net_t self:tun_socket create;\n\nEOF\n\ncheckmodule -M -m -o docker-openvpn.mod docker-openvpn.te\nsemodule_package -o docker-openvpn.pp -m docker-openvpn.mod\nsemodule -i docker-openvpn.pp\n

\n\n\n\n\n

\n72.2 Insert the tun module

\n\n

Even with the SELinux policy above, I still need to insert the “tun” module into the running kernel at the host-level, before a docker container can use it to create a tun interface.

\n\n

Run the following to auto-insert the tun module on boot:

\n\n\n

cat << EOF >> /etc/rc.d/rc.local\n# Insert the \"tun\" module so that the vpn-client container can access /dev/ne\\\nt/tun\n/sbin/modprobe tun\nEOF\nchmod 755 /etc/rc.d/rc.local\n

\n\n\n\n\n

\n72.3 Connect the VPN

\n\n

Finally, for each node, I exported client credentials, and SCP’d them over to the docker node, into /root/my-vpn-configs-here/. I also had to use the NET_ADMIN cap-add parameter, as illustrated below:

\n\n\n

docker run -d --name vpn-client \\\n  --restart=always --cap-add=NET_ADMIN --net=host \\\n  --device /dev/net/tun \\\n  -v /root/my-vpn-configs-here:/vpn:z \\\n  ekristen/openvpn-client --config /vpn/my-host-config.ovpn\n

\n\n\n\n\n

Now every time my node boots, it establishes a VPN tunnel back to my pfsense host and (by using custom configuration directives in OpenVPN) is assigned a static VPN IP.

\n\n\n

\n73 Troubleshooting

\n\n

Having difficulty with a recipe? Here are some tips..

\n\n

\n73.1 Why is my stack not launching?

\n\n

Run docker stack ps <stack name> --no-trunc for more details on why individual containers failed to launching

\n\n

\n73.2 Attaching to running container

\n\n

Need to debug why your oauth2_proxy container can’t talk to its upstream app? Start by identifying which node the proxy container is running on, using docker ps <stack name>.

\n\n

SSH to the host node, and attach to the container using docker exec -it <continer id> /bin/bash (substitute /bin/ash for /bin/bash, in the case of an Alpine container), and then try to telnet to your upstream host.

\n\n

\n73.3 Watching logs of container

\n\n

Need to see what a particular container is doing? Run docker service logs -f <stack name>_<container name> to watch a particular service. As the service dies and is recreated, the logs will continue to be displayed.

\n\n

\n73.4 Visually monitoring containers with ctop

\n\n

For a visual “top-like” display of your container’s activity (as well as a detailed per-container view), try using ctop.

\n\n

To execute, simply run docker run --rm -ti --name ctop -v /var/run/docker.sock:/var/run/docker.sock quay.io/vektorlab/ctop:latest

\n\n

Example:

\nNotes

HA Docker Swarm

Design

1Minimum Viable Cluster acronym copyright, trademark, and whatever else, to Funky Penguin for 1,000,000 years.↩

\n\n

Shared Storage (Ceph)

1Minimum Viable Cluster acronym copyright, trademark, and whatever else, to Funky Penguin for 1,000,000 years.↩

\n\n\n

\n\n

\n\n","tocStructure",[486,487,488,489,490,491,492,493,494,495,496,497,498,499,500,501,502,503,504,505,506,507,508,509,510,511,512,513,514,515,516,517,518,519,520,521,522,523,524,525,526,527,528,529,530,531,532,533,534,535,536,537,538,539,540,541,542,543,544,545,546,547,548,549,550,551,552,553,554,555,556,557,558,559,560,561,562,563,564],{"_79":73,"_43":70,"_71":-5,"_74":75,"_72":73,"_395":-5,"_396":-5,"_83":-5},{"_79":80,"_43":70,"_71":-5,"_74":75,"_72":73,"_395":-5,"_396":-5,"_83":-5},{"_79":80,"_43":85,"_71":-5,"_74":86,"_72":73,"_395":-5,"_396":-5,"_83":-5},{"_79":80,"_43":89,"_71":-5,"_74":90,"_72":73,"_395":-5,"_396":-5,"_83":-5},{"_79":80,"_43":93,"_71":-5,"_74":94,"_72":73,"_395":-5,"_396":-5,"_83":-5},{"_79":73,"_43":97,"_71":-5,"_74":98,"_72":73,"_395":-5,"_396":-5,"_83":-5},{"_79":80,"_43":101,"_71":-5,"_74":102,"_72":73,"_395":-5,"_396":-5,"_83":-5},{"_79":80,"_43":105,"_71":-5,"_74":106,"_72":73,"_395":-5,"_396":-5,"_83":-5},{"_79":80,"_43":109,"_71":-5,"_74":110,"_72":73,"_395":-5,"_396":-5,"_83":-5},{"_79":80,"_43":113,"_71":-5,"_74":114,"_72":73,"_395":-5,"_396":-5,"_83":-5},{"_79":80,"_43":117,"_71":-5,"_74":118,"_72":73,"_395":-5,"_396":-5,"_83":-5},{"_79":80,"_43":121,"_71":-5,"_74":122,"_72":73,"_395":-5,"_396":-5,"_83":-5},{"_79":80,"_43":125,"_71":-5,"_74":126,"_72":73,"_395":-5,"_396":-5,"_83":-5},{"_79":80,"_43":129,"_71":-5,"_74":130,"_72":73,"_395":-5,"_396":-5,"_83":-5},{"_79":80,"_43":133,"_71":-5,"_74":134,"_72":73,"_395":-5,"_396":-5,"_83":-5},{"_79":80,"_43":137,"_71":-5,"_74":138,"_72":73,"_395":-5,"_396":-5,"_83":-5},{"_79":73,"_43":141,"_71":-5,"_74":142,"_72":73,"_395":-5,"_396":-5,"_83":-5},{"_79":80,"_43":145,"_71":-5,"_74":146,"_72":73,"_395":-5,"_396":-5,"_83":-5},{"_79":80,"_43":149,"_71":-5,"_74":150,"_72":73,"_395":-5,"_396":-5,"_83":-5},{"_79":80,"_43":153,"_71":-5,"_74":154,"_72":73,"_395":-5,"_396":-5,"_83":-5},{"_79":80,"_43":157,"_71":-5,"_74":158,"_72":73,"_395":-5,"_396":-5,"_83":-5},{"_79":80,"_43":161,"_71":-5,"_74":162,"_72":73,"_395":-5,"_396":-5,"_83":-5},{"_79":80,"_43":165,"_71":-5,"_74":166,"_72":73,"_395":-5,"_396":-5,"_83":-5},{"_79":80,"_43":169,"_71":-5,"_74":170,"_72":73,"_395":-5,"_396":-5,"_83":-5},{"_79":80,"_43":173,"_71":-5,"_74":174,"_72":73,"_395":-5,"_396":-5,"_83":-5},{"_79":80,"_43":177,"_71":-5,"_74":178,"_72":73,"_395":-5,"_396":-5,"_83":-5},{"_79":80,"_43":181,"_71":-5,"_74":182,"_72":73,"_395":-5,"_396":-5,"_83":-5},{"_79":80,"_43":185,"_71":-5,"_74":186,"_72":73,"_395":-5,"_396":-5,"_83":-5},{"_79":80,"_43":189,"_71":-5,"_74":190,"_72":73,"_395":-5,"_396":-5,"_83":-5},{"_79":80,"_43":193,"_71":-5,"_74":194,"_72":73,"_395":-5,"_396":-5,"_83":-5},{"_79":80,"_43":197,"_71":-5,"_74":198,"_72":73,"_395":-5,"_396":-5,"_83":-5},{"_79":80,"_43":201,"_71":-5,"_74":202,"_72":73,"_395":-5,"_396":-5,"_83":-5},{"_79":80,"_43":205,"_71":-5,"_74":206,"_72":73,"_395":-5,"_396":-5,"_83":-5},{"_79":80,"_43":209,"_71":-5,"_74":210,"_72":73,"_395":-5,"_396":-5,"_83":-5},{"_79":80,"_43":213,"_71":-5,"_74":214,"_72":73,"_395":-5,"_396":-5,"_83":-5},{"_79":80,"_43":217,"_71":-5,"_74":218,"_72":73,"_395":-5,"_396":-5,"_83":-5},{"_79":80,"_43":221,"_71":-5,"_74":222,"_72":73,"_395":-5,"_396":-5,"_83":-5},{"_79":80,"_43":225,"_71":-5,"_74":226,"_72":73,"_395":-5,"_396":-5,"_83":-5},{"_79":80,"_43":229,"_71":-5,"_74":230,"_72":73,"_395":-5,"_396":-5,"_83":-5},{"_79":80,"_43":233,"_71":-5,"_74":234,"_72":73,"_395":-5,"_396":-5,"_83":-5},{"_79":80,"_43":237,"_71":-5,"_74":238,"_72":73,"_395":-5,"_396":-5,"_83":-5},{"_79":80,"_43":241,"_71":-5,"_74":242,"_72":73,"_395":-5,"_396":-5,"_83":-5},{"_79":80,"_43":245,"_71":-5,"_74":246,"_72":73,"_395":-5,"_396":-5,"_83":-5},{"_79":80,"_43":249,"_71":-5,"_74":250,"_72":73,"_395":-5,"_396":-5,"_83":-5},{"_79":80,"_43":253,"_71":-5,"_74":254,"_72":73,"_395":-5,"_396":-5,"_83":-5},{"_79":80,"_43":257,"_71":-5,"_74":258,"_72":73,"_395":-5,"_396":-5,"_83":-5},{"_79":80,"_43":261,"_71":-5,"_74":262,"_72":73,"_395":-5,"_396":-5,"_83":-5},{"_79":73,"_43":265,"_71":-5,"_74":266,"_72":73,"_395":-5,"_396":-5,"_83":-5},{"_79":80,"_43":269,"_71":-5,"_74":270,"_72":73,"_395":-5,"_396":-5,"_83":-5},{"_79":80,"_43":273,"_71":-5,"_74":274,"_72":73,"_395":-5,"_396":-5,"_83":-5},{"_79":80,"_43":277,"_71":-5,"_74":278,"_72":73,"_395":-5,"_396":-5,"_83":-5},{"_79":80,"_43":281,"_71":-5,"_74":282,"_72":73,"_395":-5,"_396":-5,"_83":-5},{"_79":80,"_43":285,"_71":-5,"_74":286,"_72":73,"_395":-5,"_396":-5,"_83":-5},{"_79":80,"_43":289,"_71":-5,"_74":290,"_72":73,"_395":-5,"_396":-5,"_83":-5},{"_79":80,"_43":293,"_71":-5,"_74":294,"_72":73,"_395":-5,"_396":-5,"_83":-5},{"_79":80,"_43":297,"_71":-5,"_74":298,"_72":73,"_395":-5,"_396":-5,"_83":-5},{"_79":80,"_43":301,"_71":-5,"_74":302,"_72":73,"_395":-5,"_396":-5,"_83":-5},{"_79":80,"_43":305,"_71":-5,"_74":306,"_72":73,"_395":-5,"_396":-5,"_83":-5},{"_79":80,"_43":309,"_71":-5,"_74":310,"_72":73,"_395":-5,"_396":-5,"_83":-5},{"_79":80,"_43":313,"_71":-5,"_74":314,"_72":73,"_395":-5,"_396":-5,"_83":-5},{"_79":80,"_43":317,"_71":-5,"_74":318,"_72":73,"_395":-5,"_396":-5,"_83":-5},{"_79":80,"_43":321,"_71":-5,"_74":322,"_72":73,"_395":-5,"_396":-5,"_83":-5},{"_79":80,"_43":325,"_71":-5,"_74":326,"_72":73,"_395":-5,"_396":-5,"_83":-5},{"_79":80,"_43":329,"_71":-5,"_74":330,"_72":73,"_395":-5,"_396":-5,"_83":-5},{"_79":80,"_43":333,"_71":-5,"_74":334,"_72":73,"_395":-5,"_396":-5,"_83":-5},{"_79":80,"_43":337,"_71":-5,"_74":338,"_72":73,"_395":-5,"_396":-5,"_83":-5},{"_79":80,"_43":341,"_71":-5,"_74":342,"_72":73,"_395":-5,"_396":-5,"_83":-5},{"_79":80,"_43":345,"_71":-5,"_74":346,"_72":73,"_395":-5,"_396":-5,"_83":-5},{"_79":80,"_43":349,"_71":-5,"_74":350,"_72":73,"_395":-5,"_396":-5,"_83":-5},{"_79":80,"_43":353,"_71":-5,"_74":354,"_72":73,"_395":-5,"_396":-5,"_83":-5},{"_79":80,"_43":357,"_71":-5,"_74":358,"_72":73,"_395":-5,"_396":-5,"_83":-5},{"_79":73,"_43":361,"_71":-5,"_74":362,"_72":73,"_395":-5,"_396":-5,"_83":-5},{"_79":80,"_43":365,"_71":-5,"_74":366,"_72":73,"_395":-5,"_396":-5,"_83":-5},{"_79":80,"_43":369,"_71":-5,"_74":370,"_72":73,"_395":-5,"_396":-5,"_83":-5},{"_79":80,"_43":373,"_71":-5,"_74":374,"_72":73,"_395":-5,"_396":-5,"_83":-5},{"_79":80,"_43":377,"_71":-5,"_74":378,"_72":73,"_395":-5,"_396":-5,"_83":-5},{"_79":80,"_43":381,"_71":-5,"_74":382,"_72":73,"_395":-5,"_396":-5,"_83":-5},{"_79":80,"_43":385,"_71":-5,"_74":386,"_72":73,"_395":-5,"_396":-5,"_83":-5},{"_79":73,"_43":389,"_71":-5,"_74":390,"_72":73,"_395":-5,"_396":-5,"_83":-5},"publicChapterContent","nextChapter","sections",[503,504,505,506,507,508,509,510,511,512,513,514,515,516,517,518,519,520,521,522,523,524,525,526,527,528,529,530,531,532],"routes/_store+/_layout","routes/_store+/_readers+/_layout","actionData","errors"]

\nII Chef’s Favorites (Docker)

Table of Contents

\n1 What is this?

\n1.1 Who is this for?

\n1.2 Why should I read this?

\n1.3 What have you done for me lately? (CHANGELOG)

\n1.4 What do you want from me?

\nGet in touch

\nSponsor / Patronize me

\nWork with me

\nBuy my book

\n2 How to read this book

\n2.1 Structure

\n2.2 Conventions

\n3 CHANGELOG

\n3.1 Subscribe to updates

\n3.2 Recent additions to work-in-progress

\n3.3 Recently added recipes

\n3.4 Recent improvements

\n4 Welcome to Funky Penguin’s Geek Cookbook

\n4.1 Hello world,

\n4.2 Why Funky Penguin?

\n4.3 Technical Documentation

\n4.4 Work with me

\n4.5 Contact Me

\nI HA Docker Swarm

\n5 Design

\n5.1 Design Decisions

\n5.2 Security

\nNetwork Flows

\nAuthentication

\n5.3 High availability

\nNormal function

\nNode failure

\nNode restore

\nTotal cluster failure

\n5.4 Chef’s Notes

\n6 Nodes

\n6.1 Ingredients

\n6.2 Preparation

\nPermit connectivity

\nCentOS

\nUbuntu

\nEnable hostname resolution

\nSet timezone

\n6.3 Serving

\n6.4 Chef’s Notes

\n7 Shared Storage (Ceph)

\n7.1 Ingredients

\n7.2 Preparation

\nPick a master node

\nInstall cephadm on master node

\nPrepare other nodes

\nAdd OSDs

\nSetup CephFS

\nMount CephFS volume

\n7.3 Serving

\nSprinkle with tools

\nDrool over dashboard

\n7.4 Summary

\n7.5 The easy, 5-minute install

\n7.6 Chef’s Notes

\n8 Shared Storage (GlusterFS)

\n8.1 Design

\nWhy GlusterFS?

\n8.2 Ingredients

\n8.3 Preparation

\nCreate Gluster “bricks”

\nCreate glusterfs container

\nCreate trusted pool

\nCreate gluster volume

\nMount gluster volume

\n8.4 Serving

\n8.5 Chef’s Notes

\n9 Keepalived

\n9.1 Ingredients

\n9.2 Preparation

\nEnable IPVS module

\nSetup nodes

\n9.3 Serving

\n Sponsor / Patronize me