From 014f73a88bdb9b0ff7abae72fdffdea78b412121 Mon Sep 17 00:00:00 2001 From: Jonathan A Rees Date: Thu, 13 Jul 2017 17:46:19 -0400 Subject: [PATCH 1/6] first draft of release page --- web/release-page.html | 119 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 119 insertions(+) create mode 100644 web/release-page.html diff --git a/web/release-page.html b/web/release-page.html new file mode 100644 index 0000000..37878c1 --- /dev/null +++ b/web/release-page.html @@ -0,0 +1,119 @@ +

+probcomp-stack-0.2 +

+ +This is probcomp-stack-0.2, released on 19 July 2017. Blah blah one +sentence description of what this is blah blah jupyter notebooks blah blah. + +

+[QUESTION: what is this thing to be called, exactly, and what is its +version number? The 'alpha' documented +here is +called variously 'probcomp stack' or 'stack 0.1'.] + +

+Before you start +

+ +

+This is research software. It is certain to contain bugs. No warranty of any kind +is implied by this release. Use it at your own risk. + +

+The installation requires some level of technical ability, +specifically the ability to use the command line, and to install +prerequisite software if required. + +

Hardware requirements

+ +The notebooks in this release have successfully executed with the +following hardware configuration, with acceptable performance: + + + +

+Running with much less than this may lead to heavy load, long +delays, and/or crashes. Actual application demands vary depending on the +particulars of the data set, both its size and the data itself. + +

+We assume that you are using a workstation possessing the recommended +resources via the workstation's monitor and keyboard. +Client/server configurations are possible for this software, +and some of you will be able to figure out how to configure it in this way. +This subject beyond the scope of the present document. + + +

Software prerequisistes

+ +

+probcomp-stack-0.2 has been tested on ubuntu 16.04.2 LTS, but we +anticipate that it will run on any operating system that supports +Docker, such as most GNU/Linux variants and Mac OS X. + +

+probcomp-stack-0.2 requires Docker version 6 or later. +

+ +

+You will need an unzip program, specifically unzip, winzip, or +similar; one of these is built in to most operating systems, +and may automatically launch on download. + +

Download and installation

+ +
    +
  1. +

    Download the stack 0.2 distribution (370 MB).

    + +

    Optional: To check the integrity of the download, the SHA256 +checksum is 79183671ab39c8625c49fab668069013e763b790054707febd95bc90eaa31391.

    +
    2. + +
  2. +

    If the file has not been unzipped automatically on download, unzip it using WinZip or similar. + The result will be a single file, probcomp-stack-full-0.2.tar, + and may be placed wherever you like.

    +
    3. +
+ +

How to run

+ +
    +
  1. +

    + At the command line, navigate to the directory containing + probcomp-stack-full-0.2.tar. + Start the Docker container as follows:

    + + 
     $ docker load --input probcomp-stack-full-0.2.tar
+ $ docker run --rm --publish 127.0.0.1:8080:8080/tcp \
+     probcomp/stack-release:0.1
    +
    2. +
  2. +

    In a web browser, visit the location http://localhost:8080/

    +
    3. +
+ +

