--- title: "Installing Totara" slug: "installing-totara" tags: ["Site Administrator", "Explainer", "Developer"] updated: 2026-09-21T08:42:01Z published: 2026-09-21T08:42:01Z canonical: "totara.help/installing-totara" --- > ## Documentation Index > Fetch the complete documentation index at: https://totara.help/llms.txt > Use this file to discover all available pages before exploring further. # Installing Totara ## Choosing an environment Information on the supported environment can always be found in code in the **readme.md** file. It can also be found in [System server requirements](/totara-20/docs/server-system-requirements) documentation. We strongly recommend that all production sites follow our recommended environments where possible. Production sites should be installed from scratch rather than being cloned from a database backup of another site. ## Preparing your environment ### Operating system If you are intending to use Totara in multiple user languages you should ensure that the server has been properly configured with the correct locales. This is important in order to ensure that dates, numbers, and currency data is displayed correctly for the user's selected language. See the [developer documentation](https://help.totaralearning.com/display/DEV/Locales) for more information on server locales. Ensure your server has been properly secured for a production environment. Refer to your operating system's provider for information on how to best achieve this. ### Database Totara supports a number of different databases. Selecting a database is a vitally important step in setting up your Totara installation. We cannot tell you which to choose, nor which is better than the rest. How you intend to use and scale your database, and your knowledge of it will have a bigger impact than most other factors. If you are unsure which to choose we recommend PostgreSQL as it delivers good performance out of the box without requiring tuning. #### MySQL If you want to use MySQL, we recommend that you use MySQL 8 or greater, due to its improved support for multilingual content in Totara. We strongly recommend that you use a case-sensitive, accent-sensitive collation (which MySQL 5.7 does not support). We also recommend a 4-byte-compatible character set (utf8mb4) to ensure full support for characters such as emojis. MySQL must be using the Barracuda file format. To create your database: ```plaintext CREATE DATABASE {dbname} DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_0900_as_cs; ``` For security we recommend you use a dedicated database user who has access just to the Totara database. #### MariaDB A case-sensitive, accent-sensitive collation is available from MariaDB 10.10 onwards. For Totara 20 we recommend MariaDB 11.4. We strongly recommend that you use a case-sensitive, accent-sensitive collation. We also recommend a 4-byte-compatible character set (utf8mb4) to ensure full support for characters such as emojis. MariaDB must be using the Barracuda file format. To create your database: ```plaintext CREATE DATABASE {dbname} DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_uca1400_as_cs; ``` For security we recommend you use a dedicated database user who has access just to the Totara database. #### PostgreSQL To create your database: ```plaintext createdb -E utf8 {dbname} ``` For security we recommend you use a dedicated database user who has access just to the Totara database. If you are running PostgreSQL 14.0 or 14.1, the **enable_memoize** setting must be turned off. #### MSSQL If you are installing Totara as a sysadmin then your database user must have permission to alter server settings: ```plaintext ALTER SETTINGS(SERVER) ``` Full text search must be enabled; see Full text search in MSSQL Server [LINK]. For security, we recommend you use a dedicated database user who has access just to the Totara database. Alternatively you can install Totara as a non-sysadmin user using the following SQL: ```plaintext -- First create a new user, change username and password to match your requirements CREATE LOGIN testuser    WITH PASSWORD = 'TestUser1'; GO -- Now make sure this user can install the site, ALTER SETTINGS permissions is needed for this USE master; GRANT ALTER SETTINGS TO testuser; -- For the database (substitute with the database name of your choice) -- create a login for the user and make sure he has the permissions needed USE totara_13; CREATE USER testuser FOR LOGIN testuser; -- Make sure the user can create tables, read and write data ALTER ROLE db_ddladmin ADD MEMBER testuser; ALTER ROLE db_datareader ADD MEMBER testuser; ALTER ROLE db_datawriter ADD MEMBER testuser; -- Create a custom role CREATE ROLE db_totara; -- This is needed to view any definition created by Totara GRANT VIEW DEFINITION TO db_totara; ALTER ROLE db_totara ADD MEMBER testuser; GO ``` After Totara is installed the following SQL will ensure Totara is fully usable without sysadmin privileges: ```plaintext -- Take away the ALTER SETTINGS permission, it's not needed anymore USE master; REVOKE ALTER SETTINGS TO testuser; USE totara_13; -- Make sure the user role has access to Totara's custom stored procedures GRANT EXECUTE ON dbo.GROUP_CONCAT_D TO db_totara; GRANT EXECUTE ON dbo.GROUP_CONCAT_S TO db_totara; GRANT EXECUTE ON dbo.GROUP_CONCAT_DS TO db_totara; GRANT EXECUTE ON dbo.GROUP_CONCAT TO db_totara; GO ``` ### Web server Totara is a web-based application and relies upon a web server to operate. Totara is officially supported when run via Apache, IIS and Nginx. Totara source code contains a **server** directory. The web server needs to be configured to serve this directory and its children only. The structure of the code base changed between Totara 12 and Totara 13. It is important that your web server serves the **server** directory only. It is a security concern if your web server is configured to serve the top-level source code directory as that exposes more information than is intended. When configuring the web server we recommend you harden it following the best practices for your chosen web server. The following points can serve as a guide for Totara best practice for production sites: - Disable directory listings - Disable serving of the following directories: - /server/**/tests/ - /server/**/amd/ - /server/**/templates/ - /server/**/classes/ - Disable serving of the following file types: - /server/*/.txt (access should only be allowed to checknet.txt) - /server/*/.md - /server/*/.xml - /server/*/.pem - All files starting with "." - Disable serving of the following files: - /server/package.json - /server/package-lock.json - /server/composer.json - /server/composer.lock - /server/Gruntfile.js - Ensure errors are being written to a known log file location. If you experience any problems and seek support they will often ask you to check the web server error logs. If you are using Apache + mod_php, CGI, or PHP-FPM, and intend to use the Totara Mobile app then you will need to additionally add the following directive to your VirtualHost entry for the site in order for Apache to correctly pass the authentication headers required by the mobile app: ```php SetEnvIf Authorization "(.*)" HTTP_AUTHORIZATION=$1 ``` If you are using Apache + mod_php, CGI, or PHP-FPM we recommend you add the following directives to your Apache VirtualHost entry to ensure that these headers are preserved: ```php SetEnvIf Content-Type "(.*)" HTTP_CONTENT_TYPE=$1 SetEnvIf Accept "(.*)" HTTP_ACCEPT=$1 ``` Information on the required PHP environment can be found on the [server system requirements](/totara-20/docs/server-system-requirements) page. ### Data directory Totara requires access to a data directory in which to store user data, cache files, temporary files etc. This directory must be readable and writable by the web server user. In a horizontally scaled environment all web servers must have access to the data directory. It must be shared by them. ## Installing Totara ### Getting the code The Totara code is available for Totara Alliance Partners only. We provide access to the source code via a GIT version control repository. To access the code you will need to have your ssh public key added to our git server. For any assistance with this please file a ticket with the support desk. For the main Totara code: ```plaintext git clone ssh://git@code.totaralms.com/totara-txp.git ``` For the Totara Mobile app code: ```plaintext git clone ssh://git@code.totaralms.com/totara-mobile.git ``` ### Building Totara via an intermediate environment From Totara 13 to 19 many third-party libraries were distributed via the libraries/required directory. From Totara 20 this directory is no longer included automatically. Instead third party libraries must be installed ahead of the site install/upgrade using [composer](https://getcomposer.org/). If you are using the zip distribution of Totara then these steps are not needed, the distribution will come with the PHP libraries included. > [!WARNING] > We recommend building the Totara source code on a separate build server, and transferring the artifacts to your production environment. **What you should have pre-configured** - PHP CLI installed for the version you will run the site as - Composer installed and available [Introduction - Composer](https://getcomposer.org/doc/00-intro.md) - git if you are cloning via our distribution repositories [https://git-scm.com/](https://git-scm.com/) - The ability to zip and unzip files via the zip utility (or some other method to ship the generated files) (optional) Why is this necessary? Running git or composer in a production environment is not advised. The safest way to build Totara is to run the build commands on one server and take the generated output and ship it to your production environments to run the final install/upgrade scripts. > For more information about Totara and Composer, please see the [Third-party libraries with Composer](/totara-20/docs/third-party-libraries-with-composer) page. ### Running the build 1. Confirm that your PHP version matches a version listed in the readme.md file `php --version` 2. Confirm you’re running PHP not as a root user. 3. Make sure you’re inside the root folder, the same directory that `README.md` and .`gitignore` exist in, **not the server folder**. 4. Building PHP Libraries (required). This is a required step: 1. Run the composer install command (depending how you installed it). ```bash # If composer is available globally composer install --no-dev -o # If you've installed composer locally php composer.phar install --no-dev -o ``` 2. Confirm that the vendor/ directory was created. 5. Add on any customisations. If you install any extra plugins, we recommend you add their source now. 6. Finally you should have a copy of Totara that’s ready for distribution. You can zip it up or resync it or use another method to distribute it to your production server. 7. From your production server you can then run the regular install or upgrade commands as noted below. ### CLI installation We strongly recommend that installation and upgrade be completed through the command line interface. This command must be run as the web user (in this case www-data): ```php sudo -u www-data php server/admin/cli/install_database.php --agree-license --adminpass=mypassword123 ``` There are a number of other optional arguments that can be provided to minimise post-install setup: ```php --lang=CODE           Installation and default site language. Default is en. --adminuser=USERNAME  Username for the admin account. Default is admin. --adminemail=STRING   Email address for the totara admin account. --fullname=STRING     Name of the site --shortname=STRING    Name of the site ``` Once the CLI install is finished you can go to the site homepage and log in using the admin credentials for further setup. ### Web installation Web installation can be performed by navigating to the **wwwroot** that was set in the **config.php** file and following the on-screen instructions. ### Essential configuration Below is an example of a minimal **config.php** file which should be present in the top-level folder. There is a lot of optional config that can be added - see the **config.example.php** file in the top-level folder. ```php wwwroot = 'http://mytotara.com'; $CFG->dirroot = '/var/www/totara/htdocs/server'; $CFG->dataroot = '/var/sitedata/totara'; $CFG->directorypermissions = 00777; // try 02777 on a server in Safe Mode $CFG->dbhost = 'localhost'; $CFG->dbtype = 'pgsql'; $CFG->dbuser = 'dbuser'; $CFG->dbpass = 'dbpass'; $CFG->dbname = 'totaradb'; $CFG->prefix = 'ttr_'; $CFG->forceflavour = 'learn_engage'; ``` The following options are available for the **forceflavour** config, depending on which combination of products the site will be using: - learn - engage - perform - learn_perform - learn_engage - perform_engage - learn_perform_engage In addition, if you wish to use flavours then you can find more information on this in our [developer documentation](https://totara.atlassian.net/wiki/spaces/DEV/pages/121184484/Totara+flavours). ## Scheduled tasks The Totara 'cron' process is a PHP script (part of the standard Totara installation) that must be run regularly in the background. It's strongly recommended that the frequency of cron is set to be at least once per minute. The Totara cron script runs different tasks at differently scheduled intervals, which can be configured by a Site Administrator. **Do not** skip setting up the cron process on your server for your Totara. Your site will not work properly without it. For more information on the scheduled tasks, and how to set this up visit the [Scheduled tasks](/totara-20/docs/schedule-tasks) page ## Next steps - [Register your site](/totara-20/docs/register-your-site) - [Getting started with site customisation](/totara-20/docs/getting-started-with-site-customisation) - [Change your Totara flavour](/totara-20/docs/change-your-totara-flavour) Join the [Totara Community](https://totara.community/) for more resources to help you get the most out of Totara. © Copyright 2026 Totara Learning Solutions. All rights reserved.