Ekko-cli

Ekko is a realtime serverless framework. Use the ekko-realtime-cli to initialize the Ekko framework and manage serverless functions for your realtime application.

Ekko-cli
Usage
Getting Started
FAQ
Commands

Usage

$ npm install -g ekko-realtime-cli
$ ekko COMMAND
running command...
$ ekko (-v|--version|version)
ekko-realtime-cli/0.0.31 darwin-x64 node-v14.15.0
$ ekko --help [COMMAND]
USAGE
  $ ekko COMMAND
...

Getting Started

Prerequisites

an AWS account
npm is installed
the AWS CLI is installed and configured
the AWS CDK command-line tool is installed

Installation

run npm install -g ekko-realtime-cli (to install our npm package)
type ekko --help to see the commands available to use

First Time Usage

The ekko command is run by inputting commands after the initial ekko like: ekko <command> <optional argument>.

To read the help text for each command, type ekko <command> --help. This will output a short explanation of what the command does, which arguments it takes and how to use it.

cd to the folder in which you would like to initialise your Ekko directory
type ekko init:
type y to deploy a new Ekko infrastructure which will:
- setup your AWS credentials for Ekko
- deploy Ekko infrastructure to AWS
- create an Ekko skeleton folder and file framework for your project files in the current directory
type n to join and existing Ekko infrastructure
- you will be prompted for your organizations Ekko infrastructure information which can be found in ~/.ekko/.env on a machine where Ekko has been initialized:
  - SECRET
  - API_ENDPOINT
  - S3_BUCKET
  - LAMBDA_ROLE_ARN
- you will then be prompted for your AWS credentials
  - AWS_ACCESS_KEY_ID
  - AWS_SECRET_KEY
  - AWS_REGION
- this creates a an Ekko folder in your current directory containing an empty ekko_apps folder
- clone your organization's Ekko application repositories in the ekko_apps folder
- clone your organizations's ekko_functions repository in the Ekko folder
once your Ekko folder is set up, cd into ekko/ekko_functions and type ekko create <function name> to create a folder and a template file for an AWS Lambda function.
type ekko deploy <function name> to deploy any particular function that exists locally inside the ekko_functions folder.
edit associations.json in the ekko_functions folder to associate a deployed ekko function with specific channels in your app
type ekko update associations.json to update the Ekko server with your new associations

Removing Ekko

To remove Ekko infrastructure from AWS, run ekko teardown. (This removes all server and shared resources infrastructure from AWS.)

To uninstall / remove the Ekko cli tool, run npm uninstall ekko-cli-tool. Then cd into /usr/local/bin and run rm ekko to delete the Ekko binary from your hard drive.

FAQ

I quit the `ekko init` command while it was in the middle of deploying infrastructure. Is there a way to tear down my infrastructure?

