These instructions will help guide you to installing Submitty onto a server (whether on a dedicated machine or a VM).

Note: We assume that you’re installing Submitty on a dedicated machine. If this machine is used for other things, you may need to adapt the instructions below and install_system.sh for your needs (as the script installs all of the dependencies that Submitty depends on).

Note: Part of the installation process consists of changing the default umask for users from 002 to 027 to better protect the files that Submitty generates during operation as well as any instructors who are SSHing into the machine and so as to not potentially allow other access to confidential material. This does mean that installing certain things (like python packages through pip) into a global scope will need to have their permissions updated or else only the owner will be able to read/execute it.

Note: These instructions should be run under root/sudo.

  1. Install Ubuntu 18.04 server edition (or other supported distro)

    Note: If you are duplicating an existing Submitty installation onto a new server, you should synchronize /etc/passwd, /etc/shadow, /etc/group, and /etc/gshadow before installing the rest of Submitty to avoid mismatched UIDs and GIDs of the Submitty users.

  2. Run the bootstrap script:
    curl https://raw.githubusercontent.com/Submitty/Submitty/master/.setup/bootstrap.sh | bash
    

    or clone the git repository and run the installer (requires git and lsb-release to be installed):

    mkdir -p /usr/local/submitty/GIT_CHECKOUT
    git clone https://github.com/Submitty/Submitty.git /usr/local/submitty/GIT_CHECKOUT/Submitty
    cd /usr/local/submitty/GIT_CHECKOUT/Submitty
    bash ./.setup/install_system.sh
    

    Note: During installation, you will be asked several questions by the CONFIGURE_SUBMITTY.py script. Pressing enter will select the default option. These questions are:

    1. Database Host
    2. Submitty Database User/Role
    3. Submitty Database User/Role Password
    4. Timezone
    5. Main Site URL
    6. Version Control System (VCS) URL
    7. Institution Name
    8. Authentication Method (PAM or Database)

    If you already have your database server installed and set up, you will most likely just specify localhost for the Database Host. Note: The database user is not a Linux user, just a user/role within the database server. If you don’t already have a role for the submitty database user/role, the script will create that for you with the specified name & password.

  3. Run installations specific to your university.
    For example: RPI Computer Science specific installations

    sudo bash /usr/local/submitty/GIT_CHECKOUT/Submitty/.setup/distro_setup/ubuntu/rpi.sh
    
  4. Edit PHP Settings

    We recommend for security that you modify your PHP installation and disable certain PHP functions. To do this, edit /etc/php/7.2/fpm/php.ini and find the entry for disable_functions and make sure the list of disabled functions contains:

    popen,pclose,proc_open,chmod,php_real_logo_guid,php_egg_logo_guid,php_ini_scanned_files,php_ini_loaded_file,readlink,symlink,link,set_file_buffer,proc_close,proc_terminate,proc_get_status,proc_nice,getmyuid,getmygid,getmyinode,putenv,get_current_user,magic_quotes_runtime,set_magic_quotes_runtime,import_request_variables,ini_alter,stream_socket_client,stream_socket_server,stream_socket_accept,stream_socket_pair,stream_get_transports,stream_wrapper_restore,mb_send_mail,openlog,syslog,closelog,pfsockopen,posix_kill,apache_child_terminate,apache_get_modules,apache_get_version,apache_lookup_uri,apache_reset_timeout,apache_response_headers,virtual,system,phpinfo,exec,shell_exec,passthru,
    

    Note: Ubuntu 18.04 is using 7.2, but older versions might be using php7.0-fpm.

  5. Setup Apache

    To access Submitty’s web interface, you will need to setup Apache for it. To help you along, we provide an annotated apache configuration for Submitty at .setup/apache/submitty.conf which you can copy to /etc/apache2/sites-available/submitty.conf. You will need to replace all instances of __your_domain__ with your actual domain / IP (don’t include the https:// part of it).

    The basic commands to do this are:

    cp /usr/local/submitty/GIT_CHECKOUT/Submitty/.setup/apache/submitty.conf /etc/apache2/sites-available/submitty.conf
    a2ensite submitty
    

    The annotated apache configuration above is setup only for HTTP. For production systems, we highly recommend setting up SSL/HTTPS for the server. If your institute or organization does not have a centralized SSL provider to use, we recommend using Let’s Encrypt to get one through their certbot tool, which should handle upgrading the Submitty apache configuration to SSL for you. The generated certificates will be available under /etc/letsencrypt/live/__your_domain__. If going through a centralized provider, they should provide instructions about where to place the certificates (commonly at /etc/ssl or /etc/apache2/ssl) and the changes necessary for Apache. See this page for more details about the various settings for SSL.

    Note: It’s recommended that after setting up SSL, that you add the following block to redirect all HTTP requests to HTTPS:

    <VirtualHost __your_domain__:80>
         ServerName __your_domain__
         Redirect / https://__your_domain__/
    </Virtualhost>
    

    We also recommend that you edit /etc/apache2/conf-enabled/security.conf to ensure these options below are set to limit the information the server gives to potential hackers:

    ServerTokens Prod
    ServerSignature Off
    

    You probably want to first disable or remove the default configurations to prevent unintended access to the web server (but don’t do this if the default site is already in use).

    a2dissite 000-default
    

    You may also want to comment out the directory specific portions of /etc/apache2/apache2.conf so that you do not risk configuration conflicts with your other configurations. (Things that begin with Directory and end with /Directory).

    At this point, you should be able to access the site by going to your_domain through a browser.

  6. We recommend that you should leave the PostgreSQL setup unless you know what you’re doing. However, for the version of PostgreSQL that comes with Ubuntu Server, you may use UNIX sockets and disable the ability to connect to the DB via TCP. The socket improves query responses minorly while disabling TCP can better secure your DB if you don’t plan to connect to it via localhost, IP, etc. The socket by default is run at /var/run/postgresql. To disable TCP, you will need to edit /etc/postgresql/9.5/main/pg_hba.conf and disable all the lines that start with host and hostssl. You will also have to modify /usr/local/submitty/.setup/INSTALL_SUBMITTY.sh and change DATABASE_HOST to point to the socket, and then re-run the script.

    NOTES:

    • When using Ubuntu 18.04, the configuration file path to disable TCP is /etc/postgresql/10/main/pg_hba.conf.
    • If you intend to run the Student Auto Feed, do not disable TCP.
  7. Test apache config with: apache2ctl -t

    If everything looks ok, restart apache with: `service apache2 restart’

Troubleshooting