# PODNAME: Yukki::Manual::Installation
# ABSTRACT: installaction instructions


__END__
=pod

=head1 NAME

Yukki::Manual::Installation - installaction instructions

=head1 VERSION

version 0.110850

=head1 SYNOPSIS

  # Install the module
  perl -MCPAN -e 'install Yukki'
 
  # OR better, install cpanm and run...
  cpanm Yukki

  # Setup your wiki's installation folder
  yukki-setup mysite
  cd mysite

  # Setup the repositories
  yukki-git-init main
  yukki-git-init yukki git://github.com/zostay/yukki-help.git

  # Add a user
  yukki-add-user

  # Start the server
  yukki.psgi

=head1 DESCRIPTION

The L</SYNOPSIS> pretty well sums up the highlights of installation. The rest of this document discusses what each piece does and how to customize it further.

=head1 INSTALLATION

The code can be installed like any other CPAN module. By using L<App::cpanminus> or L<CPAN>, you will get all the dependencies downloaded and installed automatically for you.

=head1 SITE SETUP

To setup your site, you run the F<yukki-setup> script:

  yukki-setup mysite

This will create a directory named F<mysite> in the current folder and will copy into a skeleton installation that you may customize to suit the needs of your wiki site.

In it you will find these files and directories:

=over

=item *

F<etc/yukki.conf>. This is the configuraiton file for your application. You will want to read this to make sure it is correct before continuing. The default install includes two repositories. The one named "main" is intended to be a repository for you to use to suite your needs. The one named "yukki" contains a repository of online help for the wiki software itself.

=item *

F<repositories>. This directory might not exist until L</REPOSITORY INITIALIZATION> is finished, but it will contain local copies o fthe git repositories that contain the wiki's files.

=item *

F<root/script>. This contains all the JavaScript files served by your site. You may add to these or customize to suit your needs.

=item *

F<root/style>. This contains all the CSS stylseheets served by your site. You may add to these or customize to suit your needs.

=item *

F<root/template>. This contains all the templates used to render the pages for your site. You may customize these to suit your needs.

=item *

F<var/db/users>. This is the directory that will contain your user database. At this point, users are stored as a colleciton of L<YAML> formatted files.

=back

=head1 CONFIGURATION FILE

Most of these commands (all except F<yukki-setup>) look for a file named F<etc/yukki.conf> in the current working directory. If this file is not found, the script checks for an environment variable named C<YUKKI_CONFIG>, which should point to a L<YAML> formatted configuration for your wiki site.

If no file is found, the script will stop and complain of an error.

The configuraiton file contains the following directives:

=over

=item root

This is the wiki site directory. This should be the same folder that was given the F<yukki-setup> command. It works best if you make this an absolute path.

=item template_path

THis is the folder where Yukki will find templates under the C<root>. The default is F<root/template>.

=item repository_path

This is the folder where Yukki will find the git repositories installed under C<root>. The default is F<root/repositories>.

=item staitc_path

THis is the folder where Yukki will find the static files to serve for your application.

=item user_path

This is the folder where the list of user files can be found.

=item anonymous

This is a section configuring the anonymous user information

=over

=item author_name

This is the name to use when an anonymous user makes a change to a wiki repository.

=item author_email

This is the email address to use when an anonymous user makes a change to a wiki repository.

=back

=item repositories

This is a section under which each repository is configured. The keys under here are the name found in the URL. It is also the name to use when running the F<yukki-git-init> and other repository-related commands.

Each repository configuraiton should provide the following configruation keys.

=over

=item repository

This is required. This is the name of the git repository folder found under C<repository_path>.

=item site_branch

This is teh name of the branch that will contain the wiki's files. The default is C<refs/heads/master>. You could actually use the same git repository for multiple Yukki repositories by using different branches. If you want to do it that way for some reason. Unless you know what you're doing, you probably don't want to do that.

=item name

This is a human readable title for the repository.

=item default_page

This is the name of the main repository index. 

=item anonymous_access_level

This should be set to one of the following: read, write, or none. This settings decides how much access an anonymous user has when visiting your wiki.

=item read_groups

This may be set to the word "ANY" or the word "NONE" or to an array of group names.

If set to ANY, any logged user may read this repository. If set to NONE, read access is not granted to any logged user (though if C<anonymous_access_level> or C<write_groups> grant a user access, the user will be able to read the repository).

If an array of one or more group names are given, the users with any of those groups will be able to read the repository.

=item write_groups

THe possible values that may be set are identicl to C<read_groups>. This setting determines who has permission to edit pages and upload files to the repository.

=back

=back

=head1 REPOSITORY INITIALIZATION

Once the site directory is setup, you will need to initialize each of the git repositories that will contain the files stored by the wiki.

This is most easily performed by running:

  yukki-git-init foobar

for each of the repositories. This will create a git repository that contains a single commit containing a master index file. The name of this file and the branch that it belongs to is named in the L<CONFIGURATION FILE>.

In addition to running this command, you may choose to run:

  yukki-git-init foobar git://path/to/romote

Instead of initailizing an empty reposotiry, it will clone the named remote repository into a local mirror. This is useful if you want to sync a repository between different sites. (As of this writing, Yukki provides no help for this, but git already provides all the tools you need to do it.)

This latter command is similar to running:

  git clone --mirror git://path/to/remote repositories/foobar.git

=head1 CREATE USERS

Finally, to use Yukki, you will need one or more users with access to get into your wiki. The simple way to do this is to run:

  yukki-add-user

The script will ask you for information to create each user. You can then lookup the user files and edit them if you need to make later modifications.

=head1 AUTHOR

Andrew Sterling Hanenkamp <hanenkamp@cpan.org>

=head1 COPYRIGHT AND LICENSE

This software is copyright (c) 2011 by Qubling Software LLC.

This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.

=cut

