upmk docs

upmk install <path-to-addon>

upmk will look for an .upmk-ignore file in the root of your addon for files to ignore while installing your addon. this file should be one relative file path per line (relative path from within the addon) to files which should be skipped during install

if a post-install.sh file is found in the root of the addon, upmk will run that shell script as the last step in the install process. the post install script will be run with the current working directory being the location that the command is ran from (the location of the upmk project to which you are installing the addon). The script will be passed the path to the current addon location as it's only argument for your use in the script.

allows for encrypting / decrypting secrets.yml file. so that secrets and be stored in the repo in an encrypted way

encrypt secrets.yml to secrets.yml.gpg decrypt secrets.yml.gpg to secrets.yml

upmk secrets encrypt

upmk secrets decrypt

upmk secrets generate

the above will generate a new key that you can paste into secrets.key

aliased as restart

prompts for an ssh user, validates some config settings, and executes the bin/restart-<environment>.sh script over ssh on the environment's box

upmk deploy <environment>

for example:

upmk deploy staging

runs bin/watch-build.sh which uses onchange to watch for changes and trigger the appropriate build via upmk build

adds a small dyna-um (small pre-config'd polka app) to your project, changes out your Dockerfile for deploying this app with the node backing app

upmk dyna init

clears out /static and builds all sass, js, views, assets into /static

upmk build [sass, js, views, assets] [--mode development]

optionally pass the specific builds you want to run (runs all of them by default)

default parameters:

mode: development

the upmk cli will generate models, pages, addons, and model instances

model

Add a model to project by building a schema into app/config/db/<name>.json

upmk generate model <model-name> <attributes> ...

for example:

upmk g model person name:string:required avatar:asset:required joined:date

attributes are formatted as <attribute-name>:<type>[:required]

valid attribute types are: string, date, number, array, asset, boolean

also supports --addon <somename> to build the schema into an addon

instance

Builds an instance of a given model

upmk g <model-name> <slug> <attributes>

for example:

upmk g person new-hires name:jsk avatar:assets/person/jsk.png joined:2019-09-15

note: slug is a speacial attribute that will also be used to create a file name for your model. don't include a file extension for it

page

Add pages (controller actions, views, js, sass)

upmk g page <controller> <action> [--route "/" --model=""]

for example:

upmk g page root about contact --route "/"

this would:

• create a root_controller.js (if it doesn't exist)
• create about and contact actions on the controller
• add the a default route settings (unless the controller already exists)
• create a javascript/packs/root.js file (if non-existing)
• create a javascript/root/about.js file (if non-existing)
• create a javascript/root/contact.js file (if non-existing)
• import the latter two files into the packs file
• create a styles/packs/root.scss file (if non-existing)
• create a styles/root/about.scss file (if non-existing) with scoped classes
• create a styles/root/contact.scss file (if non-existing) with scoped classes
• create a views/root/about.html.njk file
• create a views/root/contact.html.njk file

addon

Create an add-on for the current project:

upmk g addon <addon-name>

for example:

upmk g addon jsk-blog

would create app/add-ons/jsk-blog/ with the necessary directories / folders to start an addon

• validates that environment exists
• validates version number
• checks that you are on the master branch
• builds the app [same as upmk build --mode <env>]
• docker builds the app tagged with the supplied version
• pushes tagged docker image to repo
• git tags the code with supplied version
• pushes git tag to origin
• updates upmk.yml with the new image for the environment
• creates an executable deploy (restart) script in bin/restart-<environment>.sh

upmk package <environment> <version>

for example:

upmk package staging 0.12.4-rc

the above would build a staging build, docker image, git tags, and ulitmately a bin/restart-staging.sh executable that can be used to trigger the deploy (or a restart of the app at a later date)

the pull command pulls down dirty records (records with changes). it pulls down:

• model instances (editor documents)
• templates
• model schema (editor definitions)
• assets

from the config'd server.

It requires a UPMK_EDITOR_TOKEN env var, which an admin user can get from the edit screen of their account.

See General Syncing Process for more details

the push command pushes up:

• model instances (editor documents)
• templates
• model schema (editor definitions)
• assets

to the configured server. the server location gets configured in the upmk.editor_url key of the upmk.yml config file.

push uses the editor/id_map.yaml file to keep track of editor model IDs that is uses for keeping things in sync. you should check this file into git as it is your saftey net should something go wrong during a upmk push or a upmk pull

this command requires the UPMK_EDITOR_TOKEN env var to be available

UPMK_EDITOR_TOKEN=<your-user-token> upmk push

If there are dirty records in the editor, it will fail and prompt you to use the --force option. Doing so will push up your local changes, and in the process should reset any dirty flags in the editor.

General Syncing Process

The general process for syncing data with the editor should be:

• create a branch locally
• pull down any changes
  • build and verify locally
  • commit / PR / merge the changes to master
• back on master push changes with --force

git checkout -b recent-changes
UPMK_EDITOR_TOKEN=<token> upmk pull
git add .
git commit -m 'recent changes'
git checkout master
git merge recent-changes
UPMK_EDITOR_TOKEN=<token> upmk push --force

Pulls all filters into editor/filters/build to build out a single filters file and nunjucks instance for the upmk-editor

There are two sets of filters:

1. default filters available from upmk
2. custom filters that you build into render/filters/

In order to include your filters in the editor, you need to ensure that they are listed by name in the editor/filters/build/index.js file. The default upmk filters are already there, any filters you create need to be added by name.

Once your filters are listed, running:

upmk filters

Will copy the filter files of both default and custom filters into the build and directory above, npm install inside the build directory, and run webpack from the included config

This will result in two files:

1. editor/filters/index.js
2. app/assets/editor/filters.js

The later is a copy of the former. The later file will be uploaded to the editor when you upmk push

You will need to add /assets/editor/filters.js to your organization's js_includes. Doing so will add that js file as a script tag on the page when editing any documents. Thus giving you access to all your templating filters in the editor as well.