Merge branch 'dev' into accessibility-exchangeGH-2562

Author: jobara

.kube/app/Dockerfile

@@ -9,6 +9,9 @@ ENV APP_DIR /app
 ENV KUBE_DIR .kube/app
 
 ARG CIPHERSWEET_KEY
+ARG USER_ID
+# If argument passed then swap out numerical id for www-data user to allow for mirroring volumes from local to host set via .env file variable WWWUSER and is auto-generate when starting nix-shell for the first time
+RUN [ -z "$USER_ID" ] || usermod -u $USER_ID www-data
 
 RUN apt-get update
 
@@ -49,7 +52,8 @@ RUN apt-get install -y \
 
 RUN mkdir -p /tmp/imagick
 WORKDIR /tmp/imagick
-RUN curl -L -o /tmp/imagick.tar.gz https://github.com/Imagick/imagick/archive/refs/tags/3.7.0.tar.gz # upgrade version when bumping PHP version
+# upgrade version when bumping PHP version
+RUN curl -L -o /tmp/imagick.tar.gz https://github.com/Imagick/imagick/archive/refs/tags/3.7.0.tar.gz
 RUN tar --strip-components=1 -xf /tmp/imagick.tar.gz
 RUN phpize
 RUN ./configure
@@ -82,17 +86,23 @@ RUN . "$NVM_DIR/nvm.sh" && nvm install $NODE_VERSION
 ENV PATH $NVM_DIR/versions/node/v$NODE_VERSION/bin:$PATH
 
 COPY $KUBE_DIR/php.ini /etc/php/$PHP_VERSION/cli/conf.d/99-sail.ini
+# explicitly setup production PHP settings
+RUN mv "$PHP_INI_DIR/php.ini-production" "$PHP_INI_DIR/php.ini"
 COPY $KUBE_DIR/nginx.conf /etc/nginx/nginx.conf
 COPY $KUBE_DIR/supervisord.conf /etc/supervisor/conf.d/supervisord.conf
 
-RUN mkdir $APP_DIR
 WORKDIR $APP_DIR
-COPY . $APP_DIR
-
+# Change ownership as the files are copied rather than having to change after
+COPY --chown=www-data:www-data . $APP_DIR
+# Prevents error on npm ci when directory doesn not yet exist
+RUN mkdir -p $APP_DIR/node_modules
+# Set proper ownership to prevent errors when installed with php-fpm user
+RUN chown www-data:www-data $NVM_DIR/nvm.sh $APP_DIR/node_modules /var/www
+
+# run installers as the user that PHP runs under to keep ownership aligned
+USER www-data
 RUN composer install
-
 RUN . "$NVM_DIR/nvm.sh" && nvm use $NODE_VERSION && npm ci
+USER root
 
-RUN chown -R www-data:root $APP_DIR/public/ $NVM_DIR
-
-ENTRYPOINT $APP_DIR/$KUBE_DIR/entrypoint.sh
+ENTRYPOINT $APP_DIR/$KUBE_DIR/entrypoint.sh

.kube/app/entrypoint.sh

@@ -1,37 +1,27 @@
-#!/bin/sh
+#!/usr/bin/env bash
 
 set -e
 
-# TODO permanent remove cache lines once testing on per/pod caching is tested
-
 mkdir -p $FILES_PATH
-# mkdir -p $CACHE_PATH removed per https://github.com/accessibility-exchange/platform/issues/1596
 
-## fix permissions before syncing to existing storage and cache https://github.com/accessibility-exchange/platform/issues/1226
-chown -R www-data:root /app/storage /app/bootstrap/cache $FILES_PATH $VIEW_COMPILED_PATH # $CACHE_PATH removed per https://github.com/accessibility-exchange/platform/issues/1596
+# Removing in favor of changing ownership in the syncing stream
+# chown -R www-data:www-data /app/storage /app/bootstrap/cache $FILES_PATH $VIEW_COMPILED_PATH
 
 ## sync files from container storage to permanent storage then remove container storage
