Skip to content

Commit e64d69b

Browse files
committed
Update README
1 parent 7369d06 commit e64d69b

File tree

1 file changed

+152
-121
lines changed

1 file changed

+152
-121
lines changed

README.md

+152-121
Original file line numberDiff line numberDiff line change
@@ -17,7 +17,15 @@
1717

1818
This image is based on the official **[Apache 2.2](https://hub.docker.com/_/httpd)** Docker image and extends it with the ability to have **virtual hosts created automatically**, as well as **adding SSL certificates** when creating new directories. For that to work, it integrates two tools that will take care about the whole process: **[watcherd](https://github.com/devilbox/watcherd)** and **[vhost-gen](https://github.com/devilbox/vhost-gen)**.
1919

20-
From a users perspective, you mount your local project directory into the container under `/shared/httpd`. Any directory then created in your local project directory wil spawn a new virtual host by the same name. Additional settings such as custom server names, PHP-FPM or even different Apache templates per project are supported as well.
20+
From a users perspective, you mount your local project directory into the container under `/shared/httpd`. Any directory then created in your local project directory wil spawn a new virtual host by the same name. Each virtual host optionally supports a generic or custom backend configuration (**static files**, **PHP-FPM** or **reverse proxy**).
21+
22+
**HTTP/2 is enabled by default for all SSL connections.**
23+
24+
For convenience the entrypoint script during `docker run` provides a pretty decent **validation and documentation** about wrong user input and suggests steps to fix it.
25+
26+
| <img style="height: 180px;" height="180" src="doc/img/httpd-backend-invalid-type.png" /> | <img style="height: 180px;" height="180" src="doc/img/httpd-backend-unsupported.png" /> | <img style="height: 180px;" height="180" src="doc/img/httpd-alias-validation.png" /> | <img style="height: 180px;" height="180" src="doc/img/httpd-valid.png" /> |
27+
|:----------------------:|:------------------:|:-------------:|:--------:|
28+
| Invalid backend string | Backend Suggestion | Invalid Alias | Verified |
2129

2230

2331
> ##### 🐱 GitHub: [devilbox/docker-apache-2.2](https://github.com/devilbox/docker-apache-2.2)
@@ -75,103 +83,111 @@ The following Docker image tags are built once and can be used for reproducible
7583
> **Warning:** The latest available git tag is also build every night and considered a rolling tag.
7684
7785

78-
## ✰ Features
79-
80-
> 🛈 For details see **[Documentation: Features](doc/features.md)**
81-
82-
### Automated virtual hosts
83-
84-
Virtual hosts are created automatically, simply by creating a new project directory (inside or outside of the container). This allows you to quickly create new projects and work on them in your IDE without the hassle of configuring the web server.
8586

86-
### Automated PHP-FPM setup
87+
## ✰ Features
8788

88-
PHP is not included in the provided images, but you can link the Docker container to a PHP-FPM image with any PHP version. This allows you to easily switch PHP versions and choose one which is currently required.
89+
This repository uses official httpd Docker images and adds a lot of features, logic and autmomation op top. This allows you to feature-toggle certain functionality simply by setting environment variables.
8990

90-
### Automated SSL certificate generation
91+
Below is a brief overview about most outstanding features, but I would still advice you to read up on available [environment variables](#-environment-variables), as well as the [architecture](#-architecture) to get the whole picture.
9192

92-
SSL certificates are generated automatically for each virtual host to allow you to develop over HTTP and HTTPS.
9393

94-
### Automatically trusted HTTPS
94+
> 🛈 For details see **[Documentation: Features](doc/features.md)**
9595
96-
SSL certificates are signed by a certificate authority (which is also being generated). The CA file can be mounted locally and imported into your browser, which allows you to automatically treat all generated virtual host certificates as trusted.
96+
#### Automated mass virtual hosts
97+
* Virtual hosts are created automatically, simply by creating a new project directory (inside or outside of the container). This allows you to quickly create new projects and work on them in your IDE without the hassle of configuring the web server.
9798

98-
### Customization per virtual host
99+
#### Automated PHP-FPM setup
100+
* PHP is not included in the provided images, but you can enable a remote backend and link it to a PHP-FPM image. This allows you to easily switch PHP versions and choose one which is currently required.
99101

100-
Each virtual host can individually be fully customized via `vhost-gen` templates.
102+
#### Automated Reverse Proxy setup
103+
* In reverse proxy mode, you can choose any http or https backend of your likings. This way you can proxy NodeJS, Python, etc. and use the webserver to add SSL in front.
101104

102-
### Customization for the default virtual host
105+
#### Automated SSL certificate generation
106+
* SSL certificates are generated automatically for each virtual host if you choose to enable it
103107

104-
The default virtual host is also treated differently from the auto-generated mass virtual hosts. You can choose to disable it or use it for a generic overview page for all of your created projects.
108+
#### Trusted HTTPS in all vhosts
109+
* Virtual host SSL certificates are signed by an internal Certificate Authority (or one you provide to the image). That makes it possible to set the CA to trusted and all generated vhosts will automatically have trusted SSL.
105110

106-
### Reverse Proxy integration
111+
#### Customization per virtual host
112+
* Each virtual host can individually be fully customized via [`vhost-gen`](https://github.com/devilbox/vhost-gen) templates.
107113

108-
Through virtual host customization, any project can also be served with a reverse proxy. This is useful if you want to run NodeJS or Python projects which require a reverse proxy and still want to benefit with a custom domain and auto-generated SSL certificates.
114+
#### Local file system permission sync
115+
* File system permission/ownership of files/dirs inside the running container can be synced with the permission on your host system. This is accomplished by specifying a user- and group-id to the `docker run` command.
109116

110-
### Local file system permission sync
117+
#### Tested with common Frameworks
118+
* Wordpress, Drupal, Laravel, CakePHP, PhalconPHP, Magento, Shopware, Typo3, Yii, Zend and many others.
111119

112-
File system permissions of files/dirs inside the running Docker container are synced with the permission on your host system. This is accomplished by specifying a user- and group-id to the `docker run` command.
113120

114121

115122
## ∑ Environment Variables
116123

117124
The provided Docker images add a lot of injectables in order to customize it to your needs. See the table below for a brief overview.
118125

119126
> 🛈 For details see **[Documentation: Environment variables](doc/environment-variables.md)**
127+
>
128+
> If you don't feel like reading the documentation, simply try out your `docker run` command and add
129+
> any environment variables specified below. The validation will tell you what you might have done wrong,
130+
> how to fix it and what the meaning is.
120131
121132
<table>
122-
<tr>
123-
<th>Apache</th>
124-
<th>Logging</th>
125-
<th>Features</th>
126-
</tr>
127133
<tr valign="top" style="vertical-align:top">
128134
<td>
135+
<strong>Verbosity</strong><br/>
136+
<code><a href="doc/environment-variables.md#-debug_entrypoint" >DEBUG_ENTRYPOINT</a></code><br/>
137+
<code><a href="doc/environment-variables.md#-debug_runtime" >DEBUG_RUNTIME</a></code><br/>
129138
</td>
130139
<td>
131-
<code>DEBUG_ENTRYPOINT</code><br/>
132-
<code>DEBUG_RUNTIME</code><br/>
133-
<code>DOCKER_LOGS</code><br/>
140+
<strong>System</strong><br/>
141+
<code><a href="doc/environment-variables.md#-new_uid" >NEW_UID</a></code><br/>
142+
<code><a href="doc/environment-variables.md#-new_gid" >NEW_GID</a></code><br/>
143+
<code><a href="doc/environment-variables.md#-timezone" >TIMEZONE</a></code><br/>
134144
</td>
135145
<td>
136-
<code>TIMEZONE</code><br/>
137-
<code>NEW_UID</code><br/>
138-
<code>NEW_GID</code><br/>
146+
<strong>Nginx</strong><br/>
147+
<code><a href="doc/environment-variables.md#-worker_connections" >WORKER_CONNECTIONS</a></code><br/>
148+
<code><a href="doc/environment-variables.md#-worker_processes" >WORKER_PROCESSES</a></code><br/>
139149
</td>
140150
</tr>
141-
<tr>
142-
<th>Main vHost</th>
143-
<th>Mass vHost</th>
144-
<th>PHP</th>
145-
</tr>
146151
<tr valign="top" style="vertical-align:top">
147152
<td>
148-
<code>MAIN_VHOST_ENABLE</code><br/>
149-
<code>MAIN_VHOST_SSL_TYPE</code><br/>
150-
<code>MAIN_VHOST_SSL_GEN</code><br/>
151-
<code>MAIN_VHOST_SSL_CN</code><br/>
152-
<code>MAIN_VHOST_DOCROOT</code><br/>
153-
<code>MAIN_VHOST_TPL</code><br/>
154-
<code>MAIN_VHOST_STATUS_ENABLE</code><br/>
155-
<code>MAIN_VHOST_STATUS_ALIAS</code><br/>
153+
<strong>Main Vhost</strong><br/>
154+
<code><a href="doc/environment-variables.md#-main_vhost_enable" >MAIN_VHOST_ENABLE</a></code><br/>
155+
<code><a href="doc/environment-variables.md#-main_vhost_aliases_allow" >MAIN_VHOST_ALIASES_ALLOW</a></code><br/>
156+
<code><a href="doc/environment-variables.md#-main_vhost_aliases_deny" >MAIN_VHOST_ALIASES_DENY</a></code><br/>
157+
<code><a href="doc/environment-variables.md#-main_vhost_backend" >MAIN_VHOST_BACKEND</a></code><br/>
158+
<code><a href="doc/environment-variables.md#-main_vhost_backend_timeout" >MAIN_VHOST_BACKEND_TIMEOUT</a></code><br/>
159+
<code><a href="doc/environment-variables.md#-main_vhost_docroot_dir" >MAIN_VHOST_DOCROOT_DIR</a></code><br/>
160+
<code><a href="doc/environment-variables.md#-main_vhost_template_dir" >MAIN_VHOST_TEMPLATE_DIR</a></code><br/>
161+
<code><a href="doc/environment-variables.md#-main_vhost_ssl_type" >MAIN_VHOST_SSL_TYPE</a></code><br/>
162+
<br/>
163+
<code><a href="doc/environment-variables.md#-main_vhost_ssl_cn" >MAIN_VHOST_SSL_CN</a></code><br/>
164+
<code><a href="doc/environment-variables.md#-main_vhost_status_enable" >MAIN_VHOST_STATUS_ENABLE</a></code><br/>
165+
<code><a href="doc/environment-variables.md#-main_vhost_status_alias" >MAIN_VHOST_STATUS_ALIAS</a></code><br/>
156166
</td>
157167
<td>
158-
<code>MASS_VHOST_ENABLE</code><br/>
159-
<code>MASS_VHOST_SSL_TYPE</code><br/>
160-
<code>MASS_VHOST_SSL_GEN</code><br/>
161-
<code>MASS_VHOST_TLD</code><br/>
162-
<code>MASS_VHOST_DOCROOT</code><br/>
163-
<code>MASS_VHOST_TPL</code><br/>
168+
<strong>Mass Vhost</strong><br/>
169+
<code><a href="doc/environment-variables.md#-mass_vhost_enable" >MASS_VHOST_ENABLE</a></code><br/>
170+
<code><a href="doc/environment-variables.md#-mass_vhost_aliases_allow" >MASS_VHOST_ALIASES_ALLOW</a></code><br/>
171+
<code><a href="doc/environment-variables.md#-mass_vhost_aliases_deny" >MASS_VHOST_ALIASES_DENY</a></code><br/>
172+
<code><a href="doc/environment-variables.md#-mass_vhost_backend" >MASS_VHOST_BACKEND</a></code><br/>
173+
<code><a href="doc/environment-variables.md#-mass_vhost_backend_timeout" >MASS_VHOST_BACKEND_TIMEOUT</a></code><br/>
174+
<code><a href="doc/environment-variables.md#-mass_vhost_docroot_dir" >MASS_VHOST_DOCROOT_DIR</a></code><br/>
175+
<code><a href="doc/environment-variables.md#-mass_vhost_template_dir" >MASS_VHOST_TEMPLATE_DIR</a></code><br/>
176+
<code><a href="doc/environment-variables.md#-mass_vhost_ssl_type" >MASS_VHOST_SSL_TYPE</a></code><br/>
177+
<br/>
178+
<code><a href="doc/environment-variables.md#-mass_vhost_backend_rewrite" >MASS_VHOST_BACKEND_REWRITE</a></code><br/>
179+
<code><a href="doc/environment-variables.md#-mass_vhost_tld_suffix" >MASS_VHOST_TLD_SUFFIX</a></code><br/>
164180
</td>
165181
<td>
166-
<code>PHP_FPM_ENABLE</code><br/>
167-
<code>PHP_FPM_SERVER_ADDR</code><br/>
168-
<code>PHP_FPM_SERVER_PORT</code><br/>
169-
<code>PHP_FPM_TIMEOUT</code><br/>
182+
<strong>All Vhosts</strong><br/>
183+
<code><a href="doc/environment-variables.md#-docker_logs" >DOCKER_LOGS</a></code><br/>
184+
<code><a href="doc/environment-variables.md#-http2_enable" >HTTP2_ENABLE</a></code><br/>
170185
</td>
171186
</tr>
172187
</table>
173188

174189

190+
175191
## 📂 Volumes
176192

177193
The provided Docker images offer the following internal paths to be mounted to your local file system.
@@ -187,6 +203,7 @@ The provided Docker images offer the following internal paths to be mounted to y
187203
<td>
188204
<code>/var/www/default/</code><br/>
189205
<code>/shared/httpd/</code><br/>
206+
<code>/ca/</code><br/>
190207
</td>
191208
<td>
192209
<code>/etc/httpd-custom.d/</code><br/>
@@ -197,94 +214,100 @@ The provided Docker images offer the following internal paths to be mounted to y
197214
</table>
198215

199216

217+
200218
## 🖧 Exposed Ports
201219

202-
When you plan on using `443` you should enable automated SSL certificate generation.
220+
When you plan on using `443` you must enable SSL via environment variables, otherwise nothing will be listening on that port.
203221

204222
| Docker | Description |
205223
|--------|-------------|
206224
| 80 | HTTP listening Port |
207225
| 443 | HTTPS listening Port |
208226

209227

228+
210229
## 💡 Examples
211230

212-
### Serve static files
231+
The documentation provides many copy/paste examples about common use-cases including dummy projects.
213232

214-
Mount your local directort `~/my-host-www` into the container and server those files.
233+
The given examples distinguish between two different kinds of setup: The default vhost, which only allows to serve a single project and the mass vhost setup, which allows unlimited vhosts that are created automtically. Both types offer the same set of features and are configured in a similar way, so If you find an example in one kind it is easily applyable to the other kind as well.
215234

216-
**Note:** Files will be server from `~/my-host-www/htdocs`.
217-
```bash
218-
docker run -d -it \
219-
-p 80:80 \
220-
-v ~/my-host-www:/var/www/default \
221-
devilbox/apache-2.2
222-
```
235+
> 🛈 For details see **[Documentation: Examples](doc/examples.md)**<br/>
236+
> 🛈 For details see **[Docker Compose: Examples](examples/)**
237+
238+
#### Docker
239+
240+
<table>
241+
<tr valign="top" style="vertical-align:top">
242+
<td>
243+
<strong>Default vhost</strong><br/>
244+
&nbsp;&nbsp;&nbsp;💡 <a href="doc/examples.md#-serve-staticfiles" >Serve static files</a><br/>
245+
&nbsp;&nbsp;&nbsp;💡 <a href="doc/examples.md#-serve-php-files-with-php-fpm" >Serve PHP files</a><br/>
246+
&nbsp;&nbsp;&nbsp;💡 <a href="doc/examples.md#-serve-php-files-with-php-fpm-and-sync-local-permissions" >Sync local filestem permission</a><br/>
247+
&nbsp;&nbsp;&nbsp;💡 <a href="doc/examples.md#-serve-php-files-with-php-fpm-over-https" >Serve PHP files over HTTPS</a><br/>
248+
&nbsp;&nbsp;&nbsp;💡 <a href="doc/examples.md#-act-as-a-reverse-proxy-for-nodejs" >Reverse Proxy NodeJS</a><br/>
249+
</td>
250+
<td>
251+
<strong>Unlimited vhosts</strong><br/>
252+
&nbsp;&nbsp;&nbsp;💡 <a href="#" >Custom <code>vhost-gen</code> template</a><br/>
253+
&nbsp;&nbsp;&nbsp;💡 <a href="doc/examples.md#-fully-functional-lemp-stack-with-mass-vhosts" >LEMP stack with PHP-FPM and MariaDB</a><br/>
254+
&nbsp;&nbsp;&nbsp;💡 <a href="#" ><strong>Wordpress</strong> setup</a><br/>
255+
</td>
256+
</tr>
257+
</table>
258+
259+
#### Docker Compose
260+
261+
<table>
262+
<tr valign="top" style="vertical-align:top">
263+
<td>
264+
<strong>Default vhost</strong><br/>
265+
&nbsp;&nbsp;&nbsp;💡 <a href="examples/default-vhost__static-files/" >Serve static files</a><br/>
266+
&nbsp;&nbsp;&nbsp;💡 <a href="examples/default-vhost__php-fpm/" >Serve PHP files</a><br/>
267+
&nbsp;&nbsp;&nbsp;💡 <a href="examples/default-vhost__php-fpm__ssl/" >Serve PHP files over HTTPS</a><br/>
268+
&nbsp;&nbsp;&nbsp;💡 <a href="examples/default-vhost__reverse-proxy__node/" >Reverse Proxy NodeJS</a><br/>
269+
&nbsp;&nbsp;&nbsp;💡 <a href="examples/default-vhost__reverse-proxy__python/" >Reverse Proxy Python</a><br/>
270+
</td>
271+
<td>
272+
<strong>Unlimited vhosts</strong><br/>
273+
&nbsp;&nbsp;&nbsp;💡 <a href="examples/mass-vhost__php-fpm__ssl/" >Serve PHP files over HTTPS</a><br/>
274+
&nbsp;&nbsp;&nbsp;💡 <a href="examples/mass-vhost__reverse-proxy__ssl/" >Reverse Proxy <strong>and</strong> PHP-FPM</a><br/>
275+
</td>
276+
</tr>
277+
</table>
223278

224-
### Serve PHP files with PHP-FPM
225279

226-
| PHP-FPM Reference Images |
227-
|--------------------------|
228-
| <a title="PHP-FPM Reference Images" href="https://github.com/devilbox/docker-php-fpm" ><img title="Devilbox" height="82px" src="https://raw.githubusercontent.com/devilbox/artwork/master/submissions_banner/cytopia/02/png/banner_256_trans.png" /></a> |
229280

230-
Note, for this to work, the `~/my-host-www` dir must be mounted into the Apache container as well as into the php-fpm container.
231-
Each PHP-FPM container also has the option to enable Xdebug and more, see their respective Readme files for futher settings.
281+
## 👷 Architecture
282+
283+
The following diagram shows the basic architecture of this docker image.
232284

233-
```bash
234-
# Start the PHP-FPM container, mounting the same diectory
235-
docker run -d -it \
236-
--name php \
237-
-p 9000 \
238-
-v ~/my-host-www:/var/www/default \
239-
devilbox/php-fpm:5.6-prod
240-
241-
# Start the Apache Docker, linking it to the PHP-FPM container
242-
docker run -d -it \
243-
-p 80:80 \
244-
-v ~/my-host-www:/var/www/default \
245-
-e PHP_FPM_ENABLE=1 \
246-
-e PHP_FPM_SERVER_ADDR=php \
247-
-e PHP_FPM_SERVER_PORT=9000 \
248-
--link php \
249-
devilbox/apache-2.2
250-
```
251285

252-
### Fully functional LEMP stack
286+
> 🛈 For details see **[Documentation: Architecture](doc/architecture.md)**
253287
254-
Same as above, but also add a MySQL container and link it into Apache.
255288
```bash
256-
# Start the MySQL container
257-
docker run -d -it \
258-
--name mysql \
259-
-p 3306:3306 \
260-
-e MYSQL_ROOT_PASSWORD=my-secret-pw \
261-
devilbox/mysql:mysql-5.5
262-
263-
# Start the PHP-FPM container, mounting the same diectory.
264-
# Also make sure to
265-
# forward the remote MySQL port 3306 to 127.0.0.1:3306 within the
266-
# PHP-FPM container in order to be able to use `127.0.0.1` for mysql
267-
# connections from within the php container.
268-
docker run -d -it \
269-
--name php \
270-
-p 9000:9000 \
271-
-v ~/my-host-www:/var/www/default \
272-
-e FORWARD_PORTS_TO_LOCALHOST=3306:mysql:3306 \
273-
devilbox/php-fpm:5.6-prod
274-
275-
# Start the Apache Docker, linking it to the PHP-FPM container
276-
docker run -d -it \
277-
-p 80:80 \
278-
-v ~/my-host-www:/var/www/default \
279-
-e PHP_FPM_ENABLE=1 \
280-
-e PHP_FPM_SERVER_ADDR=php \
281-
-e PHP_FPM_SERVER_PORT=9000 \
282-
--link php \
283-
--link mysql \
284-
devilbox/apache-2.2
289+
# mass-vhost # main-vhost only
290+
docker-entrypoint.sh docker-entrypoint.sh
291+
| |
292+
↓ ↓
293+
supervisord (pid 1) httpd (pid 1)
294+
/ |
295+
/ |
296+
↙ ↓
297+
start start
298+
httpd watcherd
299+
/ | \
300+
/ | \
301+
↓ ↓ ↘
302+
sgn rm create-vhost.sh
303+
httpd vhost | |
304+
| |
305+
↓ ↓
306+
cert-gen vhost-gen ⭢ generate vhost
285307
```
286308

287309

310+
288311
## 🖤 Sister Projects
289312

290313
Show some love for the following sister projects.
@@ -329,10 +352,16 @@ Show some love for the following sister projects.
329352
<a href="https://hub.docker.com/r/devilbox/nginx-stable"><code>devilbox/nginx-stable</code></a><br/>
330353
<a href="https://hub.docker.com/r/devilbox/nginx-mainline"><code>devilbox/nginx-mainline</code></a>
331354
</td>
355+
<tr>
356+
<td><a title="Bind DNS Server" href="https://github.com/cytopia/docker-bind" ><img width="256px" src="https://raw.githubusercontent.com/devilbox/artwork/master/submissions_banner/cytopia/06/png/banner_256_trans.png" /></a></td>
357+
<td><a href="https://github.com/cytopia/docker-bind"><code>docker-bind</code></a></td>
358+
<td><a href="https://hub.docker.com/r/cytopia/bind"><code>cytopia/bind</code></a></td>
359+
</tr>
332360
</tr>
333361
</table>
334362

335363

364+
336365
## 👫 Community
337366

338367
In case you seek help, go and visit the community pages.
@@ -372,6 +401,7 @@ In case you seek help, go and visit the community pages.
372401
</table>
373402

374403

404+
375405
## 🧘 Maintainer
376406

377407
**[@cytopia](https://github.com/cytopia)**
@@ -394,6 +424,7 @@ Terraform: [cytopia](https://registry.terraform.io/namespaces/cytopia) **·**
394424
Ansible: [cytopia](https://galaxy.ansible.com/cytopia)
395425

396426

427+
397428
## 🗎 License
398429

399430
**[MIT License](LICENSE)**

0 commit comments

Comments
 (0)