dockette · ohmyfelix · Jun 5, 2026 · Jun 5, 2026
diff --git a/.github/workflows/docker.yml b/.github/workflows/docker.yml
@@ -0,0 +1,59 @@
+name: "Docker"
+
+on:
+  workflow_dispatch:
+
+  push:
+    branches: ["master"]
+
+  pull_request:
+
+  schedule:
+    - cron: "0 8 * * 1"
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    name: "Test"
+    runs-on: "ubuntu-latest"
+
+    steps:
+      - name: "Checkout"
+        uses: actions/checkout@v4
+
+      - name: "Validate compose and scripts"
+        run: "make test"
+
+  build:
+    name: "Build"
+    needs: ["test"]
+    runs-on: "ubuntu-latest"
+
+    steps:
+      - name: "Checkout"
+        uses: actions/checkout@v4
+
+      - name: "Set up Docker Buildx"
+        uses: docker/setup-buildx-action@v3
+
+      - name: "Build selected legacy images"
+        run: "make build"
+
+  docs:
+    name: "Docs"
+    runs-on: "ubuntu-latest"
+    needs: ["build"]
+    if: github.ref == 'refs/heads/master'
+
+    steps:
+      - name: "Checkout"
+        uses: actions/checkout@v4
+
+      - name: "Update Docker Hub description"
+        uses: peter-evans/dockerhub-description@v5
+        with:
+          username: ${{ secrets.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_TOKEN }}
+          repository: "dockette/devstack"
diff --git a/AGENTS.md b/AGENTS.md
@@ -0,0 +1,32 @@
+# AGENTS.md
+
+## Project
+
+Dockette DevStack is a legacy Docker Compose LAMP development stack. It combines Apache, PHP FPM, Node.js, Adminer, MariaDB, optional PostgreSQL, and user data helper containers through `docker-compose.yml` and the `devstack` control script.
+
+## Images
+
+- Docker Hub repository: `dockette/devstack`.
+- Local image contexts live in `apache/`, `nodejs/`, and `php/*`.
+- The default compose file references tags such as `dockette/devstack:apache`, `dockette/devstack:php72-fpm`, and `dockette/devstack:nodejs`.
+- Base images and runtime versions are legacy; avoid broad upgrades unless explicitly requested.
+
+## Commands
+
+- `make build` builds selected representative local images: Apache, PHP 7.2 FPM, and Node.js.
+- `make test` validates `docker-compose.yml` with `docker compose config` and checks `devstack` shell syntax.
+- `make run` starts the compose stack with `docker compose up -d --remove-orphans`.
+
+## Testing Notes
+
+- Use `make -n build test run` to inspect target wiring without requiring Docker.
+- Compose validation needs `SSH_AUTH_SOCK`; the Makefile provides a safe placeholder for non-interactive checks.
+- Full stack startup binds common host ports (`80`, `443`, `3306`, `8000`) and should be treated as a local/manual check.
+
+## Guidelines
+
+- Preserve the legacy compose UX and documented service names unless the task explicitly asks for migration.
+- Prefer small CI checks: compose config, shell syntax, and representative image builds.
+- Place `.PHONY` directly above every Makefile target.
+- Keep README badges in the Dockette `copybara` style and do not add Slack or Gitter badges.
+- Keep the Maintenance section aligned with active Dockette Docker image repositories.
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -0,0 +1 @@
+@AGENTS.md
diff --git a/Makefile b/Makefile
@@ -0,0 +1,20 @@
+DOCKER_IMAGE=dockette/devstack
+DOCKER_PLATFORMS?=linux/amd64
+COMPOSE?=docker compose
+COMPOSE_FILE?=docker-compose.yml
+COMPOSE_SSH_AUTH_SOCK?=/tmp/devstack-ssh-agent
+
+.PHONY: build
+build:
+	docker buildx build --platform ${DOCKER_PLATFORMS} -t ${DOCKER_IMAGE}:apache apache
+	docker buildx build --platform ${DOCKER_PLATFORMS} -t ${DOCKER_IMAGE}:php72-fpm php/7.2-fpm
+	docker buildx build --platform ${DOCKER_PLATFORMS} -t ${DOCKER_IMAGE}:nodejs nodejs
+
+.PHONY: test
+test:
+	SSH_AUTH_SOCK=${COMPOSE_SSH_AUTH_SOCK} ${COMPOSE} -f ${COMPOSE_FILE} config
+	bash -n devstack
+
+.PHONY: run
+run:
+	SSH_AUTH_SOCK=$${SSH_AUTH_SOCK:-${COMPOSE_SSH_AUTH_SOCK}} ${COMPOSE} -f ${COMPOSE_FILE} up -d --remove-orphans
diff --git a/README.md b/README.md
@@ -1,23 +1,26 @@
-# DevStack
+<h1 align=center>Dockette / DevStack</h1>
 
