Self-hosted deployment

Deploy on AWS

Generate and manage your reports inside your own AWS infrastructure

Introduction

Get a dedicated Carbone instance in your AWS private Cloud in just a few minutes via the AWS marketplace.

Benefits

Carbone On-AWS provides the same API as the Carbone Cloud API, with the following benefits:

If you have questions, reach us on the chat or by email: contact@carbone.io.

Quickstart

Subscribe to Carbone

Carbone AWS product

First Carbone run

Verify the Carbone instance is running with the following command:

curl http://"EC2_IP"/status

## Expected result : {"success":true,"code":200,"message":"OK","version":"4.22.13"}

Configuration

There are two ways of configuring Carbone on AWS.

This method allows you to generate Carbone parameters outside the instance by configuring TAGs on the instance and setting them with the AWS Systems Manager product.

The first step is to enrich the IAM role of your Carbone instance with the following policy:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": "ssm:GetParameter",
            "Resource": "*"
        },
        {
            "Effect": "Allow",
            "Action": "ssm:DescribeParameters",
            "Resource": "*"
        },
        {
            "Effect": "Allow",
            "Action": "ec2:DescribeTags",
            "Resource": "*"
        }
    ]
}

Carbone will now get CARBONE_EE_*, CARBONE_S3_* and CARBONE_PUBKEY parameters stored in Parameter Store to get running configuration.

For example, to enable Studio :

List of Carbone parameters

Here is the list of parameters you can configure. Please note that the parameters are case sensitive:

Full parameters description

Use different configuration for several Carbone instances

If you have several Carbone instances and want to configure them differently, you can add the TAG CARBONE_CONFIG_PREFIX to configure a prefix that will be used to retrieve the options.

For example the following configuration: Create studio parameter

Will use the /PROD/CARBONE_EE_* options

Options via config.json (legacy method)

You can configure Carbone on AWS in the same way as Carbone on-premise: Learn how to configure server and enable options

The configuration is accessible by connecting to the EC2 instance in the file /var/www/carbone-ee/config/config.json. We recommend using the carbone user after connecting to the EC2 instance to modify config.json. After making changes to the config.json file, please restart Carbone with the following command:

sudo systemctl restart carbone-ee

Storage backends

You can use create your own JS plugins to customise some part or Carbone : create Carbone Plugins

Sample S3 plugins is included by default to allow you to load and store templates from you S3 bucket.

To use it, you need to configure bucket name and region in file /var/www/carbone-ee/config/config.json with the following options:

    "templateS3Bucket" : "test-stockage-template",
    "templateS3BucketRegion" : "us-east-1",
    "templateS3Folder" : "prod"

Or you can configure following parameters in Systems Manager Parameter store :

Authentication is done using EC2 IAM role so you need to add following policy to grant S3 access to your EC2 instance:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "VisualEditor0",
            "Effect": "Allow",
            "Action": [
                "s3:PutObject",
                "s3:GetObject",
                "s3:GetObjectAttributes",
                "s3:ListBucket",
                "s3:DeleteObject"
            ],
            "Resource": [
                "arn:aws:s3:::test-stockage-template",
                "arn:aws:s3:::test-stockage-template/*"
            ]
        }
    ]
}

Authentication

To enable API authentication with a JWT public/private key pair:

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

Centralized logging (CloudWatch)

By default Carbone AMI is configured to export application logs on CloudWatch. To enable it, you only need to attach CloudWatchAgentServerPolicy policy on EC2 IAM role.

The logs from the Carbone application are then directly available in the CloudWatch application in log group name carbone-ee.

Scaling and availability

For production traffic, run Carbone behind an Auto Scaling Group and an Application Load Balancer:

Upgrade Carbone

To update Carbone on AWS, please follow these steps:

Prerequisites:

Upgrade procedure:

We recommend that you configure Carbone via Systems Manager and configure the S3 plugin to store templates. In this case, migration to a new version is transparent.

Otherwise, you need to follow these steps:

  1. Launch new instance with new version
  2. Stop Carbone on new instance with :
    sudo systemctl stop carbone-ee
  3. Copy /var/www/carbone-ee/config from the previous EC2 instance to the new one
  4. (If you don't use the S3 plugin to store templates) Copy /var/www/carbone-ee/template from the previous EC2 instance to the new one
  5. (If you include specific plugins) Copy /var/www/carbone-ee/plugin from the previous EC2 instance to the new one
  6. Start Carbone
    sudo systemctl start carbone-ee
  7. Enjoy 🎉, you can now take advantage of Carbone's new features and destroy the previous Carbone instance

Troubleshooting

Logs access locally

To access to Carbone logs, connect to the EC2 instance with SSH or by the System Manager. Logs are accessible with following command:

journalctl -u carbone-ee -r

Cannot connect to EC2 instance via SSH

If you try to connect through ssh, please check:

IAM Role errors

If the following error message appears in the logs, it means that the IAM MeterUsage Role is not attached to the EC2 instance.

$ Carbone need acces to AWS Marketplace API to check subscription and report usage. Please check if you ec2 instance have correct IAM role

Please check following:

  1. Login to your AWS Management Console, open EC2 Services and click Instances
  2. Select the new EC2 instance deployed from this AMI and click Actions -> Security -> Modify IAM role
  3. Click Create new IAM role (or choose an existing one if created earlier)
  4. Click Create role, select AWS service and EC2, click Next
  5. Select AWSMarketplaceMeteringFullAccess, click Next
  6. Provide a Role name (eg carbone-role), click Create role
  7. In the Modify IAM role browser tab from step 2 above, click the refresh icon, select the new IAM Role, click Update IAM role