Self-Hosting Requirements

This page applies when you host Earnie yourself, in the self-hosted Earnie or fully on-premises option. If SCANOSS hosts Earnie for you, you don’t need any of it. See Deployment options. Earnie runs on one Linux server with Docker Compose. A PostgreSQL database holds its data. You can run the database as a container on the same server, or use a PostgreSQL server you already have. In the fully on-premises option you also run the SCANOSS API and knowledge base. They have their own, much larger, hardware requirements. Run them on a separate server.

​

Before You Start

Check these with your SCANOSS contact and your infrastructure team before you install:

• Which scanners your organisation has: open source only, or also cryptography, AI provenance, or both. This decides the server size in CPU and memory.
• A Linux server that meets the Hardware and Software requirements.
• A PostgreSQL 16 database, or room on the server to run one. See Database.
• A DNS name for Earnie, and either inbound internet access for a Let’s Encrypt certificate or a certificate of your own. See Inbound.
• Outbound access to the destinations in Outbound.
• From SCANOSS: the installation bundle, a SCANOSS API key, and credentials for the container registry, or the offline image archive instead. See Installing Earnie.

​

Hardware

​

CPU and Memory

The scanners your organisation has decide how much CPU and memory Earnie needs. Open-source matching is light. Cryptography detection builds your dependencies in a sandbox and needs the most CPU. AI provenance needs the most memory, because it loads model files. These figures are for Earnie alone. If you run the database on the same server, add the database’s CPU and memory from Database. Cryptography scans also run on fewer cores, but more slowly. In SCANOSS’s measurements, the first scan of a Java project with 131 dependencies took about 10 minutes on 14 cores, 15 minutes on 8 cores, and 25 minutes on 4 cores. Memory peaked near 7.5 GB at every core count. Later scans of the same project reuse cached results and are much faster, about 2.5 minutes in the same measurement. The first scan after an Earnie upgrade or a change to the detection rules runs at full length again.

​

Disk

Use SSD storage, preferably NVMe. The data volume holds the scan archives, scan results, dependency caches for cryptography, uploaded AI model files, and the TLS certificates. Earnie mounts it at /var/lib/earnie by default. You can change the path with the EARNIE_DATA_DIR setting. If you run the database as a container, its data is on this volume too. Back up the data volume along with the database. See Upgrading and backing up.

​

Database

Earnie needs PostgreSQL 16. It doesn’t need any PostgreSQL extensions, and it doesn’t need any other data store, message broker, or object storage. Earnie’s job queue runs in the same database. The Earnie API and each scanner worker open their own connections, up to 25 each by default. With both the cryptography and AI provenance workers, that’s up to 75 connections. The DB_MAX_CONNS setting changes the limit for each one. If you use a managed database, check that its plan allows enough connections.

​

Software

• Operating system: a 64-bit Linux distribution on x86-64 (amd64). Earnie’s server images aren’t available for ARM. SCANOSS runs Earnie on Ubuntu 24.04.
• Docker: Docker Engine 23 or later, which can load the zstd-compressed image archive, with the Docker Compose v2 plugin, version 2.20 or later. Install both from Docker’s own repository, because your distribution’s packages may be too old.
• Docker’s firewall: for cryptography scans, Docker must manage the host’s iptables rules, which it does by default. Earnie adds its sandbox rules to Docker’s DOCKER-USER chain. If Docker runs without its iptables firewall, the cryptography worker doesn’t start.
• zstd: the zstd package, to extract the installation bundle.

​

Network Access

​

Inbound

Earnie needs a DNS name, such as earnie.example.com, that your users, CI pipelines, and Git provider can reach. It listens on these ports: Earnie gets its TLS certificate from Let’s Encrypt by default. This needs the DNS name to be publicly resolvable, and ports 80 and 443 to be reachable from the internet. If that isn’t possible, for example for an internal name, provide your own certificate instead. See TLS certificate. You can put a load balancer in front of Earnie. It must pass TLS through to port 443, or re-encrypt to Earnie on port 443. Earnie redirects plain HTTP to HTTPS, so a load balancer can’t send it plain HTTP. See Using a load balancer.

​

Outbound

The installer pulls the container images from the registries. If your server can’t reach them, install from the offline image archive that SCANOSS gives you instead. See Installing Earnie. Earnie doesn’t support fully air-gapped networks yet. Even in the fully on-premises option, it needs to reach the CISA feed and, for cryptography scans, your dependencies’ package registries or your mirrors of them.

​

The Cryptography Sandbox

Cryptography scans build your dependencies in a sandbox, a separate container with its own firewall rules. The sandbox can reach:

• Public package registries, such as Maven Central, Gradle, npm, Yarn, PyPI, crates.io, and the Go module proxy, on ports 80 and 443.
• Your private registry mirrors, if you add their address ranges, as comma-separated CIDRs, to the SCANS_SANDBOX_MIRROR_CIDRS setting. Mirrors are reachable on any port.
• One internal Earnie endpoint that the sandbox needs to do its work.

It can’t reach the rest of your network, the Earnie server’s other services, or anything else. The allowlist works on IP address ranges, not host names. The registries sit behind large content delivery networks (Cloudflare, Fastly, GitHub, and Google), so the sandbox can reach any site hosted on those networks on ports 80 and 443. DNS lookups aren’t filtered.

​

What’s Next

• Installing Earnie walks through installing, configuring, and connecting Earnie. Start here once your server is ready.
• Deployment and data flow explains exactly what Earnie sends to SCANOSS and to other services.
• Running Earnie on a cloud provider suggests machines, managed databases, and load balancers on AWS, Google Cloud, Azure, and DigitalOcean.
• Upgrading and backing up covers new releases, backups, and rollback.
• Workspace setup covers the first steps after Earnie is running.