Apache Camel Karavan on AWS User Guide

Overview

This image runs Apache Camel Karavan, an open source visual integration designer and toolkit for Apache Camel. Karavan gives you a browser based, drag and drop environment to design, build and run Apache Camel integrations, including Kamelets and Enterprise Integration Pattern (EIP) routes. In its docker mode it can build and run each integration as its own container on the instance's local Docker engine.

The image ships Karavan as a supervised container stack:

• Karavan is the Quarkus (Java) web application that serves the visual designer and its REST API. It runs as the official ghcr.io/apache/camel-karavan container, bound to the loopback interface on port 8080. An nginx reverse proxy on port 80 fronts it with HTTP Basic authentication, so the designer is only reachable after signing in.
• PostgreSQL holds Karavan's integration and session state. It runs as a postgres:16-alpine container on a private Docker network with no published port, so it is never reachable off the instance.
• The host Docker socket is mounted into the Karavan container so the docker mode runner can build and run each integration as a container.

Karavan 4.18.1 runs on Quarkus. The stack is defined by a Docker Compose file at /opt/karavan/docker-compose.yml and supervised by the karavan.service systemd unit. The three container images (Karavan, PostgreSQL and the Karavan devmode route runner) are baked into the image so the first boot is fast and offline capable.

Everything binds the loopback interface only. Nothing is exposed to the network except SSH on port 22 and the authenticated Karavan designer on port 80.

Per instance credentials

Karavan's only built in authentication is a sign in form (user admin) whose upstream stock build ships a well known hardcoded password. This image never ships that default. On the first boot of every deployed instance a fresh 24 character password is generated and applied to both the nginx reverse proxy gate and Karavan's own admin sign in, so the two layers share one per instance password. Two instances launched from the same Amazon Machine Image never share a password, and the well known Karavan stock default is never present on a deployed instance. The generated password is written to /root/karavan-credentials.txt with mode 0600 so that only the root user can read it. The captured image contains an empty database with no password hash of any kind.

Pre loaded demo project

On first boot the image seeds a curated demo integration project (project id demo) through Karavan's API, so the visual designer opens with a real project containing two Camel routes: a heartbeat timer to log route and a greeting timer to log route. This gives you something to open, edit and run immediately rather than an empty canvas.

Prerequisites

• An AWS account with permission to launch EC2 instances and subscribe to AWS Marketplace products.
• An EC2 key pair for SSH access.
• A security group allowing inbound TCP 22 (SSH) and TCP 80 (the Karavan designer) from your address. Karavan's designer runs an authentication gate, but you should still restrict port 80 to trusted sources.
• The recommended instance type is m5.large or larger (Karavan runs a JVM and a Docker engine).

Step 1: Launch the Instance from the AWS Marketplace

1. Open the product's AWS Marketplace listing and choose Continue to Subscribe, then Continue to Configuration and Continue to Launch.
2. Select your instance type (m5.large recommended), VPC and subnet, your key pair, and a security group allowing TCP 22 and TCP 80.
3. Launch the instance and wait a few minutes for the first boot to generate the per instance password, bring up the stack and seed the demo project.

Step 2: Launch the Instance from the AWS CLI

aws ec2 run-instances \
  --image-id ami-xxxxxxxxxxxxxxxxx \
  --instance-type m5.large \
  --key-name your-key \
  --security-group-ids sg-xxxxxxxx \
  --tag-specifications 'ResourceType=instance,Tags=[{Key=Name,Value=karavan}]'

Replace the AMI id with the one for your Region from the Marketplace listing, and the key pair and security group with your own.

Step 3: Connect to Your Instance

Connect over SSH as the default login user for your operating system variant.

ssh -i your-key.pem <login-user>@<public-ip>

Step 4: Retrieve Your Password

The per instance password is stored in a root only file. Retrieve it with:

sudo cat /root/karavan-credentials.txt

You will see the generated KARAVAN_PASSWORD, along with the URL and the username (admin). The same username and password are used for both the nginx access gate and the Karavan sign in form.

Step 5: Verify the Stack is Healthy

Confirm the services and containers are running:

systemctl is-active docker karavan nginx
sudo docker ps --format 'table {{.Names}}\t{{.Image}}\t{{.Status}}'

Expected output:

active active active
NAMES              IMAGE                                 STATUS
karavan            ghcr.io/apache/camel-karavan:4.18.1   Up 7 minutes
karavan-postgres   postgres:16-alpine                    Up 7 minutes (healthy)

Karavan binds the loopback interface only, and nginx serves port 80:

sudo ss -tln | grep -E ':80 |:8080 '

LISTEN 0      511          0.0.0.0:80        0.0.0.0:*
LISTEN 0      4096       127.0.0.1:8080      0.0.0.0:*
LISTEN 0      511             [::]:80           [::]:*

