Difference between revisions of "Installation Manual for 2.16 on Ubuntu"

From WeBWorK_wiki
Jump to navigation Jump to search
Line 153: Line 153:
 
$ sudo systemctl restart apache2
 
$ sudo systemctl restart apache2
 
password:<wwadmin password>
 
password:<wwadmin password>
  +
  +
===Fully Qualified Domain Name===
  +
Now we have to set your server's fully qualified domain name. Note that if your network was set up automatically via DHCP, your server's fully qualified domain name should already be set up. You can check by running the <code>hostname</code> commands below.
  +
  +
Run the command
  +
sudo hostnamectl set-hostname webwork
  +
[sudo] password for wwadmin: <wwadmin password>
  +
where of course you should replace webwork by whatever your server's name is.
  +
  +
  +
You can check these settings by running the commands
  +
  +
$ hostname --fqdn
  +
and
  +
$ hostname
  +
  +
The first gives the server's fully qualified domain name (e.g. webwork.mydepartment.myschool.edu) and the second the server's name (e.g. webwork).
  +
  +
Note that if your server can not find its fully qualified domain name, certain tools (such as the Synaptic Package Manager) may not start.
  +
  +
===Test Apache===
  +
Now restart Apache
  +
  +
$ sudo systemctl restart apache2
  +
password:<wwadmin password>
  +
or
  +
$ sudo apache2ctl restart
  +
[sudo] password for wwadmin: <wwadmin password>
  +
or
  +
$ sudo service apache2 restart
  +
[sudo] password for wwadmin: <wwadmin password>
  +
  +
  +
and test your server by connecting to your
  +
server ("http://yourserver.yourschool.edu") from a browser on a remote machine. You should see the '''Apache2 Ubuntu Default Page''' indicating that Apache is running.
  +
  +
You can check Apache's status by connecting to
  +
"http://yourserver.yourschool.edu/server-status" from a browser on a remote machine in the math.yourschool.edu domain.
  +
  +
Further test Apache by connecting to
  +
"http://yourserver.yourschool.edu/server-info" from a browser on a remote machine in the math.yourschool.edu domain and you will see a page listing various
  +
information about Apache. In particular under <code>Server Settings</code> you should see
  +
  +
Server Version: Apache/2.4.41 (Ubuntu) mod_apreq2-20090110/2.8.0 mod_perl/2.0.11 Perl/v5.30.0
  +
(or something very similar) indicating that both <code>mod_apreq2</code> and <code>mod_perl</code> are installed.
  +
  +
If you have problems now or in the future, a good first thing to do is to look at the Apache error log which is located at <code>/var/log/apache2/error.log</code>. In the directory <code>/var/log/apache2/</code> you can "less" through the error log (<code>less error.log</code>), look at the last few entries (<code>tail error.log</code>) or run the command <code>tail -f error.log</code> which will display new error messages as they are appended to the file. Use
  +
<code>^C</code> to break out of <code>tail -f</code> . For example if you didn't set up access to "server-info", you can run
  +
tail /var/log/apache2/error.log
  +
and in the output you should see something similar to
  +
...[mpm_event:notice] [pid 48932:tid 140494759132224] AH00489: Apache/2.4.41 (Ubuntu) mod_apreq2-20090110/2.8.0 mod_perl/2.0.11 Perl/v5.30.0 configured -- resuming normal operations
  +
indicating that both <code>mod_apreq2</code> and <code>mod_perl</code> are installed and running.
  +
  +
== Installing a Database ==
  +
  +
This section installs either MySQL or MariaDB as the database manger for webwork. Either works well with WeBWorK.
  +
  +
=== Installing and Testing MySQL ===
  +
  +
$ sudo apt install mysql-server libdbd-mysql-perl
  +
  +
'''''This needs to be tested'''''
  +
  +
First check that MySQL is running by
  +
  +
$ sudo mysql
  +
[sudo] password for wwadmin: <wwadmin password>
  +
  +
You should see something very similar to
  +
  +
Welcome to the MySQL monitor. Commands end with ; or \g.
  +
Your MySQL connection id is 8
  +
