Directory Layout

Now you've downloaded AxKit2, and you already tried "make install", but it didn't work. What is going on?

We expect you to make your own choice.

Why there is a choice to make

One part of AxKit2's philosophy is to keep things so simple you can easily adapt the code to your needs. A system-wide installation isn't terribly useful in such a situation. Moreover, if you have ever had to maintain a mass-hosting environment written in other popular technologies, you will probably know the pain of upgrades. By keeping each web site completely separate from each other, upgrades needed for one won't influence others.

On the other hand, a shared environment can have it's advantages as well, or even a mixed setup. TIMTOWTDI. The following sections show you several recommended variants.

AxKit2 in a private directory

This variant is easiest and, if well planned, very clean. Set up a user account for your web site, create a directory for AxKit2, and run it directly from there, without installing anything.

Pro:

  • strict code separation between several servers -- "set up and forget"
  • stricter filesystem security than in a one-server environment
  • crude but effective parallelism between web sites with easy load management
  • maximum per-user control over web services without any sudo/setuid/root hacks
  • better ability to work the Unix way, using traditional tools and mechanisms
  • can be installed without root privileges, shell access, even without compiler as long as just XML::LibXML is already present (which is quite probable)

Contra:

  • unusual setup for those accustomed to Apache
  • no centralized configuration
  • special provisions have to be taken for port 80 access and name-based virtual hosting

The last point can actually be transformed into an advantage if a smooth transition or side-by-side operation with existing web services is desired. See ReverseProxy and VirtualHosting for solutions that fill all three goals.

It really boils down to doing things differently than you are used to in exchange for some great advantages that usually were only possible in a difficult or hackish manner.

A note about performance: At first glance, creating a separate AxKit2 process for each virtual host might seem like a big waste of memory and processor power. But while that may indeed be true in some situations, often it is not. The Perl core will usually reside in memory shared between all Perl processes, as will C libraries like libxml. AxKit2 itself features small code size and few dependencies, thus it will usually weigh less than a typical Apache/mod_perl child process with similar functionality, especially when you add a web framework like AxKit1 or Mason. Resource usage must therefore be evaluated individually. Medium-sized hosting machines will probably neither improve nor worsen their resource usage when hosted by AxKit2.

This is an example how a web site home directory could be structured: 

/home/site1
       +-- axkit2             (from SVN or tarball)
       |    +-- axkit         (AxKit2 executable)
       |    +-- etc/...       (config file for AxKit2, password database and suchlike)
       |    +-- lib/...       (modules, AxKit2::* and custom)
       |    \-- plugins/...   (plugins, core and custom)
       |
       +-- data/...           (non-public data files like XSLT stylesheets)
       |
       +-- htdocs/...         (public data files like (X)HTML pages and images)
       |
       \-- log/...            (log files for this web site)

If you plan to mix AxKit2 with other services for the same site (running under the same user id), or if you want to separate custom files from the AxKit2 distribution, you could also choose a more generic layout: 

/home/site1
       +-- axkit2             (from SVN or tarball)
       |    +-- axkit         (AxKit2 executable)
       |    +-- lib/...       (AxKit2 modules)
       |    \-- plugins       (core plugins)
       |         \-- site1    (symlink pointing to ../../plugins)
       |
       +-- etc/...            (config files for all services)
       |
       +-- data/...           (non-public data files like XSLT stylesheets)
       |
       +-- htdocs/...         (public data files like (X)HTML pages and images)
       |
       +-- log/...            (log files for this web site)
       |
       +-- perl/...           (custom Perl modules shared between different services)
       |
       \-- plugins/...        (custom AxKit2 plugins for this site)

You get the idea. This way, upgrading AxKit2 and code sharing between services is easier.

Here is a minimal example configuration file for such a setup that does nothing but transform all XHTML files using a global default stylesheet: 

PluginDir axkit2/plugins

Plugin    logging/warn
LogLevel  LOGDEBUG

Plugin request_log
RequestLog log/access_log

Plugin fast_mime_map

<Server>
    Port   8000
    DocumentRoot   htdocs
    
    Plugin uri_to_file
    Plugin serve_file
    Plugin generic_transform
    
    DirectoryIndex index
    
    <Files *.xhtml>
        Transformation XSLT(data/xsl/global.xsl)
    </Files>

</Server>

One AxKit2 server for the whole system

In this variant, the AxKit2 modules would be installed in the usual locations for Perl extensions, plugins would also reside in a system-wide location, and usual system locations for logging and your system's service management would be used. For now, you will have to set up files by hand for this scheme, the AxKit2 team is yet undecided what exact locations to use.

Pro:

  • behaviour matches traditional web servers, thus easy to understand
  • centralized configuration
  • no additional software needed for name-based virtual hosting
  • maximized sharing of code and data

Contra:

  • name-based virtual hosting not yet working (although nearly :))
  • problems (bugs, overload) in one web site easily effect all web sites
  • no resource control over individual web sites
  • no utilization of multiple CPUs
  • needs the same amount of work as other setups for side-by-side operation with other web services

Central installation, but multiple processes

In this variant, AxKit2 modules are installed system-wide, plugins and the axkit executable script may or may not be installed system-wide, while there is a private home directory for each web site, including custom plugins. It shares all run-time advantages of a multi-server installation, but also some disadvantages of the single-server installation.

Pro:

  • easier update management for core components
  • standardized setup procedure (when this setup is supported out-of-the-box)

Contra:

  • updates can mess up older web sites in subtle ways
  • little experience, no "best practice" guidelines for this setup available