ScanCode.io on AWS User Guide

Overview

This image runs ScanCode.io, the open source server for automated software composition analysis from the AboutCode project. ScanCode.io runs configurable scan pipelines over any codebase, source trees, package archives, Docker images and root filesystems, and reports the licenses, copyrights, packages and dependencies it finds, so you can produce accurate SBOMs and answer open source compliance questions with file level evidence.

ScanCode.io is deployed from the official upstream container image, pinned by digest, and run as a managed appliance. The appliance reproduces upstream's supported production topology as a Docker Compose stack: a PostgreSQL database, a Redis queue, a gunicorn web tier serving the Django application, an RQ worker that runs scan pipelines, and an nginx reverse proxy that publishes the web interface on port 80. A single systemd service, scancodeio.service, supervises the whole stack and starts it on boot.

All stateful data, the PostgreSQL database, the Redis append only file and the scan workspace that holds every uploaded and extracted codebase, lives on a dedicated, independently resizable EBS data volume mounted at /var/lib/scancodeio, so your scan data is kept off the operating system disk and survives instance replacement.

Authentication is required. ScanCode.io ships with authentication disabled by default; this appliance sets SCANCODEIO_REQUIRE_AUTHENTICATION so every web view and REST API endpoint demands a login, because an open scanner would let anyone submit scan pipelines, which is arbitrary workload execution on your instance. To make every deployed instance secure, a one shot first boot service rotates every shared secret, a fresh Django secret key, a fresh database password, and a fresh administrator account with a unique password and REST API key, before the stack serves a single request, and writes them to /root/scancodeio-credentials.txt with mode 0600 so that only the root user can read it. Two instances launched from the same Amazon Machine Image never share a secret.

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 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 ScanCode.io. Select the cloudimg listing and choose Select, then Continue on the subscription summary.

Pick an instance type of m5.large or larger; ScanCode.io runs PostgreSQL, Redis, a gunicorn web tier and a scan worker together, and scans are CPU and memory hungry because each scan process loads a large license index. 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. Larger codebases and Docker image analysis benefit from more vCPU and RAM, so consider m5.xlarge or m5.2xlarge for heavier workloads.

Select Launch instance. First boot initialisation, which rotates the secrets and starts the appliance, takes a couple of minutes after the instance state becomes Running and the status checks pass.

Step 2: Launch the Instance from the AWS CLI

The following block launches an instance from the cloudimg ScanCode.io 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=scancodeio}]'

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 <key-name>.pem ubuntu@<public-ip>

Step 4: Retrieve the Administrator Password and API Key

The administrator password and REST API key are unique to your instance and were generated on first boot. Read them as root:

sudo cat /root/scancodeio-credentials.txt

The file lists the ScanCode.io URL, the administrator user (admin), the generated web password and the generated REST API key. Keep these somewhere safe.

Step 5: Sign In to the Web Interface

The ScanCode.io web interface is served on port 80 by nginx, which reverse proxies the gunicorn application. In a browser, go to:

http://<instance-public-ip>/

Sign in as admin with the password from the credentials file. Authentication is required, so the sign in page is the first thing you see.

After signing in you land on the Projects list, where every scan project and its pipeline status is shown.

Step 6: Create a Project and Run a Scan

Select New Project, give it a name, add an input by uploading a codebase archive or supplying a download URL or Docker image reference, choose a pipeline such as scan_codebase, and enable Execute pipeline now. The RQ worker runs the pipeline in the background and the project page updates as it progresses.

When the pipeline finishes, the project page summarises the results: the packages, dependencies and resources discovered, the unique license detections, and one click export of the results as an SBOM in SPDX, CycloneDX, XLSX, JSON and attribution formats.

Open the Resources view to see the evidence behind the scan: the detected license expression, programming language, mime type and package for every file the pipeline analysed.

Step 7: Confirm ScanCode.io Is Running

Over SSH, confirm the appliance service is active and that the web interface answers on port 80:

sudo systemctl is-active scancodeio.service
curl -s -o /dev/null -w 'login page HTTP %{http_code}\n' http://127.0.0.1/accounts/login/

You should see the service reported as active and the login page returning HTTP 200. The appliance runs its whole stack as Docker Compose services supervised by systemd. List the running containers with:

cd /opt/scancodeio && sudo docker compose --env-file docker.env ps --status running --format '{{.Service}} {{.Status}}'

You should see the db, redis, web, worker and nginx services running.

Step 8: Prove a Full Scan Round Trip

The appliance ships a self test that proves a real scan round trip end to end. It creates a project, uploads a small sample codebase that cloudimg authored with known planted licenses, runs the scan_codebase pipeline to completion, asserts that the planted Apache-2.0, MIT and BSD-3-Clause licenses and the npm package are detected, confirms that unauthenticated API access is refused, and then removes the project it created:

sudo /usr/local/sbin/scancodeio-selftest.sh

A healthy instance prints SELFTEST_SUCCESS on the last line.

Step 9: The Stack and the Data Volume

ScanCode.io stores its database, its Redis queue and every codebase you scan on a dedicated EBS volume mounted at /var/lib/scancodeio, which keeps them off the operating system disk and lets you resize or snapshot them independently. The Docker data root is relocated onto this volume, so all container data lands there. Confirm the mount with:

df -h /var/lib/scancodeio

To grow the scan storage, expand the EBS volume in the AWS console, then grow the filesystem on the instance with sudo resize2fs on the underlying device. The appliance also keeps a 4 GiB swapfile on this volume so a memory hungry scan cannot trigger the kernel out of memory killer.

Step 10: Use the REST API

ScanCode.io exposes a REST API on the same port 80, under /api/. The credentials file contains a per instance API key; send it in an Authorization: Token <key> header. For example, from outside the instance, list your projects with curl -H "Authorization: Token <your-token>" http://<instance-public-ip>/api/projects/. Use the API to create projects, upload inputs, start pipelines and download SBOMs, so you can wire scans into CI/CD and gate releases on license policy.

Step 11: Add a Custom Domain and Enable HTTPS

The appliance is configured to accept requests on any host name, so it works immediately on the instance's public IP. nginx terminates HTTP on port 80 inside the bundled nginx container and reverse proxies the gunicorn application.

The simplest way to serve ScanCode.io on your own domain over HTTPS is to place the instance behind an AWS Application Load Balancer with an AWS Certificate Manager certificate that terminates TLS and forwards to port 80. Point a DNS record at the load balancer, and restrict the security group so port 80 is reachable only from the load balancer.

When you put ScanCode.io behind TLS, set SESSION_COOKIE_SECURE=True and CSRF_COOKIE_SECURE=True in /opt/scancodeio/docker.env and restart the appliance with sudo systemctl restart scancodeio.service; these are set to False on the appliance so that browser login works over plain HTTP by IP, and should be turned back on once TLS terminates in front of the application.

Step 12: Backup and Maintenance

Back up ScanCode.io by snapshotting the /var/lib/scancodeio EBS volume, which captures the PostgreSQL database, the Redis append only file and every scan workspace in one consistent snapshot. Apply operating system security updates with sudo apt-get update && sudo apt-get upgrade and reboot when a new kernel is installed; the ScanCode.io appliance starts automatically on boot. The container images are pinned by digest, so the appliance never changes version unexpectedly.

Support

This image is published and supported by cloudimg. Support covers deployment, pipeline configuration, REST API integration, SBOM export, custom domains, TLS, data volume resizing and scaling. Contact cloudimg through the support channel listed on the AWS Marketplace listing.

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.