3SD handbook

Development environment for client projects

Follow the instructions below to set up your development environment for working on client projects.

Software requirements

Ensure that you install the following software packages (this may vary depending on your system):

# debian / ubuntu packages
apt install apache2-utils composer git default-mysql-client php-curl php-xml python3

You should also install Docker and Docker Compose as per the instructions on the website:

Location of source code

By convention we store all source code in ~/src/{PROJECT}. This is a good convention to follow as it corresponds with the file structure on our servers. The repositories mentioned below should be cloned into ~/src/.

Proxy

The Traefik repository creates a local web hosting environment on your machine.

Clone into ~/src/ and follow the instructions in the README.

Database

We use MariaDB as a database.

Clone into ~/src/ and follow the instructions in the README.

CiviCRM Docker

The CiviCRM Docker repository sets up the hosting environment for CiviCRM sites.

This is mostly used within Docker images for sites, but we occasionally need to run some of the scripts directly so it is helpful to have a copy of the code locally. Clone into ~/src/ (you don't need to bring this container up).

Scripts

Create a folder for commonly used scripts and link to them:

mkdir ~/bin
ln -s ~/src/civicrm-docker/bin/civicrm-docker-dump-manual ~/bin/civicrm-docker-dump-manual
ln -s ~/src/civicrm-docker/bin/gen-secret-keys ~/bin/gen-secret-keys
ln -s ~/src/civicrm-docker/bin/gen-wordpress-keys ~/bin/gen-wordpress-keys

You'll need to log in and out for ~/bin to be added to your path.

Server access

3SD has four main servers:

  • Apricot - production sites
  • Mango - production database
  • Coconut - test sites
  • Elm - infrastructure (e.g. GitLab, Mattermost etc.)

Add these lines to your SSH config file (~/.ssh/config) or create the file if it doesn't exist:

Host apricot.3sd.io mango.3sd.io coconut.3sd.io elm.3sd.io
  User admin

Client set up

For each client project follow these steps:

  1. Clone the client repository into ~/src and cd into it

  2. Create the database user:

    pushd ~/src/mariadb
bin/init-project --cms [CMS] [PROJECT]
popd

  3. Create secret keys: gen-secret-keys

  4. Create WordPress keys (WordPress only): gen-wordpress-keys

  5. Create the environment file by copying the output of the above commands into a .env file at the root of the client folder

    COMPOSE_FILE=compose.yaml:compose.dev.yaml

DOCKER_CPUS=2
DOCKER_MEM_LIMIT=4G

DEBUG=OFF # set to ON for debugging

CIVICRM_DB_PASS=xxx
WORDPRESS_DB_PASS=xxx # same password for WordPress
DRUPAL_DB_PASS=xxx # if using Drupal

CIVICRM_SITE_KEY=xxx
CIVICRM_CRED_KEYS=xxx
CIVICRM_SIGN_KEYS=xxx

WORDPRESS_AUTH_KEY=xxx
...

  6. Create bash history file: touch .bash_history

  7. Create the state folder: mkdir state

  8. Create a mount point for each of the volumes in the compose file (if they don't already exist):

    # example mount points - amend as needed
mkdir src/wordpress/wp-content/cache
mkdir src/wordpress/wp-content/uploads
mkdir src/wordpress/wp-content/wflogs

  9. Add a symlink for the docker compose file (not needed if using compose.yaml): ln -s docker-compose.dev.yml docker-compose.yml

  10. Start the container: docker compose up -d

  11. Check and fix ownership of mounted volumes (should be owned by civicrm user) e.g.:

    docker compose exec app ls -al wp-content
docker compose exec app chown -R civicrm:civicrm wp-content

  12. Sync the state: ./sync

Refreshing your local copy

If you want to reset your local copy to the state of the previous sync you can reload the state that you synced earlier:

docker compose exec -u civicrm app civicrm-docker-load

If you want to get an up-to-date copy of the site, use the ./sync command.