Quickstart¶

This walks you through the shortest path from "nothing installed" to "agent visible in the UI". The local stack uses Docker Compose, brings up PostgreSQL, Keycloak (OIDC), Ampora itself, and a sample OpenTelemetry Collector for you to play with.

If you are heading for a real cluster instead, jump to Operator → Installation → Kubernetes.

Prerequisites¶

On Linux (without Docker Desktop) add this entry to /etc/hosts so the browser and the Ampora container resolve Keycloak through the same name:

127.0.0.1 host.docker.internal

1. Bring the stack up¶

From the root of the Ampora repository:

docker compose up --build

This builds the ampora/web:dev image from the local source tree, brings up PostgreSQL, Keycloak (with a pre-seeded ampora realm), the OpenTelemetry Collector, Jaeger, Prometheus, MinIO and MailHog.

The first start takes a couple of minutes — Keycloak imports its realm and Ampora migrates the database.

2. Log in¶

Open http://localhost:8080. The browser is bounced to the Keycloak login page. Three users are pre-seeded; password is password for all of them:

Log in as alice. You land on the Dashboard.

3. Take a tour¶

Spend two minutes clicking through the empty UI to learn where things live:

• Fleet — agents will appear here once they connect.
• Configurations — versioned collector configs.
• Rollouts — the rollout history.
• Groups — static and dynamic agent groups.
• Audit log — every state-changing action.
• Settings → Tokens — bootstrap tokens for new agents.
• Settings → Identities — issued mTLS certificates.
• Settings → Tenant — branding, colours, login wall.

4. Issue a bootstrap token¶

Navigate to Settings → Tokens → Issue token:

1. Give it a label like quickstart-agent-1.
2. Set TTL to 24h (the default).
3. Click Issue.

Copy the token now — Ampora shows it once and never again.

5. Connect a collector¶

Use the OpenTelemetry Collector image with the opamp_extension. A minimal config that talks to the local Ampora is:

extensions:
  opamp:
    server:
      ws:
        endpoint: ws://host.docker.internal:8080/v1/opamp
        headers:
          Authorization: "Bearer YOUR_BOOTSTRAP_TOKEN_HERE"
    instance_uid: 01J0000000000000000000000A
    capabilities:
      reports_effective_config: true
      reports_health: true
      accepts_remote_config: true

receivers:
  otlp:
    protocols:
      grpc:
        endpoint: 0.0.0.0:4317

exporters:
  debug:
    verbosity: basic

service:
  extensions: [opamp]
  pipelines:
    traces:
      receivers: [otlp]
      exporters: [debug]
    metrics:
      receivers: [otlp]
      exporters: [debug]

Replace YOUR_BOOTSTRAP_TOKEN_HERE with the token from step 4 and run:

docker run --rm --name quickstart-agent \
  --add-host host.docker.internal:host-gateway \
  -v "$(pwd)/quickstart-agent.yaml:/etc/otelcol/config.yaml:ro" \
  otel/opentelemetry-collector-contrib:0.115.1 \
  --config=/etc/otelcol/config.yaml

Within a few seconds the agent should appear on the Fleet page. Click into it and you should see:

• Effective config — the YAML you just shipped.
• Health — green.
• Capabilities — AcceptsRemoteConfig, ReportsEffectiveConfig, ReportsHealth.

6. Push a config from Ampora¶

Now make Ampora the source of truth instead:

1. Configurations → New configuration, name it quickstart.
2. Paste a slightly modified version of the YAML (e.g. add a batch processor between otlp and debug).
3. Save as draft, then Publish.
4. Groups → New group → Static, name it quickstart-group, add the running agent.
5. Rollouts → New rollout → pick quickstart v1 and quickstart-group, batch size 1.
6. Start, watch the rollout walk to Completed.

Re-open the agent details. The Effective config should now match what you just published. Drift should be zero.

7. Tear it all down¶

docker compose down -v

The -v flag drops the volumes — your next up --build is a clean slate.

What next?¶