Installing Earnie

This page takes you from a fresh Linux host to a signed-in Earnie. It applies when you host Earnie yourself, in the self-hosted Earnie or fully on-premises option. See Deployment options. Earnie runs on one server with Docker Compose. You fill in one configuration file, tenant.env, and run one script, install.sh. To upgrade or back up later, see Upgrading and backing up.

What SCANOSS gives you

For each Earnie release, SCANOSS sends you:

The installation bundle. An archive, earnie-bundle-vX.Y.Z.tar.gz, with the Docker Compose files, the install.sh script, and tenant.env.example, which lists every setting with its default.
The offline image archive. Needed only if your server can’t reach the container registry. It comes as split parts, earnie-onprem-images-vX.Y.Z.tar.gz.part-00, part-01, and so on, with a .sha256 file to check them.
A SCANOSS API key. Earnie uses it to match your code against the SCANOSS knowledge base.

Ask your SCANOSS contact for these. Each release has a version number, written vX.Y.Z on this page.

Before you begin

You need:

A server that meets the Self-hosting requirements.
A DNS name for Earnie, such as earnie.example.com, pointing at the server.
A PostgreSQL 16 database, or the server’s own disk space to run one as a container.
A TLS certificate for that DNS name, unless Earnie can get one from Let’s Encrypt. See TLS certificate.

Prepare the host

On AWS, Google Cloud, Azure, or DigitalOcean, see Running Earnie on a cloud provider for the machine, disk, and network to choose.

Install Docker. Install Docker Engine and the Docker Compose plugin from Docker’s own repository, as described in Install Docker Engine for your distribution. The package in your distribution’s own repository may be too old. Check the versions:
docker version docker compose version
Give the data directory its own volume. Earnie keeps everything that must survive the host under one directory, /var/lib/earnie by default. It holds scan archives, caches, certificates, and the bundled database if you use it. Mount a volume of 50 GB or more there before you install. To use another path, set EARNIE_DATA_DIR in tenant.env. For example, for a new, empty disk that the server sees as /dev/sdb:
sudo mkfs.ext4 /dev/sdb sudo mkdir -p /var/lib/earnie echo "UUID=$(sudo blkid -s UUID -o value /dev/sdb) /var/lib/earnie ext4 defaults,nofail 0 2" | sudo tee -a /etc/fstab sudo mount /var/lib/earnie
Check the disk’s name with lsblk first: formatting the wrong disk erases it. A new ext4 file system has a lost+found directory. Leave it there.
Copy the bundle to the server. Extract it in a directory such as /opt/earnie:
sudo mkdir -p /opt/earnie sudo tar -xzf earnie-bundle-vX.Y.Z.tar.gz -C /opt/earnie cd /opt/earnie/earnie-vX.Y.Z
The bundle extracts to its own directory, earnie-vX.Y.Z. That is the bundle directory: run every command on this page from it.
Find the Docker group ID and the bridge address. You need both for tenant.env.
getent group docker | cut -d: -f3 ip -4 addr show docker0 | grep -oP 'inet \K[\d.]+'
The first command prints the group ID, which is the value for DOCKER_GID. The second prints the Docker bridge address, which is the value for DOCKER_BRIDGE_IP. The bridge address is usually 172.17.0.1.

Configure Earnie

Copy the example file and fill it in.

cp tenant.env.example tenant.env

Always edit tenant.env. Never edit .env. The installer writes .env from tenant.env every time it runs and overwrites your changes.

tenant.env is a Docker Compose environment file, not a shell script:

Write each setting as NAME=value on its own line.
Don’t use quotes and don’t write export. Quotes become part of the value.
A value runs to the end of the line, spaces included. Don’t add a trailing comment on the same line.

The installer sets the file’s permissions to 0600, because it holds secrets. Keep it readable only by the user who runs Docker Compose.

Identity

