Difference between revisions of "AppSuite:GettingStartedWithGrunt"

(Local configuration)
 
(28 intermediate revisions by 6 users not shown)
Line 6: Line 6:
  
 
Install the default nodejs of your distribution via your favourite package/ports manager and you are good to go.
 
Install the default nodejs of your distribution via your favourite package/ports manager and you are good to go.
 +
 +
If you are having problems or your package manager does not provide at least nodejs in version 0.10.x please have a look at https://github.com/joyent/node/wiki/Installing-Node.js-via-package-manager
 +
 +
Using Debian/Ubuntu you should install nodejs-legacy to get the node executable as node is some hamradio software
  
 
=== Windows ===
 
=== Windows ===
Line 11: Line 15:
 
Head to the node.js [http://nodejs.org/ site] and download and install the latest version.
 
Head to the node.js [http://nodejs.org/ site] and download and install the latest version.
 
It is recommended to restart after the installation, as paths may not be up-to-date.
 
It is recommended to restart after the installation, as paths may not be up-to-date.
 +
 +
Please also make sure git is installed and in your PATH.
 +
 +
''This is sometimes a problem on windows, make sure to activate the option to put git into your path during msys-git installation.''
  
 
=== Mac OS X ===
 
=== Mac OS X ===
  
We strongly encourage you to use [http://brew.sh/ homebrew].
+
We strongly encourage you to use [http://brew.sh/ homebrew]. Actually, we won't support you if you don't. It's that bad.
Make sure you have checked your homebrew installation with <tt>brew doctor</tt>.
+
 
 +
Make sure you have an up-to-date homebrew installation.
 +
 
 +
<pre>
 +
brew update
 +
brew upgrade
 +
</pre>
 +
 
 +
Check your homebrew installation with <tt>brew doctor</tt> and resolve any issues and repeat this step until homebrews output says "Your system is ready to brew.".
  
Install node via <tt>brew install node</tt>.
+
<pre>
 +
brew doctor
 +
</pre>
  
Make sure you don't <tt>sudo</tt> anything related to node. If you think you have to, you are doing something wrong and are probably dealing with a broken homebrew/macports installation! If this is the case, the easiest way of resolving this is completely deleting the homebrew (and if present macports) directories and (re)installing homebrew.
+
Install node via <tt>brew install node</tt> if is not yet installed.
 +
 
 +
<pre>
 +
brew install node
 +
</pre>
 +
 
 +
Make sure you '''never <tt>sudo</tt> anything related to node or its package manager npm'''. If you think you have to, you are doing something wrong and are probably dealing with a broken homebrew/macports installation! If this is the case, the easiest way of resolving this is completely deleting the homebrew (and if present macports) directories and (re)installing homebrew.
  
 
The default system's max opened file limit in mac os x is very low (256), in order to use grunt watch, it needs to be increased.
 
The default system's max opened file limit in mac os x is very low (256), in order to use grunt watch, it needs to be increased.
  
You can either set this in your shell via <tt>ulimit -n 8192</tt> to a sensible value or you can set
+
You can either set this in your shell via <tt>ulimit -n 8192</tt> to a sensible value.
it permanently by adding
+
 
 +
<pre>
 +
ulimit -n 8192
 +
</pre>
 +
 
 +
or you can set
 +
it permanently by adding <tt>limit maxfiles 8192 20480</tt> to <tt>/etc/launchd.conf</tt>
  
<tt>limit maxfiles 8192 20480</tt>
+
<pre>
 +
echo "limit maxfiles 8192 20480" | sudo tee -a /etc/launchd.conf
 +
</pre>
  
to <tt>/etc/launchd.conf</tt>.
+
''Note that you will have to restart your system for the setting to be active.''
  
 
== Grunt & Bower ==
 
== Grunt & Bower ==
  
 
With <tt>npm install -g bower grunt-cli</tt> you can install the global npm dependencies needed for grunt and bower.
 
With <tt>npm install -g bower grunt-cli</tt> you can install the global npm dependencies needed for grunt and bower.
 +
 +
'''Mac OS X / Windows:'''
 +
<pre>
 +
npm install -g bower grunt-cli
 +
</pre>
 +
 +
'''Linux ''only'':'''
 +
You may need root privileges to install global npm modules.
 +
<pre>
 +
sudo npm install -g bower grunt-cli
 +
</pre>
 +
 +
== Cleaning development environment ==
 +
 +
Sometimes it is needed to completely wipe all old and ignored (by git) files. You can also do this using git by running <tt>git clean -ndx</tt> this will print a lot of files, but _not_ delete any. Check the list if you really want to remove these files. Then run <tt>git clean -fdx</tt> to really do the cleanup.
  
 
== Installing node dependencies for OX Appsuite Frontend development ==
 
== Installing node dependencies for OX Appsuite Frontend development ==
  
 
Change to the ui directory of your git workdirectory and run <tt>npm install</tt>.
 
Change to the ui directory of your git workdirectory and run <tt>npm install</tt>.
 +
Make sure, you have got the git binary in your path. (This is sometimes a problem on windows,
 +
make sure to activate the option to put git into your path during msys-git installation. TODO: more detail)
 +
 +
<pre>
 +
npm install
 +
</pre>
 +
 +
== Building the UI ==
 +
 +
Just run the default grunt task <tt>grunt</tt>
 +
 +
<pre>
 +
grunt
 +
</pre>
 +
 +
== Local configuration ==
 +
 +
You can override some options on your local build environment by creating the file <tt>grunt/local.conf.json</tt>. See <tt>grunt/local.conf.default.json</tt> as a template.
 +
 +
Hint: use <tt>grunt show-config:local --output grunt/local.conf.json</tt> to generate <tt>grunt/local.conf.json</tt>.
 +
 +
If you want to use the proxy function of the appserver, at least the server-variable needs to be configured.
 +
 +
<pre>
 +
{
 +
    "appserver": {
 +
        "server": "http://url.to.your.ser/appsuite/",
 +
        "verbose": ["local:error"]
 +
    }
 +
}
 +
</pre>
 +
 +
== Accessing the UI ==
 +
 +
You can run the appserver with the connect grunt task:
 +
 +
<pre>
 +
grunt connect:server:keepalive
 +
</pre>
 +
 +
or in combination with the watch task:
 +
 +
<pre>
 +
grunt connect watch
 +
</pre>
 +
 +
You can now access the ui via <tt>http://localhost:8337/appsuite/</tt>.

Latest revision as of 08:33, 3 June 2014

Getting started with grunt

Node

Linux

Install the default nodejs of your distribution via your favourite package/ports manager and you are good to go.

If you are having problems or your package manager does not provide at least nodejs in version 0.10.x please have a look at https://github.com/joyent/node/wiki/Installing-Node.js-via-package-manager

Using Debian/Ubuntu you should install nodejs-legacy to get the node executable as node is some hamradio software

Windows

Head to the node.js site and download and install the latest version. It is recommended to restart after the installation, as paths may not be up-to-date.

Please also make sure git is installed and in your PATH.

This is sometimes a problem on windows, make sure to activate the option to put git into your path during msys-git installation.

Mac OS X

We strongly encourage you to use homebrew. Actually, we won't support you if you don't. It's that bad.

Make sure you have an up-to-date homebrew installation.

brew update
brew upgrade

Check your homebrew installation with brew doctor and resolve any issues and repeat this step until homebrews output says "Your system is ready to brew.".

brew doctor

Install node via brew install node if is not yet installed.

brew install node

Make sure you never sudo anything related to node or its package manager npm. If you think you have to, you are doing something wrong and are probably dealing with a broken homebrew/macports installation! If this is the case, the easiest way of resolving this is completely deleting the homebrew (and if present macports) directories and (re)installing homebrew.

The default system's max opened file limit in mac os x is very low (256), in order to use grunt watch, it needs to be increased.

You can either set this in your shell via ulimit -n 8192 to a sensible value.

ulimit -n 8192

or you can set it permanently by adding limit maxfiles 8192 20480 to /etc/launchd.conf

echo "limit maxfiles 8192 20480" | sudo tee -a /etc/launchd.conf

Note that you will have to restart your system for the setting to be active.

Grunt & Bower

With npm install -g bower grunt-cli you can install the global npm dependencies needed for grunt and bower.

Mac OS X / Windows:

npm install -g bower grunt-cli

Linux only: You may need root privileges to install global npm modules.

sudo npm install -g bower grunt-cli

Cleaning development environment

Sometimes it is needed to completely wipe all old and ignored (by git) files. You can also do this using git by running git clean -ndx this will print a lot of files, but _not_ delete any. Check the list if you really want to remove these files. Then run git clean -fdx to really do the cleanup.

Installing node dependencies for OX Appsuite Frontend development

Change to the ui directory of your git workdirectory and run npm install. Make sure, you have got the git binary in your path. (This is sometimes a problem on windows, make sure to activate the option to put git into your path during msys-git installation. TODO: more detail)

npm install

Building the UI

Just run the default grunt task grunt

grunt

Local configuration

You can override some options on your local build environment by creating the file grunt/local.conf.json. See grunt/local.conf.default.json as a template.

Hint: use grunt show-config:local --output grunt/local.conf.json to generate grunt/local.conf.json.

If you want to use the proxy function of the appserver, at least the server-variable needs to be configured.

{
    "appserver": {
        "server": "http://url.to.your.ser/appsuite/",
        "verbose": ["local:error"]
    }
}

Accessing the UI

You can run the appserver with the connect grunt task:

grunt connect:server:keepalive

or in combination with the watch task:

grunt connect watch

You can now access the ui via http://localhost:8337/appsuite/.