commit 93de476c9ae79dc643e130e106aa89a535b2843f
parent 917f457cff61c5d9833617d900736fba62c7a4eb
Author: Stefan Koch <programming@stefan-koch.name>
Date: Sat, 14 Sep 2019 20:48:30 +0200
write documentation
Diffstat:
2 files changed, 42 insertions(+), 102 deletions(-)
diff --git a/README.md b/ProjectOutline.md
diff --git a/README.md b/README.md
@@ -1,102 +1,42 @@
-# Cinderella CI
-
-## Project Outline
-
-| **Project Idea** | |
-| --- | --- |
-| **Description** | Lightweight self-hosted CI/CD platform without GUI and without a requirement for Docker |
-| **Target Audience** | Developers who work with raw git repositories or lightweight web solutions around git |
-| **Language** | Go or Rust |
-| **Expected Effort** | >100 hours |
-| **Intermediate Successes** | CD-only solution for static site generators, without CI pipelines |
-
-
-Being one of my many project ideas this will probably never take off, but the
-idea is to create a lightweight CI solution that can be used without docker.
-
-Problems with existing solutions:
-
-- Gitlab CI: Gitlab requires a lot of memory and comes with its full git
- management
-- Jenkins: Not very lightweight and in my opinion does not "feel" nice in usage
- (i.e. no clear approach because very plugin based, security configuration can
- be in multiple locations in the UI)
-- Drone: Does not want to support builds [without Docker][drone-docker] (and
- they do not have install instructions for the main process outside of Docker
- either -> this setup lead to some difficulties for me with my Gitlab
- setup, because then also a root-executor will not be on the actual server
- anymore)
-- TeamCity: Seems to require Tomcat (i.e. includes Java UI stuff), installation
- instructions (for agents) look complex on first sight
-
-Solutions that might be interesting, but there might also be problems:
-
-- GoCD:
- - states that it requires 1-2GB of memory only for the Server (without
- the Agents)
- - Pipeline as Code is not first-class citizen, plus it seems you always have
- to do adjustments in the web GUI
-- Hydra: Can only be installed on Nix OS?
-- Concourse: Uses containers for all builds?
-- builds.sr.ht: I think no documentation on how to setup self-hosted
-
-
-## Goal
-
-So what is this project's goal?
-
-### Techical Requirements
-
-- Installation of the main program must be possible without docker
- (and this will be the main approach in all docs)
-- There must be a build executor/agent that runs without docker (other agents
- that spawn docker containers might be implemented, because there are some
- advantages, but also some disadvantages)
-
-### Functional Requirements
-
-- Perform CI and CD according to build steps from a config file
-- Status Reporting:
- - If possible: no web GUI, alternatively: static HTML files with current
- status
- - Build failures and "OK again" status via mail
-- Encrypted variables directly in files in the repository (similar to ansible
- vault files) -> key for decryption must still be stored on the
- server (thus security is limited if repo and key are on the same server, but
- same goes for Gitlab etc.)
-- If possible: Should play nicely with ansible, because I deploy most projects
- with ansible (had some trouble with Gitlab there, I think because of the
- docker setup)
-- Should support any programming language, not just a list of maintained
- languages (and if there is a new one adjustments to the code have to be made)
-
-### Non-functional requirements
-
-- low memory and CPU footprint
-- easy installation without docker (ideally: copy one binary, set path
- to git repos, run it, done)
-
-### Non-Targets
-
-- solution does not have to be scalable, single-server setup is fine
-
-
-## Use Cases
-
-Project Development (if it takes place at all) will be according to use cases:
-
-1. Deploy a Zola-based website (static site generator) to the same server as
- Cinderella is installed on
-2. Deploy a Zola-based website to an FTP server (requires encrypted password)
-3. Run test execution for a Python project
-4. Deploy a project with an ansible-playbook
-
-
-## References
-
-- [List of CI/CD tools][cicd]
-- [reddit discussion on lightweight self-hosted CD][reddit-cd]
-
-[drone-docker]: https://github.com/drone/drone/issues/2378
-[cicd]: https://github.com/ligurio/awesome-ci
-[reddit-cd]: https://www.reddit.com/r/devops/comments/a4tyju/lightweight_self_hosted_cd/
+Cinderella CI
+=============
+
+Cinderella CI is a simple Continuous Integration solution for git repositories.
+It is designed for people who do not want to work with big solutions like
+Gitlab or Jenkins and probably also work with standard *bare* git repositories
+(instead of Gitlab, gitea or similar).
+
+Usage
+-----
+
+Cinderella expects a `.cinderella.toml` file with the CI configuration in the
+root folder of your repository. When you execute Cinderella with the clone URL
+of a git repository it will clone the URL into a temporary folder, search for
+the CI configuration file and if available execute the build steps.
+
+There is a sample hook in `hooks/post-update` which you can use in your remote
+repository to execute Cinderella automatically each time you push to your
+repository.
+
+Configuration Format
+--------------------
+
+The CI configuration file is a TOML file with one table per build pipeline.
+Common build pipelines are `test` or `build`. E.g. the following is a valid
+configuration file executing a `test` phase and a `build-release` phase.
+
+```toml
+[test]
+commands = [
+ "cargo test",
+]
+
+[build-release]
+commands = [
+ "cargo build --release",
+]
+```
+
+Pipelines are executed in the order in which they are defined. For the
+given configuration file it is ensured that first `test` is being executed
+followed by `build-release`.
