Set up tutorial environment

Introduction

This document describes how to set up your environment and install the necessary software for running the web tutorials on this site.

NOT INCLUDED

Credentials, such as a License API Key. This is provided to you by Colibrio when you get access to the framework.

Installing necessary software

In order to get and run the Tutorials, you need to have the following software on your machine:

• Git - for cloning the Tutorials Git repository
• Node.js - for building and running the tutorial projects

Installing Git

You need the Git version control software in order to get the source code for the Tutorials.

Check if you have Git installed by running the following command in a terminal:

git --version

If you do not have Git installed, follow one of the Git install guides, for example:

• https://github.com/git-guides/install-git
• https://www.atlassian.com/git/tutorials/install-git

Installing Node.js

You need Node.js in order to build the Colibrio Tutorial projects.

Check if you have Node.js installed by running the following command in a terminal:

node --version

If you do not have Node.js installed, you can find various install alternatives from the official Node.js website https://nodejs.org/. We recommend to use the latest LTS version of Node.js.

Cloning the Tutorials Git repository

The source code for the tutorials is available in a public Bitbucket Git repository. Run the following command line to create a local copy of the repository into the directory colibrio-web-framework-tutorials:

git clone https://bitbucket.org/colibrio/colibrio-web-framework-tutorials.git colibrio-web-framework-tutorials

Building and running a tutorial project

If you navigate into colibrio-web-framework-tutorials you should see several directories. Each directory is a tutorial project that you can build and run.

You need to perform the following steps in a tutorial project to build and run it:

1. Add your Colibrio NPM Auth Token to the project's .npmrc file.
2. Add your Colibrio License API Key to the project's .env file.
3. Install project dependencies with your preferred package manager.
4. Run the start script in package.json to build the project and start a server on http://localhost:1234.
5. Navigate a web browser to http://localhost:1234.

Configuring .npmrc with an NPM Auth Token

The @colibrio/colibrio-reader-framework NPM package is hosted in a private NPM registry. To be able to download it as a dependency with yarn or npm, you need to configure the project's .npmrc file.

Create an .npmrc file in the project with the following content:

@colibrio:registry=https://npm.pkg.colibrio.com/
//npm.pkg.colibrio.com/:_authToken=<authToken>
//npm.pkg.colibrio.com/:always-auth=true

Replace <authToken> with the NPM Auth Token you received from Colibrio.

Configuring .env with a License API Key

When you build a tutorial project, it expects the environment variable COLIBRIO_LICENSE_API_KEY to contain your Colibrio License API Key. By creating an .env file, you can define environment variables that are loaded while building the tutorial project.

Create an .env file in the project with the following content:

COLIBRIO_LICENSE_API_KEY=<apiKey>

Replace <apiKey> with the License API Key you received from Colibrio.

Installing project dependencies

Each tutorial project declares a list of dependencies in the package.json file that are required to develop, build and run the project.

Install dependencies:

npm

npm install

yarn

yarn install

pnpm

pnpm install

This will install support for Typescript in the project and Parcel which is used to build and serve the tutorial as a web app.

If the @colibrio/colibrio-reader-framework dependency fails to install, make sure you have configured the .npmrc file.

Running the project

Every tutorial project declares a "start" script in the package.json file that builds the corresponding tutorial project and serves it as a web app on http://localhost:1234.

Using Yarn:

npm

npm start

yarn

yarn start

pnpm

pnpm start

The "start" script uses parcel serve to build and host the tutorial. It will watch for source file changes and automatically rebuild the web app if needed.

You can pass additional options to parcel serve. For example, change the port used to 8899:

npm

npm start -- -p 8899

yarn

yarn start -p 8899

pnpm

pnpm start -p 8899

Please refer to https://parceljs.org/features/cli/#parameters for all available Parcel options.