librewolf
/
bunkerized-nginx
mirror of https://github.com/bunkerity/bunkerized-nginx
4
0
Fork 1
Code Issues Projects Releases Wiki Activity

use proper links in docs, automatic doc push and add pdf to releases

This commit is contained in:
florian 2023-04-29 20:54:56 +02:00
parent 08e1d157d7
commit ad16067420
No known key found for this signature in database
GPG Key ID: 3D80806F12602A7C
27 changed files with 573 additions and 353 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

58
.github/workflows/beta.yml vendored
View File

@ -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

39
.github/workflows/doc-to-pdf.yml vendored Normal file
View File

@ -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

28
.github/workflows/push-doc.yml vendored Normal file
View File

@ -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

57
.github/workflows/push-github.yml vendored Normal file
View File

@ -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

96
.github/workflows/release.yml vendored
View File

@ -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

6
.github/workflows/staging-tests.yml vendored
View File

@ -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

146
.github/workflows/staging.yml vendored
View File

@ -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 }}
# delete-infra-linux:
# if: ${{ always() }}
# needs: [tests-linux]
# uses: ./.github/workflows/staging-delete-infra.yml
# with:
# TYPE: linux
# secrets:
# CICD_SECRETS: ${{ secrets.CICD_SECRETS }}

8
README.md
View File

@ -3,11 +3,11 @@
</p>
<p align="center">
<img src="https://img.shields.io/github/release/bunkerity/bunkerweb.svg" />
<img src="https://img.shields.io/github/v/release/bunkerity/bunkerweb?label=stable" />
<img src="https://img.shields.io/github/v/release/bunkerity/bunkerweb?include_prereleases&label=latest" />
<img src="https://img.shields.io/github/last-commit/bunkerity/bunkerweb" />
<img src="https://img.shields.io/github/actions/workflow/status/bunkerity/bunkerweb/dev.yml?label=CI%2FCD%20dev&branch=dev" />
<img src="https://img.shields.io/github/actions/workflow/status/bunkerity/bunkerweb/staging.yml?label=CI%2FCD%20staging&branch=staging" />
<img src="https://img.shields.io/github/actions/workflow/status/bunkerity/bunkerweb/prod.yml?label=CI%2FCD%20prod" />
<img src="https://img.shields.io/github/actions/workflow/status/bunkerity/bunkerweb/dev.yml?branch=dev&label=CI%2FCD%20dev" />
<img src="https://img.shields.io/github/actions/workflow/status/bunkerity/bunkerweb/staging.yml?branch=staging&label=CI%2FCD%20staging" />
<img src="https://img.shields.io/github/issues/bunkerity/bunkerweb">
<img src="https://img.shields.io/github/issues-pr/bunkerity/bunkerweb">
</p>

2
docs/about.md
View File

@ -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 ?

3
docs/assets/extra.js
View File

@ -1,3 +0,0 @@
window.onload = function set_bw_version() {
document.body.innerHTML = document.body.innerHTML.replaceAll('current_bw_version', '1.5.0-beta');
}

24
docs/concepts.md
View File

@ -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

6
docs/index.md
View File

@ -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

77
docs/integrations.md
View File

@ -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
<!-- TODO
<figure markdown>
![Overview](assets/img/integration-vagrant.svg){ align=center }
<figcaption>BunkerWeb integration with Vagrant</figcaption>
</figure>
-->
List of supported providers :
- vmware_desktop

2
docs/json2md.py
View File

@ -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(

10
docs/migrating.md
View File

@ -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.
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.

13
docs/mike.sh
View File

@ -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

49
docs/misc/pdf.js Normal file
View File

@ -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 = `
<div style="font-size: 10px; text-align: center; width: 100%;">
<span>${title}</span>
</div>`;
footerHtml = `<div style="font-size: 10px; text-align: center; width: 100%;"><span class="pageNumber"></span> / <span class="totalPages"></span></div>`;
(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();
})();

28
docs/overrides/main.html
View File

@ -1,18 +1,22 @@
{% extends "base.html" %} {% block outdated %} You're not viewing the
documentation for the current version.
<a href="{{ '../' ~ base_url }}"><strong>Click here to change.</strong></a> {%
endblock %} {% block announce %} 📢 Looking for tailored support, consulting or
development for BunkerWeb ? Contact us at
<a
href="mailto:contact@bunkerity.com"
style="color: #3f6ec6; text-decoration: underline"
>contact@bunkerity.com</a
>
for enterprise offers ! {% endblock %} {% block libs %}
{% extends "base.html" %}
{% block outdated %}
You're not viewing the documentation of the latest version.
<a href="{{ '../' ~ base_url }}">
<strong>Click here to view latest.</strong>
</a>
{% endblock %}
{% block announce %}
📢 Looking for tailored support, consulting or development for BunkerWeb ?
Contact us at <a href="mailto:contact@bunkerity.com" style="color: #3f6ec6; text-decoration: underline">contact@bunkerity.com</a> for enterprise offers !
{% endblock %}
{% block libs %}
<script
async
defer
data-domain="docs.bunkerweb.io"
src="https://data.bunkerity.com/js/script.js"
></script>
{% endblock %}
{% endblock %}

34
docs/plugins.md
View File

@ -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.

128
docs/quickstart-guide.md
View File

@ -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 :

1
docs/requirements.txt
View File

@ -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

10
docs/security-tuning.md
View File

@ -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.
<figure markdown>
![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.**

2
docs/settings.md
View File

@ -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.

8
docs/troubleshooting.md
View File

@ -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

60
docs/web-ui.md
View File

@ -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 :

22
misc/update-version.sh Executable file
View File

@ -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

9
mkdocs.yml
View File

@ -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
link: https://twitter.com/bunkerity
plugins:
- search
- print-site