Splunk Web Framework
Python JavaScript Other
Latest commit a417955 Mar 8, 2014 @itay itay Release 1.0.2

README.md

The Splunk Web Framework

Version 1.0 GA

The Splunk Web Framework lets developers quickly create custom Splunk apps by using prebuilt components, styles, templates, and reusable samples, and by adding custom logic, interactions, and UI. Applications developed with the Web Framework work seamlessly side by side with current Splunk applications.

The Splunk Web Framework uses the Django web framework, the Splunk SDK for Python, and the Splunk SDK for JavaScript. The Web Framework also depends on a few JavaScript libraries for the client-side of code, such as Backbone.js for eventing, and jQuery for working with the document object model (DOM).

The version of the Splunk Web Framework contained in this repository is designed to work in a standalone mode to work against Splunk 5.x. If you are using Splunk 6, the Splunk Web Framework is included within the core Splunk product. You can use the standalone version of the Web Framework with Splunk 6, but this is only useful for very specific and advanced use cases.

Note Significant changes have been made since the Preview release, such as names of components and APIs and the way components are instantiated in JavaScript. Any code you created for the Preview of the Splunk Web Framework will not work with the GA release. Overall concepts of the Web Framework remain the same. See the Splunk Developer Portal for more information.

If you have any questions, contact devinfo@splunk.com.

Getting started

This section provides information about installing the Web Framework, running it, and creating an app.

Requirements

Here are the Web Framework requirements for this release:

  • Operating system: Windows, Linux or Mac OS X.

  • Web browser: Latest versions of Chrome, Safari, or Firefox; Internet Explorer 9 or later.

  • The Splunk Web Framework: The Web Framework is available as a ZIP file from GitHub and as a Git repository.

  • Splunk: Splunk 5.0 or later. If you haven't already installed Splunk, download it here.

    Note The Web Framework is already included with Splunk 6.0 and later.

  • Programming language: Python 2.7.

Install the Web Framework

The Web Framework installation package includes most of what you need to start building complete applications for Splunk, including:

  • The Django web framework. Django 1.5.1 is included, even if you already have another installation of Django.

  • Programming tools. The Splunk SDK for Python is included so that you can programmatically interact with the Splunk engine.

  • JavaScript tools. The Web Framework include several JavaScript client frameworks such as jQuery, Backbone.js, and Bootstrap, along with our own Splunk SDK for JavaScript.

To install the Web Framework

You'll be using the splunkdj tool at the command line to work with the Splunk Web Framework. The splunkdj commands you can use are: deploy, package, install, removeapp, createapp, test, run, start, stop, restart, clean, and setup. To get help with the syntax, enter splunkdj -h.

Note Windows users must run the splunkdj command-line tool with Administrator privileges. Otherwise, the process fails silently, without any errors.

  1. Download and unzip the Web Framework ZIP file.

  2. Open a command prompt, navigate to the directory where you unzipped the Web Framework (the $WEBFRAMEWORK_HOME).

    On Mac OS X and Unix, enter:

      ./splunkdj setup
    

    On Windows, enter:

      splunkdj setup
    

    The setup process asks you to specify where Splunk is installed, then displays the Splunk configuration variables that will be used, such as host names and port numbers. These values are taken from your current Splunk configuration settings, but you can use different values if you need to. After you accept these values (or opt to change them), setup installs the Web Framework and additional tools.

Run the Web Framework

  1. Start Splunk, if it's not running already.

  2. At a command prompt, navigate to $WEBFRAMEWORK_HOME.

    On Mac OS X and Unix, enter:

     ./splunkdj run
    

    On Windows, enter:

     splunkdj run
    
  3. Open http://localhost:3000/dj in a web browser to verify the Web Framework is working.

    Log in using your Splunk credentials, then you'll see the Web Framework home page listing all of the Web Framework apps on your system.

Create an app

When you create an app, the framework generates the new app's directory and its files.

  1. If the framework is running, stop it by pressing Ctrl+C at the command prompt.

  2. At the command prompt, navigate to $WEBFRAMEWORK_HOME.

    On Mac OS X and Unix, enter the following, where your_app_name is the case-sensitive name of your app:

     ./splunkdj createapp your_app_name
    

    On Windows, enter:

     splunkdj createapp your_app_name
    

    You'll need to provide your Splunk credentials to create the app.

A your_app_name directory is created in $SPLUNK_HOME/etc/apps/ with auto-generated project files, including:

  • /default/app.conf: Contains the meta data (author, description, version) for your app. Edit this file in a text editor to fill in the details. Note that you'll need to restart Splunk to see changes to this file.

  • /django/your_app_name/templates/home.html: The default home page, which is displayed when you go to http://localhost:3000/dj/your_app_name/.

To run your app:

  1. Start the framework--at the command prompt, navigate to $WEBFRAMEWORK_HOME.

    On Mac OS X and Unix, enter:

     ./splunkdj run
    

    On Windows, enter:

     splunkdj run
    
  2. Open the Web Framework home page at http://localhost:3000/dj, where you'll see your new app listed with the other apps.

Note These apps are also displayed in Splunk Web, but you can't run them from the Splunk Web port. The Web Framework apps can only be run in the Web Framework proxy port, which is 3000 by default.

Documentation

To learn how to use the Web Framework, see the Web Framework on the Splunk Developer Portal.

The documentation applies to the integrated version of the Web Framework in Splunk 6.0 and later. However, if you are using the stand-alone version of the Web Framework, there are a few differences to note:

  • The SplunkMap view is not supported in Splunk 5.0. Use GoogleMap view instead. The path for this view is splunkjs/mvc/googlemapview, and the template tag is {% googlemap %}.

  • Where the documentation uses the Splunk Web port (8000), use the Web Framework proxy port (3000) instead.

  • Where the documentation instructs you to restart Splunk Web, restart the Web Framework instead (splunkdj run).

Repository

cli This directory contains the Splunk Web Framework utility script
contrib This directory contains third-party tools and libraries
proxy This directory contains the development web server
server This directory contains the source for the framework and apps

Branches

The master branch always represents a stable and released version of the framework.

Documentation and resources

When you need to know more:

Community

Stay connected with other developers building on Splunk.

Email devinfo@splunk.com
Issues https://github.com/splunk/splunk-appframework/issues/
Answers http://splunk-base.splunk.com/tags/appfx/
Blog http://blogs.splunk.com/dev/
Twitter @splunkdev

How to contribute

If you would like to contribute to the framework, go here for more information:

Support

This GA version of the Splunk Web Framework is officially supported by the Splunk Support Team.

Please feel free to open issues and provide feedback either through GitHub Issues or by contacting the team directly.

Contact Us

You can reach the Developer Platform team at devinfo@splunk.com.

License

The Splunk Web Framework is licensed under the Apache License 2.0. Details can be found in the LICENSE file.