proudnerdswp/bitbucket-builder-image repository overview

⁠Bitbucket Pipeline | WORDPRESS | Proud Nerds Builder Image

This builder image is a basic image which we can internally use to build our projects through Bitbucket Pipelines.

⁠Changelog

⁠Version 4.0.0

Please read the changelog and check if upgrading is possible.

• Removed support for PHP 7.4, 8.0 and 8.1
• Added support for PHP 8.4
• Updated default state to build in PHP 8.4 (was 8.3)
• Updated default node version from 20.14.0 to 22.14.0 (current LTS version)
• A new build command is added to upgrade to the latest minor WP version regardless of the composer state
  • It does not use the wp cli, since that relies on db entries.
  • Use it AFTER building the project with the latest composer state.
  • Use the command pnd build:security-updates <path-to-wordpress> to run this command i.e. pnd build:security-updates public/wordpress

⁠Version 3.0.0

Please read the changelog and check if upgrading is possible.

• Added support for PHP 8.3

• Added support for multiple PHP versions using pnd build:switch-php [7.4|8.0|8.1|8.2|8.3]

• Downgraded requirements for pnd application so it works on all php-versions from 7.4 until 8.3

• Updated default state to build in PHP 8.3 (was 8.1)

• Updated default node version from 18.15.0 to 20.14.0 (current LTS version)

• Added new templates:

  • wp-base-theme-rediscache
  • wp-stock-rediscache

• Add salts.php generator/ symlinker

• Added option to add custom destination build dir (which defaults to ~/builds if not set)

  • Default can be overridden by adding a SSH_BUILD_DIR deployment variable; or
  • adding the --build-dir=[some-absolute-path] to each ssh command

  Note: all templates have been updated to accomodate this different build folder as well

⁠Version 2.0.0

This release contains some possible breaking changes. Please read the changelog and check if upgrading is possible.

• Migrated from Alpine to Ubuntu to be able to support multiple versions of PHP
• Added support for multiple PHP versions using pnd build:switch-php [8.2|8.3|8.4]
• Added support for NVM (in favour of pnd nvm:install and pnd nvm:use)

⁠Version 1.0.0 (DEPRECATED)

This version is deprecated. Do not use for new projects.

• Initial release

⁠Contents

The image is based on Ubuntu, and contains:

⁠Pre-installed packages

• rsync
• php-cli 8.2, 8.3 & 8.4
• curl
• make
• ssh
• git
• zip

⁠Additional applications

• Composer
• WP-CLI
• pnd; Proud Nerds Deployment Command Line Tool (see below)
• NPM 22.14.0; including yarn and gulp
• NVM

⁠In need of older NPM versions?

Too drasticly reduce the size of the builder image (and to speed up the building process on an up-to-date NPM version) all older versions of NPM are excluded by default. Use the following command to install another version during run-time:

nvm install 18.4.0

⁠PND | Proud Nerds Deployment Command Line Tool

The image contains a php-written command line application which can help you with deploying your application and simplifies the deployment yaml scripts. See below for more information on the commands that are written explicitely for Proud Nerds Deployments

⁠PND build commands

A simple command that uses the pnd workflow to execute shell scripts on the build server. It takes care of setting the +x addition on the script file.

⁠1. pnd build:switch-php <major.minor version>

This sets the php executable to the given version because some projects require a different PHP version during the build phase. Default PHP version is 8.3, possible values:

• 8.2
• 8.3 (DEFAULT)
• 8.4

⁠Example

pnd build:switch-php 8.4

⁠2. pnd build:script <path_to_file>

This script is run on the build server. To run a script on the destination server see the documentation for the pnd ssh:script command.

⁠Example

pnd build:script private/build-app.sh

⁠3. pnd build:security-updates <path_to_wordpress>

This command will update the WordPress version to the latest minor version. It does not use the WP CLI, since that relies on db entries.

NOTE: Use it AFTER building the project with the latest composer state.

⁠Examples

pnd build:security-updates public/wordpress
pnd build:security-updates public/wp

⁠PND Webhooks

There is currently only one webhook command available.

⁠1. pnd webhook:openshift

This command will execute a BuildConfig webhook on OpenShift to trigger a build. Succesfully invoking this webhook does not mean your build on OpenShift has succeeded. It simply starts building it. If the build on OpenShift is succesfull it will automagicly start the deployment process there.

If a webhook for a BuildConfig is not yet available use the following oc command to generate him

oc set triggers bc <build-config-name>  --from-webhook=true

This command uses the $OPENSHIFT_WEBHOOK environment variable, or you can optionally set it with the following option

⁠Options

There are a few options to override the default repository variables with different ones:

• --webhook=[generic-openshift-webhook-url]

⁠Example

pnd webhook:openshift --webhook="https://some-openshift-generic-webhook.url"

⁠PND SSH commands

The SSH commands require some additional setup within the repository settings on Bitbucket. Please provide the following information to the repository for these to work:

• Repository -> Pipelines -> SSH Keys
  • Add the pn_wp_otap private key to make sure we can connect.
• Repository -> Repository Variables
  • The following are not required, but if they are set, they are used as default values for the different options
    • SSH_USER
    • SSH_HOST
    • SSH_PORT

⁠1. pnd ssh:test

This command simply tests if we can connect. It uses above defaults, but can be overwritten with other data by specifying the following options:

⁠Options

There are a few options to override the default repository variables with different ones:

• --user=[user]
• --host=[host]
• --port=[port]

⁠Example

pnd ssh:test --user=$SSH_USER_DEVELOPMENT --host=$SSH_HOST_DEVELOPMENT

⁠2. pnd ssh:rsync

This command does a few things in this order:

