Automated installer for CollectionSpace

Owned by Aron Roberts (Unlicensed)
Oct 09, 2018
7 min read

This installer allows you to install CollectionSpace on a Linux host by running just a few commands, replacing many otherwise manual installation steps.  We recommend installing CollectionSpace on Ubuntu 16 LTS. Ideally, the Ubuntu server you're going to try to install CollectionSpace onto has been setup/created solely for the purpose of running CollectionSpace.  If the server is an existing system that is being used or has been used to host other software, you may encounter problems that will require advanced system administration and support.  

About the Installer

The installer allows you to install CollectionSpace on a Linux host - see System Requirements for details - by running just a few commands. On its own, unattended, the installer completes nearly all of the steps you'd otherwise need to manually perform during an installation. (There are a few steps you'll still need to perform manually, following the completion of the installation.)

Ideally, the Ubuntu server you're going to try to install CollectionSpace onto has been setup/created solely for the purpose of running CollectionSpace.  If the server is an existing system that is being used or has been used to host other software, you may encounter problems that will require advanced system administration and support.  

If you want to create a new Ubuntu 16 LTS server just for running CollectionSpace, here are a few options:

  • Linode.com provides cloud-based Ubuntu servers capable of running CollectionSpace for as little as $5/month (USD)
  • Amazon's AWS also provides cloud-based Ubuntu servers capable of running CollectionSpace
  • VirtualBox can be used to create virtual Ubuntu servers capable of running CollectionSpace

System Requirements for the Host Server

  • An Intel/AMD-based host with at least 2 GB of RAM.

    RECOMMENDED: The host server can be a virtual machine (e.g. running under VMware products, VirtualBox, et al.), a Linux container (e.g. running under Docker), a cloud-based virtual private server (VPS like Linode.com), or a a physical computer. (See Using VirtualBox and Vagrant to Host CollectionSpace for a fast, low-cost approach to getting your own virtual machine up and running.)

    Please note that, to date, successful testing has been done only on hosts with Intel/AMD x86 architecture CPU(s) (either 64-bit or 32-bit) with 2 GB of RAM or higher.
  • 'sudo' (privileged administrative user) access on that host.

  • An installed copy of Ubuntu 16 LTS.

    (It would be desirable to be able to perform automated installations on any recent version of a Debian Linux-based or a RedHat Linux-based operating system, but limits on available development resources have so far required a focus on Ubuntu 16 LTS in version 5.0. Please feel free to participate in helping make the installer run on other OSes. You can contribute - or pick up - Puppet experience in the process, and will help the community!)

    We recommend installing CollectionSpace on a dedicated Ubuntu Server 16 LTS server.

    Please note that this installer has been tried on just a few other different Linux distributions. If possible, please install it only on a system that you can dedicate entirely to running CollectionSpace, and on which you can readily revert to a previous snapshot, if you have a snapshotting system available, or (if needed), wipe and reload the operating system from scratch. Virtual machines (e.g. VirtualBox or VMware, with the use of Vagrant as a VM management tool is also highly recommended) make particularly good systems on which to try out this installer.

    The installer has been successfully tested to date with the following Linux distributions and versions:

    • Ubuntu Server 16.04.2 LTS (and minor update releases)

    In an older version of CollectionSpace - version 4.1 - the installer was known to fail when run under the following Linux distributions and versions (with potential workarounds available for some of these). If you plan try the installer on another Linux distribution, take these issues into account:

    • CentOS 6.5 (see CSPACE-6518 for details)
    • Debian 7 (see CSPACE-6377 for details; a potential workaround is available to allow successful installation on this platform)
    • Ubuntu Server 13.10 (see CSPACE-6589 for details)
    • Ubuntu Server 14.10 and Ubuntu Server 15.04 (see CSPACE-6521 for details)
    • RedHat 7

    If you encounter issues running this installer on other Debian and RedHat-based Linux distributions and/or versions, not listed here, please report these on the /wiki/spaces/collectionspace/pages/666276158 and we'll be glad to look into them with you. (Overall, your installation is far more likely to succeed on current or otherwise recent releases.)

    VirtualBox - If you're using a VirtualBox VM, ensure the current date and time are set correctly. You can set it with a command like this:

    sudo date -s "$(wget -qSO- --max-redirect=0 google.com 2>&1 | grep Date: | cut -d' ' -f5-8)Z"

Running the Installer

Downloading the Bootstrap Script

The bootstrap script is a 'bash' shell script that gathers software prerequisites needed by the installer, then kicks off the installation. To download the bootstrap script onto your host, do the following:

In an SSH terminal session, log into your host as a user with sudo access.

At that user's shell (the bash shell is preferred) command prompt, enter:

sudo apt-get update
wget https://raw.githubusercontent.com/cspace-puppet/cspace_puppet_bootstrap/v5.0-branch/scripts/bootstrap-cspace-modules.sh

If the above command fails with a wget: command not found error, try the following command instead:

curl --remote-name --location https://raw.githubusercontent.com/cspace-puppet/cspace_puppet_bootstrap/v5.0-branch/scripts/bootstrap-cspace-modules.sh
Making the Bootstrap Script Executable

To make the bootstrap script executable on your system, enter:

chmod u+x bootstrap-cspace-modules.sh
Running the Bootstrap Script

You can then run the bootstrap script in either of two ways:

  • Entirely unattended
  • With some prompting: to confirm, for example, whether you want to proceed with the installation
Running the bootstrap script entirely unattended

