|
| 1 | +**Architecture** | |
| 2 | +[Features](features.md) | |
| 3 | +[Examples](examples.md) | |
| 4 | +[Environment variables](environment-variables.md) | |
| 5 | +[Volumes](volumes.md) |
| 6 | + |
| 7 | +--- |
| 8 | + |
| 9 | +# Documentation: Architecture |
| 10 | + |
| 11 | +1. [Tools](#-tools) |
| 12 | +2. [Execution Chain](#-execution-chain) |
| 13 | +3. [Directories and files](#-directories-and-files) |
| 14 | + |
| 15 | + |
| 16 | +## 👷 Tools |
| 17 | + |
| 18 | +This project is using four core tools that interact with each other in order to achieve automated project-based mass virtual hosting with HTTPS support from SSL certificates signed by an internal CA. |
| 19 | + |
| 20 | +| Tool | Usage | |
| 21 | +|------|-------| |
| 22 | +| [`vhost-gen`](https://github.com/devilbox/vhost-gen) | An arbitrary vhost generator for Nginx (mainline and stable), Apache 2.2 and Apache 2.4 to ensure one config generates the same vhost functionality independently of underlying webserver | |
| 23 | +| [`cert-gen`](https://github.com/devilbox/cert-gen) | A tool to generate and validate Certificate Authorities and SSL certificates which are signed by a Certificate Authority | |
| 24 | +| [`watcherd`](https://github.com/devilbox/watcherd) | A file system change detecter (`inotify`-based or `bash`-based), which acts on changes (`add` or `delete` of directories in this case) with custom commands and offers a trigger command on change. (in this configuration, it will call `vhost-gen`, when a new directory is added in order to make the mass vhost possible. It will call a generic `rm ...` commad for a `delete` and restarts the webserver as its trigger command. | |
| 25 | +| [`supervisord`](http://supervisord.org/) | A daemon that manages the run-time of multiple other daemons. In this case it ensures that `watcherd` and the webserver are up and running. | |
| 26 | + |
| 27 | + |
| 28 | + |
| 29 | +## 👷 Execution Chain |
| 30 | + |
| 31 | +This is the execution chain for how the mass virtual hosting or single vhost is achieved: |
| 32 | +```bash |
| 33 | + # mass-vhost # main-vhost only |
| 34 | + docker-entrypoint.sh docker-entrypoint.sh |
| 35 | + | | |
| 36 | + ↓ ↓ |
| 37 | + supervisord (pid 1) httpd (pid 1) |
| 38 | + / | |
| 39 | + / | |
| 40 | + ↙ ↓ |
| 41 | + start start |
| 42 | + httpd watcherd |
| 43 | + / | \ |
| 44 | + / | \ |
| 45 | + ↓ ↓ ↘ |
| 46 | + sgn rm create-vhost.sh |
| 47 | + httpd vhost | | |
| 48 | + | | |
| 49 | + ↓ ↓ |
| 50 | + cert-gen vhost-gen ⭢ generate vhost |
| 51 | +``` |
| 52 | + |
| 53 | +### The basics |
| 54 | + |
| 55 | +1. The `docker-entrypoint.sh` script sets and validates given options |
| 56 | +2. It then passes over to `supervisord` via `exec` |
| 57 | +3. `supervisord` ensures the web server is running |
| 58 | +4. `supervisord` ensures `watcherd` is running |
| 59 | +5. `watcherd` listens for file system changed (directory created or directory removed)<sup>\[1\]</sup> |
| 60 | + |
| 61 | +> **\[1\]** A renamed directory is: directory removed and directory created |
| 62 | +
|
| 63 | +### What does `watcherd` do? |
| 64 | + |
| 65 | +* `watcherd` is setup with two events: |
| 66 | + * event: directory created |
| 67 | + * event: directory removed |
| 68 | +* `watcherd` is setup with two event actions (one for each event): |
| 69 | + * directory created: call `create-vhost.sh` |
| 70 | + * directory removed: remove webserver vhost config for this project |
| 71 | +* `watcherd` is setup with one *trigger* that acts after any event action has been executed: |
| 72 | + * send a reload or stop signal to webserver |
| 73 | + |
| 74 | +So in simple terms, when `watcherd` detects that a new directory was created, it calls `create-vhost.sh` and sends a reload or stop signal to the webserver. In case the webserver will shutdown gracefully, it will immediately be started by `supervisord`. In both cases, the new webserver configuration will be applied.<br/> |
| 75 | +When `watcherd` detects that a directory was removed, it will remove the corresponding webserver vhost configuration file and send a reload or stop signal to the webserver (In case of a stop signal, `supervisord` will again ensure the webserver will come up). |
| 76 | + |
| 77 | +### What does `create-vhost.sh` do? |
| 78 | + |
| 79 | +`create-vhost.sh` is a minimalistic run-time version of the entrypoint script and does thorough validation on anything that could not be validated during startup-time. Additionally it does the following: |
| 80 | + |
| 81 | +* `create-vhost.sh` will generate SSL certificates (signed by internal CA) via `cert-gen` |
| 82 | +* `create-vhost.sh` will generate a customized `vhost-gen` configuration file |
| 83 | +* `create-vhost.sh` will move any custom `vhost-gen` templates into place |
| 84 | +* `create-vhost.sh` will passes over to `vhost-gen`, which will then generate a virtual host configuration file. |
| 85 | + |
| 86 | +Once `vhost-gen` is done, the execution cycle is returned to `watcherd`, which will apply its trigger. |
| 87 | + |
| 88 | + |
| 89 | + |
| 90 | + |
| 91 | +## 👷 Directories and files |
| 92 | + |
| 93 | +To get some insights on the internals, here is an overview about all directory paths and files that are being used: |
| 94 | + |
| 95 | +| Directories / Files | Description | |
| 96 | +|----------------------------------|-------------| |
| 97 | +| `/var/www/default/` | Main Vhost base directory | |
| 98 | +| `/shared/httpd/` | Mass Vhost base directory | |
| 99 | +| `/ca/` | Directory where generated Certificate Authoriy will be placed (You can mount this and place your own, if you prefer to use another one) | |
| 100 | +| `/etc/httpd/cert/` | Directory where Vhost SSL certificates and keys are stored | |
| 101 | +| `/etc/httpd/conf.d/` | Webserer configuration directory: Stores main vhost configuration file | |
| 102 | +| `/etc/httpd/vhost.d/` | Webserver configuration directory: Stores mass vhost configuration files | |
| 103 | +| `/etc/httpd-custom.d/` | Webserver configuration directory: Mount this and place your custom webserver configuration files in here | |
| 104 | +| `/var/logs/httpd/` | Webserver log directory | |
| 105 | +| `/etc/vhost-gen/` | Directory for [vhost-gen](https://github.com/devilbox/vhost-gen/): contains its default configuration (placed during install time) | |
| 106 | +| `/etc/vhost-gen.d/` | Directory for [vhost-gen](https://github.com/devilbox/vhost-gen/): mount this and place custom `vhost-gen` templates to override `vhost-gen`'s behaviour. Templates can be found: [here](https://github.com/devilbox/vhost-gen/tree/master/etc/templates) | |
| 107 | +| [`/docker-entrypoint.sh`](../Dockerfiles/data/docker-entrypoint.sh) | Entrypoint script that will be executed by the container during startup | |
| 108 | +| `/docker-entrypoint.d/` | Entrypoint validators and functions that are used by `/docker-entrypoint.sh` | |
| 109 | +| [`/etc/supervisord.conf`](../Dockerfiles/data/docker-entrypoint.d/15-supervisord.sh) | Supervisord coniguration file. Supervisord will only be started, whenn `MASS_VHOST_ENABLE` is set to `1` | |
| 110 | +| [`/usr/local/bin/create-vhost.sh`](../Dockerfiles/data/create-vhost.sh) | A wrapper script to create a vhost (validation, ssl certificates and calls `vhost-gen` | |
0 commit comments