2.1 System Setup

This section provides instructions to IT staff on how to download and configure the EDSCLS platform package; set up the URL and e-mail; update your server with the latest version of the source code; and access the MySQL database. The instructions in this section should be performed by IT staff with administrative permissions to a web server.

The EDSCLS package is a virtual disk to be used to create a virtual machine.[1]  VirtualBox is the recommended virtualization application for creating and hosting virtual machines using this virtual disk. This guide will provide instructions using VirtualBox, which is free software.

N O T E
VirtualBox must be installed on a physical server, not another virtual machine. Running a virtual machine within another virtual machine, or nested virtualization, is neither supported nor recommended. If VMWare is used, then VirtualBox cannot be used, and that installation is outside the scope of this guide.

The image of the EDSCLS platform consists of a Linux operating system, Apache web server, MySQL Relational Database Management System, .NET Core web code,[2] and the EDSCLS application.

W A R N I N G
The EDSCLS platform requires MySQL to function properly. Changing the database management system to MS SQL server, for instance, will corrupt the platform.

The following are the key technical requirements, followed by more specific instructions, for the platform’s installation:

  • Windows (Server 2008 or later, Windows 7 or later), Linux (kernel 2.6 or later), or Mac OS X (10.9 or later);
  • at least 8 GB to 16 GB of RAM;
  • at least 20 GB of free hard disk space, plus additional space depending upon the number of total respondents (about 1 MB per 100 respondents);
  • a high-speed internet connection with at least 2 Mbps upload and download speeds;
  • a static IP and URL to which to bind the website; and
  • a Secure Sockets Layer (SSL) certificate[3]
N O T E
These are the basic requirements for hosting the EDSCLS. Servers that meet these requirements are capable of using the EDSCLS platform for data collection and reporting; however, some additional configurations or permissions are required in order to use the platform’s e-mail function for dissemination of usernames (see 2.2.9 Respondent Usernames Dissemination) or to access the surveys from devices outside of your network. The following decision trees may help you decide how the EDSCLS platform can be installed and configured at your education agency.

The EDSCLS can accommodate up to 500 concurrent[4] respondents using the minimum requirements as detailed above. Please note that a single server may not be able to support 500 concurrent users if there are network bandwidth restrictions, limited operating system capacity, and insufficient RAM. Up to 500 additional concurrent respondents can be supported if dual servers are used with the following server settings: 8 vCPU, 16GB Memory, 100GB disk.

If a user wishes to support more than 500 concurrent respondents, multiple copies of the EDSCLS platform can be installed and results from the multiple copies can be combined (see 2.2.11 Exporting and Importing Respondent-Level Survey Results). Due to these load limitations, it is recommended that large education agencies (for example, State Education Agencies) install multiple copies of the platform. Large education agencies may also wish to reduce the load on the EDSCLS platform by staggering their survey administration such that a limited number of students attempt to access the platform at once.

N O T E
If you are a large agency and plan to install multiple copies of the platform, it is useful to think strategically about how participants will be divided between the multiple copies. For instance, if you are a State Education Agency, perhaps you assign specific districts to a platform based on their size. Or, if you are a large school district, perhaps you assign your middle schools to one platform and your high schools to another, so that you don’t exceed the 500-participant limit.

Installation

A diagram shows the decisions during installation that lead to installing on a local physical server or storing in a cloud-based server. In most cases the process indicates to install on a cloud-based server. It indicates to install on a local server in two cases: first, if participants only on your computer network to access the surveys, and second, if you can assign a static IP address to the EDSCLS server, have a valid SSL certificate, and if necessary, open a port on your firewall to allow outside internet access.

Username Dissemination

A diagram shows choices for username dissemination. If you have permission to configure an email server for EDSCLS, follow the steps to configure email service. Otherwise, plan to disseminate usernames outside of EDSCLS using regular email or manually on paper.

Before beginning the download and installation steps, you should first save your current work and exit from all other programs that might be running.

The estimated time for each step is listed below:

  • Download the ~11.5 GB Virtual Machine Disk (VMDK) of the EDSCLS platform from the NCSSLE website (10 minutes);
  • Download and install Oracle VM VirtualBox (5 minutes);
  • Configure the EDSCLS virtual machine (15 minutes);
  • Create the URL and make it accessible via the web (5 minutes) and configure the virtual machine to send e-mail (5 minutes); and
  • Access the MySQL database (optional). This step is needed only when you want to view or modify the EDSCLS database.

The following section provides step-by-step instructions for installing and configuring the EDSCLS on a physical machine.

