Skip to content

Commit bf60316

Browse files
walmir-silvawalmir-silva
committed
feat(docker): implement advanced port management and health check system
- Add automatic port conflict detection with lsof and ss - Implement fix-ports command for automatic resolution - Add diagnose-ports for detailed conflict analysis - Add kill-port and port-scan utilities - Improve Memcached health check (nc instead of bash) - Update docker-compose.yml with env_file support - Remove user constraints from PHP container - Add comprehensive Redis configuration variables - Update .env.example with session handler and Redis config - Enhance Makefile targets for Docker management - Add clean-docker and check-docker-ports commands - Update documentation with troubleshooting guides - Remove deprecated install.sh script Breaking changes: - Removed install.sh (replaced by make install-dev) - Port conflict detection now fails fast with actionable messages - DEMO_MODE and HEALTH_CHECK_INSTALL disabled by default Fixes: - PHP container restart loop due to permission issues - Redis configuration errors causing crashes - Session handler conflicts - Volume mount read-only conflicts Closes #issue-number
1 parent a54ec29 commit bf60316

10 files changed

Lines changed: 1738 additions & 995 deletions

‎.docs/MAKEFILE-compose.md‎

Lines changed: 709 additions & 72 deletions
Large diffs are not rendered by default.

‎.env.example‎

Lines changed: 204 additions & 46 deletions
Original file line numberDiff line numberDiff line change
@@ -1,54 +1,212 @@
1-
# ============================================================================
1+
# ==============================================================================
22
# KaririCode DevKit - Environment Configuration
3-
# ============================================================================
4-
# IMPORTANTE: Copie este arquivo para .env e ajuste conforme necessário
5-
# cp .env.example .env
6-
# ============================================================================
7-
8-
# ============================================================================
9-
# PROJECT CONFIGURATION
10-
# ============================================================================
3+
# ==============================================================================
4+
# Professional environment variables for Docker Compose
5+
# Copy to .env and customize: cp .env.example .env
6+
# ==============================================================================
7+
8+
# ==============================================================================
9+
# APPLICATION
10+
# ==============================================================================
1111
APP_NAME=kariricode-devkit
12-
APP_ENV=development
13-
APP_DEBUG=true
12+
APP_ENV=development # development|production|testing
13+
APP_DEBUG=true # true|false
14+
APP_SECRET=change-me-in-production # Generate: openssl rand -hex 32
15+
APP_VERSION=dev
16+
SYMFONY_ENV=dev # Symfony environment
17+
18+
# ==============================================================================
19+
# DOCKER & SYSTEM
20+
# ==============================================================================
21+
# User/Group IDs (match host user for volume permissions)
22+
# Note: PHP container runs as root internally but processes run as www-data
23+
UID=1000
24+
GID=1000
25+
26+
# Timezone
27+
TZ=UTC # See: https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
28+
29+
# Volume consistency (macOS performance)
30+
VOLUME_CONSISTENCY=cached # cached|delegated|consistent
31+
32+
# ==============================================================================
33+
# PORTS
34+
# ==============================================================================
1435
APP_PORT=8089
36+
REDIS_PORT=6379
37+
MEMCACHED_PORT=11211
1538

16-
# Health Check Installation (optional)
17-
# Set to 'true' to install health check endpoint
18-
# Automatically enabled when DEMO_MODE=true
19-
DEMO_MODE=false
20-
HEALTH_CHECK_INSTALL=true
39+
# ==============================================================================
40+
# PHP SERVICE (kariricode/php-api-stack)
41+
# ==============================================================================
42+
PHP_STACK_VERSION=dev # dev|latest|1.0.0
2143

22-
# ============================================================================
23-
# PORTS - Ajuste se houver conflito com serviços existentes
24-
# Usually 6379 for Redis and 11211 for Memcached
25-
# ============================================================================
26-
REDIS_PORT=63777
27-
MEMCACHED_PORT=11210
44+
# PHP Configuration
45+
PHP_MEMORY_LIMIT=2G
46+
PHP_MAX_EXECUTION_TIME=300
47+
PHP_UPLOAD_MAX_FILESIZE=50M
48+
PHP_POST_MAX_SIZE=50M
2849

