Step by step instruction on getting a full Whimsy test environment up and running on macOS. Not all steps are required for every tool, but steps 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 macOS machine, please check out the setupmymac script, which automates configuring and keeping updated a local Whimsy instance.
Homebrew is a package manager for macOS, which is used to install other tools. Follow the instructions from brew.sh. You might have to change shells if you are using csh. Bash and zsh work fine. Be sure to read the Homebrew prerequisites; you may need part(s) of Apple's XCode.
Verify minimum version installed using:
$ brew --version Homebrew 2.1.16 Homebrew/homebrew-core (git revision 274de; last commit 2019-11-12)
Update using:
$ brew update
Much of Whimsy is written in ruby. Versions of macOS prior to 10.15 (Catalina) include an outdated version of ruby.
Verify your current ruby version:
$ ruby -v ruby 2.6.3p62 (2019-04-16 revision 67580) [universal.x86_64-darwin19]
You need at least version 2.4.1 to match the currently deployed Whimsy server. If you don't see 2.3.1 or later, run hash -r and try again. If you still need to update your ruby, proceed using one of the common ruby version managers: rbenv (known to work), or rvm.
If using rbenv, install:
$ brew install rbenv $ cd /srv/whimsy && rbenv install $ rbenv init
Follow directions to ensure rbenv is setup in your shell(s), and double-check your ruby version. Note the PATH changes that rbenv init - configures; you'll need to duplicate it in your httpd conf later. To use this globally when invoked through rbenv shims, you can use rbenv global $VERSION to set that where $VERSION is the version in /srv/whimsy/.ruby-version. [TODO: describe how to set .ruby-version] To set this system-wide, you can link the specific versions of ruby and gem in rbenv to /usr/local/bin like so:
ln -s /usr/local/bin/ruby $HOME/.rbenv/versions/2.5.5/bin/ruby ln -s /usr/local/bin/gem $HOME/.rbenv/versions/2.5.5/bin/gem
Install:
$ brew install node $ npm install -g npm
Verify:
$ node -v v12.12.0 $ npm -v 6.11.3
If you don't see v6 or higher, run hash -r and try again. If you previously installed node via brew, you may need to run brew upgrade node instead.
There are a couple of scripts that require the Puppeteer node module. Installing this is optional, as the scripts are currently only used for cron jobs.
npm install -g puppeteer
To enable easy access to the module, define the following environment variable: export NODE_PATH=$(npm root -g) For example this may produce NODE_PATH="/usr/local/lib/node_modules" Note: on Ubuntu, it looks as though the default is /usr/lib/node_modules
Depending on whether or not you have a GitHub account (Apache committer setup), use GitHub Desktop or run one of the following:
git clone git@github.com:apache/whimsy.git git clone https://github.com/apache/whimsy.git git clone https://gitbox.apache.org/repos/asf/whimsy.git
The first command makes things easier if you want to push to the GitHub clone and avoid the dual authentication each time. The third command is for pushing to the asf hosted clone. This only establishes the origin. You can add other remotes via commands like:
git remote add github git@github.com:apache/whimsy.git git remote add asf https://gitbox.apache.org/repos/asf/whimsy.git
Establish a link to this repository in a known location. First instructions for macOS version < 10.15 (Mojave, High Sierra, Sierra, ...):
cd whimsy sudo mkdir /srv sudo ln -s `pwd` /srv/whimsy
Alternate instructions for macOS version >= 10.15 (Catalina):
sudo mkdir /var/whimsy echo -e 'srv\t/var/whimsy' | sudo tee -a /etc/synthetic.conf
Reboot the machine, then:
cd whimsy sudo ln -s `pwd` /srv/whimsy
Note: if you had previously created a /srv directory and it goes missing when you upgrade to Catalina, the previous contents can be found in “/Users/Shared/Relocated Items/Security”.
Install:
cd /srv/whimsy bundle install
Verify:
$ gem list $ bundler -v Bundler version 1.17.2
Notes:
sudo gem install bundler. If this doesn't work, try sudo gem install bundler -n /usr/local/bin in order to install bundler outside of /usr/binbundler's executable "bundle" conflicts with /usr/local/bin/bundle Overwrite the executable? [yN], respond with y (twice!)bundle install run for additional gems. Simply change directory to the tool you wish to develop, and run bundle install in that directory. If you want to install all of the dendencies for all of the whimsy tools, run rake update in the top whimsy directory.xcode-select --install unless you know that's already configured.Many Whimsy modules use Apache's LDAP directory. Install:
$ cd /srv/whimsy $ sudo ruby -I lib -r whimsy/asf -e "ASF::LDAP.configure"
Verify:
$ ldapsearch -x -LLL uid=rubys cn dn: uid=rubys,ou=people,dc=apache,dc=org cn: Sam Ruby
Notes:
git clone command. Alternately, provide the full path to the whimsy/lib directory on the ASF::LDAP.configure command.ldapsearch command is the standard LDAP utility on macOS.Note as an alternative to configuring and starting the version of httpd which is provided with macOS, you can install a separate version using Homebrew. Those instructions can be found in an older version of these instructions, specifically, the Install Homebrew, Install Apache httpd, Install passenger, Configure whimsy.local, Complete Apache configuration, Make whimsy.local an alias for your machine, and Optional: forward whimsy.local traffic to port 8080 steps.
Running Whimsy tools locally depends on httpd. Apple provides a copy of httpd that you can configure and start.
Install:
sudo launchctl load -w /System/Library/LaunchDaemons/org.apache.httpd.plist
Verify:
$ curl localhost <html><body><h1>It works!</h1></body></html>
Notes:
sudo lsof -i:80 may be helpful should you find that another process already has port 80 open.sudo apachectl restart is how you restart apache; launchctl itself is for controlling what processes automatically start at startup.curl gives Connection refused then try kicking httpd:sudo /usr/sbin/apachectl stopsudo /usr/sbin/httpdsudo /usr/sbin/apachectl startAH00526: Syntax error on line 20 of /private/etc/apache2/extra/httpd-mpm.conf then you may need to delete the LockFile section.First, lock down Apache so that it can only be accessed from your localhost (using either IPv4 or IPv6). As you will be configuring Apache httpd to be running with your ID, this will prevent external hackers from exploiting that code to update your filesystem and do other nasty things.
Edit /etc/apache2/httpd.conf using sudo and your favorite text editor. Locate the first line that says Require all granted. This should be around line 263 at the end of the section Directory "/Library/WebServer/Documents" or similar Replace that line with the following four lines:
<RequireAny> Require ip 127.0.0.1 Require ip ::1 </RequireAny>
Find the next occurrence of Require all granted. It should now be around line 386 in the section Directory "/Library/WebServer/CGI-Executables or similar Replace it with Require all denied.
Now go back to the top of the file and search for User. Replace the first _www with your local user id. This may be different than your ASF availid -- that‘s OK. Your local user id is the response to whoami. Replace the second _www with staff (that’s the group name).
Save your changes.
Restart Apache httpd using sudo apachectl restart.
Verify that you can continue to access the server by re-issuing the following command:
$ curl localhost <html><body><h1>It works!</h1></body></html>
Edit /etc/hosts using sudo and your favorite text editor.
Find either line that contains the word localhost and add whimsy.local to it. For example, if you chose what is likely to be the final line in the file and update it, it would look like this:
::1 localhost whimsy.local
Save your changes.
Verify that you can access the server using this new alias:
$ curl whimsy.local <html><body><h1>It works!</h1></body></html>
Follow the Installing Passenger + Apache on Mac OS X instructions, which are summaried below:.
Install:
$ brew install passenger $ brew info passenger
For the second step (brew info passenger), you will need to follow the instructions -- which essentially is to copy a few lines to a specified location, typically /etc/apache2/other/passenger.conf.
If your ruby is installed in /usr/local/bin, change the last line to
PassengerDefaultRuby /usr/local/bin/ruby
Likewise, if you used rbenv to manage your ruby install, point to that location instead. This should be $HOME/.rbenv/shims/ruby.
Optional: add PassengerUser _www and PassengerGroup _www lines if you would like your passenger applications to run under the web user.
Restart the server:
sudo apachectl restart
Verify:
Check that the server information includes ‘Phusion_Passenger’:
$ curl --head whimsy.local HTTP/1.1 200 OK Date: Wed, 13 Nov 2019 19:37:12 GMT Server: Apache/2.4.41 (Unix) Phusion_Passenger/6.0.4 Content-Location: index.html.en Vary: negotiate TCN: choice Last-Modified: Thu, 29 Aug 2019 05:05:59 GMT ETag: "2d-5913a76187bc0" Accept-Ranges: bytes Content-Length: 45 Content-Type: text/html
This may fail on High Sierra with a We cannot safely call it or ignore it in the fork() child process. Crashing instead. message in your /var/log/apache/error.log file. If so, do the following:
cp /System/Library/LaunchDaemons/org.apache.httpd.plist /Library/LaunchDaemons/
Edit /Library/LaunchDaemons/org.apache.httpd.plist and add the following to EnvironmentVariables/Dict:
<key>OBJC_DISABLE_INITIALIZE_FORK_SAFETY</key>
<string>YES</string>
Finally:
sudo launchctl unload /System/Library/LaunchDaemons/org.apache.httpd.plist sudo launchctl load -w /Library/LaunchDaemons/org.apache.httpd.plist
N.B. Because of System Integrity Protection (SIP), it's not possible to edit files under /System. So the change is made to a copy. However the original location is baked into apachectl which is also protected by SIP. This means apachectl ignores the change. A work-round for this is to create an updated copy of apachectl somewhere further up the path.
Once again, Edit /etc/apache2/httpd.conf using sudo and your favorite text editor.
Uncomment out the following lines:
LoadModule proxy_module libexec/apache2/mod_proxy.so LoadModule proxy_wstunnel_module libexec/apache2/mod_proxy_wstunnel.so LoadModule speling_module libexec/apache2/mod_speling.so LoadModule rewrite_module libexec/apache2/mod_rewrite.so LoadModule authnz_ldap_module libexec/apache2/mod_authnz_ldap.so LoadModule ldap_module libexec/apache2/mod_ldap.so LoadModule expires_module libexec/apache2/mod_expires.so LoadModule cgi_module libexec/apache2/mod_cgi.so
Add the following line:
LDAPVerifyServerCert Off
Also from the root of your whimsy git checkout, make a /srv/cache directory owned by you, and establish a symbolic link to your whimsy git clone directory:
sudo mkdir -p /srv/cache sudo chown `id -un`:`id -gn` /srv/cache sudo ln -s `pwd` /srv/whimsy
Copy whimsy vhost definition to your apache2 configuration:
sudo cp /srv/whimsy/config/whimsy.conf /private/etc/apache2/other
Note: if you reside outside North America you may wish to use the EU LDAP server by changing the references in the whimsy.conf file from ldaps://ldap-us.apache.org:636/ to ldaps://ldap-eu.apache.org:636/
Restart Apache httpd using sudo apachectl restart.
Verify:
Compare the PATH values with your local (command line) environment. Various whimsy tools will make use of a number of commands (svn, pdftk) and it is important that these tools (and the correct version of each) can be found on the PATH defined to the Apache httpd web server. If you find you need to adjust this, edit the SetEnv PATH line in /etc/apache2/other/whimsy.conf, restart the server and verify the path again.
Every mail delivery system appears to be different. Once configured, sendmail works fine on whimsy-vm6.apache.org. Others may require passwords or may throttle the rate at which emails can be sent.
The one option that appears to work for everybody is GMail.
Create a ~/.whimsy file, and add the following content:
--- :sendmail: delivery_method: smtp address: smtp.gmail.com port: 587 domain: apache.org user_name: username password: password authentication: plain enable_starttls_auto: true
Verify this works:
$ ruby whimsy/tools/testmail.rb
Note Gmail will just be used as a delivery mechanism, you can still use a different address (such as your @apache.org email address) as the from address. The domain above should match the host portion of the from address.
Should your Apache user id differ from your local user id, either specify your ASF user id as the first parameter to the testmail.rb program, or set the USER environment variable to your ASF user id before running this script.
If this fails, check your email for a response from Google. You may need to approve this application.
Information on other ways to configure sending mail can be found at DEVELOPMENT.md step 6.
Edit ~/.whimsy and add a list of checked out ASF repositories that may be referenced by whimsy tools. For example:
:svn: - /Users/clr/apache/foundation - /Users/clr/apache/documents - /Users/clr/apache/committers
Note: wildcards are permitted. The above can more economically be expressed as:
:svn: - /Users/clr/apache/*
Verify by visiting http://whimsy.local/status/svn.
If you have at least one entry that ends with a *, and the parent directory exists and is writable, this tool will be able to do a check-out for you.
Note that some checkouts (and possibly even some updates) may take longer than the Apache httpd timeout, which defaults to 60 seconds, and if so, this tool won't automatically update when the operation completes. Should that happen, simply refresh the page to see the changes.
While CGI scripts and static pages (HTML, CSS, JavaScript) can be changed and are immediately available to be served without restarting the server, Passenger/Rack applications need to be restarted to pick up changes. To make this easier, whimsy has a small tool that will watch for file system changes and restart applications that might be affected on the receipt of the next request.
To have this tool launch automatically, copy whimsy/config/toucher.plist to ‘~/Library/LaunchAgents/’ and have launchctl load it:
mkdir -p ~/Library/LaunchAgents cp /srv/whimsy/config/toucher.plist ~/Library/LaunchAgents/ launchctl load ~/Library/LaunchAgents/toucher.plist
Note: Adjust the path to ruby in toucher.plist if necessary. If you make this change after you have loaded the script, unload then reload it.
To verify that it is working, touch a file in an application, and verify that tmp/restart.txt has been updated. Example:
$ ls -l whimsy/www/board/agenda/tmp/restart.txt $ touch whimsy/www/board/agenda/README.md $ ls -l whimsy/www/board/agenda/tmp/restart.txt
A number of individual tools require additional configuration:
When things go wrong, either check whimsy_error.log and error_log in either /usr/local/var/log/httpd/ or /var/log/apache2/. The location depends on how you have installed httpd.