Setting	What to put
`EARNIE_TENANT`	A short name for this installation, such as `acme`. It names the Docker Compose project.
`EARNIE_HOST`	The DNS name users type, such as `earnie.example.com`. No `https://`, no path.
`EARNIE_VERSION`	The release you are installing, such as `v1.4.0`. Use the exact version of your bundle.
`EARNIE_ORG_NAME`	The name of your organisation in Earnie.
`EARNIE_PUBLIC_BASE_URL`	Leave the default, `https://${EARNIE_HOST}`. GitHub and GitLab deliver webhooks and callbacks to this address, so they must be able to reach it.

Host

Setting	What to put
`EARNIE_DATA_DIR`	The data directory. The default is `/var/lib/earnie`.
`DOCKER_BRIDGE_IP`	The Docker bridge address from the previous section.
`DOCKER_GID`	The ID of the host’s `docker` group. The cryptography worker needs it to start its dependency sandbox.

Database

Earnie needs PostgreSQL 16. Choose one of two ways to provide it. Use your own PostgreSQL server. Create an empty database and a user that owns it. Then set the connection URL:

DB_URL=postgres://earnie:<password>@db.example.com:5432/earnie

Run PostgreSQL as a container on the same server. Set these three lines. The password in DB_URL must match ONPREM_PG_PASSWORD.

EARNIE_ONPREM_POSTGRES=true
ONPREM_PG_PASSWORD=<password>
DB_URL=postgres://earnie:<password>@postgres:5432/earnie

Use a password made of letters and digits, such as the output of openssl rand -hex 16, so you don’t have to escape it in the URL. The bundled database stores its files in <EARNIE_DATA_DIR>/postgres. Leave the DATABASE_URL=${DB_URL} line as it is.

Secrets

Generate these with a random source. Each command prints 64 hexadecimal characters.

openssl rand -hex 32

Run it once for each of the first three values below.

Setting	What to put
`JWT_SECRET`	A random value of at least 32 characters. Earnie uses it to sign session tokens.
`EARNIE_SSO_KEK_HEX`	Exactly 64 hexadecimal characters. Earnie uses it to encrypt your single sign-on client secret.
`EARNIE_INTEGRATIONS_KEK_HEX`	Exactly 64 hexadecimal characters. Earnie uses it to encrypt your GitHub and GitLab credentials.
`SCANOSS_API_KEY`	The key SCANOSS sent you. If it’s empty, Earnie still starts, but it logs the warning `SCANOSS_API_KEY is not set` and calls the SCANOSS API without a key, which limits or refuses your scans.

Use a different value for each of the three generated secrets. Keep a copy of tenant.env somewhere safe. See Upgrading and backing up. Earnie supports sign-in with a password, with single sign-on (OIDC), or both. Production installations refuse to start with neither.

You want	`EARNIE_PASSWORD_AUTH_ENABLED`	`OIDC_ISSUER`, `OIDC_CLIENT_ID`, `OIDC_CLIENT_SECRET`
Single sign-on only	`false` (the default)	All three set
Password and single sign-on	`true`	All three set
Password only	`true`	All three empty

Set all three OIDC values or none of them. See Single sign-on for what to enter. Leave EARNIE_ENV=production.

First administrator

The installer creates your organisation and its first administrator when it starts Earnie. It is safe to run again.

Setting	What to put
`EARNIE_INITIAL_ADMIN_EMAIL`	The email address of the first administrator.
`EARNIE_INITIAL_ADMIN_PASSWORD`	The administrator’s password, from 12 to 128 characters. Required when password sign-in is on, because otherwise nobody can sign in. If you set it, the installer sets this password again on every run.

Scanners

EARNIE_MODULES lists the scanners and features your organisation has bought, separated by commas, with no spaces.

Value	What it turns on
`oss`	Open-source matching.
`crypto`	Cryptography detection. Starts a separate worker and a dependency sandbox.
`ai`	AI provenance. Starts a separate worker.
`enrichment`	Licence and vulnerability data for the components that the cryptography and AI scanners find. It starts no worker.

For example, EARNIE_MODULES=oss,crypto. Set only what your organisation has. Hardware needs depend on this list. See CPU and memory.

Other settings

Every other setting in tenant.env.example has a default that works. Two are worth knowing about:

