build-notes.md

phpCollab Docker Image Build Notes

Automated builds

Currently, GitHub Actions builds and deploys images in a methodology similar to how official Docker images are produced, specifically the WordPress image(s). One major difference is that docker buildx is used to produce the image sets.

The Build Methodology (cloned from WordPress)

phpCollab's build methodology is essentially a clone of the WordPress official Docker image. It's flow is basically:

1. update.sh -> (not currently used) calls versions.sh and apply-template.sh.
2. versions.sh -> (not currently used) automatically creates/updates the versions.json file, which is the parameter file for the rest of the process.

   versions.json is manually maintained for phpCollab.

3. apply-template.sh -> creates folder and file layouts and processes the Docker.template file for each image set.
4. generate.sh -> calls generate-stackbrew-library.sh, which produces the bashbrew input file. generate.sh then and produces the command strategic/matrix used by GitHub Actions to build the desired permutation of images.

With the exceptions of the versions.json file being manually maintained, the rest of the flow is automated via GitHub actions.

Cutting New Releases

After a new release of phpCollab has been created and released, the Docker image repo needs to be touched.

Part of the release process generally requires a Linux (Ubuntu) environment. See the Local Builds -> "One-time" Setup section for details.

1. Make any desired changes to the general source files: Dockerfile.template, docker-entrypoint*.sh, etc.
2. Update the versions.json with at a minimum of the new phpCollab version and download hash.

   See the versions.json section for details.

3. Run the following to propagate the changes to the raw image source:

   ./apply-template.sh

4. Commit and push the changes to the GitHub repo.
5. Check the build results on GitHub Actions and Docker Hub.

Local Builds

The build process generally requires a Linux (Ubuntu) environment. It's easy to create one with Docker.

"One-time" Setup

1. Start a Docker container docker run -it --rm -v $(pwd):/tmp/code ubuntu:latest

   Note with --rm the container will be cleaned up upon exiting.

2. In the container, run:

   apt-get update -y \
   && apt-get install -y curl gawk git jq wget \
   && cd /tmp/code \
   && curl -o bashbrew https://doi-janky.infosiftr.net/job/bashbrew/job/master/lastSuccessfulBuild/artifact/bashbrew-amd64 \
   && chmod +x bashbrew; \
   export PATH=".:$PATH"; \
   export GITHUB_REPOSITORY=phpcollab

Iterative Stuff

After making template file changes:

1. Run the following to propagate the changes to the image set:

   ./apply-template.sh

2. Commit (but not necessarily push).
3. Create the build scripts.

   ./generate.sh

4. From the host machine (that has docker buildx installed) run the appropriate run command from the output of the ./generate.sh script, for the desired image.

Helpful notes

• Running ./generate-stackbrew-library.sh can be helpful in viewing the bashbrew manifest used by the generate.sh script, but do not commit this file. It will likely break the build.

versions.json

Format:

{
  "<label>": {
    "phpVersions": ["<php_docker_image_versions>"],
    "sha1": "<phpCollab_download_hash>",
    "upstream": "<phpCollab_download_version>",
    "variants": ["<php_docker_image_variants>"],
    "version": "<phpCollab_docker_image_version>"
  }
}

Example files:

• Barebones (just php 7.4 on Apache):

  {
    "latest": {
      "phpVersions": ["7.4"],
      "sha1": "1f0a41545a28d12e7364167544c55ade7b7e7814",
      "upstream": "2.8.1",
      "variants": ["apache"],
      "version": "2.8.1"
    }
  }

• A fairly complete, but only latest and no fpm-alpine:

  {
    "latest": {
      "phpVersions": ["8.0", "7.4", "7.3"],
      "sha1": "1f0a41545a28d12e7364167544c55ade7b7e7814",
      "upstream": "2.8.1",
      "variants": ["apache", "fpm"],
      "version": "2.8.1"
    }
  }

• Complete (lots of possibilites):

  {
    "beta": {
      "phpVersions": ["8.0", "7.4", "7.3"],
      "sha1": "1f0a41545a28d12e7364167544c55ade7b7e7814",
      "upstream": "2.8.1",
      "variants": ["apache", "fpm", "fpm-alpine"],
      "version": "2.8.1"
    },
    "latest": {
      "phpVersions": ["8.0", "7.4", "7.3"],
      "sha1": "1f0a41545a28d12e7364167544c55ade7b7e7814",
      "upstream": "2.8.1",
      "variants": ["apache", "fpm", "fpm-alpine"],
      "version": "2.8.1"
    }
  }

  Note: Beta refers to the Docker image being beta (new entrypoint, configs, etc) and not necessarily the phpCollab deployment itself.

Documentation

To generate the docs/README.md file, perform the same steps in Local Build: One-time Setup through step 2.

Then run /docs/update.sh and the docs/README.md file should get generated.