Revision as of 21:57, 4 March 2009

Alpine Configuration Framework

The Alpine Configuration Framework (ACF) is a mvc-style application for configuring an Alpine device. The primary focus is for a web interface - ACF's main goal is to be a light-weight MVC "webmin".

Why Haserl + Lua

Other competitors in the arena were Webmin, Ruby on Rails, PHP with templates.

A full webmin (Perl), RoR or PHP implementation each require several MB of installed code, and can have very slow startup times, especially when used in "cgi" mode. After evaluating many options, we found that Lua has the following advantages:

It is small (typically ~200KB of compiled code)
It compiles and runs much faster than PHP, Perl or Ruby
It provides a "normal" scripting language with features similar to PHP, perl, java, awk, etc.

Haserl + Lua provides a 'good enough' toolset to build a full-featured web application.

Why ACF is MVC

The MVC design pattern is used to separate presentation information from control logic. By MVC we mean:

Model - code that reads / writes a config file, starts / stops daemons, or does other work modifying the router.
View - code that formats data for output
Controller - code that glues the two together

Note the lack of words like: HTML, XML, OO, AJAX, etc. The purpose of ACF's MVC is simply to separate the configuration logic from the presentation of the output.

The flow of a single transaction is:

start -> execute requested function in controller, optionally reading/writing a file using functions in the model -> execute the view to format the output -> end

Every transaction follows this pattern. For ACF developers, the focus should be on getting a model that does a proper job of abstracting the config file into useable entities and then building a controller that presents useable "actions" based on the model. The presentation layer should be last on the priority list.

For good background information on what ACF attempts to do, please see Terence Parr's paper "Enforcing Strict Model-View Separation in Template Engines" at http://www.cs.usfcs.edu or the local copy of the pdf.

Starting ACF