Setting	What it does
`SCANOSS_API_URL`	The SCANOSS API Earnie talks to. The default is `https://api.scanoss.com`. In the fully on-premises option, set it to your own SCANOSS API.
`SCANS_MAX_UPLOAD_MB`	The largest upload Earnie accepts, in MiB. The default is 3072. Use a whole number with no unit.

TLS certificate

Earnie serves HTTPS on port 443. The EARNIE_TLS setting decides where its certificate comes from.

Setting	`acme` (default)	`custom`
Certificate source	Earnie gets one from Let’s Encrypt and renews it for you.	You provide one and renew it yourself.
`EARNIE_HOST` must be	Publicly resolvable.	Any name the certificate covers, including an internal name.
Inbound access	Ports 80 and 443 from the internet.	Port 443 from your users. Port 80 only if you want the redirect.
`EARNIE_ACME_EMAIL`	Required. The contact address for the certificate.	Not needed.
Contacts Let’s Encrypt	Yes.	No.

Let’s Encrypt

With EARNIE_TLS=acme, set EARNIE_ACME_EMAIL to a monitored address. There is nothing else to do. The name in EARNIE_HOST must already point at the server, or the certificate request fails.

Your own certificate

Use this when the server has only an internal name, when it can’t reach the internet, or when your organisation issues its own certificates.

Set EARNIE_TLS=custom in tenant.env.
Create the certificate directory. The default is /var/lib/earnie/tls, which is <EARNIE_DATA_DIR>/tls. To use another directory, set EARNIE_TLS_DIR.
Put two files in that directory:
File Content
cert.pem The full chain: your server certificate first, then any intermediate certificates.
key.pem The private key, unencrypted.
The certificate must cover the name in EARNIE_HOST.

File	Content
`cert.pem`	The full chain: your server certificate first, then any intermediate certificates.
`key.pem`	The private key, unencrypted.

If either file is missing or empty, install.sh stops before it starts anything and names the file it expects. To renew, replace both files, then restart the proxy from the bundle directory:

docker compose restart caddy

Using a load balancer

You can put a load balancer in front of Earnie. It must do one of these:

Pass TLS through. Forward the TCP connection to port 443 on the Earnie server without decrypting it. Earnie’s certificate is what users see.
Re-encrypt to Earnie. Terminate TLS on the balancer, then open a new TLS connection to port 443 on Earnie. Set EARNIE_TLS=custom, and use a certificate that the balancer trusts.

Earnie doesn’t support plain HTTP from the balancer. For the balancers of AWS, Google Cloud, Azure, and DigitalOcean, see Put a load balancer in front. Earnie uses the client’s address for rate limits and for the audit log. Behind a balancer, every request appears to come from the balancer unless you tell Earnie to trust the balancer’s X-Forwarded-For header. This applies when the balancer re-encrypts. A balancer that passes TLS through can’t add the header.

In the bundle’s Caddyfile, add a trusted_proxies entry to the global block at the top. Use the balancer’s own source range, never a range that clients can send from.
{ log { exclude admin.api } servers { trusted_proxies static 10.20.0.0/24 } }
In tenant.env, add the same range after web:
EARNIE_TRUSTED_PROXIES=web,10.20.0.0/24

If your certificate comes from an internal CA

Everything that connects to Earnie must trust the CA that signed Earnie’s certificate. Plan for these:

Who connects	What to do
Browsers	Distribute the CA through your company’s device management.
The Earnie CLI	On Linux, set `SSL_CERT_FILE` to a file that holds the CA certificate, or install the CA in the operating system’s trust store. On macOS and Windows, install it in the operating system’s store.
MCP clients built on Node.js	Set `NODE_EXTRA_CA_CERTS` to a file that holds the CA certificate.
CI runners	Install the CA on the runner, then use the same settings as for the CLI.
Your GitLab or GitHub Enterprise Server	Its administrator adds the CA to that server’s trust store. The server delivers webhooks to Earnie and refuses to deliver them if it doesn’t trust the certificate. Don’t turn off certificate verification.

Install

With access to the container registry

From the bundle directory:

./install.sh

