Apache Camel Karavan 4.22.1

Option A: AWS Marketplace console

• Open the SecureAnyCloud Hardened Node.js & Developer and API Tools AMIs listing on AWS Marketplace. Choose View purchase options, then Subscribe. One subscription covers every version in the listing.
• Once the subscription is active, choose Launch your software.
• Choose One-click launch from AWS Marketplace (or Launch from EC2 Console for the full launch wizard). In Version, choose Apache Camel Karavan 4.22.1 on Ubuntu 24.04, then choose your Region.
• Pick an instance type and your key pair. m5.large is recommended, and the software charge is $0.04 per vCPU per hour.
• For the security group, note that the listing's default group opens SSH (22), HTTP (80) and HTTPS (443). Restrict all three to your own and your team's addresses.
• Choose your VPC and subnet and leave the metadata defaults, because the image already requires IMDSv2. Then choose Launch.

Option B: AWS CLI

Run this command on your own workstation. It creates a security group that allows SSH from your management address and HTTPS from your team's network, then launches the instance.

Replace the AMI ID with the one shown for your Region on the Marketplace launch page. Replace the VPC, subnet, key pair and CIDR ranges with your own:

SG=$(aws ec2 create-security-group --group-name karavan \
  --description "Apache Camel Karavan" --vpc-id vpc-0123456789abcdef0 \
  --query GroupId --output text)
aws ec2 authorize-security-group-ingress --group-id "$SG" --protocol tcp --port 22 --cidr <your-mgmt-cidr>
aws ec2 authorize-security-group-ingress --group-id "$SG" --protocol tcp --port 443 --cidr 203.0.113.0/24
aws ec2 authorize-security-group-ingress --group-id "$SG" --protocol tcp --port 80 --cidr 203.0.113.0/24
aws ec2 run-instances \
  --image-id ami-0123456789abcdef0 \
  --instance-type m5.large \
  --key-name my-key-pair \
  --security-group-ids "$SG" \
  --subnet-id subnet-0123456789abcdef0 \
  --tag-specifications 'ResourceType=instance,Tags=[{Key=Name,Value=karavan}]'

You do not need --metadata-options, because the AMI already requires IMDSv2. To keep the address across a stop and start, associate an Elastic IP.

Connect as ubuntu with the key pair you chose:

ssh -i ~/.ssh/my-key-pair.pem ubuntu@<public-ip>

First boot finishes within two or three minutes of launch. It does the following, in order:

