docs - web UI
This commit is contained in:
bunkerity
parent
75f299978c
commit
d9f7706969
191
docs/web_ui.md
191
docs/web_ui.md
|
|
@ -2,14 +2,199 @@
|
|||
|
||||
## Overview
|
||||
|
||||
<img src="https://github.com/bunkerity/bunkerized-nginx/blob/dev/docs/img/web-ui.gif?raw=true" />
|
||||
|
||||
## Usage
|
||||
|
||||
The web UI has its own set of environment variables to configure it :
|
||||
- `ADMIN_USERNAME` and `ADMIN_PASSWORD` : credentials for accessing the web UI
|
||||
- `ABSOLUTE_URI` : the full public URI that points to the web UI
|
||||
- `API_URI` : path of the bunkerized-nginx API (must match the corresponding `API_URI` of the bunkerized-nginx instance)
|
||||
- `DOCKER_HOST` : Docker API endpoint address (default = `unix:///var/run/docker.sock`)
|
||||
|
||||
The deployment should be very easy because the web UI is web a service itself so we can use bunkerized-nginx as a reverse proxy in front of it.
|
||||
|
||||
**
|
||||
Using the web UI in a Docker environment (containers, autoconf or Swarm) exposes a security risk because you need to mount the Docker API socket into the web UI container. It's highly recommended to use a middleware like [tecnativa/docker-socket-proxy](https://github.com/Tecnativa/docker-socket-proxy) to reduce the risk as much as possible.
|
||||
Extra security steps still needs to be done like : complex admin password, hard to guess public URI, network isolation from others services, HTTPS only, ...
|
||||
**
|
||||
|
||||
### Docker
|
||||
|
||||
### Docker autoconf
|
||||
First of all, we will need to setup two networks one for ui communication and the other one for the services :
|
||||
```shell
|
||||
$ docker network create ui-net
|
||||
$ docker network create services-net
|
||||
```
|
||||
|
||||
### Docker Swarm
|
||||
We also need a volume to shared the generated configuration from the web UI to the bunkerized-nginx instances :
|
||||
```shell
|
||||
$ docker volume create bunkerized-vol
|
||||
```
|
||||
|
||||
### Kubernetes
|
||||
Next we will create the "Docker API proxy" container that will be in the front of the Docker socket and deny access to sensitive things :
|
||||
```shell
|
||||
$ docker run -d \
|
||||
--name my-docker-proxy \
|
||||
--network ui-net \
|
||||
-v /var/run/docker.sock:/var/run/docker.sock:ro \
|
||||
-e CONTAINERS=1 \
|
||||
-e SWARM=1 \
|
||||
-e SERVICES=1 \
|
||||
tecnativa/docker-socket-proxy
|
||||
```
|
||||
|
||||
We can now create the web UI container based on bunkerized-nginx-ui image :
|
||||
```shell
|
||||
$ docker run -d \
|
||||
--name my-bunkerized-ui \
|
||||
--network ui-net \
|
||||
-v bunkerized-vol:/etc/nginx \
|
||||
-e ABSOLUTE_URI=https://admin.example.com/admin-changeme/ \
|
||||
-e DOCKER_HOST=tcp://my-docker-proxy:2375 \
|
||||
-e API_URI=/ChangeMeToSomethingHardToGuess \
|
||||
-e ADMIN_USERNAME=admin \
|
||||
-e ADMIN_PASSWORD=changeme \
|
||||
bunkerity/bunkerized-nginx-ui
|
||||
```
|
||||
|
||||
Last but not least, you need to start the bunkerized-nginx and configure it as a reverse proxy for the web UI web service :
|
||||
```shell
|
||||
$ docker create -d \
|
||||
--name my-bunkerized \
|
||||
--network ui-net \
|
||||
-p 80:8080 \
|
||||
-p 443:8443 \
|
||||
-v bunkerized-vol:/etc/nginx \
|
||||
-v "${PWD}/certs:/etc/letsencrypt" \
|
||||
-e SERVER_NAME=admin.example.com \
|
||||
-e MULTISITE=yes \
|
||||
-e USE_API=yes \
|
||||
-e API_URI=/ChangeMeToSomethingHardToGuess \
|
||||
-e AUTO_LETS_ENCRYPT=yes \
|
||||
-e REDIRECT_HTTP_TO_HTTPS=yes \
|
||||
-e admin.example.com_USE_REVERSE_PROXY=yes \
|
||||
-e admin.example.com_REVERSE_PROXY_URL=/admin-changeme/ \
|
||||
-e admin.example.com_REVERSE_PROXY_HOST=http://my-bunkerized-ui:5000/ \
|
||||
-e admin.example.com_REVERSE_PROXY_HEADERS=X-Script-Name /admin-changeme \
|
||||
-e admin.example.com_USE_MODSECURITY=no \
|
||||
-l bunkerized-nginx.UI \
|
||||
bunkerity/bunkerized-nginx
|
||||
$ docker network connect services-net my-bunkerized
|
||||
$ docker start my-bunkerized
|
||||
```
|
||||
|
||||
The web UI should now be accessible at https://admin.example.com/admin-changeme/.
|
||||
|
||||
docker-compose equivalent :
|
||||
```yaml
|
||||
version: '3'
|
||||
|
||||
services:
|
||||
|
||||
my-bunkerized:
|
||||
image: bunkerity/bunkerized-nginx
|
||||
restart: always
|
||||
depends_on:
|
||||
- my-bunkerized-ui
|
||||
ports:
|
||||
- 80:8080
|
||||
- 443:8443
|
||||
volumes:
|
||||
- ./letsencrypt:/etc/letsencrypt
|
||||
- bunkerized-vol:/etc/nginx
|
||||
environment:
|
||||
- SERVER_NAME=admin.example.com # replace with your domain
|
||||
- MULTISITE=yes
|
||||
- USE_API=yes
|
||||
- API_URI=/ChangeMeToSomethingHardToGuess # change it to something hard to guess + must match API_URI from myui service
|
||||
- AUTO_LETS_ENCRYPT=yes
|
||||
- REDIRECT_HTTP_TO_HTTPS=yes
|
||||
- admin.example.com_USE_REVERSE_PROXY=yes
|
||||
- admin.example.com_REVERSE_PROXY_URL=/admin-changeme/ # change it to something hard to guess
|
||||
- admin.example.com_REVERSE_PROXY_HOST=http://my-bunkerized-ui:5000/
|
||||
- admin.example.com_REVERSE_PROXY_HEADERS=X-Script-Name /admin # must match REVERSE_PROXY_URL
|
||||
- admin.example.com_USE_MODSECURITY=no
|
||||
labels:
|
||||
- "bunkerized-nginx.UI"
|
||||
|
||||
my-bunkerized-ui:
|
||||
image: bunkerity/bunkerized-nginx-ui
|
||||
restart: always
|
||||
depends_on:
|
||||
- my-docker-proxy
|
||||
networks:
|
||||
- ui-net
|
||||
volumes:
|
||||
- autoconf:/etc/nginx
|
||||
environment:
|
||||
- ABSOLUTE_URI=https://admin.example.com/admin/ # change it to your full URI
|
||||
- DOCKER_HOST=tcp://my-docker-proxy:2375
|
||||
- API_URI=/ChangeMeToSomethingHardToGuess # must match API_URI from bunkerized-nginx
|
||||
- ADMIN_USERNAME=admin # change it to something hard to guess
|
||||
- ADMIN_PASSWORD=changeme # change it to a good password
|
||||
|
||||
my-docker-proxy:
|
||||
image: tecnativa/docker-socket-proxy
|
||||
restart: always
|
||||
networks:
|
||||
- ui-net
|
||||
volumes:
|
||||
- /var/run/docker.sock:/var/run/docker.sock:ro
|
||||
environment:
|
||||
- CONTAINERS=1
|
||||
- SWARM=1
|
||||
- SERVICES=1
|
||||
|
||||
networks:
|
||||
ui-net:
|
||||
services-net:
|
||||
|
||||
volumes:
|
||||
bunkerized-vol:
|
||||
```
|
||||
|
||||
### Linux
|
||||
|
||||
First of all, you need to edit the web UI configuration file located at `/opt/bunkerized-nginx/ui/variables.env` :
|
||||
```conf
|
||||
ABSOLUTE_URI=https://admin.example.com/admin-changeme/
|
||||
DOCKER_HOST=
|
||||
ADMIN_USERNAME=admin
|
||||
ADMIN_PASSWORD=changeme
|
||||
```
|
||||
|
||||
Make sure that the web UI service is automatically started on boot :
|
||||
```shell
|
||||
$ systemctl enable bunkerized-nginx-ui
|
||||
```
|
||||
|
||||
Now you can start the web UI service :
|
||||
```shell
|
||||
$ systemctl start bunkerized-nginx-ui
|
||||
```
|
||||
|
||||
Edit the bunkerized-nginx configurations located at `/opt/bunkerized-nginx/variables.env` :
|
||||
```conf
|
||||
HTTP_PORT=80
|
||||
HTTPS_PORT=443
|
||||
SERVER_NAME=admin.example.com
|
||||
MULTISITE=yes
|
||||
AUTO_LETS_ENCRYPT=yes
|
||||
REDIRECT_HTTP_TO_HTTPS=yes
|
||||
admin.example.com_USE_REVERSE_PROXY=yes
|
||||
admin.example.com_REVERSE_PROXY_URL=/admin-changeme/
|
||||
# Local bunkerized-nginx-ui
|
||||
admin.example.com_REVERSE_PROXY_HOST=http://127.0.0.1:5000/
|
||||
# Remote bunkerized-nginx-ui
|
||||
#REVERSE_PROXY_HOST=http://service.example.local:5000
|
||||
admin.example.com_REVERSE_PROXY_HEADERS=X-Script-Name /admin-changeme
|
||||
admin.example.com_USE_MODSECURITY=no
|
||||
```
|
||||
|
||||
And run the `bunkerized-nginx` command to apply changes :
|
||||
```shell
|
||||
$ bunkerized-nginx
|
||||
```
|
||||
|
||||
The web UI should now be accessible at https://admin.example.com/admin-changeme/.
|
||||
|
|
|
|||
Loading…
Reference in New Issue