Running sDev and divbloxPHP locally

The idea with this is to provide developers with a way to develop sDev and divbloxPHP web applications locally using containers.

Suggested file structures

The repo is envisioned to be a high level folder wherein your PHP based projects will reside. You can then swap between configurations and environment files depending on which project you are actively working on.

php-container-development/
├─ sdev/
├─ project1/
└─ project2/

Another option is to re-create this structure for each project. Where you customise the configuration once per project.

php-container-development-sdev/
└─ sdev/
php-container-development-project1/
└─ project1/
php-container-development-project2/
└─ project2/

Requirements

A Unix-like OS

This guide was written and tested for Unix-based operating systems. So macOS, BSD or any Linux distribution should work. There are some notes for Windows but as a whole, this guide will not specifically cater to or diverge for Windows users.

Windows Subsystem for Linux (WSL) can be an option, but it comes with its own set of challenges.

Git

Git should be already installed on most systems. If not, you can find it here

Run the following command in the terminal to ensure you have it installed:

git -v

GitHub CLI

Go here or check your package manager to install the GitHub CLI tool.

Run the following command in the terminal to ensure you have it installed:

gh help

Docker + Docker-Compose

Go here to get Docker Desktop. Follow the instructions for your operating system.

Alternatively, you can install Docker Engine and Docker Compose manually.

Run the following commands in the terminal to ensure you have it installed:

docker -v
docker-compose -v
docker ps

Manual DNS entries

This will allow you and other services to connect to your containers using friendly DNS names on your local machine.

Edit your machine's hosts file and add the following lines as an example:

127.0.0.1   appname.dxgroup.local
127.0.0.1   redisinsight.dxgroup.local

Hosts File Locations

• Linux: /etc/hosts
• macOS: /private/etc/hosts
• Windows: c:\windows\system32\drivers\etc\hosts.file

Validate

Run the following command to check if the DNS entries are used:

ping appname.dxgroup.local

You should see responses from our localhost with IP 127.0.0.1. Otherwise, check your setup or try restarting your machine.

Steps

GitHub CLI Login

In your terminal type the following command. This will prompt us to log in to GitHub and grant additional scopes that will be required in the next steps.

gh auth login -s read:packages

Follow the prompts and log in with your GitHub account.

Docker login to GHCR

Now we use our GitHub credentials to authenticate Docker and gain access to the private container images stored on the GitHub Container Registry (GHCR).

docker login ghcr.io -u $(gh api user -q .login) -p $(gh auth token)

Setup & Update

This script will clone the defined repo(s) into folder(s). If it already exists the specified branches will get pulled.

./setup.sh

Start your services

This will start our services using docker-compose and the docker-compose.yml file.

docker compose up

If everything was successful then you should now be able to navigate to https://appname.dxgroup.local/ and see the login page.

Trust the Caddy Root CA certificate on your browser

To prevent your browser from giving security warnings you should trust the Root CA certificate that Caddy generates on the initial start-up. You can download it from your Caddy container by using Docker Desktop / VS Code's Docker Extention or a shell session into the container.

Once inside the container, you can find it at: /data/caddy/pki/authorities/local/root.crt

This is the CA that is used to sign all the certificates generated by Caddy for use in the reverse proxy.

Download it or copy paste the contents to a file on your local system. You will then have to import that file in the relevant applications:

Chrome/Chromium

Settings > Privacy and security > Security > Manage certificates

Import it under the Authorities tab.

On the popup, ensure you tick Trust this certificate for identifying websites before pressing OK.

Firefox

Settings > Privacy & Security > Security > View Certificates

Import it under the Authorities tab.

On the popup, ensure you tick Trust this CA to identify websites before pressing OK.

Postman

Settings > Certificates > CA Certificates

Ensure CA Certificates are enabled and then you can select the file.

OS Level Certificate Manager

You can also trust the certificate on an OS level. Various applications do this depending on your OS but they should all follow a similar process. Import and trust the certificate as a Certificate Authority.

Notes

