Skip to content

1.1 Local setup

Jump to bottom Edit New page
Joshua Graham edited this page Feb 19, 2024 · 9 revisions

This page describes preparing your local environment to run the tools you need for GovCMS, and then setting up a new project.

Since we cater for a variety of developers with different experience, and many are working with limited tools in government, we can't provide perfect documentation for everyone. If you have issues please refer to Getting help.

Contents

Dependencies

If your site is using the GovCMS platform, and you want to develop this site locally, you will need these tools.

Note for Windows

We are trying to improve the Windows experience. Most commands need to be carried out in Powershell but some may require Git-bash. Use both tools with elevated permissions. DOS prompt is not appropriate for local development.

See also the Amazee docs as well as the Windows-specific tips in this user contributed guide.

Upcoming opportunities

There is a trial version of Pygmy written in Go.

This will help to address many of the common issues users have had with Pygmy in the past including:

  • Windows support (which may help Windows users who cannot install Ruby gems at present).
  • Granular control over ports and services (run Pygmy on HTTPS with no effort; run phpmyadmin/portainer as well)

Instructions to install Pygmy-go (windows)

  1. Install choco Open PowerShell as Admin Run
Set-ExecutionPolicy Bypass -Scope Process -Force
iex ((New-Object System.Net.WebClient).DownloadString('https://community.chocolatey.org/install.ps1'))

  1. Install make Run choco install make

  2. Clone the pygmy-go repo

Change to directory. e.g. cd C:\programs

Run git clone https://github.com/pygmystack/pygmy.git pygmy-go

Change to directory to pygmy-go. e.g. cd C:\programs\pygmy-go

  1. Compile pygmy-go to make pygmy.exe

_Note, If you have a SSL scanning program, e.g. zscaler by your organization, ensure the extra ssl cert is added to docker file first to avoid error "unable to get local issuer certificate"!

Instructions for Zscaler (windows)
  1. Open Windows Start menu
  2. "mmc.exe"
  3. File
  4. add /remove snap-in
  5. Certificates
  6. Add
  7. Either My account or Computer account, doesn't matter (won't appear if not run as admin - so can be skipped)
  8. OK
  9. [In left side bar]
  10. Trusted Root Certification Authorities
  11. Certificates
  12. Find Zscaler Root Certificate
  13. Right click
  14. Tasks
  15. Export (Format CER - base64) to [pygmy folder]/zscaler.cer

Then Add the following lines to the [pygmy folder]/Dockerfile after COPY service/ /go/src/github.com/pygmystack/pygmy/service/

COPY zscaler.cer /tmp/
RUN apk update
RUN apk add curl openssl
RUN openssl x509 -inform PEM -in /tmp/zscaler.cer -out /usr/local/share/ca-certificates/zscaler.crt
RUN update-ca-certificates

@see https://help.zscaler.com/zia/adding-custoem-certificate-application-specific-trusted-store#docker-file

Run make build;

  1. Add pygmy.exe to PATH

Run systempropertiesadvanced.exe => Advanced tab => Environment Variables > Click edit on PATH for System variables Add builds to that PATH property e.g. C:\programs\pygmy-go\builds

  1. Open to new command prompt (cmd.exe)

This will have the new PATH, then run pygmy up as usual.

Instructions to install Pygmy-go (Mac/Linux/WSL)

  1. Clone the pygmy-go repo

Change to directory. e.g. cd /Users/[username]/programs (replace [username] with your username)

Run git clone https://github.com/pygmystack/pygmy.git pygmy-go

Change to directory to pygmy-go. e.g.

  • cd /Users/[username]/programs/pygmy-go (Mac)
  • cd /home/[username]/programs/pygmy-go (Linux/WSL)
  1. Compile pygmy-go to make pygmy executable

_Note, If you have a SSL scanning program, e.g. zscaler by your organization, ensure the extra ssl cert is added to docker file first to avoid error "unable to get local issuer certificate"!

