# Deploy Cerbos to Cloud platforms

|     |     |
| --- | --- |
|  | This documentation is for<br>a previous<br>version of Cerbos. Choose 0.53.0 from the version picker at the top right or navigate to [https://docs.cerbos.dev](https://docs.cerbos.dev/) for the latest version. |

## Fly.io

You can deploy Cerbos on Fly.io as a [Fly Launch](https://fly.io/docs/apps) app. The following `fly.toml` file shows
how to deploy Cerbos with healthchecks and metrics:

```toml
app = '<APPLICATION_NAME>' (1)
primary_region = '<REGION>' (2)

[build]
  image = 'ghcr.io/cerbos/cerbos:0.37.0'

[[mounts]]
  source = 'policies'
  destination = '/policies'
  initial_size = '1GB'

[[services]]
  protocol = ''
  internal_port = 3592

[[services.ports]]
    port = 3592
    handlers = ['tls', 'http']

[[services.http_checks]]
    interval = '5s'
    timeout = '2s'
    grace_period = '5s'
    method = 'get'
    path = '/_cerbos/health'
    protocol = 'http'

[[services]]
  protocol = ''
  internal_port = 3593

[[services.ports]]
    port = 3593
    handlers = ['tls']

[services.ports.tls_options]
      alpn = ['h2']

[[vm]]
  memory = '1gb'
  cpu_kind = 'shared'
  cpus = 1

[metrics]
  port = 3592
  path = "/_cerbos/metrics"
```

|     |     |
| --- | --- |
| **1** | The name of the [Fly App](https://fly.io/docs/apps) |
| **2** | Pick a Fly.io [region](https://fly.io/docs/reference/regions/#fly-io-regions) |

The example above launches a Cerbos instance with the [minimal configuration](https://docs.cerbos.dev/cerbos/0.37.0/configuration/#minimal-configuration) using an empty [Fly volume](https://fly.io/docs/reference/volumes/) mounted as the policy directory. For production use cases, consider using one of the following methods for policy storage.

|     |     |
| --- | --- |
|  | Your host or service for an application should be listening on the right address within the VM: Fly Proxy reaches services through a private IPv4 address on each VM, so the process should listen on `0.0.0.0:<port>` ( [but see A note on IPv4 and IPv6 wildcards](https://fly.io/docs/networking/app-services/#a-note-on-ipv4-and-ipv6-wildcards)). |

- Cerbos [`git` driver](https://docs.cerbos.dev/cerbos/0.37.0/configuration/storage#git-driver) with a Git provider such as GitHub or GitLab

- Cerbos [`blob` driver](https://docs.cerbos.dev/cerbos/0.37.0/configuration/storage#blob-driver) with [Tigris](https://fly.io/docs/reference/tigris/#create-and-manage-a-tigris-storage-bucket)

- Cerbos [`sqlite3` driver](https://docs.cerbos.dev/cerbos/0.37.0/configuration/storage#sqlite3) with a standalone SQLite database or [LiteFS](https://fly.io/docs/litefs/#litefs-cloud)

- Cerbos [`postgres` driver](https://docs.cerbos.dev/cerbos/0.37.0/configuration/storage#postgres) with [Fly Postgres](https://fly.io/docs/postgres/)

- [Cerbos Hub](/content/product-cerbos-hub/index.html)

|     |     |
| --- | --- |
|  | Cerbos can be [configured entirely from the command line](https://docs.cerbos.dev/cerbos/0.37.0/configuration/) using `--set` flags. On the Fly.io platform, they can be set by overriding the `cmd` setting in the [`experimental` section](https://fly.io/docs/reference/configuration/#the-experimental-section) of the `fly.toml` file. |

### Using Tigris as a policy repository

Cerbos `blob` driver can be used with any S3-compatible blob storage backend such as [Tigris](https://fly.io/docs/reference/tigris).

Create a storage bucket on Tigris. Refer to [https://fly.io/docs/reference/tigris/#create-and-manage-a-tigris-storage-bucket](https://fly.io/docs/reference/tigris/#create-and-manage-a-tigris-storage-bucket) for more information about creating storage buckets.

```bash
flyctl storage create
```

Note down the credentials for accessing the bucket and save them as application secrets.

```bash
flyctl apps create <APPLICATION_NAME> (1)
flyctl secrets set --app=<APPLICATION_NAME> AWS_ACCESS_KEY_ID=tid_XXXXXX (2)
flyctl secrets set --app=<APPLICATION_NAME> AWS_SECRET_ACCESS_KEY=tsec_XXXXXX (3)
```

|     |     |
| --- | --- |
| **1** | Your application name on Fly.io |
| **2** | Tigris key ID |
| **3** | Tigris secret access key |

Create a `fly.toml` file.

```toml
app = '<APPLICATION_NAME>' (1)
primary_region = '<REGION>' (2)

[build]
  image = 'ghcr.io/cerbos/cerbos:0.37.0'

[experimental]
  cmd = [\
    'server',\
    '--set', 'storage.driver=blob',\
    '--set', 'storage.blob.bucket=s3://<BUCKET_NAME>?endpoint=fly.storage.tigris.dev&region=auto', (3)\
    '--set', 'storage.blob.downloadTimeout=30s',\
    '--set', 'storage.blob.prefix=policies',\
    '--set', 'storage.blob.updatePollInterval=15s',\
    '--set', 'storage.blob.workDir=/policies'\
  ]

[[mounts]]
  source = 'policies'
  destination = '/policies'
  initial_size = '1GB'

[[services]]
  protocol = ''
  internal_port = 3592
  auto_stop_machines = true

[[services.ports]]
    port = 3592
    handlers = ['tls', 'http']

[[services.http_checks]]
    interval = '5s'
    timeout = '2s'
    grace_period = '5s'
    method = 'get'
    path = '/_cerbos/health'
    protocol = 'http'

[[services]]
  protocol = ''
  internal_port = 3593
  auto_stop_machines = true

[[services.ports]]
    port = 3593
    handlers = ['tls']

[services.ports.tls_options]
      alpn = ['h2']

[[vm]]
  memory = '1gb'
  cpu_kind = 'shared'
  cpus = 1

[metrics]
  port = 3592
  path = "/_cerbos/metrics"
```

|     |     |
| --- | --- |
| **1** | The name of the [Fly App](https://fly.io/docs/apps) |
| **2** | Pick a Fly.io [region](https://fly.io/docs/reference/regions/#fly-io-regions) |
| **3** | Storage bucket name |

Deploy the app.

```bash
flyctl deploy
```

### Using LiteFS as a policy repository

Fly.io’s distributed SQLite storage layer [LiteFS](https://fly.io/docs/litefs) can be used for policy storage using
Cerbos' `sqlite3` driver.

Start by creating an app on Fly.io.

```bash
flyctl apps create <APPLICATION_NAME>
```

Create a LiteFS configuration file named `litefs.yml`.

```yaml
data:
  dir: "/var/lib/litefs"

exec:
  - cmd: "/cerbos server --set=storage.driver=sqlite3 --set=storage.sqlite3.dsn=file:/litefs/db --set=server.adminAPI.enabled=true --set=server.adminAPI.adminCredentials.username=$CERBOS_ADMIN_USER --set=server.adminAPI.adminCredentials.passwordHash=$CERBOS_ADMIN_PASSWORD_HASH"

exit-on-error: false

fuse:
  dir: "/litefs"

lease:
  advertise-url: "http://${FLY_ALLOC_ID}.vm.${FLY_APP_NAME}.internal:20202"
  candidate: ${FLY_REGION == PRIMARY_REGION}
  consul:
    url: "${FLY_CONSUL_URL}"
    key: "${FLY_APP_NAME}/primary"
  promote: true
  type: "consul"
```

Create a Dockerfile.

```dockerfile
FROM flyio/litefs:0.5 AS litefs

FROM ghcr.io/cerbos/cerbos:0.37.0 AS cerbos

FROM alpine:3.16 AS base
RUN apk add fuse3 sqlite
ADD litefs.yml /etc/litefs.yml
COPY --from=cerbos /cerbos /cerbos
COPY --from=litefs /usr/local/bin/litefs /usr/local/bin/litefs

ENTRYPOINT ["litefs"]
CMD ["mount"]
```

Create a `fly.toml` file to launch Cerbos.

```toml
app = '<APPLICATION_NAME>' (1)
primary_region = '<REGION>' (2)

[build]
  dockerfile = "Dockerfile"

[mounts]
  source = "litefs"
  destination = "/var/lib/litefs" (3)

[[services]]
  protocol = ''
  internal_port = 3592

[[services.ports]]
    port = 3592
    handlers = ['tls', 'http']

[[services.http_checks]]
    interval = '5s'
    timeout = '2s'
    grace_period = '5s'
    method = 'get'
    path = '/_cerbos/health'
    protocol = 'http'

[[services]]
  protocol = ''
  internal_port = 3593

[[services.ports]]
    port = 3593
    handlers = ['tls']

[services.ports.tls_options]
      alpn = ['h2']

[[vm]]
  memory = '1gb'
  cpu_kind = 'shared'
  cpus = 1

[metrics]
  port = 3592
  path = "/_cerbos/metrics"
```

|     |     |
| --- | --- |
| **1** | The name of the [Fly App](https://fly.io/docs/apps) |
| **2** | Pick a [region](https://fly.io/docs/reference/regions/#fly-io-regions) |
| **3** | Destination must be equal to the one specified in the `litefs.yaml` |

Create secrets to hold Cerbos Admin API credentials. Refer to [password hash generation instructions](https://docs.cerbos.dev/cerbos/0.37.0/configuration/server#password-hash) to learn how to generate the password hash.

```bash
flyctl secrets set CERBOS_ADMIN_USER=<ADMIN_USER_NAME>
flyctl secrets set CERBOS_ADMIN_PASSWORD_HASH=<ADMIN_PASSWORD_HASH>
```

Attach to Consul to manage LiteFS leases.

```bash
flyctl consul attach
```

|     |     |
| --- | --- |
|  | See [lease configuration](https://fly.io/docs/litefs/getting-started-fly/#lease-configuration) for more information about Consul leases on Fly.io. |

Finally, deploy Cerbos.

```bash
flyctl deploy
```

You can interact with the Cerbos [Admin API](https://docs.cerbos.dev/cerbos/0.37.0/api/admin_api) using one of the Cerbos SDKs or the [`cerbosctl`](https://docs.cerbos.dev/cerbos/0.37.0/cli/cerbosctl) utility to manage the policies stored on LiteFS.

List policies with cerbosctl

```bash
cerbosctl \
  --server=<APPLICATION_NAME>.fly.dev:3593 \
  --username=<ADMIN_USER_NAME> \
  --password=<ADMIN_PASSWORD> \
  get rp
```

Put a policy or a directory consisting of multiple policies with cerbosctl

```bash
cerbosctl \
  --server=<APPLICATION_NAME>.fly.dev:3593 \
  --username=<ADMIN_USER_NAME> \
  --password=<ADMIN_PASSWORD> \
  put policies -R \
  policy_dir
```