This is an automated email from the ASF dual-hosted git repository.
sebb pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/whimsy.git
commit a98c448ff302dd730c62a17814ee7a5cf9765c02
Author: Sebb <s...@apache.org>
AuthorDate: Sat Jan 6 17:04:33 2024 +0000
Update docs
---
DOCKER.md | 27 ++++++++++++++++-----------
config/bash_aliases .template | 26 ++++++++++++++++++++++++++
config/whimsy.template | 31 +++++++++++++++++++++++++++++++
3 files changed, 73 insertions(+), 11 deletions(-)
diff --git a/DOCKER.md b/DOCKER.md
index 86b57373..f2401613 100644
--- a/DOCKER.md
+++ b/DOCKER.md
@@ -57,16 +57,18 @@ Installation instructions
host file system outside of your home directory as those files will not
be visible to the container.
* `cd` into that directory
-* `echo ":root: ." >.whimsy`
-* `echo ":whimsy_dn: dn-to-be-used-for-whimsy LDAP access" >>.whimsy`
-* `echo ":httpd_dn: dn-to-be-used-for-httpd LDAP access" >>.whimsy` # defaults
to whimsy_dn
* `git clone g...@github.com:apache/whimsy.git` OR
* `git clone https://github.com/apache/whimsy.git` (whichever works best for
you)
-* `create .bash_aliases` if required - this will be picked up by the root user
+* `cp whimsy/config/whimsy.template .whimsy`
+* edit the `.whimsy` file as per its comments
+* Create the file `.bash_aliases` if required - this will be picked up by the
root user
+There is a sample template `whimsy/config/bash_aliases.template` to get you
started
+* `mkdir apache2_logs` if required - this will be used for the server logs
(makes it easier to review them)
* `cd whimsy`
* Start Docker if necessary: `$ open /Applications/Docker.app`
* `rake docker:update` # this runs docker:build and updates any Gems
-* `rake svn:update git:pull` # This updates the Whimsy data sources
+* If you are using a local copy of SVN, you will need to start the server and
run `rake svn:update` from a shell
+* Otherwise you can run `rake svn:update` externally
* `rake docker:up` # This prompts for LDAP Bind password
* visit `http://localhost:1999/` in your favorite browser
@@ -87,10 +89,13 @@ This should be re-run if you update any of the resources
used for the build,
e.g. files in docker-config and the Dockerfile
-The `rake svn:update git:pull` step updates the SVN and Git repos used by
Whimsy.
+The `rake svn:update` step updates the SVN repos used by Whimsy.
The container does not automatically update these (unlike the live
installation),
so the step should be performed as necessary before starting the container to
ensure the
data is sufficiently up-to-date. This requires karma to fetch some of the
files.
+If using a local copy of the SVN repos, `rake svn:update` must be run from the
container.
+It does not need any special karma.
+
This should be enough to get most of Whimsy working. It is not
known yet what functions work and what functions do not.
@@ -111,7 +116,7 @@ Note on Repositories
--------------------
If you don't want to check out all of the repositories, omit the
-`rake docker:update svn:update git:pull`, and only checkout/clone
+`rake docker:update svn:update`, and only checkout/clone
the repositories that you need. You can find the complete list in
[repository.yml](./repository.yml).
@@ -125,6 +130,8 @@ To correct this, do the following:
cd /srv/svn
svn co https://svn.apache.org/repos/private/foundation/board
foundation_board
+Adjust as necessary if using local (private) SVN repos
+
Testing email
-------------
@@ -134,21 +141,19 @@ The following command can be used to run a dummy smtp
server on port 1025:
It can be tested with:
`tools/testmail.rb <userid>`
-[Note that Whimsy does not generally send emails unless it detects that it is
the active server.]
-
Known not to work (ToDos)
-------------------------
* Board agenda web socket (used to communicate updates from the server to
browsers)
* Automatic restarting of passenger based tools when source code changes are
- made.
+ made. Just restart the server instead: `apachectl restart`.
Uninstallation procedures
-------------------------
* Exit out of any running containers
-* Remove the entire directory created as step 1 of the installation
+* Remove the entire directory structure created as step 1 of the installation
instructions.
* `docker image rm whimsy-web`
* `docker image prune -f`
diff --git a/config/bash_aliases .template b/config/bash_aliases .template
new file mode 100644
index 00000000..27d0c090
--- /dev/null
+++ b/config/bash_aliases .template
@@ -0,0 +1,26 @@
+# Template file for .bash_aliases
+# Needs to be present in the parent directory of the workspace
+
+# Note: logs can be stored on the host; create the directory apache2_logs
+alias logs='ls -lrt /var/log/apache2'
+alias cdl='cd /var/log/apache2'
+alias tfe='tail -f /var/log/apache2/error.log'
+alias tfwe='tail -f /var/log/apache2/whimsy_error.log'
+
+# IRB access
+alias wrb='irb -I /srv/whimsy/lib -r whimsy/asf'
+alias wrbmf='irb -I /srv/whimsy/lib -r whimsy/asf -r whimsy/asf/member-files'
+
+if [ ! -r $HOME/.irbrc ]
+then
+ echo Creating $HOME/.irbrc
+ cat >$HOME/.irbrc <<EOD
+require 'pp'
+# Set up Wunderbar logging if running wrb
+if \$LOAD_PATH.include?("/srv/whimsy/lib") # wrb?
+ puts "#{__FILE__} - setting log_level=info"
+ require 'wunderbar' # it has not been loaded yet
+ Wunderbar.log_level="info"
+end
+EOD
+fi
diff --git a/config/whimsy.template b/config/whimsy.template
new file mode 100644
index 00000000..e9f01848
--- /dev/null
+++ b/config/whimsy.template
@@ -0,0 +1,31 @@
+# Template file for .whimsy
+# Needs to be present in the parent directory of the workspace
+---
+:root: .
+
+# To use a local SVN, set up the repositories at the location in whimsy.conf
+# This is at /srv/REPO in the container (see SVNPath defines), and is at
'root'/REPOS on the host
+# Then enable the following line to define SVN for Whimsy
+#:svn_base: http://localhost/repos/
+# WARNING: the SVN checkouts will need to link to the above URL, which is only
valid in the container
+# In order to populate the repos, start the container and run 'rake
svn:update' in a shell.
+
+# To allow the code to send emails locally, create an SMTP server, e.g as
follows in a shell login:
+# python -m smtpd -n -c DebuggingServer localhost:1025
+# and enable the following lines:
+# :sendmail:
+# address: localhost
+# port: 1025
+# delivery_method: smtp
+
+# The default LDAPs to be used
+# :ldap:
+# - ldaps://ldap-eu.apache.org:636
+# Beware: this is the live LDAP.
+# INFRA may be able to grant access to a test LDAP, in which case define it
here
+
+# N.B. whimsy_dn must be defined; this specifies the LDAP role to be used by
Whimsy
+# Optionally define httpd_dn in case you want to use a different role for
httpd authentication
+
+# :whimsy_dn: cn=<rolename>,ou=users,ou=services,dc=apache,dc=org
+# :httpd_dn: cn=<rolename>,ou=users,ou=services,dc=apache,dc=org
