Cucumber Ltd / jam

Appliancefeatures/appliance.md

Release Crystal Apple (2018-02-01)

Romain Gérard

Currently viewing

Cucumber Pro Appliance

This guide will help you install and configure Cucumber Pro on your own network.

Requirements

  • A linux server (see supported flavours in Replicated docs)
  • 2GB RAM minimum - 16GB RAM recommended
  • 20GB Disk
  • The following ports open:
    • 8800 for the admin console
    • 80 for Cucumber Pro's web interface
    • 2222 for Cucumber Pro's SSH/git access (see Git SSH port)
  • An SMTP server to enable users to sign up and reset passwords

Overview

We use a tool called Replicated to distribute the Cucumber Pro appliance as docker containers.

You're going to start by installing Replicated on your server at the command-line, then you'll use Replicated's browser-based admin console to download and install Cucumber Pro.

The machine will need to be able to access the internet to pull down Docker images and talk to Replicated's servers, before we start we'll need to ensure your proxy server and firewall are configured correctly.

Configure your proxy

You can skip this step if your server will not use a proxy server to access the internet.

If you use a proxy server to access the internet, you may need to white-list the following domains, which will be accessed during the installation:

api.replicated.com
get.replicated.com
registry.replicated.com
quay.io
index.docker.io
cdn-registry-1.docker.io
registry-1.docker.io
*.cloudfront.net

(Optional) Start and configure your firewall

Make sure to install and start any firewall software (such as firewalld) before installing Replicated. This is because docker will set its own iptables rules, and some firewalls will overwrite those rules when they start.

If you have an external firewall in front of the host you need to open the following ports for incoming traffic:

80    for http
443   for https
8800  for access to the Replicated admin console

# Use these if you followed the Git SSH port instructions above.
22    for git+ssh access
2244  for host ssh access

# Use these if you kept the default SSH ports
2222  for git+ssh access
22    for host ssh access

Install Replicated 2.0

Follow Replicated's installation instructions and pay close attention to the platform requirements. We recommend a fresh linux installation without Docker - Replicated will install the correct version of Docker during its own installation.

You will be asked to specify the private IP address. The Replicated admin console will only be available at this IP address.

In order to restrict access to the admin console we recommend you select an IP that is not available outside your network. For a host on the Internet, this would be the IP that you cannot reach from the Internet.

Also write down the public IP address - you might need this to complete the installation.

After installing Replicated, go to its admin web console which is available at URL https://[private IP address]:8800. If your server is on the internet, you probably need to use https://[public IP address]:8800 instead.

If your web browser warns you that the SSL certificate is invalid, tell your browser to ignore the problem for now. If you want to, you can set up a proper SSL certificate to fix this issue.

(Optional) Allow all traffic on the docker0 interface

If you're running firewalld:

# Add docker0 as trusted interface
firewall-cmd --zone=public --change-interface=docker0 --permanent

# Restart services
systemctl restart network firewalld
systemctl restart docker replicated replicated-ui replicated-operator

If you're running a different firewall software, please contact support@cucumber.pro and we'll help you through the configuration.

Activate your Cucumber Pro License

Upload the .rli file you received from us to the Replicated console.

After doing this you will receive an email with an activation code from Replicated.

Enter this code into the Replicated admin console. (If Replicated doesn’t display a field to enter the code, try refreshing the page).

You will then be asked to set up a password for the admin console.

Configure Cucumber Pro

Fill in the configuration form that is presented to you. After you’ve submitted the form, Replicated will start downloading and install Cucumber Pro.

Host name

Enter the same host name that you specified earlier when you installed Replicated. When Cucumber Pro has started it will be available on http://your.host (port 80).

SMTP configuration

Cucumber Pro sends emails to users, for example when they sign up for accounts or reset their passwords.

The Replicated settings screen includes a section where you must configure your SMTP server settings before starting the app.

Enter the details of your SMTP server and test the configuration by pressing the blue button labelled "Test SMTP Authentication" at the bottom of the E-mail settings configuration section.

The SMTP server address can include a port e.g. smtp.mycompany.com:25.

The From email address is the email address that emails sent by Cucumber Pro will be addressed from. This setting can include the name of the sender as well as an email address, e.g. "My Company's Cucumber Pro" <some.email@mycompany.com>

Make sure you test the email settings before you reboot the machine, as the app will not start if they are incomplete or invalid.

Update to new releases

Cucumber Pro will update itself automatically. You can go to the Replicated admin console dashboard to see what version is currently running, browse through previous versions and read release notes.

Backups (Snapshots)

Cucumber Pro can write snapshots of the data to the host machine, under the /var/lib/replicated/snapshots.

You can enable automatic, scheduled snapshotting from the Replicated admin console (Gears dropdown -> Console Settings -> Snapshot & Restore), or https://your.host:8800/console/settings.

We recommend you set up a cron job or similar to back up the snapshot data to a secure location.

The snapshots contain a backup of Cucumber Pro's internal Postgres database and git repositories.

See the Replicated Snapshot Documentation for more details.

Restoring a backup

See the Replicated Restore Documentation

Troubleshooting

If anything goes wrong during the installation of Cucumber Pro or while running it, we’ll be able to help you better if you send us support bundle and data snapshots from your Cucumber Pro appliance.

Please send them to us by email at support@cucumber.pro.

Support bundle

A support bundle can be downloaded from your Replicated admin console. This is a file that contains logs and other diagnostic information about your environment.

Go to Support and click the Download Support Bundle button.

Data snapshots

In addition to logs, we'll sometimes need a backup snapshot as well. See Backups section above.