The easiest way to start ACF is to run the setup-webconf script. This script will install mini-httpd, create a certificate, and start mini-httpd in HTTPS mode. WARNING - This will give anyone on the network access to your machine. The script will also install the two packages that are necessary for basic ACF: acf-core and acf-alpine-baselayout. To view ACF, simply browse to your machine (https://<hostname>/).

Alternately, you can manually install ACF and your web server. Once again, the two critical ACF packages are acf-core and acf-alpine-baselayout. The ACF packages will install to /usr/share/acf. You can configure your web server to give access to /usr/share/acf/www and run cgi scripts from /usr/share/acf/www/cgi-bin, and you should be able to view ACF.

If you would like to play with other ACF packages, we recommend you install the acf-apk-tools package. This package will allow you to install / delete other packages using ACF. You can then load any other acf-* packages you are interested in.

The two default login / password combinations are 'alpine' / 'test123' and 'foo' / 'test123'. 'alpine' is given ADMIN rights and 'foo' is given USER rights. We recommend you change your login id and password by selecting 'User Management'.

Managing Your ACF Installation

ACF Developer's Guides

mvc.lua reference - mvc.lua is the core of ACF
mvc.lua example - build a simple (command-line) application
acf www-controller reference - ACF www application functions
acf www-controller example - webify the above examples
ACF how to write - Step by step howto for writing acfs
ACF core principles - Things that are standard across the application
LPOSIX - Documentation for the Lua Posix functions
ACF Libraries - Document the libraries and common functions
Writing ACF Views - Guide for writing a view
Writing ACF Controllers - Guide for writing a controller
Writing ACF Models - Guide for writing a model

ACF Layout

ACF has support for multiple skins.
Only a few skins are available. Feel free to contribute in programming css-stylesheets for ACF.

Howto contribute

First download ACF using svn or installing available acf's using apk_add.
Easiest is if you download latest Alpine ISO, boot a box on that and then run 'setup-alpine' and 'setup-webconf -a' that way you get a running environment fast and easy!
Some example skins are available

/usr/share/acf/www/skins/ice/
/usr/share/acf/www/skins/snow/

Make a new skin-folder

mkdir /usr/share/acf/www/skins/myskin

Create a css file called as the folder.

touch /usr/share/acf/www/skins/myskin/myskin.css

Now you can start editing your myskin.css.
If you have ACF running on a computer, you can browse to this ACF-page and switch to your knew skin (called myskin) and see the results of your changes.

Pack your myskin-folder, containing your css-file (and images, if there is any).
Send this patch to acf@lists.alpinelinux.org (Note: Don't forget to subscribe before sending your patch)

ACF Packages

Look at ACF packages to see available ACF modules and their status.

@@ Line 1: / Line 1: @@
-= Alpine Configuration Framework =
+= Alpine Configuration Framework  =
-The Alpine Configuration Framework (ACF) is a mvc-style application for configuring an Alpine device.  The primary focus is for a web interface - ACF's main goal is to be a light-weight MVC "webmin".
+The Alpine Configuration Framework (ACF) is a mvc-style application for configuring an Alpine device. The primary focus is for a web interface - ACF's main goal is to be a light-weight MVC "webmin".
-== Why Haserl + Lua ==
+== Why Haserl + Lua  ==
 Other competitors in the arena were Webmin, Ruby on Rails, PHP with templates.
-A full webmin (Perl), RoR or PHP implementation each require several MB of installed code, and can have very slow startup times, especially when used in "cgi" mode.  After evaluating many options, we found that [http://www.lua.org Lua] has the following advantages:
+A full webmin (Perl), RoR or PHP implementation each require several MB of installed code, and can have very slow startup times, especially when used in "cgi" mode. After evaluating many options, we found that [http://www.lua.org Lua] has the following advantages:
-* It is small (typically ~200KB of compiled code)
+*It is small (typically ~200KB of compiled code)
-* It compiles and runs much faster than [http://shootout.alioth.debian.org/gp4/benchmark.php?test=all&lang=lua&lang2=php PHP], [http://shootout.alioth.debian.org/gp4/benchmark.php?test=all&lang=lua&lang2=perl Perl] or [http://shootout.alioth.debian.org/gp4/benchmark.php?test=all&lang=lua&lang2=ruby Ruby]
+*It compiles and runs much faster than [http://shootout.alioth.debian.org/gp4/benchmark.php?test=all&lang=lua&lang2=php PHP], [http://shootout.alioth.debian.org/gp4/benchmark.php?test=all&lang=lua&lang2=perl Perl] or [http://shootout.alioth.debian.org/gp4/benchmark.php?test=all&lang=lua&lang2=ruby Ruby]
-* It provides a "normal" scripting language with [http://en.wikipedia.org/wiki/Lua_(programming_language)#Features features] similar to PHP, perl, java, awk, etc.
+*It provides a "normal" scripting language with [http://en.wikipedia.org/wiki/Lua_(programming_language)#Features features] similar to PHP, perl, java, awk, etc.
 Haserl + Lua provides a 'good enough' toolset to build a full-featured web application.
-== Why ACF is MVC ==
+== Why ACF is MVC  ==
-The MVC design pattern is used to separate presentation information from control logic.  By MVC we mean:
+The MVC design pattern is used to separate presentation information from control logic. By MVC we mean:
-* '''Model''' - code that reads / writes a config file, starts / stops daemons, or does other work modifying the router.
+*'''Model''' - code that reads / writes a config file, starts / stops daemons, or does other work modifying the router.
-* '''View''' - code that formats data for output
+*'''View''' - code that formats data for output
-* '''Controller''' - code that glues the two together
+*'''Controller''' - code that glues the two together
-Note the lack of words like: HTML, XML, OO, AJAX, etc.  The purpose of ACF's MVC is simply to separate the configuration logic from the presentation of the output.
+Note the lack of words like: HTML, XML, OO, AJAX, etc. The purpose of ACF's MVC is simply to separate the configuration logic from the presentation of the output.
 The flow of a single transaction is:
-start ->
+start -&gt; execute requested function in '''controller''', optionally reading/writing a file using functions in the '''model''' -&gt; execute the '''view''' to format the output -&gt; end
-execute requested function in '''controller''',
-optionally reading/writing a file using functions in the '''model''' ->
-execute the '''view''' to format the output ->
-end
-''Every'' transaction follows this pattern.  For ACF developers, the focus should be on getting a model that does a proper job of abstracting the config file into useable entities and then building a controller that presents useable "actions" based on the model.   The presentation layer should be last on the priority list.
+''Every'' transaction follows this pattern. For ACF developers, the focus should be on getting a model that does a proper job of abstracting the config file into useable entities and then building a controller that presents useable "actions" based on the model. The presentation layer should be last on the priority list.
-For good background information on what ACF attempts to do, please see Terence Parr's paper "Enforcing Strict Model-View Separation in Template Engines" at
+For good background information on what ACF attempts to do, please see Terence Parr's paper "Enforcing Strict Model-View Separation in Template Engines" at [http://www.cs.usfca.edu/~parrt/papers/mvc.templates.pdf http://www.cs.usfcs.edu] or the [[Media:Mvc.templates.pdf|local copy]] of the pdf.
-[http://www.cs.usfca.edu/~parrt/papers/mvc.templates.pdf http://www.cs.usfcs.edu] or the [[Media:Mvc.templates.pdf|local copy]]  of the pdf.
-= Starting ACF =
+= Starting ACF  =
-The easiest way to start ACF is to run the ''setup-webconf'' script.  This script will install mini-httpd, create a certificate, and start mini-httpd in HTTPS mode.  '''WARNING - This will give anyone on the network access to your machine.'''  The script will also install the two packages that are necessary for basic ACF: acf-core and acf-alpine-baselayout.  To view ACF, simply browse to your machine (https://<hostname>/).
+The easiest way to start ACF is to run the ''setup-webconf'' script. This script will install mini-httpd, create a certificate, and start mini-httpd in HTTPS mode. '''WARNING - This will give anyone on the network access to your machine.''' The script will also install the two packages that are necessary for basic ACF: acf-core and acf-alpine-baselayout. To view ACF, simply browse to your machine (https://&lt;hostname&gt;/).
-Alternately, you can manually install ACF and your web server.  Once again, the two critical ACF packages are acf-core and acf-alpine-baselayout.  The ACF packages will install to /usr/share/acf.  You can configure your web server to give access to /usr/share/acf/www and run cgi scripts from /usr/share/acf/www/cgi-bin, and you should be able to view ACF.
+Alternately, you can manually install ACF and your web server. Once again, the two critical ACF packages are acf-core and acf-alpine-baselayout. The ACF packages will install to /usr/share/acf. You can configure your web server to give access to /usr/share/acf/www and run cgi scripts from /usr/share/acf/www/cgi-bin, and you should be able to view ACF.
-If you would like to play with other ACF packages, we recommend you install the acf-apk-tools package.  This package will allow you to install / delete other packages using ACF.  You can then load any other acf-* packages you are interested in.
+If you would like to play with other ACF packages, we recommend you install the acf-apk-tools package. This package will allow you to install / delete other packages using ACF. You can then load any other acf-* packages you are interested in.
-The two default login / password combinations are 'alpine' / 'test123' and 'foo' / 'test123'.  'alpine' is given ADMIN rights and 'foo' is given USER rights.  We recommend you change your login id and password by selecting 'User Management'.
+The two default login / password combinations are 'alpine' / 'test123' and 'foo' / 'test123'. 'alpine' is given ADMIN rights and 'foo' is given USER rights. We recommend you change your login id and password by selecting 'User Management'.
-= ACF Developer's Guides =
+[[Managing ACF|Managing Your ACF Installation]]
-# [[ACF_mvc.lua_reference|mvc.lua reference]]  - mvc.lua is the core of ACF
+= ACF Developer's Guides  =
-# [[ACF_mvc.lua_example|mvc.lua example]] - build a simple (command-line) application
-# [[ACF_acf_www-controller.lua_reference|acf www-controller reference]] - ACF www application functions
-# [[ACF_acf_www_example| acf www-controller example]] - webify the above examples
-# [[ACF_how_to_write]] - Step by step howto for writing acfs
-# [[ACF core principles]] - Things that are standard across the application
-# [[LPOSIX]] - Documentation for the Lua Posix functions
-# [[ACF Libraries ]] - Document the libraries and common functions
-# [[Writing ACF Views]] - Guide for writing a view
-# [[Writing ACF Controllers]] - Guide for writing a controller
-# [[Writing ACF Models]] - Guide for writing a model
-== Other useful links ==
+#[[ACF mvc.lua reference|mvc.lua reference]] - mvc.lua is the core of ACF
-# [http://www.lua.org/manual/5.1/ Lua 5.1 Reference Manual]
+#[[ACF mvc.lua example|mvc.lua example]] - build a simple (command-line) application
-# [http://www.lua.org/pil/ Programming in Lua (first edition)]
+#[[ACF acf www-controller.lua reference|acf www-controller reference]] - ACF www application functions
+#[[ACF acf www example|acf www-controller example]] - webify the above examples
+#[[ACF how to write]] - Step by step howto for writing acfs
+#[[ACF core principles]] - Things that are standard across the application
+#[[LPOSIX]] - Documentation for the Lua Posix functions
+#[[ACF Libraries]] - Document the libraries and common functions
+#[[Writing ACF Views]] - Guide for writing a view
+#[[Writing ACF Controllers]] - Guide for writing a controller
+#[[Writing ACF Models]] - Guide for writing a model
+== Other useful links  ==
+#[http://www.lua.org/manual/5.1/ Lua 5.1 Reference Manual]
+#[http://www.lua.org/pil/ Programming in Lua (first edition)]
+= ACF Layout  =
+ACF has support for multiple skins.<br>Only a few skins are available. Feel free to contribute in programming css-stylesheets for ACF.
+== Howto contribute  ==
+First download ACF using svn or installing available acf's using apk_add.<br>Easiest is if you download latest Alpine ISO, boot a box on that and then run 'setup-alpine' and 'setup-webconf -a' that way you get a running environment fast and easy!<br>Some example skins are available
+*/usr/share/acf/www/skins/ice/
+*/usr/share/acf/www/skins/snow/
+Make a new skin-folder
-= ACF Layout =
-ACF has support for multiple skins.<BR>
-Only a few skins are available. Feel free to contribute in programming css-stylesheets for ACF.
-== Howto contribute ==
-First download ACF using svn or installing available acf's using apk_add.<BR>
-Easiest is if you download latest Alpine ISO, boot a box on that and then run 'setup-alpine' and 'setup-webconf -a' that way you get a running environment fast and easy!<BR>
-Some example skins are available
-* /usr/share/acf/www/skins/ice/
-* /usr/share/acf/www/skins/snow/
-Make a new skin-folder
   mkdir /usr/share/acf/www/skins/myskin
-Create a css file called as the folder.
+Create a css file called as the folder.
   touch /usr/share/acf/www/skins/myskin/myskin.css
-Now you can start editing your myskin.css.<BR>
-If you have ACF running on a computer, you can browse to this ACF-page and switch to your knew skin (called myskin) and see the results of your changes.
-Pack your myskin-folder, containing your css-file (and images, if there is any).<BR>
+Now you can start editing your myskin.css.<br>If you have ACF running on a computer, you can browse to this ACF-page and switch to your knew skin (called myskin) and see the results of your changes.
-Send this patch to acf@lists.alpinelinux.org ''('''Note:''' Don't forget to [http://wiki.alpinelinux.org/w/index.php?title=Mailing_lists subscribe] before sending your patch)''
+Pack your myskin-folder, containing your css-file (and images, if there is any).<br>Send this patch to acf@lists.alpinelinux.org ''('''Note:''' Don't forget to [http://wiki.alpinelinux.org/w/index.php?title=Mailing_lists subscribe] before sending your patch)''
+= ACF Packages  =
-= ACF Packages =
 Look at [http://wiki.alpinelinux.org/w/index.php?title=ACF_packages ACF packages] to see available ACF modules and their status.