Installing the Authoring Tool
The authoring tool is a server-based user interface for the Adapt framework.
The framework and the core plug-ins are installed as a part of the installation of the authoring tool; they do not need to be installed separately.
Upon installation, you can begin creating responsive e-learning courses.
The purpose of the authoring tool is to bring the power of the framework to non-technical persons.
This being said (and while installation is getting easier), it requires the user to manually install and configure software including git, Node.js, and MongoDB, and take steps that are typically hidden within a packaged installer. If you are not confident in doing this, we recommend you seek guidance prior to attempting an install by yourself.
The Adapt authoring tool is intended to be installed on a publicly accessible web server, but may also be installed on personal computers for use by individuals.
-
Install prerequisites.
The authoring tool and the Adapt framework depend on other software to run. We’ve got to make sure these are in place first. -
Clone the adapt_authoring project.
We’ll download the code from its repository on GitHub. -
Install the required npm packages.
We'll install some packages required by the authoring tool code. -
Run the install script. The application will be compiled and configured to your environment, ready for use.
-
Run the application. By this point we’ll have all the project pieces in place, and can log in to the authoring tool!
Tip: Some of these come preinstalled with certain operating systems. Before continuing, verify what you have already by checking for its version (also make sure it's a version that's compatible with the authoring tool).
For a full list of recommended system requirements see here
Tip: If you are new to using the command line (or if your skills are rusty), read this explanation before proceeding.
Git
Git is a tool for managing source code, and makes it easy to download and update the authoring tool codebase.If you are installing Git for the first time, don't forget to configure it:
git config --global user.name "Your Name"
git config --global user.email "youremail@domain.com"
Node.js (LTS release)
Node.js provides the JavaScript engine to run the authoring tool application, and handles the installation/updating of the tool’s dependencies (via NPM).Important: The authoring tool supports the Node.js LTS release. Please ensure your machine is using this, as you may experience compatibility issues otherwise!
Node version managers, such as nodist (Windows) or nvm (OS X, Linux), make it easy to switch between versions of node. We strongly recommended that you use one. Follow their instructions to install.
If you prefer not to use a version manager, the community wiki of Node.js provides installation instructions for various operating systems.
Verify NPM is installed: NPM (a node package manager) is used to download and install the stuff the authoring tool depends on. It comes with Node.js by default, so refer to the official Node.js installation instructions if you find you don't have it after installing Node.js.
Grunt
Grunt is a 'task runner' which handles all the necessary actions required to build the course.Tip: Windows Users Note: Run these commands in Git Bash if you installed git using default settings
MongoDB
MongoDB is the chosen database for the authoring tool.Tip: If you choose to run MongoDB manually as a background process rather than as a service, you may find using two command terminals keeps you organized. Use one to start and stop mongod and another to complete the authoring tool installation and to run it.
Tip: Installing Compass is optional. System administrators and developers may find it or Robo 3T helpful.
IMPORTANT: MongoDB must be running in order for subsequent installation steps to succeed. Do not assume that installing Mongo started the service. Verify before proceeding. Visit Ensure MongoDB is Running for tips for verification.
The Adapt authoring tool is hosted here on GitHub. You need a copy of it on your computer.
Running the following command will create a folder named "adapt_authoring" that will contain the project source code. Using the command prompt, navigate to a folder where you want this to be created. Then run the following command.
git clone https://github.com/adaptlearning/adapt_authoring.git
It is essential that you verify that the MongoDB service has started and is running. Installation will fail if the MongoDB service has stopped. (If you installed on Linux, the service should automatically start. OSX users may have to manually run mongod from a terminal. Windows users may have to start it manually; verify using the Services tab of the Task Manager.)
Navigate to the adapt_authoring folder you cloned earlier to make it the current working directory. Run the following command:
npm install --production
Note: The --production option bypasses the installation of dependencies which are only relevant to development, such as the unit testing facilities.
This process can take a few minutes to complete. If this script completes successfully, you can now run the install script!
If any error occurs, read the output, and try to determine if you forgot to install one of the prerequisites or if one failed to install properly. If you need assistance troubleshooting, consult the Adapt community's Technical Discussion Forum.
Tip: MongoDB must be running for some npm packages to install. Errors involving ECONNREFUSED and app.db are cause to ensure MongoDB is running.
You can now install and configure your new authoring tool for your requirements.
Tip: Most configuration questions will appear with a default answer already in place, so most times you can just accept these default values by pressing the Enter key.
Tip: The questions relating to the 'super user account' are not the same as the SMTP service or the master tenant. The super user's email address and password will be used to login to the authoring tool.
Note: Configuration questions will ask about SMTP service, SMTP username, SMTP password, and Sender email address. The authoring tool uses email addresses as user names and can reset passwords via e-mail. If you do not intend to use this feature, just accept the default values for all related questions.
Note: You can change any of your answers once the install has completed successfully, so don't worry if you don't know the answer.
Note: You can find no interactive options for this install here
node install
If all goes well, you'll receive the following message: Installation completed successfully, the application can now be started with 'node server'.
First you're going to start the authoring tool Node.js application, and then you can test the installation was successful by attempting to access it from a web browser.
-
Run the start command (cmd tips)
node server
As the server starts, it will report in the terminal:Server started listening on port <YOUR_PORT>
(To stop the server, make the terminal the active window, then press Ctrl+C.) -
Try it out!
Open your favourite (standards compliant 👼) web browser, and navigate to:localhost:<YOUR_PORT>
When the login page appears, enter the super user's e-mail address and password.
If you experience difficulties during installation, there are two main places you should be seeking help.
The technical discussion forum has a wealth of posts on installation advice; the likelihood is that someone else has already encountered and solved your problem.
If requesting help, please provide as much relevant information as possible; the less (useful) information you give, the less likely you'll get a response. Try to at least include the following:
- Your computer's operating system
- The version of Adapt you're attempting to install
- What steps you took before trouble was encountered
- Any error messages that were displayed
Tip: Refrain from pasting long server logs, as this makes your post hard to read, and therefore less likely to receive responses.
We also have an active (and very friendly) community in the Adapt Gitter rooms.
The same rules as above apply when asking questions here. Also, please respect the users in the room and don't demand an instant response; everyone is in there voluntarily, and often in addition to a full-time job.
Help Us Improve: If you notice errors or omissions in these instructions, please inform us by leaving a comment in Issues.
