Difference between revisions of "Automatic Installation Script Guide"

From WeBWorK_wiki
Jump to navigation Jump to search
m (added tag)
 
(21 intermediate revisions by 2 users not shown)
Line 1: Line 1:
 
=[https://github.com/openwebwork WeBWorK] Installation Script(s)=
 
=[https://github.com/openwebwork WeBWorK] Installation Script(s)=
   
The github repository at [https://github.com/openwebwork/ww_install] contains a perl script `ww_install.pl`, along with some supporting bash scripts,
+
The github repository at https://github.com/openwebwork/ww_install contains a perl script "ww_install.pl", along with some supporting bash scripts,
 
config files, and perl modules designed to work together install the open source online homework system
 
config files, and perl modules designed to work together install the open source online homework system
[WeBWorK](https://github.com/openwebwork).
+
[https://github.com/openwebwork WeBWorK].
   
The script has been updated to install [[Release notes for WeBWorK 2.11|WeBWorK 2.11]] as of 12/22/2015.
+
The script has been updated to install [[Release notes for WeBWorK 2.12|WeBWorK 2.12]] as of 3/2016.
   
 
It has been tested and supported on
 
It has been tested and supported on
- Debian 7, 8
+
* Debian 8
- Fedora 22
+
* Fedora 22, 23
- Ubuntu 14.04, 15.04, 15.10
+
* Ubuntu 15.10, 16.04 (LTS)
- CentOS 6, 7
+
* CentOS 7
   
 
On these systems it did install WeBWorK.
 
On these systems it did install WeBWorK.
   
Gotchas
 
  +
==Usage==
-------
 
   
- Fedora 23 uses Perl 5.22 which is incompatible with mod_perl. Since WeBWorK uses mod_perl this will prevent installation of WeBWorK on Fedora 23.
 
  +
To install WeBWorK:
   
Usage
 
  +
1. Get the <code>install_webwork.sh</code> script:
-------
 
  +
<pre>
 
  +
wget --no-check-certificate https://raw.githubusercontent.com/openwebwork/ww_install/master/install_webwork.sh
To install [WeBWorK](https://github.com/openwebwork):
 
  +
</pre>
 
  +
or if you prefer
1. Get the `install_webwork.sh` script:
 
  +
<pre>
 
  +
curl -ksSO https://raw.githubusercontent.com/openwebwork/ww_install/master/install_webwork.sh
`wget --no-check-certificate https://raw.github.com/openwebwork/ww_install/master/install_webwork.sh`
 
  +
</pre>
 
or if you prefer
 
 
`curl -ksSO https://raw.github.com/openwebwork/ww_install/master/install_webwork.sh`
 
   
 
2. As root (or with sudo) do
 
2. As root (or with sudo) do
 
  +
<pre>
`bash install_webwork.sh`
+
bash install_webwork.sh
  +
</pre>
   
 
Note that if you use sudo, then you must be a sudoer with sufficient administrative rights
 
Note that if you use sudo, then you must be a sudoer with sufficient administrative rights
Line 42: Line 37:
 
For more control over the process you can clone this repository with
 
For more control over the process you can clone this repository with
   
`git clone https://github.com/openwebwork/ww_install.git`
 
  +
<pre>
  +
git clone https://github.com/openwebwork/ww_install.git
  +
</pre>
   
and then run the scripts individually as needed.
+
and then run ww_install.pl manually.
   
Contents
 
  +
3. Answer the prompts as directed by the installer. Things to watch out for
--------
 
  +
* You will need to set the mysql root password. It should be different than your root/user password.
  +
* Unless you have a good reason not to, use the standard installation directories.
  +
* You can define a new WeBWorK admin user or use your current user. The WeBWorK admin user should not be root.
  +
* You should use the usual WeBWorK data group unless you have a reason not to.
  +
* Use https for your server root if you plan on setting up ssl. SSL is ''not'' set up automatically by the script.
  +
* Do not change the relative location of the WeBWorK handler unless you have a reason to.
  +
* You will probably need to contact your IT liaison to find out your smtp server (or make a guess).
  +
* You will need to set the WeBWorK database password. It should be different than your mysql root password.
  +
* Download from the usual repositories unless you have a reason not to.
  +
* Use somewhere between 15-20 for each 1 GB of memory when setting MaxClients
   
### install_webwork.sh
 
  +
4. The script will attempt to open a browser and start WeBWorK. You can login to the
  +
admin course with initial username and password 'admin'.
  +
  +
==Important Files==
  +
  +
=== install_webwork.sh ===
   
 
This script is the 'controller' that ties together the other scripts. It opens an install log, downloads this
 
This script is the 'controller' that ties together the other scripts. It opens an install log, downloads this
repo and opens it in (typically) `/tmp`. Then it installs any files needed to run `ww_install.pl` and then runs `ww_install.pl`.
+
repo and opens it in (typically) <code>/tmp</code>. Then it installs any files needed to run <code>ww_install.pl</code> and then runs <code>ww_install.pl</code>.
When `ww_install.pl` exits, it attempts to open webwork in the system's default web browser, copies
+
When <code>ww_install.pl</code> exits, it attempts to open WeBWorK in the system's default web browser, copies
webwork_install.log to your top level webwork directory (e.g. `/opt/webwork`) and then deletes the downloaded installation package.
+
webwork_install.log to your top level webwork directory (e.g. <code>/opt/webwork</code>) and then deletes the downloaded installation package.
   
### bin/ww_install.pl
+
=== bin/ww_install.pl ===
   
The goal of `ww_install.pl` is to install WeBWorK on any system with a properly set up distribution file in the `distros` folder.
+
The goal of <code>ww_install.pl</code> is to install WeBWorK on any system with a properly set up distribution file in the <code>distros</code> folder.
   
It is an interactive script based on the core perl module [Term::UI](http://perldoc.perl.org/Term/UI.html), and is written with the goal of being cross-platform. It does use some linux built-ins, and work is needed to ensure that this script will work as well on unix machines. Again, contributions of work in this direction would be welcome.
+
It is an interactive script based on the core perl module [http://perldoc.perl.org/Term/UI.html Term::UI], and is written with the goal of being cross-platform. It does use some linux built-ins, and work is needed to ensure that this script will work as well on unix machines. Again, contributions of work in this direction would be welcome.
   
### distros
+
=== distros ===
   
This folder contains distribution files which `ww_install.pl` uses to install WeBWorK on various systems. For example the file `distros/centos/7.pm` is used to install WeBWorK on CentOS version 7. If you are interested in getting the installer working on your favorite distribution you would create the appropriate file in this folder and submit a pull request. You can base your distro file off of `blankdistro.pm`. In general you will need to set the following:
+
This folder contains distribution files which <code>ww_install.pl</code> uses to install WeBWorK on various systems. For example the file <code>distros/centos/7.pm</code> is used to install WeBWorK on CentOS version 7. If you are interested in getting the installer working on your favorite distribution you would create the appropriate file in this folder. You can base your distro file off of <code>blankdistro.pm</code>. In general you will need to set the following:
 
* The array of versions which you have tested the installer on.
 
* The array of versions which you have tested the installer on.
 
* The list of packages which provide the binaries described by the hash keys
 
* The list of packages which provide the binaries described by the hash keys
 
* The list of packages which provide the perl modules described by the hash keys. Use 'CPAN' if you intend to get the package from CPAN
 
* The list of packages which provide the perl modules described by the hash keys. Use 'CPAN' if you intend to get the package from CPAN
* The `apacheLayout` array which defines where various folders and configuration files are for your apache setup.
+
* The <code>apacheLayout</code> array which defines where various folders and configuration files are for your apache setup.
 
* The command for updating package sources.
 
* The command for updating package sources.
 
* The command for updating packages.
 
* The command for updating packages.
Line 74: Line 85:
 
* The command for installing packages from CPAN.
 
* The command for installing packages from CPAN.
 
* The command for checking and configuring services post install.
 
* The command for checking and configuring services post install.
* You can add code in various "hooks" which will be run at various stages of the installation. This is an opportunity to perform any hacky fixes necessary for your distro.
+
* You can add code in various "hooks" which will be run at various stages of the installation. This is an opportunity to perform any hacky fixes necessary for your distro.
   
### Other files
+
=== Other files ===
   
The `extra/` subdirectory contains scripts which help with optional post install tasks. These are not currently
+
The <code>extra/</code> subdirectory contains scripts which help with optional post install tasks. These are not currently hooked into the other scripts, so you'll need to run them separately. Currently contains
hooked into the other scripts, so you'll need to run them separately. Currently contains
 
   
* `iptables_rules.sh`
 
  +
* <code>iptables_rules.sh</code>: Sets up an iptables firewall which only allows network services necessary for running WeBWorK.
   
Sets up an iptables firewall which only allows network services necessary for running WeBWorK.
 
  +
* <code>generate_ssl_cert.sh</code>: Steps user through generating an ssl cert. Under construction.
   
* `generate_ssl_cert.sh`
 
  +
* <code>install_chromatic.pl</code>: Standalone script to compile <code>pg/lib/chromatic/color.c</code> so the NAU library graph theory problems work. This functionality has been incorporated into <code>ww_install.pl</code>, so it should not be necessary to run this script. However, if you find the NAU graph theory problems are complaining that <code>pg/lib/chromatic/color</code> doesn't exist, then you can run this script to compile it for you.
   
Steps user through generating an ssl cert. Under construction.
 
  +
* The <code>lib/</code> subdirectory contains copies of any perl modules the script uses but which don't need to be installed on your system for webwork to run.
   
* `install_chromatic.pl`
 
  +
* The <code>conf/</code> subdirectory contains copies of config files or snippets of config files that this installation package will ask to modify.
   
Standalone script to compile `pg/lib/chromatic/color.c` so the NAU library graph theory problems work. This
 
  +
== Other Resources ==
functionality has been incorporated into `ww_install.pl`, so it should not be necessary to run this script. However,
 
if you find the NAU graph theory problems are complaining that `pg/lib/chromatic/color` doesn't exist, then you
 
can run this script to compile it for you.
 
   
The `lib/` subdirectory contains copies of any perl modules the script uses but which don't need to be installed
 
  +
Please report any problems on the [https://github.com/openwebwork/ww_install/issues issues page] for the github repository.
on your system for webwork to run.
 
   
The `conf/` subdirectory contains copies of config files or snippets of config files that this installation package
 
  +
Questions and comments about this installer can be directed to the [http://webwork.maa.org/mailman/listinfo/webwork-devel webwork-devel]
will ask to modify.
 
  +
mailing list.
  +
Information and documentation about WeBWorK itself can be found at http://webwork.maa.org/wiki
   
Other Resources
 
  +
== Author ==
----------------
 
   
Please report any problems on the [issues page](https://github.com/aubreyja/ww_install/issues?state=open) for this
 
  +
Jason Aubrey <aubreyja@gmail.com>
repository.
 
   
Questions and comments about this installer can be directed to me on the [webwork-devel](http://webwork.maa.org/mailman/listinfo/webwork-devel)
 
  +
I'd be happy to hear suggestions for improvement. Seriously, though. Send all your complaints to this guy.
mailing list. For a recent discussion see [[1]](http://webwork.maa.org/pipermail/webwork-devel/2013-June/001089.html).
 
   
Information and documentation about WeBWorK itself can be found at http://webwork.maa.org/wiki
 
 
Author
 
--------
 
 
Jason Aubrey <aubreyja@gmail.com>
 
   
If you use the script, please email me to let me know what OS you installed it on so I can add a notation to
 
  +
[[Category:Installation]]
the list of tested distributions above and address any problems you run into. I'd also be happy to hear
 
suggestions for improvement. Seriously, though. Send all yoru complaints to this guy.
 

Latest revision as of 15:00, 21 June 2021

WeBWorK Installation Script(s)

The github repository at https://github.com/openwebwork/ww_install contains a perl script "ww_install.pl", along with some supporting bash scripts, config files, and perl modules designed to work together install the open source online homework system WeBWorK.

The script has been updated to install WeBWorK 2.12 as of 3/2016.

It has been tested and supported on

  • Debian 8
  • Fedora 22, 23
  • Ubuntu 15.10, 16.04 (LTS)
  • CentOS 7

On these systems it did install WeBWorK.

Usage

To install WeBWorK:

1. Get the install_webwork.sh script:

wget --no-check-certificate https://raw.githubusercontent.com/openwebwork/ww_install/master/install_webwork.sh

or if you prefer

curl -ksSO https://raw.githubusercontent.com/openwebwork/ww_install/master/install_webwork.sh

2. As root (or with sudo) do

bash install_webwork.sh

Note that if you use sudo, then you must be a sudoer with sufficient administrative rights (probably `ALL=(ALL) ALL`) for `install_webwork.sh` to work properly. If not, run this command as root.

For more control over the process you can clone this repository with

git clone https://github.com/openwebwork/ww_install.git

and then run ww_install.pl manually.

3. Answer the prompts as directed by the installer. Things to watch out for

  • You will need to set the mysql root password. It should be different than your root/user password.
  • Unless you have a good reason not to, use the standard installation directories.
  • You can define a new WeBWorK admin user or use your current user. The WeBWorK admin user should not be root.
  • You should use the usual WeBWorK data group unless you have a reason not to.
  • Use https for your server root if you plan on setting up ssl. SSL is not set up automatically by the script.
  • Do not change the relative location of the WeBWorK handler unless you have a reason to.
  • You will probably need to contact your IT liaison to find out your smtp server (or make a guess).
  • You will need to set the WeBWorK database password. It should be different than your mysql root password.
  • Download from the usual repositories unless you have a reason not to.
  • Use somewhere between 15-20 for each 1 GB of memory when setting MaxClients

4. The script will attempt to open a browser and start WeBWorK. You can login to the admin course with initial username and password 'admin'.

Important Files

install_webwork.sh

This script is the 'controller' that ties together the other scripts. It opens an install log, downloads this repo and opens it in (typically) /tmp. Then it installs any files needed to run ww_install.pl and then runs ww_install.pl. When ww_install.pl exits, it attempts to open WeBWorK in the system's default web browser, copies webwork_install.log to your top level webwork directory (e.g. /opt/webwork) and then deletes the downloaded installation package.

bin/ww_install.pl

The goal of ww_install.pl is to install WeBWorK on any system with a properly set up distribution file in the distros folder.

It is an interactive script based on the core perl module Term::UI, and is written with the goal of being cross-platform. It does use some linux built-ins, and work is needed to ensure that this script will work as well on unix machines. Again, contributions of work in this direction would be welcome.

distros

This folder contains distribution files which ww_install.pl uses to install WeBWorK on various systems. For example the file distros/centos/7.pm is used to install WeBWorK on CentOS version 7. If you are interested in getting the installer working on your favorite distribution you would create the appropriate file in this folder. You can base your distro file off of blankdistro.pm. In general you will need to set the following:

  • The array of versions which you have tested the installer on.
  • The list of packages which provide the binaries described by the hash keys
  • The list of packages which provide the perl modules described by the hash keys. Use 'CPAN' if you intend to get the package from CPAN
  • The apacheLayout array which defines where various folders and configuration files are for your apache setup.
  • The command for updating package sources.
  • The command for updating packages.
  • The command for installing packages.
  • The command for installing packages from CPAN.
  • The command for checking and configuring services post install.
  • You can add code in various "hooks" which will be run at various stages of the installation. This is an opportunity to perform any hacky fixes necessary for your distro.

Other files

The extra/ subdirectory contains scripts which help with optional post install tasks. These are not currently hooked into the other scripts, so you'll need to run them separately. Currently contains

  • iptables_rules.sh: Sets up an iptables firewall which only allows network services necessary for running WeBWorK.
  • generate_ssl_cert.sh: Steps user through generating an ssl cert. Under construction.
  • install_chromatic.pl: Standalone script to compile pg/lib/chromatic/color.c so the NAU library graph theory problems work. This functionality has been incorporated into ww_install.pl, so it should not be necessary to run this script. However, if you find the NAU graph theory problems are complaining that pg/lib/chromatic/color doesn't exist, then you can run this script to compile it for you.
  • The lib/ subdirectory contains copies of any perl modules the script uses but which don't need to be installed on your system for webwork to run.
  • The conf/ subdirectory contains copies of config files or snippets of config files that this installation package will ask to modify.

Other Resources

Please report any problems on the issues page for the github repository.

Questions and comments about this installer can be directed to the webwork-devel mailing list. Information and documentation about WeBWorK itself can be found at http://webwork.maa.org/wiki

Author

Jason Aubrey <aubreyja@gmail.com>

I'd be happy to hear suggestions for improvement. Seriously, though. Send all your complaints to this guy.