To remove this infrastructure (that AWS will continue to set up even if you interrupt the Ekko cli command, visit the AWS console, navigate to the CloudFormation section and you can individually delete the ekko-server stack and then the shared-resources stack. Note that the infrastructure deployment must be completed before AWS will allow you to delete those stacks. AWS will also not allow you to delete shared-resources before ekko-server is deleted because there are dependencies.

What infrastructure does Ekko spin up on my behalf?

The main infrastructure we spin are as follows:
- an S3 bucket to hold configuration files
- an Elasticache / Redis cluster
- an ECS cluster managed by the Fargate service for running the server containers

Does Ekko apply tags to the infrastructure that gets spun up by the CLI?

Everything deployed by ekko is tagged with the service:ekko key:value pair. This will allow you to monitor and access CloudWatch graphs and information.

Do I have to use the Ekko skeleton folder?

It is recommended that you use the Ekko skeleton folder to organize your Ekko applications and ekko_functions.
If you must, you can organize your Ekko applicaiton repositories however you'd like

Do I have to use the ekko_functions folder?

Yes. You can only run Ekko function commands from within this folder and all of your apps should share these functions.

Can I have more than one ekko_functions repository?

No. Ekko supports multiple apps but they should all use the same Ekko functions.

Why am I getting this error?: `Command can't be run outside of ekko_functions directory.`

Some Ekko commands require that your cwd is ekko_functions. This is verified by checking for an .ekko_functions.txt file in the cwd. If you are getting this error within your ekko_functions directory, make sure that .ekko_functions.txt exists and if it does not, create it.

Commands

ekko config
ekko create FUNCTIONNAME
ekko deploy FUNCTIONNAME
ekko destroy FUNCTIONNAME
ekko help [COMMAND]
ekko init
ekko jwt APPNAME
ekko status
ekko teardown
ekko update FILENAME

`ekko config`

Update ekko-cli to use new AWS credentials

USAGE
  $ ekko config

DESCRIPTION
  ...
  If you change or receive new AWS credentials, or if you want to deploy the infrastructure or functions to a different 
  AWS region, you can run this command to input the updated values.

  You will need:

  - your AWS access key
  - your AWS secret key
  - your AWS region

See code: src/commands/config.js

`ekko create FUNCTIONNAME`

Create a local ekko function

USAGE
  $ ekko create FUNCTIONNAME

ARGUMENTS
  FUNCTIONNAME  Name of new ekko function.

DESCRIPTION
  ...
  Pass in the name of the function you want to create as an argument to this command. It will create:

  - a folder in the ekko_functions directory and
  - a skeleton JavaScript template file (inside the folder it creates) that you can use to get started writing your 
  Lambda function code

See code: src/commands/create.js

`ekko deploy FUNCTIONNAME`

Deploy an ekko function to AWS Lambda

USAGE
  $ ekko deploy FUNCTIONNAME

ARGUMENTS
  FUNCTIONNAME  Name of Function you would like to deploy.

DESCRIPTION
  ...
  Pass in the name of a folder where your lambda function code is stored. 
  (This should be inside an 'ekko_functions' folder; one is created for you by default when you run 'ekko init' and 
  deploy infrastructure).

  This command will compress the contents of the folder and upload them to AWS Lambda. 
  To use the deployed lambda in your realtime app, add it to one or more channels in associations.json.

See code: src/commands/deploy.js

`ekko destroy FUNCTIONNAME`

Tear down a deployed AWS Lambda

USAGE
  $ ekko destroy FUNCTIONNAME

ARGUMENTS
  FUNCTIONNAME  Name of the AWS Lambda that you would like to tear down

DESCRIPTION
  ...
  Tears down a deployed AWS Lambda.

  Pass in the name of the Ekko function and this command will tear down its associated AWS Lambda.

See code: src/commands/destroy.js

`ekko help [COMMAND]`

display help for ekko

USAGE
  $ ekko help [COMMAND]

ARGUMENTS
  COMMAND  command to show help for

OPTIONS
  --all  see all commands in CLI

See code: @oclif/plugin-help

`ekko init`

Initialize files and deploy ekko infrastructure

USAGE
  $ ekko init

DESCRIPTION
  ...
  The 'init' command sets up everything you'll need to get going with ekko.

  You should run the command from the working directory in which you want to initialise an 'ekko' project folder.

  To join an existing ekko infrastructure, enter 'n' at the first prompt. This does the following:

  - prompts you for the credentials required to join an existing ekko infrastructure. 
  - these credentials can be found in ~/.ekko/.env on a machine where ekko has been initialized:
     - SECRET
     - API_ENDPOINT
     - S3_BUCKET
     - LAMBDA_ROLE_ARN

  - prompts you for your AWS credentials
     - AWS_ACCESS_KEY_ID
     - AWS_SECRET_KEY
     - AWS_REGION

  - saves credentials to ~/.ekko/.env
  - creates an empty ekko folder in your current working directory where you can clone your organization's realtime 
  application repositories and ekko_functions repository

  To deploy a new ekko infratructure enter 'y'. This does the following:

  - obtains and handles credentials (your AWS access key and secret key)
  - installs all needed dependencies, the AWS CDK tool (if you don't already have it)
  - runs the 'cdk bootstrap' command to spin up necessary intermediary infrastructure for the deployment
  - deploys a full working ekko server to AWS
  - creates an 'ekko' folder in the current working directory which includes a skeleton folder structure
  - writes the necessary server endpoint addresses and secrets to ~/.ekko/.env

See code: src/commands/init.js

`ekko jwt APPNAME`

Generate JSON Web Tokens for an ekko application

USAGE
  $ ekko jwt APPNAME

ARGUMENTS
  APPNAME  Name of ekko realtime application that you would like to create JWTs for

DESCRIPTION
  ...
  Generate the JSON Web Tokens (JWTs) for your ekko application.

  This command takes a required argument: the name of the app for which you want to generate JSON Web Tokens.

  It will print the following:

  - the API endpoint of your ekko infrastructure
     - your server and client code need this to connect to your ekko infrastructure
     - this is the same value that init outputs for a new deployment and is the same value for all applications
  - user JWT to be used in your client side code
  - admin JWT to be used in your server side code

See code: src/commands/jwt.js

`ekko status`

List your ekko functions and their deployment status

USAGE
  $ ekko status

DESCRIPTION
  ...
  Lists the function folders that exist in your ekko_functions directory. If a function has been deployed to AWS Lambda 
  using the ekko-cli, it is listed as (deployed). 

  Please note:

  - A function listed as (deployed) is not necesarily syncronized with its AWS Lambda version.
  - It is the responsiblity of the developer to update Lambdas by running the update command when they make changes to a 
  local ekko function.

See code: src/commands/status.js

`ekko teardown`

Tear down your ekko infrastructure on AWS

USAGE
  $ ekko teardown

DESCRIPTION
  ...
  Removes all Lambdas deployed with Ekko.

  Removes all server and shared resources infrastructure from AWS and deletes your global ~/.ekko config directory.
  This command does not delete you ekko project directory. 

  It is recommended to remove your cloud infrastructure if you are not actively developing your application.
  Remember that AWS charges you for the time your infrastructure is up and running.

See code: src/commands/teardown.js

`ekko update FILENAME`

Update associations.json or a deployed AWS Lambda function

USAGE
  $ ekko update FILENAME

ARGUMENTS
  FILENAME  associations.json or the name of the ekko function that you would like to update.

DESCRIPTION
  ...
  This command takes a required argument, either 'associations.json' or the name of a function that has already been 
  deployed to AWS Lambda.

  If the argument passed in is 'associations.json', this command will upload an updated version of the file to S3, and 
  will update the server to propagate the new association rules.

  If the argument passed in is a valid deployed AWS Lambda function, this command will update that Lambda with any 
  changes that have been made in the directory of the ekko function.

See code: src/commands/update.js

ekko-realtime-cli

Ekko-cli

Usage

Getting Started

Prerequisites

Installation

First Time Usage

Removing Ekko

FAQ

I quit the `ekko init` command while it was in the middle of deploying infrastructure. Is there a way to tear down my infrastructure?

What infrastructure does Ekko spin up on my behalf?

Does Ekko apply tags to the infrastructure that gets spun up by the CLI?

Do I have to use the Ekko skeleton folder?

Do I have to use the ekko_functions folder?

Can I have more than one ekko_functions repository?

Why am I getting this error?: `Command can't be run outside of ekko_functions directory.`

Commands

`ekko config`

`ekko create FUNCTIONNAME`

`ekko deploy FUNCTIONNAME`

`ekko destroy FUNCTIONNAME`

`ekko help [COMMAND]`

`ekko init`

`ekko jwt APPNAME`

`ekko status`

`ekko teardown`

`ekko update FILENAME`

Readme

Keywords

Package Sidebar

Install

Repository

Homepage

Weekly Downloads

Version

License

Unpacked Size

Total Files

Last publish

Collaborators

ekko-realtime-cli

Ekko-cli

Usage

Getting Started

Prerequisites

Installation

First Time Usage

Removing Ekko

FAQ

I quit the ekko init command while it was in the middle of deploying infrastructure. Is there a way to tear down my infrastructure?

What infrastructure does Ekko spin up on my behalf?

Does Ekko apply tags to the infrastructure that gets spun up by the CLI?

Do I have to use the Ekko skeleton folder?

Do I have to use the ekko_functions folder?

Can I have more than one ekko_functions repository?

Why am I getting this error?: Command can't be run outside of ekko_functions directory.

Commands

ekko config

ekko create FUNCTIONNAME

ekko deploy FUNCTIONNAME

ekko destroy FUNCTIONNAME

ekko help [COMMAND]

ekko init

ekko jwt APPNAME

ekko status

ekko teardown

ekko update FILENAME

Readme

Keywords

Package Sidebar

Install

Repository

Homepage

DownloadsWeekly Downloads

Version

License

Unpacked Size

Total Files

Last publish

Collaborators

I quit the `ekko init` command while it was in the middle of deploying infrastructure. Is there a way to tear down my infrastructure?

Why am I getting this error?: `Command can't be run outside of ekko_functions directory.`

`ekko config`

`ekko create FUNCTIONNAME`

`ekko deploy FUNCTIONNAME`

`ekko destroy FUNCTIONNAME`

`ekko help [COMMAND]`

`ekko init`

`ekko jwt APPNAME`

`ekko status`

`ekko teardown`

`ekko update FILENAME`

Weekly Downloads