whimsical-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From curc...@apache.org
Subject [whimsy] branch master updated: Update & tie together more docs
Date Tue, 04 Apr 2017 00:33:12 GMT
This is an automated email from the ASF dual-hosted git repository.

curcuru pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/whimsy.git

The following commit(s) were added to refs/heads/master by this push:
       new  206d612   Update & tie together more docs
206d612 is described below

commit 206d6123a0ab548b762723713b70e1458871e361
Author: Shane Curcuru <asf@shanecurcuru.org>
AuthorDate: Mon Apr 3 20:33:07 2017 -0400

    Update & tie together more docs
---
 DEPLOYMENT.md  |  7 +++----
 DEVELOPMENT.md | 44 ++++++++++++++++++++++++++------------------
 README.md      | 16 ++++++++++++----
 SOFTWARE.md    | 19 ++++++++++++++-----
 4 files changed, 55 insertions(+), 31 deletions(-)

diff --git a/DEPLOYMENT.md b/DEPLOYMENT.md
index a37411a..b6adaf3 100644
--- a/DEPLOYMENT.md
+++ b/DEPLOYMENT.md
@@ -1,11 +1,10 @@
 Deployment
 ==========
 
-The contents of this repository are deployed to the following VM:
-https://whimsy.apache.org/.
+The contents of this repository are automatically deployed to the https://whimsy.apache.org/
VM every 30 minutes.
 
-This VM is based on Ubuntu 14.04 and is managed by Puppet.  The puppet definition is
-contained in the following files:
+This VM runs Ubuntu 14.04 and is managed by Puppet.  The puppet definition is
+contained in the following files:<a name="puppetnode"></a>
 
  * https://github.com/apache/infrastructure-puppet/blob/deployment/data/nodes/whimsy-vm3.apache.org.yaml
 
diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md
index e9a11c9..867b1bb 100644
--- a/DEVELOPMENT.md
+++ b/DEVELOPMENT.md
@@ -5,18 +5,19 @@ Whimsy is a set of independent tools and a common library which typically
will
 need to access various ASF SVN directories and/or LDAP.  To do development and
 testing, you will need access to a machine on which you are willing to install
 libraries which do things like access LDAP, XML parsing, composing mail and
-the like.  While some tools may work on Microsoft Windows, many don't
-currently.  Alternatives include a Docker image, a custom Vagrant VM, and
-a Kitchen/Puppet managed Vagrant VM.
+the like for full functionality.  
 
-The primary advantage of using an image or a VM is isolation.  The primary
-disadvantage is that you will need to install your SVN credentials there and
-arrange to either duplicate or mount your SVN directories.
+While some tools may work on Microsoft Windows, many don't currently.  
+Alternatives include a Docker image, a custom Vagrant VM, and a Kitchen/Puppet 
+managed Vagrant VM (as the live instance does).  The primary advantage 
+of using an image or a VM is isolation.  The primary disadvantage is that 
+you will need to install your SVN credentials there and arrange to either 
+duplicate or mount needed SVN directories.
 
-Overview
+Architecture Overview
 ========
 
-This directory has two main subdirectories...
+The core Whimsy code is split into model/view, with a variety of independent tools.
 
 1. [lib/whimsy/asf](lib/whimsy/asf) contains the "model", i.e., a set of classes
    which encapsulate access
@@ -38,13 +39,18 @@ This directory has two main subdirectories...
    Directories containing Rack applications can be identified by the presence
    of a file with the name of `config.ru`.
 
-Setup
+3. [tools](tools) contains miscellaneous and testing tools.
+
+4. [config](config) contains some sample configuration data for 
+   installing various services needed.  
+
+Setup Whimsy Locally
 =====
 
 This section is for those desiring to run a whimsy tool on their own machine.
