1.1 Local setup - govCMS/GovCMS GitHub Wiki

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.

• Dependencies
• Note for Windows
• Upcoming opportunities
• Instructions to install Pygmy (Mac/Linux/WSL)
• Instructions to install Pygmy (Windows - DO NOT USE)
• Changing the pygmy-go ports
• Building your project

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

• Git
• Docker & docker-compose Windows, OSX
• Pygmy
• Ahoy (recommended)

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.

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)

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)

2. 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"!
• If you get error reading https://proxy.golang.org/golang.org/[projectfile]: 403 Forbidden, then add ENV GOPROXY="https://goproxy.io,direct" prior to WORKDIR instruction in the Dockerfile. and try again a few times. If still not working, you can to use other proxies like:
  • docs.gomods.io, gocenter.io, goproxy.cn, goproxy.io, proxy.golang.org, thumbai.app etc.

For Zscaler WSL, see title "Instructions for Zscaler (windows)".

COPY external/ /go/src/github.com/pygmystack/pygmy/external/

WORKDIR /go/src/github.com/pygmystack/pygmy/
RUN GO111MODULE=on go mod verify

COPY external/ /go/src/github.com/pygmystack/pygmy/external/

COPY 'zscaler.pem' '/tmp/zscaler.pem'
RUN CACHE_BUST_COUNTER=1 && cp '/tmp/zscaler.pem' '/usr/local/share/ca-certificates/zscaler.pem'
RUN update-ca-certificates

WORKDIR /go/src/github.com/pygmystack/pygmy/
RUN GO111MODULE=on GOPROXY='proxy.golang.org,direct' go mod tidy
RUN GO111MODULE=on go mod verify

COPY external/ /go/src/github.com/pygmystack/pygmy/external/

WORKDIR /go/src/github.com/pygmystack/pygmy/
RUN GO111MODULE=on go mod verify

COPY external/ /go/src/github.com/pygmystack/pygmy/external/

RUN apk update
RUN apk add curl openssl
RUN CACHE_BUST_COUNTER=1 && echo "Cache bust counter: $CACHE_BUST_COUNTER"
COPY zscaler.cer /tmp/
RUN openssl x509 -inform DER -in '/tmp/zscaler.cer' -out '/usr/local/share/ca-certificates/zscaler.crt'
RUN update-ca-certificates

WORKDIR /go/src/github.com/pygmystack/pygmy/
RUN GO111MODULE=on GOPROXY='proxy.golang.org,direct' go mod tidy
RUN GO111MODULE=on go mod verify

3. Run make build

4. 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)

5. 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-darwin-arm64 (M1 (arm) Mac)
• pygmy-linux-amd64 (Linux / WSL - most Linux OSs are 64bit)
• pygmy-darwin-amd64 (Intel Mac)

So for example:

• for an M1 Mac, run sudo cp ./builds/pygmy-darwin-arm64 /usr/local/bin/pygmy
• for an Linux / WSL, run sudo cp ./builds/pygmy-linux-amd64 /usr/local/bin/pygmy

6. Mark file permission as executable.

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

Done, run pygmy up as usual.

NOTE: DO NOT USE if using WSL, use WSL instructions instead

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'))

2. Install make Run choco install make

3. 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

4. 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"!
• If you get error reading https://proxy.golang.org/golang.org/[projectfile]: 403 Forbidden, then add ENV GOPROXY="https://goproxy.io,direct" prior to WORKDIR instruction in the Dockerfile. and try again a few times. If still not working, you can to use other proxies like:
  • docs.gomods.io, gocenter.io, goproxy.cn, goproxy.io, proxy.golang.org, thumbai.app etc.

RUN apk update
RUN apk add curl openssl
RUN CACHE_BUST_COUNTER=1 && echo "Cache bust counter: $CACHE_BUST_COUNTER"
COPY zscaler.cer /tmp/
RUN openssl x509 -inform PEM -in /tmp/zscaler.cer -out /usr/local/share/ca-certificates/zscaler.crt
RUN update-ca-certificates

Run make build;

5. 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

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

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

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

3. 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

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, 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

3. Build and start the docker containers:

# This is identical to `ahoy up`.
docker-compose up -d

4. Build the codebase with Composer:

# This is identical to `ahoy composer install`.
docker-compose exec -T test composer install

5. Install a vanilla GovCMS site:

# This is identical to `ahoy install`.
docker-compose exec -T test drush si -y govcms

6. 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