diff --git a/manuscript/images/huginn.png b/manuscript/images/huginn.png new file mode 100644 index 0000000..efd313b Binary files /dev/null and b/manuscript/images/huginn.png differ diff --git a/manuscript/recipies/huginn.md b/manuscript/recipies/huginn.md new file mode 100644 index 0000000..2e69505 --- /dev/null +++ b/manuscript/recipies/huginn.md @@ -0,0 +1,117 @@ +# Huginn + +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. + + + +## 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 + +Create the location for the bind-mount of the database, so that it's persistent: + +``` +mkdir -p /var/data/huginn/database +``` + +### Create email address + +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. + +``` +cd /var/data/docker-mailserver/ +./setup.sh email add huginn@huginn.example.com my-password-here +# Setup MX and DKIM if they don't already exist: +./setup.sh config dkim +cat config/opendkim/keys/huginn.example.com/mail.txt +``` + +### Prepare environment + +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](https://github.com/huginn/huginn/blob/master/.env.example)) + +``` +# For huginn/huginn - essential +SMTP_DOMAIN=your-domain-here.com +SMTP_USER_NAME=you@gmail.com +SMTP_PASSWORD=somepassword +SMTP_SERVER=your-mailserver-here.com +SMTP_PORT=587 +SMTP_AUTHENTICATION=plain +SMTP_ENABLE_STARTTLS_AUTO=true +INVITATION_CODE= +POSTGRES_PORT_5432_TCP_ADDR=db +POSTGRES_PORT_5432_TCP_PORT=5432 +DATABASE_USERNAME=huginn +DATABASE_PASSWORD= +DATABASE_ADAPTER=postgresql + +# Optional extras for huginn/huginn, customize or append based on .env.example lined above +TWITTER_OAUTH_KEY= +TWITTER_OAUTH_SECRET= + +# For postgres/postgres +POSTGRES_USER=huginn +POSTGRES_PASSWORD= +``` + +### Setup Docker Swarm + +Create a docker swarm config file in docker-compose syntax (v3), something like this: + +``` +version: '3' + +services: + + huginn: + image: huginn/huginn + env_file: /var/data/huginn/huginn.env + networks: + - internal + - traefik + deploy: + labels: + - traefik.frontend.rule=Host:huginn.example.com + - traefik.docker.network=traefik + - traefik.port=3000 + + db: + env_file: /var/data/huginn/huginn.env + image: postgres:latest + volumes: + - /var/data/huginn/database:/var/lib/postgresql/data + networks: + - internal + +networks: + traefik: + external: true + internal: + driver: overlay + ipam: + config: + - subnet: 172.16.6.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 Huginn stack + +Launch the Huginn stack by running ```docker stack deploy huginn -c ``` + +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. + +## Chef's Notes + +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. diff --git a/manuscript/recipies/template.md b/manuscript/recipies/template.md new file mode 100644 index 0000000..3c62c7a --- /dev/null +++ b/manuscript/recipies/template.md @@ -0,0 +1,107 @@ +# NAME + +Intro + +![NAME Screenshot](../images/name.jpg) + +Details + +## 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 + +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 " +``` + +### 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 ``` + +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. diff --git a/manuscript/recipies/wekan.md b/manuscript/recipies/wekan.md index b8c2410..7da9ca5 100644 --- a/manuscript/recipies/wekan.md +++ b/manuscript/recipies/wekan.md @@ -68,6 +68,8 @@ services: networks: - traefik - internal + volumes: + - /var/data/oauth_proxy/authenticated-emails.txt:/authenticated-emails.txt deploy: labels: - traefik.frontend.rule=Host:wekan.example.com @@ -80,6 +82,7 @@ services: -http-address=http://0.0.0.0:4180 -email-domain=example.com -provider=github + -authenticated-emails-file=/authenticated-emails.txt wekan: image: wekanteam/wekan:latest diff --git a/manuscript/reference/git-docker.md b/manuscript/reference/git-docker.md index 0ecc8e1..7b71d03 100644 --- a/manuscript/reference/git-docker.md +++ b/manuscript/reference/git-docker.md @@ -2,7 +2,20 @@ Our HA platform design relies on Atomic OS, which only contains bare minimum elements to run containers. -So how can we use git on this system, to push/pull the changes we make to config files? +So how can we use git on this system, to push/pull the changes we make to config files? With a container, of course! + +## git-docker + +I [made a simple container](https://github.com/funkypenguin/git-docker/blob/master/Dockerfile) which just basically executes git in the CWD: + +To use it transparently, add an alias for the "git" command: + +``` +alias git='docker run -v $PWD:/var/data -v \ +/var/data/git-docker/data:/root funkypenguin/git-docker git' +``` + +## Limitations docker run -v /var/data/git-docker/data:/root funkypenguin/git-docker ssh-keygen -t ed25519 -f /root/.ssh/id_ed25519 Generating public/private ed25519 key pair. @@ -24,6 +37,3 @@ The key's randomart image is: |...=OX+.+. | +----[SHA256]-----+ [root@ds3 data]# - - -alias git='docker run -v $PWD:/var/data -v /var/data/git-docker/data:/root funkypenguin/git-docker git' diff --git a/manuscript/reference/networks.md b/manuscript/reference/networks.md index 90f493f..def0562 100644 --- a/manuscript/reference/networks.md +++ b/manuscript/reference/networks.md @@ -10,3 +10,4 @@ Network | Range [Wekan](https://geek-cookbook.funkypenguin.co.nz/recipies/wekan/) | 172.16.3.0/24 [Piwik](https://geek-cookbook.funkypenguin.co.nz/recipies/piwki/) | 172.16.4.0/24 [Tiny Tiny RSS](https://geek-cookbook.funkypenguin.co.nz/recipies/tiny-tiny-rss/) | 172.16.5.0/24 +[Huginn](https://geek-cookbook.funkypenguin.co.nz/recipies/huginn/) | 172.16.6.0/24 diff --git a/mkdocs.yml b/mkdocs.yml index d6a3ef5..787ad07 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -1,9 +1,12 @@ -site_name: Funky Penguin's Geek's Cookbook +site_name: Funky Penguin's Geek Cookbook site_description: 'A short description of my project' site_author: 'David Young' -site_url: 'https://geeks-cookbook.funkypenguin.co.nz' +site_url: 'https://geek-cookbook.funkypenguin.co.nz' edit_uri: 'edit/master/manuscript/' +# Fail to build if we have broken links +strict: true + # Repository repo_name: 'funkypenguin/geek-cookbook' repo_url: 'https://github.com/funkypenguin/geek-cookbook' @@ -37,28 +40,11 @@ pages: - Wekan: recipies/wekan.md - Piwik: recipies/piwik.md - Tiny Tiny RSS: recipies/tiny-tiny-rss.md + - Huginn: recipies/huginn.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 - -# - Home Assistant: -# - About: advanced/home-assistant/basic.md -# - Basic: advanced/home-assistant/basic.md -# - Grafana: advanced/home-assistant/grafana.md -# - Limitless LED: advanced/home-assistant/limitless-led.md -# - OwnTracks: advanced/home-assistant/limitless-led.md - -# - Home Assistant: - -# - About: advanced/home-assistant/basic.md -# - Basic: advanced/home-assistant/basic.md -# - Grafana: advanced/home-assistant/grafana.md -# - Limitless LED: advanced/home-assistant/limitless-led.md -# - OwnTracks: advanced/home-assistant/limitless-led.md - +# - git-docker: reference/git-docker.md # - Huginn: advanced/huginn.md # - Nextcloud: advanced/nextcloud.md # - OwnTracks: advanced/owntracks.md