Karrot Docs

Appearance

Co-op Cloud ​

Co-op Cloud is our officially preferred approach to self-hosting.

🫣 Watch out!

You might find some rough edges at this time, we are very interested to support the smoothing of those!

What is Co-op Cloud? ​

From coopcloud.tech

Public interest infrastructure. An alternative to corporate clouds built by tech co-ops.

They provide a catalogue of recipes that you can run on your own server using docker.

Also check their FAQ page.

Steps ​

Prerequisites ​

You need a server, a small VPS is fine for a typical group.

Setting up your server

We won't cover the basics of how to setup your server (add users, secure it, install docker, etc...).

If you'd like a starting point for that, check out karrot/karrot-ansible.

Next step is to follow the New Operators Tutorial from Co-op Cloud.

Once you've done that you'll have:

  • abra installed on your local computer
  • an internet-reachable machine running linux configured to use with abra
  • a traefik proxy running
  • your domain name with DNS records pointing to your server

You can then proceed to deploy your Karrot instance.

Initialize new app ​

shell
abra app new karrot
  • choose your server
  • choose a domain name that karrot will be deployed under: this is what we refer to as <domain>

Configuration ​

shell
abra app config <domain>

This is where you can add in configuration for optional features, make sure to uncomment any additional compose files and associated configuration options you need. See below for more details on these.

See configuration settings page for what you might like to set.

If you want to access the instance admin UI then be sure to set one or more email addresses:

shell
ADMIN_EMAILS=example1@example.com,example2@example.com

TIP

You only need to set the Core settings here, as anything within the App settings section you can configure later in the Admin Settings UI.

In addition to the those Karrot settings there are some settings specific to Co-op cloud:

  • TYPE, SITE_URL, LETS_ENCRYPT_ENV - you can likely leave these as they are
  • DOMAIN - this is the domain name which resolves to karrot. Should be set to the same as app name

Configure additional services (optional) ​

These additional services can be configured by including the relevant compose.<service>.yml file, and setting the appropriate settings. All of them, with the exception of GeoIP, can alternatively be configured using the instance admin UI.

SMTP ​

This can be alternatively be configured using the instance admin UI.

Send emails via external SMTP server (by default just prints them to the server console).

Postal ​

This can be alternatively be configured using the instance admin UI.

Send emails via external Postal server.

TIP

You can just use postal for incoming email, in which case you only need to set POSTAL_WEBHOOK_KEY.

You don't need to need to include the postal compose file, set the postal_api_key secret, or the POSTAL_API_URL var.

Web Push (vapid) ​

TIP

This can be alternatively be configured using the instance admin UI.

This configures support for web push notifications.

Video Calls (meet) ​

This can be alternatively be configured using the instance admin UI.

This configures support Video calls for using LiveKit. You can use a self-hosted instance, or their hosted offering.

GeoIP ​

GeoIP is optional. The Karrot application just needs the path to the database set via the GeoIP Path option.

To keep the GeoIP database up to date though, you need to run geoipupdate. You need a maxmind account to get GeoIP data. You only need the free account and then you can get an account id and license key.

Configure secrets ​

Set the secrets you need.

List all secrets:

shell
abra app secret list <domain>

Insert a secret - use this for known values, e.g. API keys:

shell
abra app secret insert <domain> <secret name> <version> "<secret value>"

Generate a secret - use this for random secrets, e.g. database password:

shell
abra app secret generate <domain> <secret name> <version>

TIP

If you are not using any known value secrets (this is the case if you have a default setup with no additional features included), you can generate them all at once with:

shell
abra app secret generate <domain> --all

Deploy it! ​

Now we're ready to deploy:

shell
abra app deploy <domain>

Wait for a few minutes while karrot initializes and then you can start creating accounts!

If you have any issues that you think might be specific to Co-op Cloud rather than Karrot, then Get In Touch.