New Dev setup

This page details how to setup a BSD- or Linux-based machine for development of the coweb framework itself. If you just want to use the framework in your own applications, see the deployment guide in the OpenCoweb manual.

Source control

1. Install and configure the git client on your machine for GitHub access.
2. If you have read/write access to the coweb and cowebx repositories, clone them:

$ git clone git@github.com:opencoweb/coweb.git
$ cd coweb
$ git submodule init # for coweb-jsoe.git
$ git submodule update
$ cd ..
$ git clone git@github.com:opencoweb/cowebx.git

1. If you want to start contributing but don't have access to our repos yet, follow the standard practice for GitHub forking and pull requests.

JavaScript setup

1. Run our script to fetch the JS pre-reqs including RequireJS, cometD, and OpenAjax Hub.

$ cd coweb/js
$ ./setup_js.sh

1. RequireJS requires Node.js for JS code minification. On Mac, we recommend building and installing Node using HomeBrew. See the two-step HomeBrew install process here. Then run:

$ brew install node

Python setup

If you plan to make changes to the JS, we recommend setting up a Python dev environment. This setup uses the uncompressed JS source so you can refresh your web app or test page to pickup any JS changes.

1. Install Python 2.6 or 2.7 if it's not already on your system. You can check with:

$ python --version

1. Install virtualenv. We recommend using easy_install if it's available:

$ sudo easy_install virtualenv

1. Create a coweb developer virtual environment:

$ cd coweb/servers/python
$ ./setup_devenv.py ~/my/work/path

1. Activate the developer virtualenv.

$ . ~/my/work/path/bin/activate

1. If you plan to work on the apps / widgets in cowebx, you can symlink to them using our convenience script:

$ cd cowebx/cowebx-apps
$ python setup.py develop ~/my/work/path/ --force

1. Start the server in the virtualenv:

$ run_server.py --port=PORT # default is 8080

1. To deactivate the virtualenv later, run:

$ deactivate

Java setup

1. Install a Java 1.6 JDK if one isn't already on your system. You can check with:

$ javac -version

1. Install Maven 2 or 3 if it's not already installed. You can check with:

$ mvn --version

1. Use Maven to install the coweb components from your local clone.

$ cd coweb/servers/java
$ mvn install

1. If you plan to work on the apps / widgets in cowebx, you can use the Maven Jetty plug-in to deploy them easily:

$ cd cowebx
$ mvn install
$ cd cowebx-apps/$APP # APP is one of the app directory names: {launcher, coedit, cotree, ...}
$ mvn jetty:deploy-war -Djetty.port=PORT # default is 8080

NOTE: If you make changes to the JS while developing against the Java server, you need to produce a new JS minified build each time. We tried some Maven overlay trickery to make it easier to develop the JS using the Java server, but failed. We're definitely open to improvements in this area.

1. Run our RequireJS build script:

$ cd js/build
$ ./build.sh

1. Reinstall the coweb-javascript component.

$ cd servers/java/coweb-javascript
$ mvn install

1. Rebuild any JS dependent project and redeploy it.

Doc tools

1. Install the Sphinx doc tool. We recommend using easy_install if it's available:

$ sudo easy_install Sphinx

Release tools

1. Install GnuPG installed. For Mac, get GPGKeyChainAccess client from https://github.com/GPGTools/GPGKeychainAccess/downloads or http://www.gpgtools.org/projects.html.
2. Import the OpenCoweb key pair into your GPG keychain.
3. See the Release process page for the release procedure.