Rel4tion-Wiki/maint/admin/ikiwiki/Ikiwiki_Setup.mdwn

Install package 'ikiwiki' using your favorite package manager. On the command
line you can run this as root:

	# apt-get install ikiwiki

We are going to use a separate system user for the wiki, in a similar manner to
how a separate git user is usually created for git servers. The following
command will create the user:

	# adduser \
	    --system \
	    --shell /bin/bash \
	    --gecos 'ikiwiki instance user' \
	    --group \
	    --disabled-password \
	    --home /home/ikiwiki \
	    ikiwiki

Check `man adduser` for an explanation of this command.

Before we create our wiki, a word about privacy must be said. When you create
the wiki, each page automatically generated (e.g. the initial index page) gets a
timestamp specifying the "last edited" time. The timezone and locale certainly
affect those dates. If you use I2P or Tor, you probably don't want to expose
your timezone and locale. The timezone and locale can both be set in the wiki
setup file, which we will soon edit. I didn't check whether editing them before
the first wiki compilation ensures all pages get the values you set. If they
don't, maybe changing the locale and timezone environment variables before
setting up the wiki will help. Also, you can copy the 'auto.setup' file and
modify it before usage.

Now let's create the wiki. While being root, change user to 'ikiwiki':

	# su - ikiwiki

Now create a new wiki. Two automatic setup files come with the package:

- /etc/ikiwiki/auto.setup
- /etc/ikiwiki/auto-blog.setup

You can use those, or set it up by hand. The ikiwiki website explains how. For
our purpose, let's use the auto.setup file:

	$ ikiwiki --setup /etc/ikiwiki/auto.setup

It will ask you several questions. You can use any wiki name and any
user/password combination you wish (has nothing to do with Linux users), but
make sure you give 'git' as the RCS to be used. I will assume the wiki name is
"My Wiki" for the rest of this guide. That means the folders created for you in
`/home/ikiwiki` are:

- MyWiki
- MyWiki.git
- public_html/MyWiki

The first one if the "srcdir", which is a clone of the wiki used for building
the HTML pages and for updating the wiki after edits made via the web interface.
The second one if the bare "master" repository, and the third contains the
generated web pages.

Near the end of the long verbose message you probably got on the command line,
there should be a line regarding updating the system wiki-list. It is a list of
all installed ikiwiki instances, used for rebuilding them every time the ikiwiki
package is upgraded. On my system, and possibly on yours too, the list requires
root access, which means the attempt to update it will fail.

If it failed, you can update it manually by appending the line "ikiwiki" (i.e.
the name of the user you created, without quotes) to `/etc/ikiwiki/wikilist`:

	$ su
	# nano /etc/ikiwiki/wikilist
	# su - ikiwiki

There are many many options in the setup file created for your wiki. For now we
will touch just what we need to get the basic wiki working, and gradually make
more changes when we need to. ikiwiki's home folder should look like this:

	$ ls
	MyWiki  MyWiki.setup  public_html

Edit the setup file (in this case MyWiki.setup), e.g. using `nano` or `emacs` or
`vim` or any other preferred editor. Here are the things I suggest you change,
in order of appearance. Some are required, others are just my recommendations or
ideas. Below that there is a copy of my own setup.

+ __adminemail__: This will probably be `ikiwiki@<domain>`. Change it to a real
  email address you use, so people can really contact you.
+ __url__: This is probably required for correct links between wiki pages. Set
  it to the address people will use to reach your wiki.
+ __cgiurl__: This is probably required too. It's the address of the CGI file,
  allowing web editing among other things. Set it to be __url__ with
  `/ikiwiki.cgi` appended.
+ __disable_plugins__: I may not know much about OpenID, but I don't like it. It
  is a plugin enabled by default, which allows using web services on which you
  already have an account to verify your identity. Its decentralized nature is
  good, but in practice AFAIK only big centralized services provide an OpenID,
  so you end up trusting G00gle or Fakeb00k to tell you who's a legitimate user
  and who's not. Until I investigate further, I prefer to avoid OpenID. Besides,
  if everyone used it - who would be providing it? *Someone* has to be the
  provider and actually store the passwords. I don't hurry to delegate tasks to
  other websites. Anyway it's your choice: If you wish to disable this plugin,
  add "openid" (without quotes) between the square brackets.
+ __timeformat__: Depending on your personal preference and your privacy
  concerns, you may want to change this. See `man strftime` for possible values.
+ __locale__: Depending on your personal preference and your privacy concerns,
  you may want to change this.
+ __timezone__: Depending on your personal preference and your privacy concerns,
  you may want to change this. For privacy, setting this to UTC is probably a
  good idea.

