Public | Automated Build

Last pushed: 9 days ago
Short Description
Allow to test and build awestruct based tools.jboss.org website
Full Description

= How to build tools.jboss.org
:awestruct-layout: title-nocol
:toc:

image:https://travis-ci.org/jbosstools/jbosstools-website.png?branch=develop["Build Status", link="https://travis-ci.org/jbosstools/jbosstools-website"]

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

The simplest way to use this is to use our automatically built docker image. See https://hub.docker.com/r/jbosstools/jbosstools-website/.

   $ docker pull jbosstools/jbosstools-website
   $ git clone https://github.com/jbosstools/jbosstools-website
   $ cd jbosstools-website
   $ docker run -it --rm -p 4242:4242 -v `pwd`:/jbosstools-website jbosstools/jbosstools-website /bin/bash

WARNING: On Linux (SELinux, Fedora), you may experience permission issues inside the container on the jbosstools-website folder. Add a trailing :Z to the volume.
The command will now be:

   $ docker run -it --rm -p 4242:4242 -v `pwd`:/jbosstools-website:Z jbosstools/jbosstools-website /bin/bash

Now in the Docker you can do:

   $ cd /jbosstools-website
   $ rake clean preview

and you can browse the result at http://$DOCKER_HOST:4242.

Everything else below is if you want to run awestruct "natively".

== Prerequisites

== Installation

=== Git
Install Git to your system. http://help.github.com/[GitHub's help page] is a good starting
point. If you are looking for some tips and tricks, checkout http://in.relation.to/Bloggers/HibernateMovesToGitGitTipsAndTricks[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 http://www.ruby-lang.org/en/downloads/[options] you have.

Note: This installation varies per OS, see details on rvm.io.

For Linux/Fedora: \curl -sSL https://get.rvm.io | bash is the simplest and no root required).
Note that for 'rvm' to be activated you need to run as a login shell. When running rvm it should tell you if
you are running in a proper terminal/login.

  • Set up the isolated environment for the site

[source]

Do not run these as root.

The purpose of using rvm is to have non-root, user isolated and reproducible gem/ruby environment

During the rvm install it might ask to install system level packages, for these your user need to have sudo permissions

or you have to run those installs as root seperately and then run rvm install again as a normal user

rvm install 2.2
rvm use 2.2

rvm gemset create jbosstools-website

Note: the project has a .ruby-gemset 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.

[source]

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

cd jbosstools-website

If you see a message like this:

Gemset 'jbosstools-website' does not exist, 'rvm gemset create jbosstools-website' 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.

[source]

do not run these as root

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
  • If you see a message like Could not find a JavaScript runtime. See https://github.com/sstephenson/execjs for a list of available runtimes this means nodejs is not installed.
  • Wait for a message like [2014-01-06 11:48:01] INFO WEBrick::HTTPServer#start: pid=24294 port=4242 to appear in the console (can take a few tens of seconds)
  • Open your browser to http://localhost:4242

Any change will be automatically picked up except for changes to _partials files and changes in front-matters.

[NOTE]

You might see warnings at startup as follows:

[source]

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.

== Next steps

Using you local site, you can have a look at our link:/survivalguide.adoc[survival guide to editing this website] to get you started.

If you are viewing this page while rendered locally this would be link:/survivalguide.html[survivalguide.html] instead.

== Tips & Tricks

=== How to add a blog ?

To add a blog add a file to the link:blog[blog] folder, following the structure of
this link:blog-title.adoc.template[template]

=== How to add New and Noteworthy

To add a new and noteworthy add a dir+file to the link:documentation/whatsnew[whatsnew folder], using
one of the existing entries as a template.

Take care to ensure you have listed all the proper component and project versions and the site generation will
automatically aggregate the news for the full release.

=== How do I exclude New and Noteworthy content from Final version ?

Sometimes a N&N in earlier versions are not appropriate in the Final release.
To avoid having to manually create a full NN you can use a asciidoctor macro
to skip content based on the finalnn property being defined.

Example:

\ifndef::finalnn[]
== Really cool feature

This awesome feature is very dangerous and might be removed, but
for now it is in there.
\endif::finalnn[]

If that is in version 1.0.0.Beta1 NN then it will still be listed in 1.0.0.Beta1 but
for the 1.0.0.Final version it will not.

=== If your changes are not visible...

completely regenerate the site via:

[source]

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 :)

== Publishing/Deploying

Publishing of the site is done automatically via https://travis-ci.org/jbosstools[Travis CI] when you publish to the 'master' or 'production' branch.

image:https://travis-ci.org/jbosstools/jbosstools-website.png?branch=develop["Build Status", link="https://travis-ci.org/jbosstools/jbosstools-website"]

If Travis build successfully it will automatically publish the result to the proper site.

=== Profile parameters

In _config/site.yml various profiles are configured. The following table documents some of the important parameters.

|===
|Name | Values | Description

|showwip
|boolean
|if true a banner will be shown on top indicating it is a work in progress.

|===

== License

Sample code available on this website is released under EPL.

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 https://github.com/jbossorg/bootstrap-community[JBoss Community Bootstrap].
This README.adoc was based on
https://github.com/hibernate/hibernate.org/blob/hibernate-rebase-of-jbossorg/README.adoc[hibernate.org
README.adoc]

Docker Pull Command
Owner
jbosstools
Source Repository

Comments (0)