Cypress 3 Custom Install Instructions

These instructions are for Cypress v3 which is not the latest version of Cypress. For Cypress v4, please see our updated instructions.

The Cypress team recommends using the VM, AMI or Chef script unless you have a specific need or reason for a custom install.

The installation will require the installation of the following components

1. Ubuntu (these instructions are for Ubuntu version 16.04 LTS)

2. Configure Proxy Settings

3. Installing Git

4. MongoDB

5. Cypress User

6. Rbenv

7. Cypress Source Code and Configuration

8. Generate a secret token

9. Configure Startup Processes

10. Configure Unicorn and Nginx

11. Installing Ubuntu

---

The ISO for ubuntu 16.04 LTS can be downloaded from the following URL: http://releases.ubuntu.com/xenial/

These instructions were developed against the "64-bit PC (AMD64) server install CD" (ubuntu-16.04-server-amd64.iso).

Installing Ubuntu is a fairly straight-forward process, but for more details on installing Ubuntu please visit the following URLs:

Graphical install using the desktop CD: https://help.ubuntu.com/community/GraphicalInstall

Installation using the Alternate CD (more configuration options): https://help.ubuntu.com/16.04/installation-guide/index.html

Once Ubuntu has been installed you need to update the software on the computer using Apt.  Apt is a software package management system used by Ubuntu. Note: the last command in the group below is only necessary if any packages were actually upgraded.

sudo apt-get update
sudo apt-get -y upgrade
sudo reboot

You will likely want to install an SSH server.  This will allow you to connect remotely to the machine.

sudo apt-get install -y openssh-server

Once SSH is installed, you can determine the IP address of the machine using the command

ifconfig

In the output of this command, look under the block starting with an e, you should find an IP address after the label inet addr:.

2. Configure Proxy Settings

---

This step is only required if the server you are installing Cypress onto needs to go through an HTTP proxy server to reach the internet. These steps will ensure that the appropriate proxy settings are in place for every user that logs into the system.

Use your favourite text editor to create a file in /etc/profile.d named http_proxy.sh with the following contents. In the sample below, replace your.proxy.host.com with the fully-qualified host name of your proxy server, and your.proxy.port with the port number that the proxy server uses.

# Set up system-wide HTTP proxy settings for all users
http_proxy='http://your.proxy.host.com:your.proxy.port/'
https_proxy='http://your.proxy.host.com:your.proxy.port/'
export http_proxy https_proxy

Set proper permissions on the new file, and load the settings into the current environment. NOTE: the proxy settings will automatically be loaded when a user logs in, but we are manually loading them here, to avoid having to log out and log back in again.

sudo chmod 0644 /etc/profile.d/http_proxy.sh
source /etc/profile.d/http_proxy.sh

Make sure that the sudo command will allow the new proxy settings to be passed to commands it launches. This is done by using your text editor to create a file in the /etc/sudoers.d directory named http_proxy (no extension) with the following contents:

# keep http_proxy environment variables.
Defaults env_keep += "http_proxy https_proxy"

Set proper permissions on the new file:

sudo chmod 0440 /etc/sudoers.d/http_proxy

3. Installing Git

---

Git is a source control system.  It will be used later to download the Cypress source code.

sudo apt-get install -y git-core

4. Installing MongoDB

---

MongoDB is the database used by Cypress.  To install MongoDB run the commands:

echo "deb [ arch=amd64,arm64 ] http://repo.mongodb.org/apt/ubuntu xenial/mongodb-org/3.4 multiverse" | sudo tee /etc/apt/sources.list.d/mongodb-org-3.4.list
sudo apt-key adv --keyserver hkp://keyserver.ubuntu.com:80 --recv 0C49F3730359A14518585931BC711F9BA15703C6
sudo apt-get update
sudo apt-get install -y mongodb-org=3.4.5 mongodb-org-mongos=3.4.5 mongodb-org-server=3.4.5 mongodb-org-shell=3.4.5 mongodb-org-tools=3.4.5
sudo apt-mark hold mongodb-org mongodb-org-mongos mongodb-org-server mongodb-org-shell mongodb-org-tools
sudo systemctl start mongod
sudo systemctl enable mongod

To test connection (wait at least 15 seconds to let the db start up), run the command below. If the command exits with a error about not being able to connect, then reboot, and log back in as the admin user. Sometimes mongodb fails to create a network socket when it is started immediately after installation. It should automatically start when the system is rebooted.

mongo

This should output _MongoDB shell version: 3.4.5

Type 'exit' to exit the mongo shell

exit

5. Create Cypress User

---

Add the cypress user (only if you did not create the VM with a Cypress user, i.e., when using EC2)

sudo adduser cypress
sudo usermod -G sudo cypress
sudo su - cypress

All commands below this line should be run as the cypress user.

6. Installing Rbenv

---

Rbenv is a system that allows managing different versions of Ruby.  It will allow the correct version of ruby to be easily installed on the system. Ruby is the development language used for the Cypress application.

First we will need to install some dependencies:

sudo apt-get install -y build-essential libssl-dev libreadline-dev zlib1g-dev

