- FINDING THE CONFIG FILE
- GETTING STARTED
- WIKI PERMISSIONS AND USER ROLES
- USER MANAGEMENT
- WEB SERVER CONFIGURATION
- COPYRIGHT AND LICENSE
Silki::Manual::Admin - Admin manual for Silki
Silki requires a Postgres database in order to function, and it also has a config file. This means that installation is a little different from a standard Perl distribution.
The basic steps are the same, but the Build.PL script takes several additional arguments:
Defaults to "Silki".
None of these are necessary, if the user that runs
./Build installhas permission create a Postgres database using the default connection settings.
When you first install Silki, it will create a new config file for you in the specified directory. This defaults to /etc/silki, but you can override it.
If you have already installed Silki, you can specify this and Silki will use this config file to figure out where to install share files, how to connect to the database, etc.
By default, the share files are installed in the Perl module tree. If you prefer a different location, you can specify an alternate location.
At runtime, Silki needs a directory for generate cache files. This defaults to /var/cache/silki.
The default hostname for the web application. Set this to the (first) hostname through which you will access Silki. Silki can be installed once for multiple hostnames, but to do this, you need to access the web UI. To access the web UI, Silki needs to know what hostname it is listening on.
By default, Silki will simply use the system hostname as returned by Sys::Hostname.
So the installation process looks like this:
perl Build.PL [--etc-dir = /usr/local/etc/silki --db-username foo --db-password bar ...] ./Build test [sudo ] ./Build install
Currently, the installer does not make the cache directory, or ensure that it has the right permissions. The cache directory must be writeable by the user that Silki will run as, which is likely to be something like "www-data".
Silki uses an INI-style configuration file. You may also need to configure a web server to serve the Silki application. While Catalyst does make it possible to run the application in standalone mode, this is not recommended for production use.
When you first install Silki, it will generate a configuration file based on the parameters you pass to Build.PL, and that will work for most users.
The configuration file has the following settings.
This section contains some application wide settings.
This determines the maximum size of an attachment in the wiki. This defaults to approximately 10MB, which will work for most cases. If you plan to store huge files (video, disk images), you will need to increase this.
Silki stores files in the database, so you may not want to use it to store huge files.
This allows you to add an arbitrary prefix to all URIs that Silki generates. This is useful if you want to install Silki under some specific path on your server, like "http://example.com/wikis".
This is used as salt when generating digests for things like user authentication cookie MACs. It is also used for generating some URIs. If you change it, existing cookies and URIs will become invalid.
There's no good reason to change this unless you believe that server security has been compromised.
This will be set to true when the configuration file is first generated. Don't make this false unless you know what you're doing.
The Apache mod_rewrite module unescapes the URI before passing it to the backend. This ends up breaking paths to page titles with any escaped characters in them. Set this to a true value and Silki will account for this problem.
This section contains settings for connecting to the database.
The name of the database containing the Silki schema. This defaults to "Silki". Don't change this unless you've already renamed your database.
The username and password used when connecting to the Postgres server.
The host and port for the Postgres server.
By default, Silki attempts to connect to Postgres running on localhost with the default port. It assumes that the user it is running as can connect without a password.
This section contains paths to some directories used by Silki
The directory which contains "share" files, such as mason components and images. By default, Silki uses File::ShareDir to find this.
Silki needs to write some cache files to disk. Files in this directory can be removed manually if you like, and they will be regenerated as needed. This defaults to /var/cache/silki.
Obviously, Silki will need to have read and write access to this directory at runtime.
This section contains configuration for Silki's optional antispam feature.
The antispam API server. This defaults to api.antispam.typepad.com.
The antispam API server key. If this is not set, Silki will not be able to check links for spamminess.
FINDING THE CONFIG FILE
By default, Silki looks for its config file at /etc/silki/silki.conf.
If you're running Silki as a user with a home directory (and not as root), it also looks in ~/.silki/etc/silki.conf, which is handy for development and testing.
If you want to put the config file somewhere else, you can set the
SILKI_CONFIG environment variable.
When you first install Silki, it will create a single admin user and a wiki for you.
The user account is "admin@<domain>". The default password is "changeme".
Once you log in, you can change the account's email, name, and password. You can also switch to using an OpenID login if you prefer.
Wikis cannot be renamed, but you can delete the wiki Silki created for you, called "My Wiki".
WIKI PERMISSIONS AND USER ROLES
Silki supports several levels of privacy for a wiki. It does this using a wiki-wide permission system. Each wiki has a privacy setting, which determines what different types of users can do.
The available settings are:
Anyone can read and edit the wiki, without logging in. Only logged-in wiki members can upload attachments.
Public, log-in to edit
Anyone can read the wiki, but users must create an account and log in to edit. This ensures that all edits are associated with a given user, as opposed to the generic "Guest User". Only logged-in wiki members can upload attachments.
Public can read, members can edit
Anyone can read the wiki, but only logged-in wiki members can edit it.
You must be a logged-in wiki member to edit the wiki.
Regardless of the privacy setting, only a wiki admin can delete pages and attachments or invite new members to the wiki.
Of course, a site admin has access to all wikis.
A wiki admin can invite new users to the wiki. If the user already has an account in the Silki installation, they are immediately added.
If they don't have an account, they receive an invitation email and are asked to confirm their account's information (name, email, etc.). Once they do this, they are full members of that wiki.
Guests Versus Logged-in Users
When someone visits the wiki without logging in, they are using a generic "Guest User" account. This account is created by the system at installation time. No one can log in as this user, and there is only one guest account for the entire system.
If the system has any public wikis, then guest users will see a "register" link. This allows them to create a new account without an explicit invitation. They are still not members of any wikis, but once they log in they will no longer be considered a guest.
As mentioned previously, there are several ways to create new user accounts. It is not really safe to delete a user, so a site admin can explicitly disable an existing user. When a user is disabled, they cannot log in, but their activity history is still preserved, and their profile is still visible to other users.
The site admin cannot disable any accounts which were created by the system (the "Guest User" and "System User" accounts), nor can the site admin disable their own account.
A site can admin also grant site admin access to existing users. Since a site admin can access any wiki, they can also grant wiki admin status to other users.
By default, Silki assumes that it is being accessed under the system's hostname. Of course, this may not be true.
This is important because Silki generates URIs with the hostname when it issues a redirect, and when it sends invitation and registration confirmation emails.
A site admin can edit the exisiting domain.
Domains can have separate web and email hostnames. The email hostname is not currently used, but will be used in the future for emailing content into the wiki.
Silki will throw an error if you attempt to access it from a domain it does not know about. If the default domain chosen when the system was installed is not being used, you can edit the domain manually using the
psql command line tool. In the future, the default domain will be made configurable during the installation process.
If you set up Silki for some sort of wiki hosting system, you may want to operate with multiple domains. When you create a wiki, you will assign it to a specific domain.
Of course, you will also need to configure the web server side to work with multiple domains.
WEB SERVER CONFIGURATION
With Catalyst, you have a number of options when deciding how to integrate Silki with your web server, including FastCGI, mod_perl, PSGI, and more.
While you can, in theory, run Silki as a vanilla CGI, this is not recommended, as it will be quite slow.
Silki uses the X-Sendfile header when users download attachments. This means you will need to configure your web server to support this.
Apache 2 and Starman
Since there are so many options, we'll cover just one in depth, running Silki with Apache 2 serving static content, and Starman as the app server.
In order to support the X-Sendfile header, you will need the mod_xsendfile Apache module installed.
AliasMatch ^/[^/]+/css(.+) /usr/local/share/silki/css$1 AliasMatch ^/[^/]+/js(.+) /usr/local/share/silki/js$1 AliasMatch ^/images(.+) /usr/local/share/silki/images$1
All other URIs should simply be passed to the Starman server. For testing, you can start the server from the command line:
sudo -u www-data \ starman --listen 127.0.0.1:13000 \ --workers 5 \ --preload-app \ /usr/local/bin/silki.psgi
You can adjust the value of
--listen, but it is recommended that you only listen on the localhost interface. There's no reason to expose the app server to the world at large. You can also adjust
--workers as needed.
You also need to enable support for the X-Sendfile header in your Apache config file:
XSendFile on XSendFileAllowAbove on
Finally, you can use mod_rewrite to pass all non-static URIs to the Starman server:
RewriteEngine On RewriteRule !^/images - [C] RewriteRule !^/[^/]+/css - [C] RewriteRule !^/[^/]+/js - [C] RewriteRule (.*) http://localhost:13000$1 [P,L]
The whole thing, wrapped in a virtual host, looks like this:
<VirtualHost *:80> ServerName silki.test DocumentRoot /usr/local/share/silki ErrorLog /var/log/apache2/error.log CustomLog /var/log/apache2/access.log combined AliasMatch ^/[^/]+/css(.+) /usr/local/share/silki/css$1 AliasMatch ^/[^/]+/js(.+) /usr/local/share/silki/js$1 AliasMatch ^/images(.+) /usr/local/share/silki/images$1 XSendFile on XSendFileAllowAbove on RewriteEngine On RewriteRule !^/images - [C] RewriteRule !^/[^/]+/css - [C] RewriteRule !^/[^/]+/js - [C] RewriteRule (.*) http://localhost:13000$1 [P,L] </VirtualHost>
Dave Rolsky <email@example.com>
COPYRIGHT AND LICENSE
This software is Copyright (c) 2011 by Dave Rolsky.
This is free software, licensed under:
The GNU Affero General Public License, Version 3, November 2007