|===\ (==== ===== /===\ | ) |-- | |-=-| |===/ (==== | | | ---- Shell build and deploy system foundation. Synopsis -------- Managing an application is executing commands, tasks are highly specific to individual applications. Deta supports you in instantly creating tasks in plain shell script. No extra abstraction layers where you don't need them but a small tool for launching the tasks, a handful of reusable functions and a sane configuration management. Copyright & License ------------------- Deta is Copyright (c) 2011-2014 David Persson if not otherwise stated. The code is distributed under the terms of the MIT License. For the full license text see the LICENSE file. Versions & Requirements ----------------------- 0.1.0 0.2.0 0.3.0 0.4.0 0.5.0 The BASH (Bourne-Again SHell) is required. Deta is continously tested with recent BASH versions on Linux and Darwin. Installation ------------ It is suggested to install deta on a per-project basis. Clone the repository or extract a downloaded archive, then move or copy the resulting directory to /project/lib/deta. Change to the `deta` directory and run make, preferrably with a prefix: $ cd /project/lib/deta $ PREFIX=/project make install This will link the deta tool into the `bin` directory in your project's root directory and copy the default development configuraton into a `config/deta` directory. Thus making the deta tool available as: $ cd /project/bin $ ./deta.sh -c ../config/deta Other setups are possible too but than installation must be performed manually. You can remove the tool (but keep the configuration) by running: $ cd /project/lib/deta $ PREFIX=/project make uninstall Quickstart ---------- 1. Start to edit a new task. $ $EDITOR deploy.sh 2. Source the g11n and transfer modules and require a THIS role. ``` source $DETA/g11n.sh source $DETA/transfer.sh role THIS # ... ``` 3. Our task will clone the project into a temporary directory and recompile all MO files. After the task has finished we want the temporary directory to be deleted. ``` # ... TMP=$(mktemp -d -t deta) defer rm -r $TMP download $THIS_REPO $TMP cd $TMP g11n_compile_mo app/locale # ... ``` 4. Run the tasks through the deta tool. $ ./deta.sh deploy.sh Example Tasks ------------- You can find ready-to-use tasks in the "contrib" subdirectory. Shell Environment Variables --------------------------- There are some environment variables that affect the way deta behaves. DETA_COMPRESSOR_JS Which compressor to use when compressing JavaScript files. Currently "yuicompressor", "closure-compiler" and "uglify-js" (>= 2.0) are supported. For more information see the documentation for compress_js() in the asset module. Defaults to "uglify-js". DETA_COMPRESSOR_CSS Which compressor to use when compressing CSS files. Currently "yuicompressor" "clean-css" and "sqwish" are supported. For more information see the documentation for compress_css() in the asset module. Defaults to "yuicompressor". DETA_CACHE_DIR Directory which holds the cached items for the internal cache. Will be created if it doesn't exist. Caches asset compressions. Defaults to "/tmp/deta_cache". Terminology ----------- Tasks ''''' Tasks are sourced by the deta tool they automatically have access to all the env configurations (loaded from *.conf). Following global variables are always available within tasks: QUIET (y|n), DRYRUN (y|n), DETA (deta directory), TASK (current task) Tasks are plain shell files and share the same interpreter as the deta tool (which is BASH). Tasks can be located wherever you want. In the end you just pass the path to the deta tool. However it is nice to be able to group tasks, therefore it is suggested to create subdirectories directly in the `bin` directory. Modules ''''''' Modules contain sets of functions and are loaded on demand by sourcing them in the beginning of each task. Modules shipped with deta are located in the directory specified by $DETA. Of course you can also built your own modules and load them in a similar way. ``` source $DETA/g11n.sh source $DETA/sys.sh # ... ``` By default the core module is always loaded, making functions as role and defer available in any task. Environments '''''''''''' Environments are inspired by the way Lithium[1] detects and handles environment configuration. Environments (or env for short) allow you to keep host specific configuration settings in one place. You may have an env called DEV, STAGE or PROD. Configuration settings are is kept in dedicated files on a per env basis. By default deta comes with a configuration for the DEV env. You can add new environments by copying dev.conf to prod.conf and adjusting the prefixes in it i.e DEV_ becomes PROD_. All environment configurations are by default loaded automatically before a task is executed. [1] Lithium framework, http://li3.me Roles ''''' Environments can _take_ roles. Tasks where you transfer transfer things between two machines would require SOURCE and a TARGET roles, whereas tasks that just build some stuff locally require a THIS role. To indicate that a task requires a role call the role function (from the core module) right below the source statements. ``` # source ... role SOURCE role TARGET # ... ``` The function will map an env to a role. This means a configuration setting available as i.e. DEV_HOST will become also available as THIS_HOST. When the env for a role can't be detected automatically it will prompt you for one. Envs can be automatically wired to roles within the configuration file. The following statement will cause the role function to use the DEV env for the THIS role when the current hostname equals the one specified for the DEV env. ``` # ... DEV_THIS=$([[ $(hostname) == $DEV_HOST ]] && echo "y" || echo "n") # ... ```