Version: 2.x

Getting started

micro-lc is shipped as an ES module CDN bundle and can be imported in any HTML page. Moreover, a dockerized webserver is available on Docker Hub.

Tutorial

The best way to get started is the step-by-step tutorial

Import from CDN

Create a blank index.html file and paste the following snippet:

index.html
<!DOCTYPE html>
<html lang="en">
<head>
  <title>micro-lc</title>
  <link rel="icon" href="https://avatars.githubusercontent.com/u/92730708?s=200&v=4" />

  <!-- 👇 CDN link to download micro-lc -->
  <script type="module" src="https://cdn.jsdelivr.net/npm/@micro-lc/orchestrator@latest/dist/micro-lc.production.js"></script>
  <!-- 👇 some optional style to fill the page -->
  <style>
    html, body {
      position: relative;
      width: 100%;
      height: 100%;
      margin: 0;
    }
  </style>

</head>
<body>
  <!-- 👇 micro-lc tag with config reference and fallback language -->
  <micro-lc config-src="/config.json" fallback-language="en-US"></micro-lc>
</body>
</html>

tip

To enhance the security of your websites you can add CSP rules either on your web server response header (e.g. nginx), or as a meta tag on the head of your Document:

<meta
  http-equiv="Content-Security-Policy"
  content="
    default-src 'self' https: http:;
    script-src 'self' 'unsafe-eval' 'unsafe-inline' blob: data:;
  "
/>

micro-lc works even without a configuration file, however a 404 error page is all you will see. It's time to write our first configuration file. You can choose either JSON or YAML (we suggest YAML for development, and JSON for production). A YAML to JSON converter is available in the Playground section.

config.json
{
  "version": 2,
  "applications": {
    "home": {
      "integrationMode": "iframe",
      "src": "https://wikipedia.org",
      "route": "./"
    }
  }
}

You can now serve the application with your static server of choice, like Node.js node-static by running:

npm install -g node-static
static -p 8000

Read the documentation to know more about what micro-lc can do, and use the live Playground section to test your configurations.

Deploy with Docker Compose

A sample micro-lc application can be deployed using Docker Compose. It requires a instance of microlc/micro-lc container where the configuration is linked via volume.

First things first, copy the following content in a docker-compose.yml file.

docker-compose.yml
version: '3'

services:
  micro-lc:
    image: microlc/micro-lc:${MICRO_LC_VERSION:-latest}
    ports:
      - 8080:8080
    volumes:
      - ./config.json:/usr/static/config.json

Now you need to create the configuration file: copy the following snippet in a config.json file located in the same directory of the previously created .yml.

config.json
{
  "version": 2,
  "applications": {
    "home": {
      "integrationMode": "iframe",
      "src": "https://example.com",
      "route": "./"
    }
  }
}

Run docker compose up -d inside the directory, and you will have micro-lc hosted on http://localhost:8080/. To drop the environment, run docker compose down in the same directory.

To spin up an environment which uses a backend to serve the application, follow this guide

Deploy Docker container

micro-lc static assets are also embedded in a pre-built Docker container available on Docker Hub. The container is a nginx web server that comes with some useful set-up.

To deploy it locally, ensure your localhost 8080 port is available, and run

docker run -d -p 8080:8080 microlc/micro-lc:latest

This container has the following runtime environment variables.

Name	Type	Default	Description
`BASE_PATH`	`string`	`/`	`index.html` base tag href.
`MODE`	`development \| production`	`production`	micro-lc bundle.
`CONFIG_SRC`	`string`	`./config.json`	URL to micro-lc config.

BASE_PATH is useful if your micro-lc app must be served on a sub path. Be aware that any route declared in the configuration file under applications, when relative, are computed with respect to BASE_PATH.

Web Page Index File

By default, micro-lc landing page is located in /usr/static/index.html and enforces no CSP security rules. Moreover it comes with 3 variables that the upstream nginx web server filters out and substitute.

