@hoctail/client NPM

Welcome to @Hoctail/client

Hoctail is a hosting platform for javascript web applications. It's in demo stage and only available for testing.
Hoctail client is an interactive console that runs locally and is using an API to interact with Hoctail server.

🏠 Homepage

Index

Install
Api Key
Node client API
Deploy express app
Deploy mini app
Run code
- Interactive mode (REPL)
- Execute a script file
CLI reference

Install

npm install @hoctail/client

Api Key

Create Api Key as shown here. Then create a project's folder on your pc, and create .env file with contents like here:

HOCTAIL_API_KEY=Your-API-Key-Here

or export environment variables: HOCTAIL_API_KEY - Api key, HOCTAIL_APP - user app. Every time when CLI is executed it will connect to a server using above settings.

Node client API

CLI assigns an instance of configured Node client to hoctail global variable. It provides an API for working with a remote application to run queries, fetch logs or run javascript code on a server in the sandbox. On server-side each application have a global hoc object, that can be used to access the platform APIs. Here some examples on how hoctail, hoc objects can be used:

await hoctail.wait(() => { return hoc.schema /*server-side context*/ })
await hoctail.run(() => { /*server-side context*/ })

CLI can deploy Hoctail Applications

Application is a single js file without specific dependencies or a folder containing a package.json.

Deploy Expressjs app

Check a complete express app example here. Here are generic steps to serve it:

Go to a local nodejs dev environment
Create API key in the Hoctail UI
Create your app in the Hoctail UI (name: MyApp)
Run the following:

$ mkdir MyApp
$ cd MyApp
$ npm init
$ npm install .... your dependencies ....
.....
$ npm install --dev @hoctail/client

.... create index.js with your app code

$ export HOCTAIL_KEY='your-api-key'
$ hoctail --app MyApp serve
$

Deploy Mini app

Run it:

$ hoctail --app MyMiniApp mini ./index.js
Will initialize app →  MyMiniApp :
Will update 'mini' app →  MyMiniApp :
bundle size: 1303 bytes

Run code

CLI executes a source code provided by user in a local nodejs environment. Node Client is using to run code provided by user in application's context on a server-side.

Interactive mode (REPL)

To enter REPL mode run hoctail CLI without command arguments:

hoctail --app MyApp
[user]@app> await hoctail.wait(() => hoc.schema)
[user]@app> .help

REPL prompt is showing [user]@app> info about current execution context. Try .help for information about standard REPL commands. For instance .sql command runs a sql query, and .logs command fetches the latest app logs.

Note: REPL supports top-level await.

Execute a script file

Users can run their (deployment) scripts:

// script.js
const result = await hoctail.wait(async () => {
  const fetch = require('node-fetch')
  try {
    // fetches DiditalOcean status data
    const data = await fetch('https://s2k7tnzlhrpw.statuspage.io/api/v2/status.json')
    const text = await data.text()
    return text
  } catch (e) {
    return e
  }
})
console.log(result)

Run it:

$ hoctail --app MyApp ./sript.js 
{"page":{"id":"s2k7tnzlhrpw","name":"DigitalOcean","url":"http://status.digitalocean.com","time_zone":"Etc/UTC",
"updated_at":"2021-04-19T19:01:56.585Z"},"status":{"indicator":"none","description":"All Systems Operational"}}
$

CLI reference

$ hoctail --help
Usage: hoctail [options] [command]

Options:
  -V, --version                output the version number
  --endpoint <endpoint_url>    Hoctail Endpoint url, env: HOCTAIL_ENDPOINT
  --key <api_key>              Hoctail API key, env: HOCTAIL_API_KEY
  --app <app_name>             Hoctail app name, format: 'owner/name', env:
                               HOCTAIL_APP
  --log-level <log_level>      Minimal log level, default: LOG, env:
                               HOCTAIL_LOG_LEVEL
  -h, --help                   display help for command

Commands:
  env <cmd>                    manipulate env variables
          			examples:
          			  hoctail env show : show all the remote app env variables
          			  hoctail env push : replace app env variables with the contents of local .env file
          			  hoctail env pull : download remote app variables to a local .env file
          
  serve [path]                 serve a local `expressjs` app on server,
                               default: [path] = .
  install <path> [serverPath]  install a local npm pkg/module on server, optionally use a server path
          			examples:
          			  hoctail install ./index.js : install a package from an entrypoint file
          			  hoctail install some-package : install a local npm package
          			  hoctail install ./module.js ./module : install a local entrypoint as require('./module')
  mini <path>                  install UI app type = 'mini'. path - is path to single js file or npm package.
        			examples:
        			  hoctail mini ./index.js : use single js file
        			  hoctail mini some-package : use a local npm module
  dryRunMini <path>            Will only create a bundle. path - is path to js file or npm package.
        			examples:
        			  hoctail mini ./index.js : use single js file
        			  hoctail mini some-package : use a local npm module
  repl [script]                launch repl
  help [command]               display help for command

Simple call will launch repl:
  $ hoctail
  hoctail>

Install

Advanced option, if you need to install specific dependencies into the sandbox.
Usually it's not needed as your local dependencies get packed and bundled with your app in serve

Install package from its entry point

$ cd node_modules/package
$ hoctail install ./index.js

Shortcut to above

$ hoctail install package

Install a `local` module

$ hoctail install ./index.js ./package

Now you can require it in your app or server code

$ hoctail --app MyApp
user@MyApp> await hoctail.wait(() => {
  const pkg = require('./package')
  return pkg.func()
})

Environment variables

Get the current env variables for an app

$ hoctail env show
{}

Use a local .env file to push and synchronize env variables

$ cat .env
HOCTAIL_API_KEY=f5eb18b6-b593-11eb-9a4b-0b6531f7e888
HOCTAIL_APP='My App'
AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE
AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY

$ hoctail env push
{
  AWS_ACCESS_KEY_ID: 'AKIAIOSFODNN7EXAMPLE',
  AWS_SECRET_ACCESS_KEY: 'wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY'
}

Note: `HOCTAIL*` env vars are not pushed to server, these are CLI specific_

You can also pull remote vars locally

$ hoctail env pull
{
  NODE_ENV: 'production'
}

$ cat .env
HOCTAIL_API_KEY=f5eb18b6-b593-11eb-9a4b-0b6531f7e888
HOCTAIL_APP='My App'
NODE_ENV='production'

Note: need to restart the app to pick up new env vars in most cases, (hoctail serve will restart for you)