To run the bootstrap script entirely unattended, enter:

sudo ./bootstrap-cspace-modules.sh -y

The -y at the end of the command is important: it's what allows the installer to run entirely unattended. If you leave it off, you'll later be prompted - once - whether you want to proceed with the installation.

If you're prompted to enter your password via a request that looks like '[sudo] password for {youruseraccountname}:', enter your account password at the prompt.

The installation will then proceed entirely unattended from this point, without requiring human input. (Please note that installation can take 30 minutes or more on a typical system. As well, several individual steps within the installation, including various building and deploying steps, can each take many minutes to complete and no new messages will appear onscreen until they're finished.)

Note that an unintended installation will use default values for a variety of configurable values, and will automatically generate passwords for several PostgreSQL database user accounts relevant to your CollectionSpace server installation. If you'd like to have control over setting these values, run the bootstrap script with prompting.

Running the bootstrap script with prompting

To run the bootstrap script with prompting, enter:

sudo ./bootstrap-cspace-modules.sh

If you're prompted to enter your password via a request that looks like '[sudo] password for {youruseraccountname}:', enter your account password at the prompt.

Bootstrap installation will then commence: getting software onto your host that's required by the installer, as well as the installer itself. (This takes around three minutes on a typical system.)

You'll then see a prompt asking whether you want to install your CollectionSpace server:

Congratulations!
Initial prerequisites for a CollectionSpace server were successfully installed..

Install your CollectionSpace server now [y/n]?
  • If you enter y or Y at this prompt, the installation will then proceed entirely unattended from this point, without requiring human input. (Please note that installation can take 30 minutes or more on a typical system.)

  • If you enter n or N at this prompt, an informational message will be displayed, identifying the full path to a second script that you can run later, at your convenience, to proceed with the installation.

    On most systems, you can run the installer script again by entering this command:

    sudo /usr/local/bin/install_collectionspace.sh

    Before running the installer script, you can change a variety of configurable values, such as passwords for several PostgreSQL database user accounts relevant to your CollectionSpace server installation, the host and port for the database server, and the location of the Tomcat server directory which will house your CollectionSpace instance.

    If you'd like to change any of these values, edit the file /etc/puppet/hierdata/collectionspace_common.yaml. Or, if you'd like to preserve the default values for reference, copy any relevant lines from that file, paste them into the file collectionspace_instance.yaml, in that same directory, and edit them there. Values in the collectionspace_instance.yaml file override those in the collectionspace_common.yaml file. (You'll need to have root (e.g. sudo) access to edit these files.)

After Installation

As mentioned above, please note that installation can sometimes take 30 minutes or more. As well, several individual steps within the installation, including various building and deploying steps, can each take many minutes to complete and no new messages will appear onscreen until they're finished.

You'll encounter one of two possible outcomes:

  • If any errors occurred, the installation will be halted at the point of error and the relevant error messages will be displayed in your terminal window. (Please feel free to post any such errors to the CollectionSpace /wiki/spaces/collectionspace/pages/666276158, where developers and the community can help you address them.)
  • Otherwise, you'll see a success message, after which you can complete the installation via the following (manual) steps.

If the Installation Fails?

If you think the installation failed and you're not sure why or what to do next, try running the installer script again. Try the with-prompting flavor:

sudo ./bootstrap-cspace-modules.sh

If you still have problems after re-running the installer script. Send a detailed description of your problem to talk@collectionspace.org.

Important Passwords

You can find a set of important passwords in the file initial_password.txt in the cspace user's home directory; i.e. in/home/cspace/initial_password.txt This file also contains instructions for changing the cspace user's initial password to another password of your choice. (The file is viewable only by the cspace user, as well as by any user with root (sudo) access.)

Logging in as the cspace User

Login as (i.e. switch to working as) the user named cspace:

sudo su - cspace

The cspace user is, by default, the Linux system user that 'owns' the CollectionSpace server directory and related files, and thus administers your CollectionSpace system.

Starting the Server

Start the CollectionSpace server:

$CSPACE_JEESERVER_HOME/bin/startup.sh

Wait for it to fully start up. (For more information on verifying server startup, see Starting Up the CollectionSpace Server.)

Logging out of the cspace User Account

You can then logout of the cspace user account, returning to the sudo-enabled account that you used when beginning the installation. To do so, enter:

exit
Configuring the Firewall (system-dependent)

  • On certain systems, it may be necessary to configure your firewall software to open the default port (8180) on which the CollectionSpace server listens for incoming connections. The image of Ubuntu 16 LTS we used did not require any changes to firewall configuration in order to remotely access the CollectionSpace server via that port.

    However, with another particular image of Ubuntu (non-server) 13.10 it was necessary to open port 8180 for public access in its default firewall configuration, via Ubutu's instructions for enabling the UFW firewall interface. (In place of using UFW, as shown here, you could alternately configure iptables directly.)

    In brief:

    • At your command prompt, start UFW via:

      sudo ufw enable

    • Open port 8180 via:

      sudo ufw allow 8180/tcp
Logging in to CollectionSpace

Check the installation: Open a browser and go to this URL http://<ip-address>:8180/cspace/core/login

(where <ip-address> is the actual IP address or hostname of your Linux host on which you've installed CollectionSpace. If you happen to be running your browser on the same host on which you've installed CollectionSpace, you can use localhost as the hostname.)

You should be able to log in to the demonstration core tenant using the user admin@core.collectionspace.org and the password Administrator.