phpIPAM
+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.
+
phpIPAM fulfils a non-sexy, but important role - It helps you manage your IP address allocation.
+Why should you care about this?
+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.
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!
+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!
+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.
+Ingredients
+-
+
- Docker swarm cluster with persistent shared storage +
- Traefik 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 +
Preparation
+Setup data locations
+Weβll need several directories to bind-mount into our container, so create them in /var/data/phpipam:
+mkdir /var/data/phpipam/databases-dump -p
+mkdir /var/data/runtime/phpipam -pPrepare environment
+Create phpipam.env, and populate with the following variables
+# Setup for github, phpipam application
+OAUTH2_PROXY_CLIENT_ID=
+OAUTH2_PROXY_CLIENT_SECRET=
+OAUTH2_PROXY_COOKIE_SECRET=
+
+# For MariaDB/MySQL database
+MYSQL_ROOT_PASSWORD=imtoosecretformyshorts
+MYSQL_DATABASE=phpipam
+MYSQL_USER=phpipam
+MYSQL_PASSWORD=secret
+
+# phpIPAM-specific variables
+MYSQL_ENV_MYSQL_USER=phpipam
+MYSQL_ENV_MYSQL_PASSWORD=secret
+MYSQL_ENV_MYSQL_DB=phpipam
+MYSQL_ENV_MYSQL_HOST=db
+
+# For backup
+BACKUP_NUM_KEEP=7
+BACKUP_FREQUENCY=1dAdditionally, create phpipam-backup.env, and populate with the following variables:
+# For MariaDB/MySQL database
+MYSQL_ROOT_PASSWORD=imtoosecretformyshorts
+MYSQL_DATABASE=phpipam
+MYSQL_USER=phpipam
+MYSQL_PASSWORD=secret
+
+# For backup
+BACKUP_NUM_KEEP=7
+BACKUP_FREQUENCY=1dCreate nginx.conf
+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.
+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.
+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.
+Create /var/data/phpipam/nginx.conf as follows:
+upstream app-upstream {
+ server app:80;
+}
+
+server {
+ listen 80;
+ server_name ~.;
+
+ # Just redirect everything to the upstream
+ # Yes, it's embarassing. We are just a mechanism to strip an AUTH header :(
+ location ^~ / {
+ proxy_pass http://app-upstream;
+ proxy_set_header Authorization "";
+ }
+
+}Setup Docker Swarm
+Create a docker swarm config file in docker-compose syntax (v3), something like this:
+!!! tip 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 π
version: '3'
+
+services:
+
+ db:
+ image: mariadb:10
+ env_file: /var/data/config/phpipam/phpipam.env
+ networks:
+ - internal
+ volumes:
+ - /var/data/runtime/phpipam/db:/var/lib/mysql
+
+ proxy:
+ image: funkypenguin/oauth2_proxy
+ env_file: /var/data/config/phpipam/phpipam.env
+ networks:
+ - internal
+ - traefik_public
+ deploy:
+ labels:
+ - traefik.frontend.rule=Host:phpipam.example.com
+ - traefik.docker.network=traefik_public
+ - traefik.port=4180
+ volumes:
+ - /var/data/config/phpipam/authenticated-emails.txt:/authenticated-emails.txt
+ command: |
+ -cookie-secure=false
+ -upstream=http://nginx
+ -redirect-url=https://phpipam.example.com
+ -http-address=http://0.0.0.0:4180
+ -email-domain=example.com
+ -provider=github
+ -authenticated-emails-file=/authenticated-emails.txt
+
+ # Wait, what? Why do we have an oauth_proxy _and_ an nginx frontend for a simple webapp?
+ # Well, it's a long story. Basically, the phpipam container sees the "auth" headers passed by the
+ # oauth_proxy, and decides to use these exclusively to authenticate users. So no web-based login form, just "access denied"
+ # To work around this, we add nginx reverse proxy to the mix. A PITA, but an easy way to solve without altering the PHPIPAM code
+ nginx:
+ image: nginx:latest
+ networks:
+ - internal
+ volumes:
+ - /var/data/phpipam/nginx.conf:/etc/nginx/conf.d/default.conf:ro
+
+ app:
+ image: pierrecdn/phpipam
+ env_file: /var/data/config/phpipam/phpipam.env
+ networks:
+ - internal
+
+ db-backup:
+ image: mariadb:10
+ env_file: /var/data/config/phpipam/phpipam.env
+ volumes:
+ - /var/data/phpipam/database-dump:/dump
+ - /etc/localtime:/etc/localtime:ro
+ entrypoint: |
+ bash -c 'bash -s <<EOF
+ trap "break;exit" SIGHUP SIGINT SIGTERM
+ sleep 2m
+ while /bin/true; do
+ mysqldump -h db --all-databases | gzip -c > /dump/dump_\`date +%d-%m-%Y"_"%H_%M_%S\`.sql.gz
+ (ls -t /dump/dump*.sql.gz|head -n $$BACKUP_NUM_KEEP;ls /dump/dump*.sql.gz)|sort|uniq -u|xargs rm -- {}
+ sleep $$BACKUP_FREQUENCY
+ done
+ EOF'
+ networks:
+ - internal
+
+networks:
+ traefik_public:
+ external: true
+ internal:
+ driver: overlay
+ ipam:
+ config:
+ - subnet: 172.16.47.0/24!!! note 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.
+Serving
+Launch phpIPAM stack
+Launch the phpIPAM stack by running docker stack deploy phpipam -c <path -to-docker-compose.yml>
Log into your new instance at https://YOUR-FQDN, and follow the on-screen prompts to set your first user/password.
+Chefβs Notes
+-
+
- 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. +
Tip your waiter (support me) π
+Did you receive excellent service? Want to make your waiter happy? (..and support development of current and future recipes!) See the support page for (free or paid) ways to say thank you! π
+Your comments? π¬
diff --git a/manuscript/whoami.md b/manuscript/whoami.md index 0117a2c..2cb826d 100644 --- a/manuscript/whoami.md +++ b/manuscript/whoami.md @@ -4,9 +4,7 @@ I'm [David](https://www.funkypenguin.co.nz/contact/). -I've spent 20+ years working with technology. My current role is **Senior Infrastructure Architect** at [Prophecy Networks Ltd](http://www.prophecy.net.nz) in New Zealand, with a specific interest in networking, systems, open-source, and business management. - -I've had a [book published](https://www.funkypenguin.co.nz/book/phplist-2-email-campaign-manager/), and I [blog](https://www.funkypenguin.co.nz/blog/) on topics that interest me. +I'm a contracting IT consultant, with a broad range of experience and skills. I'm an [AWS Certified Solution Architect (Professional)](https://www.certmetrics.com/amazon/public/badge.aspx?i=4&t=c&d=2019-02-22&ci=AWS00794574), a remote worker, I've had a [book published](https://www.funkypenguin.co.nz/book/phplist-2-email-campaign-manager/), and I [blog](https://www.funkypenguin.co.nz/blog/) on topics that interest me. ## Why Funky Penguin? diff --git a/mkdocs.yml b/mkdocs.yml index 6ce9a81..e142a5d 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -15,8 +15,13 @@ repo_url: 'https://github.com/funkypenguin/geek-cookbook' docs_dir: 'manuscript' # Copyright -copyright: 'Copyright © 2016 - 2019 David Young' +copyright: 'Copyright © 2016 - 2019 David Young, Funky Penguin Limited' +# Plugins +plugins: + - search + - minify: + minify_html: true #theme_dir: mkdocs-material nav: @@ -27,12 +32,15 @@ nav: - whoami: whoami.md - Docker Swarm: - Design: ha-docker-swarm/design.md - - VMs: ha-docker-swarm/vms.md + - Nodes: ha-docker-swarm/nodes.md - Shared Storage (Ceph): ha-docker-swarm/shared-storage-ceph.md - Shared Storage (GlusterFS): ha-docker-swarm/shared-storage-gluster.md - Keepalived: ha-docker-swarm/keepalived.md - Docker Swarm Mode: ha-docker-swarm/docker-swarm-mode.md - Traefik: ha-docker-swarm/traefik.md + - Traefik Forward Auth: + - Start: ha-docker-swarm/traefik-forward-auth.md + - KeyCloak: ha-docker-swarm/traefik-forward-auth/keycloak.md - Registry: ha-docker-swarm/registry.md - Mail Server: recipes/mail.md - Duplicity: recipes/duplicity.md @@ -40,6 +48,7 @@ nav: - Start: kubernetes/start.md - Design: kubernetes/design.md - Cluster: kubernetes/cluster.md + - DIY Cluster: kubernetes/diycluster.md - Load Balancer: kubernetes/loadbalancer.md - Snapshots: kubernetes/snapshots.md - Helm: kubernetes/helm.md @@ -69,6 +78,11 @@ nav: - iBeacon: recipes/homeassistant/ibeacon.md - Huginn: recipes/huginn.md - Kanboard: recipes/kanboard.md + - KeyCloak: + - Start: recipes/keycloak.md + - Users: recipes/keycloak/create-user.md + - OIDC Provider: recipes/keycloak/setup-oidc-provider.md + - OpenLDAP: recipes/keycloak/authenticate-against-openldap.md - Miniflux: recipes/miniflux.md - Munin: recipes/munin.md - NextCloud: recipes/nextcloud.md @@ -85,6 +99,7 @@ nav: # - phpIPAM: recipes/kubernetes/phpipam.md # - PrivateBin: recipes/kubernetes/privatebin.md - Menu: + - Bitwarden: recipes/bitwarden.md - Bookstack: recipes/bookstack.md - CryptoMiner: - Start: recipes/cryptominer.md @@ -104,24 +119,24 @@ nav: - GitLab Runner: recipes/gitlab-runner.md - Gollum: recipes/gollum.md - InstaPy: recipes/instapy.md - - KeyCloak: recipes/keycloak.md + - KeyCloak: + - Start: recipes/keycloak.md + - Users: recipes/keycloak/create-user.md + - OIDC Provider: recipes/keycloak/setup-oidc-provider.md + - OpenLDAP: recipes/keycloak/authenticate-against-openldap.md - Minio: recipes/minio.md - OpenLDAP: recipes/openldap.md - Piwik: recipes/piwik.md - Portainer: recipes/portainer.md - Realms: recipes/realms.md - Tiny Tiny RSS: recipes/tiny-tiny-rss.md + - Traefik: ha-docker-swarm/traefik.md + - Traefik Forward Auth: + - Start: ha-docker-swarm/traefik-forward-auth.md + - KeyCloak: ha-docker-swarm/traefik-forward-auth/keycloak.md - Wallabag: recipes/wallabag.md - Wekan: recipes/wekan.md - Wetty: recipes/wetty.md -# - CryptoNote Mining Pool: -# - Start: recipes/cryptonote-mining-pool.md -# - Masari: recipes/cryptonote-mining-pool/masari.md -# - Athena: recipes/cryptonote-mining-pool/athena.md -# - SSO Stack: -# - Start: recipes/sso-stack.md -# - OpenLDAP: recipes/sso-stack/openldap.md -# - KeyCloak: recipes/sso-stack/keycloak.md - Work-in-Progress: # - MatterMost: recipes/mattermost.md - IPFS Cluster: recipes/ipfs-cluster.md @@ -176,8 +191,11 @@ google_analytics: - 'UA-139253-18' - 'auto' +extra_css: + - 'stylesheets/mailchimp.css' + extra_javascript: -# - 'extras/javascript/piwik.js' + - 'extras/javascript/discord.js' # Extensions markdown_extensions: @@ -193,10 +211,12 @@ markdown_extensions: - pymdownx.caret - pymdownx.critic - pymdownx.details - - pymdownx.emoji: - emoji_generator: !!python/name:pymdownx.emoji.to_svg + - pymdownx.emoji - pymdownx.inlinehilite - - pymdownx.magiclink + - pymdownx.magiclink: + repo_url_shorthand: true + user: funkypenguin + repo: geek-cookbook - pymdownx.mark - pymdownx.smartsymbols - pymdownx.superfences diff --git a/overrides/main.html b/overrides/main.html index d2612f8..e870f49 100644 --- a/overrides/main.html +++ b/overrides/main.html @@ -13,6 +13,4 @@ (document.getElementsByTagName('head')[0] || document.getElementsByTagName('body')[0]).appendChild(d); })(); - - -{% endblock %} +{% endblock %} \ No newline at end of file diff --git a/requirements.txt b/requirements.txt index 9ee9e92..eef5584 100644 --- a/requirements.txt +++ b/requirements.txt @@ -1,4 +1,5 @@ mkdocs>=1.0.4 -mkdocs-material>=4.0.2 +mkdocs-material>=4.4.3 pymdown-extensions>=6.0 Markdown>=3.0.1 +mkdocs-minify-plugin>=0.2 diff --git a/scripts/build.sh b/scripts/build.sh new file mode 100755 index 0000000..d88cc1b --- /dev/null +++ b/scripts/build.sh @@ -0,0 +1,28 @@ +#!/bin/bash +# This script prepares mkdocs for a build (there are some adjustments to be made to the recipes before publishing) + +# Copy the contents of "manuscript" to a new "publish" folder +mkdir -p publish +mkdir -p publish/overrides +cp -r {manuscript,overrides} publish/ +cp mkdocs.yml publish/ + +# Append a common footer to all recipes/swarm docs +for i in `find publish/manuscript/ -name "*.md" | grep -v index.md` +do + # Does this recipe already have a "tip your waiter" section? + grep -q "Tip your waiter" $i + if [ $? -eq 1 ] + then + echo -e "\n" >> $i + cat scripts/recipe-footer.md >> $i + else + echo "WARNING - hard-coded footer exists in $i" + fi +done + +# Now build the docs for publishing +mkdocs build -f publish/mkdocs.yml + +# Setup any necessary netlify redirects +cp netlify_redirects.txt publish/site/_redirects diff --git a/scripts/recipe-footer.md b/scripts/recipe-footer.md new file mode 100644 index 0000000..aa5a842 --- /dev/null +++ b/scripts/recipe-footer.md @@ -0,0 +1,28 @@ +## Tip your waiter (support me) π + +Did you receive excellent service? Want to make your waiter happy? (_..and support development of current and future recipes!_) See the [support](/support/) page for (_free or paid)_ ways to say thank you! π + +## Flirt with waiter (subscribe) π + +Want to know now when this recipe gets updated, or when future recipes are added? Subscribe to the [RSS feed](https://mastodon.social/@geekcookbook_changes.atom), or leave your email address below, and we'll keep you updated. (*double-opt-in, no monkey business, no spam either - check the [archive](https://us16.campaign-archive.com/home/?u=a1d9cee4402be76497a2baf49&id=10e284530a) for proof!*) + + +
+
+
+
+
+## Your comments? π¬