Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Improve documentation #230

Merged
merged 3 commits into from
Jan 9, 2025
Merged

Improve documentation #230

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
50767d1
Fix append public key and minimum java version
diegolovison Jan 7, 2025
f9ea7ae
Remove duplicated Prerequisites section
diegolovison Jan 7, 2025
f1903fc
Update run documentation for clarity and ease of following prerequisites
diegolovison Jan 7, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
87 changes: 35 additions & 52 deletions docs/tutorial/helloworld.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,42 +1,25 @@
= qDup Hello World

== Prerequisites
qDup has 3 requirements:

1. linux operating system
2. java 11 where you run qdup
3. ssh running on the target computer

you can verify the prerequisites with two commands:
```
#> java -version
openjdk version "11.0.10" 2021-01-19
OpenJDK Runtime Environment AdoptOpenJDK (build 11.0.10+9)
OpenJDK 64-Bit Server VM AdoptOpenJDK (build 11.0.10+9, mixed mode)
```
```
#> ssh testuser@localhost
Last login: Thu Sep 15 10:01:00 2022 from 192.168.0.1
```
The `testuser` example username should be replaced with the output of `whoami`.

If you get a `command not found` or the prompted for a `Password:` when running `ssh` then please refer to the link:./prerequisites.adoc[prerequisites]
qDup connects to computers through ssh. You need to have a computer that will accept ssh connections. You can setup ssh on your own computer by following the steps in the link:./prerequisites.adoc[prerequisites]

