Skip to content

Latest commit

 

History

History
105 lines (63 loc) · 5.79 KB

developer_guide.md

File metadata and controls

105 lines (63 loc) · 5.79 KB
Raw

Cloud Stove UI Developer Guide

The Cloud Stove currently consists of two main components: The backend API implemented using Ruby on Rails and the front end application implemented using AngularJS. This document should provide you with enough information to correctly set up the front end application, in order to extend its features.

Overview

The front end is written entirely using the framework Angular 2 and in TypeScript. If you find yourself unfamiliar with either of these two, the fastest way to get a grasp of the concepts is by following the excellent Learning Angular section of the official documentation. The Cloud Stove project is heavily inspired by the official samples provided by Google in its structure and tool usage.

Structure, Configuration and important Files

The project is structured as follows:

  • docs

    Contains the documentation you are currently reading ;)

  • server

    A basic ExpressJS server to serve the static contents of the front end, when compiled and deployed in production. You can also use any kind of webserver that is able to statically serve files to fulfill this task. The provided server is used when deploying the front end as Docker container.

  • src

    • app

      Contains all of the application code of the Cloud Stove front end.

    • public

      Contains all resources such as images and additional font files (icons) that are used by the front end.

    • style

      Contains application-wide .scss files to declare styles. Also embeds Bootstrap.

  • Procfile, app.json

    Enables deployment on Heroku and manages its configuration.

  • karma-shim.js, karma.conf.js

    Enables Unit-Testing using Karma.

  • protractor.conf.js

    Enables E2E using Protractor. By default, this project tests against Chrome. You can change this setting by overriding {'browserName': 'chrome'} in this file to your liking.

  • tsconfig.json, tslint.json, typedoc.json

    Configuration for various TypeScript-settings and linter settings. The tslint is mostly following Googles standard for Angular projects using TypeScript.

  • webpack.config.js

    Config file for the webpack module bundler. More information about the specific configuration can be found in the file itself. Most likely, you won't have to change it unless a new type of file should be included in the project or an update is necessary.

  • wercker.yml

    Wercker build file that specifies how this project is built using the CI infrastructre of wercker.

Modules

The project is organized in modules that help organize the application into blocks of functionality. Each folder in src/app usually contains a .module.ts file that specifies the module, its dependencies and its exports. Thus, functionality can be built in building blocks and be reused easily. To get a grasp what belongs into the same module, check out the FAQ from the Angular Team.

Build

In order to deploy The Cloud Stove front end in production, you have a number of options.

NodeJS

Use npm run build to generate all static assets for production. You can start the supplied express server using npm run production.

Docker

Build the image on your machine using docker build, and start the container afterwards with your parameters of choice. Make sure to set the environment variables API_URL and/or PORT (defaults to 80) to your specific needs.

Localhost

See running backend with Docker.

  1. Build image:

    docker build -t cloud-stove-ui .

  2. Start frontend on port 1234, assuming the backend is running on localhost:3000:

    docker run -p 1234:80 -e API_URL='http://localhost:3000' cloud-stove-ui

  3. Login with an interactive shell

    docker run --rm -it cloud-stove-ui /bin/bash

Heroku

Make sure to set the API_URL config variable for your app to a running backend instance, e.g.:

heroku config:set API_URL=https://api.thestove.io

Deploy

Tests

You can execute tests for the front end using one of two npm shortcuts.

  • npm run test to execute unit tests
  • npm run e2e to execute E2E tests

When running E2E tests, make sure that the front end AND the Cloud Stove back end is currently up and running on your local device using npm start.