Add: more introductionary texxt

1 files changed, 42 insertions, 0 deletions

diff --git a/arch/ick2-arch.mdwn b/arch/ick2-arch.mdwn
index 1cb21e8..6a69051 100644
--- a/arch/ick2-arch.mdwn
+++ b/arch/ick2-arch.mdwn
@@ -18,6 +18,48 @@ This document describes the architecture of Ick2.
 Overview
 -----------------------------------------------------------------------------
 
+A continuous integration (CI) or continuous deployment (CD) system is,
+at its most simple core, an automated system that reacts to changes in
+a program's source code by doing a build of the program, running any
+of its automated tests, and then publishing the results somewhere. A
+CD system continues from there to also installing the new version of
+the program on all relevant computers. If a build or an automated test
+fails, the system notifies the relevant parties.
+
+Ick2 aims to be a CI/CD system. It deals with a small number of
+concepts:
+
+* **projects**, which consist of **source code** in a version control
+  system (mainly git right now)
+* **pipelines**, which are sequences of steps aiming to convert source
+  code into something executable, or test the program
+* **worker build hosts**, which do all the heavy lifting
+
+Example
+-----------------------------------------------------------------------------
+
+We will be returning to this example throughout this document. Imagine
+a static website that is built using the ikiwiki software. The source
+of the web pages is stored in a git repo, and the generated HTML pages
+are published on a web server.
+
+This might be expressed as Ick2 configuration like this:
+
+    projects:
+        website:
+            workspace:
+                - git: ssh://git@git.example.com/website.git
+            pipelines:
+                build_workspace:
+                    - shell: git clone ssh://git@git.example.com/website.git
+                build_site:
+                    - shell: ikiwiki 
+    FIXME: this should be finished
+
+
+Ick2 components
+-----------------------------------------------------------------------------
+
 Ick2 consists of several independent services. This document describes
 how they are used individually and together.