The script checks that Docker and the Compose plugin are present, writes .env, pulls the images for your EARNIE_VERSION, starts Earnie, and waits for every service to be healthy. The registry needs credentials that SCANOSS provides. Your SCANOSS contact tells you how to sign in to it.

From the offline image archive

Use the archive when your server can’t reach the container registry.

Copy the archive parts and the .sha256 file to the server, into the bundle directory. You need free disk space for about twice the archive’s size while you join and load it. You can delete the joined file and the parts afterwards, but keep them if you might run the installer again. See Changing configuration later.
Set EARNIE_VERSION in tenant.env to the archive’s version.
Join the parts and check them:
cat earnie-onprem-images-vX.Y.Z.tar.gz.part-* > earnie-onprem-images-vX.Y.Z.tar.gz sha256sum -c earnie-onprem-images-vX.Y.Z.sha256
The file has a line for the joined archive and one for each part. Every line must end in OK. If one doesn’t, copy that file again. The .images.txt file that comes with the archive lists the images inside it.

Install from the archive:

./install.sh earnie-onprem-images-vX.Y.Z.tar.gz

The loaded images keep their version tags, and Docker Compose uses them without pulling.

The archive holds the images for open-source matching and cryptography detection. Cryptography detection runs on the same earnie-api image, so you won’t see a separate image for it in .images.txt. The archive doesn’t include the AI provenance image. If EARNIE_MODULES includes ai, ask your SCANOSS contact how to get it.

Check that Earnie is healthy

When the installer finishes, it prints the address of the health check. Open it, or request it from the command line:

curl -fsS https://earnie.example.com/healthz

If your certificate comes from an internal CA that the server doesn’t trust, add --cacert with the CA’s certificate, for example curl -fsS --cacert internal-ca.pem https://earnie.example.com/healthz. A healthy Earnie answers with a success status. To see every service, including the ones that have finished:

docker compose ps -a

Every service must show running or healthy. The one-time services migrate, bootstrap, and data-init finish and show exited (0). That’s normal. Open https://<EARNIE_HOST> in a browser. Sign in with the administrator email and password from tenant.env, or with single sign-on if you set it up. Then continue with Workspace setup.

Single sign-on

Earnie signs users in through an OpenID Connect (OIDC) identity provider such as Microsoft Entra ID, Okta, or Keycloak.

In your identity provider, register Earnie as a web application.
Set its redirect URL to:
https://<EARNIE_HOST>/auth/callback
Copy the issuer URL, the client ID, and a client secret into tenant.env:
Setting What to put
OIDC_ISSUER The issuer URL of your identity provider.
OIDC_CLIENT_ID The application’s client ID.
OIDC_CLIENT_SECRET The application’s client secret.
Leave OIDC_REDIRECT_URL as it is. It already points at the address above.
Apply the change.

Setting	What to put
`OIDC_ISSUER`	The issuer URL of your identity provider.
`OIDC_CLIENT_ID`	The application’s client ID.
`OIDC_CLIENT_SECRET`	The application’s client secret.

When the client secret expires, create a new one in your identity provider, replace OIDC_CLIENT_SECRET, and apply the change. If sign-in fails with a redirect_uri_mismatch error, the redirect URL in your identity provider doesn’t match the one above.

Connecting your Git server

Earnie reads your repositories from GitHub or GitLab and posts its results on pull and merge requests. The in-app steps are the same as in the SCANOSS-hosted option. See Connecting a repository. This section covers what your self-hosted installation must provide. Your Git server must be able to reach Earnie at EARNIE_PUBLIC_BASE_URL. It delivers webhooks there, and GitHub redirects the browser there while you connect. Earnie must be able to reach your Git server too.

GitLab (self-managed)

