package Silki::Manual::Admin;

# ABSTRACT: Admin manual for Silki


__END__
=pod

=head1 NAME

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

=head1 VERSION

version 0.09

=head1 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 F<Build.PL> script takes several
additional arguments:

=over 4

=item * --db-name

Defaults to "Silki".

=item * --db-username

=item * --db-password

=item * --db-host

=item * --db-port

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

=item * --etc-dir

When you first install Silki, it will create a new config file for you in the
specified directory. This defaults to F</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.

=item * --share-dir

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

=item * --cache-dir

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

=back

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

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

=head1 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 F<Build.PL>, and that will work for most
users.

The configuration file has the following settings.

=head2 [Silki] Section

This section contains some application wide settings.

=over 4

=item * 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.

=item * 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".

=item * 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.

=item * 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.

=item * 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.

=back

=head2 [database] Section

This section contains settings for connecting to the database.

=over 4

=item * 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.

=item * username

=item * password

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

=item * host

=item * port

The host and port for the Postgres server.

=back

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.

=head2 [dirs] section

This section contains paths to some directories used by Silki

=over 4

=item * share

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

=item * 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 F</var/cache/silki>.

Obviously, Silki will need to have read and write access to this directory at
runtime.

=back

=head2 [antispam] section

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

=over 4

=item * server

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

=item * key

The antispam API server key. If this is not set, Silki will not be able to
check links for spamminess.

=back

=head1 FINDING THE CONFIG FILE

By default, Silki looks for its config file at F</etc/silki/silki.conf>.

If you're running Silki as a user with a home directory (and not as root), it
also looks in F<~/.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
C<SILKI_CONFIG> environment variable.

=head1 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@E<lt>domainE<gt>". 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".

=head1 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:

=over 4

=item * Public

Anyone can read I<and> edit the wiki, without logging in. Only logged-in wiki
members can upload attachments.

=item * 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.

=item * Public can read, members can edit

Anyone can read the wiki, but only logged-in wiki members can edit it.

=item * Private

You must be a logged-in wiki member to edit the wiki.

=back

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.

=head2 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.

=head2 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.

=head1 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.

=head1 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 C<psql> tool. In the future,
the default domain will be made configurable during the installation process.

=head2 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.

=head1 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.

=head2 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
L<mod_xsendfile|http://tn123.ath.cx/mod_xsendfile/> Apache module installed.

The examples below assume you are using
L<mod_fcgid|http://httpd.apache.org/mod_fcgid/mod/mod_fcgid.html>.

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
F</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 C<XSendFile> and
C<XSendFileAllowAbove>. Attachments are written to the cache directory and
served via the C<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>

=head1 AUTHOR

  Dave Rolsky <autarch@urth.org>

=head1 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

=cut

