TWiki's Directory Structure

This topic is sort of the theory behind SettingFileAccessRightsLinuxUnix, and perhaps helpful if for one or the other reason you can not follow the recipes given there, or if you need to move directories around and know where they are referenced, or if you need to sanitize your installation.

It is the verbose version of the table which can be found in the root directory of the TWiki distribution, file INSTALL.html, under the section "Notes on Installing TWiki on Non-Root Account".

The following description follows the directory layout as it is found in the distribution but re-orders the files and directories according to their intended use.

The Environment

The Players

In every web application there are different user ids (and group ids) involved, which need to be granted appropriate access rights. Note that all these are user ids of the operating system, not TWiki users:

• The user id under which the web server is running the TWiki CGIs
• The user id which you use to install and maintain TWiki, and under which your cron jobs are running (e.g. for mail notification)
• The server admin (root on Unix/Linux)

On "your own" machine you might be able to do the installation and maintenance as administrator, but on a hosted server things are more difficult. If you're lucky, then the user id under which the CGIs are running is the same as your ftp (or shell) account.

The Configuration Files

The paths of the directories which are listed in the next sections need to be announced in several places (details below):

• The file bin/LocalLib.cfg must contain the name to the absolute path of your lib directory.
• The file lib/LocalSite.cfg contains the absolute paths of your pub, templates, data, locales, and as of TWiki 4.2 working directories. You do not need to manually edit the file, the path names can be maintained using configure.
• The Web server configuration file needs to point to the absolute paths of your bin and pub directories. If you are (recommended) including the TWiki related configuration from your main web server config file, then the absolute path of the included file (usually httpd.conf in your root directory) needs to be defined in that main web server config file. Unfortunately location and organisation differ vastly between different Linux distributions, let alone other operating systems.
  • For Apache, there's a template at twiki_httpd_conf.txt, and you can create one online at TWiki.ApacheConfigGenerator.

The Web Server

Especially for TWikiOnWebHostingSites, there might be restrictions which directories can be made visible for the web server. For TWiki, there are two directories which need to be considered:

• The bin directory needs to be configured as containing executable files, for example with Apache's ScriptAlias directive. Web hosters often predefine the name cgi-bin and a special location, so you need to move the files to that location.
• The pub location contains what typically are "static" files for a web server. Move it to an appropriate location where your web server software will pick it up, its path names on the file system and in URL-space will be defined in the web server configuration and in TWiki's lib/LocalSite.cfg.

All the other files can - and should be - kept out of the way of the web server software. Once TWiki is configured, it will find them by absolute path names which you configure in various places, to be detailed below.

Details Per Directory

The files in TWiki's root directory are not needed for web operation.

• The root directory should not be exposed as an URL.
• The files in the directory must not be read by someone else than you.
• All subdirectories must be executable by the web server user.
• The robots.txt file from the root directory of the distribution is a template for controlling robots.
  • The file must be adapted to your installation's need and then made available under the url path /robots.txt (example: http://example.com/robots.txt) in the web server configuration (httpd.conf).
• It must be readable by the web server user.

The bin directory contains TWiki's executables.

• The directory must be mapped to URLs and declared as executable in the web server configuration.
• The directory and the files in the directory must be readable and executable by the web server user.

The pub directory contains files which can be served by the web server as static files: Images, CSS and Javascript files used by TWiki, as well as user's document attachments.

• The directory must be mapped to URLs in the web server configuration.
• The directory and the files in the directory must be readable and writeable by the web server user.
• You might want to do regular backups for this directory, because it contains your users' data.

The data directory contains TWiki's documentation as well as your user topics.

• The directory should not be exposed as an URL.
• The directory itself, the files in the directory and its subdirectories must be readable and writeable by the web server user.
• If you are using mail notification or automatic harvesting of dead sessions, then the files in the directory and its subdirectories must be readable and writeable by the cron user.
• The absolute path to the data directory is stored in lib/LocalSite.cfg, it can be changed with configure.
• The data directory holds, per default, TWiki's log files (settings {ConfigurationLogName}, {DebugFileName}, {WarningFileName}, and {LogFileName} in lib/LocalSite.cfg, changeable with configure.
• The data directory holds, per default, the .htpasswd file used to store users' mail addresses, and the passwords if you let TWiki do password management (setting {Htpasswd}{FileName} in lib/LocalSite.cfg, changeable with configure).
• The data directory holds, per default, the list of MIME types (setting {MimeTypesFileName} in lib/LocalSite.cfg, changeable with configure). On Linux, you might want to point to the system file /etc/mime.types instead.

The lib, locale, and templates, directories contain TWiki's "readonly" installation files for perl code, internationalisation and layout.

• The directories should not be exposed as URLs. It is recommended to keep them together as they come with the distribution.
• The absolute path to the lib directory must be written to bin/LocalLib.cfg.
• The absolute paths to the locale and templates directories are stored in lib/LocalSite.cfg. They can be changed with configure, section "General Path Settings".
• Several instances of the templates directory are defined with absolute path names in the setting {TemplatePath} in lib/LocalLib.cfg (changeable with configure).
• The directories and all subdirectories must be readable and executable by the web server user.
• The files in the directories must be readable by the web server user.
  • The file lib/LocalSite.cfg must be writeable by the web server user as well for configure operations.
  • If you want to install extensions using configure, then the files and directories need to be writeable by the web server user.
• You might want to do regular backups for the data directory, because it contains your users' data. Files in the locale and template directories will only change when new versions or extensions are installed.

The working directory (only in TWiki 4.2 and newer) holds temporary stuff.

• The directory should not be exposed as an URL. Per distribution this is guaranteed by the .htaccess file in the directory.
• The directory and its subdirectories must be readable, writeable, and executable by the web server user.
• The files in the directory must be readable and writeable by the web server user.
• The absolute path to the working directory is stored in lib/LocalSite.cfg, it can be changed with configure.

Final Note

This ought to be easier.

---

-- Contributors: HaraldJoerg

---

Comments & Questions about this Supplemental Document Topic

This writeup has been motivated by a lengthy debug session on IRC where we tried to move some directories to the right place and found out in how many places TWiki holds cross-references to absolute path names, and how different the procedure of moving things around is from the procedure of an initial install. It is for sure biased towards Linux and Apache, since my experience with other platforms is close to zero.

Please correct errors, complete missing items and add relevant documentation for Windows, IIS, whatever.

-- HaraldJoerg - 06 Nov 2007

Please use the Support forum if you have questions about TWiki features. This comment section is about the documentation of this topic.