Server version: 8.0.20-0ubuntu0.20.04.1 (Ubuntu)
  +
...
  +
  +
Type 'help;' or '\h' for help. Type '\c' to clear the current input statement.
  +
  +
  +
Enter <code>exit</code> to exit
  +
  +
mysql> exit
  +
Bye
  +
$
  +
  +
=== Installing and Testing MariaDB ===
  +
  +
Install MariaDB using the distro packages.
  +
  +
$ sudo apt install mariadb-server
  +
  +
Then we should secure the server
  +
  +
$ sudo mysql_secure_installation
  +
  +
  +
[sudo] password for wwadmin: <wwadmin password>
  +
  +
You can setup the VALIDATE PASSWORD plugin if you wish. I chose not to.
  +
  +
Next you will be asked to enter a
  +
<code>New password for the MySQL "root" user</code>. Enter your chosen MySQL <code>root</code> password. You have to enter a password but it will not be used. In Ubuntu systems running MySQL 5.7 (and later versions), the root MySQL user is set to authenticate using the auth_socket plugin by default rather than with a password.
  +
  +
You almost certainly want to answer 'Y' to all questions '''except''' possibly for the first one which asks if you want to set up a VALIDATE PASSWORD plugin.
  +
Now test that all is well:
  +
  +
$ sudo mysql
  +
[sudo] password for wwadmin: <wwadmin password>
  +
  +
You should see
  +
  +
Welcome to the MySQL monitor ...
  +
mysql>
  +
  +
Now lets check the MySQL users.
  +
There are five accounts. To see the accounts, do the following
  +
  +
mysql> SELECT user,authentication_string,plugin,host FROM mysql.user;
  +
  +
You will see a table with five users (<code>debian-sys-maint</code>, <code>mysql.infoschema</code>, <code>mysql.session</code>, <code>mysql.sys</code> and <code>root</code>).
  +
You should see that one of the five users has a valid password (which will be displayed in encrypted form) and <code>root</code> is authenticated by a socket. You can ignore the <code>mysql.session</code>, <code>mysql.sys</code> and <code>mysql.infoschema</code> users.
  +
  +
Now exit MySQL
  +
  +
mysql> exit
  +
Bye
  +
$
  +
  +
This last step is optional since currently most of WeBWorK's MySQL tables are now created using the MyISAM engine (by default -- this can be changed in the config files) rather than the MySQL default engine. Now we change MySQL's default engine. The default engine is InnoDB as of MySQL 5.5.5 (MyISAM before 5.5.5) but (at least on some hardware) InnoDB seems to be 50-100 times slower than MyISAM. So we will change the default MySQL engine from InnoDB to MyISAM. Note that this change only applies to new tables, tables already constructed will continue to use InnoDB. But we haven't created any WeBWorK tables so we don't have to change the engine for any existing tables.
  +
  +
To change the default MySQL engine from InnoDB to MyISAM do the following:
  +
  +
$ cd /etc/mysql/mysql.conf.d
  +
$ sudo cp mysqld.cnf mysqld.cnf.bak1
  +
[sudo] password for wwadmin: <wwadmin password>
  +
$ sudo nano mysqld.cnf
  +
  +
Search for <code>[mysqld]</code> and under "Basic Settings" above the "user = mysql" line add the line
  +
default-storage-engine = myisam
  +
  +
Then save the file and quit. Restart Mysql
  +
  +
$ sudo /etc/init.d/mysql restart
  +
[sudo] password for wwadmin: <wwadmin password>
  +
or
  +
$ sudo service mysql restart
  +
[sudo] password for wwadmin: <wwadmin password>
  +
  +
and log into mysql
  +
$ sudo mysql
  +
[sudo] password for wwadmin: <wwadmin password>
  +
  +
You will see
  +
  +
Welcome to the MySQL monitor ...
  +
mysql>
  +
  +
If you show MySQL engines
  +
  +
mysql> SHOW ENGINES\G
  +
  +
you should see that MyISAM is listed as the default engine:
  +
...
  +
*************************** 5. row ***************************
  +
Engine: MyISAM
  +
Support: DEFAULT
  +
Comment: MyISAM storage engine
  +
