From 2c75cfe0ea0556aab1329259da985e84542fe6dc Mon Sep 17 00:00:00 2001 From: Kjeld Schouten-Lebbing Date: Sun, 26 Apr 2020 16:00:47 +0200 Subject: [PATCH] Wiki replacement and CI update (#86) * dhcp uses on, not true (because iocage syntax) * Documentation updates * Add gh-pages wiki generator using mkdocs * Update shellcheck.yml * Update wiki.yml * Add filecheck * readme case correction1 * readme case correction2 * Update filecheck.yml --- .github/workflows/filecheck.yml | 21 ++++++ .github/workflows/shellcheck.yml | 4 +- .github/workflows/wiki.yml | 26 +++++++ docs/LICENSE => LICENSE | 0 docs/CONTRIBUTING.md | 90 ++++++++++++++++++++++++ docs/ISSUE_TEMPLATE.md | 13 ++++ docs/PULL_REQUEST_TEMPLATE.md | 16 +++++ docs/Readme.md | 2 +- docs/config options.md | 10 ++- docs/index.md | 5 ++ docs/jails/jails.md | 1 + docs/test.md | 1 + jails/bitwarden/readme.md | 5 +- jails/influxdb/readme.md | 4 +- jails/kms/readme.md | 3 +- jails/lidarr/readme.md | 4 +- jails/mariadb/readme.md | 4 +- jails/nextcloud/{README.md => readme.md} | 4 +- jails/organizr/readme.md | 4 +- jails/radarr/readme.md | 4 +- jails/sonarr/readme.md | 4 +- jails/tautulli/readme.md | 4 +- jails/transmission/readme.md | 4 +- mkdocs.yml | 23 ++++++ wiki/Home.md | 3 - wiki/test.md | 1 - 26 files changed, 239 insertions(+), 21 deletions(-) create mode 100644 .github/workflows/filecheck.yml create mode 100644 .github/workflows/wiki.yml rename docs/LICENSE => LICENSE (100%) create mode 100644 docs/CONTRIBUTING.md create mode 100644 docs/ISSUE_TEMPLATE.md create mode 100644 docs/PULL_REQUEST_TEMPLATE.md create mode 100644 docs/index.md create mode 100644 docs/jails/jails.md create mode 100644 docs/test.md rename jails/nextcloud/{README.md => readme.md} (99%) mode change 100755 => 100644 create mode 100644 mkdocs.yml delete mode 100644 wiki/Home.md delete mode 100644 wiki/test.md diff --git a/.github/workflows/filecheck.yml b/.github/workflows/filecheck.yml new file mode 100644 index 00000000..1ba68643 --- /dev/null +++ b/.github/workflows/filecheck.yml @@ -0,0 +1,21 @@ +name: File Presence QC +on: + pull_request: + branches: + - master + - dev + +jobs: + build: + name: Check Files + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v1 + - name: check existance + run: | + for pathname in jails/*; do test -e $pathname/readme.md || { echo "File missing: $pathname/readme.md"; error="true"; }; done + for pathname in jails/*; do test -e $pathname/install.sh || { echo "File missing: $pathname/install.sh"; error="true"; }; done + for pathname in jails/*; do test -e $pathname/update.sh || { echo "File missing: $pathname/update.sh"; error="true"; }; done + for pathname in jails/*; do test -e $pathname/config.yml || { echo "File missing: $pathname/config.yml"; error="true"; }; done + if [ "${error}" == "true" ]; then echo "Missing files detected" && exit 1; fi + shell: bash diff --git a/.github/workflows/shellcheck.yml b/.github/workflows/shellcheck.yml index 533096fd..e5d12b6f 100644 --- a/.github/workflows/shellcheck.yml +++ b/.github/workflows/shellcheck.yml @@ -1,5 +1,5 @@ # This is a workflow to run shellcheck on all scripts -name: Shellcheck Workflow +name: Shell Linter QC # Controls when the action will run. Triggers the workflow on push or pull request # events but only for the master branch @@ -10,7 +10,7 @@ on: - dev jobs: - shellcheck: + Shellcheck: runs-on: ubuntu-latest steps: - uses: actions/checkout@v1 diff --git a/.github/workflows/wiki.yml b/.github/workflows/wiki.yml new file mode 100644 index 00000000..d87b3899 --- /dev/null +++ b/.github/workflows/wiki.yml @@ -0,0 +1,26 @@ +name: Publish docs via GitHub Pages +on: + push: + branches: + - master + +jobs: + build: + name: Deploy docs + runs-on: ubuntu-latest + steps: + - name: Checkout master + uses: actions/checkout@v1 + with: + ref: 'master' + - name: rename-readme + run: | + for pathname in jails/*/README.MD; do ! cp "$pathname" "docs/jails/$( basename "$( dirname "$pathname" )" ).md"; done + for pathname in jails/*/README.md; do ! cp "$pathname" "docs/jails/$( basename "$( dirname "$pathname" )" ).md"; done + for pathname in jails/*/readme.md; do ! cp "$pathname" "docs/jails/$( basename "$( dirname "$pathname" )" ).md"; done + for pathname in jails/*/Readme.md; do ! cp "$pathname" "docs/jails/$( basename "$( dirname "$pathname" )" ).md"; done + shell: bash + - name: Deploy docs + uses: mhausenblas/mkdocs-deploy-gh-pages@master + env: + GITHUB_TOKEN: ${{ secrets.WIKI_GH_PAT }} diff --git a/docs/LICENSE b/LICENSE similarity index 100% rename from docs/LICENSE rename to LICENSE diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md new file mode 100644 index 00000000..b42eac40 --- /dev/null +++ b/docs/CONTRIBUTING.md @@ -0,0 +1,90 @@ +# Contribution and Review Guidelines + +This project welcomes any and all input, but we need to have a few quality guidelines. These guidelines will be examplained here, in this document. + +### GIT Guidelines +*** +#### New to GIT + +If you have never used git before, you can look up our general reference on our wiki. + +#### Git and You + +GIT is a fantastic system, but while using it we have a few guidelines to keep it fantastic for everyone. + +* Submit complete PR's. +* Add [DNM] if you do not want your PR merged yet. +* Always try and fill in the whole form, even for small PR's. +* Don't close when a reviewer requests changes (just push the changes or ask for help). +* Explain what you did in your PR. +* Be thorough. +* If you can add screenshots to clarify. +* Always try to add "Fixes #000" (where 000 is the Issue your PR fixes) +* found something you want to fix yourself? Please do make an issue too. + +### Structure Guidelines +*** +#### Naming scheme + +File and folder names are important and making mistakes in them may give conflicts an/or annoyance in the future. Remember, your garbage needs to be cleaned by someone sometime in the future! For that reason, we have a few guidelines in regards to naming files and folder. + +* Always start files and folders WITHOUT a Capital. + +#### Inclusion of files and folders + +Although GIT is quite friendly in what it accepts in terms of files and folder changes in a commit, a reviewer's or bugfixer's time is not unlimited. For that reason, we have a few specific guidelines in regards to the inclusion of files and folders in your PR. + +* Only include files you actually changed. +* Try not to include multiple changes in one PR +* Want to change the formatting of multiple files too? Make a separate PR. + +*Always include the following files when creating a new jail* + +- install.sh +- update.sh +- readme.md +- config.yml + + +### Code Guidelines +*** +#### Your code, your style, my review + +Here at jailman, we value people having their own style. But your code needs to be reviewable and editable by others too. For that reason, we have a few basic coding guidelines + +* **Always** explain regex in a comment within your code. +* Write simple code and don't try to impress. +* We will run (Basic) automated reformating of code once in a while. +* Document your changes in your code and if need be, on the wiki. +* All PR's should be able to pass our automated shellcheck. +* It's okey to add shellcheck ignores, but only AFTER you checked the warning! + +#### jail requirements + +- Jails should always save user-specific data in a persistant location. Which is the location specified in the config.yml file under "config:", which is automatically mounted to every jail under /config. There should be no user specific data in the jail itself +- Jails should not require the user to edit any config file themselves. All config changes should be automated +- Jails should not use default passwords, the user should always be forced(!) to put credentials in config.yml manually + + +### Review Guidelines +*** +Even us review gods need some guidelines once in a while. + +* Let people learn from their mistakes +* Review instead of merging without comments +* Abide by these guidelines in your review +* Tests exist for a reason. Don't merge with test-failures + + + +### Todo vs Feature vs bug: +*** +Please take note of the difference between a TODO and Feature + +* Bug: An unexpected behavior of the script or a crash. Including, but not limited to, errors and warnings. +* Todo: When you come across something that needs tweaking/adding during development, is not an unexpected behavior +* Feature: When you, out of personal preference, want something added or changed. + +### That's it! +*** +Someone will come along and review the changes. If everything looks good then they will merge it with the main repo. If you need any help don't be afraid to ask in the discord channel: [https://discord.gg/tFcTpBp](https://discord.gg/tFcTpBp) diff --git a/docs/ISSUE_TEMPLATE.md b/docs/ISSUE_TEMPLATE.md new file mode 100644 index 00000000..89fb703e --- /dev/null +++ b/docs/ISSUE_TEMPLATE.md @@ -0,0 +1,13 @@ +# Issue Template + +## Description + +### Detailed Bug Report +It helps if you include any relevant code / config (for describing how new features should work), images, gifs, or youtube videos! + +### Steps to Reproduce +Please enter the steps to reproduce the bug or behaviour: + +1. +2. +3. \ No newline at end of file diff --git a/docs/PULL_REQUEST_TEMPLATE.md b/docs/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 00000000..ed2f76f0 --- /dev/null +++ b/docs/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,16 @@ +# Pull Request Template + +### Purpose +_Describe the problem the PR fixes or the feature it introduces_
+_Don't forget to use "Fixes #issuenumber" to select issues and auto close them on merge_ + +### Notes: +_Please enter any other relevant information here_ + +### Please make sure you have followed the self checks below before submitting a PR: + +- [ ] Code is sufficiently commented +- [ ] Code is indented with tabs and not spaces +- [ ] The PR does not bring up any new errors +- [ ] The PR has been tested +- [ ] Any new files are named using lowercase (to avoid issues on case sensitive file systems) diff --git a/docs/Readme.md b/docs/Readme.md index 6b48c6a6..b7df9438 100644 --- a/docs/Readme.md +++ b/docs/Readme.md @@ -5,7 +5,7 @@ --- -[![GitHub last commit](https://img.shields.io/github/last-commit/ornias1993/jailman/dev.svg)](https://github.com/ornias1993/jailman/commits/dev) [![Krihelimeter](http://www.krihelinator.xyz/badge/ornias1993/jailman)](http://www.krihelinator.xyz/repositories/ornias1993/jailman) [![GitHub Release](https://img.shields.io/github/release/ornias1993/jailman.svg)](https://github.com/ornias1993/jailman/releases/latest) [![License: GPL v2](https://img.shields.io/badge/License-GPL%20v2-blue.svg)](https://github.com/ornias1993/jailman/blob/master/docs/LICENSE.GPLV2) [![License](https://img.shields.io/badge/License-BSD%202--Clause-orange.svg)](https://github.com/ornias1993/jailman/blob/master/docs/LICENSE.BSD2) +[![GitHub last commit](https://img.shields.io/github/last-commit/ornias1993/jailman/dev.svg)](https://github.com/ornias1993/jailman/commits/dev) [![GitHub Release](https://img.shields.io/github/release/ornias1993/jailman.svg)](https://github.com/ornias1993/jailman/releases/latest) [![License: GPL v2](https://img.shields.io/badge/License-GPL%20v2-blue.svg)](https://github.com/ornias1993/jailman/blob/master/docs/LICENSE.GPLV2) [![License](https://img.shields.io/badge/License-BSD%202--Clause-orange.svg)](https://github.com/ornias1993/jailman/blob/master/docs/LICENSE.BSD2) ## Intro diff --git a/docs/config options.md b/docs/config options.md index 8c0c4b93..111ba452 100644 --- a/docs/config options.md +++ b/docs/config options.md @@ -35,10 +35,14 @@ Some datasets are auto created and can not be changed from the config file. This ## General config options ### Networking + +Please be aware that dhcp is not actively supported, many of the jails depend on having a fixed IP-adress in the config file. +Some also depend on other jails having a fixed IP in the config file. Use of DHCP is on your own risk and might not work. + - ip4_addr: To set a static IP (recommended), enter the desired ip address here. Leave blank (or remove the line) for DHCP. -- gateway: Set the gateway IP for static IP setup. Leave blank (or remove the line) for DHCP. +- gateway: Set the gateway IP for static IP setup. Leave blank (or remove the line) for DHCP. ### Advanced - interfaces: Set the "interfaces" flag for iocage. Example: `vnet0:bridge0` (optional) -- dhcp: Set to force DHCP (not required for DHCP, see above) -- pkgs: Override the to-be-install packages for this jail (might break now or break updates) +- dhcp: Set to "on" to force DHCP (not required for DHCP, see above) +- pkgs: Override the to-be-install packages for this jail (might break now or break updates) \ No newline at end of file diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 00000000..f2dbf1aa --- /dev/null +++ b/docs/index.md @@ -0,0 +1,5 @@ +# Introduction +Welcome to Jailam. An open source effort to create an easy management tool for Freenas Jails. + +As this project is in its early stages, this wiki will serve the purpose of providing a foundation and a almost (not) up-to-date scripting reference to the underlying structure of jailman. + diff --git a/docs/jails/jails.md b/docs/jails/jails.md new file mode 100644 index 00000000..9daeafb9 --- /dev/null +++ b/docs/jails/jails.md @@ -0,0 +1 @@ +test diff --git a/docs/test.md b/docs/test.md new file mode 100644 index 00000000..e440e5c8 --- /dev/null +++ b/docs/test.md @@ -0,0 +1 @@ +3 \ No newline at end of file diff --git a/jails/bitwarden/readme.md b/jails/bitwarden/readme.md index b698d7fc..4438ddc8 100755 --- a/jails/bitwarden/readme.md +++ b/jails/bitwarden/readme.md @@ -1,4 +1,7 @@ -# Original README from the Bitwarden_rs github: +# Bitwarden_RS + + +## Original README from the Bitwarden_rs github: https://github.com/dani-garcia/bitwarden_rs diff --git a/jails/influxdb/readme.md b/jails/influxdb/readme.md index 446c9c9f..dd4c5003 100644 --- a/jails/influxdb/readme.md +++ b/jails/influxdb/readme.md @@ -1,4 +1,6 @@ -# Original README from the influxdb github: +# InfluxDB + +## Original README from the influxdb github: https://github.com/influxdata/influxdb diff --git a/jails/kms/readme.md b/jails/kms/readme.md index 7c55dd7f..298e6987 100755 --- a/jails/kms/readme.md +++ b/jails/kms/readme.md @@ -1,5 +1,6 @@ +# Py-KMS -# Original README from the py-kms github: +## Original README from the py-kms github: https://github.com/SystemRage/py-kms diff --git a/jails/lidarr/readme.md b/jails/lidarr/readme.md index d73b6bff..6347fad9 100755 --- a/jails/lidarr/readme.md +++ b/jails/lidarr/readme.md @@ -1,4 +1,6 @@ -# Original README from the lidarr github: +# Lidarr + +## Original README from the lidarr github: https://github.com/lidarr/Lidarr diff --git a/jails/mariadb/readme.md b/jails/mariadb/readme.md index 532bf0b6..d486c586 100755 --- a/jails/mariadb/readme.md +++ b/jails/mariadb/readme.md @@ -1,4 +1,6 @@ -# Original README from the mariadb github: +# MariaDB + +## Original README from the mariadb github: https://github.com/MariaDB/server/ diff --git a/jails/nextcloud/README.md b/jails/nextcloud/readme.md old mode 100755 new mode 100644 similarity index 99% rename from jails/nextcloud/README.md rename to jails/nextcloud/readme.md index aa4ee344..c8dc67db --- a/jails/nextcloud/README.md +++ b/jails/nextcloud/readme.md @@ -1,4 +1,6 @@ -# Original README from the Upstream Nextcloud-iocage install script: +# Nextcloud + +## Original README from the Upstream Nextcloud-iocage install script: https://github.com/danb35/freenas-iocage-nextcloud diff --git a/jails/organizr/readme.md b/jails/organizr/readme.md index 19525226..675769af 100755 --- a/jails/organizr/readme.md +++ b/jails/organizr/readme.md @@ -1,4 +1,6 @@ -# Original README from the Organizr github repo: +# Organizr + +## Original README from the Organizr github repo: https://github.com/causefx/Organizr diff --git a/jails/radarr/readme.md b/jails/radarr/readme.md index 14337343..9dc41df9 100755 --- a/jails/radarr/readme.md +++ b/jails/radarr/readme.md @@ -1,4 +1,6 @@ -# Original README from the radarr github: +# Radarr + +## Original README from the radarr github: https://github.com/Radarr/Radarr diff --git a/jails/sonarr/readme.md b/jails/sonarr/readme.md index b6f379b6..0edcb9cb 100755 --- a/jails/sonarr/readme.md +++ b/jails/sonarr/readme.md @@ -1,4 +1,6 @@ -# Original README from the sonarr github: +# Sonarr + +## Original README from the sonarr github: https://github.com/Sonarr/Sonarr diff --git a/jails/tautulli/readme.md b/jails/tautulli/readme.md index db612709..6d4c4855 100755 --- a/jails/tautulli/readme.md +++ b/jails/tautulli/readme.md @@ -1,4 +1,6 @@ -# Original README from the tautulli github: +# Tautulli + +## Original README from the tautulli github: https://github.com/Tautulli/Tautulli diff --git a/jails/transmission/readme.md b/jails/transmission/readme.md index a2573b3d..55f50f47 100755 --- a/jails/transmission/readme.md +++ b/jails/transmission/readme.md @@ -1,4 +1,6 @@ -# Original README from the transmission github: +# Transmission + +## Original README from the transmission github: https://github.com/transmission/transmission diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 00000000..8bccf8b0 --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1,23 @@ +# Project Information +site_name: JailMan +site_description: 'Project Design and Documentation for development' +site_author: 'Ornias1993' +site_url: 'https://ornias1993.github.io/jailman/' + +# Repository +repo_name: 'ornias1993/jailman' +repo_url: 'https://github.com/Ornias1993/jailman/' +edit_uri: 'edit/dev/docs/' + +theme: + name: 'material' + features: + - tabs + language: 'en' + +markdown_extensions: + - admonition + - codehilite: + guess_lang: false + - toc: + permalink: true \ No newline at end of file diff --git a/wiki/Home.md b/wiki/Home.md deleted file mode 100644 index ae97c2b6..00000000 --- a/wiki/Home.md +++ /dev/null @@ -1,3 +0,0 @@ -Welcome to the jailman wiki! - -This wiki is automatically generated from the .md files located in either the /wiki or the /jails// directories. diff --git a/wiki/test.md b/wiki/test.md deleted file mode 100644 index 45c0a5a8..00000000 --- a/wiki/test.md +++ /dev/null @@ -1 +0,0 @@ -wiki test placeholder