@undesigned/cygnus

v0.0.18

Published

2 years ago

JAMStack Framework

Downloads

0High
0Medium
0Low

davideperozzi

oclif

@undesigend/cygnus

Fetch and render content into hugo from an external service

Installation

npm install -g @undesigend/cygnus

Docker

Cygnus comes with a pre-built docker container. You should consider using this container, especially for production.

app:
  image: undesigend/cygnus:X.X.X

  # All volume mappings. Make sure to not just mount the src folder directly.
  # This could lead to unwanted files in your working directory
  volumes:
    # Example forlders for your assets. For more check out:
    # https://gohugo.io/hugo-pipes/introduction/#asset-directory
    - ./scripts:/src/assets/scripts
    - ./styles:/src/assets/styles

    # These are the hugo layouts. For more information see here:
    # https://cloudcannon.com/community/learn/hugo-tutorial/layouts-in-hugo/#what-s-a-layout
    - ./layouts:/src/layouts

    # Static files to serve directly (e.g. images). For more check out:
    # https://gohugo.io/content-management/static-files/
    - ./static:/src/static

    # This is a specific folder you can use to organize your configuration.
    # This is also included in the watcher, so changes will be detected
    - ./config:/src/config

    # The config file of your app
    - ./config.ts:/src/config.ts

    # tsconfig, node_modules, pacakge.json for bundling and compiling
    - ./tsconfig.json:/src/tsconfig.json
    - ./node_modules:/src/node_modules
    - ./package.json:/src/package.json
  environment:
    # Defines the environment used in your app. Default: production.
    # If set to dev, it'll start the hug server automatically
    ENVIRONMENT: 'dev'

    # This defines the secret to access. If this is empty the generation endpoint
    # will be public. So it's highly recommended to set it.
    SERVER_SECRET: xx-random-xx-openssl-xx-string-xx

    # The path for the reverse proxy, which points to the generation server
    # Default value: 11B368FF15C711A1A45DCFF68E74D190
    GENERATION_PATH: 11B368FF15C711A1A45DCFF68E74D190

    # Arguments attached to the hugo build command
    # For more see here: https://gohugo.io/commands/hugo/#options
    BUILD_ARGS: "gc,logFile=/tmp/hugo.log"

    # Arguments attached to the hugo server command
    # For more see here: https://gohugo.io/commands/hugo_server/#options
    DEV_SERVER_ARGS: "disableFastRender,gc"

    # The base url to serve images etc. from
    APP_BASE_URL: http://app.cygnus.localhost/

    # The endpoint to the api, used in `query` command
    API_ENDPOINT: http://api.cygnus.localhost/

    # The seconds to wait before aborting the waiting for the api endpoint
    # Default: 180
    API_WAIT_TIMEOUT: 360

General structure

Structure

Services and exposed ports

This pacakge runs nginx in the background and cygnus in the foreground. This means we basically have two (three in development) servers running in one container. To reduce the number of exposed ports cygnus serves the generation service (the one you call when you want to rebuild) through an nginx proxy, defined by the environment variable $GENERATION_PATH.

Now you have two ways to attach to the exposed ports. If you're in production you want to connect to port 8080, which is used by nginx. If you're in development you want to use the port 7652, which attaches to the hugo server command.

Since hugo server is not available when ENVIRONMENT != "dev", this service will be unavailable in production environments

Connect the generation service via a webhook

If you want to connect the generation service to a webhook (e.g. a headless CMS), you simply use the following format:

{PROTOCOL}://{HOST:3000}/{GENERATION_PATH}/generate?secret={SECRET}

# Example
https://undesigned.studio/11B368FF15C711A1A45DCFF68E74D190/generate?secrect=84jf

Now everytime the webhook gets executed a rebuild will happen. Easy.

You have to access this resource via a POST request

Commands

`cygnus generate`

Generates content via config

USAGE
  $ cygnus generate [-h] [-c <value>] [--skipScripts] [--skipStyles] [--builDelay <value>] [--outputPath
    <value>]