Next we need to install rbenv and ruby-version

git clone https://github.com/rbenv/rbenv.git ~/.rbenv
git clone https://github.com/rbenv/ruby-build.git ~/.rbenv/plugins/ruby-build
echo 'export PATH="$HOME/.rbenv/bin:$PATH"' >> ~/.bashrc
echo 'eval "$(rbenv init -)"' >> ~/.bashrc
exec $SHELL -l

7. Fetching and configuring Cypress Source Code

---

Install the additional dependencies for the application

sudo apt-get -y install nodejs

Getting the Cypress code

git clone https://github.com/projectcypress/cypress.git
cd cypress
git checkout v3.2.3 -b 3.2.3

Installing the version of ruby required for your cypress version

rbenv install

Installing the bundler gem in order to install the cypress dependencies

gem install bundler

Installing the cypress dependencies

bundle install

8. Generate a Secret Token

---

This secret token is used by the cypress application throughout. This line sets up a "secret key" that's used to generate cookies. It's needed in multiple places in the app.

secret_key=`cat /dev/urandom | env LC_CTYPE=c tr -dc 'a-e0-9' | fold -w 128 | head -n 1`

9. Configure Startup Process

---

Configure delayed job to start up on server startup. At this point, you should still have a shell open as the cypress user.

cat << DELAYED_WORKER_END | sudo dd of=/etc/systemd/system/cypress_delayed_worker@.service
  [Unit]
  Description=delayed_worker_%i
  After=mongod.service
  Requires=mongod.service

  [Service]
  Type=simple
  User=cypress
  Environment="SECRET_KEY_BASE=${secret_key}" "RAILS_ENV=production"
  WorkingDirectory=/home/cypress/cypress
  ExecStart=/home/cypress/.rbenv/shims/bundle exec rake jobs:work
  ExecStartPost=/bin/mkdir -p ./tmp/delayed_pids
  ExecStartPost=-/usr/bin/touch ./tmp/delayed_pids/delayed_job.%i.running
  ExecStopPost=/bin/rm ./tmp/delayed_pids/delayed_job.%i.running
  TimeoutSec=120

  [Install]
  WantedBy=multi-user.target
DELAYED_WORKER_END

You will then need to start and enable the service:

sudo systemctl enable cypress_delayed_worker@0
sudo systemctl start cypress_delayed_worker@0
sudo systemctl enable cypress_delayed_worker@1
sudo systemctl start cypress_delayed_worker@1
sudo systemctl enable cypress_delayed_worker@2
sudo systemctl start cypress_delayed_worker@2
sudo systemctl enable cypress_delayed_worker@3
sudo systemctl start cypress_delayed_worker@3

10. Configure Unicorn / Nginx

---

The following commands will setup unicorn for you.

cat << CYPRESS_SITE_END | sudo dd of=/etc/systemd/system/cypress.service
  [Unit]
  Description=cypress

  [Service]
  Environment="AUTO_APPROVE=true" "IGNORE_ROLES=true" "SECRET_KEY_BASE=${secret_key}" "ENABLE_DEBUG_FEATURES=true" "DEFAULT_ROLE=" "RAILS_ENV=production" "BUNDLE_GEMFILE=/home/cypress/cypress/Gemfile"
  ExecStart=/home/cypress/.rbenv/shims/bundle exec /home/cypress/.rbenv/shims/unicorn --port 8000 config.ru
  ExecReload=/bin/kill -HUP \$MAINPID
  KillSignal=TERM
  User=cypress
  WorkingDirectory=/home/cypress/cypress
  Restart=on-failure

  [Install]
  WantedBy=multi-user.target
CYPRESS_SITE_END

Install nginx with the following commands:

sudo apt-get install -y nginx

You will then need to enable and start the service:

sudo systemctl enable cypress
sudo systemctl start cypress

The following set of commands will setup nginx for you.  Update the site configuration with:

cat << CYPRESS_SITE_END | sudo dd of=/etc/nginx/sites-available/cypress
  upstream primary {
    server localhost:8000;
  }

  server {
    listen 80;
    server_name _;

    root /home/cypress/cypress/public;

    try_files \$uri/index.html \$uri @app;

    location @app {
      proxy_pass http://primary;
      proxy_set_header X-Forwarded-For \$proxy_add_x_forwarded_for;
      proxy_set_header Host \$http_host;
      proxy_redirect off;
    }

    error_page 500 502 503 504 /500.html;
    client_max_body_size 4G;
    keepalive_timeout 10;
  }
CYPRESS_SITE_END

Make the default nginx site be the cypress provided content:

sudo rm /etc/nginx/sites-enabled/default
sudo ln -s /etc/nginx/sites-available/cypress /etc/nginx/sites-enabled/default

Restart nginx:

sudo systemctl restart nginx

To open the Cypress web app you'll need the server IP address from step 1.  The server IP address was found from the ifconfig command.  Open a web browser and enter

http://<server_ip_address>/

This should open the Cypress web application.  Click on the "Create New User" link to add a new user and to get started with Cypress.

Once you have completed the install, proceed to initial setup.