Updates to the EDSCLS virtual machine, including source code changes and security patches, will be released periodically and posted on the NCSSLE website at https://safesupportivelearning.ed.gov/edscls. Known platform users will be notified by e-mail.

  • Starting with VM 3.2, the version number is located in the bottom right-hand corner of the administrator dashboard. Previous versions of the platform do not display the version number.
  • Following the release of VM 4.1, the VM numbering scheme was modified so that users could more easily identify the kind of enhancements made to the platform. The second digit of the VM number will go up when VM releases include source code changes (e.g., 4.2.0); when VM releases only include routine security patches, the third digit will go up (e.g., 4.1.1).

If you choose to update the version of your survey platform, you have three options:

  1. Replace your virtual machine with the newer version.
N O T E
Before replacing the virtual machine with a newer version, you should export the data that have been collected. If you do not export the data before deleting the older version of the virtual machine, you will lose the data that the previous version contains. For instructions on exporting survey data, please see 2.2.11 Exporting and Importing Respondent-Level Survey Results.
  1. Download the new EDSCLS virtual machine and house both the new version and the previous version on your server.
N O T E
If you are housing more than one virtual machine on your server, the requirements for memory and disk space should be multiplied by the number of virtual machines you are actively storing.
  1. Update your existing EDSCLS virtual machine using a script. For instructions, please see https://safesupportivelearning.ed.gov/updating-existing-edscls-instance.
N O T E
It is highly recommended that users take a full backup of their instance before running any updates to ensure they can revert back to a previously functional version if errors arise during the patching and update process.

If you are currently collecting data, we recommend you NOT transition to the new EDSCLS VM until your data collection is complete.

  1. To download the EDSCLS package:
    1. Download the VirtualBox image of the EDSCLS platform from https://safesupportivelearning.ed.gov/edscls/administration.
    2. Unzip the EDSCLS file in a location you remember, so it can be found in section B.4 below.
      1. On Windows: Open File Explorer and navigate to the folder with the zip file. Right click the zip file and select “Extract All” and then follow the instructions to choose the location, and then click “Extract” for the files to be unzipped and copied to the specified location.
      2. On a Mac: Open Finder, navigate to the folder where the zip file is located, then double click the zipped file for the files to be unzipped in the same folder the zipped file is located.
  2. To download and install Oracle VM VirtualBox
    1. Download the latest version of VirtualBox for your server’s operating system (either Windows, Linux, or Mac OS X) from https://www.virtualbox.org/wiki/Downloads.
Screenshot of the webpage to download VirtualBox
Download VirtualBox
  1. Install VirtualBox.

N O T E
For step-by-step installation instructions, refer to https://www.virtualbox.org/manual/ch02.html.

The EDSCLS virtual machine is scanned and updated periodically. It is recommended that users check the EDSCLS webpage at least once every other month for updates.
  1. To configure the virtual machine:
    1. Open Oracle VM VirtualBox and click on the “New” button on the main tool bar.
Screenshot of the Virtualbox computer application with the New button highlighted
Open VM VirtualBox
  1. Enter a descriptive name in the "Name" text box (e.g., "EDSCLS") and select a destination folder in the "Machine Folder" drop-down box for the new virtual machine. The Machine Folder can be any location you will remember on your computer, for example on a Windows computer, the location could be "C:\Users\administrator\VirtualBox VMs" or "C:\EDSCLS", or on a Mac /Users/administrator/VirtualBox VMs" or "/Users/administrator/Sites/edscls". Regardless of your own server’s operating system, select "Linux" from the "Type" drop-down box. Select "Ubuntu (64-bit)" from the "Version" drop-down box. Then click on the "Next" button.

Screenshot of the Virtualbox page for entering a name, folder, and type for your installation
Enter Descriptive Name
  1. For the memory size, specify a minimum of 1,024 MB, and preferably 16,384 MB, depending on your server’s specifications. Then click on the “Next” button.
Screenshot of Virtualbox memory size settings
  1. Select the “Use an existing virtual hard disk file” option button. Click on the Folder icon button.
Screenshot of hard disk settings

Click on the “Add” button and open the downloaded and unzipped EDSCLS VirtualBox image from Step A.2 above. Then click on the “Choose” button.

Screenshot of Virtualbox add image page

Click on the “Create” button. The new virtual machine should now appear on the left side of the window.

Screenshot of Virtualbox hard disk creation or selection page
  1. Make sure the EDSCLS virtual machine is selected on the left, then click on the “Settings” button on the main tool bar.
Screenshot of Virtualbox menu with settings item selected
  1. From the Settings window, select “Network” on the left side and click on the “Advanced” Expand icon. Select “PCnet-FAST III (Am79C973)” from the “Adapter Type” drop-down box. Click on the “Port Forwarding” button, which will open the Port Forwarding Rules window.
Screenshot of Virtualbox network settings
  1. From the Port Forwarding Rules window, click on the Add icon on the far right to add a new record. Under the “Name” column, enter a descriptive name (e.g., “EDSCLS Port”). Under “Host Port,” enter “80” or specify a different port of your choosing. Under “Guest Port,” enter “80”. Then click on the “OK” button to close the window.
