Directory structure

In this description we assume you are using a Linux server.

In the simplest set-up, one installation runs a single site:

• var
• • www
  • • backup (writable)
    • docstore (writable)
    • public_html
    • • .htaccess
      • cache (writable)
      • developer.txt
      • index.php
      • license.txt
      • private (writable)
      • public (writable)
      • robots.txt
      • zenario
      • zenario_custom
        • frameworks
        • modules
        • templates
          • grid_templates (writable)
      • zenario_siteconfig.php

The directories marked as writable need to be writable by the web server. To achieve this, you will either need to have global read/write permissions (777 for a directory, 666 for a file), or you will need to have them owned by your Apache user, who may be called www-data or similar depending on your Linux install.

Top-level directory structure

The Apache Document Root should be the public_html directory.

The backup directory is where Zenario may store backups. It should be outside of the Document Root directory (to prevent anyone downloading your backup files). It should be writeable by the web server.

The docstore directory is where Zenario stores downloadable files (such as PDFs, Word documents). Again this should be outside the Document Root, so as to prevent http requests from bypassing the CMS. It should be writeable by the web server.

public_html directory structure

The key sub-directories here are as follows:

• cache: Zenario uses this directory to cache images, whole web pages, and partial web pages (the output of plugins); must be writeable by the web server.
• private: used in conjunction with the docstore, when a CMS document is password-protected and a user is permitted to download it, Zenario creates a sub-directory in here with a cryptic name; inside that sub-directory it creates a symlink to the file in docstore. It may also create a .htaccess with an allowed-IP restriction for extra security (see Organizer->Configuration to set this). Must be writeable by the web server.
• public: used similarly to private, but for publicly-downloadable documents. The directory name is always the same, so that search engines should not be prevented from indexing the document; must be writeable by the web server
• zenario: the main software sub-directory. Should NOT be writeable by the web server, and you should NOT need to ever modify anything inside here. This directory does not contain anything specific to your site or its functionality.
• zenario_custom: the sub-directory where all of your customisations are kept. (More on this in a moment).

Key files

The key files in this sub-directory are:

• developer.txt: if present, this signifies that this is a developer installation (e.g. for the development of new modules). When this file exists, administrators will be prompted to turn on Dev Tools and other developer features
• .htaccess: for search-engine friendly URLs (e.g. example.com/page rather than example.com/index.php?cID=page) you will need mod_rewrite enabled in Apache, and for this .htaccess file to be in place.
• index.php: the main PHP script of Zenario.
• license.txt: your Zenario license text.
• robots.txt: this tells search engines (such as Google) not to index things in the cache, private and admin directories.
• zenario_siteconfig.php: you site's config file, containing database connection info and other parameters. Should be writeable during the install process, if you want to use the easy install, but otherwise the installer will give you the content to put into this file. After installation it can be read-only.

Inside the zenario_custom sub-directory

Inside the zenario_custom directory are all of the things that are customised in your site, in the way of designs and custom modules. Nothing else inside web-accessible directories (other than the zenario_siteconfig.php file) are specific to your site.

These directories are used as follows:

• frameworks: "frameworks" in Zenario are chunks of HTML that are generated by a plugin in a page; they are needed where CSS is not sufficient to customise the output. This directory contains a further sub-directory for each module that has a customised framework, in the same format as the zenario/modules directory.
• modules: This contains all of the custom modules used in your installation; for example, you may have written your own custom modules that may extend Zenario's standard modules (e.g. extends a module in zenario/modules), or you may have written a completely new module.
• templates: Contains all HTML template files and CSS files for your site. The Gridmaker system uses a sub-directory called grid_templates and writes grid-based template files into their (with one template file per CMS layout). Inside grid_templates is a deeper sub-directory called skins, and inside skins are further sub-directories with the themes for your site. The grid_templates directory should be writeable by the web server in order for Gridmaker to be able to write new layouts to the file system (when doing so, it writes the template PHP file, a CSS file, and makes a database entry).

By keeping all customisations in a single zenario_custom directory, it should be easy for you to use an SVN or similar software versioning system. It also makes it easy to upgrade Zenario, because all custom files are in this directory and not spread among the directories of standard software.

Non-Zenario directories in your home directory

Going back to the Document Root directory - in this example the public_html directory - if this is your allocated web directory on your server, there is nothing to stop you putting additional files and directories there.

For example, Google Webmaster Tools may ask you to add a special file here; and you may wish to have other subdirectories. Zenario does not prevent you adding these, provided you do not make anything with the reserved name stated above.

Installing in a subdirectory underneath Document Root

If you wish, you may install Zenario in a sub-directory inside the Document Root directory.

If you are running the installer at the eventual install directory, your URL will be of the form:

http://example.com/some-dir/

In that case, the installer will realise it's running in a subdirectory and it will take that into account when creating the zenario_siteconfig.php file. If you ever move your site (or change the web server Document Root location), you will need to take this into account. The following line will be in your zenario_siteconfig.php:

define('SUBDIRECTORY', '/some-dir/');

Make sure that the second part contains the path from Document Root to the installation directory, or just '/' (a slash between the quotes) if not being run in a sub-directory.