Apache Camel Karavan on Ubuntu 24.04 on Azure User Guide

Overview

Apache Camel Karavan is a visual integration designer and toolkit for Apache Camel. It gives you a browser based canvas to design, build and run enterprise integration patterns (EIP) and Kamelet based routes without hand writing boilerplate, then build and run each integration as its own container. The cloudimg image runs the official Karavan container plus its PostgreSQL state store as a Docker Compose stack under systemd, then locks it down for a marketplace appliance. Karavan is bound to loopback 127.0.0.1:8080 and never exposed directly; an nginx reverse proxy on port 80 adds a per VM HTTP Basic Auth gate (user admin, unique password generated on first boot) in front of it, plus an unauthenticated /healthz endpoint for load balancer probes. A demo integration project is seeded on first boot so the designer opens populated, and Docker Engine is installed so Karavan's built in runner can build and run integrations as containers. Backed by 24/7 cloudimg support.

What is included:

• Apache Camel Karavan 4.18.1 (the official ghcr.io/apache/camel-karavan container) running as the karavan systemd service
• The full Karavan visual designer and API on :80, fronted by nginx with Karavan bound to loopback only
• A PostgreSQL state store for projects and sessions, on a private Docker network with no published port
• Docker Engine (docker-ce) so Karavan's Docker mode can build and run each integration as its own container
• Per VM HTTP Basic Auth (user admin) protecting the UI, with a unique password generated on first boot
• Karavan's own sign in password also rotated to the same per VM value, so the upstream default is never shipped
• A demo integration project (a timer to log heartbeat route and a greeting route) seeded on first boot
• An unauthenticated /healthz endpoint for Azure Load Balancer health probes
• karavan.service + nginx.service + docker.service as systemd units, enabled and active
• The bcrypt Basic Auth hash stored on disk only - no plaintext password ships in the image
• 24/7 cloudimg support

Prerequisites

An active Azure subscription, an SSH key pair, and a VNet plus subnet in the target region. Standard_B2s (2 vCPU / 4 GiB RAM) is a comfortable starting point for the designer and running a single integration; scale up if you run several integrations at once. NSG inbound: allow 22/tcp from your management network and 80/tcp for the web UI, and 443/tcp if you add TLS. Karavan serves plain HTTP on port 80; for production use, terminate TLS in front of it with your own domain and restrict access to trusted IP ranges (see Maintenance).

Step 1 - Deploy from the Azure Marketplace

Sign in to the Azure Portal, choose Create a resource, search the Marketplace for Apache Camel Karavan by cloudimg, and select Create. On Basics pick your subscription, resource group, region and size; under Administrator account choose SSH public key and paste your key; under Inbound port rules allow SSH (22) and HTTP (80). Then Review + create -> Create.

Step 2 - Deploy from the Azure CLI

az vm create \
  --resource-group <your-rg> \
  --name karavan \
  --image <marketplace-image-urn> \
  --size Standard_B2s \
  --admin-username azureuser \
  --ssh-key-values ~/.ssh/id_rsa.pub \
  --public-ip-sku Standard

Then open ports 22 and 80 to your management network:

az vm open-port --resource-group <your-rg> --name karavan --port 22 --priority 1000
az vm open-port --resource-group <your-rg> --name karavan --port 80 --priority 1010

Step 3 - Connect to your VM

ssh azureuser@<vm-public-ip>

Step 4 - Confirm the stack is running

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

The karavan and karavan-postgres containers report up, and docker, karavan and nginx report active. Karavan serves its designer on the loopback address 127.0.0.1:8080; nginx fronts it on port 80 and adds the per VM HTTP Basic Auth gate. The application and its database are never bound to a public interface, so nginx is the only way in.

Step 5 - Retrieve your web UI password

nginx protects the Karavan UI with HTTP Basic Auth, and Karavan's own sign in uses the same credentials. The username is admin and a unique password is generated on the first boot of your VM and written to a root only file:

sudo cat /root/karavan-credentials.txt

This file contains KARAVAN_USERNAME, KARAVAN_PASSWORD and the KARAVAN_URL to open in a browser. The password is stored on disk only as a bcrypt hash in /etc/nginx/.karavan.htpasswd, so no plaintext password ships in the image. Store the password somewhere safe.