== qDup jar
qDup is distributed as an executable jar (Java's version of a zip). Download the latest `uber` jar from link:https://github.com/Hyperfoil/qDup/releases/latest[github]

== YAML script
qDup scripts use are saved as yaml. We can explore the yaml structure in later tutorials.
Use the following bash command to create a test yaml file.

The `$USER` variable will be replaced by the output of `echo $USER`. You can check by inspecting the yaml file content.
```
#> cat > helloworld.yaml << 'EOF'
#> cat <<EOF > helloworld.yaml
scripts:
tryme:
- sh: whoami
- sh: date
- sh: echo ${{message}}
hosts:
server: testuser@localhost
server: $USER@localhost
roles:
test:
hosts:
Expand All @@ -49,48 +32,48 @@ EOF
```

== Run qDup

If you followed the previous link:./prerequisites.adoc[prerequisites] tutorial and create a new identify file name `qdup` then we need to tell qDup to use that instead of the default identify file.
```
#> java -jar qDup-0.6.15-uber.jar helloworld.yaml
22:02:13.744 Running qDup version 0.6.15
22:02:13.745 output path = /tmp/20221005_220213
22:02:13.912 json server listening at wreicher.users.ipa.redhat.com:31337
22:02:14.640 starting 1 scripts
22:02:14.648 tryme:14@localhost:script-cmd: tryme
22:02:14.650 tryme:14@localhost:tryme
22:02:15.079 tryme:14@localhost:whoami
#> java -jar qDup-0.8.5-uber.jar -i ~/.ssh/qdup helloworld.yaml

13:45:49.696 Running qDup version 0.8.5 @ d66bc67
13:45:49.697 output path = /tmp/20250107_134548
13:45:49.697 shell exit code checks enabled
13:45:49.822 json server listening at user-host:31337
13:45:51.474 starting 1 scripts
13:45:51.477 tryme:20@localhost: script-cmd: tryme
13:45:51.478 tryme:20@localhost: tryme
13:45:51.891 tryme:20@localhost: whoami
testuser
22:02:15.514 tryme:14@localhost:date
Wed 05 Oct 2022 10:02:15 PM EDT
22:02:15.971 tryme:14@localhost:echo Hello, qDup!
13:45:52.304 tryme:20@localhost: date
Tue Jan 7 01:45:51 PM -03 2025
13:45:52.717 tryme:20@localhost: echo Hello, qDup!
Hello, qDup!
22:02:15.994 run-1665021733656 -> /tmp/20221005_220213.queueCleanupScripts
Finished in 02.046 at /tmp/20221005_220213
```
Finished in 02.885 at /tmp/20250107_134548

If you followed the previous link:./prerequisites.adoc[prerequisites] tutorial and create a new identify file name `id_qdup` then we need to tell qDup to use that instead of the default identify file.
```
#> java -jar qDup-0.6.15-uber.jar -i ~/.ssh/id_qdup helloworld.yaml
```

== Changing the greeting

The `- sh: echo ${{message}}` command uses pattern substitution. qDup uses the `states` value for `message` but we can change that when running qDup by passing in a different value for `message` through the command line.
```
#> java -jar qDup-0.6.15-uber.jar -S message="howdy, qDup" helloworld.yaml
22:03:16.321 Running qDup version 0.6.15
22:03:16.322 output path = /tmp/20221005_220316
22:03:16.483 json server listening at wreicher.users.ipa.redhat.com:31337
22:03:17.233 starting 1 scripts
22:03:17.248 tryme:14@localhost:script-cmd: tryme
22:03:17.253 tryme:14@localhost:tryme
22:03:17.684 tryme:14@localhost:whoami
#> java -jar qDup-0.8.5-uber.jar -i ~/.ssh/qdup -S message="howdy, qDup" helloworld.yaml

13:48:21.077 Running qDup version 0.8.5 @ d66bc67
13:48:21.078 output path = /tmp/20250107_134819
13:48:21.078 shell exit code checks enabled
13:48:21.198 json server listening at user-host:31337
13:48:22.308 starting 1 scripts
13:48:22.311 tryme:20@localhost: script-cmd: tryme
13:48:22.312 tryme:20@localhost: tryme
13:48:22.726 tryme:20@localhost: whoami
testuser
22:03:18.102 tryme:14@localhost:date
Wed 05 Oct 2022 10:03:17 PM EDT
22:03:18.527 tryme:14@localhost:echo howdy, qDup
13:48:23.139 tryme:20@localhost: date
Tue Jan 7 01:48:22 PM -03 2025
13:48:23.554 tryme:20@localhost: echo howdy, qDup
howdy, qDup
22:03:18.569 run-1665021796246 -> /tmp/20221005_220316.queueCleanupScripts
Finished in 02.050 at /tmp/20221005_220316
Finished in 02.344 at /tmp/20250107_134819

```
The `-S` argument overrides the value in yaml. We can store a default in yaml then use the command line to customize the script execution.
Expand Down
13 changes: 6 additions & 7 deletions docs/tutorial/prerequisites.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -61,9 +61,8 @@ If the previous `ls -al ~/.ssh` did not include a file named `authorized_keys` t
#> chmod g-w ~/.ssh/authorized_keys
```
Add the new `qdup` key to the list of keys.
Remember to substitute your user's name from `whoami` for the `testuser` below.
```
#> cat qdup.pub | ssh testuser@localhost 'cat >> ~/.ssh/authorized_keys'
#> (cat ~/.ssh/qdup.pub; echo) >> ~/.ssh/authorized_keys
```
The `ssh` command should work with your user's name (from `whoami`) and the `localhost` computer name without being asked for a password
```
Expand All @@ -74,14 +73,14 @@ Last login: Thu Sep 15 10:01:00 2022 from 192.168.0.1

== Java
qDup is distributed as a java executable jar (java's version of a zip file).
You need to have java 11 or higher installed to run qDup. We can check for java
You need to have Java 17 or higher installed to run qDup. We can check for java
```
#> java -version
openjdk version "11.0.10" 2021-01-19
OpenJDK Runtime Environment AdoptOpenJDK (build 11.0.10+9)
OpenJDK 64-Bit Server VM AdoptOpenJDK (build 11.0.10+9, mixed mode)
openjdk version "17.0.13" 2024-10-15
OpenJDK Runtime Environment Temurin-17.0.13+11 (build 17.0.13+11)
OpenJDK 64-Bit Server VM Temurin-17.0.13+11 (build 17.0.13+11, mixed mode, sharing)
```
if you see `bash: java: command not found...` then install [Java 11](https://adoptopenjdk.net/) or higher.
if you see `bash: java: command not found...` then install [Java 17](https://adoptopenjdk.net/) or higher.

== Next

Expand Down
Loading