JAMStack Framework
npm install @undesigned/cygnussh
npm install -g @undesigend/cygnus
`Docker
Cygnus comes with a pre-built docker container. You should consider using this container,
especially for production.
Here are all available options:
yaml
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 .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:`bash
{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
requestCommands
* cygnus generate
* [](#cygnus-help-command)
* cygnus plugins
*
*
*
*
*
*
*
*
* Generates content via config
USAGE
$ cygnus generate [-h] [-c ] [--skipScripts] [--skipStyles] [--builDelay ] [--outputPath
]FLAGS
-c, --config= [default: ./config.ts] Path to the config file
-h, --help Show CLI help.
--builDelay= [default: 10] The delay before starting the build
--outputPath= [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_
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_
List installed plugins.
USAGE
$ cygnus plugins [--core]FLAGS
--core Show core plugins.
DESCRIPTION
List installed plugins.
EXAMPLES
$ cygnus plugins
_See code: @oclif/plugin-plugins_
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
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
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
Links a plugin into the CLI for development.
USAGE
$ cygnus plugins:link PLUGINARGUMENTS
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
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
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
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
Update installed plugins.
USAGE
$ cygnus plugins update [-h] [-v]FLAGS
-h, --help Show CLI help.
-v, --verbose
DESCRIPTION
Update installed plugins.
Starts an api service to access the generator
USAGE
$ cygnus server [-h] [-c ] [-s ] [-h ] [-p ] [-w ] [--builDelay
] [--genDelay ] [--skipScripts] [--skipStyles] [-d] [--devServerPort ] [--devServerHost
] [--outputPath ]FLAGS
-c, --config= [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= [default: 0.0.0.0] The server hostname
-p, --port= [default: 3000] The port for the server
-s, --secret= Secret parameter to add to your URL (http://...?secret=XX)
-w, --watch= Comma separated list of files and dirs to watch
--builDelay= [default: 10] The delay before starting the build
--devServerHost= [default: 0.0.0.0] The dev server hostname
--devServerPort= [default: 8472] The port of the dev server
--genDelay= [default: 0] The delay before starting the generation
--outputPath= [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 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.