-Skip this section if you are running a Docker container or a Vagrant VM.
+[See below for deploying](#advanced-configuration) in a Docker container or a Vagrant VM.
 
-1. The ruby version needs be ruby 1.9.3 or higher.  Verify with `ruby -v`.
+1. Setup ruby 1.9.3 or higher.  Verify with `ruby -v`.
    If you use a system provided version of Ruby, you may need to prefix
    certain commands (like gem install) with `sudo`.  Alternatives to using
    the system provided version include using a Ruby version manager like
@@ -60,17 +66,17 @@ Skip this section if you are running a Docker container or a Vagrant VM.
     3. [Ruby Version Manager](https://rvm.io/)
 
 
-2. Make sure that the `whimsy-asf` and `bundler` gems are installed:
+2. Install the `whimsy-asf` and `bundler` gems:
 
   `gem install whimsy-asf bundler`
 
-3. current SVN checkouts of various repositories are made (or linked to from)
+3. SVN checkout ASF repositories into (or linked to from)
    `/srv/svn`
 
         svn co --depth=files https://svn.apache.org/repos/private/foundation
 
    You can specify an alternate location for these directories by placing
-   a configuration file named `.whimsy` in your home directory.  The format
+   a [configuration file](CONFIGURE.md) named `.whimsy` in your home directory.  The format
    for this file is YAML, and an example (be sure to include the dashed
    lines):
 
@@ -78,7 +84,7 @@ Skip this section if you are running a Docker container or a Vagrant VM.
         - /home/rubys/svn/foundation
         - /home/rubys/svn/committers
 
-4. Access to LDAP requires configuration, and a cert.
+4. Configure LDAP servers and certificates:
 
  1. The model code determines what host and port to connect to by parsing
       either `/etc/ldap/ldap.conf` or `/etc/openldap/ldap.conf` for a line that
@@ -103,7 +109,7 @@ Skip this section if you are running a Docker container or a Vagrant VM.
       Note: the certificate is needed because the ASF LDAP hosts use a
       self-signed certificate.
 
-   All these updates can be done for you with the following command:
+      **Simple way to configure LDAP is**:
 
         sudo ruby -r whimsy/asf -e "ASF::LDAP.configure"
 
@@ -116,7 +122,7 @@ Skip this section if you are running a Docker container or a Vagrant VM.
 
    See comments in that file for running the script as a standalone server.
 
-6. Configuring sending of mail (optional):
+6. Configure sending of mail (optional):
 
    Configuration of outbound mail delivery is done through the `.whimsy`
    file.  Three examples are provided below, followed by links to where
@@ -214,11 +220,13 @@ a virtual host, complete with authentication:
        description "listen for changes to whimsy applications"
        start on dbus SIGNAL=SessionNew
        exec /srv/whimsy/tools/toucher
+       
+More details about the live Whimsy instance are in [DEPLOYMENT.md](DEPLOYMENT.md)
 
 Further Reading
 ===============
 
-The [board agenda](https://github.com/rubys/whimsy-agenda#readme) application
+The [board agenda](www/board/agenda) application
 is an eample of a complete tool that makes extensive use of the library
 factoring, has a suite of test cases, and client componentization (using
 ReactJS), and provides instructions for setting up both a Docker component and
diff --git a/README.md b/README.md
index 066b965..8122833 100644
--- a/README.md
+++ b/README.md
@@ -25,6 +25,7 @@ and now also mirrored for Apache committers at:
  * [Submit Bugs](https://issues.apache.org/jira/browse/WHIMSY)
  * [Questions? Email The List](https://lists.apache.org/list.html?dev@whimsical.apache.org)
  * [Deployment Instructions](./DEPLOYMENT.md)
+ * [Configuration Pointers](./CONFIGURE.md)
  * [Monitoring How To](./www/status/README.md) - [Live Whimsy Status](https://whimsy.apache.org/status/)
  * [How To Setup on Mac OSX](./MACOSX.md)
  * [Dependency Listing](./SOFTWARE.md)
@@ -73,11 +74,9 @@ Details by content type:
    [Phusion Passenger](https://www.phusionpassenger.com/) under Apache httpd.
    Again, `Gemfile`s are used to specify dependencies.  In addition to simply
    checking the application, one line per passenger application needs to be
-   added to the deployment data:
+   added to the puppet file under 'passenger:` as seen in [DEPLOYMENT.md](./DEPLOYMENT.md#puppetnode).
 
-    https://github.com/apache/infrastructure-puppet/blob/deployment/data/nodes/whimsy-vm3.apache.org.yaml#L119
-
-   A simple rack application (two empty directories, and a one line file):
+   A sample rack application (two empty directories, and a one line file):
 
     https://github.com/apache/whimsy/tree/master/www/racktest
     https://whimsy.apache.org/racktest
@@ -90,3 +89,12 @@ Details by content type:
     
  * **Cron jobs** are managed by puppet.  See [deployment](DEPLOYMENT.md) for more
    information.
+   
+ * **Generated JSON data** files are automatically generated into 
+   the [`/public`](https://whimsy.apache.org/public/) directory, to 
+   cache freqently used data for whimsy and other applications. 
+  
+ * **Data models** for many Whimsy tools are in `lib/whimsy/asf`, and 
+   most **views** for tools are stored in `www`.  Note what Whimsy has 
+   a wide variety of sometimes unrelated tools, so not everything 
+   here uses the same models.
diff --git a/SOFTWARE.md b/SOFTWARE.md
index 12a3fbf..148dfec 100644
--- a/SOFTWARE.md
+++ b/SOFTWARE.md
@@ -1,5 +1,15 @@
-The project relies on various additional software packages.
-These are documented here for ease of reference.
+Whimsy runs atop a variety of software and configuration dependencies.
+This document is merely an overview, and is not necessarily complete.
+
+## Software Dependencies
+
+- Apache HTTP Web Server 2.x
+- Ruby 1.9.x
+- Rack
+- Phusion Passenger
+- Puppet (for our production deployment)
+
+A variety of Ruby gems:
 
 Wunderbar - HTML Generator and CGI application support
 Source: https://github.com/rubys/wunderbar
@@ -11,7 +21,6 @@ Source: https://github.com/bearded/ruby-ldap
 Gem: ruby-ldap
 Module: ldap
 
-TBC
+nokogiri - HTML parser for Ruby
 
-Bundled Gems
-json
+Other Ruby gems as in `asf.gemspec`.

-- 
To stop receiving notification emails like this one, please contact
['"commits@whimsical.apache.org" <commits@whimsical.apache.org>'].

Mime
View raw message