docs: add user quickstart guides #2281

sthaha · 2025-08-15T04:47:58Z

Add user-focused documentation including quickstart guides, installation instructions, configuration options, and troubleshooting to make it a bit accessible for users. The
documentation is clearly separated as user and developer where user guide may refer
developer docs for local setup.

Add user documentation directory with getting-started guides
Add developer getting started guide with Docker Compose setup
Restructure docs with consistent README.md naming (for default rendering on GH)
Add detailed installation guide for multiple deployment methods
Add quickstart guide with 4 different setup approaches
Add comprehensive troubleshooting guide for common issues
Add configuration guide covering all Kepler settings

The documentation provides paths for different user types from beginners to advanced, with examples and step-by-step instructions for deploying and configuring Kepler.

docs/user/configuration.md

vprashar2929 · 2025-08-17T08:30:05Z

docs/developer/getting-started.md

+
+```bash
+# Run with custom configuration
+sudo ./bin/kepler --config /path/to/your/config.yaml


Suggested change

sudo ./bin/kepler --config /path/to/your/config.yaml

sudo ./bin/kepler --config.file /path/to/your/config.yaml

vprashar2929 · 2025-08-17T08:31:04Z

docs/developer/getting-started.md

+sudo ./bin/kepler --log.level=debug --exporter.stdout
+
+# Run with fake CPU meter for development (no hardware required)
+sudo ./bin/kepler --config hack/config.yaml --fake-cpu-meter


we don't expose --fake-cpu-meter flag

vprashar2929 · 2025-08-17T08:32:44Z

docs/developer/getting-started.md

+**Development Access Points:**
+
+- Metrics: <http://localhost:28282/metrics>
+- Health: <http://localhost:28282/healthz>


We don't expose /healthz

Oh!!! I think we must but will remove it for now.

vprashar2929 · 2025-08-17T08:37:41Z

docs/developer/getting-started.md

+# Deploy development version of Kepler
+make build deploy


Should be something like:

# Deploy using latest make deploy VERSION=latest

as make deploy won't deploy the binary on cluster. For the build from source image we already cover that in Custom Image Deployment section

vprashar2929 · 2025-08-17T08:40:26Z

docs/developer/getting-started.md

+make test
+
+# Run tests with coverage
+make test-coverage


Suggested change

make test-coverage

make test coverage

vprashar2929 · 2025-08-17T08:40:58Z

docs/developer/getting-started.md

+# Run linting
+make lint
+
+# Run all checks
+make ci


We don't need these

vprashar2929 · 2025-08-17T08:44:05Z

docs/developer/getting-started.md

+# Enable debug logging
+env:
+  KEPLER_LOG_LEVEL: "debug"
+  KEPLER_FAKE_CPU_METER: "true"  # For development without RAPL
+


@sthaha This isn't correct way right?

vprashar2929 · 2025-08-17T08:46:55Z

docs/developer/getting-started.md

+
+```bash
+# Method 1: Command line flag
+sudo ./bin/kepler --config hack/config.yaml --fake-cpu-meter


Again no --fake-cpu-meter.
We can use this only:

# Method 3: Configuration file # Edit hack/config.yaml or create custom config cat > dev-config.yaml << EOF dev: fake-cpu-meter: enabled: true zones: [] # empty enables all default zones EOF sudo ./bin/kepler --config.file dev-config.yaml

vprashar2929 · 2025-08-17T08:47:13Z

docs/developer/getting-started.md

+# Method 2: Environment variable
+export KEPLER_FAKE_CPU_METER=true
+sudo ./bin/kepler --config hack/config.yaml


Not sure if this way will work 🤔

vprashar2929 · 2025-08-17T08:49:26Z

docs/developer/getting-started.md

+# Method 1: Environment variable in compose override
+cat > docker-compose.override.yml << EOF
+services:
+  kepler-dev:
+    environment:
+      - KEPLER_FAKE_CPU_METER=true
+EOF


Not sure this method will work

vprashar2929 · 2025-08-17T08:50:30Z

docs/developer/getting-started.md

+EOF
+
+# Method 2: Modify the config file directly
+sed -i '/fake-cpu-meter:/,/zones:/c\  fake-cpu-meter:\n    enabled: true\n    zones: []' kepler-dev/etc/kepler/config.yaml


Suggested change

sed -i '/fake-cpu-meter:/,/zones:/c\ fake-cpu-meter:\n enabled: true\n zones: []' kepler-dev/etc/kepler/config.yaml

sed -i '/fake-cpu-meter:/{n;s/enabled: false/enabled: true/}' kepler-dev/etc/kepler/config.yaml

vprashar2929 · 2025-08-17T08:51:30Z

docs/developer/getting-started.md

+env:
+  KEPLER_FAKE_CPU_METER: "true"


vprashar2929 · 2025-08-17T08:52:15Z

docs/developer/getting-started.md

+  fake-cpu-meter:
+    enabled: true
+    zones: [] # Empty list enables all default zones
+    # zones: ["package-0", "core", "uncore", "dram"] # Specific zones


