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.

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

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 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, xsltproc and html-minifier.

Preprocessed HTML also undergoes a few run-time substitutions:

• $foo (value of $foo)
• $_(Some string) Gettext translation of "Some string"
• $$ Literal $

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)">

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 and mgid 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.