Version. GitLab 17.4 or later.
Token. Create a group access token with the api and read_repository scopes. A group Owner creates it. Earnie needs the Maintainer role on each project it imports, because it registers a webhook on each one.
Reachability. Earnie only sends the token over HTTPS. GitLab must be reachable from the Earnie server over HTTPS.
Webhooks. Earnie registers one project webhook per imported project. It points at <EARNIE_PUBLIC_BASE_URL>/webhooks/gitlab/<connection id>. If Earnie has a private address, GitLab blocks the webhook by default. An administrator then needs to turn on Allow requests to the local network from webhooks and integrations, under Admin Area, Settings, Network, Outbound requests. Alternatively, add Earnie’s host to the allowlist on the same page.
Earnie trusts GitLab’s CA. If an internal CA signed GitLab’s certificate, paste that CA certificate into My GitLab uses an internal CA when you connect.
GitLab trusts Earnie’s CA. If an internal CA signed Earnie’s certificate, GitLab’s administrator must add that CA to GitLab’s trusted certificates. Until they do, GitLab fails every delivery with a certificate verify failed error. Earnie always asks GitLab to verify the certificate.

GitHub.com

Earnie connects to GitHub by creating a GitHub App for your installation.

Setting	What to put
`EARNIE_GITHUB_APP_NAME`	A name for your GitHub App. GitHub App names are unique across all of GitHub, so include your company name, for example `Earnie Acme`. If the name is taken, creating the app fails with `name already taken`.
`EARNIE_GITHUB_DEVICE_CLIENT_ID`	The client ID of the GitHub sign-in that Earnie uses to list your GitHub organisations. Your SCANOSS contact gives you the value. Without it, the Authorize step of Connect GitHub doesn’t work.

GitHub redirects the browser to your Earnie address during the connection and sends webhooks there afterwards, so EARNIE_PUBLIC_BASE_URL must be a name that GitHub can resolve and reach.

GitHub Enterprise Server

You can connect GitHub.com and any number of GitHub Enterprise Server hosts to the same Earnie. Choose GitHub Enterprise Server when you connect, then enter the server’s address.

Version. GitHub Enterprise Server 3.4 or later.
Network. Earnie reaches the server over HTTPS. The server delivers webhooks to <EARNIE_PUBLIC_BASE_URL>/webhooks/github/<server host>, so it must be able to reach Earnie.
Internal CA. If an internal CA signed the server’s certificate, paste that CA certificate when you connect. If an internal CA signed Earnie’s certificate, the server’s administrator must trust it, as for GitLab.
Organisation. The organisation list isn’t available on Enterprise Server, so you type the organisation’s name.
GitHub Actions. The scanoss/earnie-cli action works on Enterprise Server only with GitHub Connect or after you sync the action with actions-sync. Set the EARNIE_PROJECT environment variable, or the action’s project input, because the CLI can’t work out the project from an Enterprise Server remote.

Changing configuration later

To change a setting:

Edit tenant.env.
Run the installer again from the bundle directory:
./install.sh
If the server can’t reach the container registry, always pass the archive, even when the images are already loaded:
./install.sh earnie-onprem-images-vX.Y.Z.tar.gz
Without it, the installer tries to pull the images, fails with unauthorized, and changes nothing.

The installer rewrites .env, restarts the services whose settings changed, and runs the one-time services again. That includes setting the administrator password again if EARNIE_INITIAL_ADMIN_PASSWORD is set.

Turn on a scanner later

Add the scanner to EARNIE_MODULES, for example EARNIE_MODULES=oss,crypto, and run the installer as above. The installer starts the scanner’s worker. Check that the server has the extra CPU and memory it needs first. See Self-hosting requirements. To confirm, check that the enabled_modules list in Earnie’s GET /v1/me response includes the new scanner.

Troubleshooting

Start with the state and the logs of every service:

docker compose ps
docker compose logs --tail=100 <service>

The services are caddy, web, earnie-api, and, when enabled, postgres, worker-crypto, and worker-ai.

