Installation

Contents

• MacOS / Linux
• Windows

---

For MacOS / Linux

Install Docker (Linux Only)

1. Follow the instructions to install Docker and Docker Compose
2. Log out of the terminal and log back in to make sure the Docker setup has been fully applied.
3. Try running docker run hello-world. If the installation of Docker was all successful Docker should pull the image and run it.
4. Test whether docker compose help works.

Install Rancher Desktop (MacOS Only)

1. Install Rancher Desktop (do not install Docker Desktop 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 ln -s ~/.rd/bin/docker /usr/local/bin/docker (if you get a permissions error try again prefixed with sudo. This command ensures mutagen which we’ll install next works without issues.
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.

Install Mutagen (MacOS Only)

Mutagen is a synchronisation tool and enables the set up to perform at much higher levels than with regular Docker volume mounts (they are really slow on Mac OS).

1. Install Homebrew
2. Open your terminal and install mutagen using homebrew: brew install havoc-io/mutagen/mutagen
3. Register the mutagen daemon so it starts automatically: mutagen daemon register
4. Start the daemon with: mutagen daemon start
5. 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
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. nano .env) and change the following lines:
8. Set LOCAL_SRC to your totara-sites folder, e.g. /Users/USERNAME/totara-sites
9. MacOS Only: Set (or add if not exists) this line to enable the use of mutagen: USE_MUTAGEN=1
10. 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"
11. 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
12. Run the tools/set_hosts.sh script to add all required host entries to your /etc/hosts file: sh ~/totara-docker-dev/tools/set_hosts.sh (you will have to enter your password)
13. 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
14. 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
    • Linux: sudo apt-get update && sudo apt-get install php-cli, verify with php -v
15. Run the following command to test whether everything is working: tup php-8.3 pgsql13
16. 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.
17. 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
18. Set “Hack Nerd Font” as font for your terminal
    • MacOS: in iTerm2 go to Settings → Profiles → Text

Further Setup

See New Site Initialisation

---

Windows

Preparations

1. Install and set up WSL2 following the instructions on Microsoft's website: https://docs.microsoft.com/en-us/windows/wsl/install (Ubuntu is the recommended choice)
2. Either open the start menu, search and open “Ubuntu” (if you have used this as your distro) or open Windows Terminal (the app called "windows terminal", you may have to install it) and open a terminal to your Linux distro. From this point, all commands will be run inside the terminal.
3. Follow the instructions to install Docker and Docker Compose
4. Log out of the terminal and log back in to make sure the Docker setup has been fully applied.
5. Try running docker run hello-world. If the installation of Docker was all successful Docker should pull the image and run it.
6. Test whether docker compose help works.

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. Run the following from within your Ubuntu distro
2. 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).
3. Log into your Github account
4. Add your public SSH key to your Github account
5. Clone the 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. nano .env) and change LOCAL_SRC to your totara-sites folder, e.g. /Users/USERNAME/totara-sites
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. Run the following command to test whether everything is working: tup php-8.3 pgsql13
11. All containers should successfully start up without any warnings and errors.
12. If PHP is not installed (check with php -v) then install it as it’s needed for some of our helper scripts. Install via: sudo apt-get update && sudo apt-get install php-cli, verify with php -v.

Complete your setup

1. Download and install the extended font to render additional icons in the container shells.
2. Set “Hack Nerd Font” as font for your terminal (in iTerm2 go to Settings → Profiles → Text)
3. 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).

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

Set up your IDE

1. If you are using VS Code as your IDE make sure you have the WSL extension installed. Check out its documentation for more information on how to use it
2. If you are using PHPStorm check out its documentation for more information on how to use it with WSL.

Further Setup

See New Site Initialisation