diff --git a/docs/web_ui.md b/docs/web_ui.md index 89a0755..b93caf9 100644 --- a/docs/web_ui.md +++ b/docs/web_ui.md @@ -2,14 +2,199 @@ ## Overview + + ## 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/.