Elgato_dark/bunkerweb
1
0
Fork 0
mirror of https://github.com/bunkerity/bunkerweb synced 2026-05-24 09:28:37 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

Fully adding vagrant in the doc

Browse source
This commit is contained in:
AxyFr 2023-04-13 16:06:27 +02:00
parent 3a03f07f19
commit 5dd52186ba
5 changed files with 380 additions and 1 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

32
docs/integrations.md
View file

@ -802,6 +802,38 @@ Repositories of Linux packages for BunkerWeb are available on [PackageCloud](htt
sudo dnf versionlock add bunkerweb
```
=== "Redhat"
The first step is to add NGINX official repository. Create the following file at `/etc/yum.repos.d/nginx.repo` :
```conf
[nginx-stable]
name=nginx stable repo
baseurl=http://nginx.org/packages/centos/$releasever/$basearch/
gpgcheck=1
enabled=1
gpgkey=https://nginx.org/keys/nginx_signing.key
module_hotfixes=true
```
You should now be able to install NGINX 1.20.2 :
```shell
sudo dnf install nginx-1.20.2
```
And finally install BunkerWeb 1.4.6 :
```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-1.4.6
```
To prevent upgrading NGINX and/or BunkerWeb packages when executing `dnf upgrade`, you can use the following command :
```shell
sudo dnf versionlock add nginx && \
sudo dnf versionlock add bunkerweb
```
=== "From source"
The first step is to install NGINX 1.20.2 using the repository of your choice or by [compiling it from source](https://docs.nginx.com/nginx/admin-guide/installing-nginx/installing-nginx-open-source/#compiling-and-installing-from-source).

8
docs/plugins.md
View file

@ -148,6 +148,14 @@ The first step is to install the plugin by putting the plugin files inside the c
ansible-playbook -i inventory.yml playbook.yml
```
=== "Vagrant"
When using the [Vagrant integration](/1.4/integrations/#vagrant), plugins must be written to the `/etc/bunkerweb/plugins` folder :
```shell
git clone https://github.com/bunkerity/bunkerweb-plugins && \
cp -rp ./bunkerweb-plugins/* /data/plugins
```
## Writing a plugin
!!! tip "Existing plugins"

271
docs/quickstart-guide.md
View file

@ -314,6 +314,49 @@ You will find more settings about reverse proxy in the [settings section](/1.4/s
ansible-playbook -i inventory.yml playbook.yml
```
=== "Vagrant"
We will assume that you already have the [Vagrant integration](/1.4/integrations/#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 :
```shell
python3 -m http.server -b 127.0.0.1
```
Configuration of BunkerWeb is done by editing the `/etc/bunkerweb/variables.env` file.
Connect to your vagrant machine :
```shell
vagrant ssh
```
And then you can edit the `variables.env` file in your host machine like this :
```conf
SERVER_NAME=www.example.com
HTTP_PORT=80
HTTPS_PORT=443
DNS_RESOLVERS=8.8.8.8 8.8.4.4
USE_REVERSE_PROXY=yes
REVERSE_PROXY_URL=/
REVERSE_PROXY_HOST=http://127.0.0.1:8000
```
If it's already running we can restart it :
```shell
systemctl restart bunkerweb
```
Otherwise, we will need to start it :
```shell
systemctl start bunkerweb
```
Let's check the status of BunkerWeb :
```shell
systemctl status bunkerweb
```
### Multiple applications
!!! tip "Testing"
@ -881,6 +924,64 @@ You will find more settings about reverse proxy in the [settings section](/1.4/s
systemctl start bunkerweb
```
=== "Vagrant"
We will assume that you already have the [Vagrant integration](/1.4/integrations/#Vagrant) stack running on your machine with some web applications running on the same machine as BunkerWeb.
Let's assume that you have some web applications running on the same machine as BunkerWeb :
=== "App #1"
The following command will run a basic HTTP server on the port 8001 and deliver the files in the current directory :
```shell
python3 -m http.server -b 127.0.0.1 8001
```
=== "App #2"
The following command will run a basic HTTP server on the port 8002 and deliver the files in the current directory :
```shell
python3 -m http.server -b 127.0.0.1 8002
```
=== "App #3"
The following command will run a basic HTTP server on the port 8003 and deliver the files in the current directory :
```shell
python3 -m http.server -b 127.0.0.1 8003
```
Connect to your vagrant machine :
```shell
vagrant ssh
```
Configuration of BunkerWeb is done by editing the /etc/bunkerweb/variables.env file :
```conf
SERVER_NAME=app1.example.com app2.example.com app3.example.com
HTTP_PORT=80
HTTPS_PORT=443
MULTISITE=yes
DNS_RESOLVERS=8.8.8.8 8.8.4.4
USE_REVERSE_PROXY=yes
REVERSE_PROXY_URL=/
app1.example.com_REVERSE_PROXY_HOST=http://127.0.0.1:8001
app2.example.com_REVERSE_PROXY_HOST=http://127.0.0.1:8002
app3.example.com_REVERSE_PROXY_HOST=http://127.0.0.1:8003
```
If it's already running we can restart it :
```shell
systemctl restart bunkerweb
```
Otherwise, we will need to start it :
```shell
systemctl start bunkerweb
```
Let's check the status of BunkerWeb :
```shell
systemctl status bunkerweb
```
=== "Ansible"
Let's assume that you have some web applications running on the same machine as BunkerWeb :
@ -1119,6 +1220,20 @@ REAL_IP_HEADER=X-Forwarded-For
ansible-playbook -i inventory.yml playbook.yml
```
=== "Vagrant"
You will need to add the settings to the `/etc/bunkerweb/variables.env` file :
```conf
...
USE_REAL_IP=yes
REAL_IP_FROM=1.2.3.0/24 100.64.0.0/16
REAL_IP_HEADER=X-Forwarded-For
...
```
Don't forget to restart the BunkerWeb service once it's done.
### Proxy protocol
We will assume the following regarding the load balancers or reverse proxies (you will need to update the settings depending on your configuration) :
@ -1293,6 +1408,21 @@ REAL_IP_HEADER=proxy_protocol
ansible-playbook -i inventory.yml playbook.yml
```
=== "Vagrant"
You will need to add the settings to the `/etc/bunkerweb/variables.env` file :
```conf
...
USE_REAL_IP=yes
USE_PROXY_PROTOCOL=yes
REAL_IP_FROM=1.2.3.0/24 100.64.0.0/16
REAL_IP_HEADER=proxy_protocol
...
```
Don't forget to restart the BunkerWeb service once it's done.
## 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](/1.4/security-tuning/#modsecurity)). Here is the list of custom configurations types :
@ -1559,6 +1689,28 @@ Some integrations offer a more convenient way of applying configurations such as
ansible-playbook -i inventory.yml playbook.yml
```
=== "Vagrant"
When using the [Vagrant integration](/1.4/integrations/#vagrant), custom configurations must be written to the `/etc/bunkerweb/configs` folder.
Here is an example for server-http/hello-world.conf :
```conf
location /hello {
default_type 'text/plain';
content_by_lua_block {
ngx.say('world')
}
}
```
Because BunkerWeb runs as an unprivileged user (nginx:nginx), you will need to edit the permissions :
```shell
chown -R root:nginx /etc/bunkerweb/configs && \
chmod -R 770 /etc/bunkerweb/configs
```
Don't forget to restart the BunkerWeb service once it's done.
## PHP
!!! warning "Support is in beta"
@ -1899,6 +2051,62 @@ BunkerWeb supports PHP using external or remote [PHP-FPM](https://www.php.net/ma
ansible-playbook -i inventory.yml playbook.yml
```
=== "Vagrant"
We will assume that you already have the [Vagrant integration](/1.4/integrations/#vagrant) 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 application. 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.
First of all, you will need to make sure that your PHP-FPM instance can access the files inside the `/var/www/html` folder and also that BunkerWeb can access the UNIX socket file in order to communicate with PHP-FPM. We recommend to set a different user like `www-data` for the PHP-FPM service and to give the nginx group access to the UNIX socket file. Here is corresponding PHP-FPM configuration :
```ini
...
[www]
user = www-data
group = www-data
listen = /run/php/php-fpm.sock
listen.owner = www-data
listen.group = nginx
listen.mode = 0660
...
```
Don't forget to restart your PHP-FPM service :
```shell
systemctl restart php8.1-fpm
```
Once your application is copied to the `/var/www/html` folder, you will need to fix the permissions so BunkerWeb (user/group nginx) can at least read files and list folders and PHP-FPM (user/group www-data) is the owner of the files and folders :
```shell
chown -R www-data:nginx /var/www/html && \
find /var/www/html -type f -exec chmod 0640 {} \; && \
find /var/www/html -type d -exec chmod 0750 {} \;
```
You can now edit the `/etc/bunkerweb/variable.env` file :
```env
HTTP_PORT=80
HTTPS_PORT=443
DNS_RESOLVERS=8.8.8.8 8.8.4.4
SERVER_NAME=www.example.com
AUTO_LETS_ENCRYPT=yes
LOCAL_PHP=/run/php/php-fpm.sock
LOCAL_PHP_PATH=/var/www/html/
```
Let's check the status of BunkerWeb :
```shell
systemctl status bunkerweb
```
If it's already running we can restart it :
```shell
systemctl restart bunkerweb
```
Otherwise, we will need to start it :
```shell
systemctl start bunkerweb
```
### Multiple applications
!!! tip "Testing"
@ -2412,4 +2620,65 @@ BunkerWeb supports PHP using external or remote [PHP-FPM](https://www.php.net/ma
You can now run the playbook :
```shell
ansible-playbook -i inventory.yml playbook.yml
```
```
=== "Vagrant"
We will assume that you already have the [Vagrant integration](/1.4/integrations/#vagrant) 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 : each application will be in its own subfolder named the same as the primary server name. 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.
First of all, you will need to make sure that your PHP-FPM instance can access the files inside the `/var/www/html` folder and also that BunkerWeb can access the UNIX socket file in order to communicate with PHP-FPM. We recommend to set a different user like `www-data` for the PHP-FPM service and to give the nginx group access to the UNIX socket file. Here is corresponding PHP-FPM configuration :
```ini
...
[www]
user = www-data
group = www-data
listen = /run/php/php-fpm.sock
listen.owner = www-data
listen.group = nginx
listen.mode = 0660
...
```
Don't forget to restart your PHP-FPM service :
```shell
systemctl restart php8.1-fpm
```
Once your application is copied to the `/var/www/html` folder, you will need to fix the permissions so BunkerWeb (user/group nginx) can at least read files and list folders and PHP-FPM (user/group www-data) is the owner of the files and folders :
```shell
chown -R www-data:nginx /var/www/html && \
find /var/www/html -type f -exec chmod 0640 {} \; && \
find /var/www/html -type d -exec chmod 0750 {} \;
```
You can now edit the `/etc/bunkerweb/variable.env` file :
```env
HTTP_PORT=80
HTTPS_PORT=443
DNS_RESOLVERS=8.8.8.8 8.8.4.4
SERVER_NAME=app1.example.com app2.example.com app3.example.com
MULTISITE=yes
AUTO_LETS_ENCRYPT=yes
app1.example.com_LOCAL_PHP=/run/php/php-fpm.sock
app1.example.com_LOCAL_PHP_PATH=/var/www/html/app1.example.com
app2.example.com_LOCAL_PHP=/run/php/php-fpm.sock
app2.example.com_LOCAL_PHP_PATH=/var/www/html/app2.example.com
app3.example.com_LOCAL_PHP=/run/php/php-fpm.sock
app3.example.com_LOCAL_PHP_PATH=/var/www/html/app3.example.com
```
Let's check the status of BunkerWeb :
```shell
systemctl status bunkerweb
```
If it's already running we can restart it :
```shell
systemctl restart bunkerweb
```
Otherwise, we will need to start it :
```shell
systemctl start bunkerweb
```

20
docs/troubleshooting.md
View file

@ -99,6 +99,19 @@ Here is how you can access the logs, depending on your integration :
ansible -i inventory.yml all -a "cat /var/log/nginx/access.log" --become
```
=== "Vagrant"
For errors related to BunkerWeb services (e.g. not starting), you can use `journalctl` :
```shell
journalctl -u bunkerweb --no-pager
```
Common logs are located inside the `/var/log/nginx` directory :
```shell
cat /var/log/nginx/error.log
cat /var/log/nginx/access.log
```
## 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](/1.4/quickstart-guide/#custom-configurations)). You will need to set at least **RW** rights on files and **_RWX_** on folders.
@ -254,6 +267,13 @@ You can manually unban an IP which can be useful when doing some tests but it ne
ansible -i inventory.yml all -a "bwcli unban 1.2.3.4" --become
```
=== "Vagrant"
You can use the `bwcli` command (as root) :
```shell
sudo bwcli unban 1.2.3.4
```
## 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](/1.4/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 :

50
docs/web-ui.md
View file

@ -304,3 +304,53 @@ Because the web UI is a web application, the recommended installation procedure
```shell
ansible-playbook -i inventory.yml playbook.yml
```
=== "Vagrant"
The installation of the web UI using the [Vagrant integration](/1.4/integrations/#vagrant) is pretty straightforward because it is installed with BunkerWeb.
The first thing to do is to edit the BunkerWeb configuration located at **/etc/bunkerweb/variables.env** to add settings related to the web UI :
```conf
HTTP_PORT=80
HTTPS_PORT=443
DNS_RESOLVERS=8.8.8.8 8.8.4.4
...
SERVER_NAME=bwadm.example.com
MULTISITE=yes
USE_API=yes
API_WHITELIST_IP=127.0.0.0/8
bwadm.example.com_USE_UI=yes
bwadm.example.com_USE_REVERSE_PROXY=yes
bwadm.example.com_REVERSE_PROXY_URL=/changeme/
bwadm.example.com_REVERSE_PROXY_HOST=http://127.0.0.1:7000
bwadm.example.com_REVERSE_PROXY_HEADERS=X-Script-Name /changeme
bwadm.example.com_REVERSE_PROXY_INTERCEPT_ERRORS=no
...
```
Important things to note :
* `bwadm.example.com` is the dedicated (sub)domain for accessing the web UI
* replace the `/changeme` URLs with a custom one of your choice
Once the configuration file is edited, you will need to restart BunkerWeb :
```shell
systemctl restart bunkerweb
```
You can edit the **/etc/bunkerweb/ui.env** file containing the settings of the web UI :
```conf
ADMIN_USERNAME=admin
ADMIN_PASSWORD=changeme
ABSOLUTE_URI=http(s)://bwadm.example.com/changeme/
```
Important things to note :
* `http(s)://bwadmin.example.com/changeme/` is the full base URL of the web UI (must match the sub(domain) and /changeme URL used in **/etc/bunkerweb/variables.env**)
* replace the username `admin` and password `changeme` with strong ones
Restart the BunkerWeb UI service and you are now ready to access it :
```shell
systemctl restart bunkerweb-ui
```