Step 6 - Confirm the health endpoint

nginx serves an unauthenticated health endpoint for load balancers and probes:

curl -s http://localhost/healthz

It returns ok. This endpoint never requires authentication, so it is safe for an Azure Load Balancer health probe.

Step 7 - Confirm authentication

Because a password is set on first boot, an unauthenticated request to the UI returns HTTP 401, so nobody reaches Karavan without the password. The following reads the per VM password from the credentials file and proves the round trip - the health endpoint is open, an unauthenticated request to the UI is rejected, and the correct password authenticates:

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

It prints healthz : 200, unauth : 401 and authed : 200. The whole UI is only reachable with the per VM password because Karavan itself is bound to loopback and nginx is the only way in.

Step 8 - Sign in to the Karavan designer

Browse to http://<vm-public-ip>/. You are asked for credentials twice with the same username and password: first the browser's HTTP Basic Auth dialog (the nginx access gate), then the Karavan Login form. Both use username admin and the password from Step 5.

After signing in you land on the Karavan dashboard. It shows your projects and routes at a glance, a Team panel, and cards to create a new integration, design a REST service, or import a project. The seeded Demo Integration project is listed under Recent Projects.

Step 9 - Open the demo integration project

Click Demo Integration (or open Projects in the left navigation and select it). The project opens on the Architecture tab, which shows every route in the project as a topology diagram - here the heartbeat and greeting routes that were seeded on first boot. The tabs across the top (Architecture, Source, Build, Containers) and the Run button are how you design, inspect, build and run the integration.

Step 10 - Edit a route in the visual designer

Click the heartbeat route to open it in the visual designer. Each step of the route is a node on the canvas - a Timer source feeding a Logger - and the Properties panel on the right lets you edit any node's settings without writing YAML. Use the Designer and Code toggle at the top right to switch between the visual canvas and the generated Camel YAML at any time.

Step 11 - Build and run an integration

Karavan's Docker mode runs an integration as its own Apache Camel container using the Docker Engine installed on the VM. In the project, click Run (top right) to build and start the demo integration; the Containers tab then shows the running Camel container and its live log. The heartbeat route logs a message every ten seconds, which you can follow from the VM as well:

docker logs -f demo

The container reports Apache Camel 4.18.1 (demo) started and then Started heartbeat (timer://heartbeat), confirming the route is running end to end. Stop it from the Containers tab (or the route's Stop control) when you are done.

Step 12 - Create your own integration

From the dashboard, click Create Integration, give the project a name and id, then add routes on the canvas from the component and EIP palette - or import an existing project as a zip. Karavan stores every project in the PostgreSQL state store on the VM, so your work persists across restarts. Build and run any project the same way as Step 11. To collaborate across a team, connect Karavan to a Git repository from Settings so projects are committed and shared.

Maintenance

• Password: the UI password is set on first boot. The nginx Basic Auth entry is a bcrypt hash in /etc/nginx/.karavan.htpasswd; to change it run sudo htpasswd -B /etc/nginx/.karavan.htpasswd admin and then sudo systemctl reload nginx. Karavan's own sign in password is the PLATFORM_PASSWORD value in /opt/karavan/.env; change it there and run sudo systemctl restart karavan, then update the two to match.
• The stack: the Compose file is /opt/karavan/docker-compose.yml and is managed by karavan.service. Use sudo systemctl restart karavan to restart the app and database, and docker ps to check container health.
• Your projects: projects live in the PostgreSQL container's pgdata volume under /opt/karavan. Back up that directory (with the stack stopped) to preserve your integrations.
• Restrict access: Karavan serves plain HTTP on port 80. For production, restrict access to trusted IP ranges in your Network Security Group, and front it with TLS (for example certbot with your own domain) terminating on :443.
• Loopback binding: Karavan is published on 127.0.0.1:8080 and the Docker socket is used only locally, so nginx is the only path in. Keep it that way - do not publish the container on a public interface.
• Security patches: unattended-upgrades remains enabled so the OS continues to receive security updates automatically. Update the app by pulling a newer ghcr.io/apache/camel-karavan tag in /opt/karavan/docker-compose.yml and running sudo systemctl restart karavan.

Support

cloudimg provides 24/7 expert support for this image. Contact support@cloudimg.co.uk.