Prove the authentication gate. The unauthenticated health endpoint returns 200, an unauthenticated request to the UI returns 401, and the per instance password is accepted:

PW=$(sudo grep '^KARAVAN_PASSWORD=' /root/karavan-credentials.txt | cut -d= -f2-)
curl -s -o /dev/null -w 'healthz: %{http_code}\n' http://127.0.0.1/healthz
curl -s -o /dev/null -w 'unauth: %{http_code}\n'  http://127.0.0.1/
curl -s -o /dev/null -w 'auth: %{http_code}\n' -u "admin:$PW" http://127.0.0.1/

healthz: 200
unauth: 401
auth: 200

Confirm the running Karavan version:

PW=$(sudo grep '^KARAVAN_PASSWORD=' /root/karavan-credentials.txt | cut -d= -f2-)
curl -s -u "admin:$PW" http://127.0.0.1/ui/configuration \
  | python3 -c "import sys,json;print(json.load(sys.stdin).get('version'))"

4.18.1

Step 6: Open the Karavan Designer

In a browser, go to http://<instance-public-ip>/. You are asked for credentials twice with the same username and password:

1. First, the browser's HTTP Basic authentication dialog (the nginx access gate). Enter admin and your KARAVAN_PASSWORD.
2. Then, the Karavan sign in form. Enter admin and the same password, and choose Access Platform.

You reach the Karavan dashboard, which summarises your designed projects and routes. The pre loaded demo integration project is listed and ready to open.

Step 7: Explore the Demo Integration

Open the Demo Integration project. The Architecture view shows the project's two Camel routes on the visual canvas: greeting and heartbeat. You can zoom, switch layout, and open each route to edit its steps visually.

The Source view lists the project's files, including the Camel YAML route definitions and the integration's application.properties. This is the code Karavan generates and runs from the visual design.

Step 8: Build and Run an Integration

Karavan's docker mode builds and runs each integration as a container using the instance's local Docker engine. From an open project, choose Run to build and start the integration. Karavan starts a Camel container for the project and streams its live status and logs back into the designer. Use the project's Containers tab to see the running container, and stop it from the same view when you are finished.

Because each integration runs as its own container, running heavier integrations consumes instance memory and CPU. Start on m5.large and scale the instance type up for larger workloads.

Step 9: Rotate the Password

To rotate the password, generate a new value, update both the nginx access gate and Karavan's own admin password, and record it:

# choose a strong value for <new-password>, then apply it to both layers
# nginx access gate (bcrypt)
sudo htpasswd -bB /etc/nginx/.karavan.htpasswd admin '<new-password>'
sudo systemctl reload nginx
# Karavan's own admin password
sudo sed -i "s/^PLATFORM_PASSWORD=.*/PLATFORM_PASSWORD=<new-password>/" /opt/karavan/.env
sudo systemctl restart karavan
# record it
sudo sed -i "s/^KARAVAN_PASSWORD=.*/KARAVAN_PASSWORD=<new-password>/" /root/karavan-credentials.txt

Step 10: Add a Domain and TLS (Production)

For production, put a TLS terminating reverse proxy or load balancer in front of the instance, or add a certificate to nginx directly. A simple approach is Let's Encrypt with certbot against a DNS name you point at the instance:

sudo apt-get update && sudo apt-get install -y certbot python3-certbot-nginx
sudo certbot --nginx -d your-domain.example.com

Then restrict the security group so only your load balancer or trusted addresses can reach port 80/443.

Security Notes

• The Karavan designer and its PostgreSQL state store bind the loopback interface only; the sole public listeners are SSH (22) and the authenticated nginx gate (80).
• Every deployed instance generates its own password on first boot. The well known Karavan stock default is never present, and the captured image ships an empty database with no password hash.
• Keep port 80 restricted to trusted sources and place TLS in front for production use.
• Karavan's docker mode can build and run arbitrary integrations as containers on the instance; treat access to the designer as access to run code on the instance, and restrict it accordingly.

Backups

Karavan's integration and session state lives in the PostgreSQL container's data directory under /opt/karavan/pgdata, and your integration project files are stored by Karavan in the same stack. To back up, stop the stack and archive the data directory:

sudo systemctl stop karavan
sudo tar czf <backup-dir>/karavan-backup-$(date +%F).tgz -C /opt/karavan pgdata
sudo systemctl start karavan

For a running backup, use pg_dump inside the postgres container against the karavan database.

Support

cloudimg provides 24/7 technical support for this product by email and live chat.

• Email: support@cloudimg.co.uk
• Live chat: available 24/7

Our engineers assist with Karavan deployment, upgrades, integration and route design, docker mode runner configuration and performance tuning.

Apache Camel, Camel, Karavan and Apache are trademarks of the Apache Software Foundation. All other product and company names are trademarks or registered trademarks of their respective holders. Use of them does not imply any affiliation with or endorsement by them.