diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json new file mode 100644 index 0000000..e7d6a45 --- /dev/null +++ b/.devcontainer/devcontainer.json @@ -0,0 +1,40 @@ +{ + "name": "alpine-php dev", + + // Use the latest stable dev image. Change to 8.1-dev, 8.2-dev, or 8.4-dev as needed. + "image": "jorge07/alpine-php:8.3-dev", + + // Mount the workspace at /app (matches the container's WORKDIR) + "workspaceFolder": "/app", + "workspaceMount": "source=${localWorkspaceFolder},target=/app,type=bind,consistency=cached", + + // Forward Xdebug port and SSH port + "forwardPorts": [9003, 22], + "portsAttributes": { + "9003": { "label": "Xdebug", "onAutoForward": "silent" }, + "22": { "label": "SSH (IDE integration)", "onAutoForward": "silent" } + }, + + // VS Code extensions for PHP development + "customizations": { + "vscode": { + "extensions": [ + "xdebug.php-debug", + "bmewburn.vscode-intelephense-client", + "junstyle.php-cs-fixer", + "neilbrayfield.php-docblocker" + ], + "settings": { + "php.validate.executablePath": "/usr/bin/php", + "intelephense.environment.phpVersion": "8.3", + "php.debug.ideKey": "VSCODE" + } + } + }, + + // Remote user — root matches the dev image's default + "remoteUser": "root", + + // Override CMD to keep the container running with supervisor + "overrideCommand": false +} diff --git a/8.1/Dockerfile b/8.1/Dockerfile index d246444..0870a46 100644 --- a/8.1/Dockerfile +++ b/8.1/Dockerfile @@ -83,7 +83,6 @@ RUN apk add -U --no-cache --repository https://dl-cdn.alpinelinux.org/alpine/v3. make \ zip \ && rm -rf /var/cache/apk/* \ - && sed -i s/#PermitRootLogin.*/PermitRootLogin\ yes/ /etc/ssh/sshd_config \ && echo "${USER}:${PASSWORD}" | chpasswd \ && ssh-keygen -A \ && curl -sS https://getcomposer.org/installer | php -- --install-dir=/usr/bin --filename=composer --version=${COMPOSER_VERSION} diff --git a/8.1/devfs/etc/ssh/sshd_config b/8.1/devfs/etc/ssh/sshd_config new file mode 100644 index 0000000..01fec89 --- /dev/null +++ b/8.1/devfs/etc/ssh/sshd_config @@ -0,0 +1,27 @@ +# OpenSSH configuration for alpine-php dev image +# Intended for local development only — do not use in production. + +Port 22 +AddressFamily inet +Protocol 2 + +# Authentication +PermitRootLogin yes +PasswordAuthentication yes +PubkeyAuthentication yes +AuthorizedKeysFile .ssh/authorized_keys +PermitEmptyPasswords no +IgnoreRhosts yes +HostbasedAuthentication no + +# Keep connections alive (important for IDE SSH sessions) +TCPKeepAlive yes +ClientAliveInterval 60 +ClientAliveCountMax 3 + +# Forwarding (required for IDE remote debugging port forwarding) +AllowTcpForwarding yes +GatewayPorts yes + +# SFTP +Subsystem sftp /usr/lib/ssh/sftp-server diff --git a/8.2/Dockerfile b/8.2/Dockerfile index 0f07a8d..8c44bac 100644 --- a/8.2/Dockerfile +++ b/8.2/Dockerfile @@ -88,7 +88,6 @@ RUN apk add -U --no-cache --repository https://dl-cdn.alpinelinux.org/alpine/v3. # Delete APK cache. && rm -rf /var/cache/apk/* \ # Create ssh user for dev. - && sed -i s/#PermitRootLogin.*/PermitRootLogin\ yes/ /etc/ssh/sshd_config \ && echo "${USER}:${PASSWORD}" | chpasswd \ && ssh-keygen -A \ # Download composer. diff --git a/8.2/devfs/etc/ssh/sshd_config b/8.2/devfs/etc/ssh/sshd_config new file mode 100644 index 0000000..01fec89 --- /dev/null +++ b/8.2/devfs/etc/ssh/sshd_config @@ -0,0 +1,27 @@ +# OpenSSH configuration for alpine-php dev image +# Intended for local development only — do not use in production. + +Port 22 +AddressFamily inet +Protocol 2 + +# Authentication +PermitRootLogin yes +PasswordAuthentication yes +PubkeyAuthentication yes +AuthorizedKeysFile .ssh/authorized_keys +PermitEmptyPasswords no +IgnoreRhosts yes +HostbasedAuthentication no + +# Keep connections alive (important for IDE SSH sessions) +TCPKeepAlive yes +ClientAliveInterval 60 +ClientAliveCountMax 3 + +# Forwarding (required for IDE remote debugging port forwarding) +AllowTcpForwarding yes +GatewayPorts yes + +# SFTP +Subsystem sftp /usr/lib/ssh/sftp-server diff --git a/8.3/Dockerfile b/8.3/Dockerfile index d117dc5..b173999 100644 --- a/8.3/Dockerfile +++ b/8.3/Dockerfile @@ -83,7 +83,6 @@ RUN apk add -U --no-cache --repository https://dl-cdn.alpinelinux.org/alpine/v3. make \ zip \ && rm -rf /var/cache/apk/* \ - && sed -i s/#PermitRootLogin.*/PermitRootLogin\ yes/ /etc/ssh/sshd_config \ && echo "${USER}:${PASSWORD}" | chpasswd \ && ssh-keygen -A \ && curl -sS https://getcomposer.org/installer | php -- --install-dir=/usr/bin --filename=composer --version=${COMPOSER_VERSION} diff --git a/8.3/devfs/etc/ssh/sshd_config b/8.3/devfs/etc/ssh/sshd_config new file mode 100644 index 0000000..01fec89 --- /dev/null +++ b/8.3/devfs/etc/ssh/sshd_config @@ -0,0 +1,27 @@ +# OpenSSH configuration for alpine-php dev image +# Intended for local development only — do not use in production. + +Port 22 +AddressFamily inet +Protocol 2 + +# Authentication +PermitRootLogin yes +PasswordAuthentication yes +PubkeyAuthentication yes +AuthorizedKeysFile .ssh/authorized_keys +PermitEmptyPasswords no +IgnoreRhosts yes +HostbasedAuthentication no + +# Keep connections alive (important for IDE SSH sessions) +TCPKeepAlive yes +ClientAliveInterval 60 +ClientAliveCountMax 3 + +# Forwarding (required for IDE remote debugging port forwarding) +AllowTcpForwarding yes +GatewayPorts yes + +# SFTP +Subsystem sftp /usr/lib/ssh/sftp-server diff --git a/8.4/Dockerfile b/8.4/Dockerfile index 81327ac..593ff4f 100644 --- a/8.4/Dockerfile +++ b/8.4/Dockerfile @@ -85,7 +85,6 @@ RUN apk add -U --no-cache --repository https://dl-cdn.alpinelinux.org/alpine/edg make \ zip \ && rm -rf /var/cache/apk/* \ - && sed -i s/#PermitRootLogin.*/PermitRootLogin\ yes/ /etc/ssh/sshd_config \ && echo "${USER}:${PASSWORD}" | chpasswd \ && ssh-keygen -A \ && curl -sS https://getcomposer.org/installer | php -- --install-dir=/usr/bin --filename=composer --version=${COMPOSER_VERSION} diff --git a/8.4/devfs/etc/ssh/sshd_config b/8.4/devfs/etc/ssh/sshd_config new file mode 100644 index 0000000..01fec89 --- /dev/null +++ b/8.4/devfs/etc/ssh/sshd_config @@ -0,0 +1,27 @@ +# OpenSSH configuration for alpine-php dev image +# Intended for local development only — do not use in production. + +Port 22 +AddressFamily inet +Protocol 2 + +# Authentication +PermitRootLogin yes +PasswordAuthentication yes +PubkeyAuthentication yes +AuthorizedKeysFile .ssh/authorized_keys +PermitEmptyPasswords no +IgnoreRhosts yes +HostbasedAuthentication no + +# Keep connections alive (important for IDE SSH sessions) +TCPKeepAlive yes +ClientAliveInterval 60 +ClientAliveCountMax 3 + +# Forwarding (required for IDE remote debugging port forwarding) +AllowTcpForwarding yes +GatewayPorts yes + +# SFTP +Subsystem sftp /usr/lib/ssh/sftp-server diff --git a/README.md b/README.md index 71b18dc..8d8a0b3 100644 --- a/README.md +++ b/README.md @@ -1,49 +1,150 @@ -# Alpine PHP +# Alpine PHP [![All Contributors](https://img.shields.io/badge/all_contributors-4-orange.svg?style=flat-square)](#contributors-) -Repository of https://hub.docker.com/r/jorge07/alpine-php +[![PR checks](https://github.com/jorge07/alpine-php/actions/workflows/pr.yaml/badge.svg?branch=master)](https://github.com/jorge07/alpine-php/actions/workflows/pr.yaml) +![Docker Pulls](https://img.shields.io/docker/pulls/jorge07/alpine-php.svg?style=flat-square) +[![Docker Hub](https://img.shields.io/badge/Docker%20Hub-jorge07%2Falpine--php-blue)](https://hub.docker.com/r/jorge07/alpine-php) +[![GHCR](https://img.shields.io/badge/GHCR-ghcr.io%2Fjorge07%2Falpine--php-blue)](https://ghcr.io/jorge07/alpine-php) -[![PR checks](https://github.com/jorge07/alpine-php/actions/workflows/pr.yaml/badge.svg?branch=master)](https://github.com/jorge07/alpine-php/actions/workflows/pr.yaml) ![Docker Pulls](https://img.shields.io/docker/pulls/jorge07/alpine-php.svg?style=flat-square) +Lightweight PHP-FPM Docker images based on Alpine Linux — under 40MB. -Small PHP Docker images based on Alpine [<40MB]. +Kept up to date with [active PHP releases](https://www.php.net/supported-versions.php). Weekly automated rebuilds pick up Alpine security patches. -Up to date with [active releases](https://www.php.net/supported-versions.php) and a place for older unmaintained images. +--- -## Documentation +## Images -[Read about Documentation and see some examples here](https://github.com/jorge07/alpine-php/tree/master/doc/README.md) +| Tag | PHP | Alpine | Arch | +|---|---|---|---| +| `8.4` / `8.4-dev` | 8.4.x | edge | amd64, arm64, arm/v7, arm/v8 | +| `8.3` / `8.3-dev` | 8.3.x | 3.20 | amd64, arm64, arm/v7, arm/v8 | +| `8.2` / `8.2-dev` | 8.2.x | 3.21 | amd64, arm64, arm/v7, arm/v8 | +| `8.1` / `8.1-dev` | 8.1.x | 3.19 | amd64, arm64, arm/v7, arm/v8 | -## Images +Available on [Docker Hub](https://hub.docker.com/r/jorge07/alpine-php) and [GHCR](https://ghcr.io/jorge07/alpine-php). + +### Deprecated (available but unmaintained) + +`8.0` · `7.4` · `7.3` · `7.2` · `7.1` · `5.6` + +--- + +## Quick start + +```sh +# Production image — PHP-FPM on port 9000 +docker run -d --name php -p 9000:9000 -v $PWD:/app jorge07/alpine-php:8.3 + +# Dev image — PHP-FPM + Xdebug + Composer + SSH +docker run -d --name php-dev \ + -p 2244:22 \ + -p 9003:9003 \ + -v $PWD:/app \ + jorge07/alpine-php:8.3-dev +``` + +--- + +## Dev Container (VS Code) + +The repo ships a `.devcontainer/devcontainer.json` for use with [VS Code Dev Containers](https://code.visualstudio.com/docs/devcontainers/containers) or [GitHub Codespaces](https://github.com/features/codespaces). + +### Get started in 3 steps + +1. Install the [Dev Containers extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) in VS Code +2. Open your project folder +3. Click **Reopen in Container** (or run `Dev Containers: Reopen in Container` from the command palette) + +VS Code will pull `jorge07/alpine-php:8.3-dev`, mount your project at `/app`, and pre-install: +- [PHP Debug](https://marketplace.visualstudio.com/items?itemName=xdebug.php-debug) (Xdebug 3 integration) +- [Intelephense](https://marketplace.visualstudio.com/items?itemName=bmewburn.vscode-intelephense-client) (PHP language server) + +### Xdebug launch config + +Add `.vscode/launch.json` to your project: + +```json +{ + "version": "0.2.0", + "configurations": [ + { + "name": "Listen for Xdebug", + "type": "php", + "request": "launch", + "port": 9003, + "pathMappings": { + "/app": "${workspaceFolder}" + } + } + ] +} +``` + +Set breakpoints, press **F5**, and trigger a request. For CLI scripts: + +```sh +docker exec php-dev sh -c "XDEBUG_SESSION=1 php /app/script.php" +``` + +--- + +## Dev images — manual setup + +Dev images add Xdebug, Composer, SSH, and Supervisor on top of the production image. + +### PHPStorm (SSH remote interpreter) -- [8.3](https://github.com/jorge07/alpine-php/blob/master/8.3/Dockerfile) -- [8.2](https://github.com/jorge07/alpine-php/blob/master/8.2/Dockerfile) -- [8.1](https://github.com/jorge07/alpine-php/blob/master/8.1/Dockerfile) +```sh +docker run -d --name php-dev -p 2244:22 -p 9003:9003 -v $PWD:/app jorge07/alpine-php:8.3-dev +``` + +**Languages & Frameworks → PHP → Add → SSH Credentials** -# Deprecated but available images +| Field | Value | +|---|---| +| Host | `localhost` | +| Port | `2244` | +| User | `root` | +| Password | `root` | +| PHP executable | `/usr/bin/php` | -- [8.0](https://github.com/jorge07/alpine-php/blob/master/8.0/Dockerfile) -- [7.4](https://github.com/jorge07/alpine-php/blob/master/7.4/Dockerfile) -- [7.3](https://github.com/jorge07/alpine-php/blob/master/7.3/Dockerfile) -- [7.2](https://github.com/jorge07/alpine-php/blob/master/7.2/Dockerfile) -- [7.1](https://github.com/jorge07/alpine-php/blob/master/7.1/Dockerfile) -- [5.6](https://github.com/jorge07/alpine-php/blob/master/5.6/Dockerfile) +**Path mappings:** `` → `/app` -## Usage: +**Debug → Xdebug port:** `9003` + +### Custom SSH credentials ```sh -docker run -d --name dev -p 2323:22 -v $PWD:/app jorge07/alpine-php:8.3-dev +docker build \ + --build-arg USER=myuser \ + --build-arg PASSWORD=mypass \ + --target dev -t myapp:dev \ + -f 8.3/Dockerfile 8.3/ ``` -> To make xdebug config easier for all environments there's a custom ENVVAR you can define: `XDEBUG_CLIENT_HOST`. -> Example: XDEBUG_CLIENT_HOST=docker.for.mac for OSX, XDEBUG_CLIENT_HOST=docker.for.windows for Windows users and Linux users and Remote interpreters by SSH can leave it empty. +### Xdebug 3 — key settings + +| Setting | Value | +|---|---| +| Port | `9003` (changed from 9000 in Xdebug 2) | +| Trigger | `XDEBUG_SESSION=1` env var | +| Mode | `debug` (set in image, trigger-based) | + +> **Migrating from Xdebug 2?** See the [IDE integration guide](doc/IDE.md) for a full comparison table and PHPStorm setup walkthrough. + +--- + +## PHP Extensions + +All images include: -> SSH is only for IDE integration to use container as remote interpreter +`bcmath` · `ctype` · `curl` · `dom` · `exif` · `fileinfo` · `gd` · `iconv` · `intl` · `mbstring` · `opcache` · `openssl` · `pcntl` · `pdo` · `pdo_mysql` · `pdo_pgsql` · `phar` · `session` · `simplexml` · `sodium` · `tokenizer` · `xml` · `xmlreader` · `xsl` · `zip` · `zlib` · `apcu` -## Dev Dockerfiles +Dev images additionally include: `xdebug` · `pear` -Dev images extend the standard ones and add some tools for development and CI like, composer, xdebug, etc... +--- ## Contributors ✨ diff --git a/doc/IDE.md b/doc/IDE.md index b42cda1..4cc3e9d 100644 --- a/doc/IDE.md +++ b/doc/IDE.md @@ -1,64 +1,130 @@ -# IDE integration +# IDE Integration -### Up container +## Start the dev container -Run this in your project root path: - - docker run -itd --name php7 -v $PWD:/app -p 2244:22 jorge07/alpine-php:7.4-dev +Run this in your project root: -- `-v $PWD:/app` will create a volume to share the host folder with the container -- `-p 2244:22` will export the 22 container port to the 2244 host machine. This will allow us to connect the IDE via SSH. +```sh +docker run -itd --name php-dev \ + -v $PWD:/app \ + -p 2244:22 \ + -p 9003:9003 \ + jorge07/alpine-php:8.3-dev +``` -### PHPSTORM +- `-v $PWD:/app` — mounts your project at `/app` inside the container +- `-p 2244:22` — SSH port for remote interpreter +- `-p 9003:9003` — Xdebug 3 port (default, replaces 9000 from Xdebug 2) -- Languages & Frameworks > PHP > Add > Remote... - - SSH Credentials - - HOST - - Docker-machine: 192.168.99.100 ([Recommended](https://github.com/adlogix/docker-machine-nfs)) - - Linux or Docker4{MAc|Windows}: localhost - - port: 2244 (or the one you choose on the docker run command) - - user: root - - pass: root - - Executable: /usr/bin/php - - Path mappings: - - -> /app - -**Remote Interpreter** -![Remote](https://raw.githubusercontent.com/jorge07/alpine-php/master/doc/images/remote-interpreter.png) +**Default credentials:** `root` / `root` -**Mapping** -![Remote](https://raw.githubusercontent.com/jorge07/alpine-php/master/doc/images/mapping.png) +--- -Now your breakpoints should work. +## VS Code (Dev Containers) -You can also use the oficial PHPStrom documentation for [remote connexion via SSH Credentials](https://confluence.jetbrains.com/display/PhpStorm/Working+with+Remote+PHP+Interpreters+in+PhpStorm) they will explain it better than me. +The repo ships a `.devcontainer/devcontainer.json`. Open the project in VS Code and click **Reopen in Container** — it will use `jorge07/alpine-php:8.3-dev` and pre-install the PHP Debug and Intelephense extensions. -### Steps in detail +### Xdebug launch config -**Credentials** +Add to `.vscode/launch.json`: -Use the ARG variables to change the *USER* and *PASSWORD* for ssh and *COMPOSER_VERSION* to select an specific version on the build. +```json +{ + "version": "0.2.0", + "configurations": [ + { + "name": "Listen for Xdebug", + "type": "php", + "request": "launch", + "port": 9003, + "pathMappings": { + "/app": "${workspaceFolder}" + } + }, + { + "name": "Debug CLI script", + "type": "php", + "request": "launch", + "port": 9003, + "pathMappings": { + "/app": "${workspaceFolder}" + }, + "runtimeExecutable": "php", + "program": "${file}" + } + ] +} +``` -**Default Credentials Values:** +Set the `XDEBUG_SESSION` env var or use the browser extension to trigger a debug session. For CLI scripts: -- user: root -- pass: root +```sh +docker exec php-dev sh -c "XDEBUG_SESSION=1 php /app/bin/console something" +``` -**Binary path** +--- -- /usr/bin/php +## PHPStorm -**Xdebug.so path** +### Remote interpreter via SSH -- /usr/lib/php{7}/modules/xdebug.so +**Languages & Frameworks → PHP → Add → SSH Credentials** -**Server mappings** +| Field | Value | +|---|---| +| Host | `localhost` (or your Docker host IP) | +| Port | `2244` | +| User | `root` | +| Password | `root` | +| PHP executable | `/usr/bin/php` | -Add your **Path mapping** from your workspace folder to the `/app` folder inside the container. +**Path mappings:** `` → `/app` -**Xdebug** +### Xdebug 3 configuration -If you want to [debug php script commands remotely](https://confluence.jetbrains.com/display/PhpStorm/Debugging+PHP+CLI+scripts+with+PhpStorm) (I.E: php bin/console something) with Your IDE (PHPStorm in this case): - - - Set the PHP_IDE_CONFIG environment variable with **serverName=SomeName** - - where **SomeName** is the name of the server configured in *Settings / Preferences | Languages & Frameworks | PHP | Servers* in the PHPStorm IDE. +**Languages & Frameworks → PHP → Debug** + +| Setting | Value | +|---|---| +| Debug port | `9003` | +| Can accept external connections | ✅ | + +**Run → Edit Configurations → PHP Remote Debug** + +| Setting | Value | +|---|---| +| Server | (the SSH server you configured above) | +| IDE key | `PHPSTORM` | + +For CLI debugging, set the env var before running: + +```sh +docker exec php-dev sh -c "PHP_IDE_CONFIG='serverName=MyServer' XDEBUG_SESSION=PHPSTORM php /app/script.php" +``` + +### Key differences from Xdebug 2 + +| | Xdebug 2 | Xdebug 3 | +|---|---|---| +| Default port | `9000` | `9003` | +| Trigger env var | `XDEBUG_REMOTE_ENABLE=1` | `XDEBUG_SESSION=1` | +| ini key (enable) | `xdebug.remote_enable=1` | `xdebug.mode=debug` | +| ini key (host) | `xdebug.remote_host` | `xdebug.client_host` | +| ini key (port) | `xdebug.remote_port` | `xdebug.client_port` | + +The images ship with `xdebug.mode=debug` and `xdebug.start_with_request=trigger` — Xdebug only activates when a session is triggered, not on every request. + +--- + +## SSH credentials (custom) + +Pass build args to change the default user/password: + +```sh +docker build \ + --build-arg USER=myuser \ + --build-arg PASSWORD=mypassword \ + -t myapp:dev \ + --target dev \ + -f 8.3/Dockerfile 8.3/ +```