Instructions for Zscaler (mac) MAC - export certificate:
  1. Open a web browser such as chrome
  2. Browse a HTTPS sites such as https://www.google.com.au/
  3. Click on the padlock on the left of the address bar.
  4. Click "This site is secure".
  5. Click "Certificate is valid".
  6. Click "Details"
  7. Select the root Zscaler certificate (top most)​​​​​​​ [ zscaler is not preent, you skip this entire zscaler step]
  8. Click export -> format DER (.cer file extension), e.g. filename zscaler.cer
  9. Then Add the following lines to the [pygmy folder]/Dockerfile after COPY service/ /go/src/github.com/pygmystack/pygmy/service/ 
COPY zscaler.cer /tmp/
RUN apk update
RUN apk add curl openssl
RUN openssl x509 -inform PEM -in /tmp/zscaler.cer -out /usr/local/share/ca-certificates/zscaler.crt
RUN update-ca-certificates

@see https://help.zscaler.com/zia/adding-custoem-certificate-application-specific-trusted-store#docker-file

  1. Run make build

  2. Add pygmy to PATH and make executable.

Change directory to the builds folder: e.g.

  • cd /Users/[username]/programs/pygmy-go/builds (Mac)
  • cd /home/[username]/programs/pygmy-go/builds (Linux/WSL)
  1. Copy the correct executable file to the user binaries folder.

e.g. cp ./builds/[pygmy-file] /usr/local/bin/pygmy

Where [pygmy file] is:

  • pygmy-linux-arm64-static (Intel Mac)
  • pygmy-linux-arm-static (M1 (arm) Mac)
  • pygmy-linux-amd64-static (Linux / WSL - most Linux OSs are 64bit)

So for example, for an M1 Mac, run cp ./builds/pygmy-linux-arm64-static /usr/local/bin/pygmy

  1. Mark file permission as executable.

sudo chmod +x /usr/local/bin/pygmy

Done, run pygmy up as usual.

Changing the pygmy-go ports

  1. To change the pygmy-go's haproxy port (website port), add a file .pygmy.yml to your user folder. e.g. C:\users\myusername\.pygmy.yml

  2. And Put the contents (adjust 7088 / 7089 to the port you want)

services:
  amazeeio-haproxy:
    HostConfig:
      PortBindings:
        80/tcp:
          - HostPort: 7088
        443/tcp:
          - HostPort: 7089
  1. Then clean up pygmy-go's containers and start them again. (ignore the error: Error response from daemon: error while removing network: network amazeeio-network id deadXXXX has active endpoints)
pygmy clean
pygmy up

You should see the message: Using config file: C:\Users\myusername\.pygmy.yml when pygmy up is run.

You can also see the current configuration by running pygmy export --output /path/to/output-config-file.yml

Building your project

These instructions will help you set up your project locally. It assumes that you have been provisioned with a GovCMS project in Gitlab. If you have not been provisioned with a project, you can test this process by installing the scaffold for PaaS or SaaS (depending on the flavour of hosting you may choose for your future project), and skipping to step 3.

  1. Validate that you have the tools you need. Refer to these commands for help.

  2. Clone your project's Gitlab repository. The clone URL can be found at https://projects.govcms.gov.au/ORGNAME/PROJECTNAME

Your should ensure that the location of your clone is included in Docker's file sharing.

git clone [email protected]:ORGNAME/PROJECTNAME.git
cd PROJECTNAME
  1. Build and start the docker containers:
# This is identical to `ahoy up`.
docker-compose up -d
  1. Build the codebase with Composer:
# This is identical to `ahoy composer install`.
docker-compose exec -T test composer install
  1. Install a vanilla GovCMS site:
# This is identical to `ahoy install`.
docker-compose exec -T test drush si -y govcms
  1. You should have a running site now, which you can visit at http://PROJECTNAME.docker.amazee.io. To login to Drupal as user 1 you can run:
# This is identical to `ahoy login`.
docker-compose exec -T test drush uli
Add a custom footer
Add a custom sidebar
Clone this wiki locally