From 0a5c6333fc34aa77ee752d8e22bca85d3de312c3 Mon Sep 17 00:00:00 2001 From: oleg Date: Mon, 1 Feb 2016 03:16:35 +0300 Subject: [PATCH] add public readme + doc fixes --- LICENSE.txt | 2 +- README.md | 74 +++++++++++++++++++++++++++++ docs/sample-project-config.yaml | 72 ++++++++++++++++++++++++++++ docs/tutorials/standalone-web-ui.md | 26 +++++----- 4 files changed, 162 insertions(+), 12 deletions(-) create mode 100644 README.md create mode 100644 docs/sample-project-config.yaml diff --git a/LICENSE.txt b/LICENSE.txt index c8a98c1..6bedf7c 100644 --- a/LICENSE.txt +++ b/LICENSE.txt @@ -1,6 +1,6 @@ (The MIT License) -Copyright (c) 2014-2015 +Copyright (c) 2014-2016 Oleg Korobenko , Vladimir Polyakov diff --git a/README.md b/README.md new file mode 100644 index 0000000..0e5159a --- /dev/null +++ b/README.md @@ -0,0 +1,74 @@ + +# nci + +Flexible, modular continuous integration server written in node.js. + +[![Build Status](https://travis-ci.org/node-ci/nci.svg?branch=master)](https://travis-ci.org/node-ci/nci) + + +## Features + +* modular approach, small core a lot of plugins (e.g. rest api, web interface - +plugins, not core) +* minimalistic system requirements (only node and scm clients are required, no +external db) +* pluginnable db storage (any [levelup](https://github.com/Level/levelup) +backend could be used) +* using on-the-fly snappy compression for all stored data (builds, build logs) +when leveldb (via leveldown backend) is used +* working with any mercurial, git repositories (no matter is it service like +github, bitbucket or private server, all you need is authenticate user from +which nci server is running without password e.g. by ssh key) +* damn fast single page web application interface +([classic ui plugin](https://github.com/node-ci/nci-classic-ui)) +* server and projects could be configured with yaml +([yaml reader plugin](https://github.com/node-ci/nci-yaml-reader)) - provides +pretty shell scripting (strings without quotes, nice multiline strings, etc) +* provides agile project relations out of the box (see `blocks`, `blockedBy`, +`trigger` at [sample project config](./docs/sample-project-config.yaml)) +* could catch every or specific commits (see `catchRev` at +[sample project config](./docs/sample-project-config.yaml)) + + +Online demo is [here](http://classicui-ncidemo.rhcloud.com/). + + +Basic tutorial [here](./docs/tutorials/standalone-web-ui.md). + + +## System requirements + +* unix-like operating system (tested mostly on Ubuntu 14.04, CentOS 6.6) +* node.js >= 0.10 +* git client (tested with 1.9.1) (only when git projects are used) +* mercurial client (tested with 2.8.2) (only when mercurial +projects are used) + + +## Resources + +* [basic tutorial](./docs/tutorials/standalone-web-ui.md) +* [online demo](http://classicui-ncidemo.rhcloud.com/) +* [sample project config](./docs/sample-project-config.yaml) +* [developing plugins doc](./docs/developing-plugins) + + +## Roadmap + +* preserve output colors when spawn commands +* expose node/executors api, implement plugin for remote and isolated build +running (docker or similar). Only local executor currently available. +* extend web interface functionality +* allow store project config inside repository of this project + + +## Plugins + +* [yaml reader plugin](https://github.com/node-ci/nci-yaml-reader) +* [classic ui plugin](https://github.com/node-ci/nci-classic-ui) +* [static server plugin](https://github.com/node-ci/nci-static-server) +* [mail notification plugin](https://github.com/node-ci/nci-mail-notification) +* [jabber notification plugin](https://github.com/node-ci/nci-jabber-notification) +* [projects reloader plugin](https://github.com/node-ci/nci-projects-reloader) +* [rest api server plugin](https://github.com/node-ci/nci-rest-api-server) +* [scheduler plugin](https://github.com/node-ci/nci-scheduler) diff --git a/docs/sample-project-config.yaml b/docs/sample-project-config.yaml new file mode 100644 index 0000000..071dfdc --- /dev/null +++ b/docs/sample-project-config.yaml @@ -0,0 +1,72 @@ + +#sample project config + +#configure scm +scm: + type: git + repository: https://github.com/node-ci/nci + rev: master + +#specify which revisions should be built (by `tag` or `comment` regexp) +#in any case (e.g. when several commits pushed at once) +catchRev: + #for catching semver tags like 1.3.6, etc + tag: !!js/regexp /\d+\.\d+\.\d+/ + +#notification settings +notify: + #when + on: + #build successfully done + - done + #build completed with error + - error + #build status other than previous build status + #of this project + - change + to: + #target transports, `console` just log to console + #see `nci-mail-notification` plugin for mail notifications + console: + +#trigger another project +trigger: + after: + #bulld `project2` after successful `done` of current project + - status: done + project: project2 + +#specify which projects builds will block building of current project (each +#element could be string or regexp) +blockedBy: + # - project2 + - !!js/regexp /project1|project2/ + +#specify which projects will be blocked by current project (each element could +#be string or regexp) +blocks: + - project2 + +#specify project steps, each must has `cmd`. +#`name` (will be get from `cmd` by default) and `shell` (/bin/sh is default) +# are optional +steps: + - cmd: > + echo "long multiline string" && + sleep 2 && + echo "is not a problem when you're using yaml" && + echo "cur dir is `pwd`" + + - name: sleep + cmd: sleep 4 + + - cmd: echo 2 > 2.txt + + - cmd: cat 2.txt + + - shell: /bin/bash + cmd: > + for i in {1..100}; do + echo "tick $i"; + sleep 0.3; + done; diff --git a/docs/tutorials/standalone-web-ui.md b/docs/tutorials/standalone-web-ui.md index a4d6c62..6d2af66 100644 --- a/docs/tutorials/standalone-web-ui.md +++ b/docs/tutorials/standalone-web-ui.md @@ -2,20 +2,24 @@ # nci standalone server with web ui tutorial In this tutorial we will setting up continuous integration server powered -by leveldb (`leveldown` package) with web interface (`nci-classic-ui` plugin) -which will serve all required static files by it self (`nci-static-server` -plugin). We will use yaml (`nci-yaml-reader` plugin) for configure server and -projects. Running app will be controlled by `forever` to get restarted in -case of unexpected failure. +by leveldb (`leveldown` package) with web interface +([classic ui plugin](https://github.com/node-ci/nci-classic-ui)) +which will serve all required static files by it self +([static server plugin](https://github.com/node-ci/nci-static-server)). We will +use yaml ([yaml reader plugin](https://github.com/node-ci/nci-yaml-reader)) +for configure server and projects. Running app will be controlled by `forever` +to get restarted in case of unexpected failure. We will also use following plugins: -* `nci-mail-notification` to get notifications about failed builds via email -* `nci-projects-reloader` to auto reload projects config when it changes on -disk -* `nci-rest-api-server` to expose rest api for having ability to trigger build -by simple `curl` call -* `nci-scheduler` to trigger project building by schedule +* [mail notification plugin](https://github.com/node-ci/nci-mail-notification) +to get notifications about failed builds via email +* [projects reloader plugin](https://github.com/node-ci/nci-projects-reloader) +to auto reload projects config when it changes on disk +* [rest api server plugin](https://github.com/node-ci/nci-rest-api-server) +to expose rest api for having ability to trigger build by simple `curl` call +* [scheduler plugin](https://github.com/node-ci/nci-scheduler) to trigger +project building by schedule ## Installation