System.InstallationGuide
(the InstallationGuide topic in the System web).
For information on upgrades, please also refer to Foswiki:System.UpgradeGuide. A static HTML version of this document, UpgradeGuide.html
, is included in the root of your Foswiki distribution.
UpgradeGuide.html
, is included in the root of your Foswiki distribution.
Verify that your server meets the Foswiki system requirements, including having the minimum required Perl version and all required Perl modules installed. If you need to install any Perl libraries from CPAN for use by Foswiki, see Foswiki:Support.HowToInstallCpanModules for more information.
To install Foswiki, complete the following steps:
/path/to/foswiki
. foswiki
directory tree.
Note: for more information on the appropriate permissions to ensure security for your Foswiki data, see Foswiki:Support.SecuringYourSite.
The default file and directory access permissions as set by the distribution define a reasonable security level that will work for many types of installations, including shared hosting. Nonetheless, you should verify that the web server user has read access to all files and directories beneath the foswiki
directory, and execute access for all directories. Also verify that the data
and pub
directories and all the subdirectories and files beneath them allow write access for the web server user. chmod -R 770 foswiki
. Providing execute access to all files is potentially dangerous. This is a common mistake made by Foswiki installers. See Foswiki:Support.SettingFileAccessRightsLinuxUnix for a sample set of Unix commands to set the file and directory permissions.
It is possible to define tighter access permissions than the default ones; how tight they should be depends on your web server environment and local needs. Typically you should limit all access from others if the web server machine has login access for users other than root and the web server administrator. For a dedicated web server that just runs Foswiki and has limited login access, the default access permissions have a good safety level.
If you have root user permissions, then for additional security, you can change the ownership of thefoswiki
directory tree to the web server user, using the command chown -R user:group /path/to/foswiki
. The web server username varies in different installations; here are some sample commands for various Linux distributions: chown -R apache:apache /path/to/foswiki
chown -R www-data:www-data /path/to/foswiki
chown -R wwwrun:www /path/to/foswiki
/usr/bin/perl
then this step is not required. This step is required on Windows installations.
The easiest way to fix up the bin scripts is to run the tools/rewriteshebang.pl
script. If the Perl interpreter is in the default execution path, follow these steps:
cd /path/to/foswiki/tools perl -I ../lib rewriteshebang.pl
or for Windows users:
cd C:\path\to\foswiki\tools perl -I ..\lib rewriteshebang.pl
The script will determine the location of the Perl interpreter and will prompt to update both the bin and tools scripts in a single step. The changed files will be reported, and it is safe to rerun the script.
If theperl
command does not work from the command line, then you need to find the location of your system's Perl interpreter. Insert the path to Perl in the first line of the rewriteshebang
script. For example:
cd C:\path\to\foswiki\tools C:\path\to\perl -I ..\lib rewriteshebang.pl
.cgi
or .pl
). This is not normally required with the Apache web server, though some hosted web servers are configured to require it. If the documentation for your web server indicates that a special extension is necessary, rename all the executable scripts in bin
; that is, rename bin/view
to bin/view.pl
, and so on. When configuring Foswiki (see the section "Configure Foswiki"), set the ScriptSuffix
option to the special extension.
bin/
and lib/
located under the Foswiki installation directory. If you have moved these directories, or if your system requires changes to the default Perl libraries, then this step is required.
Create the file LocalLib.cfg located at bin/LocalLib.cfg
bin
directory, copy the template file LocalLib.cfg.txt
to LocalLib.cfg
. Make sure the ownership and access rights of the copy are the same as LocalLib.cfg.txt.
bin/LocalLib.cfg
so that $foswikiLibPath
is set to the absolute file path of your lib
directory. For example: /path/to/foswiki/lib
.
$CPANBASE
to point to your personal CPAN install. Don't forget that the web server user has to be able to read those files as well.
foswiki.conf
). Performance is much better with a config file, and one file gives the best overview and ensures that you get a safe installation . However to use a config file you need root or sudo access to stop and start Apache. The Foswiki apache config file can be included from the main Apache config file. (Typically httpd.conf
or apache.conf
depending on your distribution). However most distributions have a directory from which any file that ends with .conf
gets included when you restart Apache (Example RedHat/Fedora/Centos: /etc/httpd/conf.d
, Gentoo: /etc/apache2/vhost.d
). If you use a virtual host setup in Apache you should include the foswiki.conf
file from inside the desired virtual host config in your Apache configuration.
.htaccess
files on each page access. Normally this is the only way to control Apache in a shared host environment where you have no root or sudo privileges.
foswiki_httpd_conf.txt
can be found in the root of the foswiki installation.
bin
and pub
. foswiki_httpd_conf.txt
file also has examples of configuring Apache appropriately.
ScriptAlias
directive for the bin
subdirectory, or an Alias
directive with SetHandler cgi-script
and Options ExecCGI
directives for the bin
subdirectory, so that the bin
scripts will be executed by Apache.
.htaccess
files for various subdirectories in your installation. Each file has help text explaining how to modify it for your configuration. For more information, see Foswiki:Support.SupplementalDocuments. location and name of sample .htaccess file | copy sample file to the following location |
---|---|
foswiki/root-htaccess.txt | foswiki/.htaccess |
foswiki/bin-htaccess.txt | foswiki/bin/.htaccess |
foswiki/pub-htaccess.txt | foswiki/pub/.htaccess |
foswiki/subdir-htaccess.txt | foswiki/<subdir>/.htaccess Copy to all other subdirectories below foswiki , including data , lib , locale , templates , tools , working . Copy to any other directories except for bin and pub addressed above. |
bin
and pub
. The sample .htaccess
files show how to configure Apache appropriately. It is important to verify that none of these directories can be directly accessed.
foswiki/bin/.htaccess
files contains the line SetHandler cgi-script
so that all scripts in the bin
directory will be executed by Apache.
.htaccess
are hidden files and will not be listed unless using the -a option, ex. ls -la
pub
directory. For example, most Linux distributions have a default Apache installation with PHP and server side include (SSI) enabled. This would allow PHP scripts uploaded as attachments to be executed, which is a security risk, so it should be disabled in the Apache configuration with php_admin_flag engine off
.
Different script execution mechanisms are disabled in different ways; see your web server configuration and documentation for more details.
configure
script open to the public. Limit access to the bin/configure
script to either localhost, an IP address or a specific user using basic Apache authentication. The Foswiki:Support.ApacheConfigGenerator lets you setup who has access to the configure
script. Also see the foswiki-httpd-conf.txt
or bin/.htaccess.txt
file for an example of the setting required to protect the configure
script.
To limit access to a particular user, set up a .htpasswd
file that contains the user name and password that Apache will use to authenticate the user: .htpasswd
file. It will destroy the email addresses stored in that file! If the file already exists, you can choose an existing user for access to configure.
foswiki/data
directory.
htpasswd -c .htpasswd <username>
, where <username> is the name of the user you will use to access the configure
script. Choose the username with care: the username cannot be an existing login name for your Foswiki installation, nor can it be used later on to register in Foswiki. Enter a password when prompted.
.htaccess
files, all include example settings to protect the configure script with a password. The critical section looks something like:
<FilesMatch "configure.*"> SetHandler cgi-script Order Deny,Allow Deny from all # List of IP addresses allowed to access configure Allow from 127.0.0.1 192.168.1.10 # specify username used on the "htpasswd" command above Require user someuserid # Set to "Any" to allow IP -or- userid, set to "All" to require both match Satisfy Any ErrorDocument 401 default </FilesMatch>Note: In addition to any web server security protection that you have set up, when saving any configuration settings for the first time on the
configure
web page, you will be prompted to set a configuration password. This password must be entered on all subsequent configuration changes, and is also used to log in via the internal admin link (see the section "Define the administrator user(s)"). Even after a configure
password has been set, access to the configure
page should still be restricted by the web server, in order to avoid revealing internal information to potential attackers.
Tip: You do not have to use the same password file for both Configure and for Foswiki user registration. If you use a separate file, you can create it using theFor more information, refer to Foswiki:Support.ProtectingYourConfiguration.htpasswd
commmand and complete segregate configure access from Foswiki access. This is probably safer, but does not allow users to change their configure password using Foswiki services. The password file has to be manually maintained..
- Generate an alternate password file to protect configure.
htpasswd -c -s /path/to/data/.htpasswd-admin configuserid
- Add / modify and delete this alternate file using the
htpasswd
command. Don't mix them up and usehtpasswd
on the Foswiki .htpasswd file!- Edit the foswiki apache configuration and modify the block (shown above) that protects the configuration command. Add or modify the following statements in the block. Don't remove the other statements!
<FilesMatch "configure.*"> AuthType Basic AuthName "admins only" AuthUserFile /path/to/data/.htpasswd-admin # Changing the Require user to Require valid-user allows any ID in the # file access to configure! Require valid-user </FilesMatch>
http://yourdomain/url/to/foswiki/bin/configure
into your browser address bar. configure
web page for the first time, you can only edit the section General Path Settings
. Make any required changes, and save the settings, whether or not you needed to make any changes. You will be prompted to set a password for the configure
page: this password must be entered for all subsequent configuration changes, and is also used to log in via the internal admin link (see the section "Define the administrator user(s)"). Note: The
configure
password is remembered byconfigure
, separate to web server access controls mentioned in "Protect the configure script".
General Path Settings
, continue configuring Foswiki. Configuration items which may require further attention will be highlighted.
{PermittedRedirectHostUrls}
. Example: if
{DefaultUrlHost}
is set tohttps://wiki.company.com
, an example{PermittedRedirectHostUrls}
might contain:https://company.com, http://111.222.123.234
Mail and Proxies
section. Email must be available so Foswiki can send registration emails. {EnableEmail}
. Otherwise the {WebMasterEmail}
parameter must be configured.
MailProgram
is typically suitable on most Linux systems, and no further configuration is required.
Net::SMPT
methods, you must also configure {SMTP}{MAILHOST}
. Many ISPs have introduced authentication when sending emails to fight spam so you may also have to set {SMTP}{Username}
and {SMTP}{Password}
.
Net::SMTP::SSL
will encrypt the connection to the e-mail server and is required for some email services like Google's GMail.
configure
, you may have to set {PROXY}{HOST}
and {PROXY}{PORT}
. SMTP authentication requires additional perl modules includingNote: If e-mail is enabled in configure, Foswiki will not allow any new registrations unless e-mail is functional. In order to avoid issues, return to the
Mail and Proxies
,Email Test
tab inconfigure
and verify that Foswiki can successfully send e-mail.
Authen::SASL
and MIME::Base64
,
configure
page, you can configure Foswiki manually.
mod_auth_ldap
or mod_auth_mysql
. However, as your browser is caching your login, you must restart the browser to log out.
Note that the password databases for both of these authentication mechanisms are compatible, so you can switch between them at a later date.
To make it easier to follow the instructions in this section, you can view this installation guide using your Foswiki site by enteringSystem.InstallationGuide
into the "Jump" text box. By doing this instead of using the INSTALL.html
file from the distribution, you will be able to use the embedded hyperlinks to jump directly to the referenced pages.
Login
, Password
and user mapping
options.configure
, Security And Authentication
tab Login
tab on the Security and Authentication
panel. Select the Foswiki::LoginManager::TemplateLogin
login manager.
Passwords
tab. Select the appropriate PasswordManager
for your system - the default is Foswiki::Users::HtPasswdUser
. {TemplateLogin}{PreventBrowserRememberingPassword}
that you can set to prevent Browsers from remembering username and passwords if you are concerned about public terminal usage.{TemplateLogin}{AllowLoginUsingEmailAddress}
that you can set to allow users to login using their password system registered e-mail addresses.The rest of this section describes Webserver Login using the Apache web server, but the same process is applicable to other webserver implementations as well (though you may require a customised version of the ApacheLogin module to do it).
The advantage of this scheme is that if you have an existing website authentication scheme using Apache modules such asmod_auth_ldap
or mod_auth_mysql
you can just plug in to them directly.
The disadvantage is that because the user identity is cached in the browser, you can log in, but you can't log out again unless you restart the browser.
Foswiki maps theREMOTE_USER
that was used to log in to the webserver to a WikiName using the table in Main.WikiUsers. This table is updated whenever a user registers, so users can choose not to register (in which case their webserver username is used for their signature) or register (in which case that username is mapped to their WikiName).
The same private .htpasswd
file used in Foswiki Template Login can be used to authenticate Apache users, using the Apache Basic Authentication support.
htpasswd
program to modify .htpasswd
files generated by Foswiki! htpasswd
wipes out e-mail addresses that Foswiki saves in the info fields of this file.
mod_ldap
REMOTE_USER
environment variable.
To set up Apache Login, perform the following steps:
Security and Authentication
pane on the Login
tab in configure
: Foswiki::LoginManager::ApacheLogin
for {LoginManager}
.
Foswiki::Users::HtPasswdUser
for {PasswordManager}
.
Foswiki::Users::TopicUserMapping
for {UserMappingManager}
.
foswiki/bin-htaccess-advanced.txt
file to set the following Apache directives on the bin
scripts:(This example is for Apache 2.2, there are changes required if using Apache 2.4) AuthType Basic <FilesMatch "(attach|edit|manage|rename|save|upload|mail|logon|.*auth).*"> require valid-user </FilesMatch>You can also refer to the sample
foswiki_httpd_conf.txt
and bin-htaccess-advanced.txt
files to see how the appropriate Apache directives are specified.
Store
pane in configure
you will find the setting {RCS}{SearchAlgorithm}
.
By default it is set to Foswiki::Store::SearchAlgorithms::Forking
which is what you should keep if you install Foswiki in Linux or any other Unix type operating system.
If you install Foswiki on a Windows server, using an external grep program can create problems because of limitations in the length of command lines. You may be able to run with Forking in Windows if your directory path to Foswiki is kept short (short directory names and few levels), however the recommended (safe) setting for Windows is Foswiki::Store::SearchAlgorithms::PurePerl
.
admin
and the password established when initially saving the configuration. Don't log in with the wikiname AdminUser
.
After installing Foswiki, you can also register other users that you will use to administer Foswiki. To make a user an administrator, add the WikiName for the user to the AdminGroup
, defined in the AdminGroup
topic in your Foswiki installation.
Note that with the sudo or internal admin login, it is not necessary to add other users to the AdminGroup. However if you have more than one administrator, you may still want to do this to ensure that topic changes are attributed to a specific user instead of the default Main.AdminUser.
By adding users to Main.AdminGroup: bin/configure
password is not required
bin/configure
will need to be shared among administrators
System.InstallationGuide
into the "Jump" text box. By doing this instead of using the INSTALL.html
file from the distribution, you will be able to use the embedded hyperlinks to jump directly to the referenced pages.
To add an initial administrator to the AdminGroup
, perform the following steps:
AdminGroup
topic and select the "internal admin login" link. Login using the password you set on the configure
page.
Main.AdminGroup
topic. Follow the instructions on the page to add users to the AdminGroup. You do not need to edit the topic.
Any member of the Main.AdminGroup can add subsequent members — you do not have to use the internal admin login.
To more easily debug access control issues, you may want to have a regular Foswiki user account for daily use, and a special one that belongs to theAdminGroup
that you use only for administering your Foswiki site. See AccessControls for more information on access controls and user groups.
http://yourdomain.com/url/to/foswiki/bin/view/System/InstallationGuidePart2
to proceed with further tailoring your site..
In order to keep your user, group, and site configuration information separate from the actual content of your site, it is recommended that you create a new web in which your site's pages will reside. See ManagingWebs for more information on Wiki webs and how to create one.
configure
script and make sure you have resolved all errors and are satisfied that you understand any warnings.
Foswiki is written in Perl 5, which is supported on Microsoft Windows as well as Unix and Unix-like systems (including Linux and OSX). On Unix-like systems, it uses a number of shell commands. It should be able to run out-of-the-box on any server platform that meets the following requirements.
Resource | Required Server Environment |
---|---|
Perl | 5.8.8 or higher. A minimum of perl 5.12 is recommended. |
External programs | GNU diff 2.7 or higher, fgrep , and egrep (not required on Windows) |
Web server | Apache, Nginx and Lighttpd are all well supported; Apache sample configs are provided. For information on other servers, see Foswiki:Support.InstallingOnSpecificPlatforms. |
configure
script is run, but start from your expected default "view" URL, so that Foswiki can figure out your URL scheme.
Prior versions of Foswiki shipped with the important CPAN modules. Foswiki 2.0 does not, and you must ensure that the perl dependencies listed below are installed before attempting to use Foswiki. For a detailed report, PerlDependencyReport (admin access only!) or the shell script tools/dependencies
.
If you are unable to install CPAN modules, see Foswiki:Extensions.CpanContrib. Install this extension into your Foswiki installation directory if you cannot install Perl modules otherwise.
You can check the dependencies before Foswiki is fully operational with the following command. It will list all potentially missing dependencies. Not all listed dependences are required on all installations, Refer to the usage message that accompanies each missing dependency in the report.
cd /path/to/foswiki perl tools/dependencies
apt-get install apache2 rcs
Perl Module | Package to install | Notes |
---|---|---|
Algorithm::Diff | libalgorithm-diff-perl |
|
Archive::Tar | libarchive-tar-perl |
|
Authen::SASL | libauthen-sasl-perl |
|
CGI | libcgi-pm-perl |
|
CGI::Session | libcgi-session-perl |
|
Crypt::PasswdMD5 | libcrypt-passwdmd5-perl |
|
Digest::SHA | libdigest-sha-perl |
*First shipped in perl 5.9.3 |
Email::Address::XS | libemail-address-xs-perl |
|
Email::MIME | libemail-mime-perl |
|
Encode | libencode-perl |
|
Error | liberror-perl |
|
File::Copy::Recursive | libfile-copy-recursive-perl |
|
HTML::Parser | libhtml-parser-perl |
|
HTML::Tree | libhtml-tree-perl |
|
IO::Socket::IP | libio-socket-ip-perl |
First shipped perl 5.19.8 |
IO::Socket::SSL | libio-socket-ssl-perl |
|
JSON | libjson-perl |
|
Locale::Codes | liblocale-codes-perl |
|
Locale::Maketext | liblocale-maketext-perl |
|
Locale::Maketext::Lexicon | liblocale-maketext-lexicon-perl |
Optional, needed for internationalization |
Locale::Msgfmt | liblocale-msgfmt-perl |
Optional, needed for internationalization |
LWP | libwww-perl |
|
LWP::Protocol::https | liblwp-protocol-https-perl |
|
URI | liburi-perl |
|
version | libversion-perl |
Must be version 0.77 or newer, included with perl 5.10.1 and newer. |
apt-get install
libalgorithm-diff-perl
libarchive-tar-perl
libauthen-sasl-perl
libcgi-pm-perl
libcgi-session-perl
libcrypt-passwdmd5-perl
libdigest-sha-perl
libemail-address-xs-perl
libemail-mime-perl
libencode-perl
liberror-perl
libfile-copy-recursive-perl
libhtml-parser-perl
libhtml-tree-perl
libio-socket-ip-perl
libio-socket-ssl-perl
libjson-perl
liblocale-codes-perl
liblocale-maketext-perl
liblocale-maketext-lexicon-perl
liblocale-msgfmt-perl
libwww-perl
liblwp-protocol-https-perl
liburi-perl
libversion-perl
Install as needed.
Perl Module | Package to install | Notes |
---|---|---|
mod_perl2 | libapache2-mod-perl2 |
Required if using Apache 2 and mod_perl |
Apache2::Request | libapache2-request-perl |
Required if using Apache 2 and mod_perl |
DBI | libdbi-perl |
Used for the Foswiki Page cache |
DBD::mysql | libdbd-mysql-perl |
Used for MySQL based Page Cache |
DBD::Pg | libdbd-pg-perl |
Used for PostgreSQL based Page Cache |
DBD::SQLite | libdbd-sqlite3-perl |
Used for SQLite based Page Cache |
FCGI | libfcgi-perl |
Optional, needed for fastcgi / fcgi apache modules |
FCGI::ProcManager | libfcgi-procmanager-perl |
Optional, needed for fastcgi / fcgi process management on nginx |
Crypt::SMIME | libcrypt-smime-perl |
Optional, used for S/MIME email signing |
Crypt::X509 | libcrypt-x509-perl |
Optional, used for S/MIME email signing |
Convert::PEM | libconvert-pem-perl |
Optional, used for S/MIME email signing |
chown -R www-data:www-data /path/to/foswiki
a2enmod rewrite
a2enmod cgi
OR a2enmod cgid
a2enmod access_compat
Install apache2, rcs, and perl-CPAN
Perl Module | Package to install | Notes |
---|---|---|
Algorithm::Diff | perl-Algorithm-Diff |
|
Archive::Tar | perl-Archive-Tar |
*First shipped in perl 5.9.3 |
Authen::SASL | perl-Authen-SASL |
|
CGI | perl-CGI |
|
CGI::Session | perl-CGI-Session |
|
Crypt::PasswdMD5 | perl-Crypt-PasswdMD5 |
|
Digest::SHA | perl-Digest-SHA |
*First shipped in perl 5.9.3 |
Email::Address::XS | perl-Email-Address-XS |
|
Email::MIME | perl-Email-MIME |
|
Encode | perl-Encode |
|
Error | perl-Error |
|
File::Copy::Recursive | perl-File-Copy-Recursive |
|
HTML::Parser | perl-HTML-Parser |
|
HTML::Tree | perl-HTML-Tree |
|
IO::Socket::IP | perl-IO-Socket-IP |
First shipped perl 5.19.8 |
IO::Socket::SSL | perl-IO-Socket-SSL |
|
JSON | perl-JSON |
|
Locale::Language | perl-Locale-Codes |
|
Locale::Maketext | perl-Locale-Maketext |
|
Locale::Maketext::Lexicon | perl-Locale-Maketext-Lexicon |
Optional, needed for internationalization ** |
Locale::Msgfmt | perl-Locale-Msgfmt |
Optional, needed for internationalization ** |
LWP | perl-libwww-perl |
|
LWP::Protocol::https | perl-LWP-Protocol-https |
|
URI | perl-URI |
|
version | perl-version |
Must be version 0.77 or newer, included with perl 5.10.1 and newer. |
Locale::Maketext::Lexicon
and Locale::Msgfmt
are not available on
Centos. Install using CPAN if Internationalization is required.
First add the appropriate perl module repository, and then install the packages.
yum install -y epel-release
yum install
perl-Algorithm-Diff
perl-Archive-Tar
perl-Authen-SASL
perl-CGI
perl-CGI-Session
perl-Crypt-PasswdMD5
perl-Digest-SHA
perl-Email-Address-XS
perl-Email-MIME
perl-Encode
perl-Error
perl-File-Copy-Recursive
perl-HTML-Parser
perl-HTML-Tree
perl-IO-Socket-IP
perl-IO-Socket-SSL
perl-JSON
perl-Locale-Codes
perl-Locale-Maketext
perl-Locale-Maketext-Lexicon
perl-Locale-Msgfmt
perl-libwww-perl
perl-LWP-Protocol-https
perl-URI
perl-version
zypper ar -f -n perl-modules http://download.opensuse.org/repositories/devel:/languages:/perl/openSUSE_13.1 perl-modules
zypper install
perl-Algorithm-Diff
perl-Archive-Tar
perl-Authen-SASL
perl-CGI
perl-CGI-Session
perl-Crypt-PasswdMD5
perl-Digest-SHA
perl-Email-Address-XS
perl-Email-MIME
perl-Encode
perl-Error
perl-File-Copy-Recursive
perl-HTML-Parser
perl-HTML-Tree
perl-IO-Socket-IP
perl-IO-Socket-SSL
perl-JSON
perl-Locale-Codes
perl-Locale-Maketext
perl-Locale-Maketext-Lexicon
perl-Locale-Msgfmt
perl-libwww-perl
perl-LWP-Protocol-https
perl-URI
perl-version
Install as needed.
Perl Module | Package to install | Notes |
---|---|---|
mod_perl2 | mod_perl |
Required if using Apache2 and mod_perl |
Apache2::Request | perl-libapreq2 |
Required if using Apache 2 and mod_perl |
DBI | perl-DBI |
Used for the Foswiki Page cache |
DBD::mysql | perl-DBD-mysql |
Used for MySQL based Page Cache |
DBD::Pg | perl-DBD-Pg |
Used for PostgreSQL based Page Cache |
DBD::SQLite | perl-DBD-SQLite |
Used for SQLite based Page Cache |
FCGI | perl-FCGI |
Optional, needed for fastcgi / fcgi apache modules |
FCGI::ProcManager | perl-FCGI-ProcManager |
Optional, needed for fastcgi / fcgi process management on nginx |
Crypt::SMIME | perl-Crypt-SMIME |
Optional, used for S/MIME email signing (Not available in default repositories) |
Crypt::X509 | perl-Crypt-X509 |
Optional, used for S/MIME email signing |
Convert::PEM | perl-Convert-PEM |
Optional, used for S/MIME email signing |
chown -R wwwrun:www /path/to/foswiki
www-servers/apache
, dev-vcs/rcs
, and dev-lang/perl
Perl Module | Package to install | Notes |
---|---|---|
Algorithm::Diff | dev-perl/Algorithm-Diff |
|
Archive::Tar | perl-Archive-Tar |
*First shipped in perl 5.9.3 |
Authen::SASL | dev-perl/Authen-SASL |
Optional, needed for authenticated SMTP |
CGI | dev-perl/CGI |
|
CGI::Session | dev-perl/CGI-Session |
|
Crypt::PasswdMD5 | dev-perl/Crypt-PasswdMD5 |
|
Digest::SHA | Included with perl | |
Email::Address::XS | dev-perl/Email-Address-XS |
|
Email::MIME | dev-perl/Email-MIME |
|
Error | dev-perl/Error |
|
Encode | Included with perl | |
File::Copy::Recursive | dev-perl/File-Copy-Recursive |
|
HTML::Parser | dev-perl/HTML-Parser |
|
HTML::Tree | dev-perl/HTML-Tree |
|
IO::Socket::IP | Ebuild not avaiable. Install with g-cpan if IPv6 is needed. | |
IO::Socket::SSL | dev-perl/IO-Socket-SSL |
Optional, support encrypted email connection: STARTTLS or SSL |
JSON | dev-perl/JSON |
|
Locale::Maketext | Included with perl | |
Locale::Maketext::Lexicon | dev-perl/Locale-Maketext-Lexicon |
Optional, needed for internationalization |
Locale::Msgfmt | dev-perl/Locale-Msgfmt |
Optional, needed for internationalization |
LWP | dev-perl/libwww-perl |
|
LWP::Protocol::https | dev-perl/LWP-Protocol-https |
|
URI | dev-perl/URI |
|
version | Must be version 0.77 or newer, included with perl 5.10.1 and newer. |
emerge
dev-perl/Algorithm-Diff
perl-Archive-Tar
dev-perl/Authen-SASL
dev-perl/CGI
dev-perl/CGI-Session
dev-perl/Crypt-PasswdMD5
dev-perl/Email-Address-XS
dev-perl/Email-MIME
dev-perl/Error
dev-perl/File-Copy-Recursive
dev-perl/HTML-Parser
dev-perl/HTML-Tree
dev-perl/IO-Socket-SSL
dev-perl/JSON
dev-perl/Locale-Maketext-Lexicon
dev-perl/Locale-Msgfmt
dev-perl/libwww-perl
dev-perl/LWP-Protocol-https
dev-perl/URI
Install as needed.
Perl Module | Package to install | Notes |
---|---|---|
mod_perl2 | www-apache/mod_perl |
Required if using Apache 2 and mod_perl |
Apache2::Request | libapache2-request-perl |
Required if using Apache 2 and mod_perl |
DBI | dev-perl/DBI |
Optional - Used for the Foswiki Page cache |
DBD::mysql | dev-perl/DBD-mysql |
Optional - Used for MySQL based Page Cache |
DBD::Pg | dev-perl/DBD-Pg |
Optional - Used for PostgreSQL based Page Cache |
DBD::SQLite | dev-perl/DBD-SQLite |
Optional - Used for SQLite based Page Cache |
FCGI | dev-perl/FCGI |
Optional, needed for fastcgi / fcgi apache modules |
FCGI::ProcManager | dev-perl/FCGI-ProcManager |
Optional, needed for fastcgi / fcgi process management on nginx |
Crypt::SMIME | dev-perl/Crypt-SMIME |
Optional, used for S/MIME email signing |
Crypt::X509 | dev-perl/Crypt-X509 |
Optional, used for S/MIME email signing |
Convert::PEM | dev-perl/convert-pem |
Optional, used for S/MIME email signing |
chown -R apache:apache /var/www/path-to-foswiki
apache24
, rcs
, and perl5
Perl Module | Package to install | Notes |
---|---|---|
Algorithm::Diff | p5-Algorithm-Diff |
|
Archive::Tar | p5-Archive-Tar |
|
Authen::SASL | p5-Authen-SASL |
|
CGI | p5-CGI |
|
CGI::Session | p5-CGI-Session |
|
Crypt::PasswdMD5 | p5-Crypt-PasswdMD5 |
|
Digest::SHA | p5-Digest-SHA |
*First shipped in perl 5.9.3 |
Email::Address::XS | p5-Email-Address-XS |
|
Email::MIME | p5-Email-MIME |
|
Encode | p5-Encode |
|
Error | p5-Error |
|
File::Copy::Recursive | p5-File-Copy-Recursive |
|
HTML::Parser | p5-HTML-Parser |
|
HTML::Tree | p5-HTML-Tree |
|
IO::Socket::IP | p5-IO-Socket-IP |
First shipped perl 5.19.8 |
IO::Socket::SSL | p5-IO-Socket-SSL |
|
JSON | p5-JSON |
|
Locale::Maketext | p5-Locale-Maketext |
|
Locale::Maketext::Lexicon | p5-Locale-Maketext-Lexicon |
Optional, needed for internationalization |
Locale::Msgfmt | p5-Locale-Msgfmt |
Optional, needed for internationalization |
LWP | p5-libwww |
|
LWP::Protocol::https | p5-LWP-Protocol-https |
|
URI | p5-URI |
|
version | p5-version |
Must be version 0.77 or newer, included with perl 5.10.1 and newer. |
After expanding the Foswiki archive, change the ownership of the files:pkg install
p5-Algorithm-Diff
p5-Archive-Tar
p5-Authen-SASL
p5-CGI
p5-CGI-Session
p5-Crypt-PasswdMD5
p5-Digest-SHA
p5-Email-Address-XS
p5-Email-MIME
p5-Encode
p5-Error
p5-File-Copy-Recursive
p5-HTML-Parser
p5-HTML-Tree
p5-IO-Socket-IP
p5-IO-Socket-SSL
p5-JSON
p5-Locale-Maketext
p5-Locale-Maketext-Lexicon
p5-Locale-Msgfmt
p5-libwww
p5-LWP-Protocol-https
p5-URI
p5-version
chown -R www:wwwadmin /var/www/path-to-foswiki
Install as needed.
Perl Module | Package to install | Notes |
---|---|---|
mod_perl2 | ap24-mod_perl2 |
Required if using Apache 2 and mod_perl |
Apache2::Request | libapreq2 |
Required if using Apache 2 and mod_perl |
BSD-Resource | p5-BSD-Resource |
Optional - used for FCGI process handler resource limits |
DBI | p5-DBI |
Optional - Used for the Foswiki Page cache |
DBD::mysql | p5-DBD-mysql |
Optional - Used for MySQL based Page Cache |
DBD::Pg | p5-DBD-Pg |
Optional - Used for PostgreSQL based Page Cache |
DBD::SQLite | p5-DBD-SQLite |
Optional - Used for SQLite based Page Cache |
FCGI | p5-FCGI |
Optional, needed for fastcgi / fcgi apache modules |
FCGI::ProcManager | p5-FCGI-ProcManager |
Optional, needed for fastcgi / fcgi process management on nginx |
Crypt::SMIME | p5-Crypt-SMIME |
Optional, used for S/MIME email signing |
Crypt::X509 | p5-Crypt-X509 |
Optional, used for S/MIME email signing |
Convert::PEM | p5-Convert-PEM |
Optional, used for S/MIME email signing |
cpanm
, aka App::cpanminus
. On most unix* systems, cpanminus
can bootstrap itself using curl or wget.
If run as root, the modules will be installed in the System perl. Otherwise they are installed into the users local environment.
Perl Module | Notes |
---|---|
Algorithm::Diff | |
Archive::Tar | *First shipped in perl 5.9.3 |
Authen::SASL | Optional, needed for authenticated SMTP |
CGI | |
CGI::Session | |
Crypt::PasswdMD5 | |
Digest::SHA | Included with perl |
Error | |
Email::Address::XS | |
Email::MIME | |
Encode | |
File::Copy::Recursive | |
HTML::Parser | |
HTML::Tree | |
IO::Socket::IP | |
IO::Socket::SSL | Optional, support encrypted email connection: STARTTLS or SSL |
JSON | |
Locale::Maketext | |
Locale::Maketext::Lexicon | Optional, needed for internationalization |
Locale::Msgfmt | Optional, needed for internationalization |
LWP | |
LWP::Protocol::https | |
URI | |
version | Must be version 0.77 or newer, included with perl 5.10.1 and newer. |
cpanm
curl -L http://cpanmin.us | perl - App::cpanminus (optional - install cpanminus if not available )
cpanm Algorithm::Diff Archive::Tar Authen::SASL CGI CGI::Session Crypt::PasswdMD5 Digest::SHA Error Email::Address::XS Email::MIME Encode File::Copy::Recursive HTML::Parser HTML::Tree IO::Socket::IP IO::Socket::SSL JSON Locale::Maketext Locale::Maketext::Lexicon Locale::Msgfmt LWP LWP::Protocol::https URI version
Install as needed.
Perl Module | Package to install | Notes |
---|---|---|
Apache2::Request | Required if using Apache 2 and mod_perl | |
DBI | Optional - Used for the Foswiki Page cache | |
DBD::mysql | Optional - Used for MySQL based Page Cache | |
DBD::Pg | Optional - Used for PostgreSQL based Page Cache | |
DBD::SQLite | Optional - Used for SQLite based Page Cache | |
FCGI | Optional, needed for fastcgi / fcgi apache modules | |
FCGI::ProcManager | Optional, needed for fastcgi / fcgi process management on nginx | |
Crypt::SMIME | Optional, used for S/MIME email signing | |
Crypt::X509 | Optional, used for S/MIME email signing | |
Convert::PEM | Optional, used for S/MIME email signing | |
Locale::Language | Optional, Locale::Language will be removed from the Perl core distribution in 5.28. |
cpanminus
"-l"
option to cpanm, and add the lib path to bin/LocalLib.cfg
. The dependencies will be installed under the specified location, in the lib/perl5
subdirectory.
Example: User "foswiki" logs in and installs the libraries locally under the foswikideps directory:
cpanm -l foswikideps Algorithm::Diff Archive::Tar ... (install libraries into =/home/foswiki/foswikideps=)
/path/to/foswiki/bin/LocalLib.txt
is then edited, and the commented line is modified:
# @localPerlLibPath = ( '/path/to/dir', '/path/to/another/dir', ); @localPerlLibPath = ( '/home/foswiki/foswikideps/lib/perl5', );Foswiki will now run using the libraries installed by cpanm.
CSS and Javascript are used in most skins. Some skins will require more recent releases of browsers. The default (Pattern) skin is tested on IE 6+, Safari, Chrome and Firefox.
You can easily select a balance of browser capability versus look and feel. Try the installed skins at System.SkinBrowser and more at Foswiki:Extensions.SkinPackage.pub
directory.)
lib
directory at the same level as the bin
directory. You can create this directory elsewhere and configure the bin/setlib.cfg
file. Foswiki dir: | What it is: | Where to copy: | Example: |
---|---|---|---|
foswiki | start-up pages | root Foswiki dir | /home/smith/public_html/foswiki/ |
foswiki/bin | CGI bin | CGI-enabled dir | /home/smith/public_html/foswiki/bin |
foswiki/lib | library files | same level as bin | /home/smith/public_html/foswiki/lib |
foswiki/locale | language files | dir secure from public access | /home/smith/public_html/foswiki/locale |
foswiki/pub | public files | htdoc enabled dir | /home/smith/public_html/foswiki/pub |
foswiki/data | topic data | dir secure from public access | /home/smith/public_html/foswiki/data |
foswiki/templates | web templates | dir secure from public access | /home/smith/public_html/foswiki/templates |
foswiki/tools | Foswiki utlilities | dir secure from public access | /home/smith/public_html/foswiki/tools |
foswiki/working | Temporary and internal files | dir secure from public access | /home/smith/public_html/foswiki/working |
configure
page) configure
page. However, if you are unable to get the configure
page to display (for example, if a dependency is missing), or for some reason you do not wish to use the configure
page, then you can configure Foswiki manually
Perform the following steps to manually configure Foswiki: lib/Foswiki.spec
to lib/LocalSite.cfg
$Foswiki::cfg{DefaultUrlHost} $Foswiki::cfg{ScriptUrlPath} $Foswiki::cfg{ScriptDir} $Foswiki::cfg{PubUrlPath} $Foswiki::cfg{PubDir} $Foswiki::cfg{DataDir} $Foswiki::cfg{ToolsDir} $Foswiki::cfg{TemplateDir} $Foswiki::cfg{LocalesDir} $Foswiki::cfg{WorkingDir} $Foswiki::cfg{OS}
$Foswiki::cfg{LoginManager} $Foswiki::cfg{WebMasterEmail} $Foswiki::cfg{SMTP}{MAILHOST} $Foswiki::cfg{SMTP}{SENDERHOST}
__END__
and everything following it.