Skip to content
This repository was archived by the owner on Jun 6, 2023. It is now read-only.

Commit 794d585

Browse files
sanfilipsanfilip
committed
fix current directory markdown doc links in generated docs
1 parent ffc421e commit 794d585

File tree

4 files changed

+308
-1
lines changed

4 files changed

+308
-1
lines changed

‎docs/developers.md‎

Lines changed: 75 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,75 @@
1+
# Note for developers
2+
3+
A brief guide for developers who want to contribute to this repo.
4+
5+
### Overview
6+
7+
This repo is responsible for two overall things:
8+
9+
* **Docs** covering API usage
10+
* **Code** that implements the JavaScript client and CLI
11+
12+
#### Docs
13+
14+
The generated HTML docs are located inside the `docs/` folder.
15+
16+
These generated files are checked into Git because we are using GitHub Pages for hosting. GitHub Pages automatically serves a static site for the docs when changes are pushed to the `gh-pages` branch. The `index.html` file is the root.
17+
18+
To generate the docs, we are using [JSDoc 3](http://usejsdoc.org/). To regenerate the docs afresh, run the following:
19+
20+
npm run docs
21+
22+
To configure how the docs are generated, including plugin support, see `jsdoc.json`. The template used to generate the pages is currently ([Docdash](https://github.com/clenemt/docdash)).
23+
24+
The actual documentation contents are written as source code comments in the JavaScript code within this repo. See `lib/machines/create` for one example.
25+
26+
#### Code
27+
28+
The source code in this repo handles two use cases:
29+
30+
* CLI
31+
* Programmatic usage via a JavaScript/Nodejs client
32+
33+
##### CLI
34+
35+
The CLI executable is `./bin/paperspace`. (Also note the `"bin"` field inside the `package.json`.) When this package is installed via npm as a global module, the paperspace executable becomes available on the end user's system.
36+
37+
The CLI handler code is in `cli/index.js`. This is just a very small wrapper over the JavaScript client. It mostly just handles sending command line args into the correct function.
38+
39+
##### JavaScript
40+
41+
The entry module for the JavaScript client is `lib/index.js`.
42+
43+
Implementation of the individual methods provided by the API are located in the subfolders: `lib/*/*.js`, e.g. `lib/machines/create.js`.
44+
45+
Although the JavaScript entry module loads these individual implementations into a single root interface that can be accessed with `require('paperspace-node')`, it is also set up so they can be required a la carte: `require('paperspace-node/lib/machines/create')`. Start following the code in `lib/paperspace.js` to understand how this happens.
46+
47+
###### Configuration
48+
49+
There is a small config file at `lib/config.js`. Parts of this are loaded conditionally depending on the current `NODE_ENV`. To connect to the production Paperspace API web service, the `NODE_ENV` should be `production`. The values for the production api and logs server names can be overriden with these enviroment variables:
50+
51+
PAPERSPACE_CONFIG_HOST
52+
PAPERSPACE_CONFIG_LOG_HOST
53+
54+
#### Building
55+
56+
The paperspace cli requires node 8.6.3 or later, and uses a `package.json` and `package.json-lock` file to maintain a list of required dependencies.
57+
Upon cloning the repository from github, or pulling a new version, run the following in the root of the repository to update the runtime and development dependencies:
58+
59+
npm install
60+
61+
Note: if you already have a different version installed locally or globally, you may need to run these commands first:
62+
63+
npm uninstall paperspace
64+
npm uninstall -g paperspace
65+
66+
##### Building binaries
67+
68+
The npm module `pkg` is used to build the paperspace cli binaries for linux, macos, and windows.
69+
You can build local versions of the binaries by running the following at the root of the repository:
70+
71+
pkg .
72+
73+
###### Tests
74+
75+
There aren't any tests yet, although there are a number of tests run automatically by the Paperspace API itself to verify that it is compatible with this client code.

‎docs/releasenotes.md‎

Lines changed: 118 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,118 @@
1+
# Paperspace API Release Notes
2+
3+
## Release Notes for v0.1.9
4+
5+
#### New features
6+
* New jobs machineTypes method for discovering available job machine types.
7+
8+
#### Fixes
9+
* Fix for paperspace cached api key overriding an explicit api key parameter in paperspace-node apps.
10+
* Minor doc fixes
11+
12+
## Release Notes for v0.1.8
13+
14+
#### New features
15+
* New paperspace login method for acquiring and caching api tokens from the command line
16+
* New paperspace logout method
17+
* Support for downloading job containers from private docker repositories on job create
18+
* Support for downloading job workspace from private git repositories on job create
19+
* Added paperspace --version option to check the version of the CLI tool
20+
21+
#### Fixes
22+
* Minor doc fixes
23+
24+
## Release Notes for v0.1.7
25+
26+
#### New features
27+
* New states on returned machine objects: starting, stopping, restarting, serviceready, and upgrading
28+
* Ability to wait on state serviceready when calling machines waitfor method
29+
* New property on returned machine objects: updatesPending
30+
* New releasePublicIp option on machines destroy method
31+
32+
#### Fixes
33+
* Fix for jobs completing too quickly could cause jobs create output to hang
34+
* Minor doc fixes
35+
36+
## Release Notes for v0.1.6
37+
38+
#### New Features
39+
* Pre-built binaries are now available for Windows, Mac, and Linux. These binaries enable you to run the paperspace-node command line tool without having to install Nodejs or any additional node modules.
40+
* New methods for early access to jobs. Please contact hello@paperspace.com for more information.
41+
42+
#### Breaking Changes
43+
*BREAKING CHANGE #1* (for Nodejs apps which use the paperspace-node module):
44+
45+
In previous versions (up to 0.1.5) paperspace-node methods returned an HTTP response object on success, and application code needed
46+
to dereference through the HTTP response body object to get attributes of the returned object.
47+
For example, when getting the name of a machine you would have code like this:
48+
```
49+
paperspace.machines.show({ machineId: 'ps123abc' }, function callback(err, resp) {
50+
if (err) return err;
51+
console.log(resp.body.id);
52+
});
53+
```
54+
The new convention is to return the 'body' object directly in the second callback parameter, e.g.:
55+
```
56+
paperspace.machines.show({ machineId: 'ps123abc' }, function callback(err, resp) {
57+
if (err) return err;
58+
console.log(resp.id);
59+
});
60+
```
61+
This change simplifies code that works with the returned objects, and provides better encapsulation. The command line version of the api already followed this convention.
62+
63+
*BREAKING CHANGE #2* (if building the command line app or a custom Nodejs app using the source):
64+
65+
paperspace-node now requires Nodejs 8.9.3 or later. This Node version is specified in the package.json file in the root of the repository.
66+
This change is to support stand-alone binaries of the paperspace-node command line tool that don't require a separate installation of Node.
67+
Previously Node 4.2.3 or later was required, but that version of Node will soon no longer be maintained (after April 2018). You can read more about Node's support cycle here: [Node Releases](https://github.com/nodejs/Release)
68+
69+
#### Fixes
70+
* Minor doc fixes
71+
72+
## Release Notes for v0.1.5
73+
74+
#### New features
75+
* New method: machines update
76+
* machines show method now includes last 10 events associated with the machine
77+
78+
#### Fixes
79+
* Minor doc fixes
80+
81+
## Release Notes for v0.1.4
82+
83+
#### New features
84+
* New method: machines availability
85+
86+
#### Fixes
87+
* Minor doc fixes
88+
89+
## Release Notes for v0.1.3
90+
91+
#### New features
92+
* New method: machines utilization
93+
94+
#### Fixes
95+
* Minor doc fixes
96+
* List method exact date searches now work
97+
* List method null value searches now work
98+
99+
## Release Notes for v0.1.2
100+
101+
#### New features
102+
* Support for [startup scripts](scripts.md)
103+
* scripts namespace and methods
104+
* Assign a new public ip address on machines create method
105+
* Query filters on list methods
106+
* Support for [paperspace terraform provider](https://github.com/Paperspace/paperspace-terraform)
107+
108+
#### Fixes
109+
* fix for cli false input values being converted to strings
110+
* minor doc fixes
111+
112+
#### Issues
113+
* List method exact date searches don't find matches
114+
* List method null value searches don't find matches
115+
116+
## Release Notes for v0.1.1
117+
118+
* First version

‎docs/scripts.md‎

Lines changed: 114 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,114 @@
1+
# Script Guide
2+
3+
A brief guide on the use of Paperspace startup scripts
4+
5+
### Overview
6+
7+
Paperspace can run a script automatically on the startup of a paperspace virtual machine.
8+
This feature is similar to `user_data` in other cloud provider frameworks.
9+
10+
### A note on security
11+
12+
The running of scripts automatically can be a path for malware to get access to your machine.
13+
Make sure your account and paperspace apiKey are kept secure, and review your scripts closely to make sure the software you are running is safe. Paperspace supports two-factor authentication for securing your paperspace account info. This can add an extra level of security to your account to help keep your apiKeys, scripts, and script assignments secure.
14+
15+
Paperspace stores scripts within a secure area associated with your account, and encrypts and protects scripts while they are being downloaded to machines during startup. Scripts cannot be modified once uploaded to paperspace, however a new script can be defined and assigned to a machine using your apiKey. Hence the importance of keeping your apiKey and account secure.
16+
17+
### Creating a script
18+
19+
Scripts can be defined with a string value or by uploading a file. You can optionally specify an existing machine that will run the script during the machine's next boot. See the [scripts create](https://paperspace.github.io/paperspace-node/scripts.html#.create) docs for info on creating and uploading a new script.
20+
21+
Alternatively, when creating a new machine, you can specify an existing script to be used during startup of the machine. See the [machines create](https://paperspace.github.io/paperspace-node/machines.html#.create) docs for info on specifying an existing script to be used by a new machine.
22+
23+
Note: in the Paperspace API v.1.2.0 release, if you want to change the script assigned to an existing machine you need to create a new script and assign the new script to the machine as part of the [scripts create](https://paperspace.github.io/paperspace-node/scripts.html#.create) call. (We plan to remove this limitation in a future release.)
24+
25+
### Script options
26+
27+
Scripts are designed to be run during the startup of a machine. You can optionally specify that the script should only be run once, through the [scripts create](https://paperspace.github.io/paperspace-node/scripts.html#.create) `runOnce` property. A script name and script description field are also provided. Use the script description field to make a note of the original script source file name, or other identifying info. There is also a field to set the script as `isEnabled` (which defaults to true). You can explicitly set `isEnabled` to false to test script creation without actually activating a script to run automatically.
28+
29+
Note: in the Paperspace API v.1.2.0 release, the `isEnabled` property cannot be changed after script creation. (We plan to remove this limitation in a future release. For now you can just re-create a script with `isEnabled` set to true to get the same effect.)
30+
31+
### Scripts for Linux machines
32+
33+
For Linux machines startup scripts are piped to `bash` during the machine init process, after the Linux networking stack has been initialized. Scripts are run with root privileges.
34+
35+
The machine attempts to download the script from the paperspace metadata service only once per boot. Internally the paperspace infrastructure makes sure the script can only be downloaded by the virtual machine assigned to the script.
36+
37+
If the script's `runOnce` property is set to true the script will only be piped to `bash` during the first boot of the machine. The paperspace infrastructure records whether the script was retrieved or not, and will not allow the script to be retrieved again if the `runOnce` property was set.
38+
39+
The output of the startup script on Linux gets logged to `/var/log/startup-script-output.log`. Be careful about including sensitive information in the script or its output. If you need to clean up this log file after the script runs you can schedule a cron job to do so. (In the future we may make script logging optional to enhance security.)
40+
41+
If your script is set up to run on every boot, you can download the script from a terminal window within the machine after logging in, using the following command:
42+
43+
`curl https://metadata.paperspace.com/script`
44+
45+
(This form of script download only works from within the machine assigned to the script.)
46+
47+
Note: if you created an existing machine or template prior to the Paperspace API v.1.2.0 release, and would like to take advantage of the startup script functionality, simply create an executable file with the following contents at /var/lib/cloud/scripts/per-boot/fetch-and-execute-startup-script.sh:
48+
49+
```
50+
#!/bin/sh
51+
curl --retry 10 https://metadata.paperspace.com/script | bash > /var/log/startup-script-output.log 2>&1
52+
```
53+
54+
Similarly, if you would like to disable this functionality, simply remove the script located at /var/lib/cloud/scripts/per-boot/fetch-and-execute-startup-script.sh.
55+
56+
Here is a sample startup script that will install and run docker on an ubuntu 16.04 system:
57+
58+
```
59+
if [ -f /etc/firstrun ]; then
60+
echo already ran
61+
else
62+
logger installing docker
63+
apt-get -y install apt-transport-https ca-certificates curl software-properties-common
64+
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | apt-key add -
65+
add-apt-repository "deb [arch=amd64] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable"
66+
apt-get update
67+
apt-get -y install docker-ce
68+
touch /etc/firstrun
69+
fi
70+
71+
docker run hello-world
72+
```
73+
74+
75+
### Scripts for Windows machines
76+
77+
Startup scripts for Windows are run under `powershell` by the Paperspace Service on the Windows virtual machines. The Windows local system account is used to run the script. The [samples](samples/) directory shows some example of writing startup scripts for windows, including how to set environment variables globally, and how to run batch file commands from within a powershell script. See the sample files with the `.ps1` suffix.
78+
79+
If the script's `runOnce` property is set to true the script will only be run by powershell during the first *full boot* of the machine. On Windows the first full boot occurs only after an initial reboot to configure device drivers and initialize the machine name. The on the first *full boot* the paperspace infrastructure records whether the script was retrieved or not, and will not allow the script to be retrieved again if the `runOnce` property was set.
80+
81+
On a Windows machine the script is downloaded to `C:\Windows\Temp\ps_script.ps1` and its output is logged to `C:\Windows\Temp\ps_script.log` after completion of the script. Be careful about including sensitive information in the script or its output, as these files are not automatically cleaned up. If you need to clean up these files you can schedule a Windows task to do so. (In the future we may make script logging optional to enhance security.)
82+
83+
To examine the contents of an assigned script from within the Windows virtual machine execute the following command from a `powershell` prompt:
84+
85+
`(iwr -useb https://metadata.paperspace.com/script).content`
86+
87+
(This form of script download only works from within the machine assigned to the script.)
88+
89+
### Getting metadata from within a machine
90+
91+
Paperspace supports retrieving basic metadata about a machine from within the machine itself. This is available anytime after the machine has successfully booted, and also during the execution of any assigned startup script.
92+
93+
To retrieve machine metadata from within a Linux machine run:
94+
95+
`curl https://metadata.paperspace.com/meta-data/machine`
96+
97+
98+
For a Windows machine run the `powershell` equivalent command:
99+
100+
`(iwr -useb https://metadata.paperspace.com/meta-data/machine).content`
101+
102+
The metadata available includes the user specified machine 'name', the paperspace machine 'id' and other machine specific info. The info is returned from the Paperspace metadata service as a JSON object. Here is an example JSON return value:
103+
104+
```
105+
{
106+
"id": "ps123abc",
107+
"name": "My Machine",
108+
"hostname": "ps123abc",
109+
"privateIpAddress": "10.63.0.97",
110+
"publicIpAddress": ""
111+
}
112+
```
113+
114+
On Linux or Windows you can use the [jq](https://stedolan.github.io/jq/) tool to parse JSON data. Also the latest version of `powershell` has native support for parsing JSON data.

‎package.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,7 @@
1212
"scripts": {
1313
"test": "tape ./test/*.test.js | tap-spec",
1414
"lint": "eslint .",
15-
"docs": "jsdoc ./index.js -R README.md -c jsdoc.json",
15+
"docs": "jsdoc ./index.js -R README.md -c jsdoc.json && cp releasenotes.md scripts.md developers.md docs/.",
1616
"prettier": "prettier --single-quote --trailing-comma es5 --use-tabs --write lib/**/*.js"
1717
},
1818
"engines": {

0 commit comments

Comments
 (0)