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.
Install Ubuntu 20.04 server edition (or other supported distro)
Note: If you are duplicating an existing Submitty installation onto a new server, you should synchronize
/etc/gshadowbefore installing the rest of Submitty to avoid mismatched UIDs and GIDs of the Submitty users.
- Run the bootstrap script:
bash -c "$(curl -s https://raw.githubusercontent.com/Submitty/Submitty/master/.setup/bootstrap.sh)"
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:
- Database Host / Port. If you already have your database server installed and set up, you
will most likely just specify
localhostfor the Database Host and
5432for the Database Port, or just
/var/run/postgresqlfor Database Host.
- Submitty Database User/Role and Password. This 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.
- Timezone. Pick from the list of PHP timezones.
- Main Site URL.
- Version Control System (VCS) URL. This is used mostly to allow students to submit their homework through private repositories hosted on the submitty server. See Facilitating Student Submissions via GIT.
- Institution Name.
- Authentication Method. PAM and LDAP authentication requires the sysadmin to make accounts ahead of time for students and give them a password. Database authentication lets students create their own passwords.
- Database Host / Port. If you already have your database server installed and set up, you will most likely just specify
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
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.4/fpm/php.iniand find the entry for
disable_functionsand make sure the list of disabled functions contains:
Note: Ubuntu 20.04 is using 7.4, but older versions might be using
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/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.confto 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).
You may also want to comment out the directory specific portions of
/etc/apache2/apache2.confso 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_domainthrough a browser.
We recommend that you should leave the PostgreSQL setup unless you know what you’re doing. If you are running PostgreSQL on the same server as Submitty, we recommend using the UNIX socket, and to disable TCP if unused. By default, the socket is found at
/var/run/postgresql, and disabling TCP is done through editing the
pg_hba.conffile for PostgreSQL. Using the socket improves query responses as it will not need to go through the TCP stack. Disabling TCP if not used will improve security as it prevents anyone from attempting to get into the DB from the outside world. To disable TCP, you would comment out all the lines that start with
pg_hba.conffile. Setting the socket to be used for Submitty is done by running
.setup/CONFIGURE_SUBMITTY.pyand setting the database host to the socket (e.g.
- If you intend to run the Student Registration Feed, do not disable TCP.
Test apache config with:
If everything looks ok, restart apache with: `service apache2 restart’
- We suggest reviewing Additional System Customizations that might be appropriate for your installation.
- I cannot connect to PAM!
Submitty authenticates PAM through the python module python-pam using the
submitty_cgiuser. By default, we assume you’re going to use local accounts for authentication and as such
submitty_cgihas been added to the
shadowgroup so that it can read /etc/password which is necessary for PAM to work.
To test PAM, you can do:
$ sudo su submitty_cgi -c python3 Python 3.5.1 (default, Jun 29 2016, 13:08:31) [GCC 4.9.2] on linux2 Type "help", "copyright", "credits" or "license" for more information. >>> import pam >>> p = pam.pam() >>> p.authenticate('username', 'password') True
passwordmatch some account on the machine).
If you get an error about module pam not being found, that means that
submitty_cgidoes not have the proper permissions to the module and if you get False on authentication, then
submitty_cgidoes not have the proper permissions to check the right files via PAM.
If the PAM module is functioning, but Submitty is still erroring during user authentication, check
/var/log/apache2/submitty.logfor these entries with a recent timestamp:
AH01630: client denied by server configuration: /usr/local/submitty/site/cgi-bin/pam_check.cgi
POST /cgi-bin/pam_check.cgi HTTP/1.1" 403 470 "-" "-"
This indicates that apache is blocking the execution of Submitty’s authentication code. Try adding this line to
submitty.confunder the heading
Require all granted
- Installation Fails During NTP Setup
- This is indicative that you installed the Ubuntu 20.04 “Live” server. “Live” server is unsupported. Please install the traditional server. Please see the Server OS page for more details.