Installing a Custom Control Panel

Our web-based Control Panel (also known as csoftadm.fcgi) is open-source and re-usable by all. It is designed to be easily integrated into an existing website, and customized both cosmetically (using templates), and on an operational level.

csoftadm.fcgi runs as a standalone FastCGI application server which talks to a CsoftMGI server over a TCP connection. Instances of csoftadm.fcgi don't need any particular privileges to work.

csoftadm.fcgi is written in C and depends on the libmgid and libpercgi libraries. Optional dependencies include libidn (for internationalized domain names), cracklib (for password strength testing) and libiconv (for the webmail module). Those libraries are standard on all Csoft.net servers.

On the browser side of things, the latest version of csoftadm.fcgi utilizes jQuery, DataTables and Ace. csoftadm.fcgi is also designed to integrate seamlessly with the latest version of Bootstrap.

Downloading the source

First download the csoftadm.fcgi sources into some temporary directory under your $HOME, such as ~/src/csoftadm. At this time, we are not making numbered csoftadm.fcgi releases, so the source is only available via Subversion:

  $ mkdir ~/src
  $ cd ~/src
  $ svn co https://dev.csoft.net/mgid/trunk/cgi csoftadm.fcgi

Execute ./configure to prepare for compilation, and specify the directory in which you want csoftadm.fcgi installed, using --prefix.

  $ cd csoftadm.fcgi
  $ ./configure --prefix=$HOME/www/mycsoftadm --with-html-source

Tip: If you omit --with-html-source, the HTML sources/templates and all other files which are needed to re-generate your HTML files will not be installed. This reduces the number of files, but you will need to edit your HTML templates and sources from csoftadm.fcgi's source directory instead.

When the configure script finishes, you are ready to build and install:

  $ make all depend install

At this point you can delete ~/src/csoftadm.fcgi. If you inspect $HOME/www/mycsoftadm, you should see the csoftadm.fcgi binary.

Creating user-map

csoftadm.fcgi has only a single configuration file, ./etc/user-map. This file defines which users are allowed to connect, and what server is actually hosting their account (this applies to all account types including mailbox accounts).

Each line should contain one username and one hostname, separated by a colon. Unless you have multiple csoft.net accounts on multiple servers, you will probably only need to use localhost as server:

  alice:localhost
  bob:foo.domain.ext
Editing the templates

Cosmetic changes usually boils down to editing the master template file, html/m4/csoft.m4. The template is standard HTML5 (and may use M4 macros or XSLT transforms). When you are done with your edits, run make(1) in the html/ directory.

If more specific changes are required (e.g., moving forms around or adding translations to new languages), the HTML source files (those files with the *.htm extension in html/) can be edited. *.htm files will be preprocessed, at compile time, using m4(1), xsltproc(1) and html-minifier(1).

Preprocessed HTML also undergoes a few run-time substitutions:

  • $foo (value of $foo)
  • $_(Some string) Gettext translation of "Some string"
  • $$ Literal $
Translating to a new language

To translate the control panel to a new language, open up the *.htm sources files in an editor, and insert your translated text: <ml lang="xx"></ml>, where xx is the ISO language code. Note that the *.htm source files all use UTF-8 encoding.

In addition to <ml> tags, csoftadm.fcgi also uses Gettext to perform dynamic dictionary-type translations. Go to the ./po directory and run make. Copy csoftadm_fcgi.pot to xx.po and simply edit the "msgstr" lines xx.po using your favorite text editor.

Source *.htm files can take advantage of Gettext translations using the special syntax: $_(Some string). This method is recommended where short text appears in instances such as:

  <input type="text" placeholder="$_(Your name)">
Code changes

Developers familiar with C can further customize the operation of the web interface by editing, what we hope, is relatively easy-to-understand code. Documentation for both the percgi(3) and mgid(3) libraries is available.

Client functions are organized in a set of modules. For example, group.c is an interface to the unix group management functions of the csoftadm server. It implements functions named group_list, group_add, group_del, etc. Those functions use the MGI_Query() and MGI_QueryData() calls to communicate with the csoftadm server. The MGI_* API is documented on the CsoftMGI website.

You are of course encouraged to submit any change you believe would be appreciated by other users. Please contact us directly or use Bugs.csoft.net to submit bug reports, feature requests and patches.


Csoft.net
© 2024 CubeSoft Communications
All Rights Reserved.