# claper

> [Claper](https://github.com/ClaperCo/Claper): interactive presentations, polls,
> quizzes and Q&A for your audience, for Co-op Cloud

<!-- metadata -->
* **Maintainer**: [@ineiti](https://git.coopcloud.tech/ineiti)
* **Category**: Apps
* **Status**: 0, work-in-progress
* **Image**: [`ghcr.io/claperco/claper`](https://github.com/ClaperCo/Claper/pkgs/container/claper), 4, upstream
* **Healthcheck**: Yes
* **Backups**: Yes
* **Email**: Yes (SMTP)
* **Tests**: No
* **SSO**: Yes (OIDC)
<!-- endmetadata -->

## Quick start

* `abra app new claper --secrets`
* `abra app config <app-name>`, set `ADMIN_EMAIL`
* `abra app deploy <app-name>`
* Log in as `ADMIN_EMAIL` with the `admin_pass` secret printed by
  `abra app new --secrets`

## Admin account

On every start of the `app` container, the account `ADMIN_EMAIL` is ensured to
exist and to be an admin:

* if it doesn't exist, it is created with the `admin_pass` secret as password
* if it exists without admin role, it is promoted to admin
* if it already is an admin, nothing changes, the password is never overwritten

Changing `ADMIN_EMAIL` and redeploying adds a new admin; the previous admin is
kept and has to be demoted or deleted in the admin panel if it isn't needed
anymore.

To reset the admin password to the `admin_pass` secret, e.g. after rotating it:

* `abra app secret rm <app-name> admin_pass` and
  `abra app secret insert <app-name> admin_pass v1 <password>`, or bump
  `SECRET_ADMIN_PASS_VERSION` and `abra app secret generate <app-name> admin_pass`
* `abra app deploy <app-name> --force`
* `abra app cmd <app-name> app set_admin_password`

Without `ADMIN_EMAIL`, Claper's own seeds create `admin@claper.co` with the
public password `claper` on an empty database. Change it right away, e.g. by
setting `ADMIN_EMAIL=admin@claper.co` and running `set_admin_password`.

Database migrations, the admin bootstrap and seeds run on every start of the
`app` container.

## Email

Without SMTP, Claper uses its local mail adapter and drops all mails (account
confirmation, password resets, magic links). To send mails:

```
COMPOSE_FILE="$COMPOSE_FILE:compose.smtp.yml"
SMTP_RELAY=smtp.example.com
SMTP_USERNAME=claper@example.com
SECRET_SMTP_PASS_VERSION=v1
```

* `abra app secret insert <app-name> smtp_pass v1 <password>`
* `abra app deploy <app-name> --force`

## Single sign-on (OIDC)

Create a client at your provider (e.g. Authentik or Keycloak) with the redirect
URI `https://<DOMAIN>/users/oidc/callback`, then:

```
COMPOSE_FILE="$COMPOSE_FILE:compose.oidc.yml"
OIDC_ISSUER=https://authentik.example.com/application/o/claper/
OIDC_CLIENT_ID=claper
SECRET_OIDC_SECRET_VERSION=v1
```

* `abra app secret insert <app-name> oidc_secret v1 <client-secret>`
* `abra app deploy <app-name> --force`

To log in as admin via OIDC, set `ADMIN_EMAIL` to the email address of the admin
at the provider. The first OIDC login with that address is linked to the
existing admin account:

* directly, if `OIDC_TRUST_EMAIL_VERIFIED=true` and the provider marks the email
  as verified
* otherwise after clicking a confirmation link that Claper mails to that
  address, which needs [email](#email) to be set up

With this, `DISABLE_PASSWORD_LOGIN=true` (only OIDC logins) can be enabled from
the first deploy on. The `admin_pass` secret is still required, but not used for
logging in anymore.

## S3 storage

Uploaded presentations are stored in the `uploads` volume by default. To use
S3 (or an S3-compatible service) instead, enable `compose.s3.yml` in the config
and insert the secret key with
`abra app secret insert <app-name> s3_secret v1 <secret-access-key>`.

## Backups

Both the `uploads` volume and a `pg_dump` of the database are backed up by
[backupbot](https://git.coopcloud.tech/coop-cloud/backup-bot-two).