Skip to content

Commit 0ec979f

Browse files
lotyplotyp
authored
Merge pull request #32 from wayofdev/feat/structure-updates
docs: update README
2 parents 99b9cbd + 9450615 commit 0ec979f

File tree

2 files changed

+255
-46
lines changed

2 files changed

+255
-46
lines changed

‎README.md

+255-42
Original file line numberDiff line numberDiff line change
@@ -21,90 +21,303 @@
2121

2222
# Docker Image: Nginx
2323

24-
This image is used together with [wayofdev/docker-php-dev](https://github.com/wayofdev/docker-php-dev) and other WOD images, to create local development environment for our projects.
24+
This **Docker image** provides a streamlined **Nginx** setup optimized for **local PHP development environments**.
2525

26-
![Screenshot](.github/assets/screenshot.png)
26+
It's designed to seamlessly integrate with [wayofdev/docker-php-dev](https://github.com/wayofdev/docker-php-dev) and other (WOD) images, creating an efficient local development ecosystem for web projects.
2727

28-
## ⚙️ Development
28+
<br>
29+
30+
## 🌟 Why Choose This Image for Local Development?
2931

30-
To install dependencies and start development you can check contents of our `Makefile`
32+
- **Ansible-based Configuration:** Easily customizable through Ansible templates
33+
- **PHP-FPM Optimized:** Pre-configured to work with PHP-FPM for fast local testing and development
34+
- **SSL Ready:** Includes built-in support for HTTPS using self-signed certificates, mimicking production environments locally
35+
- **Developer Friendly:** Packed with tools and configurations to enhance local development workflows
36+
- **Flexible Deployment:** Includes a `k8s-alpine` variant for testing Kubernetes setups locally
37+
- **Lightweight:** Based on **Alpine Linux** for minimal footprint and faster local builds
38+
- **Multi-arch Support:** Works on both **x86 (AMD64)** and **ARM64** architectures, supporting various development machines
39+
- **Regular Updates:** Maintained and updated frequently to align with the latest development practices
3140

32-
### → Requirements
41+
Perfect for developing **Laravel** applications, **Symfony** projects, or any **PHP-based web services** in a local environment that closely mirrors production setups.
3342

34-
For testing purposes we use **goss** and **dgoss**, follow installation instructions on [their official README](https://github.com/aelsabbahy/goss/blob/master/extras/dgoss/README.md)
43+
Provides foundation for creating, testing, and debugging your web applications locally.
3544

3645
<br>
3746

38-
### → Building locally
47+
If you **like/use** this package, please consider ⭐️ **starring** it. Thanks!
3948

40-
Generating distributable Dockerfiles from yaml source code:
49+
<br>
4150

42-
```bash
43-
make generate
44-
```
51+
## 📦 Image Variants
52+
53+
| Variant | Description |
54+
|------------|-------------------------------------------------------------------------------|
55+
| dev-alpine | For local development environments, uses 80 and 443 ports. |
56+
| k8s-alpine | Optimized for k8s and local environments, uses 8880 and 8443 ports, rootless. |
4557

4658
<br>
4759

48-
Building default image:
60+
## 🚀 Usage
61+
62+
### → Pulling the Image
4963

5064
```bash
51-
git clone [email protected]:wayofdev/docker-nginx.git
52-
cd docker-nginx
53-
make build
65+
docker pull wayofdev/nginx:k8s-alpine-latest
5466
```
5567

56-
To **build** image, **test** it and then **clean** temporary files run:
57-
58-
```bash
59-
make
68+
Replace `k8s-alpine-latest` with your desired type, and tag.
69+
70+
### → Available Image Variants
71+
72+
- **Types:** k8s, dev
73+
- **Architectures:** amd64, arm64
74+
75+
### → Using in Docker Compose
76+
77+
Here's an example `docker-compose.yml` for a typical setup:
78+
79+
```yaml
80+
services:
81+
app:
82+
image: wayofdev/php-dev:8.3-fpm-alpine-latest
83+
container_name: ${COMPOSE_PROJECT_NAME}-app
84+
restart: on-failure
85+
networks:
86+
- default
87+
- shared
88+
depends_on:
89+
- database
90+
links:
91+
- database
92+
volumes:
93+
- ./.github/assets:/assets:rw,cached
94+
- ./app:/app:rw,cached
95+
- ./.env:/app/.env
96+
- ~/.composer:/.composer
97+
- ~/.ssh:/home/www-data/.ssh
98+
environment:
99+
FAKETIME: '+2h'
100+
XDEBUG_MODE: '${XDEBUG_MODE:-off}'
101+
PHIVE_HOME: /app/.phive
102+
dns:
103+
- 8.8.8.8
104+
extra_hosts:
105+
- 'host.docker.internal:host-gateway'
106+
107+
web:
108+
image: wayofdev/nginx:k8s-alpine-latest
109+
container_name: ${COMPOSE_PROJECT_NAME}-web
110+
restart: on-failure
111+
networks:
112+
- default
113+
- shared
114+
depends_on:
115+
- app
116+
links:
117+
- app
118+
volumes:
119+
- ./app:/app:rw,cached
120+
- ./.env:/app/.env
121+
labels:
122+
- traefik.enable=true
123+
- traefik.http.routers.api-${COMPOSE_PROJECT_NAME}-secure.rule=Host(`api.${COMPOSE_PROJECT_NAME}.docker`)
124+
- traefik.http.routers.api-${COMPOSE_PROJECT_NAME}-secure.entrypoints=websecure
125+
- traefik.http.routers.api-${COMPOSE_PROJECT_NAME}-secure.tls=true
126+
- traefik.http.services.api-${COMPOSE_PROJECT_NAME}-secure.loadbalancer.server.port=8880
127+
- traefik.docker.network=network.${SHARED_SERVICES_NAMESPACE}
60128
```
61129
62-
Building all images:
130+
#### This configuration includes
63131
64-
```bash
65-
make build IMAGE_TEMPLATE=dev-alpine
66-
make build IMAGE_TEMPLATE=k8s-alpine
67-
```
132+
- An `app` service using the `wayofdev/php-dev` image for PHP processing.
133+
- A `web` service using a [custom Nginx image](https://github.com/wayofdev/docker-nginx) for serving the application.
134+
- Network configuration for both default and shared networks.
135+
- Volume mounts for application code, assets, and configuration files.
136+
- Environment variables for PHP and Xdebug configuration.
137+
- Traefik labels for reverse proxy and SSL termination.
138+
139+
#### Real-world Example
140+
141+
For a comprehensive, real-world example of how to use this image in a Docker Compose setup, please refer to the [wayofdev/laravel-starter-tpl](https://github.com/wayofdev/laravel-starter-tpl) repository. This template provides a fully configured development environment for Laravel projects using the `wayofdev/php-dev` image.
68142

69143
<br>
70144

71-
## 🧪 Testing
145+
## ⚙️ Configuration
72146

73-
Testing default image:
147+
The Nginx image is pre-configured for optimal performance with PHP applications, but you can customize it further to suit your specific needs.
74148

75-
```bash
76-
make test
77-
```
149+
### → Default Configuration
78150

79-
To test all images:
151+
The default configuration is generated using Ansible templates and includes:
80152

81-
```bash
82-
make test IMAGE_TEMPLATE=dev-alpine
83-
make test IMAGE_TEMPLATE=k8s-alpine
153+
- Optimized settings for PHP-FPM
154+
- SSL/TLS support with self-signed certificates
155+
- Gzip compression enabled
156+
- Basic security headers
157+
158+
### → Custom Configuration
159+
160+
While the configuration is primarily managed through Ansible templates, you can override specific settings:
161+
162+
1. **Environment Variables:** The image uses the following environment variables:
163+
164+
| Variable | Default Value | Description |
165+
|------------------------|---------------|---------------------------------------|
166+
| PHP_UPSTREAM_CONTAINER | app | The name of the PHP-FPM container |
167+
| PHP_UPSTREAM_PORT | 9000 | The port of the PHP-FPM container |
168+
169+
Set these in your `docker-compose.yml` file:
170+
171+
```yaml
172+
services:
173+
web:
174+
image: wayofdev/nginx:k8s-alpine-latest
175+
environment:
176+
- PHP_UPSTREAM_CONTAINER=my-php-app
177+
- PHP_UPSTREAM_PORT=9001
178+
```
179+
180+
2. **Volume Mounts:** For more extensive customizations, you can mount your own config files:
181+
182+
```yaml
183+
services:
184+
web:
185+
image: wayofdev/nginx:k8s-alpine-latest
186+
volumes:
187+
- ./custom-nginx.conf:/etc/nginx/nginx.conf
188+
- ./custom-default.conf:/etc/nginx/conf.d/default.conf
189+
```
190+
191+
### → SSL Configuration
192+
193+
The image includes self-signed SSL certificates. To use your own:
194+
195+
```yaml
196+
services:
197+
web:
198+
image: wayofdev/nginx:k8s-alpine-latest
199+
volumes:
200+
- ./certs/cert.pem:/etc/nginx/ssl/cert.pem
201+
- ./certs/key.pem:/etc/nginx/ssl/key.pem
84202
```
85203

204+
### → Advanced Configuration
205+
206+
For more advanced configurations:
207+
208+
1. Fork this repository
209+
2. Modify the Ansible templates in the `src` directory
210+
3. Regenerate the Dockerfiles using `make generate`
211+
4. Build your custom image
212+
86213
<br>
87214

88-
### → Code quality tools
215+
## 🔨 Development
89216

90-
Run **yamllint** to validate all yaml files in project:
217+
This project uses a set of tools for development and testing. The `Makefile` provides various commands to streamline the development process.
91218

92-
```bash
93-
make lint-yaml
94-
```
219+
### → Requirements
220+
221+
- Docker
222+
- Make
223+
- Ansible
224+
- goss and dgoss for testing
95225

96-
Run hadolint to validate created Dockerfiles:
226+
### → Setting Up the Development Environment
227+
228+
Clone the repository:
97229

98230
```bash
99-
make lint-docker
231+
git clone [email protected]:wayofdev/docker-nginx.git && \
232+
cd docker-nginx
100233
```
101234

102-
Run ansible-lint to validate project files:
235+
### → Generating Dockerfiles
236+
237+
Ansible is used to generate Dockerfiles and configurations. To generate distributable Dockerfiles from Jinja template source code:
103238

104239
```bash
105-
make lint-ansible
240+
make generate
106241
```
107242

243+
### → Building Images
244+
245+
- Build the default image:
246+
247+
```bash
248+
make build
249+
```
250+
251+
This command builds the image specified by the `IMAGE_TEMPLATE` variable in the Makefile. By default, it's set to `k8s-alpine`.
252+
253+
- Build a specific image:
254+
255+
```bash
256+
make build IMAGE_TEMPLATE="k8s-alpine"
257+
```
258+
259+
Replace `8.3-fpm-alpine` with your desired PHP version, type, and OS.
260+
261+
- Build all images:
262+
263+
```bash
264+
make build IMAGE_TEMPLATE="k8s-alpine"
265+
make build IMAGE_TEMPLATE="dev-alpine"
266+
```
267+
268+
These commands will build all supported image variants.
269+
270+
<br>
271+
272+
## 🧪 Testing
273+
274+
This project uses a testing approach to ensure the quality and functionality of the Docker images. The primary testing tool is [dgoss](https://github.com/aelsabbahy/goss/tree/master/extras/dgoss), which allows for testing Docker containers.
275+
276+
### → Running Tests
277+
278+
You can run tests using the following commands:
279+
280+
- Test the default image:
281+
282+
```bash
283+
make test
284+
```
285+
286+
This command tests the image specified by the `IMAGE_TEMPLATE` variable in the Makefile (default is `k8s-alpine`).
287+
288+
- Test a specific image:
289+
290+
```bash
291+
make test IMAGE_TEMPLATE="k8s-alpine"
292+
```
293+
294+
Replace `8.3-fpm-alpine` with your desired PHP version, type, and OS.
295+
296+
- Test all images:
297+
298+
```bash
299+
make test IMAGE_TEMPLATE="k8s-alpine"
300+
make test IMAGE_TEMPLATE="dev-alpine"
301+
```
302+
303+
### → Test Configuration
304+
305+
The test configurations are defined in `goss.yaml` files, which are generated for each image variant. These files specify the tests to be run, including:
306+
307+
- File existence and permissions
308+
- Process checks
309+
- Port availability
310+
- Package installations
311+
- Command outputs
312+
313+
### → Test Process
314+
315+
When you run the `make test` command, the following steps occur:
316+
317+
1. The specified Docker image is built (if not already present).
318+
2. dgoss runs the tests defined in the `goss.yaml` file against the Docker container.
319+
3. The test results are displayed in the console.
320+
108321
<br>
109322

110323
## 🔒 Security Policy

‎src/group_vars/all.yml

-4
Original file line numberDiff line numberDiff line change
@@ -27,16 +27,12 @@ tpl_dockerfiles:
2727
# Additional configuration files
2828
########################################################################################################################
2929
tpl_configs:
30-
# 00-set-upstream.sh
3130
- src: config/00-set-upstream.sh.j2
3231
dst: "../dist/{{ level }}-{{ os_name }}/configs/00-set-upstream.sh"
33-
# 00_upstream.conf
3432
- src: config/00_upstream.conf.j2
3533
dst: "../dist/{{ level }}-{{ os_name }}/configs/00_upstream.conf"
36-
## default.conf
3734
- src: config/default.conf.j2
3835
dst: "../dist/{{ level }}-{{ os_name }}/configs/default.conf"
39-
## nginx.conf
4036
- src: config/nginx.conf.j2
4137
dst: "../dist/{{ level }}-{{ os_name }}/configs/nginx.conf"
4238

0 commit comments

Comments
 (0)