move around documentation

Signed-off-by: Nico Schottelius <nico@kr.ethz.ch>
15 years ago · c223a4ac5c
parent 3bbf032b41
commit c223a4ac5c
7 changed files with 187 additions and 175 deletions
--- a/6
+++ b/6
@ -1,3 +1,9 @@
 PREFIX=/usr
 BINDIR=$(PREFIX}/bin
 install:
 	cp bin/* $(BINDIR)
 sync:
 	.rsync lyni@tablett:cdist
 	.rsync nicosc@free.ethz.ch:cdist
--- a/171
+++ b/171
@ -46,174 +46,3 @@ and is equipped with manpages.
 ## How to use cdist
    man cdist
 --------------------------------------------------------------------------------
 ## How cdist works
 ### Exploring your system
 cdist analyses the system to apply the configuration on and
 selects the right backends. You can use ***cdist-explore*** to
 the results of the explore functions.
 ### Applying the configuration
 cdist looks for the configuration to apply on the local host
 and applies it using ***cdist-apply***.
 ### Managing many hosts
 Whereas ***cdist-apply*** manages one host, ***cdist-deploy***
 applies the configuration on enabled hosts.
 ## How to use cdist?
 0. Create a host specification (/etc/cdist/hosts/**hostname**)
 0. Add functionalilty to add
 0. Run ***cdist-apply***
 ## What do I need [from puppet?]
 ### Abstraction of package managers
 I don't want to care about apt, rpm, yum, pacman, etc. I just
 want to ensure, some package exists or does not exist.
 ### Common tasks already done
   - [LIBRARY] All the helper types like 
      - file
      - ssh_keys
      - package
      - service
      - user
 ### PORTABILITY
   - [PORTABILITY] clients for every unix
      - mostly ruby + facter in puppet
 ### Other
   - Modules: Nice to put stuff together
      - and reuse
   - [CONDITIONS] facter is cool
   - the DSL
      - with many bugs
   - templates
   - Client/Server approach is nice to have
      - Clients only get the part of the documentation, that's
        relevant to them
   - detect impossible/unsafe things:
      - creating a file twice
      - installing and removing a package
      - and report location of occurence
         - parse afterwards?
 --------------------------------------------------------------------------------
 what is puppet? [FOR ME]
   A configuration deployment assistant,
   a DSL that allows you define the objectives.
   A webserver with fileserver capabilities.
   A client based scheduled polling infrastructure.
 --------------------------------------------------------------------------------
 What do I miss from puppet?
   - speed
   - elegance
   - clean design
   - documentation
   - the "no surprise" factor
   - easy to use "data memory" (i.e. external ressources)
   - easy integration into installation process
      - copy identity to master
   - multi master setups
   - development configurations / tests
   - editing of configuration files
      - similar to cfengine
   - replace bug squasher with bug avoidance
      - qmail did not need one either
   - push infrastructure
   - real / meaningful error messages
 --------------------------------------------------------------------------------
 Simple stuff done by Unix[notm]
   - DSL: Shell!
      - gives if, else and EVEN elsif for free!
      - and case
      - and and and
      - and there's no os (solaris doesn't count) without a usable /bin/sh
      - cdist defines what you can use
         - you _can_ use os specific stuff
         - but it's ugly and you shoot into your own foot
      - "manifests" (use the same name here?) will be run/sourced
         - inheritance possible via sourcing
         - cdist-lib always preloaded
      - library == functions?
   - version control via git
   - file distribution via ssh
   - authentication via ssh
   - dumb clients, similar to manifest compile in puppet
      - clients just execute commands
   - dependencies via make?
      - how to ensure sigletons / conflicting definitions?
         file { "/a":
            ensure => present,
         file { "/a":
            ensure => absent,
   - matching on explored items, not only on host name?
      - match function in host? [optional]
   - file source:
      - relative to specification
      - or absolute
 --------------------------------------------------------------------------------
 Implementation
   "cdist-server"
      -> called by cron?
      -> no need to reimplement scheduling
   "cdist-explore" (facter replacement)
      -> running on the client
 --------------------------------------------------------------------------------
 Requirements:
   It MUST be incredible easy/dumb to add new types.
      => growable default types
 --------------------------------------------------------------------------------
      ## TO DOC
 Before initial release, document:
   - how to add package backends
   - how to write a minimal host manifest
   - create library with all functions (and their parameters)
      - cdist_package
      - cdist_file
      - cdist_dir
   - only do necessary work
      - install packages only if not existent
      - copy file only if different
   - how to write a module
      - module function autoloading via *.sh
      - module "manifest"?
         - create functions in *.sh
         - name functions "modulename_function"
            module hellow
            function kitty
            => hellow_kitty
      - you are advised (not forced) to put files
         to a subdirectory named "files"
--- a/10
+++ b/10
@ -1,2 +1,8 @@
- find out where I left work :-)
+- doc:
- create real todo
+   - readme (cleanup, define)
   - cdist manpage (main manpage)
   - create todos from doc/internal/puppet-analysis
 - cdist-deply-to
   - sync conf/{lib/,modules,host/$name}
 - cdist-build-explorer| ssh localhost
 - 
--- a/bin/cdist-build
+++ b/bin/cdist-build
@ -26,7 +26,6 @@
 [ $# -eq 1 ] || __cdist_usage "target"
 set -e
 set -x
 . cdist-preprocess "$1"
 . cdist-compile "$1"
--- a/bin/cdist-deploy-to
+++ b/bin/cdist-deploy-to
@ -1,4 +1,4 @@
-!/bin/sh
+#!/bin/sh
 #
 # 2010 Nico Schottelius (nico-cdist at schottelius.org)
 #
--- a/doc/internal/puppet-analysis
+++ b/doc/internal/puppet-analysis
@ -0,0 +1,66 @@
 ## What do I need [from puppet?]
 ### Abstraction of package managers
 I don't want to care about apt, rpm, yum, pacman, etc. I just
 want to ensure, some package exists or does not exist.
 ### Common tasks already done
   - [LIBRARY] All the helper types like 
      - file
      - ssh_keys
      - package
      - service
      - user
 ### PORTABILITY
   - [PORTABILITY] clients for every unix
      - mostly ruby + facter in puppet
 ### Other
   - Modules: Nice to put stuff together
      - and reuse
   - [CONDITIONS] facter is cool
   - the DSL
      - with many bugs
   - templates
   - Client/Server approach is nice to have
      - Clients only get the part of the documentation, that's
        relevant to them
   - detect impossible/unsafe things:
      - creating a file twice
      - installing and removing a package
      - and report location of occurence
         - parse afterwards?
 --------------------------------------------------------------------------------
 what is puppet? [FOR ME]
   A configuration deployment assistant,
   a DSL that allows you define the objectives.
   A webserver with fileserver capabilities.
   A client based scheduled polling infrastructure.
 --------------------------------------------------------------------------------
 What do I miss from puppet?
   - speed
   - elegance
   - clean design
   - documentation
   - the "no surprise" factor
   - easy to use "data memory" (i.e. external ressources)
   - easy integration into installation process
      - copy identity to master
   - multi master setups
   - development configurations / tests
   - editing of configuration files
      - similar to cfengine
   - replace bug squasher with bug avoidance
      - qmail did not need one either
   - push infrastructure
   - real / meaningful error messages
--- a/doc/man/cdist.text
+++ b/doc/man/cdist.text
@ -31,3 +31,109 @@ COPYING
 -------
 Copyright \(C) 2010 Nico Schottelius. Free use of this software is
 granted under the terms of the GNU General Public License version 3 (GPLv3).
 --------------------------------------------------------------------------------
 ## How cdist works
 ### Exploring your system
 cdist analyses the system to apply the configuration on and
 selects the right backends. You can use ***cdist-explore*** to
 the results of the explore functions.
 ### Applying the configuration
 cdist looks for the configuration to apply on the local host
 and applies it using ***cdist-apply***.
 ### Managing many hosts
 Whereas ***cdist-apply*** manages one host, ***cdist-deploy***
 applies the configuration on enabled hosts.
 ## How to use cdist?
 0. Create a host specification (/etc/cdist/hosts/**hostname**)
 0. Add functionalilty to add
 0. Run ***cdist-apply***
 --------------------------------------------------------------------------------
 Simple stuff done by Unix[notm]
   - DSL: Shell!
      - gives if, else and EVEN elsif for free!
      - and case
      - and and and
      - and there's no os (solaris doesn't count) without a usable /bin/sh
      - cdist defines what you can use
         - you _can_ use os specific stuff
         - but it's ugly and you shoot into your own foot
      - "manifests" (use the same name here?) will be run/sourced
         - inheritance possible via sourcing
         - cdist-lib always preloaded
      - library == functions?
   - version control via git
   - file distribution via ssh
   - authentication via ssh
   - dumb clients, similar to manifest compile in puppet
      - clients just execute commands
   - dependencies via make?
      - how to ensure sigletons / conflicting definitions?
         file { "/a":
            ensure => present,
         file { "/a":
            ensure => absent,
   - matching on explored items, not only on host name?
      - match function in host? [optional]
   - file source:
      - relative to specification
      - or absolute
 --------------------------------------------------------------------------------
 Implementation
   "cdist-server"
      -> called by cron?
      -> no need to reimplement scheduling
   "cdist-explore" (facter replacement)
      -> running on the client
 --------------------------------------------------------------------------------
 Requirements:
   It MUST be incredible easy/dumb to add new types.
      => growable default types
 --------------------------------------------------------------------------------
      ## TO DOC
 Before initial release, document:
   - how to add package backends
   - how to write a minimal host manifest
   - create library with all functions (and their parameters)
      - cdist_package
      - cdist_file
      - cdist_dir
   - only do necessary work
      - install packages only if not existent
      - copy file only if different
   - how to write a module
      - module function autoloading via *.sh
      - module "manifest"?
         - create functions in *.sh
         - name functions "modulename_function"
            module hellow
            function kitty
            => hellow_kitty
      - you are advised (not forced) to put files
         to a subdirectory named "files"