You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@whimsical.apache.org by cu...@apache.org on 2017/04/04 00:33:12 UTC
[whimsy] branch master updated: Update & tie together more docs
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 <as...@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" <co...@whimsical.apache.org>'].