Skip to content

Latest commit

 

History

History
253 lines (193 loc) · 8.72 KB

building_planner.adoc

File metadata and controls

253 lines (193 loc) · 8.72 KB

Building Planner

1. Overview

Planner can be built as a standalone app or integrated within the Fabric8-UI. Here we’ll mostly focus on various ways of running it as a webapp. We’ll also briefly touch on the process of integrating and running it with Fabric8 UI.

2. Build and Run for Development

Planner comes with a minimal standalone runtime and mock in-memory database. This can be helpful to build and run Planner without having to build/setup all the components it relies on, for e.g. Fabric8 UI, WIT core, DB, Auth server etc.

We’ll primarily discuss here how to run Planner locally in standalone mode.

  • The Without Containerization section will touch on how to integrate it with Fabric8 UI as well, but while using mock backend.

  • Whereas the orchestrated setups With Containerization will fully setup the WIT core, DB and Auth for the Planner, but without Fabric8 UI integration (for now).

2.1. Without Containerization

In this part, we’ll build and use Planner without having to setup various containerization and virtualization technologies.

  • Pros:

    • No need for setting up containerization, virtualization and orchestration tools.

    • Just having Node.js and npm installed is good enough.

    • Good for people who just want to run it

  • Cons:

    • Larger system footprints and it’s never 100% reversible.

    • Needs installing a lot more dependencies, if backend is also setup locally.

Note

In order to run Planner without containerization, you have to have Node.js and npm installed. Check their official download page for packages and docs to set it up on your platform. On latest Fedora sudo dnf install nodejs should do the job.

Once they’re installed, run npm install in the Planner directory to resolve all the libraries.

2.1.1. Using the launcher Script

To run a minimal runtime implementation of the Planner using an in-memory mock database use:

$ scripts/run-planner.sh --standalone

You can access the service on http://localhost:8080

Note
 To run the script on macOS, install gnu-getopt, run brew install gnu-getopt, and set it in your PATH: echo 'export PATH="/usr/local/opt/gnu-getopt/bin:$PATH"' >> ~/.zshrc.

This script can also build the Planner with an integrated environment such as fabric8-ui (or an external webapp):

$ scripts/run-planner.sh

See the launcher script for further information and configuration options.

2.1.2. By manually building the app

This process is functionally similar to building with the launcher script, but going through the steps manually.

Note
 You may need to have root access to run the following commands.

  1. Build the fabric8-planner as a library and set up a watch task to rebuild any TS, HTML and SCSS files you change. In the fabric8-planner root directory, run:

    npm run build -- --watch

  2. Change directory to runtime and get the dependencies for planner runtime.

    cd ./runtime
npm install

  3. Link the Planner library to the runtime over npm (this may be required to be run as a super-user).

    npm link ../dist

  4. Set the execution environment on build time using the NODE_ENV variable.

    export NODE_ENV=<mode>
    Note
    		 If you want to run the application in development mode, you can skip this step, as NODE_ENV takes development mode as the default.

    You can choose from the following modes as required:

    1. Development mode (default): export NODE_ENV=development

      Use this mode to contribute to the code base, it loads the application with local live data. Since this is the default mode, you need to use this command only if you want to switch from another mode to development mode.

    2. In-memory mode: export NODE_ENV=inmemory

      Use this mode to try out or test the application, it loads the application with mock data.

    3. Production mode: export NODE_ENV=production

      Use this mode to deploy the application.

  5. Build and run the runtime application.

    npm start

  6. Point your browser to http://localhost:8080

Important
 If you use inmemory mode, then after running the application, ensure that you visit this URL which includes the authenticated/logged-in user token, to load it up with mock data.

To integrate planner with Fabric8 UI environment, the steps are quite similar as before, but instead of the runtime, we’re going to link and use Planner library into Fabric8 UI (or any other external app needing to embed planner).

  1. Build the fabric8-planner as a library and set up a watch task to rebuild any TS, HTML and SCSS files you change. In the fabric8-planner root directory, run:

    npm run build -- --watch

  2. Change directory to the webapp into which you want to embed the Planner library (let’s use Fabric8 UI in this example) and ensure that you have installed the npm package.

    cd /path/to/fabric8-ui
npm install

  3. Link the Planner library to fabric8-ui over npm (this may be required to be run as a super-user).

    npm link/<path to fabric8-planner>/dist

  4. Run Fabric8 UI in development mode.

    npm start
    Note
    		 fabric8-ui is set up to reload and provide access to sourcemaps automatically when you run npm start.

  5. Point your browser to http://localhost:8088

2.2. With Containerization

In this part, we’ll orchestrate the Planner stack using containerization and virtualization (for minishift) technologies.

  • Pros:

    • Gives taste of the full planner stack, close to production

    • Once set up, building and running is magically simple and easy

    • Doesn’t need runtime and language installations on the host system

    • Smaller system footprints which are also fully removable/reversible

  • Cons:

    • Needs setting up containerization, virtualization and orchestration tools

    • Not good (yet) for continuous development as it lacks automatic rebuilding

Note

In order to use containerization, you have to have orchestration strategy specific tools installed. Specific requirements are detailed in their respective sections.

2.2.1. Using Docker Compose

This expects your system to have docker (and docker engine v1.13.0+ i.e. with version v3.x compose file support) set up and the service running.

  1. First, build planner image from source. This is similar to manual build process, but without the --watch flag to rebuild changes (as of now).

    docker build -t fabric8-planner-runtime .

  2. Run the stack with Docker Compose. This runs Planner, Core, DB, Auth & Auth’s DB images orchestrated to work together.

    docker-compose up

    If wit/core fails to start with docker-compose up, just force a docker-compose start core on another terminal. This will continue the stdout on the former terminal and the later terminal can be closed after invoking the command.

  3. Visit http://localhost:8088 on your browser to access the app at this point.

  4. When done, do the following to clean up:

    docker-compose down

  5. Optionally, you can remove the images as well (also helps if you need to fetch new images):

    docker images # lists the images
docker rmi <imageID>

Alternatively, you can also run only planner image, against external (prod/demo) API sources. In that case, use something like this:

docker build -t fabric8-planner-runtime .
docker run -it --name=fabric8-planner-runtime -p 8088:8080 \
        -e "API_URL=http://demo.api.openshift.io/api/" \
        -v $(pwd)/runtime/dist:/dist:Z fabric8-planner-runtime

If you just want to run the unit-tests (or some other script in the container, instead of starting the server), then please uncomment and edit the services::planner::entrypoint field in the docker-compose.yml.

Known Limitation: Data won’t persist between subsequent runs - it’s more of a choice than a limitation

2.2.2. Using Minishift

<Coming Soon>

3. Build for Production

You can use the production environment to build a production package equivalent version.

To generate the production build, set the API URL and run the build script as follows:

$ npm run build

The created library or the build output is placed in the fabric8-planner/dist directory.

Important
 Do not publish the build manually. It is recommended to let the CD pipeline do a semantic release.

To create a docker image, run this command immediately after the production build completion:

$ docker build -t fabric8-planner-deploy -f Dockerfile.deploy .