Squash TM on AWS User Guide

Overview

This image runs Squash TM, the open source test and requirement management platform from Henix. Squash TM lets QA and test teams manage requirements, author and organise test cases into libraries, plan and run test campaigns, and track execution and coverage from a single web application. It is delivered as a production application so a complete test management platform is running within minutes of launch.

Squash TM runs as a Java application on the OpenJDK 21 JRE, bound to loopback 127.0.0.1:8080, behind nginx acting as a reverse proxy on port 80. A PostgreSQL database, listening on loopback only, stores every project, requirement, test case, campaign and execution. Systemd manages the Squash TM service, PostgreSQL and nginx, starting them on boot and restarting them on failure. The application is served under the /squash context path, so the bare root redirects there.

Squash TM secures its web interface with its own administrator login. On the first boot of every deployed instance a one shot service generates a fresh PostgreSQL role password and a fresh administrator password, both unique to that instance, and rotates the shipped default admin login so it no longer works, all before the public web interface is started. Two instances launched from the same Amazon Machine Image therefore never share credentials, and the well known default admin/admin login never works on a deployed instance. The administrator password is written to /root/squash-tm-credentials.txt with mode 0600 so that only the root user can read it.

This image ships the LGPL-3.0 open source core of Squash TM. The commercial premium plugin bundle that is included in the upstream distribution is removed at build time, so only the open source core and its LGPL plugins are present.

Prerequisites

Before you deploy this image you need:

• An Amazon Web Services account where you can launch EC2 instances
• IAM permissions to launch instances, create security groups, and subscribe to AWS Marketplace products
• An EC2 key pair in the target Region for SSH access to the instance
• A VPC and subnet in the target Region, with a security group allowing inbound port 22 from your management network and port 80 for the Squash TM web interface
• The AWS CLI (version 2) installed locally if you plan to deploy from the command line

Step 1: Launch the Instance from the AWS Marketplace

Sign in to the AWS Management Console, open the EC2 service, and select Launch instance. Under Application and OS Images choose AWS Marketplace AMIs and search for Squash TM. Select the cloudimg listing and choose Select, then Continue on the subscription summary.

Pick an instance type of m5.large or larger. Squash TM is a Java application that runs with a 2 GiB heap alongside PostgreSQL, so 8 GiB of memory is a sensible minimum. Choose your EC2 key pair under Key pair (login). Under Network settings select your VPC and subnet, and either create or select a security group that opens port 22 from your management network and port 80 for the web interface. Leave the root volume at the default size or larger.

Select Launch instance. First boot initialisation takes a minute or two after the instance state becomes Running and the status checks pass, while the per instance database and administrator passwords are generated, the default login is rotated and the application starts.

Step 2: Launch the Instance from the AWS CLI

The following block launches an instance from the cloudimg Squash TM Marketplace AMI into an existing subnet and security group. Replace <ami-id> with the AMI ID shown on the Marketplace listing, <key-name> with your EC2 key pair name, <subnet-id> with your subnet ID, and <security-group-id> with a security group that opens ports 22 and 80 as described above.

aws ec2 run-instances \
  --image-id <ami-id> \
  --instance-type m5.large \
  --key-name <key-name> \
  --subnet-id <subnet-id> \
  --security-group-ids <security-group-id> \
  --tag-specifications 'ResourceType=instance,Tags=[{Key=Name,Value=squash-tm}]'

When the instance reaches the Running state and its status checks pass, note its public IP address or DNS name from the EC2 console or with aws ec2 describe-instances.

Step 3: Connect to Your Instance

Connect over SSH using your key pair and the login user for your operating system variant.

ssh -i /path/to/your-key.pem ubuntu@<public-ip>

Step 4: Retrieve Your Administrator Password

On the first boot Squash TM generated an administrator password unique to this instance and wrote it, together with the database credentials, to a root only file. Read it with sudo:

sudo cat /root/squash-tm-credentials.txt

The file lists the sign in URL, the administrator login and password, and the PostgreSQL database name, user and password:

squash.url=http://<instance-public-ip>/
squash.admin.login=admin
squash.admin.pass=<generated-password>
squash.db.name=squashtm
squash.db.user=squashtm
squash.db.pass=<generated-password>

The administrator login is admin, but the password is the generated value from this file, not the upstream default. The shipped admin/admin login is rotated on first boot and does not work.

