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

# Deploy Perfai on AWS

> Launch the Perfai appliance from AWS Marketplace, sign in, add your own certificate, and keep it up to date without losing data.

The Perfai appliance is a ready-made virtual machine image. You launch it in your own AWS account. It installs the full platform by itself on first start, and your data stays in your account.

## What you need

| | |
| - | - |
| Instance type | `m7i.xlarge` or larger (4 vCPU, 16 GB RAM) |
| Disk | 100 GB or more (gp3) |
| Ports | 443 and 80 open to your users. 22 open to your administrators only |
| AI models | Access to Anthropic Claude models in Amazon Bedrock, in the region where you launch |
| Network | Outbound internet access (HTTPS) |

## Launch the instance

1. Subscribe to **Perfai** in AWS Marketplace and choose **Launch**.
2. Choose the instance type, a key pair, a subnet with a public IP, and a security group with the ports above.
3. Attach an IAM role to the instance that allows Bedrock access (`bedrock:InvokeModel`, `bedrock:InvokeModelWithResponseStream` and `bedrock:Converse`). The appliance uses the instance role, so you do not store AWS keys on the machine.
4. Set the disk size to 100 GB or more, then launch.

First start takes about 15 to 20 minutes. The appliance finds its own address, creates all of its secrets, and installs the platform. Nothing that identifies a customer is built into the image, so every instance gets its own keys.

## Check progress

Open `http://<instance address>:9080` for the status page, or sign in over SSH (user `ubuntu`) and run:

```bash theme={null}
sudo perfai-health --print
```

The status is **starting** while it installs and **healthy** when every service is ready. Port 9080 shows status only. Open it just to the people who need it.

## Sign in

By default the appliance uses the address `<ip-with-dashes>.sslip.io` and a certificate it created itself, so your browser shows a warning until you add your own certificate (next section).

1. Open `https://cloud.<your domain>`.
2. Sign in as `admin@perfai.ai`. The generated password is the `GLOBAL_WEBAPP_ADMIN_PASSWORD` value in `/opt/perfai/lifecycle/config/perfai-secrets.env` (readable by root only):

```bash theme={null}
sudo grep GLOBAL_WEBAPP_ADMIN_PASSWORD /opt/perfai/lifecycle/config/perfai-secrets.env
```

3. Change the password when the console asks you to.

Keep a copy of that file in a safe place. It holds the keys for your data.

## Use your own domain and certificate

1. Create two DNS records that point to the instance: `<your domain>` and `*.<your domain>` (a wildcard).
2. Put the domain in `/etc/perfai/appliance.env` before first start, or switch later with the command below.
3. Get a certificate that covers `*.<your domain>`. A wildcard certificate from a public authority works, and so does one from your own CA.
4. Load it:

```bash theme={null}
sudo perfai-set-cert --domain <your domain> --cert fullchain.pem --key privkey.pem
```

If your certificate comes from a private CA, add `--ca ca.pem`. Without it, the services inside the platform cannot trust each other.

## Back up

```bash theme={null}
sudo perfai-backup
sudo perfai-backup --verify /var/lib/perfai/backups/<file>.archive
```

Backups are saved in `/var/lib/perfai/backups`. Copy them off the machine. Take one before every upgrade.

## Upgrade without losing data

You choose how to upgrade.

* **New image and restore (recommended).** Launch the new image, copy your data keys and a backup to it, and restore. This also updates the operating system and security hardening. You keep the old machine until you switch your users over, so you can go back at any time.
* **Upgrade in place.** Install a signed release folder with `sudo perfai-upgrade --release <folder>`. The appliance checks the release signature and every file checksum, backs up first, upgrades, and then checks that no database collection lost any documents. If a check fails, it stops and tells you how to put the previous release back.
* **Automatic upgrade (optional, off by default).** Turn it on with `sudo perfai-auto-upgrade --enable`. Every night it reads the signed Perfai release feed and installs a newer release only if the signature is valid. It never goes down to an older release.

Plan for 10 to 30 minutes of downtime. Scans that are running when an upgrade starts are interrupted. In-place upgrades need 30 GB of free disk space.

Your data is protected by three keys (`FIELD_ENCRYPTION_SECRET`, `SECRET_KEY` and `IV`). A restore refuses to run if the new machine's keys do not match the backup, so encrypted data is never restored unreadable. Export the keys with `sudo perfai-backup --export-secrets <file>`. Never put these keys in instance user data.

## Get help

Contact Perfai support through your account team, and include the output of `sudo perfai-health --print`.


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