Development¶
Notes on developing tailon, the front-end asset build flow and a list of long-standing TODOs.
Prerequisites¶
Generating tailon’s front-end assets requires bower, webassets, invoke and autoprefixer. Everything can be installed by running the following commands in the repository root:
$ pip install -r requirements-dev.txt
$ npm install
Front-end assets¶
Tailon’s asset pipeline uses bower, webassets and several invoke tasks that tie them together. The tree structure of relevant files is as follows:
. <root>
|-- bower_components/ # 'bower install' download location (git ignored)
|-- bower.json # list of pinned front-end requirements
|-- setup.py
|-- tasks.py # build configuration (uses the invoke tool)
|-- webassets.yaml # asset pipeline configuration
`-- tailon/assets
|-- fonts/
|-- gen/
|-- js/
|-- scss/
`-- vendor/
Bower is used to fetch tailon’s front-end dependencies. When bower install
is ran in
the root of the project, the assets listed in bower.json
are downloaded to the
bower_components
directory.
With the help of the inv collectstatic
task, all source files in bower_components
are copied to tailon/assets/vendor
. Note that unlike bower_components
, this
directory is committed to git.
Running inv webassets
generates the files in inv tailon/assets/gen
.
These are the assets that end up in the tailon source distribution that is
uploaded to PyPi. The rules that govern the asset pipeline are defined in
webassets.yaml
. In short, the following transformations are applied:
tailon/assets/scss/* --> compile,minify --> tailon/assets/gen/main.css
tailon/assets/vendor/* --> jsmin --> tailon/assets/gen/3rdparty.js
tailon/assets/Main.js --> rmconsole,jsmin --> tailon/assets/gen/js/Main.min.js
The tailon/assets/Main.js
file is generated from the typescript sources in
tailon/assets/js
. The process is handled by the compile_typescript
task.
The assets links find their way into the templates/base.html
template
through the webassets --replace
task. It simply replaces the html between
the WEBASSETS CSS
and WEBASSETS JS
placeholders with the links to the
compiled, minified and concatenated scss and js files. For example:
<link rel='stylesheet' href='{{root}}assets/gen/main.css'>
<script src='{{root}}assets/gen/3rdparty.js'></script>
<script src='{{root}}assets/gen/main.js'></script>
You may also want to skip the minification and concatenation steps with the
--debug
option.
Development data¶
You may use the inv logsim_start
and in logsim_start
tasks to generate
random logfiles that you can monitor with tailon.
FAQ¶
I just want to make a small change to the frontend code or styles. What do I do?
Modify the typescript or scss files in
tailon/assets
and run:# Compile and minify SCSS; Concatenate and minify JS. $ inv webassets --replace # Without minifying and concatenating JS (usefuly for debugging). $ inv webassets --replace --debug
Adding or updating a third-party dependency:
# Run after adding the dependency to the bower.json file. $ bower install $ inv collectstatic # Copies from bower_components to tailon/assets/vendor. $ inv webassets --replace --no-expire
TODO¶
- There are still parts of the UI that haven’t been implemented.
- Fix styling issues related to selectize.
- Visual/Audible alarms on log activity.
- Interface themes.
- Improved windows support.
- Investigate the use of seccomp on Linux for unsafe commands.
- Handling of different tool versions (i.e. GNU awk vs BSD awk).