No package-0 right?

vprashar2929 · 2025-08-17T08:53:38Z

docs/developer/getting-started.md

+#### Unit Testing
+
+```bash
+# Run tests with fake CPU meter enabled
+KEPLER_FAKE_CPU_METER=true make test
+
+# Test specific components
+KEPLER_FAKE_CPU_METER=true go test -v ./internal/device/...
+```
+
+#### Integration Testing
+
+```bash
+# Start development environment with fake meter
+make cluster-up  # Automatically enables fake meter
+
+# Verify metrics are generated
+kubectl port-forward -n kepler svc/kepler 28282:28282 &
+curl -s http://localhost:28282/metrics | grep -E "(kepler_node|kepler_container)_cpu_watts"
+```


This is not applicable, right?

vprashar2929 · 2025-08-17T08:55:56Z

docs/developer/getting-started.md

+
+# Method 2: Modify configmap before deployment
+sed -i '/fake-cpu-meter:/{n;s/enabled: false/enabled: true/}' manifests/k8s/configmap.yaml
+make build deploy


Suggested change

make build deploy

make deploy VERSION=latest

vprashar2929 · 2025-08-17T09:36:15Z

docs/developer/getting-started.md

+kubectl patch configmap kepler-config -n kepler --type merge \
+  --patch '{"data":{"config.yaml":"$(kubectl get configmap kepler-config -n kepler -o jsonpath={.data.config\\.yaml} | sed \"s/enabled: false/enabled: true/\")"}}'


This won't work. Need to update the command

vprashar2929 · 2025-08-17T09:38:31Z

docs/developer/getting-started.md

+
+```bash
+# Check logs for fake meter initialization
+kubectl logs -n kepler -l app.kubernetes.io/name=kepler | grep -i fake


Do we log that Kepler is using fake cpu meter? 🤔

vprashar2929 · 2025-08-17T09:38:54Z

docs/developer/getting-started.md

+# "Fake CPU meter enabled with zones: [package-0, core, uncore, dram]"
+
+# For local development
+sudo ./bin/kepler --config hack/config.yaml --fake-cpu-meter --log.level=debug


vprashar2929 · 2025-08-17T09:40:58Z

docs/developer/getting-started.md

+#### Data Generation Algorithm
+
+The fake CPU meter generates realistic power data by:
+
+1. **Base power calculation** - Simulates idle power consumption
+2. **CPU utilization scaling** - Increases power based on CPU usage
+3. **Workload attribution** - Distributes power across active processes
+4. **Time-based variations** - Adds realistic fluctuations over time


Is it something that Kepler will support in future?

vprashar2929 · 2025-08-17T09:41:14Z

docs/developer/getting-started.md

+}
+```
+
+## Development Environment Settings


vprashar2929 · 2025-08-17T09:41:44Z

docs/developer/getting-started.md

+# Test with fake meter
+sudo ./bin/kepler --fake-cpu-meter --log.level=debug


Refine the command

vprashar2929 · 2025-08-17T09:41:58Z

docs/developer/getting-started.md

+sudo ./bin/kepler --fake-cpu-meter --log.level=debug
+
+# Check permissions
+sudo ./bin/kepler --config hack/config.yaml --log.level=debug


Suggested change

sudo ./bin/kepler --config hack/config.yaml --log.level=debug

sudo ./bin/kepler --config.file hack/config.yaml --log.level=debug

vprashar2929 · 2025-08-17T09:42:35Z

docs/developer/getting-started.md

+
+```bash
+# Install pre-commit hooks
+make pre-commit-install


vprashar2929 · 2025-08-17T09:42:56Z

docs/developer/getting-started.md

+make pre-commit-install
+
+# Run pre-commit on all files
+make pre-commit-run-all


Suggested change

make pre-commit-run-all

pre-commit run --show-diff-on-failure --color=always --all-files

vprashar2929 · 2025-08-17T09:43:12Z

docs/developer/getting-started.md

+# Integration tests (requires cluster)
+make test-integration
+
+# E2E tests
+make test-e2e


Yet to be added

vprashar2929 · 2025-08-17T09:43:42Z

docs/developer/getting-started.md

+### Creating Release Artifacts
+
+```bash
+# Build release binaries for multiple platforms
+make build-release
+
+# Create container images for release
+make image-release VERSION=v0.10.1
+
+# Generate release documentation
+make docs-release


This section needs refinement

vprashar2929 · 2025-08-17T09:44:00Z

docs/developer/getting-started.md

+### Testing Release Candidates
+
+```bash
+# Deploy release candidate
+make deploy IMG_BASE=quay.io/sustainable_computing_io/kepler VERSION=v0.10.1-rc1
+
+# Run release validation tests
+make test-release
+```


Not sure if its applicable 🤔

vprashar2929 · 2025-08-17T12:50:45Z

docs/user/README.md

+- Multi-cluster and high availability setup
+- Security considerations


Are these relevant?

