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>

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

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 secrets ​

Set all the secrets, even the ones you don't want to use.

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>

Configure additional services (optional) ​

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.

  • in the Co-op Cloud setup this can be achieved by including compose.geoip.yml and setting MAXMIND_ACCOUNT_ID and a secret for MAXMIND_LICENSE_KEY

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.