Alpine Configuration Framework Design: Difference between revisions

Latest revision as of 05:32, 10 March 2025

The Alpine Configuration Framework (ACF) is a mvc-style application for configuring an Alpine Linux device. The primary focus is for a web interface - a light-weight MVC "webmin".

Installation

Installing ACF is really simple. Just type this in your terminal and follow the instructions to setup ACF:

setup-acf

The above script install mini-httpd, create a certificate, starts mini-httpd in HTTPS mode and installs some basic acf-packages. To view ACF, simply browse to your machine https://<hostname>/

Alternately, your existing web server can be used as follows:

Install the packages acf-core and acf-alpine-baselayout and packages will install to /usr/share/acf.
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.

ACF packages page details the available ACF modules and their status. Proceed to Managing ACF page for Managing Your ACF Installation.

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^{[Dead Link]} 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.

Of course, as with all MVC designs, the ACF MVC design is not quite 'pure' MVC and has evolved over time. Most of the controller functionality is handled by the framework code. The framework code will also automatically generate views for HTML, JSON, and a few other viewtypes if no view is defined. Also, many model functions are implemented in helper libraries. We have attempted to make it as easy as possible to develop new ACF modules.

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 https://www.cs.usfcs.edu.

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 ACF modules
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

How to contribute

ACF has support for multiple skins. Some example skins available are:

/usr/share/acf/www/skins/alps/
/usr/share/acf/www/skins/cloud/
/usr/share/acf/www/skins/ice/
/usr/share/acf/www/skins/snow/
/usr/share/acf/www/skins/wik/

Feel free to contribute in programming css-stylesheets for ACF.

Make a new skin folder.
# mkdir -p /etc/acf/skins/myskin
Create a css file called as the folder.
# touch /etc/acf/skins/myskin/myskin.css

Now you can start editing your myskin.css.
If you have ACF running on the computer, you can browse to https://<hostname>/cgi-bin/acf/acf-util/skins/read and switch to your new skin (called myskin) and see the results of your changes.

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