50+
# Resource Limits
51+
PHP_CPU_LIMIT=2.0 # CPU cores limit
52+
PHP_CPU_RESERVATION=0.5 # CPU cores reservation
53+
PHP_MEMORY_RESERVATION=512M # Memory reservation
2954

30-
# ============================================================================
31-
# XDEBUG - Descomente para habilitar
32-
# ============================================================================
33-
XDEBUG_MODE=off
55+
# OPcache
56+
OPCACHE_ENABLE=1
57+
OPCACHE_VALIDATE_TIMESTAMPS=1 # 0 for production, 1 for development
58+
OPCACHE_REVALIDATE_FREQ=2 # seconds
59+
60+
# PHP-FPM Configuration
61+
PHP_FPM_PM=dynamic # static|dynamic|ondemand
62+
PHP_FPM_PM_MAX_CHILDREN=50
63+
PHP_FPM_PM_START_SERVERS=5
64+
PHP_FPM_PM_MIN_SPARE_SERVERS=5
65+
PHP_FPM_PM_MAX_SPARE_SERVERS=10
66+
PHP_FPM_PM_MAX_REQUESTS=500
67+
68+
# ==============================================================================
69+
# XDEBUG
70+
# ==============================================================================
71+
XDEBUG_MODE=off # off|debug|coverage|profile
3472
XDEBUG_CLIENT_HOST=host.docker.internal
35-
COMPOSER_MEMORY_LIMIT=-1
36-
37-
# ============================================================================
38-
# REDIS
39-
# ============================================================================
40-
REDIS_MAXMEMORY=256mb
41-
REDIS_MAXMEMORY_POLICY=allkeys-lru
42-
REDIS_APPENDONLY=yes
43-
44-
# ============================================================================
45-
# MEMCACHED
46-
# ============================================================================
47-
MEMCACHED_MEMORY=256
48-
49-
# ============================================================================
50-
# RESOLUÇÃO DE CONFLITOS:
51-
# 1. Identifique a porta em uso: sudo lsof -i :6379
52-
# 2. Altere REDIS_PORT para 6380 ou outra porta disponível
53-
# 3. Execute: make down && make up
54-
# ============================================================================
73+
XDEBUG_CLIENT_PORT=9003
74+
XDEBUG_SESSION=PHPSTORM
75+
76+
# ==============================================================================
77+
# SESSION HANDLER
78+
# ==============================================================================
79+
# Session storage: files (local) or redis (distributed)
80+
SESSION_SAVE_HANDLER=files # files|redis
81+
SESSION_SAVE_PATH=/tmp # For files handler
82+
83+
# ==============================================================================
84+
# REDIS (Internal - Inside PHP Container)
85+
# ==============================================================================
86+
# Redis runs internally at 127.0.0.1:6379 inside PHP container
87+
REDIS_HOST=127.0.0.1
88+
REDIS_PORT_INTERNAL=6379 # Internal Redis port (inside container)
89+
REDIS_PASSWORD= # Empty for development
90+
REDIS_DB=0
91+
REDIS_TIMEOUT=5
92+
REDIS_LOG_FILE=/var/log/redis.log
93+
94+
# ==============================================================================
95+
# NGINX (Internal - Inside PHP Container)
96+
# ==============================================================================
97+
NGINX_WORKER_PROCESSES=auto
98+
NGINX_WORKER_CONNECTIONS=1024
99+
NGINX_CLIENT_MAX_BODY_SIZE=100M
100+
NGINX_KEEPALIVE_TIMEOUT=65
101+
102+
# ==============================================================================
103+
# COMPOSER
104+
# ==============================================================================
105+
COMPOSER_MEMORY_LIMIT=-1 # -1 for unlimited
106+
COMPOSER_HOME=/root/.composer
107+
108+
# ==============================================================================
109+
# MEMCACHED (External Service)
110+
# ==============================================================================
111+
MEMCACHED_VERSION=1.6-alpine
112+
MEMCACHED_MEMORY=256 # MB
113+
MEMCACHED_MAX_CONNECTIONS=1024
114+
MEMCACHED_THREADS=4
115+
MEMCACHED_MAX_ITEM_SIZE=5m # 5 megabytes
116+
117+
# Resource Limits
118+
MEMCACHED_CPU_LIMIT=1.0
119+
MEMCACHED_CPU_RESERVATION=0.25
120+
MEMCACHED_MEMORY_TOTAL=512M
121+
MEMCACHED_MEMORY_RESERVATION=256M
122+
123+
# Health Check
124+
MEMCACHED_HEALTHCHECK_INTERVAL=10s
125+
MEMCACHED_HEALTHCHECK_TIMEOUT=5s
126+
MEMCACHED_HEALTHCHECK_RETRIES=3
127+
MEMCACHED_HEALTHCHECK_START_PERIOD=10s
128+
129+
# ==============================================================================
130+
# FEATURES
131+
# ==============================================================================
132+
DEMO_MODE=false
133+
HEALTH_CHECK_INSTALL=false
134+
135+
# ==============================================================================
136+
# NETWORK
137+
# ==============================================================================
138+
ENABLE_IPV6=false
139+
BRIDGE_NAME=kariricode0
140+
NETWORK_MTU=1500
141+
NETWORK_SUBNET=172.20.0.0/16
142+
NETWORK_GATEWAY=172.20.0.1
143+
144+
# ==============================================================================
145+
# LOGGING
146+
# ==============================================================================
147+
LOG_MAX_SIZE=10m # Maximum size before rotation
148+
LOG_MAX_FILE=3 # Number of log files to keep
149+
LOG_LEVEL=info # debug|info|notice|warning|error
150+
151+
# ==============================================================================
152+
# HEALTH CHECKS
153+
# ==============================================================================
154+
HEALTHCHECK_INTERVAL=30s
155+
HEALTHCHECK_TIMEOUT=10s
156+
HEALTHCHECK_RETRIES=3
157+
HEALTHCHECK_START_PERIOD=40s
158+
159+
# ==============================================================================
160+
# TEMPORARY FILESYSTEM
161+
# ==============================================================================
162+
TMPFS_SIZE=100M # Size of /tmp tmpfs
163+
164+
# ==============================================================================
165+
# TROUBLESHOOTING
166+
# ==============================================================================
167+
# Port conflicts?
168+
# - Change APP_PORT, REDIS_PORT, or MEMCACHED_PORT
169+
# - Run: make diagnose-ports
170+
# - Run: make fix-ports
171+
#
172+
# Performance issues on macOS?
173+
# - Try VOLUME_CONSISTENCY=delegated
174+
#
175+
# Permission errors?
176+
# - Note: Container runs as root, but PHP-FPM/Nginx run as www-data
177+
# - Check file ownership: ls -la
178+
#
179+
# Memory issues?
180+
# - Adjust PHP_MEMORY_LIMIT and resource limits
181+
#
182+
# Session/Redis errors?
183+
# - Use SESSION_SAVE_HANDLER=files for development
184+
# - Use SESSION_SAVE_HANDLER=redis for distributed sessions
185+
#
186+
# PHP-FPM crashes?
187+
# - Check logs: make logs SERVICE=php
188+
# - Verify config: docker compose config
189+
#
190+
# Run diagnostics:
191+
# - make env-check # Validate .env file
192+
# - make diagnose-ports # Check port conflicts
193+
# - make docker-info # Docker environment info
194+
# - make status # Service status
195+
# - make health # Health checks
196+
# ==============================================================================
197+
198+
# ==============================================================================
199+
# PRODUCTION NOTES
200+
# ==============================================================================
201+
# For production deployment:
202+
# 1. Change APP_ENV=production
203+
# 2. Set APP_DEBUG=false
204+
# 3. Generate strong APP_SECRET: openssl rand -hex 32
205+
# 4. Set XDEBUG_MODE=off
206+
# 5. Set OPCACHE_VALIDATE_TIMESTAMPS=0
207+
# 6. Use SESSION_SAVE_HANDLER=redis with password
208+
# 7. Set proper resource limits
209+
# 8. Enable HTTPS/SSL termination
210+
# 9. Use managed Redis/Memcached services
211+
# 10. Implement proper backup strategy
212+
# ==============================================================================

