@dorfjungs/hunamic

Fetch and render content into hugo from an external service

Installation

npm install -g @dorfjungs/hunamic

Docker

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

Here are all available options:

app:
  image: dorfjungs/hunamic: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.hunamic.localhost/

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

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

General structure

Services and exposed ports

This pacakge runs nginx in the background and hunamic in the foreground. This means we basically have two (three in development) servers running in one container. To reduce the number of exposed ports hunamic 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://dorfjungs.com/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

`hunamic generate`

Generates hugo front matter via a config

USAGE
  $ hunamic generate

OPTIONS
  -b, --buildArg=buildArg  Arg for the hugo build command --buildArg=gc
  -c, --config=config      [default: ./config.ts] Path to the config file
  -h, --help               show CLI help
  --builDelay=builDelay    [default: 10] The delay before starting the build
  --skipBuild              Whether to skip the build and only do the generation

EXAMPLE
  $ humanic generate --config=./config.ts

`hunamic help [COMMAND]`

display help for hunamic

USAGE
  $ hunamic help [COMMAND]

ARGUMENTS
  COMMAND  command to show help for

OPTIONS
  --all  see all commands in CLI

See code: @oclif/plugin-help

`hunamic server`

Starts an api service to access the generator

USAGE
  $ hunamic server

OPTIONS
  -b, --buildArg=buildArg      Arg for the hugo build command --buildArg=gc
  -c, --config=config          [default: ./config.ts] Path to the config file
  -d, --devServer              Whether to start the hugo dev server. Default = no
  -h, --help                   show CLI help
  -h, --host=host              [default: 0.0.0.0] The server hostname
  -p, --port=port              [default: 3000] The port for the server
  -s, --secret=secret          Secret parameter to add to your URL (http://...?secret=XX)
  -w, --watch=watch            Comma separated list of files and dirs to watch
  --builDelay=builDelay        [default: 10] The delay before starting the build
  --devServerArg=devServerArg  Arg for the hugo server command --devServerArg=gc
  --devServerVerbose           Output everything from the dev server, #no-filter
  --genDelay=genDelay          [default: 0] The delay before starting the generation
  --skipBuild                  Whether to skip the build and only do the generation

EXAMPLES
  $ humanic server --secret=test123 --config=./config.ts
  $ humanic server --skipBuild --secret=test123 --config=./config.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.