Skip to content

Commit cc3c582

Browse files
walmir-silvawalmir-silva
committed
docs(dockerhub): add full repository overview with :latest and v1.2.0 usage examples
- Included official badges (Docker Hub pulls, GitHub, site, version, PHP, Alpine) - Added Quick Start examples using both `:latest` and `:1.2.0` tags - Documented Docker Compose usage with Redis service - Expanded configuration table with key environment variables - Added sections for Health Check, Troubleshooting, Security Notes, and Roadmap - Linked to official site and KaririCode Framework organization
1 parent 54a4e00 commit cc3c582

1 file changed

Lines changed: 234 additions & 0 deletions

File tree

‎DOCKER_HUB_OVERVIEW.md‎

Lines changed: 234 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,234 @@
1+
# KaririCode/php-api-stack
2+
3+
Production‑ready **PHP API Stack** image built on Alpine Linux with **Nginx + PHP‑FPM + Redis**. Secured, fast, and configurable via environment variables — ideal for modern APIs and web apps.
4+
5+
<p align="center">
6+
<a href="https://hub.docker.com/r/kariricode/php-api-stack"><img alt="Docker Pulls" src="https://img.shields.io/docker/pulls/kariricode/php-api-stack"></a>
7+
<a href="https://github.com/kariricode/php-api-stack"><img alt="Source" src="https://img.shields.io/badge/source-GitHub-black?logo=github"></a>
8+
<a href="https://kariricode.org/"><img alt="KaririCode" src="https://img.shields.io/badge/site-kariricode.org-0aa344"></a>
9+
<img alt="Version" src="https://img.shields.io/badge/version-1.2.0-blue">
10+
<img alt="PHP" src="https://img.shields.io/badge/PHP-8.4-777bb3?logo=php">
11+
<img alt="Alpine" src="https://img.shields.io/badge/Alpine-3.21-0d597f?logo=alpine-linux">
12+
</p>
13+
14+
---
15+
16+
## 🔗 Official Links
17+
18+
* **Repository (source)**: [https://github.com/kariricode/php-api-stack](https://github.com/kariricode/php-api-stack)
19+
* **Official site**: [https://kariricode.org/](https://kariricode.org/)
20+
* **KaririCode Framework (org)**: [https://github.com/KaririCode-Framework](https://github.com/KaririCode-Framework)
21+
22+
---
23+
24+
## ✨ Highlights
25+
26+
* **Complete Stack**: Nginx (1.27.3) + PHP‑FPM (8.4) + Redis (7.2)
27+
* **Performance**: OPcache + JIT, tuned Nginx/PHP‑FPM, socket‑based FPM
28+
* **Security‑first**: non‑root services, hardened defaults, CSP/HSTS headers
29+
* **Easy Config**: 100% via environment variables or `.env`
30+
* **Healthcheck**: `/health.php` (simple or comprehensive build)
31+
* **CI/CD‑ready**: multi‑platform builds; Makefile targets; scan/lint helpers
32+
33+
> Image tag `1.2.0` is the latest stable at publication time. Use `:latest` for automatic updates or pin to exact versions for reproducibility.
34+
35+
---
36+
37+
## 🚀 Quick Start
38+
39+
Pull and run the demo page:
40+
41+
```bash
42+
docker run -d \
43+
-p 8080:80 \
44+
--name php-api-stack-demo \
45+
kariricode/php-api-stack:latest
46+
47+
# open: http://localhost:8080
48+
```
49+
50+
Run with your application mounted:
51+
52+
```bash
53+
docker run -d \
54+
-p 8080:80 \
55+
--name my-php-app \
56+
-e APP_ENV=production \
57+
-e PHP_MEMORY_LIMIT=512M \
58+
-v $(pwd)/app:/var/www/html \
59+
kariricode/php-api-stack:latest
60+
```
61+
62+
> **Note**: Your app’s public entry point must be at `/var/www/html/public/index.php`.
63+
64+
---
65+
66+
## 🐳 Docker Compose
67+
68+
Minimal `docker-compose.yml`:
69+
70+
```yaml
71+
version: '3.9'
72+
services:
73+
app:
74+
image: kariricode/php-api-stack:latest
75+
container_name: php-api-stack
76+
ports:
77+
- "8080:80"
78+
env_file: .env
79+
volumes:
80+
- ./app:/var/www/html
81+
- ./logs:/var/log
82+
depends_on:
83+
- redis
84+
redis:
85+
image: redis:7.2-alpine
86+
command: ["redis-server", "/etc/redis/redis.conf", "--appendonly", "yes"]
87+
volumes:
88+
- redis_data:/data
89+
volumes:
90+
redis_data:
91+
```
92+
93+
Start services:
94+
95+
```bash
96+
docker compose up -d
97+
```
98+
99+
**Production tips**
100+
101+
* Mount app read‑only: `./app:/var/www/html:ro`
102+
* Add healthcheck:
103+
104+
```yaml
105+
healthcheck:
106+
test: ["CMD-SHELL", "curl -fsS http://localhost/health.php || exit 1"]
107+
interval: 30s
108+
timeout: 3s
109+
retries: 3
110+
start_period: 10s
111+
```
112+
113+
---
114+
115+
## ⚙️ Configuration (most used)
116+
117+
Set via `-e` or `.env`:
118+
119+
| Variable | Default | Description |
120+
| ---------------------------- | ----------------------- | ------------------------------------------------------- |
121+
| `APP_ENV` | `production` | `production`, `staging`, `development` |
122+
| `APP_DEBUG` | `false` | Verbose errors (use only in dev) |
123+
| `PHP_MEMORY_LIMIT` | `256M` | Per‑request memory limit |
124+
| `PHP_UPLOAD_MAX_FILESIZE` | `100M` | Upload size |
125+
| `PHP_DATE_TIMEZONE` | `UTC/America/Sao_Paulo` | Server timezone |
126+
| `PHP_FPM_PM` | `dynamic`* | FPM process manager (*auto‑forced to `static` in prod*) |
127+
| `PHP_FPM_PM_MAX_CHILDREN` | `60` | FPM workers (increase in prod) |
128+
| `NGINX_CLIENT_MAX_BODY_SIZE` | `100M` | Request body limit |
129+
| `PHP_SESSION_SAVE_HANDLER` | `redis` | `redis` or `files` |
130+
| `PHP_SESSION_SAVE_PATH` | `tcp://redis:6379` | Session DSN |
131+
| `PHP_OPCACHE_ENABLE` | `1` | Enable OPcache |
132+
| `PHP_OPCACHE_JIT` | `tracing` | JIT mode |
133+
134+
> See the **full matrix** in the GitHub repo’s `.env.example` and docs.
135+
136+
---
137+
138+
## 🏷️ Tags
139+
140+
* `1.2.0` – latest stable
141+
* `latest` – tracks the most recent stable release
142+
* `X.Y` (e.g., `1.2`) – latest patch within the minor series
143+
* `X` (e.g., `1`) – latest minor within the major series
144+
* `test` – image variant with extended health checks for testing
145+
146+
Pull a specific tag:
147+
148+
```bash
149+
docker pull kariricode/php-api-stack:latest
150+
```
151+
152+
---
153+
154+
## 🔍 Health Check
155+
156+
* **Simple**: lightweight JSON at `/health.php`
157+
* **Comprehensive**: build with `HEALTH_CHECK_TYPE=comprehensive` for deeper PHP/Redis checks.
158+
159+
Runtime verification:
160+
161+
```bash
162+
curl -fsS http://localhost:8080/health.php | jq
163+
```
164+
165+
---
166+
167+
## 🧪 Troubleshooting
168+
169+
**Container fails to start**
170+
171+
```bash
172+
docker logs <container>
173+
```
174+
175+
**502 Bad Gateway** (FPM not responding)
176+
177+
```bash
178+
docker exec <container> ps aux | grep php-fpm
179+
180+
docker exec <container> tail -f /var/log/php/fpm-error.log
181+
```
182+
183+
**Slow performance**
184+
185+
```bash
186+
docker stats <container>
187+
188+
docker exec <container> php -r "print_r(opcache_get_status()['opcache_statistics']['opcache_hit_rate']);"
189+
```
190+
191+
---
192+
193+
## 🔐 Security Notes
194+
195+
* Runs services without root privileges; hardened defaults
196+
* Enable/add headers via `SECURITY_HEADERS`, `SECURITY_CSP`, `SECURITY_HSTS_MAX_AGE`
197+
* Prefer immutable deployments in prod (`PHP_OPCACHE_VALIDATE_TIMESTAMPS=0`)
198+
199+
---
200+
201+
## 🧭 Roadmap & Contributing
202+
203+
Feature requests and PRs are welcome in the source repository:
204+
205+
* GitHub: [https://github.com/kariricode/php-api-stack](https://github.com/kariricode/php-api-stack)
206+
207+
For broader ecosystem projects, visit:
208+
209+
* KaririCode Framework: [https://github.com/KaririCode-Framework](https://github.com/KaririCode-Framework)
210+
211+
---
212+
213+
## 📝 Changelog (excerpt)
214+
215+
**1.2.0**
216+
217+
* PHP 8.4, Nginx 1.27.3, Redis 7.2
218+
* Socket‑based PHP‑FPM; OPcache + JIT optimized
219+
* `/health.php` endpoint; improved entrypoint & config processor
220+
* Extensive env‑var configuration for Nginx/PHP/Redis
221+
222+
> Full release notes are available in the GitHub repository.
223+
224+
---
225+
226+
## 📄 License
227+
228+
See `LICENSE` in the source repository.
229+
230+
---
231+
232+
## 🙌 Credits
233+
234+
Made with 💚 by **KaririCode** — [https://kariricode.org/](https://kariricode.org/)

0 commit comments

Comments
 (0)