Deploy with Docker

Installation

Carbone reference image are available on Docker Hub.

You can choose between 3 variants:

• slim : Minimal version of Carbone. This image does not include Libreoffice (no PDF generation possible).
• latest, full : Full version of Carbone including the latest version of LibreOffice
• latest-fonts, full-fonts : Full version of Carbone including the latest version of LibreOffice. This version also includes all Google Fonts⁠ (royalty-free).

You can use Carbone Community feature for free without licence.
To use Carbone Enterprise Edition on docker, you need a Carbone license. Talk to us to find out more.

To start your instance simply :

export CARBONE_EE_LICENSE=`MY_CARBONE_LICENSE`

docker run -t -i --rm -p 4000:4000 -e CARBONE_EE_LICENSE -e CARBONE_EE_STUDIO=true carbone/carbone-ee

Configuration

All configuration options can be used by setting environment variables.

Configure plugins

Two plugins are preinstalled in docker images:

• carbone-ee-plugin-s3 : Storage of templates and/or renders on an S3-compatible bucket
• carbone-ee-plugin-azure-storage-blob : Storage of templates and/or renders on an Azure Blob Storage

Here are the environment variables for configuring these plugins:

• CARBONE_USE_S3_PLUGIN : set to true to enable S3 plugin. Default : true
• CARBONE_USE_AZURE_PLUGIN : set to true to enable Azure Blob Storage plugin, and disable S3 plugin. Default : false

S3 Configuration

• AWS_ACCESS_KEY_ID : Access Key ID
• AWS_SECRET_ACCESS_KEY : Secret Key
• AWS_ENDPOINT_URL : s3.amazonaws.com for AWS, storage.googleapis.com for GCP Storage
• AWS_REGION : storage region
• BUCKET_RENDERS : "BUCKET NAME to store your generated documents"
• BUCKET_TEMPLATES : "BUCKET NAME to store your templates"

Azure Blob Storage Configuration

• AZURE_STORAGE_ACCOUNT : Storage Account Name
• AZURE_STORAGE_KEY : Storage Account Key
• CONTAINER_TEMPLATES : Templates Storage Name
• CONTAINER_RENDERS : Renders Storage Name

Authentification

To enable API authentification, you need to follow these steps :

- Set CARBONE_EE_AUTHENTICATION to true

- Generate private/public Carbone Key

The key generation tool is included in the docker image from Carbone version 5 onwards.

docker run -it --platform "linux/amd64" carbone/carbone-ee:slim-5.0.0-beta.0 generate-keys

The two keys will be generated and displayed in the console. Create the files key.pem (with private key) and key.pub (with public key).

- Generate JWT token

Follow interactive shell :

docker run -it --platform "linux/amd64" carbone/carbone-ee:slim-5.0.0-beta.0 generate-token

## Paste in terminal content of key.pem

A JWT token is then displayed in the console. You can then use it in your API calls.

Persistence storage

By default, persistent data is stored in the container.

For production use, you need to configure a persistent storage space.

When deploying with Docker, we recommend using a shared volume.

With a single Carbone instance, only the /app/template folder needs to be bind to a host folder. With multiple instances, you must also bind the /app/render folder.

# Start Carbone with /app/template bind on local folder
docker run -t -i --rm -p 4000:4000 -e CARBONE_EE_LICENSE -e CARBONE_EE_STUDIO=true -volume ./template:/app/template carbone/carbone-ee

Scenario 1 : Deploy a single instance with docker-compose

Example of docker-compose.yml to run a Carbone container:

version: "3.9"
services:
  carbone:
    image: carbone-ee
    ports:
      - "4000:4000"
    secrets:
      - source: carbone-license
        target: /app/config/prod.carbone-license
    environment:
      - CARBONE_EE_STUDIO=true
    volumes:
      - ./template:/app/template
      - ./render:/app/render
secrets:
  carbone-license:
    file: your_license.carbone-license

To start stack :

docker-compose up

Scenario 2 : Deploy 3 Carbone instances with authentification

Example of docker-compose.yml with High availability stup, authentification and reverse proxy :

version: "3.9"
services:
  carbone:
    image: "carbone/carbone-ee:full"
    deploy:
      replicas: 3
    ports:
      - "4000"
    secrets:
      - source: carbone-license
        target: /app/config/license.carbone-license
      - source: carbone-publickey
        target: /app/config/key.pub
    environment:
      - CARBONE_EE_STUDIO=true
      - CARBONE_EE_AUTHENTICATION=true
      - CARBONE_EE_STUDIOUSER=toto:Passw0rd
    volumes:
      - ./template:/app/template
      - ./render:/app/render
  nginx:
    image: nginx:latest
    volumes:
      - ./nginx.conf:/etc/nginx/nginx.conf:ro
    depends_on:
      - carbone
    ports:
      - "4000:4000"
secrets:
  carbone-license:
    file: license.carbone-license
  carbone-publickey:
    file: key.pub

Content of nginx.conf :

user  nginx;

events {
  worker_connections   1000;
}
http {
  server {
    listen 4000;
    location / {
      proxy_pass http://carbone:4000;
    }
    client_max_body_size 20M;