Symptom	Cause and fix
`tenant.env not found`	You haven’t created the file, or you aren’t in the bundle directory. Run `cp tenant.env.example tenant.env`, fill it in, and run `./install.sh` from the bundle directory.
`EARNIE_ACME_EMAIL is required with EARNIE_TLS=acme`	Set `EARNIE_ACME_EMAIL`, or switch to `EARNIE_TLS=custom`.
`EARNIE_TLS=custom needs .../cert.pem`	`cert.pem` or `key.pem` is missing or empty in the certificate directory. See Your own certificate.
`pulling images` fails with `unauthorized`	The server can’t pull from the container registry. Run `./install.sh` with the offline image archive. See From the offline image archive.
`ONPREM_PG_PASSWORD is required`	You set `EARNIE_ONPREM_POSTGRES=true` without a password.
The certificate isn’t issued, and the `caddy` log shows ACME errors	The name in `EARNIE_HOST` doesn’t resolve to the server from the internet, or port 80 or 443 is blocked. On an internal name, use `EARNIE_TLS=custom`. After you fix it, run `docker compose restart caddy`.
A container exits at start	Read its log with `docker compose logs <service>`. A missing or invalid secret is the usual cause. The two KEKs must be exactly 64 hexadecimal characters.
`502 Bad Gateway`	`web` or `earnie-api` isn’t healthy yet. Run `docker compose ps` and wait, or read the log of the service that isn’t healthy.
`DB_URL` connection refused	Check the host, port, user, and password in `DB_URL`, and any firewall between Earnie and the database.
Single sign-on fails with `redirect_uri_mismatch`	The redirect URL in your identity provider must be exactly `https://<EARNIE_HOST>/auth/callback`.
GitLab connect fails with a certificate error (`host_untrusted`)	An internal CA signed GitLab’s certificate. Paste the CA certificate into My GitLab uses an internal CA.
GitLab webhook deliveries fail with `certificate verify failed`	GitLab doesn’t trust Earnie’s certificate. Add the CA to GitLab’s trusted certificates.
Importing a GitLab project fails with `webhook_url_rejected`	GitLab blocks webhooks to private addresses. See GitLab (self-managed).
Connecting GitHub fails with `name already taken`	Choose another `EARNIE_GITHUB_APP_NAME`, and apply the change.
The `worker-crypto` service doesn’t start	The `sandbox-egress` service isn’t healthy, usually because Docker isn’t running with its iptables firewall. Read `docker compose logs sandbox-egress`.

What’s next

Workspace setup covers the first steps in the app.
Connecting a repository explains each Git connection in the app.
Upgrading and backing up covers new releases and backups.
Running Earnie on a cloud provider covers AWS, Google Cloud, Azure, and DigitalOcean.

Get started

Development

Pull requests & CI

Governance

Evidence & audit

Administration

Migrating

API reference

What SCANOSS gives you

Before you begin

Prepare the host

Configure Earnie

Identity

Host

Database

Secrets

First administrator

Scanners

Other settings

TLS certificate

Let’s Encrypt

Your own certificate

Using a load balancer

If your certificate comes from an internal CA

Install

With access to the container registry

From the offline image archive

Check that Earnie is healthy

Single sign-on

Connecting your Git server

GitLab (self-managed)

GitHub.com

GitHub Enterprise Server

Changing configuration later

Turn on a scanner later

Troubleshooting

What’s next

​What SCANOSS gives you

​Before you begin

​Prepare the host

​Configure Earnie

​Identity

​Host

​Database

​Secrets

​Sign-in methods

​First administrator

​Scanners

​Other settings

​TLS certificate

​Let’s Encrypt

​Your own certificate

​Using a load balancer

​If your certificate comes from an internal CA

​Install

​With access to the container registry

​From the offline image archive

​Check that Earnie is healthy

​Sign in

​Single sign-on

​Connecting your Git server

​GitLab (self-managed)

​GitHub.com

​GitHub Enterprise Server

​Changing configuration later

​Turn on a scanner later

​Troubleshooting

​What’s next

What SCANOSS gives you

Before you begin

Prepare the host

Configure Earnie

Identity

Host

Database

Secrets

Sign-in methods

First administrator

Scanners

Other settings

TLS certificate

Let’s Encrypt

Your own certificate

Using a load balancer

If your certificate comes from an internal CA

Install

With access to the container registry

From the offline image archive

Check that Earnie is healthy

Sign in

Single sign-on

Connecting your Git server

GitLab (self-managed)

GitHub.com

GitHub Enterprise Server

Changing configuration later

Turn on a scanner later

Troubleshooting

What’s next