Skip to main content

Using a custom module locally in GovCMS SaaS

Sometimes you need to get a custom module into your GovCMS SaaS website locally for testing, or data manipulation… most commonly for Migration.

However, you can’t just throw the module into the repo and expect it to work.

These two steps are all you need to get your module working on your SaaS site.

Prerequisites

  • GovCMS SaaS running on your local
  • A custom or contrib module you want to include

Step 1

Create a new folder in the root directory of your repository called modules, and be sure to add it to your .gitignore file, because the code inside it will likely get caught by ShipShape and ruin your pipelines if it makes it onto the git repository.

This is your folder for any custom, or contrib modules that you want to run locally.

Step 2

Now, if you try and go to Extend to enable the module, you will notice that your module doesn’t exist there.  That is because it only exists on your File system and not inside the Docker container itself.

You need to copy the module from the File system into the Docker containers.

For that, we have a simple command line instruction to run from the root folder of the repo:

docker cp modules/. govcms-PROJECT-php-1:/app/web/modules/custom/

To break it down we have:

  • docker  - The command line tool we are using
  • cp - Copy
  • modules/. - The contents of the modules folder
  • govcms-PROJECT-php-1 - The container we are copying into. Be sure to replace PROJECT with the name of your project.  If you don't know what this is, you can check Docker Desktop container list.
  • /app/web/modules/custom - The destination directory inside the container

Run a cache clear and boom, you have your modules available.

Now the problem is, especially for Migration modules, you might need to make incremental changes and want to test them out.

You can’t just Save the changes and have them appear, they need to be re-synced into the Docker container.

You will need to simply run that same command again.

Things to note

  • Don’t commit the module folder to the Repository, and to make that easier, add the module folder to the .gitignore
  • You could setup a custom ahoy command by customising /custom/ahoy.yml to make the command a bit easier to use
  • Make sure you uninstall any modules BEFORE you export the database for a forklift
     
GovCMS
GovCMS SaaS
Easy