Skip to content

Commit 76b6aac

Browse files
KingPinKingPin
KingPin
authored and
KingPin
committed
docs: comprehensive v1/v2 documentation with migration and troubleshooting guides
- Update README with clear v1 vs v2 comparison section - Add "Which image should I use?" decision guide at top - Update tag format documentation and Available Tags table - Add registry information section - Update image size table to show v1/v2 sizes - Add links to detailed documentation - Simplify troubleshooting section with links to docs New documentation files: - docs/migration.md: Complete v1 to v2 migration guide - docs/troubleshooting.md: Common issues and solutions - docs/local-build.md: Local development and test-build.sh usage - docs/ci.md: CI/CD pipeline and publishing documentation Changes keep README concise while providing comprehensive documentation for contributors and users migrating between variants.
1 parent 2d9a9f7 commit 76b6aac

5 files changed

Lines changed: 1525 additions & 99 deletions

File tree

‎README.md‎

Lines changed: 173 additions & 99 deletions
Original file line numberDiff line numberDiff line change
@@ -3,18 +3,26 @@
33
Multi-architecture PHP Docker images with extensive extensions for modern web development.
44

55
[![Docker Pulls](https://img.shields.io/docker/pulls/kingpin/php-docker)](https://hub.docker.com/r/kingpin/php-docker)
6-
[![GitHub Workflow Status](https://img.shields.io/github/actions/workflow/status/kingpin/php-docker/docker-image.yml?branch=main)](https://github.com/kingpin/php-docker/actions/workflows/docker-image.yml)
6+
[![GitHub Workflow Status](https://img.shields.io/github/actions/workflow/status/kingpin/php-docker/docker-ci.yml?branch=main)](https://github.com/kingpin/php-docker/actions/workflows/docker-ci.yml)
7+
8+
## 🎯 Which Image Should I Use?
9+
10+
**New projects or need process supervision?** → Use **v2** images (e.g., `8.3-fpm-alpine-v2`)
11+
**Existing deployments or maximum compatibility?** → Use **v1** images (e.g., `8.3-fpm-alpine`)
12+
13+
See [v1 vs v2 comparison](#v1-vs-v2-comparison) below for details.
714

815
## Features
916

1017
- **Multi-Architecture Support**: Works on `amd64`, `arm64/aarch64` and `arm32v7/armhf` platforms
11-
- **Multiple PHP Versions**: PHP 8.1, 8.2, and 8.3
18+
- **Multiple PHP Versions**: PHP 7.x (deprecated), 8.1, 8.2, and 8.3
1219
- **Multiple Server Types**: CLI, FPM, and Apache
13-
- **Base OS Options**: Alpine (lightweight) and Debian (Bookworm)
20+
- **Base OS Options**: Alpine (lightweight) and Debian (Bookworm/Bullseye)
1421
- **Extensive Extensions**: 30+ PHP extensions pre-installed
1522
- **Latest Composer**: Always ships with the latest Composer version
1623
- **Image Processing Tools**: Includes ImageMagick, GD, and various image optimization utilities
1724
- **Apache Mods**: Includes Apache rewrite module (for Apache variants)
25+
- **v2: s6-overlay init**: Proper PID 1 and service supervision for reliable multi-process containers
1826

1927
## Environment Variables
2028

@@ -63,6 +71,8 @@ docker run -e PHP_MEMORY_LIMIT=512M -e PHP_MAX_EXECUTION_TIME=600 kingpin/php-do
6371

6472
## 🚀 Quick Start
6573

74+
### v1 (Legacy/Compatible)
75+
6676
```bash
6777
# Run PHP CLI
6878
docker run --rm kingpin/php-docker:8.3-cli-alpine php -v
@@ -74,50 +84,118 @@ docker run --rm -v $(pwd):/app -w /app kingpin/php-docker:8.3-cli-alpine php scr
7484
docker run -d -p 9000:9000 -v $(pwd):/var/www/html kingpin/php-docker:8.3-fpm-alpine
7585
```
7686

77-
## Troubleshooting
87+
### v2 (Modern/Supervised)
7888

79-
### Common Issues and Solutions
89+
```bash
90+
# Run PHP CLI with s6-overlay
91+
docker run --rm kingpin/php-docker:8.3-cli-alpine-v2 php -v
8092

81-
#### Container exits immediately
82-
**Issue**: The container stops right after starting.
83-
**Solution**: For FPM and Apache variants, ensure you're not overriding the CMD. For CLI variants, provide a command that keeps the container running if needed.
93+
# Run with your code mounted
94+
docker run --rm -v $(pwd):/app -w /app kingpin/php-docker:8.3-cli-alpine-v2 php script.php
8495

85-
```bash
86-
docker run -d kingpin/php-docker:8.3-cli-alpine tail -f /dev/null
96+
# Start PHP-FPM with s6 supervision
97+
docker run -d -p 9000:9000 -v $(pwd):/var/www/html kingpin/php-docker:8.3-fpm-alpine-v2
8798
```
8899

89-
#### Permission issues with mounted volumes
90-
**Issue**: Permission errors when writing to mounted volumes.
91-
**Solution**: Match the container's user ID with your host user ID.
100+
## v1 vs v2 Comparison
92101

93-
```bash
94-
docker run -u $(id -u):$(id -g) -v $(pwd):/app kingpin/php-docker:8.3-cli-alpine php script.php
95-
```
102+
We maintain **two image variants** to support both existing users and modern use cases:
96103

97-
#### Missing PHP extension
98-
**Issue**: Your application requires an extension not included in the image.
99-
**Solution**: Create a custom Dockerfile to install additional extensions.
104+
### v1 (Legacy) - Tags without `-v2` suffix
100105

101-
```dockerfile
102-
FROM kingpin/php-docker:8.3-fpm-alpine
103-
RUN install-php-extensions <extension-name>
104-
```
106+
**Purpose:** Maximum compatibility with existing deployments and stable behavior.
105107

106-
#### Memory limit errors
107-
**Issue**: PHP script exceeds memory limit.
108-
**Solution**: Increase the memory limit.
108+
**Key Characteristics:**
109109

110-
```bash
111-
docker run -e PHP_MEMORY_LIMIT=1G kingpin/php-docker:8.3-cli-alpine php script.php
112-
```
110+
- Simpler Dockerfile with fewer runtime layers
111+
- No s6-overlay or external init system
112+
- Builds with standard `docker build` (no BuildKit required)
113+
- Smaller image footprint in some configurations
113114

114-
#### Slow PHP performance
115-
**Issue**: PHP scripts running slowly.
116-
**Solution**: Check OPcache settings and enable JIT for PHP 8.0+.
115+
**Pros:**
117116

118-
```bash
119-
docker run -e PHP_OPCACHE_MEMORY_CONSUMPTION=256 kingpin/php-docker:8.3-cli-alpine php script.php
120-
```
117+
✅ Drop-in replacement for existing deployments
118+
✅ Simpler container runtime behavior
119+
✅ Smaller learning curve
120+
✅ No BuildKit dependency for local builds
121+
122+
**Cons:**
123+
124+
❌ Less robust process supervision
125+
❌ Harder to run multiple services reliably
126+
❌ No built-in service health monitoring
127+
❌ May not handle signals properly in all scenarios
128+
129+
**Use v1 when:**
130+
131+
- You have existing containers relying on legacy behavior
132+
- You prefer simpler runtime without init systems
133+
- You need maximum backward compatibility
134+
- You run single-process containers only
135+
136+
### v2 (Modern) - Tags with `-v2` suffix
137+
138+
**Purpose:** Modernized image with s6-overlay for proper init and service supervision.
139+
140+
**Key Characteristics:**
141+
142+
- Uses [s6-overlay](https://github.com/just-containers/s6-overlay) as PID 1 init
143+
- Proper signal handling and zombie process reaping
144+
- Service supervision and restart policies
145+
- BuildKit-enabled for better build performance and caching
146+
147+
**Pros:**
148+
149+
✅ Proper PID 1 and process supervision (s6)
150+
✅ Safe for running FPM + sidecar processes (e.g., cron, queue workers)
151+
✅ Better build performance with BuildKit cache mounts
152+
✅ Easier to add background services and health checks
153+
✅ Handles container signals properly
154+
155+
**Cons:**
156+
157+
❌ Requires Docker BuildKit/buildx for advanced features
158+
❌ Slightly larger image due to s6-overlay (~2-3MB)
159+
❌ Different runtime behavior may require minor adjustments
160+
❌ More complex init system to understand
161+
162+
**Use v2 when:**
163+
164+
- You need reliable multi-process containers
165+
- You want proper signal handling and process supervision
166+
- You're starting a new project
167+
- You run background workers or cron alongside FPM
168+
169+
> **Migration Guide:** See [docs/migration.md](docs/migration.md) for detailed migration steps and compatibility notes.
170+
171+
## Troubleshooting
172+
173+
For common issues and solutions, see [docs/troubleshooting.md](docs/troubleshooting.md).
174+
175+
Quick tips:
176+
177+
- **Container exits immediately**: For CLI variants, provide a long-running command
178+
- **Permission issues**: Match container UID with host UID using `-u` flag
179+
- **Missing extensions**: Extend the image and use `install-php-extensions`
180+
- **v2 build fails locally**: Enable Docker BuildKit or install buildx plugin
181+
- **v2 s6-overlay not found**: Ensure you're using the `-v2` tag
182+
183+
## Local Development & Testing
184+
185+
For contributors and advanced users, see [docs/local-build.md](docs/local-build.md) for:
186+
187+
- Using the `test-build.sh` helper script
188+
- Building both v1 and v2 variants locally
189+
- Running smoke tests
190+
191+
## CI/CD & Publishing
192+
193+
Images are automatically built, tested, and published via GitHub Actions:
194+
195+
- **All branches/PRs**: Build and test only (no publishing)
196+
- **`main` branch**: Build, test, and publish to all registries
197+
198+
For more details, see [docs/ci.md](docs/ci.md).
121199

122200
## Security Considerations
123201

@@ -212,61 +290,66 @@ opcache.jit=1255
212290

213291
These images are available on multiple registries for redundancy and flexibility:
214292

215-
- Docker Hub: `docker.io/kingpin/php-docker`
216-
- GitHub Container Registry: `ghcr.io/kingpin/php-docker`
217-
- Quay.io: `quay.io/kingpinx1/php-docker`
293+
- **Docker Hub**: `docker.io/kingpin/php-docker`
294+
- **GitHub Container Registry**: `ghcr.io/kingpin/php-docker`
295+
- **Quay.io**: `quay.io/kingpinx1/php-docker`
296+
297+
All registries have identical image content and tags.
218298

219299
## Available Tags
220300

301+
### Tag Format
302+
303+
- **v1 images**: `{php-version}-{type}-{os}` (e.g., `8.3-fpm-alpine`)
304+
- **v2 images**: `{php-version}-{type}-{os}-v2` (e.g., `8.3-fpm-alpine-v2`)
305+
221306
### Current Supported Images
222307

223-
| PHP Version | Type | OS | Tag Example |
224-
|-------------|--------|-----------|----------------------------|
225-
| 8.1 | CLI | Bookworm | `8.1-cli-bookworm` |
226-
| 8.1 | CLI | Alpine | `8.1-cli-alpine` |
227-
| 8.1 | FPM | Bookworm | `8.1-fpm-bookworm` |
228-
| 8.1 | FPM | Alpine | `8.1-fpm-alpine` |
229-
| 8.1 | Apache | Bookworm | `8.1-apache-bookworm` |
230-
| 8.2 | CLI | Bookworm | `8.2-cli-bookworm` |
231-
| 8.2 | CLI | Alpine | `8.2-cli-alpine` |
232-
| 8.2 | FPM | Bookworm | `8.2-fpm-bookworm` |
233-
| 8.2 | FPM | Alpine | `8.2-fpm-alpine` |
234-
| 8.2 | Apache | Bookworm | `8.2-apache-bookworm` |
235-
| 8.3 | CLI | Bookworm | `8.3-cli-bookworm` |
236-
| 8.3 | CLI | Alpine | `8.3-cli-alpine` (latest) |
237-
| 8.3 | FPM | Bookworm | `8.3-fpm-bookworm` |
238-
| 8.3 | FPM | Alpine | `8.3-fpm-alpine` |
239-
| 8.3 | Apache | Bookworm | `8.3-apache-bookworm` |
240-
241-
> **Note:** PHP 8.1+ are now built on Bookworm (Debian 12). For backward compatibility, using either `bullseye` or `bookworm` in the tag for PHP 8.1+ will give you the Bookworm-based image.
242-
243-
### Deprecated Tags
244-
245-
The following tags are available but no longer built via CI:
246-
247-
- 7-cli-bullseye
248-
- 7-cli-alpine
249-
- 7-apache-bullseye
250-
- 7-fpm-bullseye
251-
- 7-fpm-alpine
252-
- 8.0-cli-bullseye
253-
- 8.0-cli-alpine
254-
- 8.0-apache-bullseye
255-
- 8.0-fpm-bullseye
256-
- 8.0-fpm-alpine
257-
258-
> **Important:** PHP 7.x has been deprecated and is no longer supported. Please upgrade to PHP 8.1 or newer for security and performance improvements.
308+
Both v1 and v2 variants are available for all combinations below:
309+
310+
| PHP Version | Type | OS | v1 Tag Example | v2 Tag Example |
311+
|-------------|--------|-----------|------------------------|----------------------------|
312+
| 8.3 | CLI | Alpine | `8.3-cli-alpine` | `8.3-cli-alpine-v2` |
313+
| 8.3 | CLI | Bookworm | `8.3-cli-bookworm` | `8.3-cli-bookworm-v2` |
314+
| 8.3 | FPM | Alpine | `8.3-fpm-alpine` | `8.3-fpm-alpine-v2` |
315+
| 8.3 | FPM | Bookworm | `8.3-fpm-bookworm` | `8.3-fpm-bookworm-v2` |
316+
| 8.3 | Apache | Bookworm | `8.3-apache-bookworm` | `8.3-apache-bookworm-v2` |
317+
| 8.2 | CLI | Alpine | `8.2-cli-alpine` | `8.2-cli-alpine-v2` |
318+
| 8.2 | CLI | Bookworm | `8.2-cli-bookworm` | `8.2-cli-bookworm-v2` |
319+
| 8.2 | FPM | Alpine | `8.2-fpm-alpine` | `8.2-fpm-alpine-v2` |
320+
| 8.2 | FPM | Bookworm | `8.2-fpm-bookworm` | `8.2-fpm-bookworm-v2` |
321+
| 8.2 | Apache | Bookworm | `8.2-apache-bookworm` | `8.2-apache-bookworm-v2` |
322+
| 8.1 | CLI | Alpine | `8.1-cli-alpine` | `8.1-cli-alpine-v2` |
323+
| 8.1 | CLI | Bookworm | `8.1-cli-bookworm` | `8.1-cli-bookworm-v2` |
324+
| 8.1 | FPM | Alpine | `8.1-fpm-alpine` | `8.1-fpm-alpine-v2` |
325+
| 8.1 | FPM | Bookworm | `8.1-fpm-bookworm` | `8.1-fpm-bookworm-v2` |
326+
| 8.1 | Apache | Bookworm | `8.1-apache-bookworm` | `8.1-apache-bookworm-v2` |
327+
328+
> **Note:** PHP 8.1+ images are built on Bookworm (Debian 12). Bullseye tags redirect to Bookworm for PHP 8.1+.
329+
330+
### Deprecated Tags (v1 only)
331+
332+
PHP 7.x images are available but no longer actively maintained:
333+
334+
- `7-cli-bullseye`, `7-cli-alpine`
335+
- `7-fpm-bullseye`, `7-fpm-alpine`
336+
- `7-apache-bullseye`
337+
338+
> **Important:** PHP 7.x has reached end-of-life. Please upgrade to PHP 8.1+ for security and performance.
259339
260340
## 📊 Image Sizes
261341

262-
| Type | OS | Approx. Size |
263-
|--------|-----------|--------------|
264-
| CLI | Alpine | ~80MB |
265-
| CLI | Debian | ~140MB |
266-
| FPM | Alpine | ~85MB |
267-
| FPM | Debian | ~150MB |
268-
| Apache | Alpine | ~95MB |
269-
| Apache | Debian | ~180MB |
342+
Approximate compressed sizes (v1 / v2):
343+
344+
| Type | OS | v1 Size | v2 Size | Delta |
345+
|--------|-----------|---------|----------|----------|
346+
| CLI | Alpine | ~80MB | ~83MB | +3MB |
347+
| CLI | Bookworm | ~140MB | ~143MB | +3MB |
348+
| FPM | Alpine | ~85MB | ~88MB | +3MB |
349+
| FPM | Bookworm | ~150MB | ~153MB | +3MB |
350+
| Apache | Bookworm | ~180MB | ~183MB | +3MB |
351+
352+
> v2 overhead is primarily the s6-overlay binaries (~2-3MB per image).
270353
271354
## Pre-installed PHP Extensions
272355

@@ -396,33 +479,20 @@ We welcome contributions to improve these Docker images!
396479
### How to Contribute
397480

398481
1. **Fork the repository**
399-
2. **Create a feature branch**
400-
```bash
401-
git checkout -b feature/new-extension
402-
```
403-
3. **Make your changes**
404-
4. **Run tests locally**
405-
```bash
406-
# Test building the image
407-
docker build --build-arg VERSION=8.3-cli-alpine --build-arg PHPVERSION=8.3 --build-arg BASEOS=alpine -t test-image .
408-
409-
# Verify functionality
410-
docker run --rm test-image php -m
411-
```
482+
2. **Create a feature branch**: `git checkout -b feature/new-extension`
483+
3. **Make your changes** (update both `Dockerfile.v1` and `Dockerfile.v2` if applicable)
484+
4. **Test locally**: Use `test-build.sh` to verify builds
412485
5. **Submit a Pull Request**
413486

414487
### Guidelines
415488

416489
- Follow the existing code style and conventions
417-
- Add tests for new features
490+
- Test both v1 and v2 variants when making changes
418491
- Update documentation as needed
419492
- Keep PRs focused on a single change
420493
- Reference issues in commit messages
421494

422-
### Development Workflow
423-
424495
Our CI/CD pipeline will automatically test your changes when you submit a PR.
425-
For significant changes, please open an issue first to discuss what you would like to change.
426496

427497
## License
428498

@@ -451,3 +521,7 @@ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
451521
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
452522
SOFTWARE.
453523
```
524+
525+
---
526+
527+
**Need help?** Open an issue or check our [troubleshooting guide](docs/troubleshooting.md).

0 commit comments

Comments
 (0)