Quickstart Process Improvements

[a5anka]

Overview

After analyzing the quickstart process (deployments/quick-start/), here are identified improvements organized by priority.

The current flow:

1. User runs a Docker container with --network=host and Docker socket mounted
2. entrypoint.sh sets up Docker socket permissions and switches to wso2-amp user
3. User manually runs ./install.sh (13 steps, ~15-20 min)
4. Script creates k3d cluster, installs OpenChoreo (4 planes), registers planes, installs AMP + 6 extensions

---

P0 — Reliability / Fail-fast

1. Bundle remote YAML files into the Docker image

The script fetches multiple YAML configs from GitHub raw URLs during installation (values files, CRDs, configmaps). If GitHub is slow or unreachable, install fails mid-way.

Suggestion: Copy these files into the Docker image at build time and use them as the primary source, with remote fetch as a fallback.

2. Resource pre-flight check

The script doesn't check if the host has enough resources (CPU/RAM) before starting. A k3d cluster + OpenChoreo + AMP on a machine with <8GB will fail late in the process.

Suggestion: Add an upfront check using docker info to verify available memory and CPUs before starting installation.

---

P1 — User Experience / Portability

3. Single-command install option

The two-step UX (enter container, then run ./install.sh) adds unnecessary friction.

Suggestion: Support docker run ... ghcr.io/wso2/amp-quick-start:v0.9.0-rc1 --install or prompt at container startup:

Would you like to start installation? [Y/n]

4. --network=host doesn't work on Docker Desktop for Mac/Windows

--network=host is a Linux-only Docker feature. On Mac (even with Colima's vz driver), it behaves differently. The k3d config already maps specific ports (3000, 9000, etc.).

Suggestion: Use explicit -p port publishing for cross-platform compatibility:

docker run --rm -it --name amp-quick-start \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -p 3000:3000 -p 9000:9000 -p 9098:9098 ... \
  ghcr.io/wso2/amp-quick-start:v0.9.0-rc1

5. Add progress indicators for long-running helm installs

Steps like Control Plane (600s timeout), Observability Plane (900s timeout), and AMP install (1800s timeout) run silently.

Suggestion: Add a spinner or periodic progress updates (e.g., pod status every 30s) to reduce user anxiety during long waits.

6. Distinguish fatal vs non-fatal waits

wait_for_pods() catches timeout errors and returns 0 with a "non-fatal" warning, meaning the script continues even if critical pods never start.

Suggestion: Critical waits (Control Plane, AMP core) should fail hard. Only optional extension waits should be non-fatal.

---

P2 — Speed / Maintainability / Verification

7. Merge observability logs install + upgrade into single install

In Step 10, observability-logs-opensearch is installed and then immediately upgraded with --reuse-values --set fluent-bit.enabled=true.

Suggestion: Pass --set fluent-bit.enabled=true in the initial install to save ~2-3 minutes.

8. Consolidate duplicate helper functions

Both install.sh and install-helpers.sh define overlapping helpers:

• install.sh: helm_install_idempotent(), wait_for_pods(), wait_for_deployments()
• install-helpers.sh: install_amp_helm_chart(), wait_for_deployment(), wait_for_statefulset()

Suggestion: Consolidate into a single helpers file.

9. Add endpoint health checks after installation

The verification section just runs kubectl get pods.

Suggestion: Verify endpoints are actually reachable:

curl -sf http://localhost:3000 > /dev/null && log_success "Console is reachable"
curl -sf http://localhost:9000/health > /dev/null && log_success "API is reachable"

10. Resume/checkpoint support

If install fails at Step 10, the user must re-run everything. While helm installs are idempotent, wait_for_* and create_plane_cert_resources calls still run.

Suggestion: Record completed steps in a checkpoint file so re-runs skip verified steps.

---

P3 — Security / Image Size

11. Slim Docker image variant

The Dockerfile installs debug tools (tcpdump, vim, htop, bind-tools) not needed for installation.

Suggestion: Consider a --slim variant or move debug tools to a separate optional layer.

12. Remove chmod 666 Docker socket fallback

In check_docker_permissions(), the fallback runs sudo chmod 666 /var/run/docker.sock. The entrypoint already handles group-based permissions properly.

Suggestion: Remove or replace with group membership approach.

13. Randomize dev credentials

The ClusterSecretStore uses hardcoded passwords (ThisIsTheOpenSearchPassword1).

Suggestion: Generate random passwords per install and/or add a clear warning that these are dev-only credentials.

---

Summary Table

Priority	#	Improvement	Impact
P0	1	Bundle remote YAML files into image	Reliability
P0	2	Resource pre-flight check	Fail-fast UX
P1	3	Single-command install option	Onboarding UX
P1	4	Fix --network=host portability	Mac/Windows support
P1	5	Add progress indicators	User experience
P1	6	Distinguish fatal vs non-fatal waits	Reliability
P2	7	Merge observability logs install+upgrade	Speed (~2-3 min saved)
P2	8	Consolidate duplicate helpers	Maintainability
P2	9	Add endpoint health checks	Verification
P2	10	Resume/checkpoint support	Re-run speed
P3	11	Slim Docker image variant	Image size
P3	12	Remove chmod 666 fallback	Security hygiene
P3	13	Randomize dev credentials	Security hygiene