Cypress CookieCutter

Rapid Splunk App development using CookieCutter templates

Latest Release: v1.11.5

Templates

Templates	Type	Description
app-simple	Base	Simple App or Add on for Splunk with simple packaging capabilities
app-python	Base	App or Add on with Python support
custom-conf	Extension	Add support for a custom configuration file type, optionally with UI configuration page
custom-rest	Extension	Support a custom Splunkd persistent non-EAI REST interface
alert-rest	Component	Modular alert and ES Adaptive Response that triggers a REST call
search-command	Component	Expand search-time capabilities using a custom Splunk SPL command written in Python
modinput-rest	Component	Ingest custom data from a REST API using Python

Custom Fields

Many of the above templates support a set of custom fields for template-specific purposes. A common field reference is shared across for keeping things as simple as possible.

Using Templates

These templates are built using the crispy_cookie CLI tool (which is a wrapper extending the excellent cookiecutter tool). Crispy Cookie can be installed or updated using any normal Python packaging technique, but typically can be accomplished by running:

pip install -U crispy_cookie

Simple use case

Simple apps can be created with a single command:

crispy_cookie config --build git@github.com:Kintyre/cypress-cookiecutter.git --checkout v1.11.5 app-simple

Note: that the above command requires crispy_cookie 1.7.0 or later.

Next, run steps listed in Post-creation steps below.

Layered use case

Anything but the most simple app will use the more advanced layered approach which combines features from multiple templates at once. For example, to create a custom search command that has API access to backend server would build on top app-python, use custom-conf to store server definitions securely with a configuration page, and search-command layer to build the actual search command. If later an additional search command is needed, simply add another search-command layer. This mix-n-match approach is very flexible and builds on top of ksconf's layer handling abilities to keep features cleanly separated.

pip install -U crispy_cookie

crispy_cookie config git@github.com:Kintyre/cypress-cookiecutter.git --checkout v1.11.5 custom-conf modinput-rest search-command -o NEW_PROJECT.json

crispy_cookie build git@github.com:Kintyre/cypress-cookiecutter.git --checkout v1.11.5 --config NEW_PROJECT.json --output ~/projects

To later re-run the template process to update to a new version, run the following command:

crispy_cookie build git@github.com:Kintyre/cypress-cookiecutter.git --checkout v1.9.9
--output ~/projects/my_project

There's much more to updating, and app, this is the basic idea. See Upgrading apps for more details.

Post-creation steps

# Change into the newly created app folder (substitution required)
cd APP_FOLDER

# Initialize git
git init
git add .

# Enable & install pre-commit hooks
pre-commit install --install-hooks

# Run pre-commit once (ignore output)
pre-commit run -a > /dev/null

# First commit
git commit -am "Initial project created from cypress_cookiecutter v1.11.5"

# Make a new cookiecutter branch (used for template updating)
git branch cookiecutter

Login to github, create a new empty repo, and follow the push an existing repository from the command line instructions provided there, such as:

git remote add origin https://github.com/Kintyre/APP_FOLDER.git
git push -u origin main

git push -u origin cookiecutter:cookiecutter

Customizations

Of course a cookiecutter template only goes so far. A few other specific places have been marked as a reminder that should be looked at. Specifically, search all files for the term COOKIECUTTER-TODO. Remove these comments after customization.

From your new project folder, run to get a list of places that still need to be addressed:

find . -type f | xargs fgrep COOKIECUTTER-TODO

Upgrade to the latest template

It's fairly easy to apply the latest template to an existing app (one that was created with, or migrated to, the cypress-cookiecutter framework). Often this can be done with a single command, run from the base of your project:

crispy_cookie update --branch cookiecutter --checkout v1.11.5 .


# Preview merge for conflicts:
git format-patch $(git merge-base HEAD cookiecutter)..cookiecutter --stdout | git apply --3way --check - 2>&1 | grep error

# (Optional)  Create a branch if you want to make PR
git checkout -b cypres-cookiecutter-v1.11.5

# If all goes well, finalized the migration with a merge, resolving any conflicts as you go
git merge cookiecutter

# If you have to revert certain files (to reject incoming changes), you can do so with:
git checkout --ours -- <filename>

# Once merged, you can always see the upgrade "diff" with the command
git show --diff-merges=on

Once everything looks good, you may want push changes to repo and possibly issue a new release.

However, if you run into any issues (like if the cookiecutter branch not existing), please see the Upgrade Apps documentation. If you have an existing app that you'd like to migrate see Retrofit docs, but be aware that this is much more involved and not documented super well.

Need cookiecutter?

You can try either:

# Python install
pip install cookiecutter

# Homebrew install (OS X)
brew install cookiecutter

If you run into any issues see Cookiecutter Installation for more options.

Want to contribute?

Please see the Template Maintenance guide.