How to build tools.jboss.org

Table of Contents

• Prerequisites
• Installation
  • Git
  • Ruby (via RVM)
  • Get the source
  • Install Ruby dependencies
• Serve the site locally
• guard and livereload
• Next steps
• Tips & Tricks
  • If your changes are not visible…​
  • If serving the site is slow…​
• License
• Acknowledgements

A bit of Git, a bit of Ruby and you will get your local tools.jboss.org served.

Prerequisites

• Get Git

• Get Ruby 1.9.3 (part of the RVM install if you follow that path - see below)

• Get RubyGems 1.3.6 or above

• Get GNU Wget 1.14

• If on Mac OS, get XCode (needed for native gems)

Installation

Git

Install Git to your system. GitHub’s help page is a good starting point. If you are looking for some tips and tricks, checkout Emmanuel’s blog.

Ruby (via RVM)

Ruby like many other platforms has its dependency hell. We do recommend you use RVM to isolate your ruby runtimes as well as dependencies (gems). The RVM steps are optional though. If you are not going to use RVM have a look at the different installations options you have.

• Install RVM.

• Set up the isolated environment for the site

rvm install 1.9.3
rvm use 1.9.3
rvm gemset create jbosstools

Note: the project has a .rvmrc file which will be used by rvm when you enter the jbosstools-website directory. This file will assume you have the above installed.

Get the source

Next, let’s retrieve the website.

git clone https://github.com/jbosstools/jbosstools-website
cd jbosstools-website

If you see a message like this:

Gemset 'jbosstools' does not exist, 'rvm gemset create jbosstools' first, or append '--create'.

Then it is because you have rvm installed and forgot to run the rvm setup above.

Install Ruby dependencies

This next step might take some time - it is installing all the required dependencies.

gem install bundler
bundle install

Note that if someone updates Awestruct or any dependent gem via the Gemfile dependency management, you need to rerun bundle install.

Serve the site locally

• Run rake preview

• Open your browser to http://localhost:4242

Any change will be automatically picked up except for changes to _partials files.

Note

You might see warnings at startup like WARNING: Missing required dependency to activate optional built-in extension coffeescripttransform.rb cannot load such file -- coffee-script Using profile: development Generating site: http://localhost:4242 Skipping files cache update. CodeRay::Scanners could not load plugin :bash; falling back to :text CodeRay::Scanners could not load plugin :bash; falling back to :text CodeRay::Scanners could not load plugin :bash; falling back to :text CodeRay::Scanners could not load plugin :bash; falling back to :text CodeRay::Scanners could not load plugin :bash; falling back to :text CodeRay::Scanners could not load plugin :bash; falling back to :text [Listen warning]: The blocking parameter of Listen::Listener#start is deprecated. Please use Listen::Adapter#start for a non-blocking listener and Listen::Listener#start! for a blocking one. That’s ok, it’s not your fault ;) It’s related to some Awestruct limitations.

guard and livereload

You can install the livereload extension to get instant refresh in your browser when pages are regenerated by running guard.

The dependencies should already be installed by the Gemfile thus you just need to start guard:

guard start

Install the LiveReload extension in your browser and click on the button next to the Location to activate the extension.

Chrome users can install the v.2.0.9 extension from the Chrome Marketplace.

Firefox users should use v. 2.0.9 or newer of the LiveReload extension available from here. If you hit an issue where the browser disconnects just after it has connected, which means the server cannot push refresh commands to it, you are using an old plugin and should update it.

Next steps

Using you local site, you can have a look at our survival guide to editing this website to get you started.

Tips & Tricks

If your changes are not visible…​

completely regenerate the site via:

rake clean[all] preview

If serving the site is slow…​

On Linux, serving the file may be atrociously slow (something to do with WEBRick).

Use the following alternative:

• Go in your ~/jbosstools-website directory.

• Run awestruct --auto -P development

• In parallel, go to the ~/jbosstools-website/_site directory

• Run python -m SimpleHTTPServer 4242

You should be back to millisecond serving :)

License

The content of this repository is released under TBD. Sample code available on this website is released under TBD.

By submitting a "pull request" or otherwise contributing to this repository, you agree to license your contribution under the respective licenses mentioned above.

Acknowledgements

This website uses JBoss Community Bootstrap. This README.adoc was based on hibernate.org README.adoc