From ad16067420526eadfb744c5ef2aa04abdd798b41 Mon Sep 17 00:00:00 2001 From: florian Date: Sat, 29 Apr 2023 20:54:56 +0200 Subject: [PATCH] use proper links in docs, automatic doc push and add pdf to releases --- .github/workflows/beta.yml | 58 +++++------ .github/workflows/doc-to-pdf.yml | 39 ++++++++ .github/workflows/push-doc.yml | 28 ++++++ .github/workflows/push-github.yml | 57 +++++++++++ .github/workflows/release.yml | 96 +++++++++++++----- .github/workflows/staging-tests.yml | 6 +- .github/workflows/staging.yml | 146 ++++++++++++++-------------- README.md | 8 +- docs/about.md | 2 +- docs/assets/extra.js | 3 - docs/concepts.md | 24 ++--- docs/index.md | 6 +- docs/integrations.md | 77 +++++++-------- docs/json2md.py | 2 +- docs/migrating.md | 10 +- docs/mike.sh | 13 --- docs/misc/pdf.js | 49 ++++++++++ docs/overrides/main.html | 28 +++--- docs/plugins.md | 34 +++---- docs/quickstart-guide.md | 128 ++++++++++++------------ docs/requirements.txt | 1 + docs/security-tuning.md | 10 +- docs/settings.md | 2 +- docs/troubleshooting.md | 8 +- docs/web-ui.md | 60 ++++++------ misc/update-version.sh | 22 +++++ mkdocs.yml | 9 +- 27 files changed, 573 insertions(+), 353 deletions(-) create mode 100644 .github/workflows/doc-to-pdf.yml create mode 100644 .github/workflows/push-doc.yml create mode 100644 .github/workflows/push-github.yml delete mode 100644 docs/assets/extra.js delete mode 100755 docs/mike.sh create mode 100644 docs/misc/pdf.js create mode 100755 misc/update-version.sh diff --git a/.github/workflows/beta.yml b/.github/workflows/beta.yml index 219df089..44ee8eeb 100644 --- a/.github/workflows/beta.yml +++ b/.github/workflows/beta.yml @@ -368,9 +368,9 @@ jobs: BW_VERSION: ${{ jobs.wait-builds.steps.getversion.outputs.version }} secrets: PACKAGECLOUD_TOKEN: ${{ secrets.PACKAGECLOUD_TOKEN }} - - # Create tag + release + discussion - publish-beta: + + # Create doc PDF + doc-pdf: needs: [ push-bunkerweb, push-scheduler, @@ -381,38 +381,30 @@ jobs: push-rhel, push-fedora ] + uses: ./.github/workflows/doc-to-pdf.yml + with: + VERSION: ${{ jobs.wait-builds.steps.getversion.outputs.version }} + + # Push on GH + push-gh: + needs: [doc-pdf] permissions: contents: write - steps: - - uses: actions/checkout@v3 - - uses: rickstaa/action-create-tag@v1 - name: Create tag - with: - tag: "v${{ jobs.wait-builds.steps.getversion.outputs.version }}" - message: "v${{ jobs.wait-builds.steps.getversion.outputs.version }}" - - name: Extract changelog - id: getchangelog - run: echo "::set-output name=content::$(awk -v n=2 '/##/{n--}; n > 0' CHANGELOG.md | grep -v '# Changelog' | grep -v '##' | sed '/^$/d')" - - name: Create release - uses: softprops/action-gh-release@v1 - with: - body: | - Documentation : https://docs.bunkerweb.io/${{ jobs.wait-builds.steps.getversion.outputs.version }}/ + uses: ./.github/workflow/push-github.yml + with: + VERSION: ${{ jobs.wait-builds.steps.getversion.outputs.version }} + PRERELEASE: true + + # Push doc + push-doc: + needs: [publish-gh] + permissions: + contents: write + uses: ./.github/workflow/push-doc.yml + VERSION: ${{ jobs.wait-builds.steps.getversion.outputs.version }} + ALIAS: beta + + - Docker tags : - - `bunkerity/bunkerweb:${{ jobs.wait-builds.steps.getversion.outputs.version }}` - - `bunkerity/bunkerweb-scheduler:${{ jobs.wait-builds.steps.getversion.outputs.version }}` - - `bunkerity/bunkerweb-autoconf:${{ jobs.wait-builds.steps.getversion.outputs.version }}` - - `bunkerity/bunkerweb-ui:${{ jobs.wait-builds.steps.getversion.outputs.version }}` - - Linux packages : https://packagecloud.io/app/bunkerity/bunkerweb/search?q=${{ jobs.wait-builds.steps.getversion.outputs.version }}&filter=all&dist= - - Changelog : - ${{steps.getchangelog.outputs.content}} - draft: false - prerelease: true - name: v${{ jobs.wait-builds.steps.getversion.outputs.version }} - tag_name: v${{ jobs.wait-builds.steps.getversion.outputs.version }} - discussion_category_name: Announcements diff --git a/.github/workflows/doc-to-pdf.yml b/.github/workflows/doc-to-pdf.yml new file mode 100644 index 00000000..789e9a25 --- /dev/null +++ b/.github/workflows/doc-to-pdf.yml @@ -0,0 +1,39 @@ +name: Generate documentation PDF (REUSABLE) + +on: + workflow_call: + inputs: + VERSION: + required: true + type: string + +jobs: + build: + runs-on: ubuntu-latest + steps: + # Prepare + - name: Checkout source code + uses: actions/checkout@v3 + - name: Install Python + uses: actions/setup-python@v4 + with: + python-version: '3.10' + - name: Install doc requirements + run: pip install -r docs/requirements.txt + - name: Install chromium + uses: apt install chromium-browser + - name: Install node + uses: actions/setup-node@v3 + with: + node-version: 18 + - name: Install puppeteer + run: npm i --save puppeteer + - name: Run mkdocs serve in background + run: mkdocs serve & sleep 10 + - name: Run pdf script + run: node docs/misc/pdf.js http://localhost:8000/print_page/ BunkerWeb_documentation_v${{ inputs.VERSION }}.pdf 'BunkerWeb documentation v${{ inputs.VERSION }}' + - uses: actions/upload-artifact@v3 + with: + name: BunkerWeb_documentation_v${{ inputs.VERSION }}.pdf + path: BunkerWeb_documentation_v${{ inputs.VERSION }}.pdf + diff --git a/.github/workflows/push-doc.yml b/.github/workflows/push-doc.yml new file mode 100644 index 00000000..af079c18 --- /dev/null +++ b/.github/workflows/push-doc.yml @@ -0,0 +1,28 @@ +name: Push documentation (REUSABLE) + +on: + workflow_call: + inputs: + VERSION: + required: true + type: string + ALIAS: + required: true + type: string + +jobs: + build: + runs-on: ubuntu-latest + steps: + - name: Checkout source code + uses: actions/checkout@v3 + uses: actions/setup-python@v4 + with: + python-version: '3.10' + - name: Install doc requirements + run: pip install -r docs/requirements.txt + - name: Push doc + run: mike deploy --update-aliases --push ${{ inputs.VERSION }} ${{ inputs.ALIAS }} + - name: Set default doc + if: inputs.ALIAS == 'latest' + run: mike set-default --push latest diff --git a/.github/workflows/push-github.yml b/.github/workflows/push-github.yml new file mode 100644 index 00000000..fe0c5446 --- /dev/null +++ b/.github/workflows/push-github.yml @@ -0,0 +1,57 @@ +name: Push on GitHub (REUSABLE) + +on: + workflow_call: + inputs: + VERSION: + required: true + type: string + PRERELEASE: + required: true + type: boolean + +jobs: + build: + runs-on: ubuntu-latest + steps: + # Checkout + - uses: actions/checkout@v3 + # Get PDF doc + - name: Get documentation + uses: actions/download-artifact@v3 + with: + name: BunkerWeb_documentation_v${{ inputs.VERSION }}.pdf + path: BunkerWeb_documentation_v${{ inputs.VERSION }}.pdf + # Create tag + - uses: rickstaa/action-create-tag@v1 + name: Create tag + with: + tag: "v${{ inputs.VERSION }}" + message: "v${{ inputs.VERSION }}" + # Extract changelog + - name: Extract changelog + id: getchangelog + run: echo "::set-output name=content::$(awk -v n=2 '/##/{n--}; n > 0' CHANGELOG.md | grep -v '# Changelog' | grep -v '##' | sed '/^$/d')" + # Create release + - name: Create release + uses: softprops/action-gh-release@v1 + with: + body: | + Documentation : https://docs.bunkerweb.io/${{ inputs.VERSION }}/ + + Docker tags : + - `bunkerity/bunkerweb:${{ inputs.VERSION }}` + - `bunkerity/bunkerweb-scheduler:${{ inputs.VERSION }}` + - `bunkerity/bunkerweb-autoconf:${{ inputs.VERSION }}` + - `bunkerity/bunkerweb-ui:${{ inputs.VERSION }}` + + Linux packages : https://packagecloud.io/app/bunkerity/bunkerweb/search?q=${{ inputs.VERSION }}&filter=all&dist= + + Changelog : + ${{steps.getchangelog.outputs.content}} + draft: false + prerelease: ${{ inputs.PRERELEASE }} + name: v${{ inputs.VERSION }} + tag_name: v${{ inputs.VERSION }} + discussion_category_name: Announcements + diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 638d30e0..8c882828 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -344,9 +344,9 @@ jobs: BW_VERSION: ${{ jobs.wait-builds.steps.getversion.outputs.version }} secrets: PACKAGECLOUD_TOKEN: ${{ secrets.PACKAGECLOUD_TOKEN }} - - # Create tag + release + discussion - publish-latest: + + # Create doc PDF + doc-pdf: needs: [ push-bunkerweb, push-scheduler, @@ -357,38 +357,80 @@ jobs: push-rhel, push-fedora ] + uses: ./.github/workflows/doc-to-pdf.yml + with: + VERSION: ${{ jobs.wait-builds.steps.getversion.outputs.version }} + + # Push on GH + push-gh: + needs: [doc-pdf] + permissions: + contents: write + uses: ./.github/workflow/push-github.yml + with: + VERSION: ${{ jobs.wait-builds.steps.getversion.outputs.version }} + PRERELEASE: false + + # Push doc + push-doc: + needs: [publish-gh] + permissions: + contents: write + uses: ./.github/workflow/push-doc.yml + VERSION: ${{ jobs.wait-builds.steps.getversion.outputs.version }} + ALIAS: latest + + # Update Docker Hub description + update-docker-hub: + needs: [ + push-bunkerweb, + push-scheduler, + push-autoconf, + push-ui + ] permissions: contents: write steps: - uses: actions/checkout@v3 - - uses: rickstaa/action-create-tag@v1 - name: Create tag + - name: Login to Docker Hub + uses: docker/login-action@v2 with: - tag: "v${{ jobs.wait-builds.steps.getversion.outputs.version }}" - message: "v${{ jobs.wait-builds.steps.getversion.outputs.version }}" + username: ${{ secrets.DOCKER_USERNAME }} + password: ${{ secrets.DOCKER_TOKEN }} - name: Extract changelog id: getchangelog run: echo "::set-output name=content::$(awk -v n=2 '/##/{n--}; n > 0' CHANGELOG.md | grep -v '# Changelog' | grep -v '##' | sed '/^$/d')" - - name: Create release - uses: softprops/action-gh-release@v1 + - name: Update Docker Hub description for BW + uses: peter-evans/dockerhub-description@v3 with: - body: | - Documentation : https://docs.bunkerweb.io/${{ jobs.wait-builds.steps.getversion.outputs.version }}/ - - Docker tags : - - `bunkerity/bunkerweb:${{ jobs.wait-builds.steps.getversion.outputs.version }}` - - `bunkerity/bunkerweb-scheduler:${{ jobs.wait-builds.steps.getversion.outputs.version }}` - - `bunkerity/bunkerweb-autoconf:${{ jobs.wait-builds.steps.getversion.outputs.version }}` - - `bunkerity/bunkerweb-ui:${{ jobs.wait-builds.steps.getversion.outputs.version }}` - - Linux packages : https://packagecloud.io/app/bunkerity/bunkerweb/search?q=${{ jobs.wait-builds.steps.getversion.outputs.version }}&filter=all&dist= - - Changelog : - ${{steps.getchangelog.outputs.content}} - draft: false - prerelease: false - name: v${{ jobs.wait-builds.steps.getversion.outputs.version }} - tag_name: v${{ jobs.wait-builds.steps.getversion.outputs.version }} - discussion_category_name: Announcements + username: ${{ secrets.DOCKER_USERNAME }} + password: ${{ secrets.DOCKER_TOKEN }} + repository: bunkerity/bunkerweb + readme-filepath: ./README.md + - name: Update Docker Hub description for scheduler + uses: peter-evans/dockerhub-description@v3 + with: + username: ${{ secrets.DOCKER_USERNAME }} + password: ${{ secrets.DOCKER_TOKEN }} + repository: bunkerity/bunkerweb-scheduler + readme-filepath: ./README.md + - name: Update Docker Hub description for autoconf + uses: peter-evans/dockerhub-description@v3 + with: + username: ${{ secrets.DOCKER_USERNAME }} + password: ${{ secrets.DOCKER_TOKEN }} + repository: bunkerity/bunkerweb-autoconf + readme-filepath: ./README.md + - name: Update Docker Hub description for UI + uses: peter-evans/dockerhub-description@v3 + with: + username: ${{ secrets.DOCKER_USERNAME }} + password: ${{ secrets.DOCKER_TOKEN }} + repository: bunkerity/bunkerweb-ui + readme-filepath: ./README.md + + + + diff --git a/.github/workflows/staging-tests.yml b/.github/workflows/staging-tests.yml index dc1b54de..5248e340 100644 --- a/.github/workflows/staging-tests.yml +++ b/.github/workflows/staging-tests.yml @@ -63,9 +63,9 @@ jobs: - name: Pull BW linux debian test image if: inputs.TYPE == 'linux' run: docker pull ${{ secrets.PRIVATE_REGISTRY }}/infra/debian-tests:staging && docker tag ${{ secrets.PRIVATE_REGISTRY }}/infra/debian-tests:staging local/debian:latest - - name: Pull BW linux centos test image - if: inputs.TYPE == 'linux' - run: docker pull ${{ secrets.PRIVATE_REGISTRY }}/infra/centos-tests:staging && docker tag ${{ secrets.PRIVATE_REGISTRY }}/infra/centos-tests:staging local/centos:latest + # - name: Pull BW linux centos test image + # if: inputs.TYPE == 'linux' + # run: docker pull ${{ secrets.PRIVATE_REGISTRY }}/infra/centos-tests:staging && docker tag ${{ secrets.PRIVATE_REGISTRY }}/infra/centos-tests:staging local/centos:latest - name: Pull BW linux fedora test image if: inputs.TYPE == 'linux' run: docker pull ${{ secrets.PRIVATE_REGISTRY }}/infra/fedora-tests:staging && docker tag ${{ secrets.PRIVATE_REGISTRY }}/infra/fedora-tests:staging local/fedora:latest diff --git a/.github/workflows/staging.yml b/.github/workflows/staging.yml index a771d1ac..4579f93e 100644 --- a/.github/workflows/staging.yml +++ b/.github/workflows/staging.yml @@ -58,28 +58,28 @@ jobs: PRIVATE_REGISTRY_TOKEN: ${{ secrets.PRIVATE_REGISTRY_TOKEN }} # Linux - build-ubuntu: - uses: ./.github/workflows/linux-build.yml - with: - RELEASE: staging - LINUX: ubuntu - PACKAGE: deb - secrets: - DOCKER_USERNAME: ${{ secrets.DOCKER_USERNAME }} - DOCKER_TOKEN: ${{ secrets.DOCKER_TOKEN }} - PRIVATE_REGISTRY: ${{ secrets.PRIVATE_REGISTRY }} - PRIVATE_REGISTRY_TOKEN: ${{ secrets.PRIVATE_REGISTRY_TOKEN }} - build-debian: - uses: ./.github/workflows/linux-build.yml - with: - RELEASE: staging - LINUX: debian - PACKAGE: deb - secrets: - DOCKER_USERNAME: ${{ secrets.DOCKER_USERNAME }} - DOCKER_TOKEN: ${{ secrets.DOCKER_TOKEN }} - PRIVATE_REGISTRY: ${{ secrets.PRIVATE_REGISTRY }} - PRIVATE_REGISTRY_TOKEN: ${{ secrets.PRIVATE_REGISTRY_TOKEN }} + # build-ubuntu: + # uses: ./.github/workflows/linux-build.yml + # with: + # RELEASE: staging + # LINUX: ubuntu + # PACKAGE: deb + # secrets: + # DOCKER_USERNAME: ${{ secrets.DOCKER_USERNAME }} + # DOCKER_TOKEN: ${{ secrets.DOCKER_TOKEN }} + # PRIVATE_REGISTRY: ${{ secrets.PRIVATE_REGISTRY }} + # PRIVATE_REGISTRY_TOKEN: ${{ secrets.PRIVATE_REGISTRY_TOKEN }} + # build-debian: + # uses: ./.github/workflows/linux-build.yml + # with: + # RELEASE: staging + # LINUX: debian + # PACKAGE: deb + # secrets: + # DOCKER_USERNAME: ${{ secrets.DOCKER_USERNAME }} + # DOCKER_TOKEN: ${{ secrets.DOCKER_TOKEN }} + # PRIVATE_REGISTRY: ${{ secrets.PRIVATE_REGISTRY }} + # PRIVATE_REGISTRY_TOKEN: ${{ secrets.PRIVATE_REGISTRY_TOKEN }} # build-centos: # uses: ./.github/workflows/linux-build.yml # with: @@ -91,28 +91,28 @@ jobs: # DOCKER_TOKEN: ${{ secrets.DOCKER_TOKEN }} # PRIVATE_REGISTRY: ${{ secrets.PRIVATE_REGISTRY }} # PRIVATE_REGISTRY_TOKEN: ${{ secrets.PRIVATE_REGISTRY_TOKEN }} - build-fedora: - uses: ./.github/workflows/linux-build.yml - with: - RELEASE: staging - LINUX: fedora - PACKAGE: rpm - secrets: - DOCKER_USERNAME: ${{ secrets.DOCKER_USERNAME }} - DOCKER_TOKEN: ${{ secrets.DOCKER_TOKEN }} - PRIVATE_REGISTRY: ${{ secrets.PRIVATE_REGISTRY }} - PRIVATE_REGISTRY_TOKEN: ${{ secrets.PRIVATE_REGISTRY_TOKEN }} - build-rhel: - uses: ./.github/workflows/linux-build.yml - with: - RELEASE: staging - LINUX: rhel - PACKAGE: rpm - secrets: - DOCKER_USERNAME: ${{ secrets.DOCKER_USERNAME }} - DOCKER_TOKEN: ${{ secrets.DOCKER_TOKEN }} - PRIVATE_REGISTRY: ${{ secrets.PRIVATE_REGISTRY }} - PRIVATE_REGISTRY_TOKEN: ${{ secrets.PRIVATE_REGISTRY_TOKEN }} + # build-fedora: + # uses: ./.github/workflows/linux-build.yml + # with: + # RELEASE: staging + # LINUX: fedora + # PACKAGE: rpm + # secrets: + # DOCKER_USERNAME: ${{ secrets.DOCKER_USERNAME }} + # DOCKER_TOKEN: ${{ secrets.DOCKER_TOKEN }} + # PRIVATE_REGISTRY: ${{ secrets.PRIVATE_REGISTRY }} + # PRIVATE_REGISTRY_TOKEN: ${{ secrets.PRIVATE_REGISTRY_TOKEN }} + # build-rhel: + # uses: ./.github/workflows/linux-build.yml + # with: + # RELEASE: staging + # LINUX: rhel + # PACKAGE: rpm + # secrets: + # DOCKER_USERNAME: ${{ secrets.DOCKER_USERNAME }} + # DOCKER_TOKEN: ${{ secrets.DOCKER_TOKEN }} + # PRIVATE_REGISTRY: ${{ secrets.PRIVATE_REGISTRY }} + # PRIVATE_REGISTRY_TOKEN: ${{ secrets.PRIVATE_REGISTRY_TOKEN }} # Code security code-security: @@ -167,20 +167,20 @@ jobs: # TYPE: k8s # secrets: # CICD_SECRETS: ${{ secrets.CICD_SECRETS }} - create-infra-linux: - needs: - [ - code-security, - build-ubuntu, - build-debian, - build-fedora, - build-rhel, - ] - uses: ./.github/workflows/staging-create-infra.yml - with: - TYPE: linux - secrets: - CICD_SECRETS: ${{ secrets.CICD_SECRETS }} + # create-infra-linux: + # needs: + # [ + # code-security, + # build-ubuntu, + # build-debian, + # build-fedora, + # build-rhel, + # ] + # uses: ./.github/workflows/staging-create-infra.yml + # with: + # TYPE: linux + # secrets: + # CICD_SECRETS: ${{ secrets.CICD_SECRETS }} # Perform tests # tests-docker: @@ -211,13 +211,13 @@ jobs: # TYPE: k8s # RUNS_ON: "['ubuntu-latest']" # secrets: inherit - tests-linux: - needs: [create-infra-linux] - uses: ./.github/workflows/staging-tests.yml - with: - TYPE: linux - RUNS_ON: "['self-hosted', 'bw-linux']" - secrets: inherit + # tests-linux: + # needs: [create-infra-linux] + # uses: ./.github/workflows/staging-tests.yml + # with: + # TYPE: linux + # RUNS_ON: "['self-hosted', 'bw-linux']" + # secrets: inherit tests-ui: needs: [code-security, build-bw, build-scheduler, build-ui] uses: ./.github/workflows/tests-ui.yml @@ -260,11 +260,11 @@ jobs: # TYPE: k8s # secrets: # CICD_SECRETS: ${{ secrets.CICD_SECRETS }} - delete-infra-linux: - if: ${{ always() }} - needs: [tests-linux] - uses: ./.github/workflows/staging-delete-infra.yml - with: - TYPE: linux - secrets: - CICD_SECRETS: ${{ secrets.CICD_SECRETS }} \ No newline at end of file + # delete-infra-linux: + # if: ${{ always() }} + # needs: [tests-linux] + # uses: ./.github/workflows/staging-delete-infra.yml + # with: + # TYPE: linux + # secrets: + # CICD_SECRETS: ${{ secrets.CICD_SECRETS }} \ No newline at end of file diff --git a/README.md b/README.md index 57e62670..847a52e8 100644 --- a/README.md +++ b/README.md @@ -3,11 +3,11 @@