‎.make/core/Makefile.functions.mk‎

Lines changed: 13 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -7,28 +7,28 @@
77
# --- Validação de Parâmetros ---
88
define validate_param
99
@if [ -z "$($(1))" ]; then \
10-
echo "$(RED)✗ $(1) required. Usage: $(2)$(RESET)"; \
10+
echo -e "$(RED)✗ $(1) required. Usage: $(2)$(RESET)"; \
1111
exit 1; \
1212
fi
1313
endef
1414

1515
# --- Execução Docker Genérica ---
1616
define docker_exec
17-
@echo "$(BLUE)→ Running $(1) in Docker...$(RESET)"
17+
@echo -e "$(BLUE)→ Running $(1) in Docker...$(RESET)"
1818
@$(DOCKER_RUN) $(DOCKER_IMAGE) $(2)
19-
@echo "$(GREEN)✓ $(1) complete$(RESET)"
19+
@echo -e "$(GREEN)✓ $(1) complete$(RESET)"
2020
endef
2121

2222
define docker_exec_make
23-
@echo "$(BLUE)→ Running make $(1) in Docker...$(RESET)"
23+
@echo -e "$(BLUE)→ Running make $(1) in Docker...$(RESET)"
2424
@$(DOCKER_RUN) $(DOCKER_IMAGE) make $(1)
25-
@echo "$(GREEN)✓ Docker make $(1) complete$(RESET)"
25+
@echo -e "$(GREEN)✓ Docker make $(1) complete$(RESET)"
2626
endef
2727

