search

andrewchilds / overcast

Orchestrate VMs from your terminal
MIT License
479 stars 36 forks source link

Potentially confusing script usage in README.md #15

Closed jeffbrl closed 10 years ago

jeffbrl commented 10 years ago

The examples in the README that include shell scripts may not be clear to new users. The examples use a relative path to scripts in the "install" directory. npm with the -g flag installs the examples in /usr/lib/node_modules/overcast/scripts. If there is a way to configure a search path for scripts, this is undocumented and /usr/lib/node_modules/overcast/scripts is not included.

If the user cuts and pastes the examples, the scripts will not be found. One of the great things about overcast is the ease in which a new user can quickly kick the tires and use standard shell scripts for provisioning. It would be a shame if new users got frustrated by not being able to execute the included shell scripts.

andrewchilds commented 10 years ago

Thanks Jeff, agreed that the README doesn't do a good job demystifying script commands like install/core or explaining the script lookup behavior. I just added an extra line yesterday at the end of the Features section to show that you can run any script file, not just bundled scripts, but maybe that's too buried. I'll take another pass at the README, maybe something like this:

Files are looked for in the current working directory, the .overcast config directory, and finally the bundled scripts directory. For example, assuming Overcast is installed in /usr/lib/node_modules:

cd /some/path
overcast run myInstance install/core
# /some/path/install/core? no.
# ~/.overcast/scripts/install/core? no.
# /usr/lib/node_modules/overcast/scripts/install/core? yes! run it!

The scripts directory doesn't exist in your install? I'm able to verify that the scripts directory is included during both local npm install overcast and global npm -g install overcast installations on OS X and Ubuntu.

$ overcast digitalocean create test.01
$ overcast run test.01 install/core install/nodejs "npm -g install overcast"
$ overcast run test.01 "ls -Al /usr/lib/node_modules/overcast"

test.01: $ ls -Al /usr/lib/node_modules/overcast
test.01: total 104
test.01: drwxr-xr-x 2 nobody root  4096 May 12 11:17 bin
test.01: drwxr-xr-x 2 nobody root  4096 May 12 11:17 fixtures
test.01: -rw-r--r-- 1 nobody root    76 May  7 23:35 .gitattributes
test.01: -rw-r--r-- 1 nobody root  1070 Apr 20 12:01 LICENSE
test.01: drwxr-xr-x 4 nobody root  4096 May 12 11:17 modules
test.01: drwxr-xr-x 9 nobody root  4096 May 12 11:17 node_modules
test.01: -rw-r--r-- 1 nobody root    79 Apr 25 17:06 .npmignore
test.01: -rw-r--r-- 1 nobody root   721 Apr 28 17:34 overcast.js
test.01: -rw-r--r-- 1 nobody root 28528 May 12 11:17 package.json
test.01: -rw-r--r-- 1 nobody root 26362 May 11 23:55 README.md
test.01: drwxr-xr-x 3 nobody root  4096 May 12 11:17 recipes
test.01: drwxr-xr-x 3 nobody root  4096 May 12 11:17 scripts
test.01: drwxr-xr-x 5 nobody root  4096 May 12 11:17 test
test.01: -rw-r--r-- 1 nobody root    38 Apr 20 12:01 .travis.yml
jeffbrl commented 10 years ago

Andrew,

Your suggested edits to the README look great.

I can't repeat the behavior I encountered with the script search path when I initially installed overcast. The /usr/lib/node_modules/overcast/scripts is populated. overcast finds the script examples in /usr/lib/node_modules/overcast/scripts as expected. I don't know what went wrong previously. I'll chalk it up to user error. :)

Thank you.