FLAGS
  -c, --config=<value>  [default: ./config.ts] Path to the config file
  -h, --help            Show CLI help.
  --builDelay=<value>   [default: 10] The delay before starting the build
  --outputPath=<value>  [default: dist] Where to put all the compiled files
  --skipScripts         Whether to skip the build of scripts
  --skipStyles          Whether to skip the build of styles

DESCRIPTION
  Generates content via config

EXAMPLES
  $ cygnus generate --config=./config.ts

See code: dist/commands/generate/index.ts

`cygnus help [COMMAND]`

Display help for cygnus.

USAGE
  $ cygnus help [COMMAND] [-n]

ARGUMENTS
  COMMAND  Command to show help for.

FLAGS
  -n, --nested-commands  Include all nested commands in the output.

DESCRIPTION
  Display help for cygnus.

See code: @oclif/plugin-help

`cygnus plugins`

List installed plugins.

USAGE
  $ cygnus plugins [--core]

FLAGS
  --core  Show core plugins.

DESCRIPTION
  List installed plugins.

EXAMPLES
  $ cygnus plugins

See code: @oclif/plugin-plugins

`cygnus plugins:install PLUGIN...`

Installs a plugin into the CLI.

USAGE
  $ cygnus plugins:install PLUGIN...

ARGUMENTS
  PLUGIN  Plugin to install.

FLAGS
  -f, --force    Run yarn install with force flag.
  -h, --help     Show CLI help.
  -v, --verbose

DESCRIPTION
  Installs a plugin into the CLI.

  Can be installed from npm or a git url.

  Installation of a user-installed plugin will override a core plugin.

  e.g. If you have a core plugin that has a 'hello' command, installing a user-installed plugin with a 'hello' command
  will override the core plugin implementation. This is useful if a user needs to update core plugin functionality in
  the CLI without the need to patch and update the whole CLI.

ALIASES
  $ cygnus plugins add

EXAMPLES
  $ cygnus plugins:install myplugin 

  $ cygnus plugins:install https://github.com/someuser/someplugin

  $ cygnus plugins:install someuser/someplugin

`cygnus plugins:inspect PLUGIN...`

Displays installation properties of a plugin.

USAGE
  $ cygnus plugins:inspect PLUGIN...

ARGUMENTS
  PLUGIN  [default: .] Plugin to inspect.

FLAGS
  -h, --help     Show CLI help.
  -v, --verbose

DESCRIPTION
  Displays installation properties of a plugin.

EXAMPLES
  $ cygnus plugins:inspect myplugin

`cygnus plugins:install PLUGIN...`

Installs a plugin into the CLI.

USAGE
  $ cygnus plugins:install PLUGIN...

ARGUMENTS
  PLUGIN  Plugin to install.

FLAGS
  -f, --force    Run yarn install with force flag.
  -h, --help     Show CLI help.
  -v, --verbose

DESCRIPTION
  Installs a plugin into the CLI.

  Can be installed from npm or a git url.

  Installation of a user-installed plugin will override a core plugin.

  e.g. If you have a core plugin that has a 'hello' command, installing a user-installed plugin with a 'hello' command
  will override the core plugin implementation. This is useful if a user needs to update core plugin functionality in
  the CLI without the need to patch and update the whole CLI.

ALIASES
  $ cygnus plugins add

EXAMPLES
  $ cygnus plugins:install myplugin 

  $ cygnus plugins:install https://github.com/someuser/someplugin

  $ cygnus plugins:install someuser/someplugin

`cygnus plugins:link PLUGIN`

Links a plugin into the CLI for development.

USAGE
  $ cygnus plugins:link PLUGIN

ARGUMENTS
  PATH  [default: .] path to plugin

FLAGS
  -h, --help     Show CLI help.
  -v, --verbose

DESCRIPTION
  Links a plugin into the CLI for development.

  Installation of a linked plugin will override a user-installed or core plugin.

  e.g. If you have a user-installed or core plugin that has a 'hello' command, installing a linked plugin with a 'hello'
  command will override the user-installed or core plugin implementation. This is useful for development work.

EXAMPLES
  $ cygnus plugins:link myplugin

`cygnus plugins:uninstall PLUGIN...`

Removes a plugin from the CLI.

USAGE
  $ cygnus plugins:uninstall PLUGIN...

