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.

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, go to “Virtual Machine” and increase the Hardware limits, if possible at least 8 CPUs and 12 - 16 GB RAM
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

Clone the Totara source code (For Totara employees, please use internal GIT repository) into your site folder and give it a name (e.g. cd ~/totara-sites && git clone REPO_URL integration)

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 [email protected]: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
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. Update your /etc/hosts file to include the totara host entries
    • MacOS & Ubuntu: Run ~/totara-docker-dev/tools/set_hosts.sh (requires your sudo password)
    • Windows: Update the hosts file (howto) and add the following to it. Note that you have to edit this file should you check out more sites in parallel (otherwise those are not reachable via sitename.totara83) or you need more PHP versions to be available (5.6 or earlier, or newly added ones).
      Hosts file example

      127.0.0.1 totara74
      127.0.0.1 totara74.debug
      127.0.0.1 totara80
      127.0.0.1 totara80.debug
      127.0.0.1 totara81
      127.0.0.1 totara81.debug
      127.0.0.1 totara82
      127.0.0.1 totara82.debug
      127.0.0.1 totara83
      127.0.0.1 totara83.debug
      127.0.0.1 integration.totara74
      127.0.0.1 integration.totara74.debug
      127.0.0.1 integration.totara80
      127.0.0.1 integration.totara80.debug
      127.0.0.1 integration.totara81
      127.0.0.1 integration.totara81.debug
      127.0.0.1 integration.totara82
      127.0.0.1 integration.totara82.debug
      127.0.0.1 integration.totara83
      127.0.0.1 integration.totara83.debug
      

11. 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
12. 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
13. Run the following command to test whether everything is working: tup php-8.3 pgsql13
14. 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.
15. Download and install the extended font "Hack Nerd Font" to render additional icons in the container shells: Download site
    • MacOS: via brew install font-hack-nerd-font
    • Windows: via this installer
16. Set “Hack Nerd Font” as font for your terminal
    • MacOS: in iTerm2 go to Settings → Profiles → Text
    • Windows: in Windows Terminal, go to Settings → Profiles → Ubuntu → Appearance → Font face

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