docs - concepts
This commit is contained in:
florian
parent
435aae7cf1
commit
0bf2116c44
|
|
@ -2,7 +2,6 @@
|
|||
|
||||
<figure markdown>
|
||||
{ align=center }
|
||||
|
||||
</figure>
|
||||
|
||||
## Integrations
|
||||
|
|
@ -11,18 +10,19 @@ The first concept is the integration of BunkerWeb into the target environment. W
|
|||
|
||||
The following integrations are officially supported :
|
||||
|
||||
- [Docker](/1.4/integrations/#docker)
|
||||
- [Docker autoconf](/1.4/integrations/#docker-autoconf)
|
||||
- [Swarm](/1.4/integrations/#swarm)
|
||||
- [Docker](/1.5.0-beta/integrations/#docker)
|
||||
- [Docker autoconf](/1.5.0-beta/integrations/#docker-autoconf)
|
||||
- [Swarm](/1.5.0-beta/integrations/#swarm)
|
||||
- [Kubernetes](/1.4/integrations/#kubernetes)
|
||||
- [Linux](/1.4/integrations/#linux)
|
||||
- [Ansible](/1.4/integrations/#ansible)
|
||||
- [Linux](/1.5.0-beta/integrations/#linux)
|
||||
- [Ansible](/1.5.0-beta/integrations/#ansible)
|
||||
- [Vagrant](/1.5.0-beta/integrations/#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](/1.4/integrations) of the documentation.
|
||||
The technical details of all BunkerWeb integrations are available in the [integrations section](/1.5.0-beta/integrations) of the documentation.
|
||||
|
||||
## Settings
|
||||
|
||||
|
|
@ -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](/1.4/quickstart-guide) of the documentation and the [examples](https://github.com/bunkerity/bunkerweb/tree/master/examples) directory of the repository.
|
||||
You will find concrete examples of multisite mode in the [quickstart guide](/1.5.0-beta/quickstart-guide) of the documentation and the [examples](https://github.com/bunkerity/bunkerweb/tree/master/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](/1.4/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](/1.5.0-beta/plugins)), 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,4 +91,36 @@ 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](/1.4/quickstart-guide) of the documentation and the [examples](https://github.com/bunkerity/bunkerweb/tree/master/examples) directory of the repository.
|
||||
You will find concrete examples of custom configurations in the [quickstart guide](/1.5.0-beta/quickstart-guide) of the documentation and the [examples](https://github.com/bunkerity/bunkerweb/tree/master/examples) directory of the repository.
|
||||
|
||||
## Database
|
||||
|
||||
State of the current configuration of BunkerWeb is stored in a backend database which contains the following data :
|
||||
|
||||
- Settings defined for all the services
|
||||
- Custom configurations
|
||||
- BunkerWeb instances
|
||||
- Metadata about jobs execution
|
||||
- Cached files
|
||||
|
||||
Under the hood, when you edit a setting or add a new configuration, everything is stored in the database. We actually support SQLite, MariaDB, MySQL and PostgreSQL as backends.
|
||||
|
||||
Database configuration is done by using the `DATABASE_URI` setting which respects the following formats :
|
||||
|
||||
- SQLite : `sqlite:///var/lib/bunkerweb/db.sqlite3`
|
||||
- MariaDB : `mariadb+pymysql://bunkerweb:changeme@bw-db:3306/db`
|
||||
- MySQL : `mysql+pymysql://bunkerweb:changeme@bw-db:3306/db`
|
||||
- PostgreSQL : `postgresql://bunkerweb:changeme@bw-db:5432/db`
|
||||
|
||||
## Scheduler
|
||||
|
||||
To make things automagically work together, a dedicated service called the scheduler is in charge of :
|
||||
|
||||
- Storing the settings and custom configurations inside the database
|
||||
- Executing various tasks (called jobs)
|
||||
- Generating a configuration which is understood by BunkerWeb
|
||||
- Being the intermediary for other services (like web UI or autoconf)
|
||||
|
||||
In other words, the scheduler is the brain of BunkerWeb.
|
||||
|
||||
When using container-based integrations, the scheduler is executed in its own container. Whereas, for linux-based integrations scheduler is self-contained in the `bunkerweb` service.
|
||||
|
|
@ -15,19 +15,22 @@ We provide ready-to-use prebuilt images for x64, x86 armv8 and armv7 architectur
|
|||
docker pull bunkerity/bunkerweb:1.5.0-beta
|
||||
```
|
||||
|
||||
Alternatively, you can build the Docker images directly from the [source](https://github.com/bunkerity/bunkerweb) (and get a coffee ☕ because it may take a long time depending on your hardware) :
|
||||
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) :
|
||||
|
||||
```shell
|
||||
git clone https://github.com/bunkerity/bunkerweb.git && \
|
||||
cd bunkerweb && \
|
||||
docker build -t my-bunkerweb .
|
||||
docker build -t my-bunkerweb -f src/bunkerweb/Dockerfile .
|
||||
```
|
||||
|
||||
BunkerWeb container's usage and configuration are based on :
|
||||
Docker integration key concepts are :
|
||||
|
||||
- **Environment variables** to configure BunkerWeb and meet your use cases
|
||||
- **Volume** to cache important data and mount custom configuration files
|
||||
- **Networks** to expose ports for clients and connect to upstream web services
|
||||
- **Environment variables** to configure BunkerWeb
|
||||
- **Scheduler** container to store configuration and execute jobs
|
||||
- **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 not documented but still possible if you want to.
|
||||
|
||||
### Environment variables
|
||||
|
||||
|
|
@ -56,14 +59,26 @@ services:
|
|||
!!! info "Full list"
|
||||
For the complete list of environment variables, see the [settings section](/1.4/settings) of the documentation.
|
||||
|
||||
### Volume
|
||||
### Scheduler
|
||||
|
||||
A volume is used to share data with BunkerWeb and store persistent data like certificates, cached files, ...
|
||||
|
||||
The easiest way of managing the volume is by using a named one. You will first need to create it :
|
||||
The [scheduler](/1.5.0-beta/concepts/#scheduler) is executed in its own container which is also available on Docker Hub :
|
||||
|
||||
```shell
|
||||
docker volume create bw_data
|
||||
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) :
|
||||
|
||||
```shell
|
||||
git clone https://github.com/bunkerity/bunkerweb.git && \
|
||||
cd bunkerweb && \
|
||||
docker build -t my-scheduler -f src/scheduler/Dockerfile .
|
||||
```
|
||||
|
||||
A volume is needed to store the SQLite database that will be used by the scheduler :
|
||||
|
||||
```shell
|
||||
docker volume create bw-data
|
||||
```
|
||||
|
||||
Once it's created, you will be able to mount it on `/data` when running the container :
|
||||
|
|
@ -71,9 +86,9 @@ Once it's created, you will be able to mount it on `/data` when running the cont
|
|||
```shell
|
||||
docker run \
|
||||
...
|
||||
-v bw_data:/data \
|
||||
-v bw-data:/data \
|
||||
...
|
||||
bunkerity/bunkerweb:1.5.0-beta
|
||||
bunkerity/bunkerweb-scheduler:1.5.0-beta
|
||||
```
|
||||
|
||||
Here is the docker-compose equivalent :
|
||||
|
|
@ -82,17 +97,17 @@ Here is the docker-compose equivalent :
|
|||
...
|
||||
services:
|
||||
mybunker:
|
||||
image: bunkerity/bunkerweb:1.5.0-beta
|
||||
image: bunkerity/bunkerweb-scheduler:1.5.0-beta
|
||||
volumes:
|
||||
- bw_data:/data
|
||||
- bw-data:/data
|
||||
...
|
||||
volumes:
|
||||
bw_data:
|
||||
bw-data:
|
||||
```
|
||||
|
||||
!!! warning "Using local folder for persistent data"
|
||||
|
||||
BunkerWeb runs as an **unprivileged user with UID 101 and GID 101** inside the container. The reason behind this is security : in case a vulnerability is exploited, the attacker won't have full root (UID/GID 0) privileges.
|
||||
The scheduler runs as an **unprivileged user with UID 101 and GID 101** inside the container. The reason behind this is security : in case a vulnerability is exploited, the attacker won't have full root (UID/GID 0) privileges.
|
||||
But there is a downside : if you use a **local folder for the persistent data**, you will need to **set the correct permissions** so the unprivileged user can write data to it. Something like that should do the trick :
|
||||
```shell
|
||||
mkdir bw-data && \
|
||||
|
|
@ -125,6 +140,8 @@ volumes:
|
|||
chmod -R 770 bw-data
|
||||
```
|
||||
|
||||
TODO
|
||||
|
||||
### Networks
|
||||
|
||||
By default, BunkerWeb container is listening (inside the container) on **8080/tcp** for **HTTP** and **8443/tcp** for **HTTPS**.
|
||||
|
|
@ -137,7 +154,7 @@ By default, BunkerWeb container is listening (inside the container) on **8080/tc
|
|||
sudo sysctl net.ipv4.ip_unprivileged_port_start=1
|
||||
```
|
||||
|
||||
The easiest way to connect BunkerWeb to web applications is by using Docker networks.
|
||||
The easiest way to connect BunkerWeb to web applications is by using Docker networks.
|
||||
|
||||
First of all, you will need to create a network :
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue