Splunk Application boilerplate, that uses docker for development.
- OS: we are primarily using
macOS
for development, these scripts probably will work on Linux, but require some testing. For Windows, we can recommend using Linux Subsystem for Windows. Patches are welcome. - Docker. We are testing and using Docker for Mac CE (
18.03.1
at the moment).
Here and below we use
appdemo
as an application name (or folder name) that we want to use for our application.
Create a folder for your project
mkdir splunk-appdemo && cd splunk-appdemo
Download the latest version from the master and untar it directly to the just created folder
curl -L https://github.com/outcoldsolutions/splunk-app-boilerplate/archive/v1.1.tar.gz | tar xvz --strip 1
You you can use the latest
https://github.com/outcoldsolutions/splunk-app-boilerplate/archive/master.tar.gz
Initialize git
git init && git add . && git commit -m "Splunk Application Boilerplate"
Rename the application from appboilerplate
to appdemo
(if that an application
name you want to use) and update the files, that depends on that name
APPNAME=appdemo
mv appboilerplate ${APPNAME}
sed -i '' "s/appboilerplate/${APPNAME}/" Makefile .gitignore ${APPNAME}/default/app.conf hack/splunk/etc/users/admin/user-prefs/local/user-prefs.conf
Use your README.md file and rename the LICENSE
to the LICENSE-splunk-app-boilerplate
,
so you can define your LICENSE
for the application (if you want to publish it
as an open source project).
cat <<- EOF > README.md
# ${APPNAME}
> built with https://github.com/outcoldsolutions/splunk-app-boilerplate
EOF
mv LICENSE LICENSE-splunk-app-boilerplate
Commit the changes
git add . && git commit -m "Renaming boilerplate to ${APPNAME}"
Start Splunk
make splunk-up
It takes some time to start Splunk, append the configurations, you can follow the progress with
make splunk-logs-follow
When it is done you can open the Splunk Web with
make splunk-web
That automatically will bring you to your application in Splunk Web, already logged in.
If you are modifying files locally on disk, you need to tell Splunk to refresh them, open the refresh page
make splunk-refresh
You can also specify which parts you want to refresh with query parameters, that will make refresh much quicker. As an example, to refresh only views, you can open an URL
localhost:8000/en-US/debug/refresh?entity=data/ui/views
You can request your Splunk Development License at Splunk Developer License Signup
Keep your license as hack/splunk/licenses/*.lic
, when you will start the Splunk instance,
licenses from this folder will be automatically loaded. Pattern hack/splunk/licenses/*.lic
included in the .gitignore
file, so it is not going to be saved in your git repo.
You can define base configuration under hack/splunk/etc
for your Splunk instance.
By default we predefine some configurations, like
-
Cache is disabled, see About file precedence and caching. That allows developing applications with JavaScript code. Browser still can cache your JavaScript. Use
make splunk-refresh
to open a page, that let you reload dashboards and other configuration files. -
Minification is turned off for JavaScript and CSS files.
-
Insecure logins are enabled, that allows us to authenticate with GET requests (forget about login page).
-
Default session timeouts increased to 30 days.
-
Telemetry dialog already acknowledged.
-
HTTP Event Collector is enabled with Token
00000000-0000-0000-0000-000000000001
-
hack/splunk/etc/users/admin/user-prefs/local/user-prefs.conf
has some default user settings for admin user, like Dark mode for SPL editor (developers like dark themes)
You can modify all the files or add new under hack/splunk/etc
. When you run
make splunk-up
these files are used for bootstrapping the
Splunk instance. Changing files after make splunk-up
does not have effect
on already bootstrapped Splunk instance, you need tear it down first make splunk-down
and bootstrap again make splunk-up
.
In the Makefile
there are two version strings that you want to update, when
updates are available. SPLUNK_IMAGE
points to the Splunk image,
and APPINSPECT_IMAGE
points to the image with latest AppInspect.
You can create a symbolic link from appdemo/default/data
to appdemo/local/data
.
ln -s ../default/data appboilerplate/local/data
In that way, when you modify the dashboard using Splunk Web
the changes are saved to the default
folder.
We use Vagrant a lot to test various environments. One cool hack about Vagrant
that you can access the host using IP address 10.0.2.2
, so to access you HTTP
Event Collector you can use
curl -k https://10.0.2.2:8088/services/collector/event/1.0 -H "Authorization: Splunk 00000000-0000-0000-0000-000000000001" -d '{"event": "hello world"}'
When it is ready for prime time, you can pack your application and upload on splunkbase
Make sure that you move all of the configurations and changes from
appdemo/local
to appdemo/default
, and from appdemo/metadata/local.meta
to
appdemo/metadata/default.meta
, after that, you can run
Command below deletes
appdemo/local
andappdemo/metadata/local.meta
!
make app-clean
Verify with Splunk AppInspect that your application meets the guidelines (not required, but preferable)
make app-inspect
Fix all the issues, if you see some (the appboilerplate
does not meet the
guidelines)
make app-pack
Upload your application from out/appdemo.tar.gz
.
MIT License
We are happy to review and merge Pull Requests, but please keep in mind:
- Default configurations for Splunk instance should be minimum, but at the same time allowing you to start quickly.
- If you aren't sure if a change should be made, open a ticket for discussion.