Step 5: Sign In to Squash TM

Browse to http://<instance-public-ip>/ in your web browser. The bare root redirects to the Squash TM sign in page under the /squash context path. Sign in with the login admin and the password from /root/squash-tm-credentials.txt.

After signing in you land on the home workspace, with navigation to Requirements, Test cases, Executions, Reporting and Administration down the left.

As a first step, change the administrator password to one of your own choosing under My account, and create additional user accounts under Administration > Users so each team member signs in with their own login.

Step 6: Create Your First Project

Everything in Squash TM lives inside a project. Open Administration in the left navigation and choose Projects, then use the add button to create a project and give it a name.

Select the project to open its configuration, where you can add a description, connect a bug tracker, set clearance and manage permissions for the users and teams who work on it.

Step 7: Add Requirements, Test Cases and Campaigns

With a project in place you can build out your test assets:

• Requirements - open the Requirements workspace, select your project, and create requirement folders and requirements to capture what the system under test must do.
• Test cases - open the Test cases workspace, organise test cases into folders and libraries, and write each test case as a set of steps with actions and expected results. Link test cases to the requirements they cover to build a coverage matrix.
• Campaigns and executions - open the Executions workspace to plan test campaigns and iterations, add the test cases to run, assign them to testers, and record execution results. Dashboards and the Reporting workspace show progress and coverage.

Step 8: Use the REST API

Squash TM exposes a REST API on the same port 80, under the /squash/api/rest/latest/ path, for integration with CI pipelines and other tools. Authenticate with the administrator credentials or a dedicated API user. For example, to list the projects visible to your account:

curl -u admin:<your-token> http://<public-ip>/squash/api/rest/latest/projects

Create a dedicated API user under Administration > Users for automated access rather than using the administrator account.

Architecture and Security

The image is secure by default:

• Squash TM binds to loopback only. nginx on port 80 is the sole public listener and reverse proxies to the application:

LISTEN  127.0.0.1:5432          (PostgreSQL, loopback only)
LISTEN  0.0.0.0:80              (nginx reverse proxy)
LISTEN  127.0.0.1:8080          (Squash TM, loopback only)

• Authentication is enforced. An unauthenticated request to a protected page redirects to the sign in form, and the bare root returns a 302 redirect into the /squash context.
• The shipped default admin/admin login is rotated on first boot and does not work. Only the generated per instance password authenticates.
• The administrator password is stored in /root/squash-tm-credentials.txt with mode 0600, readable only by root.

You can confirm the service state and health on the instance:

systemctl is-active squash-tm.service postgresql.service nginx.service
# active active active

curl -o /dev/null -w '%{http_code}\n' http://127.0.0.1/squash/isSquashAlive
# 200

Step 9: Enable HTTPS with a Custom Domain

For production use, place your instance behind a domain name and enable TLS. Point a DNS A record at the instance's public IP, then either terminate TLS at an AWS Application Load Balancer in front of the instance, or install a certificate directly on the instance with Certbot and the nginx plugin:

sudo apt-get update
sudo apt-get install -y certbot python3-certbot-nginx
sudo certbot --nginx -d your-domain.example.com

Certbot obtains a certificate and updates the nginx site to serve Squash TM over HTTPS on port 443, with automatic renewal.

Backup and Maintenance

• Database - the application data lives in the PostgreSQL squashtm database. Back it up with pg_dump:

sudo -u postgres pg_dump squashtm | gzip > squashtm-$(date +%F).sql.gz

• Attachments and configuration - the application directory /opt/squash-tm holds the configuration under conf/ and any attachments. Include it in your backups.
• Snapshots - take periodic EBS snapshots of the root volume for point in time recovery.
• Updates - apply operating system security updates with sudo apt-get update && sudo apt-get upgrade. For Squash TM version upgrades, contact cloudimg support for a guided procedure that preserves your database.

Support

cloudimg provides 24/7 technical support for this image by email and live chat at support@cloudimg.co.uk. Our engineers help with deployment, project and workspace setup, the REST API, bug tracker and CI integration, user management, database tuning, TLS and scaling. Critical issues receive a one hour average response.

All product and company names are trademarks or registered trademarks of their respective holders. Use of them does not imply any affiliation with or endorsement by them.