2828
# --- Verificação de Arquivo ---
2929
define check_file
3030
@test -f $(1) || (echo "$(RED)✗ $(2) not found$(RESET)" && exit 1)
31-
endef
31+
endef
3232

3333
# --- Criação de Diretório ---
3434
define ensure_dir
@@ -37,30 +37,30 @@ endef
3737

3838
# --- Header de Pipeline ---
3939
define pipeline_header
40-
@echo "$(BOLD)$(CYAN)╔════════════════════════════════════════════════════════╗$(RESET)"
41-
@echo "$(BOLD)$(CYAN)║ $(1)$(RESET)"
42-
@echo "$(BOLD)$(CYAN)╚════════════════════════════════════════════════════════╝$(RESET)"
40+
@echo -e "$(BOLD)$(CYAN)╔════════════════════════════════════════════════════════╗$(RESET)"
41+
@echo -e "$(BOLD)$(CYAN)║ $(1)$(RESET)"
42+
@echo -e "$(BOLD)$(CYAN)╚════════════════════════════════════════════════════════╝$(RESET)"
4343
@echo ""
4444
endef
4545

4646
# --- Verificação de Branch Git ---
4747
define check_git_branch
4848
@CURRENT_BRANCH=$$(git rev-parse --abbrev-ref HEAD); \
4949
if [ "$$CURRENT_BRANCH" != "$(1)" ]; then \
50-
echo "$(RED)✗ This action requires branch '$(1)' (current: $$CURRENT_BRANCH)$(RESET)"; \
50+
echo -e "$(RED)✗ This action requires branch '$(1)' (current: $$CURRENT_BRANCH)$(RESET)"; \
5151
exit 1; \
5252
fi
5353
endef
5454

5555
# --- Verificação de Versão PHP ---
5656
define check_php_version
57-
@echo "$(BLUE)→ Checking PHP version...$(RESET)"; \
57+
@echo -e "$(BLUE)→ Checking PHP version...$(RESET)"; \
5858
CURRENT_VERSION="$(PHP_VERSION)"; \
5959
MIN_VERSION="$(PHP_MIN_VERSION)"; \
6060
LOWEST=$$(printf '%s\n%s' "$$MIN_VERSION" "$$CURRENT_VERSION" | sort -V | head -n1); \
6161
if [ "$$LOWEST" != "$$MIN_VERSION" ]; then \
62-
echo "$(RED)✗ PHP $$MIN_VERSION+ required, found $$CURRENT_VERSION$(RESET)"; \
62+
echo -e "$(RED)✗ PHP $$MIN_VERSION+ required, found $$CURRENT_VERSION$(RESET)"; \
6363
exit 1; \
6464
fi; \
65-
echo "$(GREEN)✓ PHP version $$CURRENT_VERSION OK (>= $$MIN_VERSION)$(RESET)"
65+
echo -e "$(GREEN)✓ PHP version $$CURRENT_VERSION OK (>= $$MIN_VERSION)$(RESET)"
6666
endef

0 commit comments

Comments
 (0)