/ 
Silki-0.02
River stage one • 1 direct dependent • 1 total dependent
/ Silki::Manual::Admin

NAME

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

VERSION

version 0.02

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:

  • --db-name

    Defaults to "Silki".

  • --db-username

  • --db-password

  • --db-host

  • --db-port

    None of these four are necessary, if the user that runs ./Build install has permission create a Postgres database using the default connection settings.

  • --etc-dir

    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.

  • --share-dir

    By default, the share files are installed in the Perl module tree. If you something else, you can specify an alternate location.

  • --cache-dir

    At runtime, Silki needs a directory for generate cache files. This defaults to /var/cache/silki.

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.

  • max_upload_size

    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.

  • path_prefix

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

  • static

    When running in production mode, Silki expects that all static files (images, javascript, CSS, etc) will be served by a front-end web server. However, if you explicitly set this to a true value, Silki will be able to serve all static content.

  • secret

    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.

  • is_production

    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.

[database] Section

This section contains settings for connecting to the database.

  • name

    The name of the database containing the Silki schema. This defaults to "Silki". Don't change this unless you've already renamed your database.

  • username

  • password

    The username and password used when connecting to the Postgres server.

  • host

  • port

    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.

[dirs] section

This section contains paths to some directories used by Silki

  • share

    The directory which contains "share" files, such as mason components and images. By default, Silki uses File::ShareDir to find this.

  • cache

    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.

[antispam] section

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

  • server

    The antispam API server. This defaults to api.antispam.typepad.com.

  • key

    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.

GETTING STARTED

When you first install Silki, it will create a single admin user and a wiki for you. It assumes that the wiki will be run using the hostname of the system on which it is installed. Don't worry, you can change this.

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 usign 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:

  • Public

    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.

  • Private

    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.

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 from the psql 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 FastCGI

Since there are so many options, we'll cover just one in depth, running Silki undef FastCGI with Apache 2.

In order to support the X-Sendfile header, you will need the mod_xsendfile Apache module installed.

The examples below assume you are using mod_fcgid.

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 Silki fastcgi script:

<LocationMatch "^(?!/images|/[^/]+/(css|js)).+">
    XSendFile on
    XSendFileAllowAbove on

    SetHandler fcgid-script
    Options +ExecCGI

    FcgidWrapper /usr/local/bin/silki_fastcgi.pl virtual
</LocationMatch>

Note that we also turned on XSendFile and XSendFileAllowAbove. Attachments are written to the cache directory and served via the X-Sendfile header.

The whole thing, wrapped in a virtual host, looks like this:

<VirtualHost *:80>
    ServerName  silki.test

    AliasMatch ^/[^/]+/css(.+) /usr/local/share/silki/css$1
    AliasMatch ^/[^/]+/js(.+)  /usr/local/share/silki/js$1
    AliasMatch ^/images(.+)    /usr/local/share/silki/images$1

    <LocationMatch "^(?!/images|/[^/]+/(css|js)).+">
        XSendFile on
        XSendFileAllowAbove on

        SetHandler fcgid-script
        Options +ExecCGI

        FcgidWrapper /usr/local/bin/silki_fastcgi.pl virtual
    </LocationMatch>
</VirtualHost>

AUTHOR

Dave Rolsky <autarch@urth.org>

COPYRIGHT AND LICENSE

This software is Copyright (c) 2010 by Dave Rolsky.

This is free software, licensed under:

The GNU Affero General Public License, Version 3, November 2007