22 add wekan recipe (#8)

* Add Wekan recipe

docs/ha-docker-swarm/maintenance.md

@@ -13,6 +13,9 @@ Add Brick successful
 
 # Replacing failed host
 
+Followed https://access.redhat.com/documentation/en-US/Red_Hat_Storage/3/html/Administration_Guide/sect-Replacing_Hosts.html
+
+
 [root@glusterfs-server /]# gluster peer status
 Number of Peers: 1
 
@@ -28,3 +31,53 @@ change:
 UUID=aee45c2c-aa19-4d29-bc94-4833f2b22863
 to
 UUID=db9c80da-11e4-461d-8ea5-66dd12ca897c
+
+My peer's id (ds2):
+[root@glusterfs-server /]# gluster system:: uuid get
+UUID: 38ca4e8b-8ef5-4165-9f41-5c8b3f0103cc
+[root@glusterfs-server /]#
+
+vi /var/lib/glusterd/peers/38ca4e8b-8ef5-4165-9f41-5c8b3f0103cc
+
+UUID=38ca4e8b-8ef5-4165-9f41-5c8b3f0103cc
+state=3
+hostname=ds3
+
+
+
+Got volume info
+
+
+[root@glusterfs-server /]# gluster volume info
+
+Volume Name: gv0
+Type: Replicate
+Volume ID: 84e1169c-41dc-467a-9ae1-a474efaf789f
+Status: Started
+Snapshot Count: 0
+Number of Bricks: 1 x 2 = 2
+Transport-type: tcp
+Bricks:
+Brick1: ds1:/var/no-direct-write-here/brick1/gv0
+Brick2: ds3:/var/no-direct-write-here/brick1/gv0
+Options Reconfigured:
+nfs.disable: on
+transport.address-family: inet
+[root@glusterfs-server /]#
+
+
+
+----
+[root@glusterfs-server /]# getfattr -d -m. -ehex /var/no-direct-write-here/brick1/gv0/
+getfattr: Removing leading '/' from absolute path names
+# file: var/no-direct-write-here/brick1/gv0/
+security.selinux=0x73797374656d5f753a6f626a6563745f723a756e6c6162656c65645f743a733000
+trusted.gfid=0x00000000000000000000000000000001
+trusted.glusterfs.dht=0x000000010000000000000000ffffffff
+trusted.glusterfs.volume-id=0x84e1169c41dc467a9ae1a474efaf789f
+
+[root@glusterfs-server /]#
+
+
+
+setfattr -n trusted.glusterfs.volume-id -v 0x84e1169c41dc467a9ae1a474efaf789f /var/no-direct-write-here/brick1/gv0

docs/recipies/gitlab.md

@@ -101,9 +101,11 @@ networks:
     driver: overlay
     ipam:
       config:
-        - subnet: 172.16.1.0/24
+        - subnet: 172.16.2.0/24
+        - 
 ```
-
+!!! tip
+    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](/reference/networks/) here.
 
 
 ## Serving

docs/recipies/wekan.md

@@ -0,0 +1,115 @@
+# Wekan
+
+Wekan is an open-source kanban board which allows a card-based task and to-do management, similar to tools like WorkFlowy or Trello.
+
+![Wekan Screenshot](../images/wekan.jpg)
+
+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.
+
+There's a [video](https://www.youtube.com/watch?v=N3iMLwCNOro) of the developer showing off the app, as well as a f[unctional demo](https://wekan.indie.host/b/t2YaGmyXgNkppcFBq/wekan-fork-roadmap).
+
+!!! note
+    For added privacy, this design secures wekan behind an [oauth2 proxy](/reference/oauth_proxy/), so that in order to gain access to the wekan UI at all, oauth2 authentication (to GitHub, GitLab, Google, etc) must have already occured.
+
+## Ingredients
+
+1. [Docker swarm cluster](/ha-docker-swarm/) with [persistent shared storage](/ha-docker-swarm/shared-storage-ceph.md)
+2. [Traefik](/ha-docker-swarm/traefik) configured per design
+
+## Preparation
+
+### Setup data locations
+
+We'll need several directories to bind-mount into our container, so create them in /var/data/wekan:
+
+```
+mkdir /var/data/wekan
+cd /var/data/wekan
+mkdir -p {wekan-db,wekan-db-dump}
+```
+
+### Prepare environment
+
+You'll need to know the following:
+
+1. Choose an oauth provider, and obtain a client ID and secret
+2. Create wekan.env, and populate with the following variables
+```
+OAUTH2_PROXY_CLIENT_ID=
+OAUTH2_PROXY_CLIENT_SECRET=
+OAUTH2_PROXY_COOKIE_SECRET=
+MONGO_URL=mongodb://wekandb:27017/wekan
+ROOT_URL=https://wekan.example.com
+MAIL_URL=smtp://wekan@wekan.example.com:password@mail.example.com:587/
+MAIL_FROM="Wekan <wekan@wekan.example.com>"
+```
+
+### Setup Docker Swarm
+
+Create a docker swarm config file in docker-compose syntax (v3), something like this:
+
+```
+version: '3'
+
+services:
+
+  wekandb:
+    image: mongo:3.2.15
+    command: mongod --smallfiles --oplogSize 128
+    networks:
+      - internal
+    volumes:
+      - /var/data/wekan/wekan-db:/data/db
+      - /var/data/wekan/wekan-db-dump:/dump
+
+  proxy:
+    image: zappi/oauth2_proxy
+    env_file: /var/data/wekan/wekan.env
+    networks:
+      - traefik
+      - internal
+    deploy:
+      labels:
+        - traefik.frontend.rule=Host:wekan.example.com
+        - traefik.docker.network=traefik
+        - traefik.port=4180
+    command: |
+      -cookie-secure=false
+      -upstream=http://wekan:80
+      -redirect-url=https://wekan.example.com
+      -http-address=http://0.0.0.0:4180
+      -email-domain=example.com
+      -provider=github
+
+  wekan:
+    image: wekanteam/wekan:latest
+    networks:
+      - internal
+    env_file: /var/data/wekan/wekan.env
+
+networks:
+  traefik:
+    external: true
+  internal:
+    driver: overlay
+    ipam:
+      config:
+        - subnet: 172.16.3.0/24
+```
+
+!!! tip
+    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](/reference/networks/) here.
+
+
+
+## Serving
+
+### Launch Wekan stack
+
+Launch the Wekan stack by running ```docker stack deploy wekan -c <path -to-docker-compose.yml>```
+
+Log into your new instance at https://**YOUR-FQDN**, with user "root" and the password you specified in gitlab.env.
+
+## Chef's Notes
+
+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.

docs/reference/networks.md

@@ -0,0 +1,10 @@
+# Networks
+
+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:
+
+Network  | Range
+--|--
+[Traefik](/ha-docker-swarm/traefik/)  | _unspecified_
+[Mail Server](/recipies/mail/)  | 172.16.1.0/24
+[Gitlab](/recipies/gitlab/) | 172.16.2.0/24
+[Wekan](/recipies/wekan/)  |  172.16.3.0/24

docs/reference/oauth_proxy.md

@@ -0,0 +1,79 @@
+# OAuth proxy
+
+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).
+
+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.
+
+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.
+
+This is the role of the OAuth proxy.
+
+## How does it work?
+
+**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.
+
+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.
+
+Illustrated below:
+![OAuth proxy](/images/oauth_proxy.png)
+
+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.
+
+## Ingredients
+
+## Preparation
+
+### OAuth provider
+
+OAuth Proxy currently supports the following OAuth providers:
+
+* Google (default)
+* Azure
+* Facebook
+* GitHub
+* GitLab
+* LinkedIn
+* MyUSA
+
+Follow the [instructions](https://github.com/bitly/oauth2_proxy) 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.
+
+### Authorized emails file
+
+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_)
+
+The most restrictive configuration allows access on a per-email address basis, which is illustrated below:
+
+I created **/var/data/oauth_proxy/authenticated-emails.txt**, and add my own email address to the first line.
+
+### Configure stack
+
+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](/recipies/wekan/) recipe:
+
+```
+proxy:
+  image: zappi/oauth2_proxy
+  env_file : /var/data/wekan/wekan.env
+  networks:
+    - traefik
+    - internal
+  deploy:
+    labels:
+      - traefik.frontend.rule=Host:wekan.funkypenguin.co.nz
+      - traefik.docker.network=traefik
+      - traefik.port=4180
+  volumes:
+    - /var/data/oauth_proxy/authenticated-emails.txt:/authenticated-emails.txt
+  command: |
+    -cookie-secure=false
+    -upstream=http://wekan:80
+    -redirect-url=https://wekan.funkypenguin.co.nz
+    -http-address=http://0.0.0.0:4180
+    -email-domain=funkypenguin.co.nz
+    -provider=github
+    -authenticated-emails-file=/authenticated-emails.txt
+```
+
+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

mkdocs.yml

@@ -31,6 +31,10 @@ pages:
       - Mail Server: recipies/mail.md
       - GitLab: recipies/gitlab.md
       - GitLab Runner: recipies/gitlab-runner.md
+      - Wekan: recipies/wekan.md
+    - Reference:
+      - OAuth Proxy: reference/oauth_proxy.md
+      - Networks: reference/networks.md
 #      - Basic: advanced/tiny-tiny-rss.md
 #      - Plugins: advanced/tiny-tiny-rss.md
 #      - Themes: advanced/tiny-tiny-rss.md