Here is what my setup looked like at this point (just the relevant part of it).
The arrows point at parts discussed above.

	# IkiWiki::Setup::Yaml - YAML formatted setup file
	#
	# Setup file for ikiwiki.
	# 
	# Passing this to ikiwiki --setup will make ikiwiki generate
	# wrappers and build the wiki.
	# 
	# Remember to re-run ikiwiki --setup any time you edit this file.
	#
	# name of the wiki
	wikiname: Partager
	# contact email for wiki
	__adminemail: fr33domlover@riseup.net__                         # <--------
	# users who are wiki admins
	adminuser:
	- fr33domlover
	# users who are banned from the wiki
	banned_users: []
	# where the source of the wiki is located
	srcdir: /home/ikiwiki/Partager
	# where to build the wiki
	destdir: /home/ikiwiki/public_html/Partager
	# base url to the wiki
	__url: http://partager.i2p__                                    # <--------
	# url to the ikiwiki.cgi
	__cgiurl: http://partager.i2p/ikiwiki.cgi__                     # <--------
	# filename of cgi wrapper to generate
	cgi_wrapper: /home/ikiwiki/public_html/Partager/ikiwiki.cgi
	# mode for cgi_wrapper (can safely be made suid)
	cgi_wrappermode: 06755
	# rcs backend to use
	rcs: git
	# plugins to add to the default configuration
	add_plugins:
	- goodstuff
	- websetup
	# plugins to disable
	__disable_plugins: [openid]__                                   # <--------
	# additional directory to search for template files
	templatedir: /usr/share/ikiwiki/templates
	# base wiki source location
	underlaydir: /usr/share/ikiwiki/basewiki
	# display verbose messages?
	#verbose: 1
	# log to syslog?
	syslog: 1
	# create output files named page/index.html?
	usedirs: 1
	# use '!'-prefixed preprocessor directives?
	prefix_directives: 1
	# use page/index.mdwn source files
	indexpages: 0
	# enable Discussion pages?
	discussion: 1
	# name of Discussion pages
	discussionpage: Discussion
	# generate HTML5?
	html5: 0
	# only send cookies over SSL connections?
	sslcookie: 0
	# extension to use for new pages
	default_pageext: mdwn
	# extension to use for html files
	htmlext: html
	# strftime format string to display date
	__timeformat: '%c'__                                            # <--------
	# UTF-8 locale to use
	__locale: en_US.UTF-8__                                         # <--------
	# put user pages below specified page
	userdir: ''
	# how many backlinks to show before hiding excess (0 to show all)
	numbacklinks: 10
	# attempt to hardlink source files? (optimisation for large files)
	hardlink: 0
	# force ikiwiki to use a particular umask (keywords public, group or
	# private, or a number)
	#umask: public
	# group for wrappers to run in
	#wrappergroup: ikiwiki
	# extra library and plugin directory
	libdir: /home/ikiwiki/.ikiwiki
	# environment variables
	ENV: {}
	# time zone name
	__timezone: UTC__                                               # <--------
	# regexp of normally excluded files to include
	#include: ^\\.htaccess$
	# regexp of files that should be skipped
	#exclude: ^(*\\.private|Makefile)$
	# specifies the characters that are allowed in source filenames
	wiki_file_chars: -\[:alnum:\]+/.:_
	# allow symlinks in the path leading to the srcdir (potentially insecure)
	allow_symlinks_before_srcdir: 0

Now run ikiwiki to update your wiki after the setup change:

	$ ikiwiki --setup MyWiki.setup

Last thing to get the basic wiki running: Configure the web server. You need to
enable lighttpd's CGI module (unless you already did, e.g. if you already use
Gitweb), and update the configuration. Commands:

	$ su
	# lighty-enable-mod cgi
	# nano /etc/lighttpd/lighttpd.conf
	# service lighttpd reload

Here's an example lighttpd configuration:

	## core modules used by the server
	## mod_access: deny access to files with specific extensions (e.g. backup files)
	## mod_alias: specify special document root for a url subset
	## mod_compress: compress static content to reduce network load
	## mod_redirect: redirect a set of URLs externally
	server.modules = (
	        "mod_access",
	        "mod_alias",
	        "mod_compress",
	        "mod_redirect",
	#        "mod_rewrite",
	)
	
	## basic setup
	#server.document-root        = "/var/www/web"
	server.document-root        = "/home/ikiwiki/public_html/MyWiki"
	server.upload-dirs          = ( "/var/cache/lighttpd/uploads" )
	server.errorlog             = "/var/log/lighttpd/error.log"
	server.pid-file             = "/var/run/lighttpd.pid"
	server.username             = "www-data"
	server.groupname            = "www-data"
	server.port                 = 7658
	server.tag                  = "Be the change"
	
	## CGI
	## The lighttpd CGI conf looks for CGI files in /cgi-bin, but ikiwiki's
	## file is located somewhere else. The following config allows the ikiwiki
	## CGI to work (still requires the CGI module to be enabled)
	$HTTP["url"] =~ "^/ikiwiki.cgi" {
	        cgi.assign = ( "ikiwiki.cgi" => "" )
	}
	
	## filenames to be used as directory index
	index-file.names            = ( "index.cgi", "index.html" )
	
	## deny access to some files by pattern
	url.access-deny             = ( "~", ".inc" )
	
	## avoid serving dynamic content generators as static content
	static-file.exclude-extensions = ( ".php", ".pl", ".fcgi", ".cgi" )
	
	## directory to use for caching compressed content
	compress.cache-dir          = "/var/cache/lighttpd/compress/"
	
	## which file types to compress
	compress.filetype           = ( "application/javascript", "text/css", "text/html", "text/plain" )
	
	## default listening port for IPv6 falls back to the IPv4 port
	include_shell "/usr/share/lighttpd/use-ipv6.pl " + server.port
	include_shell "/usr/share/lighttpd/create-mime.assign.pl"
	include_shell "/usr/share/lighttpd/include-conf-enabled.pl"

The important parts are the `document-root` and the part setting `cgi.assign`.

The wiki should work now. Browse to the IP address / domain name of your
website. You should see the default index page. Try editing it to make sure the
CGI works. Also look at the "last edited" date, before and after the edit, and
make sure it matches your preferred privacy settings.