This page is guidance, not a tested recipe. SCANOSS runs Earnie on its own virtual machines, not on these four providers. Machine names and features change, so check them in your provider’s console, and for your region, before you build.
The simplest setup
For most organisations, this is enough:- One virtual machine on x86-64, sized from the table below, running Ubuntu 24.04 LTS.
- A static public IP address attached to it, so the address survives a restart.
- A DNS record that points your Earnie name, such as
earnie.example.com, at that address. - Firewall rules that allow ports 443 and 80 in, and allow outbound traffic.
- Let’s Encrypt for the certificate, which is Earnie’s default.
Choose a machine
Earnie’s server images are built for x86-64 only. Don’t choose an ARM machine, such as AWS Graviton, Google Axion or Tau T2A, Azure Cobalt or Ampere, because Earnie won’t start on it. Pick a machine with dedicated CPU, not a burstable or shared one. Cryptography scans keep every core busy for minutes, and a burstable machine slows down once it runs out of CPU credits. These machines match the recommended sizes in Self-hosting requirements. They are examples. Any machine with at least the same CPU and memory works.
If you run PostgreSQL as a container on the same machine, add the database’s CPU and memory from Database.
Disk
Put Earnie’s data directory,/var/lib/earnie by default, on SSD storage of the size in Disk.
A separate data disk, rather than the boot disk, makes it easier to resize, snapshot, and move to a new machine.
Network
Allow these in:
- Port 443 from your users, your CI runners, and your GitHub or GitLab server.
- Port 80 from the internet if you use Let’s Encrypt, because it checks your name over port 80. With your own certificate, port 80 only redirects to HTTPS, and you can limit it like port 443.
Use a managed PostgreSQL service
You can run PostgreSQL as a container on the Earnie machine, or use your provider’s managed service. A managed service handles backups, patches, and high availability for you.
Whichever you choose:
- Use PostgreSQL 16. Earnie needs no extensions.
- Put the database in the same region as the Earnie machine, and connect over the private network. Don’t give the database a public address.
-
Require TLS. Add
sslmode=requireto the connection URL: -
Give Earnie a database it owns. Earnie creates its tables when it starts, so its user needs to create objects in the database. Connected as the service’s administrator, run:
If your organisation doesn’t allow a separate owner, connect to the
earniedatabase and grant the rights Earnie needs instead: -
Check the connection limit. Earnie opens up to 25 connections, set by
DB_MAX_CONNSintenant.env. The smallest plans of some services allow fewer. Pick a plan that allows more, or lowerDB_MAX_CONNS. - Connect to the database directly, not through a connection pooler in transaction mode, such as PgBouncer or a provider’s connection pool. Earnie holds database locks across statements, which transaction pooling breaks.
EARNIE_ONPREM_POSTGRES=false in tenant.env. See Database.
Put a load balancer in front
You don’t need a load balancer to run Earnie. Use one when your organisation requires all traffic to enter through it, for example for a web application firewall or a shared certificate. A load balancer must either pass TLS through to port 443 on Earnie, or re-encrypt to it. Plain HTTP from the balancer to Earnie doesn’t work. See Using a load balancer. Passing TLS through is the simpler choice. The balancer forwards TCP on port 443, and Earnie keeps its own certificate. If you use Let’s Encrypt, forward port 80 too. Use a TCP health check on port 443. Re-encrypting lets the balancer present its own certificate and inspect requests. Earnie then needs a certificate of its own on port 443, set withEARNIE_TLS=custom. Tell Earnie to trust the balancer’s X-Forwarded-For header, as described in Using a load balancer, or every request appears to come from the balancer. For the health check, use HTTPS on port 443 with the path /healthz, and send your Earnie name as the host if the balancer allows it.
If you pass TLS through on a balancer that hides the client’s address, Earnie’s rate limits and audit log record the balancer’s address for every request.
Back up
Back up the database, the data directory, andtenant.env, as described in Upgrading and backing up. On a cloud, you can use the provider’s tools for the first two:
- With a managed PostgreSQL service, turn on its automated backups and point-in-time recovery. Before an upgrade, also take a manual snapshot or a
pg_dump, so you can roll back to the moment just before it. - For the data directory, take a disk snapshot: an EBS snapshot, a persistent disk snapshot, an Azure managed disk snapshot, or a DigitalOcean Volume or Droplet snapshot. If PostgreSQL runs as a container on the same disk, stop Earnie first with
docker compose stop, so the snapshot holds a database that agrees with the files. - Keep
tenant.envapart from the machine, for example in your provider’s secret manager. It holds the keys that decrypt the credentials stored in the database.
What’s next
- Self-hosting requirements lists the hardware, software, and network access in full.
- Installing Earnie walks through the installation on the machine.
- Upgrading and backing up covers new releases and restores.