Screenshot of Virtualbox port forwarding rules settings
  1. Click on the “OK” button to close the Settings window.
Screenshot of Virtualbox memory settings menu
  1. To start the EDSCLS virtual machine, make sure it is selected on the left, and then click on the "Start" button on the main tool bar. The machine will take about a minute to boot up.
Screenshot of Virtualbox menu with the Start virtual machine option selected
  1. If the system only provides a black screen after trying to start, and never boots, shutdown the machine by clicking the X in the corner and selecting “Power off the machine” from the prompt.Make sure the EDSCLS virtual machine is selected on the left, then click on the “Settings” button on the main tool bar, then click the “Settings” button.
  1. Increase the Base Memory settings, click OK, and try to start the machine again per step 9 above.
  1. To log in to the EDSCLS virtual machine, press the Enter key.
Screenshot of virtual machine logon screen

If you’re logging on to the EDSCLS virtual machine for the first time, enter “OsunXiboGyP4x” in the “Password” text box. Otherwise, enter the new password you have chosen. The password will be hidden. Then press the Enter key.

Screenshot of virtual machine logon screen with password box filled in
  1. If you’re logging on to the EDSCLS virtual machine for the first time, enter “OsunXiboGyP4x” again in the “Current password” text box. The password will be hidden. Then press the Enter key.

Enter a new password in the “new password” text box. The password will be hidden. Then press the Enter key.

Enter the same new password in the “Retype new password” text box. The password will be hidden. Then press the Enter key.

Screenshot of virtual machine change password screen
  1. Click on the “File” menu, then select “Close” to power off the EDSCLS virtual machine.
Screenshot of virtual machine menu with the file close menu selected

From the Close Virtual Machine window, select “Power off the machine”, then click on the “OK” button.

Screenshot of virtual machine logon screen with the Power off the machine opton selected

Once the EDSCLS virtual machine has been downloaded, installed, and configured, the following instructions should be performed by a Network/System Administrator, as there may be security and firewall issues involved.

  • D.    To set up the URL and e-mail:
    1. Log in to your hosting provider’s web portal and navigate to the DNS section. Create a new record with your domain name without “www” (e.g., “edagency.edu”) and the static IP address of the computer hosting the EDSCLS virtual machine.
    2. To make the domain accessible with “www” at the beginning as well, create a CNAME record with “www” and “@”.
    3. To configure your server to send e-mail, create MX records containing information about your e- mail service provider.
    4. To configure the hostname and DNS, first, launch Chromium to load Webmin.
  1. Restart the virtual machine from VirtualBox Manager.
Screenshot of Virtualbox menu with the Start virtual machine option selected
  1. Log in to the EDSCLS virtual machine.
Screenshot of virtual machine logon screen
  1. Click on the Chromium Web Browser icon button.
Screenshot of Linux desktop menu with Chromium Web Browser selected

The browser should load Webmin at URL “localhost:10000”. If not, then type it in manually. NOTE: If Chromium fails to load Webmin, refer to section 2.1.2 Troubleshooting.

From the Login to Webmin window, enter “adminuser” in the “Username” text box and enter the new password you have chosen in the “Password” text box. The password will be hidden. Then click on the “Sign in” button.

Screenshot of Webmin logon screen

Click on the blue menu button on the upper left corner.

Screenshot of Webmin menu icon

Select “Networking” on the left side; then select “Network Configuration.”

Screenshot of Webmin menu with Networking and Network Configuration selected

Then click on the “Hostname and DNS Client” button.

Screenshot of Webmin menu with Hostname and DNS Client selected

In the “Hostname” text box, replace “edscls.com” with your URL without the “www”. Then click on the “Save” button.

Screenshot of Webmin settings for Hostname and DNS Client

Click on the blue menu button on the upper left corner.

Screenshot of Webmin menu icon

To set the hostname of the mail system, select “Servers” from the menu on the left side of the window; then select “Postfix Mail Server.”

Screenshot of Webmin menu with Servers and Postfix Mail Server selected

Then click on the “General Options” button.

Screenshot of Webmin Mail Server menu with General Options selected

Scroll down and replace “edscls.com” with your URL without the “www” in the “Internet hostname of this mail system” text box. Then click on the “Save and Apply” button.

Screenshot of Webmin Mail Server General Options screen

Click on the back button on the upper left corner.

Screenshot of Webmin menu icon

To configure SMTP mail with your existing mail server, select “Servers” on the left side; then select “Postfix Mail Server.” Then click on the “SMTP Authentication And Encryption” button.

Screenshot of Webmin Postfix Mail Server menu with SMTP Authentication and Encryption selected