Transactions: NO
  +
XA: NO
  +
Savepoints: NO
  +
  +
Now exit
  +
mysql> exit
  +
Bye
  +
$

Revision as of 08:18, 15 May 2021

Construction.png This article is under construction. Use the information herein with caution until this message is removed.

These instructions are a work in progress.


These instructions cover the installation of WeBWorK 2.16 for Ubuntu Server 20.04 LTS, XXX and XXX. Specific OS instruction are embedded within this document

If you are just upgrading WeBWorK, especially if you already have existing WeBWorK courses, see Upgrading_WeBWorK_with_Github.

Also, it is assumed that you have an operating system installed. You can visit for instructions on installing the operating system or google how to install your favorite linux flavor. Also make sure the OS is upgraded to all patches within the version you are running.

Notation

First some short comments on notation we will be using. We will use <key> to indicate that you should press a specific key (e.g. <Enter>, <Tab>, <F12>, etc.). Sometimes we will also use e.g. <wwadmin password> to indicate you have to enter the wwadmin password.

^ will indicate the <Ctrl> key so e.g. ^X is really shorthand for <Ctrl> <X>, i.e. press the Ctrl key and hit the X key.

Install Software Packages

Ubuntu Software Packages

On Ubuntu and other Debian linuxes, the following instructions will get needed software packages installed.

Here is the list of Ubuntu packages that need to be installed.

  1. apache2
  2. cpanminus
  3. curl
  4. dvipng
  5. gcc
  6. git
  7. libapache2-request-perl
  8. libarray-utils-perl
  9. libcrypt-ssleay-perl
  10. libdatetime-perl
  11. libdata-dump-perl
  12. libemail-address-xs-perl
  13. libemail-sender-perl
  14. libexception-class-perl
  15. libextutils-xsbuilder-perl
  16. libfile-find-rule-perl-perl
  17. libgd-perl
  18. libhtml-scrubber-perl
  19. libiterator-perl
  20. libiterator-util-perl
  21. libjson-perl
  22. liblocale-maketext-lexicon-perl
  23. libmime-tools-perl
  24. libmoox-options-perl
  25. libnet-ip-perl
  26. libnet-ldap-perl
  27. libnet-oauth-perl
  28. libossp-uuid-perl
  29. libpadwalker-perl
  30. libpath-class-perl
  31. libphp-serialization-perl
  32. libpod-wsdl-perl
  33. libsoap-lite-perl
  34. libsql-abstract-perl
  35. libstring-shellquote-perl
  36. libtemplate-perl
  37. libtext-csv-perl
  38. libtimedate-perl
  39. libuuid-tiny-perl
  40. libxml-parser-easytree-perl
  41. libxml-parser-perl
  42. libxml-writer-perl
  43. make
  44. netpbm
  45. preview-latex-style
  46. texlive
  47. texlive-latex-extra
  48. unzip


To install all of these packages in one fell swoop, first become root:

$ sudo su
[sudo] password for wwadmin: <wwadmin password>

and then run the command (obviously you want to use cut and paste)

# apt install apache2 cpanminus curl dvipng gcc git libapache2-request-perl \
libarray-utils-perl libcrypt-ssleay-perl libdancer-perl libdancer-plugin-database-perl \
libdata-dump-perl libdatetime-perl libemail-address-xs-perl libemail-sender-perl \
libexception-class-perl libextutils-xsbuilder-perl libfile-find-rule-perl-perl \
libgd-perl libhtml-scrubber-perl libiterator-perl libiterator-util-perl libjson-perl \
liblocale-maketext-lexicon-perl libmime-tools-perl libmoox-options-perl libnet-ip-perl libnet-ldap-perl \
libnet-oauth-perl libossp-uuid-perl libpadwalker-perl libpath-class-perl \
libphp-serialization-perl libpod-wsdl-perl \
libsoap-lite-perl libsql-abstract-perl libstring-shellquote-perl libtemplate-perl \
libtext-csv-perl libtimedate-perl libuuid-tiny-perl libxml-parser-easytree-perl \
libxml-parser-perl libxml-writer-perl make netpbm \
preview-latex-style texlive texlive-latex-extra unzip