-rsync -a /app/storage/ $FILES_PATH
+rsync -a --chown=www-data:www-data /app/storage/ $FILES_PATH
 rm -rf /app/storage
 
-## sync files from container cache to permanent storage then remove container cache
-## removed syncing to shared/permenant storage https://github.com/accessibility-exchange/platform/issues/1596
-# rsync -a /app/bootstrap/cache/ $CACHE_PATH
-# rm -rf /app/bootstrap/cache
-
 ## create symlinks from permanent storage & cache to application directory folders
 ln -s $FILES_PATH /app/storage
-## removed linked to shared/permenant storage https://github.com/accessibility-exchange/platform/issues/1596
-# ln -s $CACHE_PATH /app/bootstrap/cache
 
 php artisan deploy:local
 
 flock -n -E 0 /opt/data -c "php artisan deploy:global" # run exclusively on a single instance at once
 
-## fix permissions after syncing to existing storage and cache https://github.com/accessibility-exchange/platform/issues/1236
-chown -R www-data:root /app/bootstrap/cache $FILES_PATH # $CACHE_PATH removed per and added path to cache in the pod https://github.com/accessibility-exchange/platform/issues/1596
-
 # Generate the robots.txt and sitemap.xml files
 php artisan seo:generate
 
+# Add in symlink to ownership update, add in public folder where assets are compiled
+chown -R www-data:www-data /app/storage /app/bootstrap/cache /app/public/build /app/public/*.{xml,txt} $FILES_PATH
+
 /usr/bin/supervisord -c /etc/supervisor/conf.d/supervisord.conf

.local-deploy/accessibility-app/Dockerfile

@@ -2,11 +2,10 @@
 
 INCLUDE+ ./.kube/app/Dockerfile
 
-ARG USER_ID
+# for development add in command for showing running processes
+RUN apt install -y procps
 
-RUN usermod -u $USER_ID www-data
-RUN chown -R www-data:root /app $NVM_DIR
-RUN chown www-data:root /var/www
-
-COPY .local-deploy/accessibility-app/php.ini-development /usr/local/etc/php/conf.d/php.ini
+COPY .local-deploy/accessibility-app/php.ini-development "$PHP_INI_DIR/conf.d/99-sail.ini"
+# explicitly setup development php settings
+RUN mv "$PHP_INI_DIR/php.ini-development" "$PHP_INI_DIR/php.ini"
 COPY .local-deploy/accessibility-app/etc /etc

.local-deploy/accessibility-app/etc/nginx/nginx.conf

@@ -31,13 +31,9 @@ http {
         listen 8080;
         server_name _;
 
-        location /nginx_status {
+        # change to match production path
+        location /status/nginx {
             stub_status on;
-            # don't need ip restrictions for local testing
-            # allow 127.0.0.1;
-            # allow 10.0.0.0/8;
-            # allow 172.0.0.0/8;
-            # deny all;
         }
 
         include /etc/nginx/includes/laravel.conf;

README.md

@@ -182,6 +182,7 @@ Herd supports debuging via XDebug. The article "[Activating XDebug on Visual Stu
 ### Local development using Docker and Nix  
 
 #### Setup Instructions  
+
 1. Install [Nix](https://nixos.org/download/) for your system.  
 2. Run `nix-shell`.  
 3. If you are wanting to run Docker, follow the steps for your platform:  
@@ -193,60 +194,157 @@ Herd supports debuging via XDebug. The article "[Activating XDebug on Visual Stu
        ```  
    - **Other Systems**: You will need to have Docker installed and running.  
 
-#### Docker Compose Aliases  
-These aliases simplify working with `docker-compose` using the `docker-compose.yml` file:  
-
-- `dc` → Shortcut for `docker-compose -f docker-compose.yml`  
-- `dcbp` → Build the `platform.test` service: `docker-compose -f docker-compose.yml build platform.test`  
-- `dcup` → Start services in detached mode: `docker-compose -f docker-compose.yml up -d`  
-- `dcd` → Stop and remove containers: `docker-compose -f docker-compose.yml down`  
-- `dil` → List Docker images: `docker image ls`  
-- `dirm` → Remove Docker images: `docker image rm`  
-- `dvl` → List Docker volumes: `docker volume ls`  
-- `dvrm` → Remove Docker volumes: `docker volume rm`  
-
-#### Kubernetes Aliases  
-These aliases simplify working with `kubectl` in different namespaces:  
-
-- `kcd` → Shortcut for `kubectl -n iris-accessibility-development`  
-- `kcs` → Shortcut for `kubectl -n iris-accessibility-staging`  
-- `kcp` → Shortcut for `kubectl -n iris-accessibility-production`  
-
-#### Pod Flushing Functions  
-
-##### `kflush` Function  
-The `kflush` function executes Laravel deployment commands (`php artisan deploy:local` and `php artisan deploy:global`) inside running `app-` pods for a given namespace.  
-
-###### Usage:  
-```sh
-kflush <namespace>
-```  
-Example:  
-```sh
-kflush development
-```  
-This will:  
-1. Find all running pods with the `app-` prefix in the `iris-accessibility-<namespace>` namespace.  
-2. Execute `php artisan deploy:local` in each pod.  
-3. Execute `php artisan deploy:global` in the first matching pod.  
-
-##### `kflushall` Function  
-Flushes all `app-` pods in all environments (`development`, `staging`, `production`).  
-
-###### Usage:  
-```sh
-kflushall
-```  
-This iterates through all environments and runs `kflush` for each.  
-
-##### Namespace-Specific Flush Aliases  
-For convenience, predefined aliases allow flushing without specifying the namespace:  
-
-- `kdflush` → Runs `kflush development`  
-- `ksflush` → Runs `kflush staging`  
-- `kpflush` → Runs `kflush production`  
+#### Entering Development Environment
+
+Each time you want to have your terminal environment setup you will want to run `nix-shell` to make sure you have your aliases and packages setup.
+
+#### Aliases
+
+> :heavy_check_mark: All commands assume they're run from the project root directory where `docker-compose.yml` exists and the user has entered the nix shell by first running `nix-shell`.
+
+##### :toolbox: 1. Docker Compose (`dc`, `dexit`, etc.)
+
+| Command | Description |
+|--------|-------------|
+| `dc <command>` | Runs any `docker-compose` command (e.g., `dc ps`, `dc exec...`) |
+| `dcbp` | Builds the `platform.test` service |
+| `dcupd` | Starts containers in detached mode |
+| `dcdn` | Stops and removes containers |
+| `dexit [options] <service> <cmd>` | Executes an interactive command in a running container |
+| `dexp` | Opens a Bash shell in `platform.test` as user `www-data` |
+
+---
+
+##### :camera: 2. Docker Images (`img`, `imgrm`, etc.)
+
+| Command | Description |
+|--------|-------------|
+| `img <command>` | Runs any `docker image` command |
+| `imgls` | Lists all Docker images |
+| `imglsp` | Lists only platform-related images (`platform*`) with their name:tag |
+| `imgrmp` | Prompts for confirmation before removing platform-related images |
+| `imgrm` | Removes specified Docker images manually |
+| `imgprune` | Removes all unused images (no confirmation) |
+
+---
+
+##### :page_facing_up: 3. Docker Logs (`log`, `logf`, `logt`, etc.)
+
+| Command | Description |
+|--------|-------------|
+| `log <container>` | Shows logs for a specific container |
+| `logf <container>` | Follows (tails) logs for a specific container |
+| `logt` | Tails logs for `platform.test` with last 100 lines |
+| `logp` | Tails logs for `platform.proxy` with last 100 lines |
+| `logsql` | Tails logs for `platform.mysql` with last 100 lines |
+| `tailt`, `tailp`, `tailsql` | Show static last 100 lines (not tailing) for respective containers |
+
+---
+
+##### :floppy_disk: 4. Docker Volumes (`vol`, `volrmp`, etc.)
+
+| Command | Description |
+|--------|-------------|
+| `vol <command>` | Runs any `docker volume` command |
+| `vols` | Lists all volumes |
+| `volsp` | Lists only platform-specific volumes (e.g., `platform.mysql`, `platform.redis`) |
+| `volrmp` | Prompts for confirmation before removing matched platform volumes |
+| `volrm` | Removes specified volume manually |
+| `volprune` | Removes all unused volumes (no confirmation) |
+
+---
+
+##### :star: 5. Laravel Artisan (`artisan`, `tinker`, etc.)
+
+| Command | Description |
+|--------|-------------|
+| `artisan <command>` | Runs any Laravel Artisan command inside `platform.test` container |
+| `tinker` | Shortcut for `artisan tinker` |
+| `test` | Shortcut for `artisan test` |
+
+Example:
+```bash
+artisan make:model User -mf
+```
+is equivalent to:
+```bash
+docker-compose exec -it --user www-data platform.test php artisan make:model User -mf
+```
+
+---
+
+##### :atom_symbol: 6. Kubernetes (`kflush`, `kflushall`, etc.)
+
+These are custom deployment helpers that trigger Laravel `deploy:local` and `deploy:global` commands across Laravel pods in Kubernetes clusters.
+
+| Command | Description |
+|--------|-------------|
+| `kflush development` | Flushes all pods in `iris-accessibility-development` namespace |
+| `kflush staging` | Flushes all pods in `iris-accessibility-staging` namespace |
+| `kflush production` | Flushes all pods in `iris-accessibility-production` namespace |
+| `kflushall` | Flushes pods in all three environments (dev → stag → prod) |
+| `kflushd`, `kflushs`, `kflushp` | Shortcuts for flushing dev/stag/prod respectively |
+
+###### Internals of `kflush <env>`
+- Finds all `app-*` pods in the correct namespace
+- Runs `php artisan deploy:local` on each pod
+- Runs `php artisan deploy:global` only once (on the first pod)
+
+---
+
+##### :test_tube: Example Usage Overview
+
+###### Docker Compose
+```bash
+dc ps                     # Show running services
+dcupd                     # Start environment
+dexp                      # Open shell in app
+```
+
+###### Docker Images
+```bash
+imglsp                    # List platform images
+imgrmp                    # Remove platform images after confirming
+```
+
+###### Docker Logs
+```bash
+logt                      # View recent logs for app
+logf platform.test        # Tail logs for app
+```
+
+###### Docker Volumes
+```bash
+volsp                     # List platform volumes
+volrmp                    # Remove them safely
+```
+
+###### Laravel
+```bash
+artisan migrate           # Run migrations
+artisan make:controller   # Generate controller
+tinker                    # Start Laravel Tinker
+```
+
+###### Kubernetes
+```bash
+kflushd                   # Run kflush in dev environment
+kflushall                 # Run kflush dev, staging, and prod environments
+```
+
+---
+
+##### :memo: Legend
+
+| Symbol | Meaning |
+|-------|----------|
+| `$@` | Passes all arguments received by a function |
+| `-r` | Prevents execution if no input is given to `xargs` |
+| `-p` | Prompts for confirmation before executing |
+| `| grep ...` | Filters output based on pattern matching |
 
 #### Environment Setup  
+
 If the `.env` file does not exist, the script automatically generates it using `.env.local.template` and random secrets:  
 - `CIPHERSWEET_KEY` (32-byte hex string)  
 - `DB_PASSWORD` (16-byte hex string)  
@@ -258,6 +356,7 @@ If the `.env` file does not exist, the script automatically generates it using `
 Ensure `.env.local.template` is available before running the script.  
 
 #### Rootless Docker Support  
+
 For users running `dockerd-rootless`, the script provides:  
 - Aliases:  
   ```sh