portals: A TypeScript repository from monika

Portals - VM microservice

Docs

Info
- Status
Codebase
Questions / Issues

Info

@cryb/portals is the microservice used to handle requests @cryb/api to create and destroy 'Portals', which is the term we use for VM instances.

@cryb/portal instances also connect to @cryb/portals over WS to send and recieve updates like controller events and health updates.

Status

@cryb/portals has been actively developed internally since September 2019, and is now open source as of October 2019.

Codebase

The codebase for @cryb/portals is written in JavaScript, utilising TypeScript and Node.js. Express.js is used for our REST API, while the WebSocket API uses the ws module.

MongoDB is used as the primary database, while Redis is used for cache and PUB/SUB.

Folder Structure

cryb/portals/
└──┐ src # The core source code
   ├──┐ config # Config files for Redis, Passport, etc
   │  └── providers # Config files for the provider APIs, such as Google Cloud, Kubernetes, etc.
   ├── controllers # Our REST route controller files
   ├── drivers # Methods used to deploy Portal instances
   ├── models # Models for our a data types, such as portals and requests
   ├── schemas # Mongoose schema files
   ├── server # Our Express.js setup and WebSocket setup
   ├── services # Services such as queue management, etc
   └── utils # Helper methods

First time setup

First, clone the @cryb/portals repository locally:

git clone https://github.com/crybapp/portals.git

Installation

The following services need to be installed for @cryb/portals to function:

MongoDB
Redis
@cryb/api

We recommend that you run the following services alongside @cryb/portals, but it's not required.

@cryb/web
@cryb/aperture

You also need to install the required dependencies, by running either:

npm install

yarn

Ensure that .env-example is either copied and renamed to .env, or is simply renamed to .env.

In this file, you'll need some values. Documentation is available in the .env-example file.

Running the app locally

Background Services

Make sure that you have installed MongoDB and Redis, and they are both running locally on port 27017 and 6379 respectively.

The command to start MongoDB is mongod, and the command to start Redis is redis-server.

If you're developing a feature that requires the VM infrastructure, then make sure @cryb/aperture is running.

Starting @cryb/portals

To run @cryb/portals in development mode, run either:

npm run dev

yarn dev

Adding a custom provider

@cryb/portals makes it easy to add a custom cloud provider to deploy Portal instances onto.

First, make a config file under src/config/providers. You want to call this foo.config.ts. This file should export the API of the provider you want to use. See gcloud.config.ts for an example of how Google Cloud intergration is handled.
Next, make a file under src/drivers. You want to call this foo.driver.ts. You can copy the code in example.driver.ts as a starting point.
Import your foo.config.ts file and then add the code to create a cloud deployment with the desired config under the try { clause in the openPortalInstance method.
Optional, but recommended Add the method under the try { clause in closePortalInstance to destroy the VM instance. This will be called when a Room no longer needs a portal, such as when all members have gone offline.
Now, under src/drivers/router.ts, import your driver and rename its methods so they don't conflict when any other drivers. See below:

import {
    openPortalInstance as openFooPortalInstance,
    closePortalInstance as closeFooPortalInstance
} from './foo.driver'

If you're not using TypeScript, skip this step Make sure you have added the name of your driver to the Driver type. See below:

type Driver = 'gcloud' | 'kubernetes' | 'foo'

Add a case to the switch statement under openPortalInstance with the name of your driver methods. See below:

switch(driver) {
    ...
    case 'foo':
        openFooPortalInstance(portal)
        break
}

Optional, but recommended If you added a closePortalInstance handler in your driver, add a case to the switch statement under closePortalInstance with the name of your driver methods. See below:

switch(driver) {
    ...
    case 'foo':
        closeFooPortalInstance(portal)
        break
}

Make sure you change the current driver under fetchCurrentDriver. See below:

const fetchCurrentDriver = () => 'foo' as Driver

Done! Enjoy using @cryb/portals with the cloud provider of your preferred choice. For any help, view here. If you're feeling generous, create a PR request with your driver so the community can use it. Be sure to follow our Guidelines before submitting a PR.

Questions / Issues

If you have an issues with @cryb/portals, please either open a GitHub issue, or contact a maintainer.

monika/portals