> ## Documentation Index
> Fetch the complete documentation index at: https://docs.scanoss.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Running Earnie on a cloud provider

> Machine types, networking, managed PostgreSQL, and load balancers for running a self-hosted Earnie on AWS, Google Cloud, Azure, or DigitalOcean.

Earnie installs the same way on any cloud: one Linux virtual machine with Docker, set up as in [Installing Earnie](/en/latest/earnie/self-hosting/installation). This page tells you which services to pick on AWS, Google Cloud, Azure, and DigitalOcean, and what to watch for on each.

<Note>
  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.
</Note>

## The simplest setup

For most organisations, this is enough:

1. **One virtual machine** on x86-64, sized from the table below, running Ubuntu 24.04 LTS.
2. **A static public IP address** attached to it, so the address survives a restart.
3. **A DNS record** that points your Earnie name, such as `earnie.example.com`, at that address.
4. **Firewall rules** that allow ports 443 and 80 in, and allow outbound traffic.
5. **Let's Encrypt** for the certificate, which is Earnie's default.

Add a managed PostgreSQL service or a load balancer only when you need them. Each is covered below.

## 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](/en/latest/earnie/self-hosting-requirements#cpu-and-memory). They are examples. Any machine with at least the same CPU and memory works.

| Scanners | Recommended | AWS | Google Cloud | Azure | DigitalOcean (General Purpose or CPU-Optimized) |
| - | - | - | - | - | - |
| Open source | 2 vCPU, 8 GB RAM | `m7i.large` | `n2-standard-2` | `Standard_D2s_v5` | 2 vCPU, 8 GB |
| Open source and AI provenance | 8 vCPU, 32 GB RAM | `m7i.2xlarge` | `n2-standard-8` | `Standard_D8s_v5` | 8 vCPU, 32 GB |
| Open source and cryptography | 16 vCPU, 32 GB RAM | `c7i.4xlarge` | `n2-custom-16-32768` | `Standard_F16s_v2` | CPU-Optimized, 16 vCPU, 32 GB |
| Open source, cryptography, and AI provenance | 16 vCPU, 64 GB RAM | `m7i.4xlarge` | `n2-standard-16` | `Standard_D16s_v5` | 16 vCPU, 64 GB |

If you run PostgreSQL as a container on the same machine, add the database's CPU and memory from [Database](/en/latest/earnie/self-hosting-requirements#database).

### Disk

Put Earnie's data directory, `/var/lib/earnie` by default, on SSD storage of the size in [Disk](/en/latest/earnie/self-hosting-requirements#disk).

| Provider | Disk |
| - | - |
| AWS | An EBS `gp3` volume. |
| Google Cloud | A Balanced or SSD persistent disk, or Hyperdisk Balanced on machine series that need it. |
| Azure | A Premium SSD or Premium SSD v2 managed disk. |
| DigitalOcean | The Droplet's own SSD, or a Volume if you want the data to outlive the Droplet. |

A separate data disk, rather than the boot disk, makes it easier to resize, snapshot, and move to a new machine.

## Network

| Provider | Static IP address | Firewall | Outbound from a private subnet |
| - | - | - | - |
| AWS | Elastic IP | Security group | NAT gateway |
| Google Cloud | Static external IP | VPC firewall rules | Cloud NAT |
| Azure | Static public IP | Network security group | NAT gateway |
| DigitalOcean | Reserved IP | Cloud Firewall | VPC NAT gateway |

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.

Allow outbound traffic on ports 80 and 443 to the destinations in [Outbound](/en/latest/earnie/self-hosting-requirements#outbound). Most providers allow all outbound traffic by default. If the machine sits in a private subnet without a public address, it needs a NAT gateway to reach them. On Azure, check that the subnet has outbound access at all: newer virtual networks can have private subnets that have none until you add a NAT gateway.

Keep SSH closed to the internet. Use your provider's console access, such as AWS Systems Manager Session Manager, Google Cloud IAP, or Azure Bastion, or allow SSH only from your own network.

## 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.

| Provider | Service |
| - | - |
| AWS | Amazon RDS for PostgreSQL |
| Google Cloud | Cloud SQL for PostgreSQL |
| Azure | Azure Database for PostgreSQL flexible server |
| DigitalOcean | Managed PostgreSQL |

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=require` to the connection URL:

  ```text theme={null}
  DB_URL=postgres://earnie:<password>@<database host>:5432/earnie?sslmode=require
  ```

* **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:

  ```sql theme={null}
  CREATE ROLE earnie LOGIN PASSWORD '<password>';
  CREATE DATABASE earnie OWNER earnie;
  ```

  If your organisation doesn't allow a separate owner, connect to the `earnie` database and grant the rights Earnie needs instead:

  ```sql theme={null}
  GRANT CONNECT, CREATE ON DATABASE earnie TO earnie;
  GRANT USAGE, CREATE ON SCHEMA public TO earnie;
  ```

* **Check the connection limit.** Earnie opens up to 25 connections, set by `DB_MAX_CONNS` in `tenant.env`. The smallest plans of some services allow fewer. Pick a plan that allows more, or lower `DB_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.

Then leave `EARNIE_ONPREM_POSTGRES=false` in `tenant.env`. See [Database](/en/latest/earnie/self-hosting/installation#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](/en/latest/earnie/self-hosting/installation#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 with `EARNIE_TLS=custom`. Tell Earnie to trust the balancer's `X-Forwarded-For` header, as described in [Using a load balancer](/en/latest/earnie/self-hosting/installation#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.

| Provider | Pass TLS through | Re-encrypt |
| - | - | - |
| AWS | Network Load Balancer with a TCP listener on 443 and a TCP target group on 443. With instance targets, Earnie sees the client's address. | Application Load Balancer with an HTTPS listener and an HTTPS target group on 443. The balancer doesn't verify Earnie's certificate, so a self-signed one works. |
| Google Cloud | External passthrough Network Load Balancer on TCP 443. Earnie sees the client's address. | External Application Load Balancer with an HTTPS backend service on 443. By default, the balancer doesn't verify Earnie's certificate. |
| Azure | Azure Load Balancer with a rule for TCP 443. Earnie sees the client's address. | Application Gateway v2 with HTTPS backend settings on 443. Set the backend host name to your Earnie name. The gateway verifies Earnie's certificate, so for a certificate from an internal CA, upload that CA's root certificate to the backend settings. |
| DigitalOcean | Load Balancer with an HTTPS-to-HTTPS forwarding rule and TLS passthrough turned on. Earnie sees the balancer's address, not the client's. | Load Balancer with an HTTPS-to-HTTPS forwarding rule without passthrough. |

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, and `tenant.env`, as described in [Upgrading and backing up](/en/latest/earnie/self-hosting/upgrading-and-backups). 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.env` apart 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](/en/latest/earnie/self-hosting-requirements) lists the hardware, software, and network access in full.
* [Installing Earnie](/en/latest/earnie/self-hosting/installation) walks through the installation on the machine.
* [Upgrading and backing up](/en/latest/earnie/self-hosting/upgrading-and-backups) covers new releases and restores.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.