Nonchalant Programming Master

    ekko-realtime-cli

    0.0.31 • Public • Published

    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.

    oclif Version Downloads/week License

    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

    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

    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

    Keywords

    Install

    npm i ekko-realtime-cli

    DownloadsWeekly Downloads

    0

    Version

    0.0.31

    License

    MIT

    Unpacked Size

    53 kB

    Total Files

    26

    Last publish

    Collaborators

    • dpholbrook