Scroll down. For the “Enable TLS encryption?” drop-down box, select “Never”. For the “Send outgoing mail via host” radio button, select the second option and enter the SMTP hostname. For the “SMTP login to outgoing mail host” radio button, select the second option. Enter the SMTP host username in the “Login as” text box and enter your SMTP host password in the “with password” text box. Then click on the “Save and Apply” button. If this step is unsuccessful, revert back to the default configuration (i.e., “Deliver directly”, “None needed”).

Screenshot of Webmin Mail Server Authentication and Encryption settings screen

Make sure to provide the Survey Administrator with the URL and e-mail address you created in the steps above.

Once installation and configuration are complete, please work closely with the Survey Administrator to ensure that the EDSCLS platform is functioning properly. You may encounter the following issues, and here are some suggested solutions.

  1. If usernames are not being generated:
  1. Restart your server and/or the EDSCLS virtual machine.
  2. Recreate the data collection and generate the usernames again.
  3. In older versions of the platform, problems generating usernames may be due to the length of a school name. When you add a new school and enter a school name that is more than 50 characters long to an older platform, it is unable to generate usernames. Newer versions of the platform, VM 4.0 and later, include a 60-character limit on school name.
  1. If e-mails are not being sent:
  1. Repeat the steps under 2.1.1 D. To set up the URL and e-mail to verify the information entered is correct.
  2. Verify your settings with your e-mail service provider.
  1. You might need to use an IP address if no DNS name is available or resolves.
  2. Make sure you include the port number they require if not standard. For example, smtp.gmail.com uses port 587.
  3. You might need to enable (or disable) SASL for use with your provider. In Webmin > Servers > Postfix Mail Server > SMTP Auth & Encryption, for “Use SASL SMTP authentication?” select Yes (or No).
  1. Make sure your firewall and virus scanner on the host allows e-mails to be sent from the virtual machine. For example, McAfee needs to have an exception for not preventing Virtualbox.exe to send e-mail.
  2. If you are running EDSLS VM version 4.2.1 or higher and are trying to use it along with
    Microsoft Exchange Server, you must apply patches provided by Microsoft to allow Exchange to
    support TLS version 1.2.
  1. If Chromium reports problems with the signing certificate when loading Webmin:
    1. Close and restart the EDSCLS virtual machine. Alternatively, open a terminal inside the virtual machine and type “reboot”.
N O T E
If you are using an older version of the platform, there is an intermittent problem reported with Midori that is usually cleared up after a reboot. This will reset the network communications and fix minor filesystem corruption that can happen in a virtual machine that is interrupted by power outage or sudden shutdown.
  1. Test the site from the virtual machine:

To test that the site is running from within the VM, a system administrator can open the Chromium web browser, navigate to https://localhost and can log in and interact with the site directly from within the virtual machine.

  1. If you can load the site, but when logging in (1) nothing happens within Chromium on the virtual machine using localhost, the local IP address, or the hostname and (2) you see a CORS error in the web browser’s developer console, the CORS issue is due to the browser limiting access to specific origins. Users can modify the allowed origins within the configuration files of the code if needed to resolve the issue.

To add a new origin:

  1. On the virtual machine, open a terminal window.
  2. Navigate to the directory that holds the web code.
    • Cd /var/www/scls/api/
  3. Open (as an administrator) the configuration file(s). For example, using vi as the text editor:
    • Sudo vi appsettings.Prod.json
  4. Update the origins list to include your IP address or domain name (example below). PLEASE NOTE: Each line, except the last must end with a comma, and the URLs cannot have a backlash at the end.
  1. Save the file using the commands (if using vi as the text editor):
    • Escape
    • :wq
    • Enter
  1. Repeat steps 3-5 for the other app settings files.
  1. appsettings.Development.json
  2. appsettings.Qa.json
  1. Navigate to the folder /var/www/scls/web/conf

Cd /var/www/scls/web/conf

  1. Open (as an administrator) the site.json file.  For example, using vi as the text editor:

Sudo vi site.json

  1. Change the baseURLs your URL, leaving the port as is. For example:

  1. Save the file (if using vi as the text editor)
  • Escape
  • :wq
  • Enter
  1. Restart the virtual machine.
  2. Log back in, and open Chromium to try to access the site again from both localhost, IP address, or site URL – all should now work.

American Institutes for Research

U.S. Department of Education

The contents of the National Center on Safe Supportive Learning Environments Web site were assembled under contracts from the U.S. Department of Education, Office of Safe and Supportive Schools to the American Institutes for Research (AIR), Contract Number  91990021A0020.

This Web site is operated and maintained by AIR. The contents of this Web site do not necessarily represent the policy or views of the U.S. Department of Education nor do they imply endorsement by the U.S. Department of Education.

©2024 American Institutes for Research — Disclaimer   |   Privacy Policy   |   Accessibility Statement