/
Automated installer for CollectionSpace

Automated installer for CollectionSpace

Oct 09, 2018

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!)


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

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 Talk mailing list, 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