diff --git a/.github/workflows/CI.yml b/.github/workflows/CI.yml index 8a5cb3a..705526e 100644 --- a/.github/workflows/CI.yml +++ b/.github/workflows/CI.yml @@ -4,61 +4,77 @@ on: [push, pull_request] jobs: - markdownlint: + lint: runs-on: ubuntu-latest steps: - - uses: actions/checkout@v1 - - name: markdownlint + - uses: actions/checkout@v4 + - name: Set up Python + uses: actions/setup-python@v5 + with: + python-version: 3.x + - name: Install linters run: | - echo '{"default": true,"line_length": false,"no-inline-html": false,"first-line-h1": false, "code-block-style": false, "ul-indent": false}' > .markdownlint.json - while IFS= read -r line; do echo "Linting ${line}"; docker run --rm -v "${PWD}:/markdown" -v "${PWD}:${PWD}" 06kellyjac/markdownlint-cli "${PWD}/${line}" || exit 1; done < <(git ls-files '*.md') + pip install $(grep yamllint requirements.txt) + - name: Lint YAML files + run: yamllint . + - name: Lint Markdown files + uses: DavidAnson/markdownlint-cli2-action@v15 + with: + globs: "**/*.md" - yamllint: + build: + needs: lint runs-on: ubuntu-latest steps: - - uses: actions/checkout@v1 - - name: yamllint - run: | - while IFS= read -r line; do echo "Linting ${line}"; docker run --rm -v "${PWD}:${PWD}" sdesbure/yamllint yamllint -d '{extends: default, rules: {document-start: {present: false}, line-length: disable}}' "${PWD}/${line}" || exit 1; done < <(git ls-files '*.yaml' '*.yml') + - name: Checkout repository + uses: actions/checkout@v4 + with: + fetch-depth: 0 + - name: Setup python + uses: actions/setup-python@v5.0.0 + with: + python-version: 3.x + - name: Install dependencies + run: pip install -r requirements.txt + - name: Build documentation + run: mkdocs build deploy: - needs: [markdownlint, yamllint] + if: github.event_name == 'push' && contains(fromJson('["refs/heads/master", "refs/heads/main"]'), github.ref) + needs: build + name: Deploy docs runs-on: ubuntu-latest steps: - - uses: actions/checkout@v1 - - name: mkdocs - run: | - docker run --name="patch" --entrypoint="" squidfunk/mkdocs-material pip install mkdocs-git-revision-date-localized-plugin git+git://github.com/g-provost/lightgallery-markdown#egg=lightgallery - docker commit --change 'ENTRYPOINT ["mkdocs"]' patch selfhosters/builder - docker run --rm -v ${PWD}/site:/site -v ${PWD}:/docs selfhosters/builder build --verbose --clean --strict - sudo cp ${PWD}/CNAME ${PWD}/site/ - - name: deploy - if: github.ref == 'refs/heads/master' - uses: peaceiris/actions-gh-pages@v2.5.0 - env: - ACTIONS_DEPLOY_KEY: ${{ secrets.ACTIONS_DEPLOY_KEY }} - # PERSONAL_TOKEN: ${{ secrets.PERSONAL_TOKEN }} - # GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} - PUBLISH_BRANCH: gh-pages - PUBLISH_DIR: ./site + - name: Checkout repository + uses: actions/checkout@v4 with: - emptyCommits: "false" - - make_public: - needs: deploy - runs-on: ubuntu-latest - if: github.ref == 'refs/heads/master' - steps: - - name: clear CF cache - run: | - curl -X GET "https://api.cloudflare.com/client/v4/user/tokens/verify" \ - -H "Authorization: Bearer ${{ secrets.CLOUDFLARE_CLEAR_CACHE }}" \ - -H "Content-Type:application/json" - - name: notify discord - uses: appleboy/discord-action@master + fetch-depth: 0 + sparse-checkout: | + docs + - name: Setup python + uses: actions/setup-python@v5.0.0 with: - webhook_id: ${{ secrets.WEBHOOK_ID }} - webhook_token: ${{ secrets.WEBHOOK_TOKEN }} - username: "Selfhosters.net" - avatar_url: "https://avatars3.githubusercontent.com/u/52747488?s=200" - message: "New stuff has been added to the wiki" + python-version: 3.x + - name: Install dependencies + run: pip install -r requirements.txt + - name: Deploy to GitHub Pages + run: mkdocs gh-deploy --force + +# make_public: +# needs: builds +# runs-on: ubuntu-latest +# if: github.ref == 'refs/heads/master' +# steps: +# - name: clear CF cache +# run: | +# curl -X GET "https://api.cloudflare.com/client/v4/user/tokens/verify" \ +# -H "Authorization: Bearer ${{ secrets.CLOUDFLARE_CLEAR_CACHE }}" \ +# -H "Content-Type:application/json" +# - name: notify discord +# uses: appleboy/discord-action@master +# with: +# webhook_id: ${{ secrets.WEBHOOK_ID }} +# webhook_token: ${{ secrets.WEBHOOK_TOKEN }} +# username: "Selfhosters.net" +# avatar_url: "https://avatars3.githubusercontent.com/u/52747488?s=200" +# message: "New stuff has been added to the wiki" diff --git a/.markdownlint-cli2.yaml b/.markdownlint-cli2.yaml new file mode 100644 index 0000000..cfb5b3c --- /dev/null +++ b/.markdownlint-cli2.yaml @@ -0,0 +1,8 @@ +config: + MD007: + indent: 4 + line-length: false + no-inline-html: false + code-block-style: false +ignores: + - venv/** diff --git a/.yamllint b/.yamllint new file mode 100644 index 0000000..0b41e4d --- /dev/null +++ b/.yamllint @@ -0,0 +1,15 @@ +extends: default + +ignore: | + venv/ + +rules: + document-start: disable + truthy: disable + comments: + min-spaces-from-content: 1 + quoted-strings: + quote-type: double + required: only-when-needed + line-length: + max: 160 diff --git a/docs/commands.md b/docs/commands.md index 6a03508..99625af 100644 --- a/docs/commands.md +++ b/docs/commands.md @@ -1,5 +1,5 @@ -# Nice to know Unraid commands +# Nice-to-know Unraid commands ## Docker service diff --git a/docs/docker/templating/templating.md b/docs/docker/templating/templating.md index 68cf820..bb34299 100644 --- a/docs/docker/templating/templating.md +++ b/docs/docker/templating/templating.md @@ -1,58 +1,60 @@ -# Writing a template compatible for unraid +# Writing a template compatible for Unraid -This is an effort to collect information from [Squids FAQ](https://forums.unraid.net/topic/57181-docker-faq/){target=_blank}. +This is an effort to collect information from [Squids FAQ](https://forums.unraid.net/topic/57181-docker-faq/){target=_ +blank}. -## 0. Enabling Template Authoring Mode +## Prerequisites -In order to have a smooth experience creating templates I highly recommend enabling `Template Authoring Mode`, it allows you to see the XML in clear-text and some other small neat tricks we might need to come back to. +### Enabling Template Authoring Mode -This process requires you to shut down the docker service for a short while, as unraid doesn't let us change the setting with the service running. +In order to have a smooth experience creating templates I highly recommend enabling `Template Authoring Mode`, it allows +you to see the XML in clear-text and some other small neat tricks we might need to come back to. + +This process requires you to shut down the docker service for a short while, as Unraid doesn't let us change the setting +with the service running. ![!docker-off](tmpl-docker-off.png) When the docker service is successfully shut down, enable advanced view. ![!docker-adv-view](tmpl-docker-adv-view.png) -We can now enable authoring mode, you can also toggle the docker service back on. +We can now enable authoring mode, you can also toggle the docker service back on. ![!docker-author-mode](tmpl-docker-auth-mode.png) -## 1. Choosing which way to go - -We can create a template in two ways: - -1. Convert a template generated by Community Application, the CA way -2. Work directly with the XML - -## The CA way +## Auto-generating from Docker image -### 1.1.0 Enabling search from dockerHub +### 1. Search from Docker Hub -In order to have Community Applications (hereby referenced as CA) generate a template, we need to enable additional search from dockerHub. You do this by opening CA, and press the settings button on the sidebar. -![!ca-side-bar](tmpl-ca-bar.png) +??? note "Make sure you can retrieve search results from Docker Hub" -Enable additional search. -![!ca-dHub-on](tmpl-ca-hub-on.png) + In order to have Community Applications generate a template, we need to enable additional search from Docker Hub. You do this by opening CA, and press the settings button on the sidebar, and enabling additional search. + ![!ca-side-bar](tmpl-ca-bar.png) + ![!ca-dHub-on](tmpl-ca-hub-on.png) -### 1.1.1 Search from DockerHub - -For this guide I will use `domistyle/idrac6` as an example. Go back to CA, and type the image you want to create a template for in the search bar (If you get a match now, chances are, it is already in CA) and press `Get More Results From DockerHub`. +For this guide I will use `domistyle/idrac6` as an example. Go back to CA, and type the image you want to create a +template for in the search bar (If you get a match now, chances are, it is already in CA) and +press `Get More Results From Docker Hub`. ![!ca-from-dHub](tmpl-ca-from-dHub.png) -CA shows results for both the image-maintainer, and image-name. Which means that we will get similar results. Press the download to disk icon, and let CA convert it. +Community Applications shows results for both the image-maintainer, and image-name. Which means that we will get similar +results. Press the download to disk icon, and let Community Applications convert it. ![!ca-result-dHub](tmpl-ca-result-dHub.png) -For this one CA didn't do a very good job in converting it (It reads the Dockerfile for volumes, expose, publish etc.), however we can modify it with the template editor in Unraid. +For this one Community Applications didn't do a very good job in converting it (It reads the Dockerfile for volumes, +expose, publish etc.), however we can modify it with the template editor in Unraid. ![!converted](tmpl-converted.png) -### 1.1.2 Editing the template +### 2. Edit the template -To see what we need to edit, we can most often refer to the [readme](https://github.com/DomiStyle/docker-idrac6/blob/master/README.md#usage) of the container +To see what we need to edit, we can most often refer to +the [readme](https://github.com/DomiStyle/docker-idrac6/blob/master/README.md#usage) of the container (Including a screenshot in case the readme changes) ![!cont-readme](tmpl-cont-readme.png). !!! note "Get to know the template editor, its very handy. Also for managing existing templates." -I'm going through the rest of this guide with a mix of views (to remove clutter from images). If some of the settings you see in a screenshot isn't showing to you, enable advanced view. +I'm going through the rest of this guide with a mix of views (to remove clutter from images). If some of the settings +you see in a screenshot isn't showing to you, enable advanced view. ![!cont-adv-mode](tmpl-cont-adv-mode.png) #### Variables @@ -62,58 +64,66 @@ I will start with adding the variables, just because those are on the top of the To add the `IDRAC_HOST` variable, we are going to press the `Add another Path, Port, Variable or Device` link. ![!cont-add-var](tmpl-cont-add-var.png) -We need to change the Config Type to Variable, then we can start adding values. There is a lot going on here, but it is all going to make sense in the end. +We need to change the Config Type to Variable, then we can start adding values. There is a lot going on here, but it is +all going to make sense in the end. -* ==Name== The name for the variable, this is to help the user identifying what this variable does. +- `Name` - The name for the variable, this is to help the user identifying what this variable does. -* ==Key== This is the actual variable, so we are putting `IDRAC_HOST` here. +- `Key` - This is the actual variable, so we are putting `IDRAC_HOST` here. -* ==Value== We don't fill this, this is for the user. +- `Value` - We don't fill this, this is for the user. -* ==Default Value== We could fill this, but since we can only do an estimated guess on what a users idrac host is, we are going to skip it. +- `Default Value` - We could fill this, but since we can only do an estimated guess on what a users idrac host is, we + are going to skip it. -* ==Description== Usually I don't fill this field with this long of a text, but the documentation of the container had a good one, so I'm using it. +- `Description` - Usually I don't fill this field with this long of a text, but the documentation of the container had a + good one, so I'm using it. -* ==Display== This decides if the "average user" (someone that isn't using advanced view) is going to see this variable. +- `Display` - This decides if the "average user" (someone that isn't using advanced view) is going to see this variable. -* ==Required== I set this to yes because I know the container wont work without it set. The fact that the documentation tells me its required also helped in the decision. +- `Required` - I set this to yes because I know the container wont work without it set. The fact that the documentation + tells me its required also helped in the decision. -* ==Password Mask== This isn't a password, so it doesn't need to have its value masked behind asterisk (*). +- `Password Mask` - This isn't a password, so it doesn't need to have its value masked behind asterisk (*). ![!cont-add-var-menu](tmpl-cont-add-var-menu.png) ??? example "Here are some screenshots on how I added the other required variables" ![!cont-add-var-menu-user](tmpl-cont-add-var-menu-user.png) - Here I set the Default value as root, since I know that's the default username on idrac + Here I set the Default value as root, since I know that's the default username on idrac ![!cont-add-var-menu-password](tmpl-cont-add-var-menu-password.png) Here I set the Default value as calvin, since I know that's the default password on idrac, I also enabled Password Mask #### Volumes -Next is adding the volumes. We press the same `Add another Path, Port, Variable or Device` link, but we don't need to change the config type this time. +Next is adding the volumes. We press the same `Add another Path, Port, Variable or Device` link, but we don't need to +change the config type this time. The fields we can add here is mostly the same, but with the "Volume" type some of them are voided. Like password mask. If it's a "proper" appdata location, I set required to yes -* ==Access Mode== Defines how the container should have access to this volume. Almost always `read/write` +- `Access Mode` - Defines how the container should have access to this volume. Almost always `read/write` ![!cont-add-vol-menu](tmpl-cont-add-vol-menu.png) #### Ports -Now its time for the ports. We press the same `Add another Path, Port, Variable or Device` link. This time we need to change the config type to `Port`. +Now it is time for the ports. We press the same `Add another Path, Port, Variable or Device` link. This time we need to +change the config type to `Port`. -The documentation for this container says we can use port 5800 to access the interface, so that's the port we are going to add. It also mentions the VNC port, but most users wont need this. +The documentation for this container says we can use port 5800 to access the interface, so that's the port we are going +to add. It also mentions the VNC port, but most users wont need this. -* ==Connection Type== Always `TCP`, unless specified otherwise. +- `Connection Type` - Always `TCP`, unless specified otherwise. ![!tmpl-cont-add-port-menu.png](tmpl-cont-add-port-menu.png) #### Metadata -Now you have a basic template. This might be enough for your own usage, but in order to add it to CA we should add some spice to the template. +Now you have a basic template. This might be enough for your own usage, but in order to add it to Community Applications +we should add some spice to the template. As you can see there are lots of fields we can fill in with the template editor. ![!cont-meta-empty](tmpl-cont-meta-empty.png) @@ -126,23 +136,27 @@ I used the dropdown to set the categories as I saw fit. I set the support thread as the issue page of the project. -!!! danger "Do not do this if you are creating a template for your own container, create a support thread on the unraid forums and use that link" +!!! danger "Do not do this if you are creating a template for your own container, create a support thread on the Unraid +forums and use that link" The project page is usually the GitHub link to the container. I have yet to change the Icon URL, because I need to create an icon. -`WebUI` Should be filled with the *container* port, unraid should do the translation `http://[IP]:[PORT:5800]`. If this is an https enabled port, set the url to use https. +`WebUI` Should be filled with the *container* port, Unraid should do the translation `http://[IP]:[PORT:5800]`. If this +is an https enabled port, set the url to use https. For Post arguments and Extra Parameters, you should know if you need to fill this. -!!! note "There is more information on this in the [Manual way](#121-fill-the-base) part" +!!! note "There is more information on this in the [Manual way](#2-fill-the-base) part" ![!cont-meta-filled](tmpl-cont-meta-filled.png) -### 1.1.3 Grab the XML +### 3. Grab the XML -Once you have filled all the fields, and set the ports, variables and volumes as good as you can, you can press the `Save` button, this takes you to a page where can see the xml in plain-text. Don't worry, it also saves the xml to your OS disk. Bellow is the XML generated by the procedure above. +Once you have filled all the fields, and set the ports, variables and volumes as good as you can, you can press +the `Save` button, this takes you to a page where can see the xml in plain-text. Don't worry, it also saves the xml to +your OS disk. Bellow is the XML generated by the procedure above. ??? example "Extracted XML" @@ -249,9 +263,10 @@ Once you have filled all the fields, and set the ports, variables and volumes as ``` -### 1.1.4 Shave off the XML +### 4. Clean the XML -CA adds a lot of stuff that is not necessary for a template, but which Unraid uses to actually run and present the container. +Community Applications adds a lot of stuff that is not necessary for a template, but which Unraid uses to actually run +and present the container. My first steps in removing unnecessary tags is to delete tags that are closed without value, like ``. @@ -352,7 +367,8 @@ My first steps in removing unnecessary tags is to delete tags that are closed wi ``` -Since I prefer using just the `Config` tags, I also remove the tags `Networking`, `Data` and `Environment` together with it's content. +Since I prefer using just the `Config` tags, I also remove the tags `Networking`, `Data` and `Environment` together with +it's content. ??? example "XML after" @@ -423,11 +439,12 @@ Unless you know what shell the container uses, also remove `Shell`. ``` !!! note "More spice" - It's worth reading [1.1.2 Add a Config](#122-add-a-config) and [Tips and tricks](#2-additional-tags-and-neat-tricks) to see if any of that applies to your template. + It's worth reading [Add a Config Entry](#3-add-a-config-entry) and [XML Field Explanations](#xml-field-explanations) to + see if any of that applies to your template. -## The Manual way +## Manually writing a template -### 1.2.0 Starting from "scratch" +### 1. Starting from "scratch" To make sure we don't miss anything, we are going to start from a baseXML. @@ -458,55 +475,66 @@ I'm using the same [example-container](https://hub.docker.com/r/domistyle/idrac6 ``` -### 1.2.1 Fill the base +### 2. Fill the base -Since you are here browsing the "hard" way, I'm assuming you know some, if not most of the Docker terminology used going forward. +Since you are here browsing the "hard" way, I'm assuming you know some, if not most of the Docker terminology used going +forward. Filling the baseXML above is pretty straight forward, however the tags expect the following: -* ==Name== The name for the container, preferably in lowercase. +- `Name` - The name for the container, preferably in lowercase. -* ==Repository== The name of the image to pull from dockerHub (other repositories work). e.g. `domistyle/idrac6` +- `Repository` - The name of the image to pull from Docker Hub (other repositories work). e.g. `domistyle/idrac6` -* ==Registry== Link to the dockerHub page for this container. e.g. `https://hub.docker.com/r/domistyle/idrac6/` +- `Registry` - Link to the Docker Hub page for this container. e.g. `https://hub.docker.com/r/domistyle/idrac6/` -* ==Support== A link to a support thread on the unraid forums for the container +- `Support` - A link to a support thread on the Unraid forums for the container -* ==Project== Link to the GitHub page (or the homepage of the project) e.g. `https://github.com/DomiStyle/docker-idrac6/` +- `Project` - Link to the GitHub page (or the homepage of the project) + e.g. `https://github.com/DomiStyle/docker-idrac6/` -* ==Overview== Basic description of the project. e.g. - > Allows access to the iDRAC 6 console without installing Java or messing with Java Web Start. Java is only run inside of the container and access is provided via web interface or directly with VNC. +- `Overview` - Basic description of the project. e.g. + > Allows access to the iDRAC 6 console without installing Java or messing with Java Web Start. Java is only run inside + of the container and access is provided via web interface or directly with VNC. -* ==WebUI== Which container-port a webui might be on. e.g. `http://[IP]:[PORT:5800]` Unraid will translate this string to the IP of the server, and the host-port set for container-port 5800 +- `WebUI` - Which container-port a web UI might be on. e.g. `http://[IP]:[PORT:5800]` Unraid will translate this string + to the IP of the server, and the host-port set for container-port 5800 -* ==Icon== URL to an icon, personally I prefer them in png. It has to be loaded over https. e.g. `https://raw.githubusercontent.com/selfhosters/unRAID-CA-templates/master/templates/img/chevereto.png` -![chevereto icon](https://raw.githubusercontent.com/selfhosters/unRAID-CA-templates/master/templates/img/chevereto.png){: style="height:1em"} +- `Icon` URL to an icon, personally I prefer them in png. It has to be loaded over https. + e.g. `https://raw.githubusercontent.com/selfhosters/unRAID-CA-templates/master/templates/img/chevereto.png` + ![chevereto icon](https://raw.githubusercontent.com/selfhosters/unRAID-CA-templates/master/templates/img/chevereto.png){: + style="height:1em"} -* ==ExtraParams== Parameters sent with the `docker run` command. e.g. `--restart unless-stopped` +- `ExtraParams` - Parameters sent with the `docker run` command. e.g. `--restart unless-stopped` -* ==PostArgs== Command to run inside the container after start. e.g. `/bin/sh -c 'apk update && apk add ipmitool && telegraf'` -[See valid example](../../telegraf/ipmi#telegraf){target=_blank} +- `PostArgs` - Command to run inside the container after start. + e.g. `/bin/sh -c 'apk update && apk add ipmitool && telegraf'` + [See valid example](../../telegraf/ipmi#telegraf){target=_blank} -* ==DonateText== Text to show with the donate button. +- `DonateText` - Text to show with the donate button. -* ==DonateLink== URL for donations. +- `DonateLink` - URL for donations. -* ==Network== Usually `bridge` if not specified by the image maintainer +- `Network` - Usually `bridge` if not specified by the image maintainer -* ==TemplateURL== Url to the template. If it is a PR to our repo, set it to `https://raw.githubusercontent.com/selfhosters/unRAID-CA-templates/master/templates/.xml` and replace `` with the actual name of the container (again, in lowercase). +- `TemplateURL` - URL to the template. If it is a PR to our repo, set it + to `https://raw.githubusercontent.com/selfhosters/unRAID-CA-templates/master/templates/.xml` and + replace `` with the actual name of the container (again, in lowercase). !!! warning Has to be a raw link for GitHub. -* ==DonateImg== URL to donation image. +- `DonateImg` URL to donation image. -### 1.2.2 Add a Config +### 3. Add a Config entry There are two ways to achieve this, but I'm only going to focus on one of them. The syntax is like this: ```xml - + + ``` This syntax spans over all the 4 config types, some attributes changes meaning depending on the `Type`. @@ -515,56 +543,205 @@ This syntax spans over all the 4 config types, some attributes changes meaning d The volume specific values are: -* ==Target== The container path for the volume. e.g. `/config` +- `Target` - The container path for the volume. e.g. `/config` -* ==Mode== What permissions to use for the volume. - * `rw` as ReadWrite - * `ro` as ReadOnly - * Slave options are also supported +- `Mode` - What permissions to use for the volume. + - `rw` as ReadWrite + - `ro` as ReadOnly + - Slave options are also supported -* ==Type== Always `Path`. +- `Type` - Always `Path`. #### Add a Variable -* ==Target== The variable. e.g. `IDRAC_HOST` +- `Target` - The variable. e.g. `IDRAC_HOST` -* ==Type== Always `Variable`. +- `Type` - Always `Variable`. #### Add a Port -* ==Target== The container port. e.g. `80` +- `Target` - The container port. e.g. `80` -* ==Type== Always `Port`. +- `Type` - Always `Port`. #### Shared attributes -* ==Name== The name that shows in the Unraid template manager. e.g. `Appdata`, `PUID`, `WebUI` +- `Name` - The name that shows in the Unraid template manager. e.g. `Appdata`, `PUID`, `WebUI` -* ==Description== A more detailed description on this Config. e.g `Appdata location`, `PUID`, `WebUI` +- `Description` - A more detailed description on this Config. e.g `Appdata location`, `PUID`, `WebUI` -* ==Default== Suggested value for the Config. e.g. `/mnt/user/appdata/idrac`, `99`, `8080` +- `Default` - Suggested value for the Config. e.g. `/mnt/user/appdata/idrac`, `99`, `8080` -* ==Display== How the volume is shown to the user. - * `always` Always show the volume, can be edited and deleted in basic view. - * `always-hide` Always show the volume, can *not* be edited and deleted in basic view. - * `advanced` Shows when the user presses `Show more settings ...`, can be edited and deleted in basic view. - * `advanced-hide` Shows when the user presses `Show more settings ...`, can *not* be edited and deleted in basic view. +- `Display` - How the volume is shown to the user. + - `always` Always show the volume, can be edited and deleted in basic view. + - `always-hide` Always show the volume, *cannot* be edited and deleted in basic view. + - `advanced` Shows when the user presses `Show more settings ...`, can be edited and deleted in basic view. + - `advanced-hide` Shows when the user presses `Show more settings ...`, *cannot* be edited and deleted in basic + view. -* ==Required== If the user is able to continue without specifying the value. `true` or `false` +- `Required` If the user is able to continue without specifying the value. `true` or `false` -* ==Mask== If the value should be masked behind asterisks, only really useful on variables. `true` or `false` +- `Mask` If the value should be masked behind asterisks, only really useful on variables. `true` or `false` -### 2 Additional tags, and neat tricks +## Tips and Tricks -CA supports some extra tags that enhances the experience. They are all listed in the [XML schema post](https://forums.unraid.net/topic/38619-docker-template-xml-schema/){target=_blank}. +### Limit Config entry to predefined values -* ==Beta== Gives the application a warning in CA with the following text `This application has been marked as being Beta. This does NOT neccessarily mean that there will be issues.`. `true` or `false` +For a Config field, instead of allowing users to type in a value, you can provide a dropdown list of options. In +the `Default` attribute, list the available values separated by the pipe (`|`) character (e.g. `Default="true|false"`). +This is *highly recommended* for boolean values. -* ==Branch== Prompts the user to choose a dockerHub tag. e.g. [linuxserver/emby.xml](https://github.com/linuxserver/docker-templates/blob/7e87d46ca1edcb0371b5f5f3a663735242d042ce/linuxserver.io/emby.xml#L6-L13){target=_blank} +### Categorization tool -The template manager also support setting a set of predefined values, often uses in conjunction with variables that expect bools. Defined by separating the values with `|`. e.g. `true|false`. Has to be set in the default attribute. +It's preferred to categorize your template, and recommended to use the "Application Categorizer" plugin to generate the +appropriate tags. +![!templ-application-categorizer](tmpl-app-cat.png) -#### 2.1 Categories +## XML field explanations -It's preferred to categories your template, use the `Application Categorizer` plugin in CA to do this, it generates the tags we need for us. -![!templ-application-categorizer](tmpl-app-cat.png) +This is an alphabetical, non-exhaustive list of the fields that can be provided in the `` section of the XML +template (as of Unraid 6.10+), and what they do. For a full list, see +the [XML schema post](https://forums.unraid.net/topic/38619-docker-template-xml-schema/){target=_blank}. + +Please note that a number of these fields are optional, and you should only include them if they are relevant to your +container. + +- `Banner` - A URL to a banner image for the container. This should be a direct link to an image file, typically a PNG + file. + +- `Beta` - Gives the application a warning in Community Applications with the following + text `This application has been marked as being Beta. This does NOT neccessarily mean that there will be issues.`. Set + to either `true` or `false`. + +- `Branch` - Offer different versions of the container to the user. This corresponds to different tags on the Docker + image. For example, offer a `latest` branch and a `beta` branch, or a version of the container that uses different GPU + drivers. + + ??? info "Screenshot" + + ![!templ-branches](tmpl-branches.png) + +- `Tag` - The tag of the Docker image to use. It is typical to include at least a `latest` tag, but other tags can be + used as well. + +- `TagDescription` - A description of the tag. This is displayed to the user when they are installing the container. + +- `Category` - A list of categories that this template belongs to. Please use + the ["Application Categorizer" plugin](#categorization-tool) to generate the appropriate tags. Proper categories make + your template more discoverable in the Community Applications store. + +- `Changes` - A changelog for the template. This should be used for changes to the template, *NOT* changes to the + application itself. This is displayed in the Community Applications store entry. + This [only supports Markdown](https://forums.unraid.net/topic/38431-plug-in-application-template-categorizer/page/2/#comment-375520), + not HTML. + + ??? info "Screenshot" + + ![!templ-changelog](tmpl-changelog.png) + +- `Config` - A configuration entry for the container. See the [Add a Config](#3-add-a-config-entry) section for more + information. + +- `Date` - The date this container was last updated. This is used internally by Unraid and should not be modified. Do + *NOT* include this in your template. + +- `DateInstalled` - The date that the container was installed. This is used internally by Unraid and should not be + modified. Do *NOT* include this in your template. + +- `Description` - Deprecated. Use `Overview` instead. + + ??? info "Screenshot" + + ![!templ-overview](tmpl-overview.png) + +- `DonateText` - Deprecated. This should be included in your Community Applications profile configuration instead. + +- `DonateLink` - Deprecated. This should be included in your Community Applications profile configuration instead. + +- `ExtraParams` - Additional parameters to pass to the `docker run` command when starting the container. This should + only be used for advanced configurations. + +- `ExtraSearchTerms` - A space-delimited list of + additional [search terms](https://forums.unraid.net/topic/38619-docker-template-xml-schema/page/3/?tab=comments#comment-941891) + for the container. This can be used to help users find the container in the Community Applications store. + +- `Icon` - A URL to an icon for the container. This should be a direct link to an image file, typically a PNG file. + +- `License` - Information about + the [license for the container](http://lime-technology.com/forum/index.php?topic=40262.msg444243#msg444243). + +- `Maintainer` - Information about the maintainer of the template (you). This is displayed in the Community Applications + store entry. + +- `WebPage` - A link to your personal website or contact page. + +- `Name` - The name of the container. This is what the template will be called in the Community Applications store ( + including search results). + +- `Network` - The networking mode for the container. This is often either `bridge` or `host`, but can also be the name + of a [custom network](https://docs.docker.com/network/). + +- `Overview` - A description of the container. This is displayed in the Community Applications store entry and when the + user is setting up the container. Include any important instructions or information here. + + ??? info "Screenshot" + + ![!templ-overview-2](tmpl-overview-2.png) + ![!templ-overview](tmpl-overview.png) + +- `Privileged` - Whether the container should run in privileged mode. This can be a security risk and should be avoided + if possible. + +- `Project` - A link to the project's GitHub repository or other homepage. + +- `ReadMe` - A link to a README file for the container. This will be displayed in the context menu (left-click on the + container's icon) in the Docker tab. + +- `Registry` - A link to the registry where the Docker image is located. This is often a link to the Docker Hub page for + the image. + +- `Repository` - A link to the repository where the Docker image can be downloaded from, in the + pattern `registry/author/app_name:tag_name`. For example, `author/app_name` (defaults to Docker Hub and `latest` tag), + or `ghcr.io/author/app_name:preview` (a `preview`-tagged image from the GitHub Container Registry). + +- `Requires` - A warning message informing users of any prerequisites or requirements. This will be displayed: + + - in the "Additional Requirements" section of the app's Community Applications store entry + + ??? info "Screenshot" + + ![!templ-requires](tmpl-requires.png) + + - in a pop-up when the user clicks "Install" in the Community Applications store + + ??? info "Screenshot" + + ![!templ-requires-2](tmpl-requires-2.png) + + - in "Additional Requirements" on the container's settings page in Unraid + + ??? info "Screenshot" + + ![!templ-requires-3](tmpl-requires-3.png) + +- `Screenshot` - A link to an image + to [display in the Community Applications store entry](https://forums.unraid.net/topic/38619-docker-template-xml-schema/page/4/?tab=comments#comment-1051850). + This should be a direct link to an image file, typically a PNG file. You can include multiple screenshots by adding + multiple `` tags. + +- `Shell` - The shell to use when running commands in the container. This is typically `sh` or `bash`. Do *NOT* include + if you are unsure, as it can cause issues with the container. + +- `Support` - A link to a [support thread on the Unraid forums](https://forums.unraid.net/forum/47-docker-containers/) + for the container. This will be mapped to the "Support" button on the Community Applications store entry. + +- `TemplateURL` - A link to the raw XML file for the template hosted on GitHub. This should start + with `https://raw.githubusercontent.com/`. + +- `WebUI` - A pattern of the URL to access the web interface of the container, typically in the + pattern `http://[IP]:[PORT:5000]`. When provided, a "WebUI" option will be available in the context menu (left-click + on the container's icon) in the Docker tab. + + ??? info "Screenshot" + + ![!templ-webui](tmpl-webui.png) diff --git a/docs/docker/templating/tmpl-branches.png b/docs/docker/templating/tmpl-branches.png new file mode 100644 index 0000000..c600828 Binary files /dev/null and b/docs/docker/templating/tmpl-branches.png differ diff --git a/docs/docker/templating/tmpl-changelog.png b/docs/docker/templating/tmpl-changelog.png new file mode 100644 index 0000000..c22b808 Binary files /dev/null and b/docs/docker/templating/tmpl-changelog.png differ diff --git a/docs/docker/templating/tmpl-overview-2.png b/docs/docker/templating/tmpl-overview-2.png new file mode 100644 index 0000000..3d33f13 Binary files /dev/null and b/docs/docker/templating/tmpl-overview-2.png differ diff --git a/docs/docker/templating/tmpl-overview.png b/docs/docker/templating/tmpl-overview.png new file mode 100644 index 0000000..0a0a398 Binary files /dev/null and b/docs/docker/templating/tmpl-overview.png differ diff --git a/docs/docker/templating/tmpl-requires-2.png b/docs/docker/templating/tmpl-requires-2.png new file mode 100644 index 0000000..48ce930 Binary files /dev/null and b/docs/docker/templating/tmpl-requires-2.png differ diff --git a/docs/docker/templating/tmpl-requires-3.png b/docs/docker/templating/tmpl-requires-3.png new file mode 100644 index 0000000..268bc04 Binary files /dev/null and b/docs/docker/templating/tmpl-requires-3.png differ diff --git a/docs/docker/templating/tmpl-requires.png b/docs/docker/templating/tmpl-requires.png new file mode 100644 index 0000000..3f699d2 Binary files /dev/null and b/docs/docker/templating/tmpl-requires.png differ diff --git a/docs/docker/templating/tmpl-webui.png b/docs/docker/templating/tmpl-webui.png new file mode 100644 index 0000000..2725dba Binary files /dev/null and b/docs/docker/templating/tmpl-webui.png differ diff --git a/docs/index.md b/docs/index.md index 74c725a..fac1173 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,7 +1,7 @@ -[![Unraid](https://raw.githubusercontent.com/selfhosters/unRAID-CA-templates/master/.github/ISSUE_TEMPLATE/discord_unraid_unraid.png )](https://discord.gg/qWPbc8R) - # Welcome to selfhosters.net +[![Unraid](https://raw.githubusercontent.com/selfhosters/unRAID-CA-templates/master/.github/ISSUE_TEMPLATE/discord_unraid_unraid.png )](https://discord.gg/qWPbc8R) + Selfhosters.net is a documentation portal for the [Unraid Discord](https://discord.gg/qWPbc8R). Here you will find short guides and walkthroughs made by the Unraid community. diff --git a/docs/testing/highlighting_test.md b/docs/testing/highlighting_test.md index e0c45fb..12c5914 100644 --- a/docs/testing/highlighting_test.md +++ b/docs/testing/highlighting_test.md @@ -49,7 +49,7 @@ server { ## python ```python -print("unraid rulez") +print("Unraid rulez") ``` ## bash diff --git a/mkdocs.yml b/mkdocs.yml index d0b969f..4467344 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -1,11 +1,12 @@ -site_name: "Selfhosters.net" -site_description: "Selfhosters.net is a documentation portal for the Unraid Discord. Here you will find short guides and walkthroughs made by the Unraid community." -site_author: "Selfhosters" -site_url: "https://selfhosters.net" +site_name: Selfhosters.net +site_description: | + Selfhosters.net is a documentation portal for the Unraid Community Discord. Here you will find short guides and walkthroughs made by the Unraid community. +site_author: Selfhosters +site_url: https://selfhosters.net -repo_name: "selfhosters/selfhosters.net" -repo_url: "https://github.com/selfhosters/selfhosters.net" -edit_uri: "https://github.com/selfhosters/selfhosters.net/edit/master/docs/" +repo_name: selfhosters/selfhosters.net +repo_url: https://github.com/selfhosters/selfhosters.net +edit_uri: https://github.com/selfhosters/selfhosters.net/edit/master/docs/ # Configuration @@ -15,13 +16,13 @@ edit_uri: "https://github.com/selfhosters/selfhosters.net/edit/master/docs/" plugins: - search - git-revision-date-localized + - glightbox markdown_extensions: - admonition - attr_list - codehilite - footnotes - - lightgallery - pymdownx.arithmatex - pymdownx.betterem: smart_enable: all @@ -44,37 +45,37 @@ markdown_extensions: permalink: true theme: - favicon: "assets/images/favicon.ico" - logo: "assets/images/logo.png" + favicon: assets/images/favicon.ico + logo: assets/images/logo.png features: - instant - name: "material" - language: "en" - custom_dir: "lightgallery/" + name: material + language: en + custom_dir: lightgallery/ palette: - primary: "orange" - accent: "red" + primary: orange + accent: red font: - text: "Roboto" - code: "Fira Code" + text: Roboto + code: Fira Code extra: social: - - icon: "fontawesome/brands/github" - link: "https://github.com/selfhosters" - - icon: "fontawesome/brands/discord" - link: "https://discord.gg/qWPbc8R" + - icon: fontawesome/brands/github + link: https://github.com/selfhosters + - icon: fontawesome/brands/discord + link: https://discord.gg/qWPbc8R # Navigation nav: - Home: index.md - - Nice to know Unraid commands: commands.md + - Nice-to-know Unraid commands: commands.md - Unraid Tips: - Adding Discord Notifications: tips/discord_notifications/discord_notifications.md + - Adding Discord Notifications: tips/discord_notifications/discord_notifications.md - Docker: - Telegraf: - Adding IPMI stats to the Telegraf container: docker/telegraf/ipmi.md - Plex: - Routing Plex through Cloudflare: docker/plex/cloudflare.md - VPN: - Route a container trough a VPN with PfSense: docker/pfsense_vlan_vpn/pfsense_vlan_vpn.md - Writing a template compatible for unraid: docker/templating/templating.md + - Telegraf: + - Adding IPMI stats to the Telegraf container: docker/telegraf/ipmi.md + - Plex: + - Routing Plex through Cloudflare: docker/plex/cloudflare.md + - VPN: + - Route a container trough a VPN with PfSense: docker/pfsense_vlan_vpn/pfsense_vlan_vpn.md + - Writing a template compatible for Unraid: docker/templating/templating.md diff --git a/requirements.txt b/requirements.txt index bacbf0e..ee66f57 100644 --- a/requirements.txt +++ b/requirements.txt @@ -1,5 +1,6 @@ mkdocs +mkdocs-git-revision-date-localized-plugin +mkdocs-glightbox mkdocs-material pymdown-extensions -mkdocs-git-revision-date-localized-plugin -git+git://github.com/g-provost/lightgallery-markdown#egg=lightgallery \ No newline at end of file +yamllint \ No newline at end of file