• This certificate is valid for 10 years after generation
• You will have to redo this if you remove the caddy_data named volume as a new CA certificate will then be generated.

sDev Sync + Gen Code

This script uses the maintenance password and the specified URLs to run operations in sDev. The arguments are a list of operations to perform and operations will be performed on each URL (module) before moving on to the next operation.

The following command will sync all modules sequentially and then gen all modules only if each sync is successful:

./sdev_remote.sh REMOTESYNCONLY REMOTEGENONLY

Features

PHP Debugging

In this repo, you will find an Xdebug.Dockerfile, which builds on the base image to add PHP Xdebug configuration. You can use this modified image by updating the service to build it rather than using the base image:

service_name:
    build:
        context: .
        dockerfile: Xdebug.Dockerfile
    image: customxdebug
    # image: johanmarx/dxgroup_php_apache:latest
    volumes:
        - ./src:/var/www/html
    extra_hosts:
        - host.docker.internal:host-gateway
        - ...
    env_file:
        - sdev.env

You can then listen for debug connections on VSCode or PhpStorm on port 9003.

Redis Insight

Included in the services is an instance of Redis Insight which can be used to view and test the Redis data store.

This can be accessed locally at https://redisinsight.dxgroup.local/ or http://localhost:5540.

You can get the connection details from the relevant environment files. The defaults are:host:redis password:123

Any setup will persist on restart unless the volume (redisinsight_data) is removed.

PHPUnit Tests

Included is a sdev_run_tests.sh bash script that will run the PHPUnit tests for the modules where it is defined. You can modify the array in the script if you want to reduce the scope.

This scripts works by executing the PHPUnit script in the running Docker containers so please ensure your services are up and running locally.

./sdev_run_tests.sh

Maildev Local Email Server

For aid in email development, maildev, is incuded and set up as the default email server for sDev. This gives us a local SMTP server and inbox to test email functionality.

The front end inbox can be accessed at http://localhost:1080 using the credentials from the docker-compose.yml file, default admin in both fields.

Running commands in your container

When you need to execute a single command from withing the context of your container you can use the run_script_in_app_container.sh file and customise it as needed.

Otherwise using the run_shell_in_app_container.sh will get you and interactive shell.

FAQs

fatal: Authentication failed for <repo> when I run the setup script

Ensure that you are logged in to GitHub CLI. You can run

git config --list

to check that you have GitHub credential entries.

I get a permission denied message when trying to execute a script

You might have to give the execute permission to the script. Try using this command on the script:

chmod +x <script name>

After Gen I see files with Modified (File Mode) changes in git

• This might be because your git setup sees permission changes on files as file changes
• Navigate to your repo folder and do a git config core.filemode false

I get a permission denied response when I Sync or Gen

This is most likely due to the user permissions on the source folder. When binding the folder as a volume to the container the internal processes run as a different user which is not present on your host system. Run the following script to allow read and write access to all users:

sudo chmod 777 -R <source folder>

I get a Cannot connect to the Docker daemon at unix:<path>. Is the docker daemon running? message when running Docker commands

This means your Docker daemon isn't running.

If you are using Docker Desktop, ensure that it is running.

If you are running Docker natively you might have to start the Docker daemon manually by running:

sudo dockerd

or checkout this guide to have it start on boot.

My containers exited with a status of 0 when I tried to start them

I suggest you try to remove all the containers with the following commands and try again:

docker compose down --remove-orphans
docker rm -f $(docker ps -a -q) #remove ALL containers

Next to pruge all images from you system you can run:

docker image prune -a -f

This will then cause the next compose up to redownload all images and rebuild all containers.

Getting an unauthorized response when trying to pull the divblox-group images

Please ensure you are logged in to the Git Hub Contrainer Registry (GHCR) with your GitHub account. Check and repeat the "GitHub CLI Login" and "Docker login to GHCR" steps above.

You can check that your GitHub login has the read:packages scope listed under Token scopes

gh auth status

You can check that your Docker config file includes an entry in the auths for ghcr.io:

cat ~/.docker/config.json