+[QUESTION: Is the docker load step really part of +installation, in that it only has to run once at install time? I +don't understand how this works. But if this is so, +the load step should be documented as part of +installation, not under 'how to run'.] + +

+[QUESTION: Is the application self-explanatory from that point that +the home web page comes up? Need to check.] + +

+In the unlikely even port 8080 is unavailable on your machine, feel free to choose a +different port. + +

Saving your work

+ +To save any changed or new notebooks, use either 'Save and checkpoint' +or 'Download' in the Jupyter notebook 'File' menu. From 4366163cdc02c072e9a9fc620b8f4bcca468297c Mon Sep 17 00:00:00 2001 From: Jonathan A Rees Date: Fri, 14 Jul 2017 14:24:39 -0400 Subject: [PATCH 2/6] second draft of release page --- web/release-page.html | 99 ++++++++++++++++++++++++++++--------------- 1 file changed, 65 insertions(+), 34 deletions(-) diff --git a/web/release-page.html b/web/release-page.html index 37878c1..0270845 100644 --- a/web/release-page.html +++ b/web/release-page.html @@ -1,22 +1,25 @@

-probcomp-stack-0.2 +probcomp-stack-0.1

-This is probcomp-stack-0.2, released on 19 July 2017. Blah blah one -sentence description of what this is blah blah jupyter notebooks blah blah. +

+[VERSION NUMBER - everything will change to 0.2, but as +of this writing only version 0.1 is present.]

-[QUESTION: what is this thing to be called, exactly, and what is its -version number? The 'alpha' documented -here is -called variously 'probcomp stack' or 'stack 0.1'.] +This is probcomp-stack-0.1, released by the +MIT Probabilistic Computing Project +on 19 July 2017. Blah blah one +sentence description of what this is blah blah +jupyter notebooks blah blah.

Before you start

-This is research software. It is certain to contain bugs. No warranty of any kind +This is research software. It is certain to contain flaws. No warranty of any kind is implied by this release. Use it at your own risk.

@@ -37,81 +40,109 @@

Hardware requirements

Running with much less than this may lead to heavy load, long delays, and/or crashes. Actual application demands vary depending on the -particulars of the data set, both its size and the data itself. +particulars of the data set, both on its size and on the data itself.

We assume that you are using a workstation possessing the recommended -resources via the workstation's monitor and keyboard. -Client/server configurations are possible for this software, -and some of you will be able to figure out how to configure it in this way. -This subject beyond the scope of the present document. +resources via the workstation's monitor and keyboard. Client/server +configurations may be possible for this software with additional +setup, but methods vary by operating system. We have not prepared +documentation for client/server configurations. + +

+[NOTE: It is JAR's feeling that very few people will have a hefty +workstation with a head; indeed I have personally never seen such a thing. They are +much more likely to have a hefty server and an ordinary laptop or desktop. This +is why I feel compelled to say something about client/server +configuration: If we do not acknowledge the possibility, then it will sound +as if a same-computer configuration is required when it is not, +and we will immediately decimate the potential user base.] + +

+[CONTINUED: Mentioning 'ssh tunnel' could be a useful hint +for some portion of the audience (not all of it), but I understand +that we're not supposed to mention ssh for some reason? There are +other access options (e.g. https) but we don't have time before Wednesday to +implement any hooks or features that would make this setup easy and +documentable. I see the two constraints "no new implementation work now" and +"do not mention ssh" as forcing the above weasel-wording.] +

Software prerequisistes

-probcomp-stack-0.2 has been tested on ubuntu 16.04.2 LTS, but we +probcomp-stack-0.1 has been tested on ubuntu 16.04.2 LTS, but we anticipate that it will run on any operating system that supports -Docker, such as most GNU/Linux variants and Mac OS X. +Docker, such as most GNU/Linux +variants, Mac OS X, and +64-bit Windows 10.

-probcomp-stack-0.2 requires Docker version 6 or later. +probcomp-stack-0.1 requires Docker version 1.6 or later.

-You will need an unzip program, specifically unzip, winzip, or -similar; one of these is built in to most operating systems, -and may automatically launch on download. +You will need an unzip program such as unzip or WinZip. One of these +is part of most operating system distributions, so it is unlikely that you will +need to install it.

Download and installation

  1. -

    Download the stack 0.2 distribution (370 MB).

    +

    Download the probcomp-stack-0.1 distribution (370 MB).

    Optional: To check the integrity of the download, the SHA256 checksum is 79183671ab39c8625c49fab668069013e763b790054707febd95bc90eaa31391.

  2. -

    If the file has not been unzipped automatically on download, unzip it using WinZip or similar. - The result will be a single file, probcomp-stack-full-0.2.tar, +

    If the file has not been unzipped automatically on download, unzip it using WinZip or unzip. + The result will be a single file, probcomp-stack-full-0.1.tar, and may be placed wherever you like.

+

[QUESTION: Why do the filenames include the word full? + Can that be removed, for the sake of consistency?... not too important.] +

How to run

  1. -

    At the command line, navigate to the directory containing - probcomp-stack-full-0.2.tar. + probcomp-stack-full-0.1.tar. +

  2. +

    Start the Docker container as follows:

    - 
     $ docker load --input probcomp-stack-full-0.2.tar
+    
     $ docker load --input probcomp-stack-full-0.1.tar
  $ docker run --rm --publish 127.0.0.1:8080:8080/tcp \
      probcomp/stack-release:0.1
  3. -

    In a web browser, visit the location http://localhost:8080/

    +

    In a web browser, visit the location http://localhost:8080/

-[QUESTION: Is the docker load step really part of -installation, in that it only has to run once at install time? I -don't understand how this works. But if this is so, +In the unlikely event that port 8080 is unavailable on your machine, feel free to choose a +different port. + +

+[QUESTION: Is the docker load step actually part of +installation, i.e. does it only have to run once at install time? I +don't understand how this works (daemon, state, etc.). But if load +need only be done once, the the load step should be documented as part of installation, not under 'how to run'.]

[QUESTION: Is the application self-explanatory from that point that -the home web page comes up? Need to check.] - -

-In the unlikely even port 8080 is unavailable on your machine, feel free to choose a -different port. +the home web page comes up? Need to check. If not, say here what +people should do once they connect to it.]

Saving your work

From 833b4b22f6c36eb6cd1e2a1bd6a32e691bbb2431 Mon Sep 17 00:00:00 2001 From: Jonathan A Rees Date: Fri, 14 Jul 2017 16:06:19 -0400 Subject: [PATCH 3/6] third draft of release page --- web/release-page.html | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/web/release-page.html b/web/release-page.html index 0270845..ab3cf2f 100644 --- a/web/release-page.html +++ b/web/release-page.html @@ -35,6 +35,7 @@

Hardware requirements

  • 60G RAM
  • 32 CPU cores +
  • 1.4 Gbyte [?] available disk space

@@ -92,7 +93,8 @@

Download and installation

  1. -

    Download the probcomp-stack-0.1 distribution (370 MB).

    +

    Download the probcomp-stack-0.1 distribution (370 MB).

    Optional: To check the integrity of the download, the SHA256 checksum is 79183671ab39c8625c49fab668069013e763b790054707febd95bc90eaa31391.

    @@ -101,7 +103,7 @@

    Download and installation

  2. If the file has not been unzipped automatically on download, unzip it using WinZip or unzip. The result will be a single file, probcomp-stack-full-0.1.tar, - and may be placed wherever you like.

    + and may be placed wherever you like. The .zip file can then be deleted.

From 4381e580c8cf6635f8bb71dce64ffe5c8f29fd01 Mon Sep 17 00:00:00 2001 From: Jonathan A Rees Date: Fri, 14 Jul 2017 18:46:29 -0400 Subject: [PATCH 4/6] incorporate some suggestions from @riastradh --- web/release-page.html | 62 ++++++++++++++++++++++++------------------- 1 file changed, 34 insertions(+), 28 deletions(-) diff --git a/web/release-page.html b/web/release-page.html index ab3cf2f..850e237 100644 --- a/web/release-page.html +++ b/web/release-page.html @@ -2,10 +2,6 @@

probcomp-stack-0.1

-

-[VERSION NUMBER - everything will change to 0.2, but as -of this writing only version 0.1 is present.] -

This is probcomp-stack-0.1, released by the sentence description of what this is blah blah jupyter notebooks blah blah. +

+

+[VERSION NUMBER NOTE - the version number will change to 0.2 before 7/19, but as +of this writing there is only a version 0.1.] +

+

Before you start

@@ -35,7 +37,7 @@

Hardware requirements

  • 60G RAM
  • 32 CPU cores -
  • 1.4 Gbyte [?] available disk space +
  • 2.5 Gbyte available disk space

@@ -46,10 +48,12 @@

Hardware requirements

We assume that you are using a workstation possessing the recommended resources via the workstation's monitor and keyboard. Client/server -configurations may be possible for this software with additional +configurations are possible for this software with additional setup, but methods vary by operating system. We have not prepared documentation for client/server configurations. + - -

Software prerequisistes

+

Software prerequisites

probcomp-stack-0.1 has been tested on ubuntu 16.04.2 LTS, but we @@ -93,22 +98,37 @@

Download and installation

  1. -

    Download Download and save the probcomp-stack-0.1 distribution (370 MB).

    -

    Optional: To check the integrity of the download, the SHA256 +

    Optional: To check the integrity of the download, verify that the SHA256 checksum is 79183671ab39c8625c49fab668069013e763b790054707febd95bc90eaa31391.

  2. -

    If the file has not been unzipped automatically on download, unzip it using WinZip or unzip. +

    If the file was not unzipped automatically on download, unzip it using WinZip or unzip. The result will be a single file, probcomp-stack-full-0.1.tar, and may be placed wherever you like. The .zip file can then be deleted.

    3. + +
  3. + At the command line, navigate to the directory containing + probcomp-stack-full-0.1.tar. +
  4. +

    + Tell docker about the probcomp-stack container as follows:

    + + 
     $ docker load --input probcomp-stack-full-0.1.tar
    +
    5. +
-

[QUESTION: Why do the filenames include the word full? - Can that be removed, for the sake of consistency?... not too important.] +

+

[IDEA: Have the user download a .tgz file instead of a .zip file, + and skip the unzip step. Docker can take in .tgz files directly so + this requires no explanation or prerequisiste. + Remove discussion of unzip from the documentation.] +

How to run

@@ -120,8 +140,7 @@

How to run

Start the Docker container as follows:

- 
 $ docker load --input probcomp-stack-full-0.1.tar
- $ docker run --rm --publish 127.0.0.1:8080:8080/tcp \
+    
 $ docker run --rm --publish 127.0.0.1:8080:8080/tcp \
      probcomp/stack-release:0.1

   
   
  • 
@@ -133,19 +152,6 @@ 
    How to run
    
 In the unlikely event that port 8080 is unavailable on your machine, feel free to choose a
 different port.
 
-
    
-[QUESTION: Is the docker load step actually part of
-installation, i.e. does it only have to run once at install time?  I
-don't understand how this works (daemon, state, etc.).  But if load
-need only be done once, the
-the load step should be documented as part of
-installation, not under 'how to run'.]
-
-
    
-[QUESTION: Is the application self-explanatory from that point that
-the home web page comes up?  Need to check.  If not, say here what
-people should do once they connect to it.]
-
 
    Saving your work
    
 
 To save any changed or new notebooks, use either 'Save and checkpoint'

From 7b959950282366b75df5d7dbb94b12c34ba9d0d7 Mon Sep 17 00:00:00 2001
From: Jonathan A Rees 
Date: Mon, 17 Jul 2017 10:55:56 -0400
Subject: [PATCH 5/6] tweaks to release-page

---
 web/release-page.html | 29 +++++++++++++++++++++++------
 1 file changed, 23 insertions(+), 6 deletions(-)

diff --git a/web/release-page.html b/web/release-page.html
index 850e237..90eda7c 100644
--- a/web/release-page.html
+++ b/web/release-page.html
@@ -9,11 +9,13 @@ 
    
 on 19 July 2017.  Blah blah one
 sentence description of what this is blah blah 
 jupyter notebooks blah blah.
+
    
 
 
    
 
    
 [VERSION NUMBER NOTE - the version number will change to 0.2 before 7/19, but as
 of this writing there is only a version 0.1.]
+
    
 
    
 
 
    
@@ -23,27 +25,32 @@ 
    
 
    
 This is research software.  It is certain to contain flaws.  No warranty of any kind
 is implied by this release.  Use it at your own risk.
+
    
 
 
    
 The installation requires some level of technical ability,
 specifically the ability to use the command line, and to install
 prerequisite software if required.
+
    
 
 
    Hardware requirements
    
 
+
    
 The notebooks in this release have successfully executed with the
 following hardware configuration, with acceptable performance:
+
    
 
 
      
-  
    •  60G RAM
-  
    •  32 CPU cores
-  
    •  2.5 Gbyte available disk space
+  
    •  60G RAM 
      • 
+  
    •  32 CPU cores 
      • 
+  
    •  2.5 Gbyte available disk space 
      • 
 
    
 
 
    
 Running with much less than this may lead to heavy load, long
 delays, and/or crashes. Actual application demands vary depending on the
 particulars of the data set, both on its size and on the data itself.
+
    
 
 
    
 We assume that you are using a workstation possessing the recommended
@@ -51,6 +58,7 @@ 
    Hardware requirements
    
 configurations are possible for this software with additional
 setup, but methods vary by operating system.  We have not prepared
 documentation for client/server configurations.
+