- + + - - - + +

diff --git a/docs/about.md b/docs/about.md index ba80b2e9..27522ae5 100644 --- a/docs/about.md +++ b/docs/about.md @@ -34,7 +34,7 @@ Here is a non-exhaustive list of what you can do : - Follow us on [LinkedIn](https://www.linkedin.com/company/bunkerity/), [Twitter](https://twitter.com/bunkerity) and [GitHub](https://github.com/bunkerity) - Report bugs and propose new features using [issues](https://github.com/bunkerity/bunkerweb/issues) - Contribute to the code using [pull requests](https://github.com/bunkerity/bunkerweb/pulls) -- Write an awesome [plugin](/current_bw_version/plugins) +- Write an awesome [plugin](plugins.md) - Talk about BunkerWeb to your friends/colleagues, on social media, on your blog, ... ## How to report security issue ? diff --git a/docs/assets/extra.js b/docs/assets/extra.js deleted file mode 100644 index 8b565ed3..00000000 --- a/docs/assets/extra.js +++ /dev/null @@ -1,3 +0,0 @@ -window.onload = function set_bw_version() { - document.body.innerHTML = document.body.innerHTML.replaceAll('current_bw_version', '1.5.0-beta'); -} \ No newline at end of file diff --git a/docs/concepts.md b/docs/concepts.md index 11aa084a..6ee280e5 100644 --- a/docs/concepts.md +++ b/docs/concepts.md @@ -10,19 +10,19 @@ The first concept is the integration of BunkerWeb into the target environment. W The following integrations are officially supported : -- [Docker](/current_bw_version/integrations/#docker) -- [Docker autoconf](/current_bw_version/integrations/#docker-autoconf) -- [Swarm](/current_bw_version/integrations/#swarm) -- [Kubernetes](/current_bw_version/integrations/#kubernetes) -- [Linux](/current_bw_version/integrations/#linux) -- [Ansible](/current_bw_version/integrations/#ansible) -- [Vagrant](/current_bw_version/integrations/#vagrant) +- [Docker](integrations.md#docker) +- [Docker autoconf](integrations.md#docker-autoconf) +- [Swarm](integrations.md#swarm) +- [Kubernetes](integrations.md#kubernetes) +- [Linux](integrations.md#linux) +- [Ansible](integrations.md#ansible) +- [Vagrant](integrations.md#vagrant) If you think that a new integration should be supported, do not hesitate to open a [new issue](https://github.com/bunkerity/bunkerweb/issues) on the GitHub repository. !!! info "Going further" - The technical details of all BunkerWeb integrations are available in the [integrations section](/current_bw_version/integrations) of the documentation. + The technical details of all BunkerWeb integrations are available in the [integrations section](integrations.md) of the documentation. ## Settings @@ -44,7 +44,7 @@ USE_BROTLI=no !!! info "Going further" - The complete list of available settings with descriptions and possible values is available in the [settings section](/current_bw_version/settings) of the documentation. + The complete list of available settings with descriptions and possible values is available in the [settings section](settings.md) of the documentation. !!! info "Settings generator tool" @@ -79,11 +79,11 @@ app3.example.com_USE_BAD_BEHAVIOR=no !!! info "Going further" - You will find concrete examples of multisite mode in the [quickstart guide](/current_bw_version/quickstart-guide) of the documentation and the [examples](https://github.com/bunkerity/bunkerweb/tree/vcurrent_bw_version/examples) directory of the repository. + You will find concrete examples of multisite mode in the [quickstart guide](quickstart-guide.md) of the documentation and the [examples](https://github.com/bunkerity/bunkerweb/tree/v1.5.0-beta/examples) directory of the repository. ## Custom configurations -Because meeting all the use cases only using the settings is not an option (even with [external plugins](/current_bw_version/plugins)), you can use custom configurations to solve your specific challenges. +Because meeting all the use cases only using the settings is not an option (even with [external plugins](plugins.md)), you can use custom configurations to solve your specific challenges. Under the hood, BunkerWeb uses the notorious NGINX web server, that's why you can leverage its configuration system for your specific needs. Custom NGINX configurations can be included in different [contexts](https://docs.nginx.com/nginx/admin-guide/basic-functionality/managing-configuration-files/#contexts) like HTTP or server (all servers and/or specific server block). @@ -91,7 +91,7 @@ Another core component of BunkerWeb is the ModSecurity Web Application Firewall !!! info "Going further" - You will find concrete examples of custom configurations in the [quickstart guide](/current_bw_version/quickstart-guide) of the documentation and the [examples](https://github.com/bunkerity/bunkerweb/tree/vcurrent_bw_version/examples) directory of the repository. + You will find concrete examples of custom configurations in the [quickstart guide](quickstart-guide.md) of the documentation and the [examples](https://github.com/bunkerity/bunkerweb/tree/v1.5.0-beta/examples) directory of the repository. ## Database diff --git a/docs/index.md b/docs/index.md index 56f7a5c4..17c64011 100644 --- a/docs/index.md +++ b/docs/index.md @@ -9,9 +9,9 @@ BunkerWeb is a next-generation and open-source Web Application Firewall (WAF). -Being a full-featured web server (based on [NGINX](https://nginx.org/) under the hood), it will protect your web services to make them "secure by default". BunkerWeb integrates seamlessly into your existing environments ([Linux](/current_bw_version/integrations/#linux), [Docker](/current_bw_version/integrations/#docker), [Swarm](/current_bw_version/integrations/#swarm), [Kubernetes](/current_bw_version/integrations/#kubernetes), …) and is fully configurable (don't panic, there is an [awesome web UI](/current_bw_version/web-ui/) if you don't like the CLI) to meet your own use-cases . In other words, cybersecurity is no more a hassle. +Being a full-featured web server (based on [NGINX](https://nginx.org/) under the hood), it will protect your web services to make them "secure by default". BunkerWeb integrates seamlessly into your existing environments ([Linux](integrations.md#linux), [Docker](integrations.md#docker), [Swarm](integrations.md#swarm), [Kubernetes](integrations.md#kubernetes), …) and is fully configurable (don't panic, there is an [awesome web UI](web-ui.md) if you don't like the CLI) to meet your own use-cases . In other words, cybersecurity is no more a hassle. -BunkerWeb contains primary [security features](/current_bw_version/security-tuning/) as part of the core but can be easily extended with additional ones thanks to a [plugin system](/current_bw_version/plugins/). +BunkerWeb contains primary [security features](security-tuning.md) as part of the core but can be easily extended with additional ones thanks to a [plugin system](plugins.md)). ## Why BunkerWeb ? @@ -35,7 +35,7 @@ A non-exhaustive list of security features : - **Block known bad IPs** with external blacklists and DNSBL - And much more ... -Learn more about the core security features in the [security tuning](/current_bw_version/security-tuning) section of the documentation. +Learn more about the core security features in the [security tuning](security-tuning.md) section of the documentation. ## Demo diff --git a/docs/integrations.md b/docs/integrations.md index caa3e89a..e394d9d1 100644 --- a/docs/integrations.md +++ b/docs/integrations.md @@ -12,7 +12,7 @@ Using BunkerWeb as a [Docker](https://www.docker.com/) container is a quick and We provide ready-to-use prebuilt images for x64, x86 armv8 and armv7 architectures on [Docker Hub](https://hub.docker.com/r/bunkerity/bunkerweb) : ```shell -docker pull bunkerity/bunkerweb:current_bw_version +docker pull bunkerity/bunkerweb:1.5.0-beta ``` Alternatively, you can build the Docker image directly from the [source](https://github.com/bunkerity/bunkerweb) (and get a coffee ☕ because it may take a long time depending on your hardware) : @@ -30,7 +30,7 @@ Docker integration key concepts are : - **Networks** to expose ports for clients and connect to upstream web services !!! info "Database backend" - Please note that we assume you are using SQLite as database backend (which is the default for the `DATABASE_URI` setting). Other backends for this integration are still possible if you want to : see docker-compose files in the [misc/integrations folder](https://github.com/bunkerity/bunkerweb/tree/vcurrent_bw_version/misc/integrations) folder of the repostiory for more information. + Please note that we assume you are using SQLite as database backend (which is the default for the `DATABASE_URI` setting). Other backends for this integration are still possible if you want to : see docker-compose files in the [misc/integrations folder](https://github.com/bunkerity/bunkerweb/tree/v1.5.0-beta/misc/integrations) folder of the repostiory for more information. ### Environment variables @@ -40,7 +40,7 @@ Settings are passed to BunkerWeb using Docker environment variables : ... services: mybunker: - image: bunkerity/bunkerweb:current_bw_version + image: bunkerity/bunkerweb:1.5.0-beta labels: - "bunkerweb.INSTANCE" environment: @@ -52,14 +52,14 @@ services: Please note that the `bunkerweb.INSTANCE` is mandatory to make sure the scheduler can detect BunkerWeb instance(s). !!! info "Full list" - For the complete list of environment variables, see the [settings section](/current_bw_version/settings) of the documentation. + For the complete list of environment variables, see the [settings section](settings.md) of the documentation. ### Scheduler -The [scheduler](/current_bw_version/concepts/#scheduler) is executed in its own container which is also available on Docker Hub : +The [scheduler](concepts.md#scheduler) is executed in its own container which is also available on Docker Hub : ```shell -docker pull bunkerity/bunkerweb-scheduler:current_bw_version +docker pull bunkerity/bunkerweb-scheduler:1.5.0-beta ``` Alternatively, you can build the Docker image directly from the [source](https://github.com/bunkerity/bunkerweb) (less coffee ☕ needed than BunkerWeb image) : @@ -76,7 +76,7 @@ A volume is needed to store the SQLite database that will be used by the schedul ... services: mybunker: - image: bunkerity/bunkerweb-scheduler:current_bw_version + image: bunkerity/bunkerweb-scheduler:1.5.0-beta volumes: - bw-data:/data ... @@ -133,7 +133,7 @@ You will need to create the Docker API proxy container, mount the socket and set ... services: bw-scheduler: - image: bunkerity/bunkerweb-scheduler:current_bw_version + image: bunkerity/bunkerweb-scheduler:1.5.0-beta env: - DOCKER_HOST=tcp://bw-docker:2375 ... @@ -180,13 +180,13 @@ The scheduler needs to contact the API of BunkerWeb and for obvious security rea ... services: mybunker: - image: bunkerity/bunkerweb:current_bw_version + image: bunkerity/bunkerweb:1.5.0-beta networks: - bw-services - bw-universe ... bw-scheduler: - image: bunkerity/bunkerweb-scheduler:current_bw_version + image: bunkerity/bunkerweb-scheduler:1.5.0-beta networks: - bw-universe - bw-docker @@ -224,10 +224,10 @@ The downside of using environment variables is that the container needs to be re Instead of defining environment variables for the BunkerWeb container, you simply add **labels** to your web applications containers and the **autoconf** will "automagically" take care of the rest. !!! info "Multisite mode" - The Docker autoconf integration implies the use of **multisite mode**. Please refer to the [multisite section](/current_bw_version/concepts/#multisite-mode) of the documentation for more information. + The Docker autoconf integration implies the use of **multisite mode**. Please refer to the [multisite section](concepts.md#multisite-mode) of the documentation for more information. !!! info "Database backend" - Please note that we assume you are using MariaDB as database backend (which is defined using the `DATABASE_URI` setting). Other backends for this integration are still possible if you want to : see docker-compose files in the [misc/integrations folder](https://github.com/bunkerity/bunkerweb/tree/vcurrent_bw_version/misc/integrations) folder of the repostiory for more information. + Please note that we assume you are using MariaDB as database backend (which is defined using the `DATABASE_URI` setting). Other backends for this integration are still possible if you want to : see docker-compose files in the [misc/integrations folder](https://github.com/bunkerity/bunkerweb/tree/v1.5.0-beta/misc/integrations) folder of the repostiory for more information. Another container, named `bw-autoconf` for example, containing the autoconf service must be added to the stack. Since two services will generate the configuration for BunkerWeb, a "real" database backend (in other words, not SQLite) also needs to be added : @@ -235,7 +235,7 @@ Another container, named `bw-autoconf` for example, containing the autoconf serv ... services: bunkerweb: - image: bunkerity/bunkerweb:current_bw_version + image: bunkerity/bunkerweb:1.5.0-beta labels: - "bunkerweb.INSTANCE" environment: @@ -247,7 +247,7 @@ services: - bw-services ... bw-scheduler: - image: bunkerity/bunkerweb-scheduler:current_bw_version + image: bunkerity/bunkerweb-scheduler:1.5.0-beta depends_on: - bunkerweb - bw-docker @@ -336,12 +336,12 @@ Like the [Docker autoconf integration](#docker-autoconf), configuration for web The recommended setup is to schedule the **BunkerWeb service** as a **global service** on all nodes and the **autoconf, scheduler and Docker API proxy services** as **single replicated services**. Please note that the **Docker API proxy service** needs to be scheduled on a manager node unless you configure it to use a remote API (which is not covered in the documentation). -Since we have multiple instances of BunkerWeb running, a shared data store implemented as a [Redis](https://redis.io/) service must be created : the instances will use it to cache and share data. You will find more information about the Redis settings [here](/current_bw_version/settings/#redis) +Since we have multiple instances of BunkerWeb running, a shared data store implemented as a [Redis](https://redis.io/) service must be created : the instances will use it to cache and share data. You will find more information about the Redis settings [here](settings.md#redis) Using a shared folder or a specific driver for the database volume is left as an exercise for the reader (and depends on your own use-case). !!! info "Database backend" - Please note that we assume you are using MariaDB as database backend (which is defined using the `DATABASE_URI` setting). Other backends for this integration are still possible if you want to : see docker-compose files in the [misc/integrations folder](https://github.com/bunkerity/bunkerweb/tree/vcurrent_bw_version/misc/integrations) folder of the repostiory for more information. Clustered database backends setup are out-of-the-scope of this documentation. + Please note that we assume you are using MariaDB as database backend (which is defined using the `DATABASE_URI` setting). Other backends for this integration are still possible if you want to : see docker-compose files in the [misc/integrations folder](https://github.com/bunkerity/bunkerweb/tree/v1.5.0-beta/misc/integrations) folder of the repostiory for more information. Clustered database backends setup are out-of-the-scope of this documentation. Here is the stack boilerplate that you can deploy using `docker stack deploy` : @@ -350,7 +350,7 @@ version: "3.5" services: bunkerweb: - image: bunkerity/bunkerweb:current_bw_version + image: bunkerity/bunkerweb:1.5.0-beta ports: - published: 80 target: 8080 @@ -380,7 +380,7 @@ services: - "bunkerweb.INSTANCE" bw-autoconf: - image: bunkerity/bunkerweb-autoconf:current_bw_version + image: bunkerity/bunkerweb-autoconf:1.5.0-beta environment: - SWARM_MODE=yes - DOCKER_HOST=tcp://bw-docker:2375 @@ -411,7 +411,7 @@ services: - "node.role == manager" bw-scheduler: - image: bunkerity/bunkerweb-scheduler:current_bw_version + image: bunkerity/bunkerweb-scheduler:1.5.0-beta environment: - SWARM_MODE=yes - DOCKER_HOST=tcp://bw-docker:2375 @@ -507,10 +507,10 @@ The autoconf acts as an [Ingress controller](https://kubernetes.io/docs/concepts The recommended setup is to define **BunkerWeb** as a **[DaemonSet](https://kubernetes.io/docs/concepts/workloads/controllers/daemonset/)** which will create a pod on all nodes and the **autoconf and scheduler** as **single replicated [Deployment](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/)**. -Since we have multiple instances of BunkerWeb running, a shared data store implemented as a [Redis](https://redis.io/) service must be created : the instances will use it to cache and share data. You will find more information about the Redis settings [here](/current_bw_version/settings/#redis) +Since we have multiple instances of BunkerWeb running, a shared data store implemented as a [Redis](https://redis.io/) service must be created : the instances will use it to cache and share data. You will find more information about the Redis settings [here](settings.md#redis) !!! info "Database backend" - Please note that we assume you are using MariaDB as database backend (which is defined using the `DATABASE_URI` setting). Other backends for this integration are still possible if you want to : see yaml files in the [misc/integrations folder](https://github.com/bunkerity/bunkerweb/tree/vcurrent_bw_version/misc/integrations) folder of the repostiory for more information. Clustered database backends setup are out-of-the-scope of this documentation. + Please note that we assume you are using MariaDB as database backend (which is defined using the `DATABASE_URI` setting). Other backends for this integration are still possible if you want to : see yaml files in the [misc/integrations folder](https://github.com/bunkerity/bunkerweb/tree/v1.5.0-beta/misc/integrations) folder of the repostiory for more information. Clustered database backends setup are out-of-the-scope of this documentation. Please note that both scheduler and autoconf services needs to access the Kubernetes API. The recommended way of doing it is using [RBAC authorization](https://kubernetes.io/docs/reference/access-authn-authz/rbac/). @@ -568,7 +568,7 @@ spec: spec: containers: - name: bunkerweb - image: bunkerity/bunkerweb:current_bw_version + image: bunkerity/bunkerweb:1.5.0-beta imagePullPolicy: Always securityContext: runAsUser: 101 @@ -638,7 +638,7 @@ spec: serviceAccountName: sa-bunkerweb containers: - name: bunkerweb-controller - image: bunkerity/bunkerweb-autoconf:current_bw_version + image: bunkerity/bunkerweb-autoconf:1.5.0-beta imagePullPolicy: Always env: - name: KUBERNETES_MODE @@ -665,7 +665,7 @@ spec: serviceAccountName: sa-bunkerweb containers: - name: bunkerweb-scheduler - image: bunkerity/bunkerweb-scheduler:current_bw_version + image: bunkerity/bunkerweb-scheduler:1.5.0-beta imagePullPolicy: Always env: - name: KUBERNETES_MODE @@ -780,7 +780,7 @@ spec: storage: 5Gi ``` -Once the BunkerWeb Kubernetes stack is set up and running (see autoconf logs for more information), you will be able to deploy web applications in the cluster and declare your Ingress resource. Please note that [settings](/current_bw_version/settings) need to be set as annotations for the Ingress resource with the special value **bunkerweb.io** for the domain part : +Once the BunkerWeb Kubernetes stack is set up and running (see autoconf logs for more information), you will be able to deploy web applications in the cluster and declare your Ingress resource. Please note that [settings](settings.md) need to be set as annotations for the Ingress resource with the special value **bunkerweb.io** for the domain part : ```yaml apiVersion: networking.k8s.io/v1 @@ -843,12 +843,12 @@ Repositories of Linux packages for BunkerWeb are available on [PackageCloud](htt sudo apt install -y nginx=1.24.0-1~$(lsb_release -cs) ``` - And finally install BunkerWeb current_bw_version : + And finally install BunkerWeb 1.5.0-beta : ```shell curl -s https://packagecloud.io/install/repositories/bunkerity/bunkerweb/script.deb.sh | sudo bash && \ sudo apt update && \ - sudo apt install -y bunkerweb=current_bw_version + sudo apt install -y bunkerweb=1.5.0-beta ``` To prevent upgrading NGINX and/or BunkerWeb packages when executing `apt upgrade`, you can use the following command : @@ -877,12 +877,12 @@ Repositories of Linux packages for BunkerWeb are available on [PackageCloud](htt sudo apt install -y nginx=1.24.0-1~jammy ``` - And finally install BunkerWeb current_bw_version : + And finally install BunkerWeb 1.5.0-beta : ```shell curl -s https://packagecloud.io/install/repositories/bunkerity/bunkerweb/script.deb.sh | sudo bash && \ sudo apt update && \ - sudo apt install -y bunkerweb=current_bw_version + sudo apt install -y bunkerweb=1.5.0-beta ``` To prevent upgrading NGINX and/or BunkerWeb packages when executing `apt upgrade`, you can use the following command : @@ -899,14 +899,14 @@ Repositories of Linux packages for BunkerWeb are available on [PackageCloud](htt sudo dnf install -y nginx-1.24.0 ``` - And finally install BunkerWeb current_bw_version : + And finally install BunkerWeb 1.5.0-beta : ```shell curl -s https://packagecloud.io/install/repositories/bunkerity/bunkerweb/script.rpm.sh | \ sed 's/yum install -y pygpgme --disablerepo='\''bunkerity_bunkerweb'\''/yum install -y python-gnupg/g' | \ sed 's/pypgpme_check=`rpm -qa | grep -qw pygpgme`/python-gnupg_check=`rpm -qa | grep -qw python-gnupg`/g' | sudo bash && \ sudo dnf makecache && \ - sudo dnf install -y bunkerweb-current_bw_version + sudo dnf install -y bunkerweb-1.5.0-beta ``` To prevent upgrading NGINX and/or BunkerWeb packages when executing `dnf upgrade`, you can use the following command : @@ -943,13 +943,13 @@ Repositories of Linux packages for BunkerWeb are available on [PackageCloud](htt ```shell sudo dnf install nginx-1.24.0 ``` - And finally install BunkerWeb current_bw_version : + And finally install BunkerWeb 1.5.0-beta : ```shell dnf install -y epel-release && \ curl -s https://packagecloud.io/install/repositories/bunkerity/bunkerweb/script.rpm.sh | sudo bash && \ sudo dnf check-update && \ - sudo dnf install -y bunkerweb-current_bw_version + sudo dnf install -y bunkerweb-1.5.0-beta ``` To prevent upgrading NGINX and/or BunkerWeb packages when executing `dnf upgrade`, you can use the following command : @@ -978,12 +978,12 @@ Repositories of Linux packages for BunkerWeb are available on [PackageCloud](htt sudo dnf install nginx-1.24.0 ``` - And finally install BunkerWeb current_bw_version : + And finally install BunkerWeb 1.5.0-beta : ```shell dnf install -y epel-release && \ curl -s https://packagecloud.io/install/repositories/bunkerity/bunkerweb/script.rpm.sh | sudo bash && \ sudo dnf check-update && \ - sudo dnf install -y bunkerweb-current_bw_version + sudo dnf install -y bunkerweb-1.5.0-beta ``` To prevent upgrading NGINX and/or BunkerWeb packages when executing `dnf upgrade`, you can use the following command : @@ -1007,7 +1007,7 @@ Repositories of Linux packages for BunkerWeb are available on [PackageCloud](htt https://github.com/bunkerity/bunkerweb.git /tmp/bunkerweb ``` - BunkerWeb needs some dependencies to be compiled and installed to `/usr/share/bunkerweb/deps`, the easiest way to do it is by executing the [install.sh helper script](https://github.com/bunkerity/bunkerweb/blob/current_bw_version/deps/install.sh) (please note that you will need to install additional packages which is not covered in this procedure and depends on your own system) : + BunkerWeb needs some dependencies to be compiled and installed to `/usr/share/bunkerweb/deps`, the easiest way to do it is by executing the [install.sh helper script](https://github.com/bunkerity/bunkerweb/blobdeps/install.sh) (please note that you will need to install additional packages which is not covered in this procedure and depends on your own system) : ``` mkdir /usr/share/bunkerweb/deps && \ /tmp/bunkerweb/src/deps/install.sh @@ -1123,7 +1123,7 @@ Configuration of BunkerWeb is done by using specific role variables : | Name | Type | Description | Default value | |:-----:|:-----:|--------------|----------------| -| `bunkerweb_version` | string | Version of BunkerWeb to install. | `current_bw_version` | +| `bunkerweb_version` | string | Version of BunkerWeb to install. | `1.5.0-beta` | | `nginx_version` | string | Version of NGINX to install. | `1.24.0` | | `freeze_versions` | boolean | Prevent upgrade of BunkerWeb and NGINX when performing packages upgrades. | `true` | | `variables_env` | string | Path of the variables.env file to configure BunkerWeb. | `files/variables.env` | @@ -1137,11 +1137,12 @@ Configuration of BunkerWeb is done by using specific role variables : ## Vagrant + List of supported providers : - vmware_desktop diff --git a/docs/json2md.py b/docs/json2md.py index 05345ebf..7f21c90a 100755 --- a/docs/json2md.py +++ b/docs/json2md.py @@ -40,7 +40,7 @@ print( file=doc, ) print( - "This section contains the full list of settings supported by BunkerWeb. If you are not yet familiar with BunkerWeb, you should first read the [concepts](/1.4/concepts) section of the documentation. Please follow the instructions for your own [integration](/1.4/integrations) on how to apply the settings.\n", + "This section contains the full list of settings supported by BunkerWeb. If you are not yet familiar with BunkerWeb, you should first read the [concepts](concepts.md) section of the documentation. Please follow the instructions for your own [integration](integrations.md) on how to apply the settings.\n", file=doc, ) print( diff --git a/docs/migrating.md b/docs/migrating.md index d78ebc31..da2625c1 100644 --- a/docs/migrating.md +++ b/docs/migrating.md @@ -2,7 +2,7 @@ !!! warning "Read this if you were a 1.4.X user" - A lot of things changed since the 1.4.X releases. Container-based integrations stacks contain more services but, trust us, fundamental principles of BunkerWeb are still there. You will find ready to use boilerplates for various integrations in the [misc/integrations](https://github.com/bunkerity/bunkerweb/tree/vcurrent_bw_version/misc/integrations) folder of the repository. + A lot of things changed since the 1.4.X releases. Container-based integrations stacks contain more services but, trust us, fundamental principles of BunkerWeb are still there. You will find ready to use boilerplates for various integrations in the [misc/integrations](https://github.com/bunkerity/bunkerweb/tree/v1.5.0-beta/misc/integrations) folder of the repository. ## Scheduler @@ -10,7 +10,7 @@ Back to the 1.4.X releases, jobs (like Let's Encrypt certificate generation/rene Called **Scheduler**, this service also generates the final configuration used by BunkerWeb and acts as an intermediary between autoconf and BunkerWeb. In other words, the scheduler is the **brain of the BunkerWeb 1.5.X stack**. -You will find more information about the scheduler [here](/current_bw_version/concepts/#scheduler). +You will find more information about the scheduler [here](concepts.md#scheduler). ## Database @@ -24,7 +24,7 @@ Using a real database offers many advantages : Please note that we actually support, **SQLite**, **MySQL**, **MariaDB** and **PostgreSQL** as backends. -You will find more information about the database [here](/current_bw_version/concepts/#database). +You will find more information about the database [here](concepts.md#database). ## Redis @@ -34,8 +34,8 @@ Security is not the only reason to have a shared data store for clustered integr We actually support **Redis** as a backend for the shared data store. -See the list of [redis settings](/current_bw_version/settings/#redis) and the corresponding documentation of your integration for more information. +See the list of [redis settings](settings.md#redis) and the corresponding documentation of your integration for more information. ## Default values and new settings -The default value of some settings have changed and we have added many other settings, we recommend you read the [security tuning](/current_bw_version/security-tuning) and [settings](/current_bw_version/settings) sections of the documentation. \ No newline at end of file +The default value of some settings have changed and we have added many other settings, we recommend you read the [security tuning](security-tuning.md) and [settings](settings.md) sections of the documentation. \ No newline at end of file diff --git a/docs/mike.sh b/docs/mike.sh deleted file mode 100755 index 6daa14e4..00000000 --- a/docs/mike.sh +++ /dev/null @@ -1,13 +0,0 @@ -#!/bin/bash - -if [ "$1" != "dev" ] && [ "$1" != "latest" ] ; then - echo "missing dev/latest argument" - exit 1 -fi - -if [ "$1" == "dev" ] ; then - mike deploy --push --update-aliases dev -else - mike deploy --push --update-aliases "$(cat VERSION | sed -E 's/([0-9]+)\.([0-9]+)\.([0-9]+)/\1\.\2/')" latest - mike set-default --push latest -fi \ No newline at end of file diff --git a/docs/misc/pdf.js b/docs/misc/pdf.js new file mode 100644 index 00000000..23ef1c29 --- /dev/null +++ b/docs/misc/pdf.js @@ -0,0 +1,49 @@ +const puppeteer = require('puppeteer'); +var args = process.argv.slice(2); +var url = args[0]; +var pdfPath = args[1]; +var title = args[2]; + +console.log('Saving', url, 'to', pdfPath); + +// date – formatted print date +// title – document title +// url – document location +// pageNumber – current page number +// totalPages – total pages in the document +headerHtml = ` +
+ ${title} +
`; + +footerHtml = `
/
`; + + +(async() => { + const browser = await puppeteer.launch({ + headless: true, + executablePath: process.env.CHROME_BIN || null, + args: ['--no-sandbox', '--headless', '--disable-gpu', '--disable-dev-shm-usage'] + }); + + const page = await browser.newPage(); + await page.goto(url, { waitUntil: 'networkidle2' }); + await page.pdf({ + path: pdfPath, // path to save pdf file + format: 'A4', // page format + displayHeaderFooter: true, // display header and footer (in this example, required!) + printBackground: true, // print background + landscape: false, // use horizontal page layout + headerTemplate: headerHtml, // indicate html template for header + footerTemplate: footerHtml, + scale: 1, //Scale amount must be between 0.1 and 2 + margin: { // increase margins (in this example, required!) + top: 80, + bottom: 80, + left: 30, + right: 30 + } + }); + + await browser.close(); +})(); \ No newline at end of file diff --git a/docs/overrides/main.html b/docs/overrides/main.html index b14a3ce5..7012e1b1 100644 --- a/docs/overrides/main.html +++ b/docs/overrides/main.html @@ -1,18 +1,22 @@ -{% extends "base.html" %} {% block outdated %} You're not viewing the -documentation for the current version. -Click here to change. {% -endblock %} {% block announce %} 📢 Looking for tailored support, consulting or -development for BunkerWeb ? Contact us at -contact@bunkerity.com -for enterprise offers ! {% endblock %} {% block libs %} +{% extends "base.html" %} + +{% block outdated %} + You're not viewing the documentation of the latest version. + + Click here to view latest. + +{% endblock %} + +{% block announce %} + 📢 Looking for tailored support, consulting or development for BunkerWeb ? + Contact us at contact@bunkerity.com for enterprise offers ! +{% endblock %} + +{% block libs %} -{% endblock %} +{% endblock %} \ No newline at end of file diff --git a/docs/plugins.md b/docs/plugins.md index d1572ad9..ab343dc2 100644 --- a/docs/plugins.md +++ b/docs/plugins.md @@ -28,7 +28,7 @@ The first step is to install the plugin by putting the plugin files inside the c === "Docker" - When using the [Docker integration](current_bw_version/integrations/#docker), plugins must be written to the volume mounted on `/data/plugins` into the scheduler container. + When using the [Docker integration](1.5.0-beta/integrations/#docker), plugins must be written to the volume mounted on `/data/plugins` into the scheduler container. The first thing to do is to create the plugins folder : @@ -56,7 +56,7 @@ The first step is to install the plugin by putting the plugin files inside the c services: ... bw-scheduler: - image: bunkerity/bunkerweb-scheduler:current_bw_version + image: bunkerity/bunkerweb-scheduler:1.5.0-beta volumes: - ./bw-data:/data ... @@ -64,7 +64,7 @@ The first step is to install the plugin by putting the plugin files inside the c === "Docker autoconf" - When using the [Docker autoconf integration](current_bw_version/integrations/#docker-autoconf), plugins must be written to the volume mounted on `/data/plugins` into the scheduler container. + When using the [Docker autoconf integration](1.5.0-beta/integrations/#docker-autoconf), plugins must be written to the volume mounted on `/data/plugins` into the scheduler container. The first thing to do is to create the plugins folder : @@ -93,7 +93,7 @@ The first step is to install the plugin by putting the plugin files inside the c services: ... bw-scheduler: - image: bunkerity/bunkerweb-scheduler:current_bw_version + image: bunkerity/bunkerweb-scheduler:1.5.0-beta volumes: - ./bw-data:/data ... @@ -101,7 +101,7 @@ The first step is to install the plugin by putting the plugin files inside the c === "Swarm" - When using the [Swarm integration](current_bw_version/integrations/#swarm), plugins must be written to the volume mounted on `/data/plugins` into the scheduler container. + When using the [Swarm integration](1.5.0-beta/integrations/#swarm), plugins must be written to the volume mounted on `/data/plugins` into the scheduler container. !!! info "Swarm volume" Configuring a Swarm volume that will persist when the scheduler service is running on different nodes is not covered is in this documentation. We will assume that you have a shared folder mounted on `/shared` accross all nodes. @@ -132,7 +132,7 @@ The first step is to install the plugin by putting the plugin files inside the c services: ... bw-scheduler: - image: bunkerity/bunkerweb-scheduler:current_bw_version + image: bunkerity/bunkerweb-scheduler:1.5.0-beta volumes: - /shared/bw-plugins:/data/plugins ... @@ -140,7 +140,7 @@ The first step is to install the plugin by putting the plugin files inside the c === "Kubernetes" - When using the [Kubernetes integration](current_bw_version/integrations/#kubernetes), plugins must be written to the volume mounted on `/data/plugins` into the scheduler container. + When using the [Kubernetes integration](1.5.0-beta/integrations/#kubernetes), plugins must be written to the volume mounted on `/data/plugins` into the scheduler container. The fist thing to do is to declare a [PersistentVolumeClaim](https://kubernetes.io/docs/concepts/storage/persistent-volumes/) that will contain our plugins data : @@ -179,7 +179,7 @@ The first step is to install the plugin by putting the plugin files inside the c serviceAccountName: sa-bunkerweb containers: - name: bunkerweb-scheduler - image: bunkerity/bunkerweb-scheduler:current_bw_version + image: bunkerity/bunkerweb-scheduler:1.5.0-beta imagePullPolicy: Always env: - name: KUBERNETES_MODE @@ -205,7 +205,7 @@ The first step is to install the plugin by putting the plugin files inside the c === "Linux" - When using the [Linux integration](current_bw_version/integrations/#linux), plugins must be written to the `/etc/bunkerweb/plugins` folder : + When using the [Linux integration](1.5.0-beta/integrations/#linux), plugins must be written to the `/etc/bunkerweb/plugins` folder : ```shell git clone https://github.com/bunkerity/bunkerweb-plugins && \ @@ -215,7 +215,7 @@ The first step is to install the plugin by putting the plugin files inside the c === "Ansible" - When using the [Ansible integration](current_bw_version/integrations/#ansible), you can use the `plugins` variable to set a local folder containing your plugins that will be copied to your BunkerWeb instances. + When using the [Ansible integration](1.5.0-beta/integrations/#ansible), you can use the `plugins` variable to set a local folder containing your plugins that will be copied to your BunkerWeb instances. Let's assume that you have plugins inside the `bunkerweb-plugins` folder : @@ -249,7 +249,7 @@ The first step is to install the plugin by putting the plugin files inside the c === "Vagrant" - When using the [Vagrant integration](current_bw_version/integrations/#vagrant), plugins must be written to the `/etc/bunkerweb/plugins` folder (you will need to do a `vagrant ssh` first) : + When using the [Vagrant integration](1.5.0-beta/integrations/#vagrant), plugins must be written to the `/etc/bunkerweb/plugins` folder (you will need to do a `vagrant ssh` first) : ```shell git clone https://github.com/bunkerity/bunkerweb-plugins && \ @@ -260,7 +260,7 @@ The first step is to install the plugin by putting the plugin files inside the c !!! tip "Existing plugins" - If the documentation is not enough, you can have a look at the existing source code of [official plugins](https://github.com/bunkerity/bunkerweb-plugins) and the [core plugins](https://github.com/bunkerity/bunkerweb/tree/vcurrent_bw_version/src/common/core) (already included in BunkerWeb but they are plugins, technically speaking). + If the documentation is not enough, you can have a look at the existing source code of [official plugins](https://github.com/bunkerity/bunkerweb-plugins) and the [core plugins](https://github.com/bunkerity/bunkerweb/tree/v1.5.0-beta/src/common/core) (already included in BunkerWeb but they are plugins, technically speaking). The first step is to create a folder that will contain the plugin : @@ -339,7 +339,7 @@ Each job has the following fields : ### Configurations -You can add custom NGINX configurations by adding a folder named **confs** with content similar to the [custom configurations](/current_bw_version/quickstart-guide/#custom-configurations). Each subfolder inside the **confs** will contain [jinja2](https://jinja.palletsprojects.com) templates that will be generated and loaded at the corresponding context (`http`, `server-http`, `default-server-http`, `stream` and `server-stream`). +You can add custom NGINX configurations by adding a folder named **confs** with content similar to the [custom configurations](quickstart-guide.md#custom-configurations). Each subfolder inside the **confs** will contain [jinja2](https://jinja.palletsprojects.com) templates that will be generated and loaded at the corresponding context (`http`, `server-http`, `default-server-http`, `stream` and `server-stream`). Here is an example for a configuration template file inside the **confs/server-http** folder named **example.conf** : @@ -426,7 +426,7 @@ The declared functions are automatically called during specific contexts. Here a #### Libraries -All directives from [NGINX LUA module](https://github.com/openresty/lua-nginx-module) and are available and [NGINX stream LUA module](https://github.com/openresty/stream-lua-nginx-module). On top of that, you can use the LUA libraries included within BunkerWeb : see [this script](https://github.com/bunkerity/bunkerweb/blob/current_bw_version/src/deps/clone.sh) for the complete list. +All directives from [NGINX LUA module](https://github.com/openresty/lua-nginx-module) and are available and [NGINX stream LUA module](https://github.com/openresty/stream-lua-nginx-module). On top of that, you can use the LUA libraries included within BunkerWeb : see [this script](https://github.com/bunkerity/bunkerweb/blobsrc/deps/clone.sh) for the complete list. If you need additional libraries, you can put them in the root folder of the plugin and access them by prefixing them with your plugin ID. Here is an example file named **mylibrary.lua** : @@ -507,7 +507,7 @@ end !!! tip "More examples" - If you want to see the full list of available functions, you can have a look at the files present in the [lua directory](https://github.com/bunkerity/bunkerweb/tree/vcurrent_bw_version/src/bw/lua/bunkerweb) of the repository. + If you want to see the full list of available functions, you can have a look at the files present in the [lua directory](https://github.com/bunkerity/bunkerweb/tree/v1.5.0-beta/src/bw/lua/bunkerweb) of the repository. ### Jobs @@ -515,7 +515,7 @@ BunkerWeb uses an internal job scheduler for periodic tasks like renewing certif ### Plugin page -Plugin pages are used to display information about your plugin and interact with the user inside the plugins section of the [web UI](/current_bw_version/web-ui). +Plugin pages are used to display information about your plugin and interact with the user inside the plugins section of the [web UI](web-ui.md). Everything related to the web UI is located inside a subfolder named **ui** at the root directory of your plugin. A template file named **template.html** and located inside the **ui** subfolder contains the client code and logic to display your page. Another file named **actions.py** and also located inside the **ui** subfolder contains code that will be executed when the user is interacting with your page (filling a form for example). @@ -554,4 +554,4 @@ def myplugin() : !!! info "Python libraries" You can use Python libraries that are already available like : - `Flask`, `Flask-Login`, `Flask-WTF`, `beautifulsoup4`, `docker`, `Jinja2`, `python-magic` and `requests`. To see the full list, you can have a look at the Web UI [requirements.txt](https://github.com/bunkerity/bunkerweb/blob/current_bw_version/src/ui/requirements.txt). If you need external libraries, you can install them inside the **ui** folder of your plugin and then use the classical **import** directive. + `Flask`, `Flask-Login`, `Flask-WTF`, `beautifulsoup4`, `docker`, `Jinja2`, `python-magic` and `requests`. To see the full list, you can have a look at the Web UI [requirements.txt](https://github.com/bunkerity/bunkerweb/blobsrc/ui/requirements.txt). If you need external libraries, you can install them inside the **ui** folder of your plugin and then use the classical **import** directive. diff --git a/docs/quickstart-guide.md b/docs/quickstart-guide.md index 9c40272a..f6fd06c9 100644 --- a/docs/quickstart-guide.md +++ b/docs/quickstart-guide.md @@ -1,10 +1,10 @@ # Quickstart guide !!! info "Prerequisites" - We assume that you're already familiar with the [core concepts](/current_bw_version/concepts) and you have followed the [integrations instructions](/current_bw_version/integrations) for your environment. + We assume that you're already familiar with the [core concepts](concepts.md) and you have followed the [integrations instructions](integrations.md) for your environment. !!! tip "Going further" - To demonstrate the use of BunkerWeb, we will deploy a dummy "Hello World" web application as an example. See the [examples folder](https://github.com/bunkerity/bunkerweb/tree/vcurrent_bw_version/examples) of the repository to get real-world examples. + To demonstrate the use of BunkerWeb, we will deploy a dummy "Hello World" web application as an example. See the [examples folder](https://github.com/bunkerity/bunkerweb/tree/v1.5.0-beta/examples) of the repository to get real-world examples. ## Protect HTTP applications @@ -16,7 +16,7 @@ The following settings can be used : - `REVERSE_PROXY_URL` : the public path prefix - `REVERSE_PROXY_HOST` : (internal) address of the proxied web application -You will find more settings about reverse proxy in the [settings section](/current_bw_version/settings/#reverse-proxy) of the documentation. +You will find more settings about reverse proxy in the [settings section](settings.md#reverse-proxy) of the documentation. ### Single application @@ -35,7 +35,7 @@ You will find more settings about reverse proxy in the [settings section](/curre - bw-services bunkerweb: - image: bunkerity/bunkerweb:current_bw_version + image: bunkerity/bunkerweb:1.5.0-beta ports: - 80:8080 - 443:8443 @@ -52,7 +52,7 @@ You will find more settings about reverse proxy in the [settings section](/curre - bw-services bw-scheduler: - image: bunkerity/bunkerweb-scheduler:current_bw_version + image: bunkerity/bunkerweb-scheduler:1.5.0-beta depends_on: - bunkerweb - bw-docker @@ -92,7 +92,7 @@ You will find more settings about reverse proxy in the [settings section](/curre === "Docker autoconf" - We will assume that you already have the [Docker autoconf integration](/current_bw_version/integrations/#docker-autoconf) stack running on your machine and connected to a network called `bw-services` so you can connect your existing application and configure BunkerWeb with labels : + We will assume that you already have the [Docker autoconf integration](integrations.md#docker-autoconf) stack running on your machine and connected to a network called `bw-services` so you can connect your existing application and configure BunkerWeb with labels : ```yaml version: '3.5' @@ -118,7 +118,7 @@ You will find more settings about reverse proxy in the [settings section](/curre === "Swarm" - We will assume that you already have the [Swarm integration](/current_bw_version/integrations/#swarm) stack running on your cluster and connected to a network called `bw-services` so you can connect your existing application and configure BunkerWeb with labels : + We will assume that you already have the [Swarm integration](integrations.md#swarm) stack running on your cluster and connected to a network called `bw-services` so you can connect your existing application and configure BunkerWeb with labels : ```yaml version: "3" @@ -148,7 +148,7 @@ You will find more settings about reverse proxy in the [settings section](/curre === "Kubernetes" - We will assume that you already have the [Kubernetes integration](/current_bw_version/integrations/#kubernetes) stack running on your cluster. + We will assume that you already have the [Kubernetes integration](integrations.md#kubernetes) stack running on your cluster. Let's assume that you have a typical Deployment with a Service to access the web application from within the cluster : @@ -213,7 +213,7 @@ You will find more settings about reverse proxy in the [settings section](/curre === "Linux" - We will assume that you already have the [Linux integration](/current_bw_version/integrations/#linux) stack running on your machine. + We will assume that you already have the [Linux integration](integrations.md#linux) stack running on your machine. The following command will run a basic HTTP server on the port 8000 and deliver the files in the current directory : @@ -299,7 +299,7 @@ You will find more settings about reverse proxy in the [settings section](/curre === "Vagrant" - We will assume that you already have the [Vagrant integration](/current_bw_version/integrations/#vagrant) stack running on your machine. + We will assume that you already have the [Vagrant integration](integrations.md#vagrant) stack running on your machine. The following command will run a basic HTTP server on the port 8000 and deliver the files in the current directory : @@ -385,7 +385,7 @@ You will find more settings about reverse proxy in the [settings section](/curre - bw-services bunkerweb: - image: bunkerity/bunkerweb:current_bw_version + image: bunkerity/bunkerweb:1.5.0-beta ports: - 80:8080 - 443:8443 @@ -405,7 +405,7 @@ You will find more settings about reverse proxy in the [settings section](/curre - bw-services bw-scheduler: - image: bunkerity/bunkerweb-scheduler:current_bw_version + image: bunkerity/bunkerweb-scheduler:1.5.0-beta depends_on: - bunkerweb - bw-docker @@ -444,7 +444,7 @@ You will find more settings about reverse proxy in the [settings section](/curre === "Docker autoconf" - We will assume that you already have the [Docker autoconf integration](/current_bw_version/integrations/#docker-autoconf) stack running on your machine and connected to a network called `bw-services` so you can connect your existing application and configure BunkerWeb with labels : + We will assume that you already have the [Docker autoconf integration](integrations.md#docker-autoconf) stack running on your machine and connected to a network called `bw-services` so you can connect your existing application and configure BunkerWeb with labels : ```yaml version: '3.5' @@ -494,7 +494,7 @@ You will find more settings about reverse proxy in the [settings section](/curre === "Swarm" - We will assume that you already have the [Swarm integration](/current_bw_version/integrations/#swarm) stack running on your cluster and connected to a network called `bw-services` so you can connect your existing application and configure BunkerWeb with labels : + We will assume that you already have the [Swarm integration](integrations.md#swarm) stack running on your cluster and connected to a network called `bw-services` so you can connect your existing application and configure BunkerWeb with labels : ```yaml version: "3" @@ -556,7 +556,7 @@ You will find more settings about reverse proxy in the [settings section](/curre === "Kubernetes" - We will assume that you already have the [Kubernetes integration](/current_bw_version/integrations/#kubernetes) stack running on your cluster. + We will assume that you already have the [Kubernetes integration](integrations.md#kubernetes) stack running on your cluster. Let's assume that you have typical Deployments with a Service to access the web applications from within the cluster : @@ -642,7 +642,7 @@ You will find more settings about reverse proxy in the [settings section](/curre === "Linux" - We will assume that you already have the [Linux integration](/current_bw_version/integrations/#linux) stack running on your machine. + We will assume that you already have the [Linux integration](integrations.md#linux) stack running on your machine. The following command will run a basic HTTP server on the port 8001 and deliver the files in the current directory (repeat it and change the port if you want to test BunkerWeb) : @@ -734,7 +734,7 @@ You will find more settings about reverse proxy in the [settings section](/curre === "Vagrant" - We will assume that you already have the [Vagrant integration](/current_bw_version/integrations/#vagrant) stack running on your machine. + We will assume that you already have the [Vagrant integration](integrations.md#vagrant) stack running on your machine. First of all, connect to your vagrant machine : @@ -797,7 +797,7 @@ The following settings can be used : - `REAL_IP_FROM` : list of trusted IP/network address allowed to send us the "real IP" - `REAL_IP_HEADER` : the HTTP header containing the real IP or special value `proxy_protocol` when using PROXY protocol -You will find more settings about real IP in the [settings section](/current_bw_version/settings/#real-ip) of the documentation. +You will find more settings about real IP in the [settings section](settings.md#real-ip) of the documentation. ### HTTP header @@ -820,7 +820,7 @@ REAL_IP_HEADER=X-Forwarded-For ```yaml mybunker: - image: bunkerity/bunkerweb:current_bw_version + image: bunkerity/bunkerweb:1.5.0-beta ... environment: - USE_REAL_IP=yes @@ -831,11 +831,11 @@ REAL_IP_HEADER=X-Forwarded-For === "Docker autoconf" - Before running the [Docker autoconf integration](/current_bw_version/integrations/#docker-autoconf) stack, you will need to add the settings for the BunkerWeb container : + Before running the [Docker autoconf integration](integrations.md#docker-autoconf) stack, you will need to add the settings for the BunkerWeb container : ```yaml mybunker: - image: bunkerity/bunkerweb:current_bw_version + image: bunkerity/bunkerweb:1.5.0-beta ... environment: - USE_REAL_IP=yes @@ -846,11 +846,11 @@ REAL_IP_HEADER=X-Forwarded-For === "Swarm" - Before running the [Swarm integration](/current_bw_version/integrations/#swarm) stack, you will need to add the settings for the BunkerWeb service : + Before running the [Swarm integration](integrations.md#swarm) stack, you will need to add the settings for the BunkerWeb service : ```yaml mybunker: - image: bunkerity/bunkerweb:current_bw_version + image: bunkerity/bunkerweb:1.5.0-beta ... environment: - USE_REAL_IP=yes @@ -970,7 +970,7 @@ REAL_IP_HEADER=proxy_protocol ```yaml mybunker: - image: bunkerity/bunkerweb:current_bw_version + image: bunkerity/bunkerweb:1.5.0-beta ... environment: - USE_REAL_IP=yes @@ -982,11 +982,11 @@ REAL_IP_HEADER=proxy_protocol === "Docker autoconf" - Before running the [Docker autoconf integration](/current_bw_version/integrations/#docker-autoconf) stack, you will need to add the settings for the BunkerWeb container : + Before running the [Docker autoconf integration](integrations.md#docker-autoconf) stack, you will need to add the settings for the BunkerWeb container : ```yaml mybunker: - image: bunkerity/bunkerweb:current_bw_version + image: bunkerity/bunkerweb:1.5.0-beta ... environment: - USE_REAL_IP=yes @@ -998,11 +998,11 @@ REAL_IP_HEADER=proxy_protocol === "Swarm" - Before running the [Swarm integration](/current_bw_version/integrations/#swarm) stack, you will need to add the settings for the BunkerWeb service : + Before running the [Swarm integration](integrations.md#swarm) stack, you will need to add the settings for the BunkerWeb service : ```yaml mybunker: - image: bunkerity/bunkerweb:current_bw_version + image: bunkerity/bunkerweb:1.5.0-beta ... environment: - USE_REAL_IP=yes @@ -1113,7 +1113,7 @@ REAL_IP_HEADER=proxy_protocol BunkerWeb can also act as **generic UDP/TCP reverse proxy** : you can protect any network-based applications working at least on layer 4 of the OSI model. Behind the hood, it leverages the [stream module](https://nginx.org/en/docs/stream/ngx_stream_core_module.html) of NGINX instead of using the "classical" http one. -Please note that not all settings and security features are available when using the stream module. You will find more info about that in the [security tuning](/current_bw_version/security-tuning/) and [settings](/current_bw_version/settings/) sections of the documentation. +Please note that not all settings and security features are available when using the stream module. You will find more info about that in the [security tuning](security-tuning.md) and [settings](settings.md) sections of the documentation. Configuration for a basic reverse proxy is very similar to the HTTP one because it uses the same `USE_REVERSE_PROXY=yes` and `REVERSE_PROXY_HOST=myapp:4242` settings. Even the settings used when BunkerWeb is [behind a Load Balancer](#behind-load-balancer-or-reverse-proxy) are the same (but for obvious reasons, only **PROXY protocol** is supported). @@ -1124,7 +1124,7 @@ On top of that, the following specific settings are used : - `LISTEN_STREAM_PORT_SSL=4343` : the listening "ssl/tls" port that BunkerWeb will listen on - `USE_UDP=no` : listen for and forward UDP packets instead of TCP -For complete list of settings regarding `stream` mode, please refer to the [settings](/current_bw_version/settings/) section of the documentation. +For complete list of settings regarding `stream` mode, please refer to the [settings](settings.md) section of the documentation. === "Docker" @@ -1148,7 +1148,7 @@ For complete list of settings regarding `stream` mode, please refer to the [sett - bw-services bunkerweb: - image: bunkerity/bunkerweb:current_bw_version + image: bunkerity/bunkerweb:1.5.0-beta ports: - 80:8080 # Keep it if you want to use Let's Encrypt automation - 10000:10000 # app1 @@ -1170,7 +1170,7 @@ For complete list of settings regarding `stream` mode, please refer to the [sett - bw-services bw-scheduler: - image: bunkerity/bunkerweb-scheduler:current_bw_version + image: bunkerity/bunkerweb-scheduler:1.5.0-beta depends_on: - bunkerweb - bw-docker @@ -1210,7 +1210,7 @@ For complete list of settings regarding `stream` mode, please refer to the [sett === "Docker autoconf" - Before running the [Docker autoconf integration](/current_bw_version/integrations/#docker-autoconf) stack on your machine, you will need to edit the ports : + Before running the [Docker autoconf integration](integrations.md#docker-autoconf) stack on your machine, you will need to edit the ports : ```yaml version: "3.5" @@ -1218,7 +1218,7 @@ For complete list of settings regarding `stream` mode, please refer to the [sett services: bunkerweb: - image: bunkerity/bunkerweb:current_bw_version + image: bunkerity/bunkerweb:1.5.0-beta ports: - 80:8080 # Keep it if you want to use Let's Encrypt automation - 10000:10000 # app1 @@ -1269,14 +1269,14 @@ For complete list of settings regarding `stream` mode, please refer to the [sett === "Swarm" - Before running the [Swarm integration](/current_bw_version/integrations/#swarm) stack on your machine, you will need to edit the ports : + Before running the [Swarm integration](integrations.md#swarm) stack on your machine, you will need to edit the ports : ```yaml version: "3.5" services: bunkerweb: - image: bunkerity/bunkerweb:current_bw_version + image: bunkerity/bunkerweb:1.5.0-beta ports: # Keep it if you want to use Let's Encrypt automation - published: 80 @@ -1343,7 +1343,7 @@ For complete list of settings regarding `stream` mode, please refer to the [sett === "Kubernetes" - Protection TCP/UDP applications using the `stream` feature is not yet supported when using the [Kubernetes integration](/current_bw_version/integrations/#kubernetes). + Protection TCP/UDP applications using the `stream` feature is not yet supported when using the [Kubernetes integration](integrations.md#kubernetes). === "Linux" @@ -1426,7 +1426,7 @@ For complete list of settings regarding `stream` mode, please refer to the [sett ## Custom configurations -Because BunkerWeb is based on the NGINX web server, you can add custom NGINX configurations in different NGINX contexts. You can also apply custom configurations for the ModSecurity WAF which is a core component of BunkerWeb (more info [here](/current_bw_version/security-tuning/#modsecurity)). Here is the list of custom configurations types : +Because BunkerWeb is based on the NGINX web server, you can add custom NGINX configurations in different NGINX contexts. You can also apply custom configurations for the ModSecurity WAF which is a core component of BunkerWeb (more info [here](security-tuning.md#modsecurity)). Here is the list of custom configurations types : - **http** : http level of NGINX - **server-http** : http/server level of NGINX @@ -1444,7 +1444,7 @@ Some integrations offer a more convenient way of applying configurations such as === "Docker" - When using the [Docker integration](/current_bw_version/integrations/#docker), you have two choices for the addition of custom configurations : + When using the [Docker integration](integrations.md#docker), you have two choices for the addition of custom configurations : - Using specific settings `*_CUSTOM_CONF_*` as environment variables (recommended) - Writing .conf files to the volume mounted on /data of the scheduler @@ -1462,7 +1462,7 @@ Some integrations offer a more convenient way of applying configurations such as ```yaml ... mybunker: - image: bunkerity/bunkerweb:current_bw_version + image: bunkerity/bunkerweb:1.5.0-beta environment: - | CUSTOM_CONF_SERVER_HTTP_hello-world= @@ -1505,7 +1505,7 @@ Some integrations offer a more convenient way of applying configurations such as ```yaml mybunker: - image: bunkerity/bunkerweb:current_bw_version + image: bunkerity/bunkerweb:1.5.0-beta volumes: - ./bw-data:/data ... @@ -1513,7 +1513,7 @@ Some integrations offer a more convenient way of applying configurations such as === "Docker autoconf" - When using the [Docker autoconf integration](/current_bw_version/integrations/#docker-autoconf), you have two choices for adding custom configurations : + When using the [Docker autoconf integration](integrations.md#docker-autoconf), you have two choices for adding custom configurations : - Using specific settings `*_CUSTOM_CONF_*` as labels (easiest) - Writing .conf files to the volume mounted on /data of the scheduler @@ -1574,7 +1574,7 @@ Some integrations offer a more convenient way of applying configurations such as ```yaml myautoconf: - image: bunkerity/bunkerweb-scheduler:current_bw_version + image: bunkerity/bunkerweb-scheduler:1.5.0-beta volumes: - ./bw-data:/data ... @@ -1582,7 +1582,7 @@ Some integrations offer a more convenient way of applying configurations such as === "Swarm" - When using the [Swarm integration](/current_bw_version/integrations/#swarm), custom configurations are managed using [Docker Configs](https://docs.docker.com/engine/swarm/configs/). + When using the [Swarm integration](integrations.md#swarm), custom configurations are managed using [Docker Configs](https://docs.docker.com/engine/swarm/configs/). To keep it simple, you don't even need to attach the Config to a service : the autoconf service is listening for Config events and will update the custom configurations when needed. @@ -1606,7 +1606,7 @@ Some integrations offer a more convenient way of applying configurations such as === "Kubernetes" - When using the [Kubernetes integration](/current_bw_version/integrations/#kubernetes), custom configurations are managed using [ConfigMap](https://kubernetes.io/docs/concepts/configuration/configmap/). + When using the [Kubernetes integration](integrations.md#kubernetes), custom configurations are managed using [ConfigMap](https://kubernetes.io/docs/concepts/configuration/configmap/). To keep it simple, you don't even need to use the ConfigMap with a Pod (e.g. as environment variable or volume) : the autoconf Pod is listening for ConfigMap events and will update the custom configurations when needed. @@ -1636,7 +1636,7 @@ Some integrations offer a more convenient way of applying configurations such as === "Linux" - When using the [Linux integration](/current_bw_version/integrations/#linux), custom configurations must be written to the /etc/bunkerweb/configs folder. + When using the [Linux integration](integrations.md#linux), custom configurations must be written to the /etc/bunkerweb/configs folder. Here is an example for server-http/hello-world.conf : @@ -1701,7 +1701,7 @@ Some integrations offer a more convenient way of applying configurations such as === "Vagrant" - When using the [Vagrant integration](/current_bw_version/integrations/#vagrant), custom configurations must be written to the `/etc/bunkerweb/configs` folder. + When using the [Vagrant integration](integrations.md#vagrant), custom configurations must be written to the `/etc/bunkerweb/configs` folder. Here is an example for server-http/hello-world.conf : @@ -1750,13 +1750,13 @@ BunkerWeb supports PHP using external or remote [PHP-FPM](https://www.php.net/ma === "Docker" - When using the [Docker integration](/current_bw_version/integrations/#docker), to support PHP applications, you will need to : + When using the [Docker integration](integrations.md#docker), to support PHP applications, you will need to : - Mount your PHP files into the `/var/www/html` folder of BunkerWeb - Set up a PHP-FPM container for your application and mount the folder containing PHP files - Use the specific settings `REMOTE_PHP` and `REMOTE_PHP_PATH` as environment variables when starting BunkerWeb - If you enable the [multisite mode](/current_bw_version/concepts/#integration), you will need to create separate directories for each of your applications. Each subdirectory should be named using the first value of `SERVER_NAME`. Here is a dummy example : + If you enable the [multisite mode](concepts.md#integration), you will need to create separate directories for each of your applications. Each subdirectory should be named using the first value of `SERVER_NAME`. Here is a dummy example : ``` www @@ -1807,7 +1807,7 @@ BunkerWeb supports PHP using external or remote [PHP-FPM](https://www.php.net/ma - bw-services bunkerweb: - image: bunkerity/bunkerweb:current_bw_version + image: bunkerity/bunkerweb:1.5.0-beta volumes: - ./www:/var/www/html ports: @@ -1830,7 +1830,7 @@ BunkerWeb supports PHP using external or remote [PHP-FPM](https://www.php.net/ma - bw-services bw-scheduler: - image: bunkerity/bunkerweb-scheduler:current_bw_version + image: bunkerity/bunkerweb-scheduler:1.5.0-beta depends_on: - bunkerweb - bw-docker @@ -1870,15 +1870,15 @@ BunkerWeb supports PHP using external or remote [PHP-FPM](https://www.php.net/ma === "Docker autoconf" !!! info "Multisite mode enabled" - The [Docker autoconf integration](/current_bw_version/integrations/#docker-autoconf) integration implies the use of multisite mode : protecting one PHP application is the same as protecting multiple ones. + The [Docker autoconf integration](integrations.md#docker-autoconf) integration implies the use of multisite mode : protecting one PHP application is the same as protecting multiple ones. - When using the [Docker autoconf integration](/current_bw_version/integrations/#docker-autoconf), to support PHP applications, you will need to : + When using the [Docker autoconf integration](integrations.md#docker-autoconf), to support PHP applications, you will need to : - Mount your PHP files into the `/var/www/html` folder of BunkerWeb - Set up a PHP-FPM containers for your applications and mount the folder containing PHP apps - Use the specific settings `REMOTE_PHP` and `REMOTE_PHP_PATH` as labels for your PHP-FPM container - Since the Docker autoconf implies using the [multisite mode](/current_bw_version/concepts/#integration), you will need to create separate directories for each of your applications. Each subdirectory should be named using the first value of `SERVER_NAME`. Here is a dummy example : + Since the Docker autoconf implies using the [multisite mode](concepts.md#integration), you will need to create separate directories for each of your applications. Each subdirectory should be named using the first value of `SERVER_NAME`. Here is a dummy example : ``` www @@ -1907,7 +1907,7 @@ BunkerWeb supports PHP using external or remote [PHP-FPM](https://www.php.net/ma services: bunkerweb: - image: bunkerity/bunkerweb:current_bw_version + image: bunkerity/bunkerweb:1.5.0-beta volumes: - ./www:/var/www/html labels: @@ -1921,7 +1921,7 @@ BunkerWeb supports PHP using external or remote [PHP-FPM](https://www.php.net/ma - bw-services bw-scheduler: - image: bunkerity/bunkerweb-scheduler:current_bw_version + image: bunkerity/bunkerweb-scheduler:1.5.0-beta depends_on: - bunkerweb - bw-docker @@ -2022,18 +2022,18 @@ BunkerWeb supports PHP using external or remote [PHP-FPM](https://www.php.net/ma === "Swarm" !!! info "Multisite mode enabled" - The [Swarm integration](/current_bw_version/integrations/#docker-autoconf) integration implies the use of multisite mode : protecting one PHP application is the same as protecting multiple ones. + The [Swarm integration](integrations.md#docker-autoconf) integration implies the use of multisite mode : protecting one PHP application is the same as protecting multiple ones. !!! info "Shared volume" Using PHP with the Docker Swarm integration needs a shared volume between all BunkerWeb and PHP-FPM instances which is not covered in this documentation. - When using the [Docker autoconf integration](/current_bw_version/integrations/#docker-autoconf), to support PHP applications, you will need to : + When using the [Docker autoconf integration](integrations.md#docker-autoconf), to support PHP applications, you will need to : - Mount your PHP files into the `/var/www/html` folder of BunkerWeb - Set up a PHP-FPM containers for your applications and mount the folder containing PHP apps - Use the specific settings `REMOTE_PHP` and `REMOTE_PHP_PATH` as labels for your PHP-FPM container - Since the Swarm integration implies using the [multisite mode](/current_bw_version/concepts/#integration), you will need to create separate directories for each of your applications. Each subdirectory should be named using the first value of `SERVER_NAME`. Here is a dummy example : + Since the Swarm integration implies using the [multisite mode](concepts.md#integration), you will need to create separate directories for each of your applications. Each subdirectory should be named using the first value of `SERVER_NAME`. Here is a dummy example : ``` www @@ -2064,7 +2064,7 @@ BunkerWeb supports PHP using external or remote [PHP-FPM](https://www.php.net/ma services: bunkerweb: - image: bunkerity/bunkerweb:current_bw_version + image: bunkerity/bunkerweb:1.5.0-beta volumes: - /shared/www:/var/www/html ... @@ -2139,7 +2139,7 @@ BunkerWeb supports PHP using external or remote [PHP-FPM](https://www.php.net/ma === "Linux" - We will assume that you already have the [Linux integration](/current_bw_version/integrations/#linux) stack running on your machine. + We will assume that you already have the [Linux integration](integrations.md#linux) stack running on your machine. By default, BunkerWeb will search for web files inside the `/var/www/html` folder. You can use it to store your PHP applications. Please note that you will need to configure your PHP-FPM service to get or set the user/group of the running processes and the UNIX socket file used to communicate with BunkerWeb. @@ -2163,7 +2163,7 @@ BunkerWeb supports PHP using external or remote [PHP-FPM](https://www.php.net/ma systemctl restart php-fpm ``` - If you enable the [multisite mode](/current_bw_version/concepts/#integration), you will need to create separate directories for each of your applications. Each subdirectory should be named using the first value of `SERVER_NAME`. Here is a dummy example : + If you enable the [multisite mode](concepts.md#integration), you will need to create separate directories for each of your applications. Each subdirectory should be named using the first value of `SERVER_NAME`. Here is a dummy example : ``` /var/www/html @@ -2224,7 +2224,7 @@ BunkerWeb supports PHP using external or remote [PHP-FPM](https://www.php.net/ma !!! info "Linux" Please follow the instruction for Linux integration to create a local `www` folder (permissions are not needed, Ansible will do it for you). - We will assume that you already have the [Ansible integration](/current_bw_version/integrations/#ansible) setup on your machine. + We will assume that you already have the [Ansible integration](integrations.md#ansible) setup on your machine. Content of the `my_variables.env` configuration file : @@ -2273,7 +2273,7 @@ BunkerWeb supports PHP using external or remote [PHP-FPM](https://www.php.net/ma !!! info "Linux" Please follow the instruction for Linux integration to create the `/var/www/html` folder. - We will assume that you already have the [Vagrant integration](/current_bw_version/integrations/#vagrant) stack running on your machine. + We will assume that you already have the [Vagrant integration](integrations.md#vagrant) stack running on your machine. Once PHP files are copied into the `/var/www/html`folder, you can now edit the `/etc/bunkerweb/variable.env` file : diff --git a/docs/requirements.txt b/docs/requirements.txt index 62b604c7..93dcf966 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -3,3 +3,4 @@ mkdocs-material==9.1.8 pytablewriter==0.64.2 mike==1.1.2 jinja2<3.1.0 +mkdocs-print-site-plugin==2.3.4 \ No newline at end of file diff --git a/docs/security-tuning.md b/docs/security-tuning.md index 5deefad0..6df239bd 100644 --- a/docs/security-tuning.md +++ b/docs/security-tuning.md @@ -1,9 +1,9 @@ # Security tuning -BunkerWeb offers many security features that you can configure with [settings](/current_bw_version/settings). Even if the default values of settings ensure a minimal "security by default", we strongly recommend you tune them. By doing so you will be able to ensure the security level of your choice but also manage false positives. +BunkerWeb offers many security features that you can configure with [settings](settings.md). Even if the default values of settings ensure a minimal "security by default", we strongly recommend you tune them. By doing so you will be able to ensure the security level of your choice but also manage false positives. !!! tip "Other settings" - This section only focuses on security tuning, see the [settings section](/current_bw_version/settings) of the documentation for other settings. + This section only focuses on security tuning, see the [settings section](settings.md) of the documentation for other settings.
![Overview](assets/img/core-order.svg){ align=center } @@ -98,7 +98,7 @@ Various security headers are available and most of them can be set using BunkerW STREAM support :x: -[Cross-Origin Resource Sharing](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) lets you manage how your service can be contacted from different origins. Please note that you will have to allow the `OPTIONS` HTTP method using the `ALLOWED_METHODS` if you want to enable it (more info [here](https://docs.bunkerweb.io/current_bw_version/security-tuning/#allowed-methods)). Here is the list of settings related to CORS : +[Cross-Origin Resource Sharing](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) lets you manage how your service can be contacted from different origins. Please note that you will have to allow the `OPTIONS` HTTP method using the `ALLOWED_METHODS` if you want to enable it (more info [here](#allowed-methods)). Here is the list of settings related to CORS : | Setting | Default | Context |Multiple| Description | |------------------------|------------------------------------------------------------------------------------|---------|--------|--------------------------------------------------| @@ -183,7 +183,7 @@ ModSecurity is integrated and enabled by default alongside the OWASP Core Rule S We strongly recommend keeping both ModSecurity and the OWASP Core Rule Set enabled. The only downsides are the false positives that may occur. But they can be fixed with some efforts and the CRS team maintains a list of exclusions for common applications (e.g., WordPress, Nextcloud, Drupal, Cpanel, ...). -Tuning ModSecurity and the CRS can be done using [custom configurations](/current_bw_version/quickstart-guide/#custom-configurations) : +Tuning ModSecurity and the CRS can be done using [custom configurations](quickstart-guide.md#custom-configurations) : - modsec-crs : before the OWASP Core Rule Set is loaded - modsec : after the OWASP Core Rule Set is loaded (also used if CRS is not loaded) @@ -456,7 +456,7 @@ You can quickly protect sensitive resources like the admin area for example, by ### Auth request -You can deploy complex authentication (e.g. SSO), by using the auth request settings (see [here](https://docs.nginx.com/nginx/admin-guide/security-controls/configuring-subrequest-authentication/) for more information on the feature). Please note that you will find [Authelia](https://www.authelia.com/) and [Authentik](https://goauthentik.io/) examples in the [repository](https://github.com/bunkerity/bunkerweb/tree/vcurrent_bw_version/examples). +You can deploy complex authentication (e.g. SSO), by using the auth request settings (see [here](https://docs.nginx.com/nginx/admin-guide/security-controls/configuring-subrequest-authentication/) for more information on the feature). Please note that you will find [Authelia](https://www.authelia.com/) and [Authentik](https://goauthentik.io/) examples in the [repository](https://github.com/bunkerity/bunkerweb/tree/v1.5.0-beta/examples). **Auth request settings are related to reverse proxy rules.** diff --git a/docs/settings.md b/docs/settings.md index a6d3c78c..9feb9ed4 100644 --- a/docs/settings.md +++ b/docs/settings.md @@ -4,7 +4,7 @@ To help you tune BunkerWeb, we have made an easy-to-use settings generator tool available at [config.bunkerweb.io](https://config.bunkerweb.io). -This section contains the full list of settings supported by BunkerWeb. If you are not yet familiar with BunkerWeb, you should first read the [concepts](/1.4/concepts) section of the documentation. Please follow the instructions for your own [integration](/1.4/integrations) on how to apply the settings. +This section contains the full list of settings supported by BunkerWeb. If you are not yet familiar with BunkerWeb, you should first read the [concepts](concepts.md) section of the documentation. Please follow the instructions for your own [integration](integrations.md) on how to apply the settings. As a general rule when multisite mode is enabled, if you want to apply settings with multisite context to a specific server, you will need to add the primary (first) server name as a prefix like `www.example.com_USE_ANTIBOT=captcha` or `myapp.example.com_USE_GZIP=yes` for example. diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index d8091c7b..80e249c9 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -114,7 +114,7 @@ Here is how you can access the logs, depending on your integration : ## Permissions -Don't forget that BunkerWeb runs as an unprivileged user for obvious security reasons. Double-check the permissions of files and folders used by BunkerWeb, especially if you use custom configurations (more info [here](/current_bw_version/quickstart-guide/#custom-configurations)). You will need to set at least **RW** rights on files and **_RWX_** on folders. +Don't forget that BunkerWeb runs as an unprivileged user for obvious security reasons. Double-check the permissions of files and folders used by BunkerWeb, especially if you use custom configurations (more info [here](quickstart-guide.md#custom-configurations)). You will need to set at least **RW** rights on files and **_RWX_** on folders. ## ModSecurity @@ -205,11 +205,11 @@ As we can see, there are 3 different logs : One important thing to understand is that rule **949110** is not a "real" one : it's the one that will deny the request because the anomaly threshold is reached (which is **10** in this example). You should never remove the **949110** rule ! -If it's a false-positive, you should then focus on both **930120** and **932160** rules. ModSecurity and/or CRS tuning is out of the scope of this documentation but don't forget that you can apply custom configurations before and after the CRS is loaded (more info [here](/current_bw_version/quickstart-guide/#custom-configurations)). +If it's a false-positive, you should then focus on both **930120** and **932160** rules. ModSecurity and/or CRS tuning is out of the scope of this documentation but don't forget that you can apply custom configurations before and after the CRS is loaded (more info [here](quickstart-guide.md#custom-configurations)). ## Bad Behavior -A common false-positive case is when the client is banned because of the "bad behavior" feature which means that too many suspicious HTTP status codes were generated within a time period (more info [here](/current_bw_version/security-tuning/#bad-behavior)). You should start by reviewing the settings and then edit them according to your web application(s) like removing a suspicious HTTP code, decreasing the count time, increasing the threshold, ... +A common false-positive case is when the client is banned because of the "bad behavior" feature which means that too many suspicious HTTP status codes were generated within a time period (more info [here](security-tuning.md#bad-behavior)). You should start by reviewing the settings and then edit them according to your web application(s) like removing a suspicious HTTP code, decreasing the count time, increasing the threshold, ... ## IP unban @@ -276,7 +276,7 @@ You can manually unban an IP which can be useful when doing some tests but it ne ## Whitelisting -If you have bots that need to access your website, the recommended way to avoid any false positive is to whitelist them using the [whitelisting feature](/current_bw_version/security-tuning/#blacklisting-and-whitelisting). We don't recommend using the `WHITELIST_URI*` or `WHITELIST_USER_AGENT*` settings unless they are set to secret and unpredictable values. Common use cases are : +If you have bots that need to access your website, the recommended way to avoid any false positive is to whitelist them using the [whitelisting feature](security-tuning.md#blacklisting-and-whitelisting). We don't recommend using the `WHITELIST_URI*` or `WHITELIST_USER_AGENT*` settings unless they are set to secret and unpredictable values. Common use cases are : - Healthcheck / status bot - Callback like IPN or webhook diff --git a/docs/web-ui.md b/docs/web-ui.md index 99dfb48c..0f165dcd 100644 --- a/docs/web-ui.md +++ b/docs/web-ui.md @@ -29,11 +29,11 @@ Because the web UI is a web application, the recommended installation procedure * Choose a strong password for the login * Put the web UI under a "hard to guess" URI * Do not open the web UI on the Internet without any further restrictions - * Apply settings listed in the [security tuning section](/current_bw_version/security-tuning/) of the documentation + * Apply settings listed in the [security tuning section](security-tuning.md) of the documentation !!! info "Multisite mode" - The usage of the web UI implies enabling the [multisite mode](/current_bw_version/concepts/#multisite-mode). + The usage of the web UI implies enabling the [multisite mode](concepts.md#multisite-mode). === "Docker" @@ -57,11 +57,11 @@ Because the web UI is a web application, the recommended installation procedure - `ADMIN_PASSWORD` : password to access the web UI - `ABSOLUTE_URI` : full URI of your web UI instance (like `http://www.example.com/foo/`) - Accessing the web UI through BunkerWeb is a classical [reverse proxy setup](/current_bw_version/quickstart-guide/#protect-http-applications). We recommend you to connect BunkerWeb and web UI using a dedicated network (like `bw-universe` also used by the scheduler) so it won't be on the same network of your web services for obvious security reasons. Please note that the web UI container is listening on the `7000` port. + Accessing the web UI through BunkerWeb is a classical [reverse proxy setup](quickstart-guide.md#protect-http-applications). We recommend you to connect BunkerWeb and web UI using a dedicated network (like `bw-universe` also used by the scheduler) so it won't be on the same network of your web services for obvious security reasons. Please note that the web UI container is listening on the `7000` port. !!! info "Database backend" - If you want another Database backend than MariaDB please refer to the docker-compose files in the [misc/integrations folder](https://github.com/bunkerity/bunkerweb/tree/vcurrent_bw_version/misc/integrations) of the repository. + If you want another Database backend than MariaDB please refer to the docker-compose files in the [misc/integrations folder](https://github.com/bunkerity/bunkerweb/tree/v1.5.0-beta/misc/integrations) of the repository. Here is the docker-compose boilerplate that you can use (don't forget to edit the `changeme` data) : @@ -70,7 +70,7 @@ Because the web UI is a web application, the recommended installation procedure services: bunkerweb: - image: bunkerity/bunkerweb:current_bw_version + image: bunkerity/bunkerweb:1.5.0-beta ports: - 80:8080 - 443:8443 @@ -95,7 +95,7 @@ Because the web UI is a web application, the recommended installation procedure - bw-services bw-scheduler: - image: bunkerity/bunkerweb-scheduler:current_bw_version + image: bunkerity/bunkerweb-scheduler:1.5.0-beta depends_on: - bunkerweb - bw-docker @@ -116,7 +116,7 @@ Because the web UI is a web application, the recommended installation procedure - bw-docker bw-ui: - image: bunkerity/bunkerweb-ui:current_bw_version + image: bunkerity/bunkerweb-ui:1.5.0-beta depends_on: - bw-docker environment: @@ -179,11 +179,11 @@ Because the web UI is a web application, the recommended installation procedure - `ADMIN_PASSWORD` : password to access the web UI - `ABSOLUTE_URI` : full URI of your web UI instance (like `http://www.example.com/foo/`) - Accessing the web UI through BunkerWeb is a classical [reverse proxy setup](/current_bw_version/quickstart-guide/#protect-http-applications). We recommend you to connect BunkerWeb and web UI using a dedicated network (like `bw-universe` also used by the scheduler and autoconf) so it won't be on the same network of your web services for obvious security reasons. Please note that the web UI container is listening on the `7000` port. + Accessing the web UI through BunkerWeb is a classical [reverse proxy setup](quickstart-guide.md#protect-http-applications). We recommend you to connect BunkerWeb and web UI using a dedicated network (like `bw-universe` also used by the scheduler and autoconf) so it won't be on the same network of your web services for obvious security reasons. Please note that the web UI container is listening on the `7000` port. !!! info "Database backend" - If you want another Database backend than MariaDB please refer to the docker-compose files in the [misc/integrations folder](https://github.com/bunkerity/bunkerweb/tree/vcurrent_bw_version/misc/integrations) of the repository. + If you want another Database backend than MariaDB please refer to the docker-compose files in the [misc/integrations folder](https://github.com/bunkerity/bunkerweb/tree/v1.5.0-beta/misc/integrations) of the repository. Here is the docker-compose boilerplate that you can use (don't forget to edit the `changeme` data) : @@ -192,7 +192,7 @@ Because the web UI is a web application, the recommended installation procedure services: bunkerweb: - image: bunkerity/bunkerweb:current_bw_version + image: bunkerity/bunkerweb:1.5.0-beta ports: - 80:8080 - 443:8443 @@ -209,7 +209,7 @@ Because the web UI is a web application, the recommended installation procedure - bw-services bw-autoconf: - image: bunkerity/bunkerweb-autoconf:current_bw_version + image: bunkerity/bunkerweb-autoconf:1.5.0-beta depends_on: - bunkerweb - bw-docker @@ -222,7 +222,7 @@ Because the web UI is a web application, the recommended installation procedure - bw-docker bw-scheduler: - image: bunkerity/bunkerweb-scheduler:current_bw_version + image: bunkerity/bunkerweb-scheduler:1.5.0-beta depends_on: - bunkerweb - bw-docker @@ -256,7 +256,7 @@ Because the web UI is a web application, the recommended installation procedure - bw-docker bw-ui: - image: bunkerity/bunkerweb-ui:current_bw_version + image: bunkerity/bunkerweb-ui:1.5.0-beta networks: bw-docker: bw-universe: @@ -316,11 +316,11 @@ Because the web UI is a web application, the recommended installation procedure - `ADMIN_PASSWORD` : password to access the web UI - `ABSOLUTE_URI` : full URI of your web UI instance (like `http://www.example.com/foo/`) - Accessing the web UI through BunkerWeb is a classical [reverse proxy setup](/current_bw_version/quickstart-guide/#protect-http-applications). We recommend you to connect BunkerWeb and web UI using a dedicated network (like `bw-universe` also used by the scheduler and autoconf) so it won't be on the same network of your web services for obvious security reasons. Please note that the web UI container is listening on the `7000` port. + Accessing the web UI through BunkerWeb is a classical [reverse proxy setup](quickstart-guide.md#protect-http-applications). We recommend you to connect BunkerWeb and web UI using a dedicated network (like `bw-universe` also used by the scheduler and autoconf) so it won't be on the same network of your web services for obvious security reasons. Please note that the web UI container is listening on the `7000` port. !!! info "Database backend" - If you want another Database backend than MariaDB please refer to the stack files in the [misc/integrations folder](https://github.com/bunkerity/bunkerweb/tree/vcurrent_bw_version/misc/integrations) of the repository. + If you want another Database backend than MariaDB please refer to the stack files in the [misc/integrations folder](https://github.com/bunkerity/bunkerweb/tree/v1.5.0-beta/misc/integrations) of the repository. Here is the stack boilerplate that you can use (don't forget to edit the `changeme` data) : @@ -329,7 +329,7 @@ Because the web UI is a web application, the recommended installation procedure services: bunkerweb: - image: bunkerity/bunkerweb:current_bw_version + image: bunkerity/bunkerweb:1.5.0-beta ports: - published: 80 target: 8080 @@ -359,7 +359,7 @@ Because the web UI is a web application, the recommended installation procedure - "bunkerweb.INSTANCE" bw-autoconf: - image: bunkerity/bunkerweb-autoconf:current_bw_version + image: bunkerity/bunkerweb-autoconf:1.5.0-beta environment: - SWARM_MODE=yes - DOCKER_HOST=tcp://bw-docker:2375 @@ -386,7 +386,7 @@ Because the web UI is a web application, the recommended installation procedure - "node.role == manager" bw-scheduler: - image: bunkerity/bunkerweb-scheduler:current_bw_version + image: bunkerity/bunkerweb-scheduler:1.5.0-beta environment: - SWARM_MODE=yes - DOCKER_HOST=tcp://bw-docker:2375 @@ -413,7 +413,7 @@ Because the web UI is a web application, the recommended installation procedure - bw-universe bw-ui: - image: bunkerity/bunkerweb-ui:current_bw_version + image: bunkerity/bunkerweb-ui:1.5.0-beta environment: - DATABASE_URI=mariadb+pymysql://bunkerweb:changeme@bw-db:3306/db # Remember to set a stronger password for the database - DOCKER_HOST=tcp://bw-docker:2375 @@ -465,11 +465,11 @@ Because the web UI is a web application, the recommended installation procedure - `ADMIN_PASSWORD` : password to access the web UI - `ABSOLUTE_URI` : full URI of your web UI instance (like `http://www.example.com/foo/`) - Accessing the web UI through BunkerWeb is a classical [reverse proxy setup](/current_bw_version/quickstart-guide/#protect-http-applications). Network segmentation between web UI and web services is not covered in this documentation. Please note that the web UI container is listening on the `7000` port. + Accessing the web UI through BunkerWeb is a classical [reverse proxy setup](quickstart-guide.md#protect-http-applications). Network segmentation between web UI and web services is not covered in this documentation. Please note that the web UI container is listening on the `7000` port. !!! info "Database backend" - If you want another Database backend than MariaDB please refer to the yaml files in the [misc/integrations folder](https://github.com/bunkerity/bunkerweb/tree/vcurrent_bw_version/misc/integrations) of the repository. + If you want another Database backend than MariaDB please refer to the yaml files in the [misc/integrations folder](https://github.com/bunkerity/bunkerweb/tree/v1.5.0-beta/misc/integrations) of the repository. Here is the yaml boilerplate that you can use (don't forget to edit the `changeme` data) : @@ -523,7 +523,7 @@ Because the web UI is a web application, the recommended installation procedure spec: containers: - name: bunkerweb - image: bunkerity/bunkerweb:current_bw_version + image: bunkerity/bunkerweb:1.5.0-beta imagePullPolicy: Always securityContext: runAsUser: 101 @@ -593,7 +593,7 @@ Because the web UI is a web application, the recommended installation procedure serviceAccountName: sa-bunkerweb containers: - name: bunkerweb-controller - image: bunkerity/bunkerweb-autoconf:current_bw_version + image: bunkerity/bunkerweb-autoconf:1.5.0-beta imagePullPolicy: Always env: - name: KUBERNETES_MODE @@ -620,7 +620,7 @@ Because the web UI is a web application, the recommended installation procedure serviceAccountName: sa-bunkerweb containers: - name: bunkerweb-scheduler - image: bunkerity/bunkerweb-scheduler:current_bw_version + image: bunkerity/bunkerweb-scheduler:1.5.0-beta imagePullPolicy: Always env: - name: KUBERNETES_MODE @@ -704,7 +704,7 @@ Because the web UI is a web application, the recommended installation procedure spec: containers: - name: bunkerweb-ui - image: bunkerity/bunkerweb-ui:current_bw_version + image: bunkerity/bunkerweb-ui:1.5.0-beta imagePullPolicy: Always env: - name: ADMIN_USERNAME @@ -805,7 +805,7 @@ Because the web UI is a web application, the recommended installation procedure === "Linux" - The installation of the web UI using the [Linux integration](/current_bw_version/integrations/#linux) is pretty straightforward because it is installed with BunkerWeb. + The installation of the web UI using the [Linux integration](integrations.md#linux) is pretty straightforward because it is installed with BunkerWeb. The web UI comes as systemd service named `bunkerweb-ui` which is not enabled by default. If you want to start the web UI when on startup you can run the following command : @@ -827,7 +827,7 @@ Because the web UI is a web application, the recommended installation procedure systemctl restart bunkerweb-ui ``` - Accessing the web UI through BunkerWeb is a classical [reverse proxy setup](/current_bw_version/quickstart-guide/#protect-http-applications). Please note that the web UI is listening on the `7000` port and only on the loopback interface. + Accessing the web UI through BunkerWeb is a classical [reverse proxy setup](quickstart-guide.md#protect-http-applications). Please note that the web UI is listening on the `7000` port and only on the loopback interface. Here is the `/etc/bunkerweb/variables.env` boilerplate you can use : @@ -853,7 +853,7 @@ Because the web UI is a web application, the recommended installation procedure === "Ansible" - The installation of the web UI using the [Vagrant integration](/current_bw_version/integrations/#linux) is pretty straightforward because it is installed with BunkerWeb. + The installation of the web UI using the [Vagrant integration](integrations.md#linux) is pretty straightforward because it is installed with BunkerWeb. Create a `my_ui.env` filed used to configure the web UI : @@ -908,7 +908,7 @@ Because the web UI is a web application, the recommended installation procedure === "Vagrant" - The installation of the web UI using the [Vagrant integration](/current_bw_version/integrations/#vagrant) is pretty straightforward because it is installed with BunkerWeb. + The installation of the web UI using the [Vagrant integration](integrations.md#vagrant) is pretty straightforward because it is installed with BunkerWeb. First of all, you will need to get a shell on your Vagrant box : @@ -936,7 +936,7 @@ Because the web UI is a web application, the recommended installation procedure systemctl restart bunkerweb-ui ``` - Accessing the web UI through BunkerWeb is a classical [reverse proxy setup](/current_bw_version/quickstart-guide/#protect-http-applications). Please note that the web UI is listening on the `7000` port and only on the loopback interface. + Accessing the web UI through BunkerWeb is a classical [reverse proxy setup](quickstart-guide.md#protect-http-applications). Please note that the web UI is listening on the `7000` port and only on the loopback interface. Here is the `/etc/bunkerweb/variables.env` boilerplate you can use : diff --git a/misc/update-version.sh b/misc/update-version.sh new file mode 100755 index 00000000..8489423a --- /dev/null +++ b/misc/update-version.sh @@ -0,0 +1,22 @@ +#/bin/bash + +if [ $# -ne 1 ] ; then + echo "Missing version argument" + exit 1 +fi + + + +OLD_VERSION="$(cat src/VERSION | tr -d '\n' | sed 's/\./\\./g' | sed 's/\-/\\-/g')" +NEW_VERSION="$(echo -n "$1" | sed 's/\./\\./g' | sed 's/\-/\\-/g')" + +# VERSION +echo -en "$NEW_VERSION" | sed 's/\\//g' > src/VERSION +# integrations +sed -i "s@${OLD_VERSION}@${NEW_VERSION}@g" misc/integrations/*.yml +# examples +for example in examples/* ; do + sed -i "s@${OLD_VERSION}@${NEW_VERSION}@g" ${example}/*.yml +done +# docs +sed -i "s@${OLD_VERSION}@${NEW_VERSION}@g" docs/*.md \ No newline at end of file diff --git a/mkdocs.yml b/mkdocs.yml index f8b85230..53417247 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -36,9 +36,6 @@ theme: extra_css: - assets/extra.css -extra_javascript: - - assets/extra.js - markdown_extensions: - attr_list - md_in_html @@ -67,4 +64,8 @@ extra: - icon: fontawesome/brands/linkedin link: https://www.linkedin.com/company/bunkerity/ - icon: fontawesome/brands/twitter - link: https://twitter.com/bunkerity \ No newline at end of file + link: https://twitter.com/bunkerity + +plugins: + - search + - print-site \ No newline at end of file