Nebulous Puffy Marshmallows
    Have ideas to improve npm?Join in the discussion! »

    @byndyusoft/casc
    TypeScript icon, indicating that this package has built-in type declarations

    2.0.0 • Public • Published

    node-casc

    npm@latest test workflow code style: prettier semantic-release

    Configuration as Code solution for Node.js (and not just) 📝 ⚙️

    Introduction

    Source code of the microservice and its configuration for different environments must be versioned and deployed from the same commit. This project takes care of generating config from a template and managing values for different environments.

    Comparison with Helm

    Why don't we just use Helm? Helm is heavily dependent on Kubernetes and this creates problems for various local scripts and migrating applications from Kubernetes to PaaS.

    Feature Helm node-casc
    Container Orchestration Platform Kubernetes No limits
    Microservice runtime No limits No limits
    Runtime for configuration No limits Node.js
    Template language Go templates Handlebars
    Output config format No limits YAML or JSON
    Support secret variables Plugin Built-in
    Cryptography algorithm No limits RSA
    Plugins Yes No

    Requirements

    • Node.js v12 LTS or later
    • npm or yarn

    Install

    npm install @byndyusoft/casc

    or

    yarn add @byndyusoft/casc

    Releases

    From releases you can download:

    • standalone version for Linux, Alpine, Windows and macOS
    • npm package tarball

    Quick start

    Execute in your terminal to initialize CASC directory:

    casc init:dir

    By default CASC directory is $(pwd)/.casc.

    CASC directory structure

    • keys/ - directory with public and private keys for encrypting and decrypting secret values
    • .env - override values.override.yaml through process.env (see dotenv for syntax)
    • config.yaml - application config (see Handlebars for syntax)
    • settings.yaml - CASC settings
    • values.yaml - values for config.yaml
    • values.override.yaml - override values.yaml

    Add files to .gitignore

    • your private key
    • .env
    • values.override.yaml

    config.yaml

    Handlebars helpers:

    • str - convert value to string
    • exists - checks that all values exists

    settings.yaml

    Default settings:

    crypto:
      strategy: rsa
    
    privateKey:
      format: pkcs8-private-pem
      strategies:
        file: private.pem
        env: CASC_PRIVATE_KEY
    
    publicKey:
      format: pkcs8-public-pem
      strategies:
        file: public.pem

    Properties:

    • crypto.strategy - asymmetric cryptography algorithm, only rsa supported
    • privateKey.format - private key format, rsa supports only pkcs8-private-pem
    • privateKey.strategies
      • key of this object is name of private key reading strategy (the order of the keys depends on the order in which the strategies are applied)
      • value of this object is settings for strategy
    • publicKey.format - public key format, rsa supports only pkcs8-public-pem
    • publicKey.strategies
      • key of this object is name of public key reading strategy (the order of the keys depends on the order in which the strategies are applied)
      • value of this object is settings for strategy

    file private or public key reading strategies

    Strategy settings are a string or an array of strings, where each item is a path to a private or public key. The first found key will be read. If the path is relative, then it will be relative to the keys/ directory.

    env private key reading strategy

    Strategy settings are a string or an array of strings, where each item is a key of process.env. The first found key will be read.

    values.yaml and values.override.yaml

    Example structure:

    VALUE_NAME:
      env_name: some value
      other_env_name:
        - some host 1
        - some host 2
        - some host 3
      env_name_with_encrypted_value*: 6JM8YlugHyjnzatv/nOB7A==
      env_name_with_decrypted_value!: secret value
      default: default value if current environment is not found

    Only english letters, digits and underscores are allowed in value names and environments. The digits at the beginning is prohibited. Values can only be strings, numbers, booleans, nulls, or their arrays.

    Usage

    CLI

    We do recommend using this project as a CLI in order to avoid inadvertently affecting your application.

    Build config

    USAGE
      $ casc config:build
    
    OPTIONS
      -c, --cascDir=cascDir    [default: /app/.casc] CASC directory
      -e, --env=env            (required) environment
      -o, --override=override  [default: true] override values
      -y, --yaml=yaml          [default: false] YAML output instead JSON
    

    Init CASC directory

    USAGE
      $ casc init:dir
    
    OPTIONS
      -c, --cascDir=cascDir  [default: /app/.casc] CASC directory
    

    Init RSA keys

    USAGE
      $ casc init:keys:rsa
    
    OPTIONS
      -b, --bits=bits           [default: 2048] RSA key size in bits
      -c, --cascDir=cascDir     [default: /app/.casc] CASC directory
      -f, --format=(pkcs8-pem)  [default: pkcs8-pem] keys format
    

    Decrypt values

    USAGE
      $ casc values:decrypt
    
    OPTIONS
      -c, --cascDir=cascDir  [default: /app/.casc] CASC directory
      -y, --yaml=yaml        [default: true] YAML output instead JSON
    

    Encrypt values

    USAGE
      $ casc values:encrypt
    
    OPTIONS
      -c, --cascDir=cascDir  [default: /app/.casc] CASC directory
      -y, --yaml=yaml        [default: true] YAML output instead JSON
    

    Library

    We do not recommend using this project as a library in order to avoid inadvertently affecting your application.

    How to build config

    import "reflect-metadata";
    
    import {
      container,
      IConfigBuilder,
      IConfigBuilderToken,
      IContextBuilder,
      IContextBuilderToken,
      IValuesReader,
      IValuesReaderToken,
    } from "@byndyusoft/casc";
    
    const configBuilder = container.resolve<IConfigBuilder>(IConfigBuilderToken);
    const contextBuilder = container.resolve<IContextBuilder>(IContextBuilderToken);
    const valuesReader = container.resolve<IValuesReader>(IValuesReaderToken);
    
    const config = await configBuilder.build(
      await contextBuilder.build(
        process.env.NODE_ENV,
        await valuesReader.read(true),
      ),
    );
    
    console.log(config);

    Maintainers

    Install

    npm i @byndyusoft/casc

    DownloadsWeekly Downloads

    4

    Version

    2.0.0

    License

    MIT

    Unpacked Size

    226 kB

    Total Files

    483

    Last publish

    Collaborators

    • avatar
    • avatar
    • avatar
    • avatar