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

[[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"
```

### 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)
```

Create a `fly.toml` file.

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

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

[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"
```

### 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.35.1 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"
```

Create secrets to hold Cerbos Admin API credentials. Refer to [password hash generation instructions](https://docs.cerbos.dev/cerbos/0.35.1/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
```

Finally, deploy Cerbos.

```bash
flyctl deploy
```

You can interact with the Cerbos [Admin API](https://docs.cerbos.dev/cerbos/0.35.1/api/admin_api) using one of the Cerbos SDKs or the [`cerbosctl`](https://docs.cerbos.dev/cerbos/0.35.1/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
```