Dave Rolsky > Silki > Silki::Manual::Admin

Download:
Silki-0.29.tar.gz

Annotate this POD

CPAN RT

New  1
Open  0
View/Report Bugs
Source  

NAME ^

Silki::Manual::Admin - Admin manual for Silki

VERSION ^

version 0.29

INSTALLATION ^

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:

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

Cache Dir

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".

CONFIGURATION ^

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.

[Silki] Section

This section contains some application wide settings.

[database] Section

This section contains settings for connecting to the database.

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.

[dirs] section

This section contains paths to some directories used by Silki

[antispam] section

This section contains configuration for Silki's optional antispam feature.

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.

GETTING STARTED ^

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:

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.

Wiki Membership

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.

USER MANAGEMENT ^

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.

DOMAINS ^

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.

Multiple Domains

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.

You should configure Apache to serve the css, images, and javascript files statically. In production, Silki prepends the css and javascript URIs with the Silki version number. This helps ensure that these files are reloaded when a new version of Silki is installed. Assuming you installed the share files in /usr/local/share/silki, this would look like:

  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>

AUTHOR ^

Dave Rolsky <autarch@urth.org>

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
syntax highlighting: