Skip to content

Commit a7e942f

Browse files
AlcidesRCAlcidesRC
committed
docs(README.md): update doc
1 parent 02a8d19 commit a7e942f

File tree

1 file changed

+25
-266
lines changed

1 file changed

+25
-266
lines changed

‎README.md

Lines changed: 25 additions & 266 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
[![Continuous Integration](https://github.com/fonil/dockerized-php/actions/workflows/ci.yml/badge.svg)](https://github.com/fonil/dockerized-php/actions/workflows/ci.yml)
1+
[![Continuous Integration](https://github.com/AlcidesRC/dockerized-php-supervisor/actions/workflows/ci.yml/badge.svg)](https://github.com/AlcidesRC/dockerized-php-supervisor/actions/workflows/ci.yml)
22

33
# Dockerized PHP - Supervisor
44

@@ -14,14 +14,15 @@
1414

1515
## Summary
1616

17-
This repository contains a _dockerized_ environment for building PHP applications based on **php:8.3.10-fpm-alpine** with Caddy support.
17+
This repository contains a _dockerized_ environment for building PHP applications based on **php:8.3.10-fpm-alpine** with Supervisor support.
1818

1919
### Highlights
2020

2121
- Unified environment to build <abbr title="Command Line Interface">CLI</abbr>, <u>web applications</u> and/or <u>micro-services</u> based on **PHP8**.
2222
- Allows you to create an optimized **development environment** Docker image
2323
- Allows you to create an optimized **production-ready** Docker image
24-
- **Self-signed local domains** thanks to Caddy.
24+
- Using **built-in PHP webserver**.
25+
- Managed PHP-FPM and built-in web server via Supervisor.
2526

2627

2728

@@ -48,7 +49,7 @@ To use this repository you need:
4849
| Type | Component | Description |
4950
| -------------- | -------------------------------------------------------- | ------------------------------------------------------------ |
5051
| Infrastructure | [Docker](https://www.docker.com/) | Containerization platform |
51-
| Service | [Caddy Server](https://caddyserver.com/) | Open source web server with automatic HTTPS written in Go |
52+
| Service | [Supervisor](http://supervisord.org/) | Supervisor is a client/server system that allows its users to control a number of processes on UNIX-like operating systems. |
5253
| Service | [PHP-FPM](https://www.php.net/manual/en/install.fpm.php) | PHP with FastCGI Process Manager |
5354
| Miscelaneous | [Bash](https://www.gnu.org/software/bash/) | Allows to create an interactive shell within containerized service |
5455
| Miscelaneous | [Make](https://www.gnu.org/software/make/) | Allows to execute commands defined on a _Makefile_ |
@@ -59,313 +60,71 @@ To use this repository you need:
5960

6061

6162

62-
## Getting Started
63-
64-
Just clone the repository into your preferred path:
65-
66-
```bash
67-
$ mkdir -p ~/path/to/my-new-project && cd ~/path/to/my-new-project
68-
$ git clone git@github.com:fonil/dockerized-php.git .
69-
```
70-
71-
### Conventions
72-
73-
#### Dockerfile
74-
75-
`Dockerfile` is based on [multi-stage builds](https://docs.docker.com/build/building/multi-stage/) in order to simplify the process to generate the **development container image** and the optimized **production-ready container image**.
76-
77-
##### Default Stages
78-
79-
| Name | Description |
80-
| --------------------------- | ------------------------------------------------------------ |
81-
| `base-image` | Used to define the base Docker image |
82-
| `common` | Used to define generic variables: `WORKDIR`, `HEALTCHECK`, etc. |
83-
| `extensions-builder-common` | Used to build generic PHP extensions |
84-
| `extensions-builder-dev` | Used to build **development** PHP extensions |
85-
| `build-development` | Used to build the development environment |
86-
| `optimize-php-dependencies` | Used to optimize the PHP dependencies in production by removing the development ones |
87-
| `build-production` | Used to build the **production** environment |
88-
89-
###### Default Stages Hierarchy
90-
91-
```mermaid
92-
---
93-
title: Dockerfile Stages Hierarchy
94-
---
95-
stateDiagram-v2
96-
[*] --> BaseImage
97-
BaseImage --> Common
98-
Common --> ExtensionsBuilderCommon
99-
100-
ExtensionsBuilderCommon --> ExtensionsBuilderDev
101-
ExtensionsBuilderDev --> BuildDevelopment
102-
103-
ExtensionsBuilderCommon --> OptimizePhpDependencies
104-
OptimizePhpDependencies --> BuildProduction
105-
```
106-
107-
##### Health check
108-
109-
A custom health check script is provided to check the container service by performing a `PHP-FPM` `ping/pong` check.
110-
111-
You can find this shell script at `build/healthcheck.sh`.
112-
113-
114-
115-
> [!NOTE]
116-
>
117-
> Review the `Dockerfile` file and adjust the `HEALTHCHECK` directive options accordingly.
63+
## Development Environment
11864

11965

12066

12167
> [!IMPORTANT]
12268
>
123-
> Remember to rebuild the Docker image if you make any change on this file.
124-
125-
126-
127-
##### Non-Privileged User
128-
129-
Current container service uses a **non-privileged user** to execute `PHP-FPM`, with same User/Group ID than the host user.
130-
131-
This mechanism allows to `PHP-FPM` create/update shared resources within the host with the same credentials than current host user, avoiding possible file-permissions issues.
132-
133-
To create this user in the container service, current host user details are collected in the `Makefile` and passed to Docker `build` command as arguments:
134-
135-
| Argument | Default value | Required value | Description |
136-
| ----------------- | --------------- | --------------------- | -------------------------- |
137-
| `HOST_USER_NAME` | host-user-name | `$ id --user --name` | Current host user name |
138-
| `HOST_GROUP_NAME` | host-group-name | `$ id --group --name` | Current host group name |
139-
| `HOST_USER_ID` | 1001 | `$ id --user` | Current host user ID |
140-
| `HOST_GROUP_ID` | 1001 | `$ id --group` | Current host user group ID |
141-
142-
143-
144-
> [!NOTE]
69+
> This development environment is based on [Dockerized PHP](https://github.com/alcidesrc/dockerized-php), a framework agnostic *dockerized* environment to create and deploy PHP applications.
14570
>
146-
> Review the `Makefile` and `Dockerfile` files and adjust the arguments to your convenience.
71+
> Please take a look to the [README.md](https://github.com/alcidesrc/dockerized-php/blob/main/README.md) file to know how to familiarize with it and get up and running.
14772
14873

14974

15075
> [!IMPORTANT]
15176
>
152-
> Remember to rebuild the Docker image if you make any change on `Dockerfile` file.
153-
154-
155-
156-
#### Logging
157-
158-
The container service logs to `STDOUT` by default.
159-
160-
#### Project Structure
161-
162-
```text
163-
├── build # Docker-related configuration files
164-
│ ├── Caddyfile # Caddy's configuration file
165-
│ ├── healthcheck.sh # Shell script for Docker's HEALTHCHECK directive
166-
│ ├── www.conf # PHP-FPM configuration file
167-
│ └── xdebug.ini # xDebug configuration file
168-
├── coverage # Code Coverage HTML report target folder
169-
├── src # PHP application folder
170-
├── caddy-root-ca-authority.crt # Generated certificate file with Caddy Root CA Authority details
171-
├── docker-compose.yml
172-
├── Dockerfile
173-
├── Makefile
174-
└── README.md # This file
175-
```
176-
177-
##### Volumes
178-
179-
There are some volumes created between the *host* and the container service:
180-
181-
| Host path | Container path | Description |
182-
| ------------ | -------------- | --------------------------------------- |
183-
| `./src` | `/code` | PHP application folder |
184-
| `./coverage` | `/coverage` | Code Coverage HTML report target folder |
185-
186-
187-
188-
> [!NOTE]
77+
> Default application is based on [PHP Skeleton](https://github.com/alcidesrc/php-skeleton), a minimalistic boilerplate to create PHP applications from scratch.
18978
>
190-
> Review the `docker-compose.yml` and volumes to your convenience.
191-
79+
> Please take a look to the [README.md](https://github.com/alcidesrc/php-skeleton/blob/main/README.md) file to know how to familiarize with it and get up and running.
19280
19381

194-
> [!IMPORTANT]
195-
>
196-
> Remember to restart the container service if you make any change in `docker-compose.yml`.
19782

83+
------
19884

19985

20086

201-
##### Available Commands
87+
## Getting Started
20288

203-
A *Makefile* is provided with following commands:
89+
Just clone the repository into your preferred path:
20490

20591
```bash
206-
~/path/to/my-new-project$ make
207-
208-
╔══════════════════════════════════════════════════════════════════════════════╗
209-
║ ║
210-
║ .: AVAILABLE COMMANDS :. ║
211-
║ ║
212-
╚══════════════════════════════════════════════════════════════════════════════╝
213-
214-
· build Docker: builds the service
215-
· up Docker: starts the service
216-
· restart Docker: restarts the service
217-
· down Docker: stops the service
218-
· logs Docker: exposes the service logs
219-
· bash Docker: establish a bash session into main container
220-
· extract-caddy-certificate Setup: extracts the Caddy Local Authority certificate
221-
· show-context Setup: show context
222-
· uninstall Application: removes the PHP application
223-
· install-skeleton Application: installs PHP Skeleton
224-
· install-laravel Application: installs Laravel
225-
· install-symfony Application: installs Symfony
92+
$ mkdir -p ~/path/to/my-new-project && cd ~/path/to/my-new-project
93+
$ git clone git@github.com:alcidesrc/dockerized-php-supervisor.git .
22694
```
22795

228-
#### Web Server
229-
230-
This project uses Caddy as main web server which <u>provides HTTPS by default</u>.
231-
232-
233-
234-
> [!WARNING]
235-
>
236-
> Caddy is optional and you can replace/remove it based on your preferences.
237-
238-
239-
240-
##### Default Domain
241-
242-
The default website domain is `https://website.localhost`.
243-
244-
Any `.localhost` TLD resolves by default to `127.0.0.1` so no any additional action is required on your *host*.
245-
246-
247-
248-
> [!NOTE]
249-
>
250-
> Review the `build/Caddyfile` and apply the changes based on your preferences.
251-
>
252-
> Review the `Makefile` to ensure `WEBSITE_URL` constant has the desired domain URL.
253-
254-
255-
256-
> [!IMPORTANT]
257-
>
258-
> Remember to restart the container service if you make any change in `build/Caddyfile` file.
259-
260-
261-
262-
##### Certificate Authority (CA) & SSL Certificate
263-
264-
You can generate/register the **Caddy Authority Certificate** in order to get `SSL` support .
265-
266-
267-
268-
> [!NOTE]
269-
>
270-
> Just execute `make install-caddy-certificate` and follow the provided guidelines to generate the Caddy Authority Certificate and install it on your host.
271-
272-
273-
274-
> [!IMPORTANT]
275-
>
276-
> Remember to reinstall the certificate if you rebuild the container service.
277-
278-
279-
280-
281-
#### PHP Application
282-
283-
PHP application must be placed into `src` folder.
284-
285-
286-
287-
> [!TIP]
288-
>
289-
> There are some `Makefile` commands that allows you to install a [PHP Skeleton](https://github.com/fonil/php-skeleton) as boilerplate or [Laravel](https://github.com/laravel/laravel) when creating `PHP` applications from scratch.
290-
29196

29297

293-
##### Testing
294-
295-
###### Mocking Date/Time functions
296-
297-
Testing with date and/or time variations sometimes can be a nightmare. To assist on this topic the **UOPZ** extension has been installed and enabled by default.
298-
299-
300-
301-
> [!TIP]
302-
>
303-
> You can use [slope-it/clock-mock](https://github.com/slope-it/clock-mock) as a development dependency when mocking date/time functions.
304-
305-
306-
307-
### Development Environment
308-
309-
#### Build Docker Image
310-
311-
##### Linux Based Hosts
98+
### Building the container
31299

313100
```bash
314101
$ make build
315102
```
316103

317-
##### Windows Hosts
104+
### Starting the container service
318105

319106
```bash
320-
$ docker compose build
107+
$ make up
321108
```
322109

323-
#### Access to Container
324-
325-
##### Linux Based Hosts
110+
### Accessing to Supervisor Status web panel
326111

327112
```bash
328-
$ make bash
113+
$ xdg-open http://guest:guest@localhost:9001
329114
```
330115

331-
##### Windows Hosts
116+
### Accessing to web application
332117

333118
```bash
334-
$ docker run -it --rm app:development bash
119+
$ xdg-open http://localhost
335120
```
336121

337-
### Production Environment
338-
339-
#### Build Docker Image
340-
341-
##### Linux Based Hosts
122+
### Stopping the container service
342123

343124
```bash
344-
$ docker buildx build --target=build-production --tag="app:production" .
125+
$ make down
345126
```
346127

347-
##### Windows Hosts
348-
349-
```bash
350-
$ docker buildx build --target=build-production --tag="app:production" .
351-
```
352-
353-
#### Access to Container
354-
355-
##### Linux Based Hosts
356-
357-
```bash
358-
$ docker run -it --rm app:production sh
359-
```
360-
361-
##### Windows Hosts
362-
363-
```bash
364-
$ docker run -it --rm app:production sh
365-
```
366-
367-
368-
369128

370129

371130
------
@@ -385,7 +144,7 @@ Only the latest major version receives security fixes.
385144

386145
### Reporting a Vulnerability
387146

388-
If you discover a security vulnerability within this project, please [open an issue here](https://github.com/fonil/dockerized-php/issues). All security vulnerabilities will be promptly addressed.
147+
If you discover a security vulnerability within this project, please [open an issue here](https://github.com/alcidesrc/dockerized-php-supervisor/issues). All security vulnerabilities will be promptly addressed.
389148

390149

391150

0 commit comments

Comments
 (0)