Versions Compared

Old Version 1

changes.mady.by.user Anonymous

Saved on

compared with

New Version Current

changes.mady.by.user Megan Forbes

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

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 18 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.  

Table of Contents
maxLevel4

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 18 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

...

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 18.04 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 are using a VirtualBox VM, ensure the current date and time are set correctly. You can set it using a command like this:

Code Block
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:

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

...

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

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

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

Code Block
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

...

width45%
Running the bootstrap script entirely unattended

To run the bootstrap script entirely unattended, enter:

Code Block
sudo ./bootstrap-cspace-modules.sh -y
Tip

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.

...

width45%

...

To run the bootstrap script with prompting, enter:

Code Block
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:

Code Block
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.)

...

Code Block
sudo /usr/local/bin/install_collectionspace.sh

...

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.
Info
titleIf 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:

Code Block
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.

Info
titleImportant 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:

Code Block
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:

Code Block
$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:

Code Block
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 18 LTS we used did not require any changes to firewall configuration in order to remotely access the CollectionSpace server via that port.

...

At your command prompt, start UFW via:

Code Block
sudo ufw enable

Open port 8180 via:

Code Block
languagetext
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/

(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.)

...

The CollectionSpace Automated Installer can be found via the program's GitHub repository: https://github.com/collectionspace/cspace-installer.


From the repository's README:

The installer provides an Ansible playbook for setting up CollectionSpace on an Ubuntu server consistent with the official documentation.

For a turn-key, production ready deployment there are just two requirements:

  • An Ubuntu server reachable via SSH
  • DNS configured to access the server by hostname

All of the components in a CollectionSpace system will be installed:

Some minimal system configuration updates can be applied, including:

  • Enable firewall (default deny policy) with exceptions for HTTP & SSH
  • Software packages are updated automatically
  • SSH ip addresses can be whitelisted
  • SSH password authentication is disabled
  • SSH for root user login can be disabled

These features are optional but highly recommended. If you do not use these features of the installer we strongly advise hardening and securing your server before running the installer.

We recommend starting with a newly created server as a buildup to a production deployment. As you become familiar with the installation process and CollectionSpace you may want to wipe and reload the Operating System a few times before settling on a final configuration / setup.

See the documentation for full instructions.


License

This project is available as open source under the terms of the MIT License.