• Sets the hostname Karavan is served as (the instance's public DNS name when it has one).
• Creates the TLS certificate and generates the passwords.
• Creates the local git repository and starts PostgreSQL and Karavan.
• Proves that both accounts sign in with their own passwords.
• Loads a demo integration and writes /root/karavan-credentials.txt (mode 0600, root).
• Opens nginx.

These are the entries in the credentials file (the passwords are not shown here):

sudo grep -E '^KARAVAN_(URL|USERNAME|DEVELOPER_USERNAME)=' /root/karavan-credentials.txt
sudo grep -oE '^[A-Z_]+=' /root/karavan-credentials.txt
sudo stat -c '%a %U:%G' /root/karavan-credentials.txt

KARAVAN_URL=https://ec2-3-95-166-62.compute-1.amazonaws.com/ KARAVAN_USERNAME=admin KARAVAN_DEVELOPER_USERNAME=developer KARAVAN_URL= KARAVAN_USERNAME= KARAVAN_PASSWORD= <set-at-first-boot>= KARAVAN_DEVELOPER_PASSWORD= 600 root:root

• KARAVAN_URL: the address of this instance's Karavan.
• KARAVAN_USERNAME / KARAVAN_PASSWORD: the admin account (all roles), generated on this instance. It opens both the access gate and Karavan's sign-in.
• KARAVAN_DEVELOPER_USERNAME / KARAVAN_DEVELOPER_PASSWORD: the built-in developer account (developer role) with its own password, for both the gate and Karavan.

To read the values, run sudo cat /root/karavan-credentials.txt in your own session and store them in your password manager.

The metadata wall, the rootless engine, the first-boot units, Karavan and nginx are all active. Only sshd and nginx listen beyond loopback. Karavan is on 127.0.0.1:8080, integrations you run publish on 127.0.0.1 too, and PostgreSQL's port exists only inside its internal container network.

The engine belongs to the karavan account, so list its containers with sudo -u karavan:

systemctl is-active sac-karavan-imds-deny.service karavan-docker.service karavan-firstboot.service karavan.service karavan-postboot.service nginx.service kd() { (cd / && sudo -u karavan env HOME=/var/lib/karavan DOCKER_HOST=unix:///run/karavan-docker/docker.sock docker "$@"); } kd ps --format '{{.Names}} {{.Image}} {{.Ports}}'
sudo ss -Htlnp | awk '{print $4, $6}' | sed -E 's/,pid=[0-9]+,fd=[0-9]+//g' | sort -u curl -sk https://127.0.0.1/healthz

active active active active active active karavan sac/camel-karavan:4.22.1-temurin25 127.0.0.1:8080->8080/tcp karavan-postgres postgres:18.6-alpine 5432/tcp 0.0.0.0:22 users:(("sshd"),("systemd")) 0.0.0.0:443 users:(("nginx"),("nginx"),("nginx")) 0.0.0.0:80 users:(("nginx"),("nginx"),("nginx")) 127.0.0.1:8080 users:(("rootlesskit")) 127.0.0.53%lo:53 users:(("systemd-resolve")) 127.0.0.54:53 users:(("systemd-resolve")) [::]:22 users:(("sshd"),("systemd")) [::]:443 users:(("nginx"),("nginx"),("nginx")) [::]:80 users:(("nginx"),("nginx"),("nginx")) ok

nginx answers /healthz itself and reveals nothing, so it is safe to use as a load balancer health check.

Signed-out requests stop at the access gate, including the path variants that bypass path-based authorization in some web frameworks. The gate alone gives no access to Karavan's API, because Karavan's own session is needed too.

The commands show that a cross-origin POST is refused, an unknown Host header gets no answer, and plain HTTP redirects to the configured HTTPS name. The last line signs in to Karavan with this instance's admin password and reads its version:

H=$(sudo sed -n 's/^set \$app_host "\(.*\)";$/\1/p' /etc/nginx/karavan-host.conf)
P=$(sudo grep '^KARAVAN_PASSWORD=' /root/karavan-credentials.txt | cut -d= -f2-) R=(--resolve "$H:443:127.0.0.1") for path in / "/ui/project" "/ui/project;x" "/ui/project%3Bx" "/ui%2Fproject"; do curl -sk "${R[@]}" --path-as-is -o /dev/null -w "anonymous $path -> %{http_code}\n" "https://$H$path" done curl -sk "${R[@]}" -o /dev/null -w 'gate, wrong password -> %{http_code}\n' -K <(printf 'user = "admin:not-the-password"\n') "https://$H/" curl -sk "${R[@]}" -o /dev/null -w 'gate, your password -> %{http_code}\n' -K <(printf 'user = "admin:%s"\n' "$P") "https://$H/" curl -sk "${R[@]}" -o /dev/null -w 'API without a Karavan session -> %{http_code}\n' -K <(printf 'user = "admin:%s"\n' "$P") "https://$H/ui/project" curl -sk "${R[@]}" -o /dev/null -w 'cross-origin POST -> %{http_code}\n' -K <(printf 'user = "admin:%s"\n' "$P") -X POST \
  -H 'Origin: https://evil.example' -H 'Content-Type: application/json' -d '{}' "https://$H/ui/auth/login" curl -sk -o /dev/null -w 'unknown Host -> %{http_code}\n' -H 'Host: evil.example' https://127.0.0.1/ || true curl -s -o /dev/null -w 'http -> %{http_code} %{redirect_url}\n' -H "Host: $H" http://127.0.0.1/
J=$(mktemp); curl -sk "${R[@]}" -o /dev/null -c "$J" -K <(printf 'user = "admin:%s"\n' "$P") -H "Origin: https://$H" \
  -H 'Content-Type: application/json' --data-binary @<(printf '{"username":"admin","password":"%s"}' "$P") "https://$H/ui/auth/login" curl -sk "${R[@]}" -b "$J" -K <(printf 'user = "admin:%s"\n' "$P") "https://$H/ui/configuration" | jq -c '{title, version, infrastructure}' rm -f "$J"

anonymous / -> 401 anonymous /ui/project -> 401 anonymous /ui/project;x -> 401 anonymous /ui/project%3Bx -> 401 anonymous /ui%2Fproject -> 401 gate, wrong password -> 401 gate, your password -> 200 API without a Karavan session -> 401 cross-origin POST -> 403 unknown Host -> 000 http -> 301 https://ec2-3-95-166-62.compute-1.amazonaws.com/ {"title":"Apache Camel Karavan","version":"4.22.1","infrastructure":"docker"}

The password reaches curl through files on file descriptors (-K <(...) and --data-binary @<(...)), so it never appears on a command line or in your shell history.

Browse to KARAVAN_URL (https://<public-dns-name>/). The certificate is self-signed, so your browser warns you once. Accept it for this host, or install your own certificate (Step 9).

Your browser first asks for the access gate username and password. Enter admin and KARAVAN_PASSWORD. Karavan's sign-in page then opens. Enter the same username and password and choose Access Platform.

The Integrations page lists your projects. A new instance has one project, Demo Integration (demo), with two routes. It is committed to the instance's local git repository.

Open demo, choose Source and select heartbeat.camel.yaml. The Designer shows the route as a flow: a Timer that fires every 10 seconds, a Set Body step and a Log step.

Select a step to edit its properties on the right. Drag components and patterns from the palette to extend the route. Code shows the same route as Camel YAML, and Diff shows your changes since the last commit.

To create your own project, choose Create Integration on the Integrations page. Under Source, Commits shows the git history of the project, and Push commits your changes to the local repository.

In the project, open Containers and choose Run. Karavan starts the integration as its own container from the developer-mode runtime image, on the rootless engine.

Log streams the container's output. The demo's two routes log a heartbeat every 10 seconds and a greeting every 30 seconds.

You can do the same from the command line, through the access gate and Karavan's API:

H=$(sudo sed -n 's/^set \$app_host "\(.*\)";$/\1/p' /etc/nginx/karavan-host.conf)
P=$(sudo grep '^KARAVAN_PASSWORD=' /root/karavan-credentials.txt | cut -d= -f2-) R=(--resolve "$H:443:127.0.0.1");
J=$(mktemp) G() { curl -sk "${R[@]}" -K <(printf 'user = "admin:%s"\n' "$P") -b "$J" -c "$J" -H "Origin: https://$H" "$@"; } G -o /dev/null -H 'Content-Type: application/json' --data-binary @<(printf '{"username":"admin","password":"%s"}' "$P") "https://$H/ui/auth/login"
CSRF=$(awk '$6=="csrf"{print $7}' "$J") G -o /dev/null -w 'run demo in developer mode -> %{http_code}\n' -H "X-CSRF-Token: $CSRF" "https://$H/ui/devmode/run/demo" kd() { (cd / && sudo -u karavan env HOME=/var/lib/karavan DOCKER_HOST=unix:///run/karavan-docker/docker.sock docker "$@"); } for i in $(seq 1 30); do
L=$(kd logs demo 2>&1 || true); [[ "$L" == *"demo heartbeat"* ]] && break; sleep 5; done kd ps --filter name=^demo$ --format '{{.Names}} {{.Image}} {{.Ports}}' grep -m1 -o 'Body: sac Karavan demo heartbeat' <<<"$L" rm -f "$J"

run demo in developer mode -> 200 demo sac/camel-karavan-devmode:4.22.1-sac1 8443/tcp, 127.0.0.1:8081->8080/tcp Body: sac Karavan demo heartbeat

The first run of a route downloads the Camel components it uses from Maven Central, so it takes a little longer.

An integration's HTTP port (here 8081) is bound to 127.0.0.1 only. To reach it from elsewhere, add an nginx location for it or use an SSH tunnel (ssh -L 8081:127.0.0.1:8081 ubuntu@<public-ip>).

After a few minutes, Docker reports developer-mode containers as unhealthy, because Karavan 4.22.1's container health check probes an older management port. The integration keeps running, and Karavan shows it as running.

The engine runs as karavan in rootless mode, and the root Docker daemon is masked. From inside the running demo integration, the internet is reachable but the instance metadata service is not. Both metadata walls are in place:

kd() { (cd / && sudo -u karavan env HOME=/var/lib/karavan DOCKER_HOST=unix:///run/karavan-docker/docker.sock docker "$@"); } echo "engine runs as: $(ps -o user= -p "$(systemctl show -p MainPID --value karavan-docker.service)")" kd info --format '{{json .SecurityOptions}}' systemctl is-enabled docker.service docker.socket containerd.service kd exec demo curl -s -m 10 -o /dev/null -w 'integration -> internet: %{http_code}\n' https://checkip.amazonaws.com/ kd exec demo curl -s -m 6 -o /dev/null -w 'integration -> instance metadata: %{http_code}\n' -X PUT \
  -H 'X-aws-ec2-metadata-token-ttl-seconds: 60' http://169.254.169.254/latest/api/token || true systemctl show -p IPAddressDeny karavan-docker.service
sudo iptables -S OUTPUT | grep -c 'uid-owner'

engine runs as: karavan ["name=seccomp,profile=builtin","name=rootless","name=cgroupns"] masked masked masked integration -> internet: 200 integration -> instance metadata: 000 IPAddressDeny=fd00:ec2::254/128 168.63.129.16/32 169.254.169.254/32 4

000 means the connection never got an answer.

If an integration needs AWS credentials, give it an access key through its own configuration (or a secrets service) instead of the instance role. The instance role is deliberately out of reach.

Point a DNS record at the instance. An Elastic IP keeps the address stable. Then set the name with the helper, which re-issues the self-signed certificate for it, updates nginx and the Origin guard, and updates KARAVAN_URL:

sudo karavan-set-hostname <your-domain>

To use a certificate from a public CA, replace /etc/ssl/karavan/karavan.crt and /etc/ssl/karavan/karavan.key (key mode 0600, root) with your own, then reload nginx with sudo systemctl reload nginx.

Without a pinned name, the instance follows its public DNS name across a stop and start.

Developer mode works out of the box. Karavan's Build and Deploy actions package an integration as a container image, push it to a registry and run it from there. They need a git remote and a container registry that you provide.

Edit /opt/karavan/docker-compose.yml. Set KARAVAN_GIT_REPOSITORY to your remote, with KARAVAN_GIT_USERNAME and KARAVAN_GIT_PASSWORD for an HTTPS remote. Add KARAVAN_CONTAINER_IMAGE_REGISTRY, KARAVAN_CONTAINER_IMAGE_REGISTRY_USERNAME and KARAVAN_CONTAINER_IMAGE_REGISTRY_PASSWORD. Then run sudo systemctl restart karavan to apply the change.

The compose file is world-readable, so keep secrets out of it. A production setup puts them in /opt/karavan/secrets/karavan-secrets.properties as karavan.git.password= and karavan.container-image.registry-password= lines instead.

In Karavan, open your profile from the account menu and choose Change password for the signed-in account. As admin, you can also set other accounts' passwords on the access management page.

Then set the same new password for that account at the access gate. The command asks for the password twice and stores only a bcrypt hash:

sudo htpasswd -B /etc/nginx/karavan.htpasswd admin
# enter <new-password> twice

Update /root/karavan-credentials.txt to match. The value in /opt/karavan/secrets/karavan-secrets.properties only seeds the admin account on the first start of an empty database. Changing it later does not change an existing password.