If prompted, you can always accept the default (hit <Enter>). When the process finishes, enter

# exit

to return to a regular user.

Installation of Other Perl Modules with cpanm

We will use cpanm to install other perl modules. For example, one module, Statistics::R::IO that will be needed is not in a standard package. To install this

cpanm Statistics::R::IO

Below, we will determine other perl modules that will need to be installed with this method.

Apache2 Modules and mod perl

The following loads needed apache modules.

enabling info.conf and status.conf in Ubuntu

We enable the info module. Acting as root in a terminal window enter

$ sudo su
[sudo] password for wwadmin: <wwadmin password>
# a2enmod info

Next we make a copy of the configuration files we will be editing for safekeeping.

# cd /etc/apache2/mods-available
# cp info.conf info.conf.bak1
# cp status.conf status.conf.bak1
# exit
$

Now we will edit configuration files info.conf and status.conf to allow us to view information about the setup and performance of the web server. Note that this is not absolutely necessary but it can be very useful. You can use your favorite editor but we will give instructions assuming you are using nano. Note that you have to be root to edit these files. First we edit info.conf

$ cd /etc/apache2/mods-available
$ sudo nano info.conf
[sudo] password for wwadmin: <wwadmin password>

I suggest you allow access to server information from e.g. your department domain. To do this uncomment (i.e. remove the # from)

	Require ip 192.0.2.0/24

and then replace 192.0.2.0/24 by .math.yourschool.edu where of course you should edit .math.yourschool.edu appropriately.

Then save the file and quit (press ^X, Y, <Enter>).

Now we edit status.conf

$ cd /etc/apache2/mods-available
$ sudo nano status.conf
[sudo] password for wwadmin: <wwadmin password>

Edit the

 #Require ip 192.0.2.0/24

line just as you did for info.conf. Then save the file and quit. And restart Apache so that the above changes take effect

$ sudo systemctl restart apache2
password:<wwadmin password>

Fully Qualified Domain Name

Now we have to set your server's fully qualified domain name. Note that if your network was set up automatically via DHCP, your server's fully qualified domain name should already be set up. You can check by running the hostname commands below.

Run the command

sudo hostnamectl set-hostname webwork
[sudo] password for wwadmin: <wwadmin password>

where of course you should replace webwork by whatever your server's name is.


You can check these settings by running the commands

$ hostname --fqdn

and

$ hostname

The first gives the server's fully qualified domain name (e.g. webwork.mydepartment.myschool.edu) and the second the server's name (e.g. webwork).

Note that if your server can not find its fully qualified domain name, certain tools (such as the Synaptic Package Manager) may not start.

Test Apache

Now restart Apache

$ sudo systemctl restart apache2
password:<wwadmin password>

or

$ sudo apache2ctl restart
[sudo] password for wwadmin: <wwadmin password>

or

$ sudo service apache2 restart
[sudo] password for wwadmin: <wwadmin password>


and test your server by connecting to your server ("http://yourserver.yourschool.edu") from a browser on a remote machine. You should see the Apache2 Ubuntu Default Page indicating that Apache is running.

You can check Apache's status by connecting to "http://yourserver.yourschool.edu/server-status" from a browser on a remote machine in the math.yourschool.edu domain.

Further test Apache by connecting to "http://yourserver.yourschool.edu/server-info" from a browser on a remote machine in the math.yourschool.edu domain and you will see a page listing various information about Apache. In particular under Server Settings you should see

Server Version: Apache/2.4.41 (Ubuntu) mod_apreq2-20090110/2.8.0 mod_perl/2.0.11 Perl/v5.30.0

(or something very similar) indicating that both mod_apreq2 and mod_perl are installed.

If you have problems now or in the future, a good first thing to do is to look at the Apache error log which is located at /var/log/apache2/error.log. In the directory /var/log/apache2/ you can "less" through the error log (less error.log), look at the last few entries (tail error.log) or run the command tail -f error.log which will display new error messages as they are appended to the file. Use ^C to break out of tail -f . For example if you didn't set up access to "server-info", you can run

tail /var/log/apache2/error.log

and in the output you should see something similar to

...[mpm_event:notice] [pid 48932:tid 140494759132224] AH00489: Apache/2.4.41 (Ubuntu) mod_apreq2-20090110/2.8.0 mod_perl/2.0.11 Perl/v5.30.0 configured -- resuming normal operations

indicating that both mod_apreq2 and mod_perl are installed and running.

Installing a Database

This section installs either MySQL or MariaDB as the database manger for webwork. Either works well with WeBWorK.

Installing and Testing MySQL

$ sudo apt install mysql-server libdbd-mysql-perl

This needs to be tested

First check that MySQL is running by

$ sudo mysql
[sudo] password for wwadmin: <wwadmin password>

You should see something very similar to

Welcome to the MySQL monitor.  Commands end with ; or \g.
Your MySQL connection id is 8
Server version: 8.0.20-0ubuntu0.20.04.1 (Ubuntu)
...

Type 'help;' or '\h' for help. Type '\c' to clear the current input statement.


Enter exit to exit

mysql> exit
Bye
$

Installing and Testing MariaDB

Install MariaDB using the distro packages.

$ sudo apt install mariadb-server

Then we should secure the server

$ sudo mysql_secure_installation


[sudo] password for wwadmin: <wwadmin password>

You can setup the VALIDATE PASSWORD plugin if you wish. I chose not to.

Next you will be asked to enter a New password for the MySQL "root" user. Enter your chosen MySQL root password. You have to enter a password but it will not be used. In Ubuntu systems running MySQL 5.7 (and later versions), the root MySQL user is set to authenticate using the auth_socket plugin by default rather than with a password.

You almost certainly want to answer 'Y' to all questions except possibly for the first one which asks if you want to set up a VALIDATE PASSWORD plugin. Now test that all is well:

$ sudo mysql 
[sudo] password for wwadmin: <wwadmin password>

You should see

Welcome to the MySQL monitor ...
mysql>

Now lets check the MySQL users. There are five accounts. To see the accounts, do the following

mysql> SELECT user,authentication_string,plugin,host FROM mysql.user;

You will see a table with five users (debian-sys-maint, mysql.infoschema, mysql.session, mysql.sys and root). You should see that one of the five users has a valid password (which will be displayed in encrypted form) and root is authenticated by a socket. You can ignore the mysql.session, mysql.sys and mysql.infoschema users.

Now exit MySQL

mysql> exit
Bye
$

This last step is optional since currently most of WeBWorK's MySQL tables are now created using the MyISAM engine (by default -- this can be changed in the config files) rather than the MySQL default engine. Now we change MySQL's default engine. The default engine is InnoDB as of MySQL 5.5.5 (MyISAM before 5.5.5) but (at least on some hardware) InnoDB seems to be 50-100 times slower than MyISAM. So we will change the default MySQL engine from InnoDB to MyISAM. Note that this change only applies to new tables, tables already constructed will continue to use InnoDB. But we haven't created any WeBWorK tables so we don't have to change the engine for any existing tables.

To change the default MySQL engine from InnoDB to MyISAM do the following:

$ cd /etc/mysql/mysql.conf.d
$ sudo cp mysqld.cnf mysqld.cnf.bak1
[sudo] password for wwadmin: <wwadmin password>
$ sudo nano mysqld.cnf

Search for [mysqld] and under "Basic Settings" above the "user = mysql" line add the line

default-storage-engine = myisam  

Then save the file and quit. Restart Mysql

$ sudo /etc/init.d/mysql restart
[sudo] password for wwadmin: <wwadmin password>

or

$ sudo service mysql restart
[sudo] password for wwadmin: <wwadmin password>

and log into mysql

$ sudo mysql 
[sudo] password for wwadmin: <wwadmin password>

You will see

Welcome to the MySQL monitor ...
mysql>

If you show MySQL engines

mysql> SHOW ENGINES\G

you should see that MyISAM is listed as the default engine:

...
*************************** 5. row ***************************
      Engine: MyISAM
     Support: DEFAULT
     Comment: MyISAM storage engine 
Transactions: NO
          XA: NO
  Savepoints: NO

Now exit

mysql> exit
Bye
$