Archived

This repository has been archived on 2024-08-21. You can view files and clone it, but cannot push or open issues or pull requests.

Marsell Kukuljevic 51028156c9 Document installation of app, including in production. Add smf manifest so

we can run this in a Joyent-branded zone too.

2021-04-11 20:51:52 +02:00

3.7 KiB

Raw Blame History

Installing in Production

Be familiar with the steps in [Installation][] below, since it is needed to build the Angular app first.

Once the Angular app is built, provision a small base-64-lts 20.4.0 VM, connected solely to the external network (aka public Internet). From within the VM, the following steps are needed:

pkgin in gmake
mkdir -p /opt/spearhead/portal

From this repo, copy in bin/, cfg/, smf/, static/ (since this is a symlink, this means the build in app/dist should be copied into static/ in prod), and *. Notably, avoid app/ and node_modules. In production, adjust the config in /opt/spearhead/portal/cfg/prod.json. Lastly:

pushd /opt/spearhead/portal
npm install
svccfg import smf/service.xml
svcadm enable portal
popd

The application will now be running.

Installation

First install the server-side libraries:

npm install

Then install the Angular compiler needed for the client-side app:

npm install -g @angular/cli
pushd app && npm install && popd

Build the client-side app:

pushd app && npm run build && popd

Generate server certificates

pushd config
openssl genrsa -out key.pem
openssl req -new -key key.pem -out csr.pem
openssl x509 -req -days 9999 -in csr.pem -signkey key.pem -out cert.pem
rm csr.pem
popd

Configuration

Ensure the config file in config/ matches your details. If running in production, name the config file config/prod.json.

Relevant configuration attributes:

server.port: the port this server will serve the app from
server.key: path to the private key for TLS
server.cert: path to the PKIX certificate for TLS
urls.local: the domain or IP the SSO will redirect back to (aka this server)
urls.sso: the URL to the SSO
urls.cloudapi: the URL to cloudapi
key.user: name of Triton user who has "Registered Developer" permission set
key.id: SSH fingerprint of Triton user (same as what node-triton uses)
key.path: path to private key of Triton user

The SSH key used must be the correct format, e.g. generated with:

ssh-keygen -m PEM -t rsa -C "your@email.address"

Running the server

node bin/server.js config/prod.json

The server generates a lot of JSON data about every request. This is easier for a human to handle if they have bunyan installed ("npm install -g bunyan"), and instead:

node bin/server.js config/prod.json | bunyan

Endpoints

GET /*

This is where all the front-end code goes. All files will be served as-is as found in that directory (by default a symlink from static/ to app/dist). The default is static/index.html. There is no authentication; all files are public.

GET /api/login

Call this endpoint to begin the login cycle. It will redirect you to the SSO login page: an HTTP 302, with a Location header.

GET/POST/PUT/DELETE/HEAD /api/*

All calls will be passed through to cloudapi. For these calls to succeed, they MUST provide an X-Auth-Token header, containing the token returned from SSO.

Interaction cycle

client --- GET /api/login --------> this server
       <-- 302 Location #1 ----

client --- GET <Location #1> --> SSO server
       <separate SSO cycle>
       <-- 302 with token query arg

From now on call this server as if it were a cloudapi server (using cloudapi paths), except prefixing any path with "/api". Also always provide the X-Auth-Token.

For example, to retrieve a list of packages:

client --- GET /api/my/packages --> this server
       <-- 200 JSON body ------

The most useful cloudapi endpoints to begin with will be ListPackages, GetPackage, ListImages, GetImage, ListMachines, GetMachine, CreateMachine and DeleteMachine (see cloudapi docs).

3.7 KiB Raw Blame History