ARGUMENTS
  PLUGIN  plugin to uninstall

FLAGS
  -h, --help     Show CLI help.
  -v, --verbose

DESCRIPTION
  Removes a plugin from the CLI.

ALIASES
  $ cygnus plugins unlink
  $ cygnus plugins remove

`cygnus plugins:uninstall PLUGIN...`

Removes a plugin from the CLI.

USAGE
  $ cygnus plugins:uninstall PLUGIN...

ARGUMENTS
  PLUGIN  plugin to uninstall

FLAGS
  -h, --help     Show CLI help.
  -v, --verbose

DESCRIPTION
  Removes a plugin from the CLI.

ALIASES
  $ cygnus plugins unlink
  $ cygnus plugins remove

`cygnus plugins:uninstall PLUGIN...`

Removes a plugin from the CLI.

USAGE
  $ cygnus plugins:uninstall PLUGIN...

ARGUMENTS
  PLUGIN  plugin to uninstall

FLAGS
  -h, --help     Show CLI help.
  -v, --verbose

DESCRIPTION
  Removes a plugin from the CLI.

ALIASES
  $ cygnus plugins unlink
  $ cygnus plugins remove

`cygnus plugins update`

Update installed plugins.

USAGE
  $ cygnus plugins update [-h] [-v]

FLAGS
  -h, --help     Show CLI help.
  -v, --verbose

DESCRIPTION
  Update installed plugins.

`cygnus server`

Starts an api service to access the generator

USAGE
  $ cygnus server [-h] [-c <value>] [-s <value>] [-h <value>] [-p <value>] [-w <value>] [--builDelay
    <value>] [--genDelay <value>] [--skipScripts] [--skipStyles] [-d] [--devServerPort <value>] [--devServerHost
    <value>] [--outputPath <value>]

FLAGS
  -c, --config=<value>     [default: ./config.ts] Path to the config file
  -d, --devServer          Whether to start the dev server. Default = no
  -h, --help               Show CLI help.
  -h, --host=<value>       [default: 0.0.0.0] The server hostname
  -p, --port=<value>       [default: 3000] The port for the server
  -s, --secret=<value>     Secret parameter to add to your URL (http://...?secret=XX)
  -w, --watch=<value>      Comma separated list of files and dirs to watch
  --builDelay=<value>      [default: 10] The delay before starting the build
  --devServerHost=<value>  [default: 0.0.0.0] The dev server hostname
  --devServerPort=<value>  [default: 8472] The port of the dev server
  --genDelay=<value>       [default: 0] The delay before starting the generation
  --outputPath=<value>     [default: dist] Where to put all the compiled files
  --skipScripts            Whether to skip the build of scripts
  --skipStyles             Whether to skip the build of styles

DESCRIPTION
  Starts an api service to access the generator

EXAMPLES
  $ cygnus server --secret=test123 --config=./config.ts

  $ cygnus server --devServer --config=./config.ts

See code: dist/commands/server/index.ts

Development

To release a new version simply run yarn version --(major|minor|patch) to update the package.json and then just git push origin master. Our CI/CD will handle the rest. It will also deploy the corresponding docker image.

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

@undesigend/cygnus

Installation

Docker

General structure

Services and exposed ports

Connect the generation service via a webhook

Commands

cygnus generate

cygnus help [COMMAND]

cygnus plugins

cygnus plugins:install PLUGIN...

cygnus plugins:inspect PLUGIN...

cygnus plugins:install PLUGIN...

cygnus plugins:link PLUGIN

cygnus plugins:uninstall PLUGIN...

cygnus plugins:uninstall PLUGIN...

cygnus plugins:uninstall PLUGIN...

cygnus plugins update

cygnus server

Development

`cygnus generate`

`cygnus help [COMMAND]`

`cygnus plugins`

`cygnus plugins:install PLUGIN...`

`cygnus plugins:inspect PLUGIN...`

`cygnus plugins:install PLUGIN...`

`cygnus plugins:link PLUGIN`

`cygnus plugins:uninstall PLUGIN...`

`cygnus plugins:uninstall PLUGIN...`

`cygnus plugins:uninstall PLUGIN...`

`cygnus plugins update`

`cygnus server`