-Great LAMP devstack based on **Docker** & **Docker Compose** for your home programming.
-
-[![Docker Stars](https://img.shields.io/docker/stars/dockette/devstack.svg?style=flat)](https://hub.docker.com/r/dockette/devstack/)
-[![Docker Pulls](https://img.shields.io/docker/pulls/dockette/devstack.svg?style=flat)](https://hub.docker.com/r/dockette/devstack/)
+<p align=center>
+   <a href="https://github.com/dockette/devstack/actions"><img src="https://github.com/dockette/devstack/actions/workflows/docker.yml/badge.svg" alt="GitHub Actions"></a>
+   <a href="https://hub.docker.com/r/dockette/devstack"><img src="https://img.shields.io/docker/pulls/dockette/devstack.svg" alt="Docker Hub pulls"></a>
+   <a href="https://github.com/sponsors/f3l1x"><img src="https://img.shields.io/badge/sponsor-GitHub%20Sponsors-ea4aaa" alt="GitHub Sponsors"></a>
+   <a href="https://github.com/orgs/dockette/discussions"><img src="https://img.shields.io/badge/support-discussions-6f42c1" alt="Support/Discussions"></a>
+</p>
 
-## Discussion / Help
-
-[![Join the chat](https://img.shields.io/gitter/room/dockette/dockette.svg?style=flat-square)](https://gitter.im/dockette/dockette?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
+Great LAMP devstack based on **Docker** & **Docker Compose** for your home programming.
 
 ## LAMP
 
 - Apache 2.4.x
 - PHP 7.2.x + Composer + PHPMailer
+- MariaDB 10.1
+- Adminer 4.3.x
+
+Optional services are prepared in `docker-compose.yml`, but are commented out until you enable them:
+
 - PHP 5.6.x + Composer + PHPMailer
 - NodeJS 8.x + NPM 5.x
-- MariaDB 10.1
 - PostgreSQL 9.6
-- Adminer 4.3.x
 
 ## Install
 
@@ -35,6 +38,9 @@ Great LAMP devstack based on **Docker** & **Docker Compose** for your home progr
 	- `DEVSTACK_DOCKER=~/.devstack/docker-compose.yml` (docker compose file)
 	- `DEVSTACK_PREFIX=devstack` (container's prefix)
 	- `DEVSTACK_USER=dfx` (attached user in container) [you can leave it]
+	- `DEVSTACK_COMPOSE` (optional compose command override; defaults to `docker compose` with `docker-compose` fallback)
+
+    The compose file mounts your SSH agent into containers, so `SSH_AUTH_SOCK` should point to a running SSH agent socket. If you do not use agent forwarding, the `devstack` script uses `/tmp/devstack-ssh-agent` as a fallback; override it with `DEVSTACK_SSH_AUTH_SOCK` if needed.
 
 3. Make `devstack` managing script executable.
 
@@ -52,19 +58,19 @@ Great LAMP devstack based on **Docker** & **Docker Compose** for your home progr
 
 ### Ports
 
-| Container     | Ports    | IP           |
-|---------------|----------|--------------|
-| Apache        | 80 / 443 | 172.10.10.5  |
-| PHP 7.2 + FPM |          | 172.10.10.10 |
-| PHP 5.6 + FPM |          | 172.10.10.11 |
-| NodeJS        |          | 172.10.10.12 |
-| Adminer       | 8000     | 172.10.10.13 |
-| MariaDB       | 3306     | 172.10.10.20 |
-| PostgreSQL    | 5432     | 172.10.10.21 |
+| Container                | Ports    | IP           |
+|--------------------------|----------|--------------|
+| Apache                   | 80 / 443 | 172.10.10.5  |
+| PHP 7.2 + FPM            |          | 172.10.10.10 |
+| PHP 5.6 + FPM (optional) |          | 172.10.10.11 |
+| NodeJS (optional)        |          | 172.10.10.12 |
+| Adminer                  | 8000     | 172.10.10.13 |
+| MariaDB                  | 3306     | 172.10.10.20 |
+| PostgreSQL (optional)    | 5432     | 172.10.10.21 |
 
 ### Docker Compose (`docker-compose.yml`)
 
-I have prepared docker configuration file for you. You can [download it here](https://github.com/dockette/devstack/blob/master/docker-compose.yml).
+I have prepared docker configuration file for you. You can [download it here](https://github.com/dockette/devstack/blob/master/docker-compose.yml). The project uses the Docker Compose plugin command (`docker compose`) and keeps a legacy `docker-compose` fallback for older hosts.
 
 ```
 wget https://raw.githubusercontent.com/dockette/devstack/master/docker-compose.yml
@@ -75,17 +81,17 @@ If you didn't change the `DEVSTACK_DOCKER` variable, you should place your `dock
 After you've followed install section, your devstack should be well prepared. One thing left, you should configure your devstack (passwords, folders, etc). 
 
 You should: 
- - setup your [**data homeland**](https://github.com/dockette/devstack/blob/master/docker-compose.yml#L132-L134)
- - setup MySQL [**root password**](https://github.com/dockette/devstack/blob/master/docker-compose.yml#L108-L110)
- - setup PostgreSQL [**root password**](https://github.com/dockette/devstack/blob/master/docker-compose.yml#L125-L127)
+ - setup your [**data homeland**](https://github.com/dockette/devstack/blob/master/docker-compose.yml#L151-L153)
+ - setup MySQL [**root password**](https://github.com/dockette/devstack/blob/master/docker-compose.yml#L125-L127)
+ - setup PostgreSQL [**root password**](https://github.com/dockette/devstack/blob/master/docker-compose.yml#L144-L146) if you enable PostgreSQL
 
 ### Userdirs
 
 There are two kind of users inside these containers, **root** (main unix user) and **dfx** (special user with uid 1000 in all `dockette` based images).
 
-You can find it in docker-compose.yml [file in section/container](https://github.com/dockette/devstack/blob/master/docker-compose.yml#L139-L147).
+You can find it in docker-compose.yml [file in section/container](https://github.com/dockette/devstack/blob/master/docker-compose.yml#L155-L166).
 
-On the containers startup, your `users dir` are attached to `php72`, `php56`, `nodejs` containers. You can create your own `.bash_profile`, `.bashrc` files 
+On the containers startup, your `users dir` are attached to `php72` and to `php56`/`nodejs` when you enable those optional containers. You can create your own `.bash_profile`, `.bashrc` files
 for easier manipulation inside docker containers.
 
 [**TIP**] There used to be a skeleton in ubuntu/debian/mint system. 
@@ -125,9 +131,9 @@ MariaDB container has predefined IP address `172.10.10.20`.
 172.10.10.20 mariadb
 ```
 
-### PostgreSQL
+### PostgreSQL (optional)
 
-PostgreSQL's default root password is `root`. You should change it.
+If you enable PostgreSQL, its default root password is `root`. You should change it.
 
 You have to setup in you application/configs proper `host` which is `postgresql`. 
 
@@ -152,6 +158,9 @@ By default is devstack available on domains:
 - www.local.dev (php)
 - local.dev7 (php7)
 - www.local.dev7 (php7)
+
+When you enable PHP 5.6, these domains are available too:
+
 - local.dev56 (php56)
 - www.local.dev56 (php56)
 
@@ -168,16 +177,19 @@ You should add these lines to your `/etc/hosts` file.
 
 # Devstack [DB]
 172.10.10.20 mariadb
+# Optional PostgreSQL
 172.10.10.21 postgresql
 ```
 
 Give a try!
 
 ```
 ping local.dev
-ping local.dev56
 ping local.dev7
 ping mariadb
+
+# Optional services
+ping local.dev56
 ping postgresql
 ```
 

diff --git a/devstack b/devstack
@@ -4,6 +4,7 @@
 DEVSTACK_PREFIX=${DEVSTACK_PREFIX:-devstack}
 DEVSTACK_DOCKER=${DEVSTACK_DOCKER:-~/.devstack/docker-compose.yml}
 DEVSTACK_USER=${DEVSTACK_USER:-dfx}
+DEVSTACK_SSH_AUTH_SOCK=${DEVSTACK_SSH_AUTH_SOCK:-/tmp/devstack-ssh-agent}
 DEVSTACK_VERSION=1.3
 
 # Functions
@@ -18,6 +19,7 @@ Environment:
     User: $DEVSTACK_USER
     Prefix: $DEVSTACK_PREFIX-[container]
     Configuration: $DEVSTACK_DOCKER
+    SSH agent: ${SSH_AUTH_SOCK:-$DEVSTACK_SSH_AUTH_SOCK}
 
 Commands:
 
@@ -42,8 +44,18 @@ Commands:
 EOF
 }
 
+compose() {
+    if [ -n "$DEVSTACK_COMPOSE" ]; then
+        $DEVSTACK_COMPOSE "$@"
+    elif docker compose version >/dev/null 2>&1; then
+        docker compose "$@"
+    else
+        docker-compose "$@"
+    fi
+}
+
 call() {
-    docker-compose -p "$DEVSTACK_PREFIX" --file "$DEVSTACK_DOCKER" $*
+    SSH_AUTH_SOCK=${SSH_AUTH_SOCK:-$DEVSTACK_SSH_AUTH_SOCK} compose -p "$DEVSTACK_PREFIX" --file "$DEVSTACK_DOCKER" "$@"
 }
 
 up() {