vprashar2929 · 2025-08-17T12:52:39Z

docs/user/README.md

+
+**Happy energy monitoring with Kepler!** ⚡
+
+*Last updated: 2024 | [Suggest improvements](https://github.com/sustainable-computing-io/kepler/issues/new)*


when it was trained I guess :p

vprashar2929 · 2025-08-17T13:10:02Z

@sthaha Can you also update the reference to --config to --config.file in the docs as part of this PR 🙏

sthaha · 2025-08-17T21:29:55Z

docs/developer/getting-started.md

+env:
+  KEPLER_LOG_LEVEL: "debug"
+  KEPLER_FAKE_CPU_METER: "true"  # For development without RAPL


remove these.

sthaha · 2025-08-17T21:31:02Z

docs/developer/getting-started.md

+curl -s http://localhost:28282/metrics | grep kepler_container_cpu_watts
+```
+
+### Fake CPU Meter Implementation Notes


remove this section

Add user-focused documentation including quickstart guides, installation instructions, configuration options, and troubleshooting. - Add user documentation directory with comprehensive guides - Restructure docs with consistent README.md naming - Add detailed installation guide for multiple deployment methods - Add quickstart guide with 4 different setup approaches - Add troubleshooting guide for common issues - Add configuration guide covering all Kepler settings The documentation provides clear paths for different user types from beginners to advanced users, with practical examples and step-by-step instructions for deploying and configuring Kepler. Signed-off-by: Sunil Thaha <[email protected]>

github-actions bot added the docs Documentation changes label Aug 15, 2025

sthaha changed the title ~~docs: add comprehensive user quickstart guides~~ docs: add user quickstart guides Aug 15, 2025

sthaha commented Aug 15, 2025

View reviewed changes

docs/user/configuration.md Outdated Show resolved Hide resolved

sthaha force-pushed the doc-user-quickstart branch 5 times, most recently from 38e028d to ba18b95 Compare August 15, 2025 05:39

sthaha requested a review from vprashar2929 August 15, 2025 06:38

sthaha marked this pull request as ready for review August 15, 2025 06:38

vprashar2929 reviewed Aug 17, 2025

View reviewed changes

docs/developer/getting-started.md Outdated

Comment on lines 306 to 307

env:

KEPLER_FAKE_CPU_METER: "true"

Copy link

Collaborator

vprashar2929 Aug 17, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🤔

vprashar2929 reviewed Aug 17, 2025

View reviewed changes

docs/developer/getting-started.md Outdated

}

```

## Development Environment Settings

Copy link

Collaborator

vprashar2929 Aug 17, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🤔 ?

vprashar2929 reviewed Aug 17, 2025

View reviewed changes

docs/developer/getting-started.md Outdated

```bash

# Install pre-commit hooks

make pre-commit-install

Copy link

Collaborator

vprashar2929 Aug 17, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No make

vprashar2929 reviewed Aug 17, 2025

View reviewed changes

sthaha commented Aug 17, 2025

View reviewed changes

sthaha force-pushed the doc-user-quickstart branch from ba18b95 to 5436188 Compare August 17, 2025 21:51

sthaha force-pushed the doc-user-quickstart branch from 5436188 to 2ad766f Compare August 17, 2025 21:58

	sudo ./bin/kepler --config /path/to/your/config.yaml
	sudo ./bin/kepler --config.file /path/to/your/config.yaml

	sed -i '/fake-cpu-meter:/,/zones:/c\ fake-cpu-meter:\n enabled: true\n zones: []' kepler-dev/etc/kepler/config.yaml
	sed -i '/fake-cpu-meter:/{n;s/enabled: false/enabled: true/}' kepler-dev/etc/kepler/config.yaml

		kubectl patch configmap kepler-config -n kepler --type merge \
		--patch '{"data":{"config.yaml":"$(kubectl get configmap kepler-config -n kepler -o jsonpath={.data.config\\.yaml} \| sed \"s/enabled: false/enabled: true/\")"}}'

		# Test with fake meter
		sudo ./bin/kepler --fake-cpu-meter --log.level=debug

	sudo ./bin/kepler --config hack/config.yaml --log.level=debug
	sudo ./bin/kepler --config.file hack/config.yaml --log.level=debug

	make pre-commit-run-all
	pre-commit run --show-diff-on-failure --color=always --all-files

		- Multi-cluster and high availability setup
		- Security considerations


		Happy energy monitoring with Kepler! ⚡

		Last updated: 2024 \| [Suggest improvements](https://github.com/sustainable-computing-io/kepler/issues/new)

docs: add user quickstart guides #2281

Are you sure you want to change the base?

docs: add user quickstart guides #2281

Uh oh!

Conversation

sthaha commented Aug 15, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

vprashar2929 Aug 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

vprashar2929 Aug 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

vprashar2929 commented Aug 17, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

sthaha commented Aug 15, 2025 •

edited

Loading

vprashar2929 Aug 17, 2025 •

edited

Loading

vprashar2929 Aug 17, 2025 •

edited

Loading