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
commit 07beb2611e135b6257ca6183c7f9e303d8d7d212 Author: Shane Curcuru <[email protected]> AuthorDate: Tue Apr 28 10:50:15 2020 -0400 Various updates to reflect current docs; clarifications --- DEPLOYMENT.md | 3 ++- DEVELOPMENT.md | 22 +++++++++++++++------- DOCKER.md | 4 ++++ MACOSX.md | 4 ++++ README.md | 23 +++++++++++++++-------- SETUPMYMAC.md | 19 +++++++++++++++---- 6 files changed, 55 insertions(+), 20 deletions(-) diff --git a/DEPLOYMENT.md b/DEPLOYMENT.md index 197e17f..0f0ebac 100644 --- a/DEPLOYMENT.md +++ b/DEPLOYMENT.md @@ -22,6 +22,7 @@ Application developers may need to know where different things are configured: - **Public JSON** generation comes from various www/roster/public_*.rb scripts - **Misc server config** is executed by whimsy_server/manifests/init.pp - **LDAP** configured in whimsy-vm*.apache.org.yaml +- Various other config-like settings are in [CONFIGURE.md](./CONFIGURE.md) How Production Is Updated ---- @@ -46,7 +47,7 @@ the normal methods Apache infra uses for managing servers. Note however that management of Whimsy code and tools is a PMC responsibility. <a name="puppetnode"></a> -The **puppet definition** is contained in the following files: +The **puppet definition** is contained in the following files currently (note: Infra plans to move Puppet details in 2020). * https://github.com/apache/infrastructure-puppet/blob/deployment/data/nodes/whimsy-vm4.apache.org.yaml (Includes modules, software, vhosts, ldap realms, and httpd.conf) diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md index ee4e9fe..9e99038 100644 --- a/DEVELOPMENT.md +++ b/DEVELOPMENT.md @@ -10,16 +10,24 @@ composing mail and the like for full functionality. Contents :books: ------- -- [Architecture](#architecture-overview) +- [Preface](#preface) + - [Contents :books:](#contents-books) +- [Architecture Overview](#architecture-overview) - [Setup Whimsy Locally](#setup-whimsy-locally) -- [Running Whimsy Applications](#running-whimsy-applications-car) +- [Running Whimsy Applications :car:](#running-whimsy-applications-car) - [Advanced Configuration](#advanced-configuration) -- [Server Configuration](DEPLOYMENT.md) -- [Further Reading](#further-reading) - [Documentation Standards](#documentation-standards) -- [How To / FAQ](#how-to--faq-question) -- [Running Whimsy on Mac OSX](MACOSX.md) -- [Running Whimsy on Windows](#whimsy-on-windows) +- [How To / FAQ :question:](#how-to--faq-question) + - [How To: Create A New Whimsy CGI](#how-to-create-a-new-whimsy-cgi) + - [How To: Use New SVN or Git Directories](#how-to-use-new-svn-or-git-directories) + - [How To: Keep Your Local Environment Updated](#how-to-keep-your-local-environment-updated) + - [How To: Authenticate/Authorize Your Scripts](#how-to-authenticateauthorize-your-scripts) + - [How To: Add A New Mailing List-Id](#how-to-add-a-new-mailing-list-id) + - [How To: Test Whimsy Library methods](#how-to-test-whimsy-library-methods) + - [How To: Match Email Addresses To Committers](#how-to-match-email-addresses-to-committers) + - [How To: Have A CGI Create either HTML or JSON Output](#how-to-have-a-cgi-create-either-html-or-json-output) +- [Whimsy On Windows](#whimsy-on-windows) +- [Further Reading](#further-reading) Architecture Overview ======== diff --git a/DOCKER.md b/DOCKER.md index 857bba3..a0bb4bd 100644 --- a/DOCKER.md +++ b/DOCKER.md @@ -1,6 +1,10 @@ Docker execution instructions ============================= +:dizzy: **New!** For a simpler way to setup a Mac OSX machine, please +check out the [setupmymac script](./SETUPMYMAC.md), which automates +configuring and keeping updated a local whimsy instance with Docker. + This is experimental at this point. Do *NOT* proceed unless you are comfortable with the notion of containers, diff --git a/MACOSX.md b/MACOSX.md index 4a8c226..9e3e0f4 100644 --- a/MACOSX.md +++ b/MACOSX.md @@ -7,6 +7,10 @@ common to many tools are included here, and additional steps required for specific tools are linked at the bottom of these instructions. See Also the general DEVELOPMENT.md configuration notes. +:dizzy: **New!** For a simpler way to setup a Mac OSX machine, please +check out the [setupmymac script](./SETUPMYMAC.md), which automates +configuring and keeping updated a local whimsy instance. + Install Homebrew ---------------- diff --git a/README.md b/README.md index 29daf7e..269f963 100644 --- a/README.md +++ b/README.md @@ -7,7 +7,7 @@ Apache people, projects, and processes. Whimsy is both an [Apache PMC](https:// this codebase, and the live deployed instance of https://whimsy.apache.org/. The ASF's Whimsy instance hosts static content, repository checkouts/clones, CGI scripts, Rack -applications, tools, and cron jobs. Note: features accessing private +applications, Node.js applications, tools, and cron jobs. Note: features accessing private ASF data are restricted to committers, Members, or Officers of the ASF. Every commit pushed to master is deployed within minutes to https://whimsy.apache.org/ using @@ -20,18 +20,22 @@ How Tos and Get The Code Whimsy source code is hosted at: https://github.com/apache/whimsy.git -and now also mirrored for Apache committers at: +and mirrored for Apache committers at: https://gitbox.apache.org/repos/asf/whimsy.git * [How To Develop Whimsy Code](./DEVELOPMENT.md) * [Submit Bugs/Enhancement Requests](https://issues.apache.org/jira/browse/WHIMSY) * [Questions? See the Mailing List](https://lists.apache.org/[email protected]) - * [Deployment Instructions](./DEPLOYMENT.md) - * [Configuration Pointers](./CONFIGURE.md) + * **Setting Up For Local Development** + * Mac OSX - [Run setupmymac](./SETUPMYMAC.md) or [Follow manual steps on OSX](./MACOSX.md) + * [Linux-y setup steps](./DEVELOPMENT.md) + * [Use DOCKER to run Whimsy locally](./DOCKER.md) + * [General FAQs for developing the Whimsy Way](./DEVELOPMENT.md#how-to--faq-question) + * [Whimsy API Docs](https://whimsy.apache.org/docs/) + * [Configuration Pointers](./CONFIGURE.md) - various config settings for server or local use + * [Production Server Deployment Instructions](./DEPLOYMENT.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](./CONFIGURE.md#Dependencies) - * [Todos](./TODOS.md). How To Get Involved! =============== @@ -40,13 +44,14 @@ Since Whimsy hosts many independent tools that make finding or updating informat at the ASF simpler, there are plenty of places for Apache committers to get involved. Bugs or improvement suggestions for the many [tools available on Whimsy](https://whimsy.apache.org/committers/tools) -or [list of public datafiles](https://whimsy.apache.org/test/dataflow.cgi) are always appreciated. +or [list of public datafiles](https://whimsy.apache.org/test/dataflow.cgi) are always appreciated, +and please join us on the [public #whimsy channel on Slack](https://the-asf.slack.com/). If you have an idea for a new Whimsy tool, [email us](mailto:[email protected]?subject=Tool-Idea)! The PMC supports a rich server environment, so deploying a new tool is as simple as proposing a .cgi with a bit of Ruby code. We also have deployments of Rack and Sinatra apps, and use JavaScript and Wunderbar for most of the -UI building in most tools. The Whimsy server also supports direct access +UI building in many tools. The Whimsy server also supports direct access to Apache SVN or git repositories, making consuming data simple. The Whimsy committers are always looking for new ideas to improve processes @@ -111,6 +116,8 @@ Details for each type of deployed tool or script: * **Cron jobs** are managed by puppet. See [deployment](./DEPLOYMENT.md) for more information. + + * **NEW!** Node.js is being prototyped to improve the Board Agenda tool, stay tuned. * **Generated JSON data** files are automatically generated into the [`/public`](https://whimsy.apache.org/public/) directory, to diff --git a/SETUPMYMAC.md b/SETUPMYMAC.md index 239b416..9d246eb 100644 --- a/SETUPMYMAC.md +++ b/SETUPMYMAC.md @@ -1,7 +1,13 @@ +Automatically Setup Your Mac OSX Environment +============================================ + If you have a MacBook you undoubtedly have never used LDAP on it, have a version of the Ruby programming language installed that you also haven't used much, and the Apache httpd web server is disabled. Why not put them to use? +Simple Whimsy.Local Installation +-------------------------------- + It is easy, run the following two commands: git clone [email protected]:apache/whimsy.git @@ -14,12 +20,15 @@ Once complete, you will have a virtual host defined as `whimsy.local` that you can access in your web browser. The whole process should take about five minutes, possibly less if you already have things like `brew` installed. +Simple Whimsy.Local Installation With docker +-------------------------------------------- + Don't want to instal things on your machine? If you have Docker installed, you can use that instead, simply pass `--docker` to the `setupmymac` command above and you will have a Docker image created. This will take longer, require more disk space, runs slower, and is less convenient, but is more secure, more closely matches how the production whimsy server is configured, and can easily -be removed when done. Once complete, you start the server with the following +be removed when done. Once complete, you start the Docker server with the following commands: cd /srv/whimsy @@ -45,7 +54,8 @@ same. If you want to update more (say, to get a new version of `passenger`), there are options to do that, enter `whimsy/config/setupmymac --help` for details. Pass `--update-all` to update everything. -Sample usages: +Setupmymac Command Line Reference +--------------------------------- | Command | Description | | ------- | ----------- | @@ -61,7 +71,8 @@ Sample usages: | setupmymac --user | Set up webserver to run under your user id | | setupmymac --dry-run | show what commands would have been issued | -Notes: +Setupmymac notes +---------------- * Two long running daemons (toucher and websocket) can be started with this and these daemons will continue to run and will restart on system restart until explicitly stopped. * Cleaning `/srv/whimsy` may be needed if you change your version of Ruby or Gems. @@ -69,5 +80,5 @@ Notes: * Dry run may not be accurate as running commands may change the state of the system, affecting what subsequent commands are necessary. If you want to know what is going on under the covers with the setupmymac -scripts, visit either the [macOS](./MACOSX.md) or [Docker](./DOCKER.md) +scripts, visit either of the detailed step-by-step [macOS](./MACOSX.md) or [Docker](./DOCKER.md) instructions.
