Liukko-POC

Main goals of this POC

• Separate back- and frontend development
  • Basically backend side will be installed to some *nix machine
  • Frontend side of this POC is just for example
  • Implementation to _your_ own frontend application should be fairly easy
• Simple file(s) watcher to send socket messages about file updates
  • Watched files can be configured to backend side
  • Updates of files are send to clients via WebSockets
  • User can define which files to "listen"
  • Simple file content update, to demonstrate actual changes of files
• Frontend - backend communication is authenticated by JWT
  • CORS support
  • All data access routes are secured via sails policies
  • Actual user authentication is done in the backend

Why?

Just for fun and to learn how to make this kind of stuff work with node.js.

Directory structure

backend  = Sails.js server, just API nothing else
frontend = Slush-angular, just frontend side

Backend

For backend side this POC uses Sails.js (imho awesome). See more info at https://github.com/balderdashy/sails.

Frontend

Boilerplate uses slush-angular for frontend (AngularJS using Google Angular App Structure Recommendations). See more info at https://github.com/slushjs/slush-angular This library is awesome to distribute frontend.

Used libraries, guides, etc.

• Sails.js, http://sailsjs.org/
• slush-angular, https://github.com/slushjs/slush-angular
• AngularJS, https://angularjs.org/
• Bootstrap, http://getbootstrap.com/
• Techniques for authentication in AngularJS applications, https://medium.com/opinionated-angularjs/7bbf0346acec
• Json Web Tokens, http://angular-tips.com/blog/2014/05/json-web-tokens-examples/

Installation

First of all you have to install npm and node.js to your box. Installation instructions can be found there http://sailsjs.org/#/getStarted?q=what-os-do-i-need

After that you need to install bower, slush and sails main packages to make all things to happen. These can be installed with following commands on your *nix box.

sudo npm install bower -g
sudo npm install slush -g
sudo npm install sails -g

After you need to download codes of this project to your computer, please follow instructions below.

Back- and frontend installation

Navigate yourself to directory where you downloaded or cloned this repo and run following command on shell:

npm install

That will install all needed packages for back- and frontend. You can also install those separately just by run that same command on backend or frontend directory.

Configuration

You can configure your backend and frontend applications to use your environment specified settings. Basically by default you don't need to make any configurations at all. With default configuration backend will be run on http://localhost:1337 and frontend on http://localhost:3001 (development) http://localhost:3000 (production).

Backend

There is an example of backend configuration file on following path.

backend/config/local_example.js

Just copy this to backend/config/local.js and make necessary changes to it. Note that this local.js file is in .gitignore so it won't go to VCS at any point.

Frontend

There is an example of front configuration file on following path.

frontend/config/config_example.json

Just copy this to backend/config/config.json and make necessary changes to it. Note that this config.json file is in .gitignore so it won't go to VCS at any point.

Running of this POC

You need to start both backend and frontend servers to run this POC.

Backend

cd backend
sails lift

This will start sails.js server on defined port. By default this is accessible from http://localhost:1337 url. If you try that with your browser you should only see page that contains Not Found message on it. This means that everything is ok.

Frontend

Development

cd frontend
gulp serve

This will start simple web server that you can use within developing frontend side. By default this is accessible from http://localhost:3001 url. You should be see login page if you try that url with your browser.

Deployment

As in production

cd frontend
gulp dist

This will create a deployment code to frontend/dist folder. After that you can serve those static HTML, CSS, Javascript and asset files by any web server you like (Apache, nginx, IIS, etc.). For testing this production ready code you can also use gulp production command which will serve those dist files. By default this is accessible from http://localhost:3000 url.

Testing POC

1. Start back- and frontend servers as described above
2. Open http://localhost:3001 with your favorite browser
3. Login with with following credentials:
   • username: liukko
   • password: poc
4. Start watcher for files you like
5. Open terminal and modify backend/data/{watcherFile}
   • You should see changes of that file on the browser

Possible failures

Below is small list of possible failures that can occur while trying this POC.

1. Sails won't lift and you get error message like: Fatal error: watch ENOSPC
   • http://stackoverflow.com/questions/16748737/grunt-watch-error-waiting-fatal-error-watch-enospc
   • tl;dr just run npm dedupe
2. Frontend side is missing some 3rd party libraries. eg. browser console is full of some errors.
   • Try to install bower packages manually by command bower install in frontend directory.

Author

Protacon Solutions

Contributors

Tarmo Leppänen

License

The MIT License (MIT)

Copyright (c) 2014 Protacon Solutions

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.