From ffa431491963f4fafe37621ebdf41bfdc2c7a678 Mon Sep 17 00:00:00 2001 From: David Young Date: Wed, 27 Oct 2021 14:41:40 +1300 Subject: [PATCH] Misc housekeeping tidy-ups --- .github/ISSUE_TEMPLATE/bug-report.yaml | 93 +++++++++++++++++++ .github/ISSUE_TEMPLATE/bug_report.md | 35 ------- .github/ISSUE_TEMPLATE/recipe-request.yaml | 12 ++- .github/ISSUE_TEMPLATE/suggestion.md | 23 ----- .github/ISSUE_TEMPLATE/suggestion.yaml | 81 ++++++++++++++++ .github/ISSUE_TEMPLATE/support-request.md | 14 +-- .github/pull_request_template.md | 4 +- .../index.md} | 0 .../traefik-forward-auth/keycloak.md | 3 + manuscript/index.md | 4 + manuscript/{premix.md => premix/index.md} | 0 manuscript/recipes/homeassistant/ibeacon.md | 26 ------ .../{keycloak.md => keycloak/index.md} | 21 +++-- manuscript/support.md | 5 +- mkdocs.yml | 26 +++--- scripts/local-markdownlint-and-fix.sh | 2 +- 16 files changed, 226 insertions(+), 123 deletions(-) create mode 100644 .github/ISSUE_TEMPLATE/bug-report.yaml delete mode 100644 .github/ISSUE_TEMPLATE/bug_report.md delete mode 100644 .github/ISSUE_TEMPLATE/suggestion.md create mode 100644 .github/ISSUE_TEMPLATE/suggestion.yaml rename manuscript/ha-docker-swarm/{traefik-forward-auth.md => traefik-forward-auth/index.md} (100%) rename manuscript/{premix.md => premix/index.md} (100%) delete mode 100644 manuscript/recipes/homeassistant/ibeacon.md rename manuscript/recipes/{keycloak.md => keycloak/index.md} (83%) diff --git a/.github/ISSUE_TEMPLATE/bug-report.yaml b/.github/ISSUE_TEMPLATE/bug-report.yaml new file mode 100644 index 0000000..0bfeb07 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug-report.yaml @@ -0,0 +1,93 @@ +name: "πŸ› Bug Report" +description: If something isn't working as expected πŸ€’ +title: "[bug report] " +assignees: funkypenguin +labels: [ bug ] + +body: + - type: markdown + attributes: + value: | + ## :wave: Greetings! + + Greetings, fellow geek! + + Thanks for taking the time to point out a bug πŸ›! This issue form helps to capture the bug report in a standardized way, all the better to **squish** it! πŸ₯Ύ + + - type: checkboxes + id: sanity_check + attributes: + label: πŸ€ͺ Sanity check + description: Let's first confirm that this is not a bug which is already under action + options: + - label: I have searched and confirmed no existing [open](https://github.com/funkypenguin/geek-cookbook/issues?q=is%3Aissue)/[closed](https://github.com/funkypenguin/geek-cookbook/issues?q=is%3Aissue+is%3Aclosed) issues exist for this bug + required: true + + - type: textarea + attributes: + label: 1️⃣ Description + description: A clear and concise description of the bug + placeholder: I get an error when [...] + validations: + required: true + + - type: textarea + attributes: + label: 2️⃣ Expected Behaviour + placeholder: A clear and concise description of the expected behaviour + validations: + required: true + + - type: textarea + attributes: + label: 3️⃣ Actual Behaviour + placeholder: A clear and concise description of the actual behaviour + validations: + required: true + + - type: textarea + attributes: + label: 4️⃣ Steps to Reproduce + description: Describe how to reproduce the bug + placeholder: | + 1.. + 2.. + 3.. + validations: + required: true + + - type: textarea + attributes: + label: 5️⃣ Possible solutions + description: Suggestions you may have on how to fix the bug + + - type: textarea + attributes: + label: 6️⃣ Relevant Information + description: Paste in any relevant data, including YAML files, package versions, etc. + + - type: input + id: discord_id + attributes: + label: πŸ’¬ Your Discord username + description: If you've joined our [Discord server](http://chat.funkypenguin.co.nz), enter your username here so that we can collaborate effectively + placeholder: BobTheBuilder#4567 + + - type: checkboxes + id: engagement + attributes: + label: πŸ’ Engagement + description: To see this bug squished, I'm willing to... + options: + - label: Test the changes after a preview deploy and provide feedback + - label: Solicit community input in [Discord](http://chat.funkypenguin.co.nz) + - label: Submit a PR for a fix myself πŸ† + + - type: checkboxes + id: terms + attributes: + label: βœ… Code of Conduct + description: By submitting this issue, I agree to follow our community's [Code of Conduct](https://geek-cookbook.funkypenguin.co.nz/community/code-of-conduct/) + options: + - label: I agree to follow this Geek Cookbook's Code of Conduct + required: true diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md deleted file mode 100644 index a1cbc3d..0000000 --- a/.github/ISSUE_TEMPLATE/bug_report.md +++ /dev/null @@ -1,35 +0,0 @@ ---- -name: "\U0001F41B Bug Report" -about: "If something isn't working as expected \U0001F914." -title: "[bug report] there's a fly in my soup" -labels: '' -assignees: funkypenguin - ---- - -# Waiter! There's a bug in my recipe! πŸ› - -## ‼️ Current Behavior -A clear and concise description of the behavior. - -```bash -echo "stuff is broken" -``` - -## βœ… Expected behavior -A clear and concise description of what you expected to happen (or code). - -```bash -echo "stuff is working! -``` - -## πŸ‘―β€β™‚οΈ Steps to reproduce - -Explain how to reproduce the issue - -## πŸ“– Context and logs - -Provide any extra context and logs relevant. If the logs are too large to read easily, provide a link via ghostbin / pastebin - -## πŸ’‘Possible Solutions - diff --git a/.github/ISSUE_TEMPLATE/recipe-request.yaml b/.github/ISSUE_TEMPLATE/recipe-request.yaml index 0d85ce1..ad47376 100644 --- a/.github/ISSUE_TEMPLATE/recipe-request.yaml +++ b/.github/ISSUE_TEMPLATE/recipe-request.yaml @@ -1,5 +1,5 @@ name: "🍰 Request a new recipe!" -description: I have a request for a fresh recipe πŸ˜‹ +description: I have a request for a fresh, tasty recipe πŸ˜‹ title: "[recipe] " labels: ["recipe/request", "status/backlog", "good first issue"] @@ -7,7 +7,9 @@ body: - type: markdown attributes: value: | - Greetings, fellow geek! :wave: + ## :wave: Greetings + + Greetings, fellow geek! Thanks for taking the time to request this recipe! This issue form helps to capture the request in a standardized way, and to pre-gather as much information as possible, to expidite @@ -27,7 +29,7 @@ body: - type: textarea attributes: - label: Description + label: πŸ“œ Description description: Please provide a brief description of the proposed recipe validations: required: true @@ -44,7 +46,7 @@ body: - type: input id: discord_id attributes: - label: Your Discord username + label: πŸ’¬ Your Discord username description: If you've joined our [Discord server](http://chat.funkypenguin.co.nz), enter your username here so that we can collaborate effectively placeholder: BobTheBuilder#4567 @@ -73,7 +75,7 @@ body: id: terms attributes: label: Code of Conduct - description: By submitting this issue, you agree to follow our [Code of Conduct](https://geek-cookbook.funkypenguin.co.nz/community/code-of-conduct/) + description: By submitting this issue, you agree to follow our community's [Code of Conduct](https://geek-cookbook.funkypenguin.co.nz/community/code-of-conduct/) options: - label: I agree to follow this Geek Cookbook's Code of Conduct required: true diff --git a/.github/ISSUE_TEMPLATE/suggestion.md b/.github/ISSUE_TEMPLATE/suggestion.md deleted file mode 100644 index 735551f..0000000 --- a/.github/ISSUE_TEMPLATE/suggestion.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -name: "\U0001F680 Feature Request" -about: "I have a suggestion (and may want to implement it \U0001F642)!" -title: "[suggestion] The cookbook would be so much better if..." -labels: '' -assignees: funkypenguin - ---- - -## Feature Request - -**Is your feature request related to a problem? Please describe.** -A clear and concise description of what the problem is. Ex. I have an issue when [...] - -**Describe the solution you'd like** -A clear and concise description of what you want to happen. Add any considered drawbacks. - -**Describe alternatives you've considered** -A clear and concise description of any alternative solutions or features you've considered. - -**Teachability, Documentation, Adoption, Migration Strategy** -If you can, explain how users will be able to use this and possibly write out a version the docs. -Maybe a screenshot or design? diff --git a/.github/ISSUE_TEMPLATE/suggestion.yaml b/.github/ISSUE_TEMPLATE/suggestion.yaml new file mode 100644 index 0000000..f88fe6f --- /dev/null +++ b/.github/ISSUE_TEMPLATE/suggestion.yaml @@ -0,0 +1,81 @@ +name: "πŸ’‘ Suggestion" +description: I have a suggestion for an improvement 🧐 +title: "[suggestion] " + +body: + - type: markdown + attributes: + value: | + ## :wave: Greetings! + + Greetings, fellow geek! + + Thanks for taking the time to pass on a suggestion for improvement! This issue form helps to capture your + suggestion in a standardized way, all the better to implement it! + + - type: checkboxes + id: sanity_check + attributes: + label: πŸ€ͺ Sanity check + description: Let's first confirm that this is not a suggestion which has previously been discussed / proposed + options: + - label: I have searched and confirmed no existing [open](https://github.com/funkypenguin/geek-cookbook/issues?q=is%3Aissue) / [closed](https://github.com/funkypenguin/geek-cookbook/issues?q=is%3Aissue+is%3Aclosed) issues, or [open](https://github.com/funkypenguin/geek-cookbook/pulls?q=is%3Apr) / [closed](https://github.com/funkypenguin/geek-cookbook/pulls?q=is%3Apr+is%3Aclosed) PRs exist for this suggestion + required: true + + - type: textarea + attributes: + label: πŸ€• What's not right? + description: What's the challenge, or the area for improvement? + placeholder: A clear and concise description of what the problem/challenge is. Ex. I have an issue when [...] + validations: + required: true + + - type: textarea + attributes: + label: 🀯 Here's my idea! + description: Describe the solution you'd suggest + placeholder: A clear and concise description of what you want to happen. Add any considered drawbacks. + validations: + required: true + + - type: textarea + attributes: + label: πŸ€” On the other hand.. + description: Describe alternatives you've considered + placeholder: A clear and concise description of any alternative solutions or features you've considered. + validations: + required: true + + - type: textarea + attributes: + label: 🀩 But will it fly? + description: Teachability, Documentation, Adoption, Migration Strategy + placeholder: If you can, explain how users will be able to use this and possibly write out a version the docs. Maybe a screenshot or design? + validations: + required: true + + - type: input + id: discord_id + attributes: + label: πŸ’¬ Your Discord username + description: If you've joined our [Discord server](http://chat.funkypenguin.co.nz), enter your username here so that we can collaborate effectively + placeholder: BobTheBuilder#4567 + + - type: checkboxes + id: engagement + attributes: + label: πŸ’ Engagement + description: To see this suggestion implemented, I'm willing to... + options: + - label: Test the changes after a preview deploy and provide feedback + - label: Solicit community input in [Discord](http://chat.funkypenguin.co.nz) + - label: Submit a PR for a first-cut myself πŸ† + + - type: checkboxes + id: terms + attributes: + label: βœ… Code of Conduct + description: By submitting this issue, I agree to follow our community's [Code of Conduct](https://geek-cookbook.funkypenguin.co.nz/community/code-of-conduct/) + options: + - label: I agree to follow this Geek Cookbook's Code of Conduct + required: true diff --git a/.github/ISSUE_TEMPLATE/support-request.md b/.github/ISSUE_TEMPLATE/support-request.md index 52315e6..3225e8b 100644 --- a/.github/ISSUE_TEMPLATE/support-request.md +++ b/.github/ISSUE_TEMPLATE/support-request.md @@ -1,17 +1,19 @@ --- -name: "\U0001F917 Support Request" -about: "If you have a question \U0001F4AC, please refer to Discord or Discourse!" +name: "πŸ™‹β€β™‚οΈ Support Request" +about: "If you need help, please refer to Discord or Discourse! πŸ€·β€β™‚οΈ" title: '' labels: '' assignees: '' --- ---------------^ Click "Preview" for a nicer view! -We primarily use GitHub as an issue tracker; for usage and support questions, please check out these resources below. Thanks! 😁. + +We primarily use GitHub issues to track changes needed to be made to the cookbook; for individual usage and support questions, please use the resources below. Thanks! 😁 + +(*Tip: Each recipe includes a comments thread which integrates into our Forums for support / questions*) --- -* Discord: http://chat.funkypenguin.co.nz -* Discourse: https://discourse.geek-kitchen.funkypenguin.co.nz +* Real-time chat: http://chat.funkypenguin.co.nz +* Discussion forums: https://discourse.geek-kitchen.funkypenguin.co.nz * Details: https://geek-cookbook.funkypenguin.co.nz/support/ diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 4b3afd6..e5bba5c 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -26,13 +26,11 @@ - [ ] I have read the [contribution guide](https://geek-cookbook.funkypenguin.co.nz/community/contribute/#contributing-recipes) - [ ] The format of my changes matches that of other recipes (*ideally it was copied from [template](/manuscript/recipes/template.md)*) +- [ ] My changes have passed markdown linting, either by running `./scripts/local-markdownlint.sh` locally, or by checking the status of the PR check below. - -### Recipe-specific checks - - [ ] I've added at least one footnote to my recipe (*Chef's Notes*) - [ ] I've updated `common_links.md` in the `_snippets` directory and sorted alphabetically - [ ] I've updated the navigation in `mkdocs.yaml` in alphabetical order diff --git a/manuscript/ha-docker-swarm/traefik-forward-auth.md b/manuscript/ha-docker-swarm/traefik-forward-auth/index.md similarity index 100% rename from manuscript/ha-docker-swarm/traefik-forward-auth.md rename to manuscript/ha-docker-swarm/traefik-forward-auth/index.md diff --git a/manuscript/ha-docker-swarm/traefik-forward-auth/keycloak.md b/manuscript/ha-docker-swarm/traefik-forward-auth/keycloak.md index 140da72..3682207 100644 --- a/manuscript/ha-docker-swarm/traefik-forward-auth/keycloak.md +++ b/manuscript/ha-docker-swarm/traefik-forward-auth/keycloak.md @@ -2,6 +2,9 @@ While the [Traefik Forward Auth](/ha-docker-swarm/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. +!!! tip "Keycloak with Traefik" + Did you land here from Google, looking for information about using Keycloak with Traefik? All this and more is covered in the [Keycloak][keycloak] recipe! + --8<-- "recipe-tfa-ingredients.md" ## Preparation diff --git a/manuscript/index.md b/manuscript/index.md index d842744..06fd8c3 100644 --- a/manuscript/index.md +++ b/manuscript/index.md @@ -91,6 +91,10 @@ Need some Cloud / Microservices / DevOps / Infrastructure design work done? I'm I'm publishing the Geek Cookbook as a formal eBook (*PDF, mobi, epub*), on Leanpub (). Check it out! +### Buy me a coffee β˜•οΈ + +A sponsorship is too much commitment, and a book is TL;DR? Hit me up with a [one-time caffine shot](https://www.buymeacoffee.com/funkypenguin)! + ### Sponsored Projects I'm supported and motivated by [GitHub Sponsors](https://github.com/sponsors/funkypenguin), [Patreon patrons](https://www.patreon.com/funkypenguin) and [LeanPub readers](https://leanpub.com/geeks-cookbook) who have generously sponsored me. diff --git a/manuscript/premix.md b/manuscript/premix/index.md similarity index 100% rename from manuscript/premix.md rename to manuscript/premix/index.md diff --git a/manuscript/recipes/homeassistant/ibeacon.md b/manuscript/recipes/homeassistant/ibeacon.md deleted file mode 100644 index 93504a1..0000000 --- a/manuscript/recipes/homeassistant/ibeacon.md +++ /dev/null @@ -1,26 +0,0 @@ -# iBeacons with Home assistant - -!!! warning -This is not a complete recipe - it's an optional additional of the [HomeAssistant](/recipes/homeassistant/) "recipe", since it only applies to a subset of users - -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! - -## Ingredients - -1. [HomeAssistant](/recipes/homeassistant/) per recipe -2. iBeacon(s) - This recipe is for -3. [LightBlue Explorer](https://itunes.apple.com/nz/app/lightblue-explorer/id557428110?mt=8) - -## Preparation - -### Write UUID to iBeacon - -The iBeacons come with no UUID. We use the LightBlue Explorer app to pair with them (_code is "123456"_), and assign own own UUID. - -Generate your own UUID, or get a random one at - -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** - -Having paired, you'll be able to see the vital statistics of your iBeacon. - ---8<-- "recipe-footer.md" diff --git a/manuscript/recipes/keycloak.md b/manuscript/recipes/keycloak/index.md similarity index 83% rename from manuscript/recipes/keycloak.md rename to manuscript/recipes/keycloak/index.md index c11ea33..27513f4 100644 --- a/manuscript/recipes/keycloak.md +++ b/manuscript/recipes/keycloak/index.md @@ -4,9 +4,11 @@ description: Kick-ass OIDC and identity management # KeyCloak -[KeyCloak](https://www.keycloak.org/) is "_an open source identity and access management solution_". Using a local database, or a variety of backends (_think [OpenLDAP](/recipes/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](/ha-docker-swarm/traefik-forward-auth/), to protect [vulnerable services](/recipes/autopirate/nzbget/) with an extra layer of authentication. +[KeyCloak](https://www.keycloak.org/) is "_an open source identity and access management solution_". Using a local database, or a variety of backends (_think [OpenLDAP](/recipes/openldap/)_), you can provide Single Sign-On (SSO) using OpenID, OAuth 2.0, and SAML. -![KeyCloak Screenshot](../images/keycloak.png) +KeyCloak's OpenID provider can also be used in combination with [Traefik Forward Auth](/ha-docker-swarm/traefik-forward-auth/), to protect [vulnerable services](/recipes/autopirate/nzbget/) with an extra layer of authentication. + +![KeyCloak Screenshot](../../images/keycloak.png) --8<-- "recipe-standard-ingredients.md" @@ -39,7 +41,7 @@ KEYCLOAK_PASSWORD=ilovepasswords PROXY_ADDRESS_FORWARDING=true # What's our hostname? -KEYCLOAK_HOSTNAME=keycloak.batcave.com +KEYCLOAK_HOSTNAME=keycloak.example.com # Tell Postgress what user/password to create POSTGRES_USER=keycloak @@ -76,20 +78,19 @@ services: - internal deploy: labels: - # traefik common + # traefik - traefik.enable=true - traefik.docker.network=traefik_public # traefikv1 - traefik.frontend.rule=Host:keycloak.example.com - - traefik.port=8080 + - traefik.port=8080 # traefikv2 - "traefik.http.routers.keycloak.rule=Host(`keycloak.example.com`)" + - "traefik.http.routers.keycloak.entrypoints=https" - "traefik.http.services.keycloak.loadbalancer.server.port=8080" - - "traefik.enable=true" - - + keycloak-db: env_file: /var/data/config/keycloak/keycloak.env image: postgres:10.1 @@ -136,6 +137,8 @@ networks: Launch the KeyCloak stack by running `docker stack deploy keycloak -c ` -Log into your new instance at https://**YOUR-FQDN**, and login with the user/password you defined in `keycloak.env`. +Log into your new instance at `https://YOUR-FQDN`, and login with the user/password you defined in `keycloak.env`. --8<-- "recipe-footer.md" + +[^1]: For more geeky {--pain--}{++fun++}, try integrating KeyCloak with [OpenLDAP][openldap] for an authentication backend! diff --git a/manuscript/support.md b/manuscript/support.md index d783244..1f751ef 100644 --- a/manuscript/support.md +++ b/manuscript/support.md @@ -63,7 +63,7 @@ I'm also writing the Geek Cookbook as a formal eBook, on Leanpub (