• Create the following folder through ssh ~/builds/<BITBUCKET_PROJECT_KEY>-BLD-<BITBUCKET_BUILD_NUMBER>
• Remove all .git directories from the build folder
• Rsync the complete repository to the specfified folder above
• Restores the directories to websafe permissions (files: 644, directories 755)

⁠Options

There are a few options to override the default repository variables with different ones:

• --user=[user]
• --host=[host]
• --port=[port]

⁠Example

pnd ssh:rsync --user=$SSH_USER_DEVELOPMENT --host=$SSH_HOST_DEVELOPMENT

⁠3. pnd ssh:script <path_to_file>

This script is run on the destination server. The command will copy the file through ssh and executes the script from the same folder as the relative path in the clone dir. It performs the following actions:

• Create the script file through ssh in this directory ~/builds/<BITBUCKET_PROJECT_KEY>-BLD-<BITBUCKET_BUILD_NUMBER><path_to_file>
• Make the script executable
• Execute the script
• Remove the script from the destination folder.

⁠Options

There are a few options to override the default repository variables with different ones:

• --user=[user]
• --host=[host]
• --port=[port]

⁠Example

pnd ssh:script private/set-symlinks.sh

⁠4. pnd ssh:template <template_name>

This script is run on the destination server. The command will copy a preset symlink template file through ssh and executes the script on the destination server. It performs the following actions:

• Create the script file through ssh in this directory ~/builds/<BITBUCKET_PROJECT_KEY>-BLD-<BITBUCKET_BUILD_NUMBER>/
• Make the script executable
• Execute the script
• Remove the script from the destination folder.

⁠Options

There are a few options to override the default repository variables with different ones:

• --user=[user]
• --host=[host]
• --port=[port]
• --list Output available templates in this edition of the pnd binary.

⁠Example

The following templates are available. In the future more templates might come available. To see all templates currently, use the --list option.

pnd ssh:template --list

pnd ssh:template wp-base-theme-rediscache
pnd ssh:template wp-base-theme-w3tc
pnd ssh:template wp-base-theme-wprocket
pnd ssh:template wp-stock-rediscache
pnd ssh:template wp-stock-w3tc
pnd ssh:template wp-stock-wprocket

⁠5. pnd ssh:cleanup

This script will clean up some old builds on the production server. By default it will keep the last 5 builds.

⁠Options

There are a few options to override the default repository variables with different ones:

• --user=[user]
• --host=[host]
• --port=[port]
• --keep=[int], defaults to 5 which keeps the last 5 builds (next to the current one)

⁠Example

pnd ssh:cleanup --keep=3

⁠A basic bitbucket-pipeline.yml to get you started

Below you will find a basic pipeline for inside your bitbucket projects. It does not use all features listed above, but it gives you an insight in how to get started.

image: proudnerdswp/bitbucket-builder-image:4.0.0          # Make sure we keep using a specific build so this project will continue building even if newer versions of the image are available.

definitions:
  steps:
    - step: &build
        name: Build
        script:
          #- nvm install 18.4.0                              # Install a node version if needed v20.14.0 is already installed by default
          #- pnd build:switch-php 8.0
          #- pnd build:script private/test-build-script.sh   # Build your project using pnd; handles setting file to +x mode
          # A basic builds example.
          - composer config http-basic.satispress.wp.proudnerds.com $SATISPRESS_TOKEN satispress
          - make prod
          - pnd build:security-updates public/wp            # Update to the latest minor version of WordPress
        artifacts:                                          # Defining the artifacts to be passed to each future step(s).
          - public/{wordpress,wp}/**
          - public/{wp-content,content,app}/themes/**
          - public/{wp-content,content,app}/plugins/**
          - public/vendor/**
          - vendor/**

# Make sure you have set the private BITBUCKET_SSH_KEY_FILE to allow access to the server in Repository Settings->Pipeline->SSH Keys
pipelines:
  branches:
    develop:
      - step: *build
      - step:
          name: Deploy testing
          deployment: test                          # Make sure you have defined this deployment with variables SSH_USER, SSH_HOST, SSH_PORT
          script:
            - pnd ssh:rsync                         # rsync all repo files without .git folders
            - pnd ssh:template wp-base-theme-w3tc   # set symlinks according to given template
            - pnd ssh:cleanup --keep=2              # cleanup old builds and keep latest 2
    release/*:
      - step: *build
      - step:
          name: Deploy staging
          deployment: staging                       # Make sure you have defined this deployment with variables SSH_USER, SSH_HOST, SSH_PORT
          script:
            - pnd ssh:rsync                         # rsync all repo files without .git folders
            - pnd ssh:template wp-base-theme-w3tc   # set symlinks according to given template
            - pnd ssh:cleanup                       # cleanup old builds and keep latest 5
    main:
      - step: *build
      - step:
          name: Deploy production
          deployment: production                    # Make sure you have defined this deployment with variables SSH_USER, SSH_HOST, SSH_PORT
          script:
            - pnd ssh:rsync                         # rsync all repo files without .git folders
            - pnd ssh:template wp-base-theme-w3tc   # set symlinks according to given template
            - pnd ssh:cleanup                       # cleanup old builds and keep latest 5

⁠Migrating from Bamboo to Bitbucket Pipelines

When migrating from our Bamboo builds to Bitbucket builds, please check the following:

• Update the /domains/[domain]/public_html symlink to ~/builds/current
• Make sure the files and folders in the ~/builds/shared folder have correct permissions by running cd ~/builds/shared && find . -type f -exec chmod 644 {} \; && find . -type d -exec chmod 755 {} \;
• Make sure the ~/builds/shared/.env file is correctly filled
• Make sure the ~/builds/shared/advanced-cache.php and object-cache.php files are not empty