Cameleer SaaS is a managed observability and runtime platform for Apache Camel applications. It lets you upload your Camel application JARs, deploy them as managed containers with the Cameleer agent automatically injected, and observe their behavior through route topology graphs, execution traces, processor metrics, and container logs -- all without running your own infrastructure.
### Who This Manual Is For
This manual is written for:
- **SaaS customers** who access a hosted Cameleer instance to deploy and monitor their Camel applications.
- **Self-hosted operators** who run the full Cameleer SaaS stack on their own infrastructure using Docker Compose.
Both audiences share the same UI and workflows. The self-hosted setup section at the end covers the additional steps needed to run the platform yourself.
The sidebar provides access to all major sections:
| Section | Description |
|---------|-------------|
| **Dashboard** | Tenant overview and KPI metrics |
| **Environments** | Expandable tree showing all environments and their apps |
| **License** | License tier, features, limits, and token |
| **Platform** | Platform-wide tenant management (visible only to platform admins) |
| **View Dashboard** | Opens the observability dashboard (cameleer3-server) in a new tab |
| **Account** | Log out of the current session |
The Environments section in the sidebar renders as a collapsible tree: environments at the top level, with their applications nested underneath. Clicking any item navigates directly to its detail page.
---
## 3. Environments
### What Environments Are
An environment is an isolated runtime context within your tenant. Environments let you separate concerns -- for example, you might create `development`, `staging`, and `production` environments. Each environment has its own set of applications and deployments.
Every environment has:
- A **slug** (URL-safe identifier, e.g., `production`) -- immutable after creation.
- A **display name** (human-readable, e.g., "Production") -- can be renamed.
- A **status** -- typically `ACTIVE`.
### Creating an Environment
> **Note:** Creating environments requires the `apps:manage` scope. If you do not see the "Create Environment" button, contact your organization admin.
To create an environment:
1. Navigate to **Environments** from the sidebar or click **Create Environment** on the dashboard.
2. Click **Create Environment** in the top-right corner.
3. In the modal dialog, enter:
- **Slug** -- A URL-safe identifier (e.g., `staging`). Cannot be changed later.
- **Display Name** -- A human-readable name (e.g., "Staging").
Your license tier determines how many environments you can create:
| Tier | Max Environments |
|------|-----------------|
| LOW | 1 |
| MID | 2 |
| HIGH | Unlimited |
| BUSINESS | Unlimited |
If you attempt to create an environment beyond your tier limit, the request will be rejected.
### Managing Environments
From the environment detail page you can:
- **Rename** the environment by clicking its display name (inline edit). Requires the `apps:manage` scope.
- **Delete** the environment using the "Delete Environment" button. An environment can only be deleted after all its apps have been removed. Requires the `apps:manage` scope.
---
## 4. Applications
### What an Application Represents
An application in Cameleer SaaS represents one of your Apache Camel applications. It tracks the uploaded JAR file, deployment state, routing configuration, and observability status. Applications live inside environments.
### Creating an Application
> **Note:** Creating applications requires the `apps:deploy` scope.
To create an application:
1. Navigate to the environment where you want to add the app.
2. Click **New App**.
3. In the modal dialog, fill in:
- **Slug** -- A URL-safe identifier (e.g., `order-router`). Cannot be changed later.
- **Display Name** -- A human-readable name (e.g., "Order Router").
- **JAR File** (optional) -- Select your Camel application JAR. You can also upload or re-upload the JAR later.
4. Click **Create App**.
### Uploading a JAR File
You can upload a JAR at creation time or re-upload it later:
1. Navigate to the app detail page.
2. In the **Actions** card on the Overview tab, click **Re-upload JAR**.
3. Select the new JAR file and click **Upload**.
The platform stores the original filename, file size, and a checksum for each upload.
### Understanding Agent Injection
When you deploy an application, the platform builds a Docker image from your JAR with the Cameleer agent automatically injected as a `-javaagent`. This means:
- You do not need to modify your application code or build process.
- The agent instruments your Camel routes at runtime using bytecode manipulation.
- The agent connects to the observability server and begins reporting route topology, execution traces, and processor metrics.
---
## 5. Deployments
### Deploying an Application
> **Note:** Deploying requires the `apps:deploy` scope.
To deploy an application:
1. Navigate to the app detail page (via the sidebar tree or the environment's app list).
2. On the **Overview** tab, in the **Actions** card, click **Deploy**.
3. The deployment starts asynchronously. The status will transition through the deployment lifecycle.
### Viewing Deployment Status
After triggering a deployment, the **Current Deployment** card on the Overview tab shows:
- **Version** -- An incrementing deployment version number.
- **Status** -- The observed status of the deployment.
- **Image** -- The Docker image reference built for this deployment.
- **Deployed** -- The timestamp when the deployment started.
- **Error** -- If the deployment failed, the error message appears here.
The deployment lifecycle follows these status transitions:
```
BUILDING --> STARTING --> RUNNING
|
+--> FAILED
```
- **BUILDING** -- The Docker image is being built with your JAR and the Cameleer agent.
- **STARTING** -- The container has been created and is starting up.
- **RUNNING** -- The container is running and healthy.
- **FAILED** -- The deployment encountered an error (image build failure, container crash, etc.).
### Stopping and Restarting
From the **Actions** card:
- **Stop** -- Stops the running container. A confirmation dialog appears before stopping.
- **Restart** -- Stops and redeploys the application with the same JAR version.
Both actions require the `apps:deploy` scope and are only available when the app has an active deployment.
### Reading Container Logs
To view container logs:
1. Navigate to the app detail page.
2. Click the **Logs** tab.
3. Logs appear in a scrollable viewer with timestamps.
4. Filter by stream using the buttons at the top: **All**, **stdout**, or **stderr**.
> **Tip:** If no logs appear, the app may not have been deployed yet or the container may have exited immediately.
### Deployment History
To view the full deployment history:
1. Navigate to the app detail page.
2. Click the **Deployments** tab.
3. A table shows all past and current deployments with: version, observed status, desired status, deployed timestamp, stopped timestamp, and any error message.
Failed deployments are highlighted with a red accent for quick identification.
---
## 6. Observability
### Accessing the Observability Dashboard
The observability dashboard is provided by cameleer3-server and opens in a separate browser tab:
1. In the sidebar footer, click **View Dashboard**.
2. The dashboard opens at the cameleer3-server URL.
Alternatively, from any app detail page, the **Agent Status** card includes a "View in Dashboard" link.
### What You Can See
The observability dashboard provides:
- **Route topology** -- Visual graph of your Camel routes showing processors, endpoints, and data flow.
- **Execution traces** -- Individual route execution traces with timing, payload snapshots, and processor-level detail.
- **Processor metrics** -- Throughput, latency, and error rates per processor node.
### Agent Connection Status
The **Agent Status** card on each app detail page shows:
- **Registration state** -- Whether the agent has registered with the observability server.
- **Connection state** -- `CONNECTED` (live, with a pulsing indicator) or `DISCONNECTED`.
- **Last heartbeat** -- Timestamp of the most recent agent heartbeat.
- **Routes** -- List of Camel route IDs discovered by the agent.
- **Observability data** -- Whether traces, metrics, and diagrams are being produced, with a 24-hour trace count.
---
## 7. Licenses
### Understanding Tiers
Cameleer SaaS uses four license tiers that control available features and resource limits:
| Tier | Features | Max Agents | Max Environments | Retention |
- **Validity** -- Issue date, expiration date, and days remaining. The days-remaining badge turns yellow when 30 or fewer days remain and red when expired.
- **Features** -- Which observability features are enabled or disabled.
- **Limits** -- Max agents, retention days, and max environments.
- **License token** -- Click "Show token" to reveal the token used for agent registration.
> **Warning:** If your license expires, deployed applications continue to run but new deployments and agent registrations may be restricted. Contact your administrator to renew.
---
## 8. Platform Administration
> **Note:** This section applies only to users with the `platform:admin` scope. The Platform section in the sidebar is not visible to regular users.
### Managing Tenants
Platform administrators can view and manage all tenants across the platform:
1. Click **Platform** in the sidebar.
2. The **All Tenants** page displays a table of every tenant with: name, slug, tier, status, and creation date.
3. Click on a tenant row to switch your active context to that tenant's dashboard.
New tenants can be created via the API (the UI currently provides read-only access to the tenant list):
```
POST /api/tenants
Content-Type: application/json
{
"name": "Acme Corp",
"slug": "acme-corp",
"tier": "MID"
}
```
This requires a valid token with the `platform:admin` scope. A default environment is automatically created with each new tenant.
### Creating Organizations in Logto
Each tenant in Cameleer SaaS corresponds to an organization in Logto. When you create a tenant, a corresponding Logto organization should be created and users assigned to it. For self-hosted deployments, the bootstrap script handles this automatically for the initial tenant.
To create additional organizations:
1. Open the Logto admin console.
2. Navigate to **Organizations** and create a new organization.
3. Add users to the organization and assign them the appropriate role (admin or member).
4. Create the corresponding tenant in Cameleer SaaS via the API with a matching slug.
---
## 9. Roles and Permissions
### Organization Roles
Cameleer SaaS uses two organization-level roles managed in Logto:
| Role | Description |
|------|-------------|
| **admin** | Full access to all tenant operations |
| **member** | Can deploy apps and view observability data |
| `settings:manage` | Yes | No | Manage settings |
In the UI, buttons and actions that require a scope you do not have are automatically hidden. For example, members will not see "Create Environment" or "Delete App" buttons.
### How Permissions Are Managed
All role and permission management happens in Logto, not in the Cameleer SaaS application itself:
- Organization roles and their scopes are configured in Logto during the bootstrap process.
- To change a user's role, update their organization role assignment in the Logto admin console.
- To add a user to a tenant, add them to the corresponding Logto organization and assign a role.
There is also a global `platform:admin` scope (separate from organization roles) that grants access to the Platform section for cross-tenant administration.
The full list of 10 scopes is also available programmatically via the `GET /api/config` endpoint, which the frontend uses to discover available scopes at runtime.
In production mode (`docker compose up`), only ports 80 and 443 are exposed via Traefik. In development mode (`docker compose -f docker-compose.yml -f docker-compose.dev.yml up`), individual service ports are exposed directly for debugging.
### The Bootstrap Process
On first boot, the `logto-bootstrap` container automatically:
1. Waits for Logto and cameleer3-server to be healthy.
2. Creates three Logto applications:
- **Cameleer SaaS** (SPA) -- for the management UI frontend.
- **Cameleer SaaS Backend** (Machine-to-Machine) -- for server-to-Logto API calls.
- **Cameleer Dashboard** (Traditional Web App) -- for cameleer3-server OIDC login.
6. Creates a Logto organization ("Example Tenant") and assigns both users.
7. Configures cameleer3-server with Logto OIDC settings for dashboard authentication.
8. Writes all generated IDs and secrets to `/data/logto-bootstrap.json` for the SaaS backend to consume.
The bootstrap is idempotent -- re-running it will skip resources that already exist.
### Logto Admin Console Access
For self-hosted deployments, the Logto admin console is available at:
- **Development:** `http://localhost:3002`
- **Production:** Accessible only if you configure a Traefik route for port 3002.
Use the admin console to:
- Manage users and their roles.
- Configure social login connectors (Google, GitHub, etc.).
- View and manage applications and API resources.
- Create additional organizations for new tenants.
### Connecting to an External OIDC Provider
To use an external identity provider instead of Logto's built-in username/password:
1. Open the Logto admin console.
2. Navigate to **Connectors** > **Social** or **Enterprise SSO**.
3. Configure your provider (e.g., Google, Azure AD, Okta).
4. Users can then sign in through the configured provider on the Logto login page.
The Cameleer SaaS application itself does not need any changes -- all identity configuration is handled in Logto.
---
## 11. Troubleshooting
### Login Fails or Redirect Loop
**Symptoms:** Clicking "Sign in with Logto" redirects you in a loop, or you see an error page.
**Possible causes:**
- The Logto endpoint is unreachable. Verify that Logto is running: `docker compose ps logto`.
- The SPA client ID is incorrect. Check that `VITE_LOGTO_CLIENT_ID` (or the auto-configured value from bootstrap) matches the SPA application ID in Logto.
- The redirect URI is not registered. The SPA app in Logto must have your current URL's `/callback` path as an allowed redirect URI. The bootstrap registers `http://localhost/callback`, `http://localhost:8080/callback`, and `http://localhost:5173/callback` by default.
**Resolution:**
1. Check Logto logs: `docker compose logs logto`.
2. Open the Logto admin console and verify the SPA application's redirect URIs.
3. If running on a custom domain, add your callback URL to the SPA application's redirect URI list.
### 401 Errors After Login
**Symptoms:** You log in successfully but API calls return 401 Unauthorized.
**Possible causes:**
- Token audience mismatch. The backend expects tokens issued for `https://api.cameleer.local`.
- The Logto issuer URI configured in the backend does not match the actual Logto endpoint.
- Clock skew between the Logto container and the backend container.
3. To increase memory limits, set `CAMELEER_SERVER_RUNTIME_CONTAINER_MEMORYLIMIT` to a higher value (e.g., `1g`) on the per-tenant server container and restart it.
