Because the web UI is a web application, the recommended installation procedure is to use BunkerWeb in front of it as a reverse proxy.
!!! warning "Security considerations"
The security of the web UI is really important. If someone manages to gain access to the application, not only he will be able to edit your configurations but he could execute some code in the context of BunkerWeb (with a custom configuration containing LUA code for example). We highly recommend you to follow minimal security best practices like :
The web UI uses the following environment variables :
-`OVERRIDE_ADMIN_CREDS` : set it to `yes` to enable the override even if the admin credentials are already set (default is `no`).
-`ADMIN_USERNAME` : username to access the web UI.
-`ADMIN_PASSWORD` : password to access the web UI.
-`FLASK_SECRET` : a secret key used to encrypt the session cookie (if not set, a random key will be generated).
-`TOTP_SECRETS` : a list of TOTP secrets separated by spaces or a dictionary (e.g. : `{"1": "mysecretkey"}` or `mysecretkey` or `mysecretkey mysecretkey1`). **We strongly recommend you to set this variable if you want to use 2FA, as it will be used to encrypt the TOTP secret keys** (if not set, a random number of secret keys will be generated). Check out the [passlib documentation](https://passlib.readthedocs.io/en/stable/narr/totp-tutorial.html#application-secrets) for more information.
The web UI will use these variables to authenticate you and handle the 2FA feature.
The setup wizard is a feature that helps you to **configure** and **install the web UI** using a **user-friendly interface**. You will need to set the `UI_HOST` setting (`http://hostname-of-web-ui:7000`) and browse the `/setup` URI of your server to access the setup wizard.
Choose your administrator username and password. Please note that password must have at least 8 chars with 1 lower case letter, 1 upper case letter, 1 digit and 1 special char.
<figcaption>Settings section of the setup wizard</figcaption>
</figure>
Configure the following settings :
-`UI Host` : internal http endpoint of your web UI
-`UI URL` : the public path where your web UI will be accessible
-`Server name` : the public server name where your web UI will be accessible
-`Auto let's encrypt` : enable/disable HTTPS using automated let's encrypt
Please note that your server name must have a valid DNS entry pointing to your BunkerWeb instance (or load balancer if you use Swarm/Kubernetes). You can check the DNS validity by clicking the `Check` button.
Review your final BunkerWeb UI URL and then click on the `Setup` button. Once the setup is finished, you will be redirected to your web UI login page.
=== "Docker"
If you want to use the setup wizard, you will need to set the `UI_HOST` setting to the HTTP endpoint of your web UI container. For example, if your web UI container is named `bw-ui` and is listening on the `7000` port, you will need to set the `UI_HOST` setting to `http://bw-ui:7000`.
If you want to use the setup wizard, you will need to set the `UI_HOST` setting to the HTTP endpoint of your web UI container. For example, if your web UI container is named `bw-ui` and is listening on the `7000` port, you will need to set the `UI_HOST` setting to `http://bw-ui:7000`.
If you want to use the setup wizard, you will need to set the `UI_HOST` setting to the HTTP endpoint of your web UI container. For example, if your web UI container is named `bw-ui` and is listening on the `7000` port, you will need to set the `UI_HOST` setting to `http://bw-ui:7000`.
If you want to use the setup wizard, you will need to set the `UI_HOST` setting to the HTTP endpoint of your web UI SERVICE. For example, if your web UI service is named `svc-bunkerweb-ui` and is listening on the `7000` port, you will need to set the `UI_HOST` setting to `http://svc-bunkerweb-ui.default.svc.cluster.local:7000` (don't forget to replace the namespace and the service name accordingly).
If you don't want to use the setup wizard, you will need to run the following command `export UI_WIZARD=no` before installing BunkerWeb as described in [integrations section](integrations.md#linux) of the documentation (this is an optional step).
Beginning with version `1.6.0-beta`, the method of accessing logs has changed. This update specifically impacts **Docker, Autoconf, and Swarm** Integrations. Logs are now exclusively accessed from the `/var/log/bunkerweb` directory.
To keep the logs accessible from the web UI, you will need to use `syslog-ng` to forward the logs to a file in the `/var/log/bunkerweb` directory.
=== "Docker"
To forward the logs correctly to the `/var/log/bunkerweb` directory on the Docker integration, you will need to stream the logs to a file using `syslog-ng`. Here is an example of how to do this :
```yaml
x-bw-env: &bw-env
# We anchor the environment variables to avoid duplication
API_WHITELIST_IP: "127.0.0.0/24 10.20.30.0/24"
services:
bunkerweb:
image: bunkerity/bunkerweb:1.6.0-beta
ports:
- "80:8080/tcp"
- "443:8443/tcp"
- "443:8443/udp" # QUIC
environment:
<<:*bw-env
restart: "unless-stopped"
networks:
- bw-universe
- bw-services
logging:
driver: syslog
options:
tag: "bunkerweb" # This will be the tag used by syslog-ng to create the log file
syslog-address: "udp://10.20.30.254:514" # This is the syslog-ng container address
bw-scheduler:
image: bunkerity/bunkerweb-scheduler:1.6.0-beta
environment:
<<:*bw-env
BUNKERWEB_INSTANCES: "bunkerweb" # Make sure to set the correct instance name
SERVER_NAME: "www.example.com"
MULTISITE: "yes"
DATABASE_URI: "mariadb+pymysql://bunkerweb:changeme@bw-db:3306/db" # Remember to set a stronger password for the database
SERVE_FILES: "no"
DISABLE_DEFAULT_SERVER: "yes"
USE_CLIENT_CACHE: "yes"
USE_GZIP: "yes"
www.example.com_USE_UI: "yes"
www.example.com_USE_REVERSE_PROXY: "yes"
www.example.com_REVERSE_PROXY_URL: "/changeme" # Change it to a hard to guess URI
- bw-data:/data # This is used to persist the cache and other data like the backups
restart: "unless-stopped"
networks:
- bw-universe
- bw-db
logging:
driver: syslog
options:
tag: "bw-scheduler" # This will be the tag used by syslog-ng to create the log file
syslog-address: "udp://10.20.30.254:514" # This is the syslog-ng container address
bw-ui:
image: bunkerity/bunkerweb-ui:1.6.0-beta
environment:
DATABASE_URI: "mariadb+pymysql://bunkerweb:changeme@bw-db:3306/db" # Remember to set a stronger password for the database
ADMIN_USERNAME: "changeme"
ADMIN_PASSWORD: "changeme" # Remember to set a stronger password for the admin user
TOPT_SECRETS: "mysecret" # Remember to set a stronger secret key (see the Prerequisites section)
volumes:
- bw-logs:/var/log/bunkerweb # This is the volume used to store the logs
restart: "unless-stopped"
networks:
- bw-universe
- bw-db
logging:
driver: syslog
options:
tag: "bw-ui" # This will be the tag used by syslog-ng to create the log file
syslog-address: "udp://10.20.30.254:514" # This is the syslog-ng container address
bw-db:
image: mariadb:11
environment:
MYSQL_RANDOM_ROOT_PASSWORD: "yes"
MYSQL_DATABASE: "db"
MYSQL_USER: "bunkerweb"
MYSQL_PASSWORD: "changeme" # Remember to set a stronger password for the database
volumes:
- bw-db:/var/lib/mysql
restart: "unless-stopped"
networks:
- bw-db
bw-syslog:
image: balabit/syslog-ng:4.7.1
# image: lscr.io/linuxserver/syslog-ng:4.7.1-r1-ls116 # For aarch64 architecture
volumes:
- bw-logs:/var/log/bunkerweb # This is the volume used to store the logs
- ./syslog-ng.conf:/etc/syslog-ng/syslog-ng.conf # This is the syslog-ng configuration file
networks:
bw-universe:
ipv4_address: 10.20.30.254 # Make sure to set the correct IP address
volumes:
bw-data:
bw-db:
bw-logs:
networks:
bw-universe:
name: bw-universe
ipam:
driver: default
config:
- subnet: 10.20.30.0/24
bw-services:
name: bw-services
bw-db:
name: bw-db
```
=== "Docker Autoconf"
To forward the logs correctly to the `/var/log/bunkerweb` directory on the Autoconf integration, you will need to stream the logs to a file using `syslog-ng`. Here is an example of how to do this :
```yaml
x-ui-env: &bw-ui-env
# We anchor the environment variables to avoid duplication
AUTOCONF_MODE: "yes"
DATABASE_URI: "mariadb+pymysql://bunkerweb:changeme@bw-db:3306/db" # Remember to set a stronger password for the database
services:
bunkerweb:
image: bunkerity/bunkerweb:1.6.0-beta
ports:
- "80:8080/tcp"
- "443:8443/tcp"
- "443:8443/udp" # QUIC
environment:
AUTOCONF_MODE: "yes"
API_WHITELIST_IP: "127.0.0.0/24 10.20.30.0/24"
restart: "unless-stopped"
networks:
- bw-universe
- bw-services
logging:
driver: syslog
options:
tag: "bunkerweb" # This will be the tag used by syslog-ng to create the log file
syslog-address: "udp://10.20.30.254:514" # This is the syslog-ng container address
bw-scheduler:
image: bunkerity/bunkerweb-scheduler:1.6.0-beta
environment:
<<:*bw-ui-env
BUNKERWEB_INSTANCES: "" # We don't need to specify the BunkerWeb instance here as they are automatically detected by the autoconf service
SERVER_NAME: "" # The server name will be filled with services labels
MULTISITE: "yes" # Mandatory setting for autoconf / ui
API_WHITELIST_IP: "127.0.0.0/24 10.20.30.0/24"
volumes:
- bw-data:/data # This is used to persist the cache and other data like the backups
restart: "unless-stopped"
networks:
- bw-universe
- bw-db
logging:
driver: syslog
options:
tag: "bw-scheduler" # This will be the tag used by syslog-ng to create the log file
syslog-address: "udp://10.20.30.254:514" # This is the syslog-ng container address
bw-autoconf:
image: bunkerity/bunkerweb-autoconf:1.6.0-beta
depends_on:
- bunkerweb
- bw-docker
environment:
<<:*bw-ui-env
DOCKER_HOST: "tcp://bw-docker:2375" # This is the Docker socket address
restart: "unless-stopped"
networks:
- bw-universe
- bw-docker
- bw-db
logging:
driver: syslog
options:
tag: "bw-autoconf" # This will be the tag used by syslog-ng to create the log file
syslog-address: "udp://10.20.30.254:514" # This is the syslog-ng container address
bw-ui:
image: bunkerity/bunkerweb-ui:1.6.0-beta
environment:
<<:*bw-ui-env
ADMIN_USERNAME: "changeme"
ADMIN_PASSWORD: "changeme" # Remember to set a stronger password for the admin user
TOPT_SECRETS: "mysecret" # Remember to set a stronger secret key (see the Prerequisites section)
volumes:
- bw-logs:/var/log/bunkerweb
restart: "unless-stopped"
networks:
- bw-universe
- bw-db
labels:
- "bunkerweb.SERVER_NAME=www.example.com"
- "bunkerweb.USE_UI=yes"
- "bunkerweb.USE_REVERSE_PROXY=yes"
- "bunkerweb.REVERSE_PROXY_URL=/changeme" # Change it to a hard to guess URI
tag: "bw-ui" # This will be the tag used by syslog-ng to create the log file
syslog-address: "udp://10.20.30.254:514" # This is the syslog-ng container address
bw-db:
image: mariadb:11
environment:
MYSQL_RANDOM_ROOT_PASSWORD: "yes"
MYSQL_DATABASE: "db"
MYSQL_USER: "bunkerweb"
MYSQL_PASSWORD: "changeme" # Remember to set a stronger password for the database
volumes:
- bw-db:/var/lib/mysql
restart: "unless-stopped"
networks:
- bw-db
bw-docker:
image: tecnativa/docker-socket-proxy:nightly
environment:
CONTAINERS: "1"
LOG_LEVEL: "warning"
volumes:
- /var/run/docker.sock:/var/run/docker.sock:ro
restart: "unless-stopped"
networks:
- bw-docker
bw-syslog:
image: balabit/syslog-ng:4.7.1
# image: lscr.io/linuxserver/syslog-ng:4.7.1-r1-ls116 # For aarch64 architecture
volumes:
- bw-logs:/var/log/bunkerweb # This is the volume used to store the logs
- ./syslog-ng.conf:/etc/syslog-ng/syslog-ng.conf # This is the syslog-ng configuration file
networks:
bw-universe:
ipv4_address: 10.20.30.254 # Make sure to set the correct IP address
volumes:
bw-data:
bw-db:
bw-logs:
networks:
bw-universe:
name: bw-universe
ipam:
driver: default
config:
- subnet: 10.20.30.0/24
bw-services:
name: bw-services
bw-db:
name: bw-db
bw-docker:
name: bw-docker
```
=== "Swarm"
To forward the logs correctly to the `/var/log/bunkerweb` directory on the Swarm integration, you will need to stream the logs to a file using `syslog-ng`. Here is an example of how to do this :
```yaml
x-ui-env: &ui-env
# We anchor the environment variables to avoid duplication
SWARM_MODE: "yes"
DATABASE_URI: "mariadb+pymysql://bunkerweb:changeme@bw-db:3306/db" # Remember to set a stronger password for the database
services:
bunkerweb:
image: bunkerity/bunkerweb:1.6.0-beta
ports:
- published: 80
target: 8080
mode: host
protocol: tcp
- published: 443
target: 8443
mode: host
protocol: tcp
- published: 443
target: 8443
mode: host
protocol: udp # For QUIC / HTTP3 support
environment:
SWARM_MODE: "yes"
API_WHITELIST_IP: "127.0.0.0/8 10.20.30.0/24"
restart: "unless-stopped"
networks:
- bw-universe
- bw-services
deploy:
mode: global
placement:
constraints:
- "node.role == worker"
labels:
- "bunkerweb.INSTANCE=yes"
logging:
driver: syslog
options:
tag: "bunkerweb" # This will be the tag used by syslog-ng to create the log file
syslog-address: "udp://10.20.30.254:514" # This is the syslog-ng container address
bw-scheduler:
image: bunkerity/bunkerweb-scheduler:1.6.0-beta
environment:
<<:*ui-env
BUNKERWEB_INSTANCES: ""
SERVER_NAME: ""
API_WHITELIST_IP: "127.0.0.0/8 10.20.30.0/24"
MULTISITE: "yes"
USE_REDIS: "yes"
REDIS_HOST: "bw-redis"
volumes:
- bw-data:/data # This is used to persist the cache and other data like the backups
restart: "unless-stopped"
networks:
- bw-universe
- bw-db
logging:
driver: syslog
options:
tag: "bw-scheduler" # This will be the tag used by syslog-ng to create the log file
syslog-address: "udp://10.20.30.254:514" # This is the syslog-ng container address
bw-autoconf:
image: bunkerity/bunkerweb-autoconf:1.6.0-beta
environment:
<<:*ui-env
DOCKER_HOST: "tcp://bw-docker:2375"
restart: "unless-stopped"
networks:
- bw-universe
- bw-docker
- bw-db
logging:
driver: syslog
options:
tag: "bw-autoconf" # This will be the tag used by syslog-ng to create the log file
syslog-address: "udp://10.20.30.254:514" # This is the syslog-ng container address
bw-docker:
image: tecnativa/docker-socket-proxy:nightly
volumes:
- /var/run/docker.sock:/var/run/docker.sock:ro
environment:
CONFIGS: "1"
CONTAINERS: "1"
SERVICES: "1"
SWARM: "1"
TASKS: "1"
LOG_LEVEL: "warning"
restart: "unless-stopped"
networks:
- bw-docker
deploy:
placement:
constraints:
- "node.role == manager"
bw-ui:
image: bunkerity/bunkerweb-ui:1.6.0-beta
environment:
<<:*ui-env
ADMIN_USERNAME: "changeme"
ADMIN_PASSWORD: "changeme" # Remember to set a stronger password for the changeme user
TOTP_SECRETS: "mysecret" # Remember to set a stronger secret key (see the Prerequisites section)
volumes:
- bw-logs:/var/log/bunkerweb # This is the volume used to store the logs
tag: "bw-ui" # This will be the tag used by syslog-ng to create the log file
syslog-address: "udp://10.20.30.254:514" # This is the syslog-ng container address
bw-db:
image: mariadb:11
environment:
MYSQL_RANDOM_ROOT_PASSWORD: "yes"
MYSQL_DATABASE: "db"
MYSQL_USER: "bunkerweb"
MYSQL_PASSWORD: "changeme" # Remember to set a stronger password for the database
volumes:
- bw-db:/var/lib/mysql
networks:
- bw-db
bw-redis:
image: redis:7-alpine
networks:
- bw-universe
bw-syslog:
image: balabit/syslog-ng:4.7.1
# image: lscr.io/linuxserver/syslog-ng:4.7.1-r1-ls116 # For aarch64 architecture
volumes:
- bw-logs:/var/log/bunkerweb # This is the volume used to store the logs
- ./syslog-ng.conf:/etc/syslog-ng/syslog-ng.conf # This is the syslog-ng configuration file
networks:
bw-universe:
ipv4_address: 10.20.30.254 # Make sure to set the correct IP address
volumes:
bw-db:
bw-data:
networks:
bw-universe:
name: bw-universe
driver: overlay
attachable: true
ipam:
config:
- subnet: 10.20.30.0/24
bw-services:
name: bw-services
driver: overlay
attachable: true
bw-docker:
name: bw-docker
driver: overlay
attachable: true
bw-db:
name: bw-db
driver: overlay
attachable: true
```
=== "Kubernetes"
Kubernetes does not support the `syslog` logging driver. If you want to access the logs you will have to use some other way like Loki, Fluentd, or any other log management system.
=== "Linux"
For Linux this is the simplest way as the logs files are directly accessible from the filesystem.
### Syslog-ng configuration
Here is an example of a `syslog-ng.conf` file that you can use to forward the logs to a file :
```conf
@version: 4.7
# Source configuration to receive logs from Docker containers
source s_net {
udp(
ip("0.0.0.0")
);
};
# Template to format log messages
template t_imp {
template("$MSG\n");
template_escape(no);
};
# Destination configuration to write logs to dynamically named files
destination d_dyna_file {
file(
"/var/log/bunkerweb/${PROGRAM}.log"
template(t_imp)
owner("101")
group("101")
dir_owner("root")
dir_group("101")
perm(0440)
dir_perm(0770)
create_dirs(yes)
);
};
# Log path to direct logs to dynamically named files
BunkerWeb PRO is an enhanced version of BunkerWeb open-source. Whether it's enhanced security, an enriched user experience, or technical monitoring, the BunkerWeb PRO version will allow you to fully benefit from BunkerWeb and respond to your professional needs. Do not hesitate to visit the [BunkerWeb panel](https://panel.bunkerweb.io/knowledgebase?utm_campaign=self&utm_source=doc) or [contact us](https://panel.bunkerweb.io/contact.php?utm_campaign=self&utm_source=doc) if you have any question regarding the PRO version.
Once you have your PRO license key from the [BunkerWeb panel](https://panel.bunkerweb.io/?utm_campaign=self&utm_source=doc), you can paste it into the PRO section of the account management page.
<figcaption>Upgrade to PRO from the web UI</figcaption>
</figure>
!!! warning "Upgrade time"
The PRO version is downloaded in the background by the scheduler, it may take some time to upgrade.
When your BunkerWeb instance has upgraded to the PRO version, you will see your license expiration date and the maximum number of services you can protect.
In case you forgot your UI credentials, you can reset them from the CLI following [the steps described in the troubleshooting section](troubleshooting.md#web-ui).
You can update your username or password by filling the dedicated forms. For security reason, you need to enter your current password even if you are connected.
Please note that when your username or password is updated, you will be logout from the web UI to log in again.
You can power-up your login security by adding **Two-Factor Authentication (2FA)** to your account. By doing so, an extra code will be needed in addition to your password.
The web UI uses [Time based One Time Password (TOTP)](https://en.wikipedia.org/wiki/Time-based_one-time_password) as 2FA implementation : using a **secret key**, the algorithm will generate **one time passwords only valid for a short period of time**.
Any TOTP client such as Google Authenticator, Authy, FreeOTP, ... can be used to store the secret key and generate the codes. Please note that once TOTP is enabled, **you won't be able to retrieve it from the web UI**.
The following steps are needed to enable the TOTP feature from the web UI :
- Copy the secret key or use the QR code on your authenticator app
A new secret key is **generated each time** you visit the page or submit the form. In case something went wrong (e.g. : expired TOTP code), you will need to copy the new secret key to your authenticator app until 2FA is successfully enabled.
When you enable 2FA, you will be provided with **5 recovery codes**. These codes can be used to recover your account in case you have lost your TOTP secret key. Each code can only be used once. **These codes will only be shown once so make sure to store them in a safe place**.
If you ever lose your recovery codes, **you can refresh them via the TOTP section of the account management page**. Please note that the old recovery codes will be invalidated.
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.
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.6.0-beta/misc/integrations) of the repository.
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.
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.6.0-beta/misc/integrations) of the repository.
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.
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.6.0-beta/misc/integrations) of the repository.
The web UI can be deployed using a dedicated container which is available on [Docker Hub](https://hub.docker.com/r/bunkerity/bunkerweb-ui) as a standard [Deployment](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/).
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.
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.6.0-beta/misc/integrations) of the repository.
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 :
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.
