Self-hosted deployment

Carbone on Amazon Elastic Container Service

Generate and manage your reports inside your own Amazon ECS Cluster

Introduction

Setting up Carbone in an environment is very simple and effective.

Here's the recommended configuration:

To use Carbone Enterprise Edition on Amazon Elastic Container Service, you need a Carbone license. Talk to us to find out more.

Quickstart

Create ECS Cluster

To set up Carbone in your environment, the first step is to create your cluster. To do this, connect to the Amazon Elastic Container Service console and create your cluster:

Create Carbone Cluster

Create IAM role

You then need to prepare a role that will be used by your carbon container.

For this example, we suggest you give access rights to CloudWatch and to read secrets for license storage.

You must first create the carbone_service_role with Elastic Container Service Task trusted entity : Create Role

Then, you must assign AmazonECSTaskExecutionRolePolicy, CloudWatchLogsFullAccess and custom ReadSecret permissions policies : Assign permission to role

Storing Carbone Licence

To store secrets properly, we recommend using AWS Secrets Manager. You'll need to create a new secret from the AWS Secrets Manager Console.

Insert your license as Other type of secret : Storing Carbone licence

Create Task definition

You now need to create a task definition for the Carbone service. Go to the Task definitions console, and create a task. Here is an example of a json task definition:

{
    "family": "carboneService",
    "containerDefinitions": [
        {
            "name": "Carbone",
            "image": "carbone/carbone-ee:full",
            "cpu": 0,
            "portMappings": [
                {
                    "containerPort": 4000,
                    "hostPort": 4000,
                    "protocol": "tcp"
                }
            ],
            "essential": true,
            "environment": [
                {
                    "name": "CARBONE_EE_STUDIO",
                    "value": "true"
                }
            ],
            "mountPoints": [],
            "volumesFrom": [],
            "secrets": [
                {
                    "name": "CARBONE_EE_LICENSE",
                    "valueFrom": <REPLACE WITH YOUR LICENCE SECRET ARN>
                }
            ],
            "stopTimeout": 20,
            "logConfiguration": {
                "logDriver": "awslogs",
                "options": {
                    "awslogs-group": "awslog-carbone",
                    "awslogs-create-group": "true",
                    "awslogs-region": "eu-west-3",
                    "awslogs-stream-prefix": "Carbone"
                }
            },
            "systemControls": []
        }
    ],
    "executionRoleArn": <REPLACE WITH YOUR ROLE ARN>,
    "networkMode": "awsvpc",
    "placementConstraints": [],
    "requiresCompatibilities": [
        "FARGATE"
    ],
    "cpu": "1024",
    "memory": "2048",
    "runtimePlatform": {
        "cpuArchitecture": "ARM64",
        "operatingSystemFamily": "LINUX"
    }
}

Create Service

Finally, all that's left to do is create the service in your cluster using the task definition you've just created.

You can then configure the number of tasks you need, autoscaling, an `Application Load Balancer', ...

Et voilà 🎉

Configuration

Data persistency (Mandatory)

To use Carbone in production, you need to configure data persistence for template and rendering storage.

There are two possible solutions in the ECS environment: using S3 buckets or configuring an Elastic File System shared volume.

Storing persistent data on S3 bucket

To store your data on S3 buckets, you need to :

Create 2 buckets, one for storing your templates, and one for storing renderings
Create a user with a pair of API keys (KEY_ID and KEY_SECRET) with read and write rights to these buckets.

In the task definition, you need to add the following environment variables:

AWS_ENDPOINT_URL=s3.amazonaws.com
AWS_REGION=<S3 REGION>
AWS_ACCESS_KEY_ID=<YOUR KEY_ID>
AWS_SECRET_ACCESS_KEY=<YOUR KEY_SECRET>
BUCKET_TEMPLATES=<YOUR TEMPLATES BUCKET NAME>
BUCKET_RENDERS=<YOUR RENDERS BUCKET NAME>

Storing persistent data on shared Elastic File System (EFS)

To use storage via the shared volume, you need to:

Create an EFS space from the Elastic File System Console
Check that the network configuration allows this storage to be accessed from Carbone containers

Mount a shared volume by adding the volume directive to the task definition:

"volume": [
{
  "name": "template-storage",

  "efs_volume_configuration": {
    "file_system_id": <EFS ID>,
    "root_directory": "/app/template"
  }
},
{
  "name": "render-storage",

  "efs_volume_configuration": {
    "file_system_id": <EFS ID>,
    "root_directory": "/app/render"
  }
}
]

Enable Carbone options

All Carbone configuration options are available on this page.

You can also create your own plugins, configure your version of LibreOffice or add your own fonts by creating your own Carbone image.

Terraform sample deployement

A complete terraform deployment example is available.