|
| 1 | +# Contributing to fail2ban |
| 2 | + |
| 3 | +## Gotchas |
| 4 | + |
| 5 | +* While contributing make sure to make all your changes before creating a Pull Request, as our pipeline builds each commit after the PR is open. |
| 6 | +* Read, and fill the Pull Request template |
| 7 | + * If this is a fix for a typo (in code, documentation, or the README) please file an issue and let us sort it out. We do not need a PR |
| 8 | + * If the PR is addressing an existing issue include, closes #\<issue number>, in the body of the PR commit message |
| 9 | +* If you want to discuss changes, you can also bring it up in [#dev-talk](https://discordapp.com/channels/354974912613449730/757585807061155840) in our [Discord server](https://discord.gg/YWrKVTn) |
| 10 | + |
| 11 | +## Common files |
| 12 | + |
| 13 | +| File | Use case | |
| 14 | +| :----: | --- | |
| 15 | +| `Dockerfile` | Dockerfile used to build amd64 images | |
| 16 | +| `Dockerfile.aarch64` | Dockerfile used to build 64bit ARM architectures | |
| 17 | +| `Dockerfile.armhf` | Dockerfile used to build 32bit ARM architectures | |
| 18 | +| `Jenkinsfile` | This file is a product of our builder and should not be edited directly. This is used to build the image | |
| 19 | +| `jenkins-vars.yml` | This file is used to generate the `Jenkinsfile` mentioned above, it only affects the build-process | |
| 20 | +| `package_versions.txt` | This file is generated as a part of the build-process and should not be edited directly. It lists all the installed packages and their versions | |
| 21 | +| `README.md` | This file is a product of our builder and should not be edited directly. This displays the readme for the repository and image registries | |
| 22 | +| `readme-vars.yml` | This file is used to generate the `README.md` | |
| 23 | + |
| 24 | +## Readme |
| 25 | + |
| 26 | +If you would like to change our readme, please __**do not**__ directly edit the readme, as it is auto-generated on each commit. |
| 27 | +Instead edit the [readme-vars.yml](https://github.com/linuxserver/docker-fail2ban/edit/master/readme-vars.yml). |
| 28 | + |
| 29 | +These variables are used in a template for our [Jenkins Builder](https://github.com/linuxserver/docker-jenkins-builder) as part of an ansible play. |
| 30 | +Most of these variables are also carried over to [docs.linuxserver.io](https://docs.linuxserver.io/images/docker-fail2ban) |
| 31 | + |
| 32 | +### Fixing typos or clarify the text in the readme |
| 33 | + |
| 34 | +There are variables for multiple parts of the readme, the most common ones are: |
| 35 | + |
| 36 | +| Variable | Description | |
| 37 | +| :----: | --- | |
| 38 | +| `project_blurb` | This is the short excerpt shown above the project logo. | |
| 39 | +| `app_setup_block` | This is the text that shows up under "Application Setup" if enabled | |
| 40 | + |
| 41 | +### Parameters |
| 42 | + |
| 43 | +The compose and run examples are also generated from these variables. |
| 44 | + |
| 45 | +We have a [reference file](https://github.com/linuxserver/docker-jenkins-builder/blob/master/vars/_container-vars-blank) in our Jenkins Builder. |
| 46 | + |
| 47 | +These are prefixed with `param_` for required parameters, or `opt_param` for optional parameters, except for `cap_add`. |
| 48 | +Remember to enable param, if currently disabled. This differs between parameters, and can be seen in the reference file. |
| 49 | + |
| 50 | +Devices, environment variables, ports and volumes expects its variables in a certain way. |
| 51 | + |
| 52 | +### Devices |
| 53 | + |
| 54 | +```yml |
| 55 | +param_devices: |
| 56 | + - { device_path: "/dev/dri", device_host_path: "/dev/dri", desc: "For hardware transcoding" } |
| 57 | +opt_param_devices: |
| 58 | + - { device_path: "/dev/dri", device_host_path: "/dev/dri", desc: "For hardware transcoding" } |
| 59 | +``` |
| 60 | +
|
| 61 | +### Environment variables |
| 62 | +
|
| 63 | +```yml |
| 64 | +param_env_vars: |
| 65 | + - { env_var: "TZ", env_value: "Europe/London", desc: "Specify a timezone to use EG Europe/London." } |
| 66 | +opt_param_env_vars: |
| 67 | + - { env_var: "VERSION", env_value: "latest", desc: "Supported values are LATEST, PLEXPASS or a specific version number." } |
| 68 | +``` |
| 69 | +
|
| 70 | +### Ports |
| 71 | +
|
| 72 | +```yml |
| 73 | +param_ports: |
| 74 | + - { external_port: "80", internal_port: "80", port_desc: "Application WebUI" } |
| 75 | +opt_param_ports: |
| 76 | + - { external_port: "80", internal_port: "80", port_desc: "Application WebUI" } |
| 77 | +``` |
| 78 | +
|
| 79 | +### Volumes |
| 80 | +
|
| 81 | +```yml |
| 82 | +param_volumes: |
| 83 | + - { vol_path: "/config", vol_host_path: "</path/to/appdata/config>", desc: "Configuration files." } |
| 84 | +opt_param_volumes: |
| 85 | + - { vol_path: "/config", vol_host_path: "</path/to/appdata/config>", desc: "Configuration files." } |
| 86 | +``` |
| 87 | +
|
| 88 | +### Testing template changes |
| 89 | +
|
| 90 | +After you make any changes to the templates, you can use our [Jenkins Builder](https://github.com/linuxserver/docker-jenkins-builder) to have the files updated from the modified templates. Please use the command found under `Running Locally` [on this page](https://github.com/linuxserver/docker-jenkins-builder/blob/master/README.md) to generate them prior to submitting a PR. |
| 91 | + |
| 92 | +## Dockerfiles |
| 93 | + |
| 94 | +We use multiple Dockerfiles in our repos, this is because sometimes some CPU architectures needs different packages to work. |
| 95 | +If you are proposing additional packages to be added, ensure that you added the packages to all the Dockerfiles in alphabetical order. |
| 96 | + |
| 97 | +### Testing your changes |
| 98 | + |
| 99 | +```bash |
| 100 | +git clone https://github.com/linuxserver/docker-fail2ban.git |
| 101 | +cd docker-fail2ban |
| 102 | +docker build \ |
| 103 | + --no-cache \ |
| 104 | + --pull \ |
| 105 | + -t linuxserver/fail2ban:latest . |
| 106 | +``` |
| 107 | + |
| 108 | +The ARM variants can be built on x86_64 hardware using `multiarch/qemu-user-static` |
| 109 | + |
| 110 | +```bash |
| 111 | +docker run --rm --privileged multiarch/qemu-user-static:register --reset |
| 112 | +``` |
| 113 | + |
| 114 | +Once registered you can define the dockerfile to use with `-f Dockerfile.aarch64`. |
| 115 | + |
| 116 | +## Update the changelog |
| 117 | + |
| 118 | +If you are modifying the Dockerfiles or any of the startup scripts in [root](https://github.com/linuxserver/docker-fail2ban/tree/master/root), add an entry to the changelog |
| 119 | + |
| 120 | +```yml |
| 121 | +changelogs: |
| 122 | + - { date: "DD.MM.YY:", desc: "Added some love to templates" } |
| 123 | +``` |
0 commit comments