--- source: https://carbone.io/documentation/developer/self-hosted-deployment/deploy-on-aws.html title: "Simply run and configure Carbone in your AWS environment" description: "Generate and manage your reports inside your own AWS infrastructure" generated_at: "2026-07-13" --- # 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](https://aws.amazon.com/marketplace/pp/prodview-m4tdvrln53afm). ### Benefits Carbone On-AWS provides the same API as the Carbone Cloud API, with the following benefits: - 🔐 The instance runs in your private AWS VPC with all your security requirements. Templates, data-set and generated documents are not leaving your infrastructure. - 🚀 Runs without internet access. - ⚡️ Install in a few minutes. - ✅ Easy to pay, you are billed according to your usage and the invoicing will be available on your AWS account. - All entreprise features (dynamic images, colors, html rendering, ...). - A stateless Carbone Studio with basic authentication (Web interface to design and preview documents) - Customise storage, and authentication thanks to NodeJS plugins. - SLA Support. - All incoming new features, updates and fixes. If you have questions, reach us on the chat or by email: [contact@carbone.io](mailto:contact@carbone.io). ## Quickstart ### Subscribe to Carbone - Go to the [AWS product sheet](https://aws.amazon.com/marketplace/pp/prodview-m4tdvrln53afm) - And click on "Continue to Subscribe" - 🎉 It's done ![Carbone AWS product](/img/doc/aws-product.png) ### First Carbone run - Go to [AWS Marketplace > Manage subscriptions](https://us-east-1.console.aws.amazon.com/marketplace/home#/subscriptions) console ![Carbone subscription](/img/doc/aws-subscribe.png) - Click on "Launch new instance - Select Carbone version, region and click on "Continue to launch through EC2" ![Carbone start AMI](/img/doc/aws-launch-instance.png) - Click on "Cancel" to keep default settings ![Change settings](/img/doc/aws-change-ec2-configs.png) - Review EC2 options. Before launching EC2 Carbone instance, please check following options: - Security group: It must contain at least one "Inbound rules" allowing `TCP/4000` from API users - IAM role: Attach to the instance the following policy: ```json { "Version": "2012-10-17", "Statement": [ { "Action": [ "aws-marketplace:MeterUsage" ], "Effect": "Allow", "Resource": "*" } ] } ``` - Enjoy 🎉 Verify the Carbone instance is running with the following command: ```bash 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. ### Options via Parameter Store (recommended, >v4.22.13) 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: ```json { "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 : - Access to Parameter Store in AWS Systems Manager : [Systems Manager](https://console.aws.amazon.com/systems-manager/parameters/) - Create parameter : **CARBONE\_EE\_studio** with value **true** ![Create studio parameter](/img/doc/aws-parameter-studio.png) - Restart EC2 instance - 🎉 Studio is now enabled on your Carbone instance #### List of Carbone parameters Here is the list of parameters you can configure. Please note that the parameters are case sensitive: - CARBONE\_EE\_port - CARBONE\_EE\_factories - CARBONE\_EE\_attempts - CARBONE\_EE\_authentication - CARBONE\_EE\_studio - CARBONE\_EE\_studioUser - CARBONE\_EE\_maxDataSize - CARBONE\_EE\_maxTemplateSize - CARBONE\_EE\_templatePathRetention - CARBONE\_EE\_lang - CARBONE\_EE\_timezone - CARBONE\_EE\_currencySource - CARBONE\_EE\_currencyTarget - CARBONE\_EE\_converterFactoryTimeout - CARBONE\_EE\_xlsmEnabled - CARBONE\_EE\_collectStatistics - CARBONE\_S3\_templateS3BucketRegion - CARBONE\_S3\_templateS3Bucket - CARBONE\_S3\_templateS3Folder - CARBONE\_S3\_renderS3Bucket - CARBONE\_S3\_renderS3Folder - CARBONE\_PUBKEY [Full parameters description](/documentation/developer/on-premise-installation/configuration.md) #### 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](/img/doc/aws-prefix-tag.png) 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](/documentation/developer/on-premise-installation/configuration.md) 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: ```bash sudo systemctl restart carbone-ee ``` ### Storage backends You can use create your own JS plugins to customise some part or Carbone : [create Carbone Plugins](/documentation/developer/on-premise-installation/plugins.md) 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: ```json "templateS3Bucket" : "test-stockage-template", "templateS3BucketRegion" : "us-east-1", "templateS3Folder" : "prod" ``` Or you can configure following parameters in Systems Manager Parameter store : - CARBONE\_S3\_templateS3BucketRegion - CARBONE\_S3\_templateS3Bucket - CARBONE\_S3\_templateS3Folder - CARBONE\_S3\_renderS3Bucket - CARBONE\_S3\_renderS3Folder Authentication is done using EC2 IAM role so you need to add following policy to grant S3 access to your EC2 instance: ```json { "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: - Set **CARBONE\_EE\_authentication** to `true` (Parameter Store) or `authentication: true` (config.json) - Generate a key pair with the same helper used on Docker and Kubernetes: ```sh docker run -it --platform "linux/amd64" carbone/carbone-ee:slim-5.0.0-beta.0 generate-keys ``` - Store the public key content in the **CARBONE\_PUBKEY** parameter (Parameter Store) or the `publicKey` option (config.json). Keep the private key secret — it is only used to generate JWT tokens. - Generate a JWT token: ```sh 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. ### 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**: - Build a Launch Template from a working Carbone instance, with the IAM role (marketplace metering + Parameter Store + S3, as configured above) and the `CARBONE_CONFIG_PREFIX` / `CARBONE_EE_*` tags attached, so every new instance self-configures identically on boot. - Point the target group's health check at `/status` on port `4000`. - Store templates and renders on S3 (see [Storage backends](#configuration-storage-backends) above) so every instance behind the load balancer shares the same data — a plain Auto Scaling Group does not replicate local disk between instances. ## Upgrade Carbone To update Carbone on AWS, please follow these steps: **Prerequisites:** - Carbone Version N is running in your infrastructure **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 : ```bash 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 ```bash 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: ```bash journalctl -u carbone-ee -r ``` ### Cannot connect to EC2 instance via SSH If you try to connect through ssh, please check: - SSH **Key pair** was configured when the instance was created - **Security group** contains inbound rule allowing `TCP/22` ### 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. ```bash $ 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 ## Related topics - [Deploy with Docker](/documentation/developer/self-hosted-deployment/deploy-with-docker.md) - [Deploy on Kubernetes](/documentation/developer/self-hosted-deployment/deploy-on-kubernetes.md) - [Deploy on Google Cloud Platform](/documentation/developer/self-hosted-deployment/deploy-on-gcp.md) - [Deploy on Azure](/documentation/developer/self-hosted-deployment/deploy-on-azure.md) - [Carbone on Amazon Elastic Container Service](/documentation/developer/self-hosted-deployment/deploy-on-aws-ecs.md)