# -*- ispell-local-dictionary: "english" -*-

* Info

From: Carbone https://hub.docker.com/r/carbone/carbone-ee#running-carbone-community-edition-forever-free

Upstream documentation:
- On-premise configuration: https://carbone.io/documentation/developer/on-premise-installation/configuration.html
- Template management: https://carbone.io/documentation/developer/on-premise-installation/template-management.html
- Studio Web Component: https://carbone.io/documentation/developer/embedding/studio-web-component.html

* What this charm enables

By default Carbone starts in the *stateless* mode: it only renders the
template sent with each request, exposes no Studio and keeps no template
metadata.  The =init= hook turns it into the *stateful* service, which is
what the charm is meant to provide:

- =CARBONE_STUDIO=true= serves the Studio web interface and the
  =/carbone-studio.js= Web Component.
- =CARBONE_TEMPLATE_MANAGEMENT=true= enables stable 64-bit template IDs,
  versioning, the =GET/POST/PATCH /template= endpoints and the
  =embedded-versioning= Studio mode.
- =CARBONE_BIND=0.0.0.0= makes Carbone listen on all interfaces so the
  =web-proxy= can reach it (the upstream default is =127.0.0.1=).

* Usage

ex :

#+begin_src yaml
carbone:
  relations:
    web-proxy:
      frontend:
        domain: carbone.dev1.elabore.coop
#+end_src

* Persistence

| Path            | Resource type    | Content                                              |
|-----------------+------------------+------------------------------------------------------|
| =/app/template= | =data-resources= | Templates and the metadata store (metadata.db)       |
| =/app/config=   | =config-resources= | Optional license, authentication public key (key.pub) |

Templates and their versioning metadata both live under =/app/template=,
so they survive redeploys and are covered by the =backup= relation.

* Enterprise license

Carbone runs fine without a license (Community Edition, forever free).
Advanced features (dynamic images/colors, barcodes, charts, HTML
aggregation, PDF operations, ...) require an Enterprise license.

To enable it, drop your =*.carbone-license= file into the config store
(=/app/config= on the host side, i.e.
=$SERVICE_CONFIGSTORE/app/config=) and redeploy the service.

* API authentication

Authentication is *disabled by default*: the API is reachable as soon as
the service is up, which is the expected setup behind the =web-proxy=.
If you ever need an API key (JWT), enable =CARBONE_AUTHENTICATION=true=,
generate an EC keypair with =generate-keys=, expose the public key as
=/app/config/key.pub= and generate a token with =generate-token=.  See
the upstream "Deploy with Docker" documentation for the exact commands.