@@ Line 1: / Line 1: @@
-= Alpine Configuration Framework =
+The Alpine Configuration Framework (ACF) is a mvc-style application for configuring an Alpine Linux device. The primary focus is for a web interface - 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".
+== Installation ==
-== Why Haserl + Lua ==
+Installing ACF is really simple. Just type this in your terminal and follow the instructions to setup ACF: {{cmd|setup-acf}}
-Other competitors in the arena were Webmin, Ruby on Rails, PHP with templates.
+The above script install mini-httpd, create a certificate, starts mini-httpd in HTTPS mode and installs some basic acf-packages. To view ACF, simply browse to your machine https://&lt;hostname&gt;/
-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:
+Alternately, your existing web server can be used as follows:
+* [[Install]] the packages {{pkg|acf-core}} and {{pkg|acf-alpine-baselayout}} and packages will install to {{path|/usr/share/acf}}.
+* Configure your web server to give access to {{path|/usr/share/acf/www}} and run cgi scripts from {{path|/usr/share/acf/www/cgi-bin}} and you should be able to view ACF.
-* It is small (typically ~200KB of compiled code)
+[[ACF packages]] page details the available ACF modules and their status. Proceed to [[Managing ACF]] page for Managing Your ACF Installation.
-* 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.
-Haserl + Lua provides a 'good enough' toolset to build a full-featured web application.
+== Why Haserl + Lua  ==
+Other competitors in the arena were Webmin, Ruby on Rails, PHP with templates.
-== Why ACF is MVC ==
+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 [https://www.lua.org Lua] has the following advantages:
-The MVC design pattern is used to separate presentation information from control logic.  By MVC we mean:
+*It is small (typically ~200KB of compiled code)
+*It compiles and runs much faster than [https://web.archive.org/web/20100707143932/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]{{dead link}} or [https://web.archive.org/web/20100313062645/http://shootout.alioth.debian.org/gp4/benchmark.php?test=all&lang=lua&lang2=ruby Ruby]
+*It provides a "normal" scripting language with [https://en.wikipedia.org/wiki/Lua_(programming_language)#Features features] similar to PHP, perl, java, [[awk]], etc.
-* '''Model''' - code that reads / writes a config file, starts / stops daemons, or does other work modifying the router.
+Haserl + Lua provides a 'good enough' toolset to build a full-featured web application.
-* '''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.
+== Why ACF is MVC  ==
-The flow of a single transaction is:
+The MVC design pattern is used to separate presentation information from control logic. By MVC we mean:
-start ->
+*'''Model''' - code that reads / writes a config file, starts / stops daemons, or does other work modifying the router.
-execute requested function in '''controller''',
+*'''View''' - code that formats data for output
-optionally reading/writing a file using functions in the '''model''' ->
+*'''Controller''' - code that glues the two together
-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.
+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.
-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
+The flow of a single transaction is:
-[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.
-= ACF Developer's Guides =
+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
-# [[ACF_mvc.lua_reference|mvc.lua reference]]  - mvc.lua is the core of ACF
+''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.
-# [[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 core principles]] (Things that are standard across the application)
+Of course, as with all MVC designs, the ACF MVC design is not quite 'pure' MVC and has evolved over time. Most of the '''controller''' functionality is handled by the framework code. The framework code will also automatically generate views for HTML, JSON, and a few other viewtypes if no '''view''' is defined. Also, many '''model''' functions are implemented in helper libraries. We have attempted to make it as easy as possible to develop new ACF modules.
-# [[ACF Libraries ]] Document the libraries and common functions
-= ACF Modules =
+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 [https://www.cs.usfca.edu/~parrt/papers/mvc.templates.pdf https://www.cs.usfcs.edu].
-== Networking ==
+== ACF Developer's Guides  ==
-=== Firewall ===
-based on shorewall. Will need an advanced and simple interface
-=== Routing ===
+#[[ACF mvc.lua reference|mvc.lua reference]] - mvc.lua is the core of ACF
-this is for remote/multi box routing, bgp...etc
+#[[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 ACF modules
+#[[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
-=== Interfaces ===
+== How to contribute  ==
-Local interface management-local routing taken care of here
-=== DNS ===
+ACF has support for multiple skins. Some example skins available are:
-Caching/Hosting/for both Internet and Inside firewall nets
+*/usr/share/acf/www/skins/alps/
+*/usr/share/acf/www/skins/cloud/
+*/usr/share/acf/www/skins/ice/
+*/usr/share/acf/www/skins/snow/
+*/usr/share/acf/www/skins/wik/
-== Proxies ==
+Feel free to contribute in programming css-stylesheets for ACF.
-=== Web Proxies ===
-Squid
-=== Web Filtering ===
-Dansguardian
-=== Mail ===
-May Include fetchmail configuration/Relay host/store and forward
-== Connectivity ==
+* Make a new skin folder.{{Cmd|# mkdir -p /etc/acf/skins/myskin}}
-=== VPN ===
+* Create a css file called as the folder. {{Cmd|# touch /etc/acf/skins/myskin/myskin.css}}
-Needs to be split into an administrative end for letting people connect to you(rogue warriors,personal laptop size connectivity) and VPN connectivity to other sites(remote office or location). These are to configured differently.
-=== Dialup ===
+Now you can start editing your myskin.css.<br>If you have ACF running on the computer, you can browse to https://&lt;hostname&gt;/cgi-bin/acf/acf-util/skins/read and switch to your new skin (called myskin) and see the results of your changes.
-Start/Stop Dialup connection
-=== Dialup/PPPoE ===
+Pack your myskin folder, containing your css file (and images, if there are any).<br>Send this patch to acf@lists.alpinelinux.org ''('''Note:''' Don't forget to [[Alpine_Linux:Mailing_lists|subscribe]] before sending your patch)''
-Configure Dialup/PPP/PPPoE connectivity. Maybe other Internet connections that aren't ethernet-which is Interfaces
-== Backup/Packages ==
+== See also ==
-=== Backup ===
-Way to have save things not in /etc and just kickoff a lbu commit
-=== Source Manager ===
-Way to change the /etc/apk/apk.conf
-=== Package Manager ===
-Way to say what to upgrade-install-remove...apk_*
-== General ==
+* [https://www.lua.org/manual/5.1/ Lua 5.1 Reference Manual]
-=== Password Manager ===
+* [https://www.lua.org/pil/ Programming in Lua (first edition)]
-Local password changer
-=== Logfiles ===
-* General
-** The logfiles-model decides which folders should be listed.<BR>Based on this list files could be deleted/view/downloaded.
-** By manually entering a filename that doesn't match the logfiles-list you get a error message (wrong files could not be deleted/viewed/...)
-* Delete
-** File is blocked for removal if the file is in use.<BR>'fuser ''filename''' checks if file is in use at the moment.
-* View
-** Files could be blocked for viewing if this was programmed in the logfiles-model.<BR>Preparations has been done, but no rules has been defined if some file/files are blocked for viewing.
-* Download
-** Logfiles should be able to be downloaded.
-=== Diagnostic ===
+[[Category:ACF]] [[Category:Lua]]
-Stats/Resource use/maybe graphs-rrd