Installation

Prerequisites

Windows Prerequisites

1. Install and set up WSL2 with Ubuntu following the instructions on Microsoft's website: https://docs.microsoft.com/en-us/windows/wsl/install
2. Open Windows Terminal and open a Ubuntu terminal instance
3. Follow the Ubuntu Prerequisites, running commands inside your Ubuntu terminal instance

Ubuntu Prerequisites

1. Follow the instructions to install Docker Engine using the apt repository from the Docker docs
2. Add your user to the docker group via sudo groupadd docker -f && sudo usermod -aG docker $USER
3. Log out and log back in to make sure the Docker setup and permissions have been fully applied.
4. Try running docker run hello-world. If the installation of Docker was all successful Docker should pull the image and run it.
5. Test whether docker compose help works.
6. Install Node Version Manager (NVM)
7. Install Node 20 via nvm install 20 && nvm use 20

MacOS Prerequisites

1. Install Rancher Desktop (do not install Docker Desktop or Docker Engine otherwise it will create conflicts!)
2. You won’t need Kubernetes so you can disable it during installation
3. After the installation open the Preferences in Rancher, and change the following preferences:
   • Application
     • Behavior
       • Automatically start at login ✅
       • Start in the background ✅
   • Virtual Machine
     • Hardware
       • Memory: 12-16 GB
       • CPUs: At least 8
     • Emulation
       • Virtual Machine Type: vz (Apple Virtualisation Framework)
       • VZ Option: Enable Rosetta support ✅
     • Volumes (the Emulation setting may turn the following preference on for you)
       • Mount type: virtiofs
4. Open a terminal and run sudo rm -f /usr/local/bin/docker && sudo ln -s ~/.rd/bin/docker /usr/local/bin/docker
5. Open a terminal and try running docker run hello-world. If the installation of Rancher was all successful Docker should pull the image and run it.
6. Install Homebrew
7. Open your terminal and install mutagen using homebrew: brew install havoc-io/mutagen/mutagen
8. Register the mutagen daemon so it starts automatically: mutagen daemon register
9. Start the daemon with: mutagen daemon start
10. Run the command mutagen sync list to test whether it’s working. You should see an empty list of synchronisation options.

Clone Totara code repository

1. Visit the Totara source code repo

   For Totara employees: please use the txp-integration repo in Github.

2. Clone it to your ~/totara-sites directory by running:

   • cd ~/totara-sites
   • git clone REPO_URL integration - Note: Important to specify integration as site names can only have numbers and letter in the name

Set up docker-dev

1. If you have not created an SSH key yet, use these instructions to create one (make sure you use a strong password for your private key).
2. Log into your Github account
3. Add your public SSH key to your Github account
4. Open a terminal
   • Windows Note: Make sure you are using a Ubuntu terminal, and not Command Prompt or Powershell
5. Clone this repository: git clone git@github.com:totara/totara-docker-dev.git ~/totara-docker-dev
6. In your ~/totara-docker-dev directory copy the .env.dist file to .env: cp .env.dist .env
7. Edit the file (e.g. vim .env) and change the following lines:
   • Set LOCAL_SRC to your totara-sites folder, e.g. /Users/mark/totara-sites or /home/mark/totara-sites
   • MacOS Only: Uncomment the #USE_MUTAGEN=1 line to enable the use of mutagen
   • Linux & Windows: Follow the instructions to update HOST_IP
8. Add the ~/totara-docker-dev/bin folder to your PATH environment variable, e.g. by adding the following to your ~/.bashrc or ~/.zshrc file: export PATH="$HOME/totara-docker-dev/bin:$PATH"
9. Copy the file template config.php from your totara-docker-dev folder to your Totara codebase, cp ~/totara-docker-dev/config.php ~/totara-sites/integration
10. MacOS Only: If you are using a Mac with Apple Silicon (M1/2/3/4 chip) follow the steps on Apple Silicon support to create a custom docker-compose file ~/totara-docker-dev/custom/arm.yml
11. If PHP is not installed (check with php -v) then install it as it’s needed for some of our helper scripts:
    • MacOS: via Homebrew (see also): brew install php and verify with php -v
    • Ubuntu / Windows: sudo apt update && sudo apt install php-cli, verify with php -v
12. Run the following command to test whether everything is working: tup php-8.3 pgsql13
13. MacOS Only: Now make sure the mutagen file synchronisation is running with mutagen sync monitor totara. It might take a while for the initial synchronisation to finish. You should see the status "Watching for changes" which marks a successful sync.

Further Setup

Windows Only: IDE Setup with WSL

VS Code: Make sure you have the WSL extension installed. Check out its documentation for more information on how to use it

PHPStorm: check out its documentation for more information on how to use it with WSL.

See New Site Initialisation