**MICRO_LC_BASE_PATH** becomes the container environment variable BASE_PATH
**CSP_NONCE** is substituted once per request and provides a valid 32 bytes random nonce
**MICRO_LC_MODE** becomes the container environment variable MODE
**MICRO_LC_CONFIG_SRC** becomes the container environment variable CONFIG_SRC

Due to the presence of the **CSP_NONCE** variable, nginx attempts multiple substitutions on any resource it serves (sub_filter_once is set to off). micro-lc code is aware of that, but be careful in case you embed static files in this container that they will be filtered using such rules.

index.html
<!DOCTYPE html>
<html lang="en">
<head>
  <!-- HEAD section -->
</head>
<body>
  <micro-lc config-src="**MICRO_LC_CONFIG_SRC**"></micro-lc>
</body>
</html>

The head element provides specifications for base tag, icon and title. CSP are also declared

index.html/head
<head>
  <base href="**MICRO_LC_BASE_PATH**" target="_blank" />
  <title>Microlc</title>
  <link rel="icon" type="image/png" href="./favicon.png" />
  <meta
    http-equiv="Content-Security-Policy" content="
      default-src 'self' https: http:;
      script-src 'self' 'unsafe-eval' 'unsafe-inline' blob:;
      object-src 'none';
      style-src 'self' 'unsafe-inline';
      img-src 'self' data: https: http:;
      font-src 'self';
      worker-src 'self' blob:;
      base-uri 'self';"
    />
  <style>
    html, body {
      position: relative;
      width: 100%;
      height: 100%;
      margin: 0;
      padding: 0;
      overflow: hidden;
    }
    micro-lc {
      display: inline-block;
      position: relative;
      height: inherit;
      width: inherit;
    }
  </style>
  <script async type="module" src="./micro-lc.**MICRO_LC_MODE**.js"></script>
</head>

Web Server

The micro-lc container is effectively an nginx web server, currently on version 1.23.2. It is preset to rewrite any route according to your BASE_PATH choice. Moreover, it does per-call sub filtering of special variables. This feature is useful to

inject runtime variables to micro-lc web component, and
inject a CSP nonce on scripts and style tags.

Which basically sums up to the following configuration:

http {
  server {
    # ...
    location ~ (^/|^${BASE_PATH}) {
      set_secure_random_alphanum      $cspNonce 32;

      rewrite                         ^${BASE_PATH}$ /index.html break;
      rewrite                         ^${BASE_PATH}/?(.*) /$1 break;

      sub_filter_once                 off;
      sub_filter                      '**MICRO_LC_BASE_PATH**' '${BASE_PATH}';
      sub_filter                      '**MICRO_LC_MODE**' '${MODE}';
      sub_filter                      '**MICRO_LC_CONFIG_SRC**' '${CONFIG_SRC}';
      sub_filter                      '**CSP_NONCE**' $cspNonce;

      expires                         -1;
      try_files                       $uri $uri/index.html /index.html =404;
    }
  }
}

Notice that the algorithm set_secure_random_alphanum is provided by an nginx external module and generates 32 bytes of random hash on each endpoint call replacing the variable `CSP_NONCE.

Customization

To override default configurations with your own, you can use volumes:

index.html is mounted at /usr/static/index.html
config.json is mounted at /usr/static/config.json
default.conf is mounted at /etc/nginx/conf.d/default.conf

Building from source

If you would like to contribute or simply run micro-lc from source code, checkout locally the official repository.

Be aware that it needs node 16+ and . These requirements can be met installing a node version manager like nvm and then running:

nvm install lts/gallium
corepack enable

Once your node is up and running, issue:

yarn install
yarn initialize

and the source code of micro-lc will be located at packages/orchestrator/dist.

Locally a playground is available but requires Docker and Docker Compose to run. After running:

yarn playground

the playground will be available on http://localhost/.

Playground

An online playground is available on this documentation website. Refer to our guides to try micro-lc out on the playground setup.

Tutorial​

Import from CDN​

Deploy with Docker Compose​

Deploy Docker container​

Web Page Index File​

Web Server​

Customization​

Building from source​

Playground​