|
Size: 3352
Comment: Initial contents, copied from DomTool/Building
|
Size: 4176
Comment: mention activewebnodes
|
| Deletions are marked like this. | Additions are marked like this. |
| Line 1: | Line 1: |
| [[TableOfContents()]] | ## page was renamed from Portal/Building |
| Line 3: | Line 3: |
| = Prerequisites = | The HCoop portal runs https://members.hcoop.net and https://join.hcoop.net, generates the [[http://hcoop.net/who|member directory]], and manages the vmail user database. |
| Line 5: | Line 5: |
| == Compilers == | <<TableOfContents>> |
| Line 7: | Line 7: |
| To compile the standalone DomTool tools, you will need the [http://mlton.org/ MLton] [http://www.standardml.org/ Standard ML] compiler. It's available as Debian package "mlton". The version in Debian testing works fine, but the stable version is too old, so grab the Debian stable version of the latest release from [http://mlton.org/Download the MLton download page]. | = Build Requirements = |
| Line 9: | Line 9: |
| To use DomTool from an interactive SML REPL session, you will need a recent version of [http://www.smlnj.org/ Standard ML of New Jersey]. The SML/NJ packages in non-experimental Debian are so old that I don't bother using them, opting to install SML/NJ manually following the directions on the SML/NJ web site. Chances are you can get by just fine without support for interactive REPL use and can skip installing SML/NJ if you don't want it for some other purpose. | The portal requires [[http://git.hcoop.net/?p=hcoop/mlt.git;a=summary|mlt]] (an html templating system for smlnj) and [[http://git.hcoop.net/?p=hcoop/smlsql.git;a=summary|smlsql]] (postgresql bindings for smlnj). They are managed in the standard hcoop git repositories. The password generating tool also relies upon [[https://packages.debian.org/search?keywords=apg|apg]] (automatic password generator). |
| Line 11: | Line 11: |
| Why am I referencing two different compilers here? Well, developing with SML/NJ and building release binaries with MLton is standard practice in the SML world. SML/NJ supports separate compilation and interactive use, which are very helpful during development. MLton is a whole-program optimizing compiler that produces extremely efficient binaries, at the cost of much greater compile-time time and memory usage than SML/NJ. | The portal build utilities stored in and installed to `~hcoop/portal-tools/...` |
| Line 13: | Line 13: |
| == Libraries == | * `.../src`: checkouts of mlt and smlsql (portal build file references smlsql from here) * `.../etc`: location of default `mlt.conf`, `hcoop.header`, `hcoop.footer` * `.../bin`: `mlt` and `hcoop_header` binaries * `.../lib32`: 32-bit libraries needed by the smlsql * `.../cgi`: portal cgi binaries |
| Line 15: | Line 19: |
| You will need the OpenSSL C library with development files, available in Debian package "libssl-dev". | mlt and smlsql licensed under the LGPL version 2.1 or any later version. |
| Line 17: | Line 21: |
| == Utilities == | = Source = |
| Line 19: | Line 23: |
| If you plan to run a server (dispatcher or slave), you'll need rsync, which is available in Debian package "rsync". | The portal source lives in module `portal` of [[http://git.hcoop.net/?p=hcoop/portal.git;a=summary|our git server]]. The main check-out is in `/afs/hcoop.net/user/h/hc/hcoop/portal`. |
| Line 21: | Line 25: |
| = Getting the source code = | ''The portal licensing is currently unclear'' (but should soon be properly freely licensed -- ClintonEbadi <<DateTime(2014-02-21T15:09:17-0400)>>) |
| Line 23: | Line 27: |
| You can obtain the approximately-latest version of the DomTool source code from [http://sourceforge.net/cvs/?group_id=99567 SourceForge anonymous CVS]. The module name is `portal`. I write "approximately" because it can take about a day for the latest changes to propagate from developer CVS to anonymous CVS. I'll duplicate the directions from that Source``Forge help page and tell you that you can check out this module by running: {{{cvs -d:pserver:anonymous@hcoop.cvs.sourceforge.net:/cvsroot/hcoop login cvs -z3 -d:pserver:anonymous@hcoop.cvs.sourceforge.net:/cvsroot/hcoop co -P portal}}} |
= Building = |
| Line 27: | Line 29: |
| Just press enter when prompted for a password. | Run `become_hcoop` before modifying files in the main check-out or running any git commands that would modify it. |
| Line 29: | Line 31: |
| If you have been granted write permission to the repository and plan to commit code changes, then you'll want to check the repo out from developer CVS, like so: {{{export CVS_RSH=ssh cvs -z3 -d:ext:developername@hcoop.cvs.sourceforge.net:/cvsroot/hcoop co -P portal}}} |
There are small CGI wrappers which just run compiled binaries in `~hcoop/portal/out/`. The file `mlt.conf` contains the CGI installation path (modify this to suit your system if building locally). These wrappers are generated automatically by `mlt`. |
| Line 33: | Line 33: |
| = Building the standalone tools = | `mlt` at hcoop has been modified to build with `LD_LIBRARY_PATH` set to our lib32 directory (since squeeze does not have Multi-arch) and to set the `LD_LIBRARY_PATH` in generated wrapper scripts. This is unfortunately needed to load `libpq` until we upgrade the web servers to Wheezy. |
| Line 35: | Line 35: |
| First, change to the `portal` directory that you have checked out and run{{{ # something for adamc to fill out}}} |
== Publishing == |
| Line 38: | Line 37: |
| == Reinstalling the standalone tools == | To recompile and publish, enter the portal source directory and run `~hcoop/portal-tools/bin/mlt`: |
| Line 40: | Line 39: |
| If you want to reinstall the portal on machines that are running it already, then it is best to use a slightly modified set of instructions. | {{{ become_hcoop cd ~/portal ~portal-tools/bin/mlt }}} |
| Line 42: | Line 45: |
| = Building for SML/NJ = | == Regenerating Page Header == |
| Line 44: | Line 47: |
| After following the same procedure as above for `config.sml`, run{{{ make smlnj}}} |
`header.mlt` and `footer.mlt` are built from assorted other files. Running `make` in a check-out directory should build them. See the Makefile for how they're built. Note that `make` '''won't''' publish changes that you make onto the real web sites; you must use `mlt` for that. |
| Line 47: | Line 49: |
| followed by{{{ make install}}} |
Needed files for building: |
| Line 50: | Line 51: |
| as root. Now you should be able to run `sml` in the base `domtool2` directory and run `CM.make "src/domtool.cm";`. If you don't see any error messages, then the DomTool modules are loaded and you can start poking them. For instance, running `open Main;` should print information on the primary entry-points. | * hcoop_header is the one line script `cat $prefix/etc/hcoop.header | sed "s/TITLE/$1/g"` * hcoop_footer is the one line script `cat $prefix/etc/hcoop.footer` * You need `~hcoop/portal-tools/etc/hcoop.{header,footer}` (currently not tracked in git) == Other Applications Within the Portal == There are some subdirectories of `portal` that contain different web apps, like `app` (the source for join.hcoop.net). '''You must run `mlt` separately in any of these directories to publish changes in it'''. These include: * `app/` The Join script * `contact/` Appears to be unused (does not build) * `listaddrs/` Lists all hcoop member email addresses * `mailman/` portal subscription helper program * `passgen/` Password reset tool * `remind/` Low balance reminder * `static/` Public member directory generator * `vmailpasswd` Vmail password changing = Maintenance = == Adding Machine == To support user requests for a machine, insert a `WebNode` into the database. The Debian version should be the release name (e.g. "squeeze"). {{{ INSERT INTO WebNode (id, name, descr, debian) VALUES ((select max(id)+1 from WebNode), $HOST, $DESCRIPTION, $DEBIANVERSION); }}} If the machine should show up in the portal for members to request permissions or packages on, add it to `ActiveWebNodes`. {{{ insert into ActiveWebNode VALUES ((select id from WebNode where name = '$HOST')); }}} ---- CategorySystemAdministration |
The HCoop portal runs https://members.hcoop.net and https://join.hcoop.net, generates the member directory, and manages the vmail user database.
Contents
1. Build Requirements
The portal requires mlt (an html templating system for smlnj) and smlsql (postgresql bindings for smlnj). They are managed in the standard hcoop git repositories. The password generating tool also relies upon apg (automatic password generator).
The portal build utilities stored in and installed to ~hcoop/portal-tools/...
.../src: checkouts of mlt and smlsql (portal build file references smlsql from here)
.../etc: location of default mlt.conf, hcoop.header, hcoop.footer
.../bin: mlt and hcoop_header binaries
.../lib32: 32-bit libraries needed by the smlsql
.../cgi: portal cgi binaries
mlt and smlsql licensed under the LGPL version 2.1 or any later version.
2. Source
The portal source lives in module portal of our git server. The main check-out is in /afs/hcoop.net/user/h/hc/hcoop/portal.
The portal licensing is currently unclear (but should soon be properly freely licensed -- ClintonEbadi 2014-02-21 19:09:17)
3. Building
Run become_hcoop before modifying files in the main check-out or running any git commands that would modify it.
There are small CGI wrappers which just run compiled binaries in ~hcoop/portal/out/. The file mlt.conf contains the CGI installation path (modify this to suit your system if building locally). These wrappers are generated automatically by mlt.
mlt at hcoop has been modified to build with LD_LIBRARY_PATH set to our lib32 directory (since squeeze does not have Multi-arch) and to set the LD_LIBRARY_PATH in generated wrapper scripts. This is unfortunately needed to load libpq until we upgrade the web servers to Wheezy.
3.1. Publishing
To recompile and publish, enter the portal source directory and run ~hcoop/portal-tools/bin/mlt:
become_hcoop cd ~/portal ~portal-tools/bin/mlt
3.2. Regenerating Page Header
header.mlt and footer.mlt are built from assorted other files. Running make in a check-out directory should build them. See the Makefile for how they're built. Note that make won't publish changes that you make onto the real web sites; you must use mlt for that.
Needed files for building:
hcoop_header is the one line script cat $prefix/etc/hcoop.header | sed "s/TITLE/$1/g"
hcoop_footer is the one line script cat $prefix/etc/hcoop.footer
You need ~hcoop/portal-tools/etc/hcoop.{header,footer} (currently not tracked in git)
3.3. Other Applications Within the Portal
There are some subdirectories of portal that contain different web apps, like app (the source for join.hcoop.net). You must run mlt separately in any of these directories to publish changes in it. These include:
app/ The Join script
contact/ Appears to be unused (does not build)
listaddrs/ Lists all hcoop member email addresses
mailman/ portal subscription helper program
passgen/ Password reset tool
remind/ Low balance reminder
static/ Public member directory generator
vmailpasswd Vmail password changing
4. Maintenance
4.1. Adding Machine
To support user requests for a machine, insert a WebNode into the database. The Debian version should be the release name (e.g. "squeeze").
INSERT INTO WebNode (id, name, descr, debian)
VALUES ((select max(id)+1 from WebNode), $HOST, $DESCRIPTION, $DEBIANVERSION);If the machine should show up in the portal for members to request permissions or packages on, add it to ActiveWebNodes.
insert into ActiveWebNode VALUES ((select id from WebNode where name = '$HOST'));