testing
[ikiwiki.git] / doc / setup.mdwn
1 So you want to set up your own wiki using ikiwiki? This tutorial will walk
2 you through setting up a wiki that is stored in [[Subversion]], [[Git]],
3 [[TLA]] or [[Mercurial]], and that has optional support for commits from the web.
4
5 1. [[Install]] ikiwiki. See [[download]] for where to get it.
6
7 2. Decide where your wiki's files will go.
8
9    Pick three directories for respectively the repository (contains
10    the "master copy" and history); working copy (checked-out
11    files from the repository); and web pages (served by the web server).
12
13    For the purposes of this tutorial, we'll set shell variables
14    for these locations, and use those variables in the commands that follow.
15
16                 REPOSITORY=~/wikirepo
17                 SRCDIR=~/wikiwc
18                 DESTDIR=~/public_html/wiki/
19
20 3. Create the master rcs repository for your wiki.
21
22                 # Subversion
23                 svnadmin create $REPOSITORY
24                 svn mkdir file://$REPOSITORY/trunk -m create
25                  
26                 # Git
27                 mkdir $REPOSITORY
28                 cd $REPOSITORY
29                 git init-db
30                 # Git requires something be in the repo to start with.
31                 cp /usr/share/ikiwiki/basewiki/index.mdwn .
32                 git add .
33                 git commit -m create -a
34                 # No need to keep files in the master repository; so at this
35                 # stage, you may want to remove all files (except .git) to
36                 # save disk space.
37
38                 # TLA
39                 mkdir $REPOSITORY
40                 tla make-archive me@localhost--wiki $REPOSITORY
41                 tla my-id "<me@localhost>"
42
43                 # Mercurial
44                 hg init $REPOSITORY
45
46 4. Check out the repository to make the working copy that ikiwiki will use
47    as its source directory.
48
49                 # Subversion
50                 svn co file://$REPOSITORY/trunk ~/wikiwc
51                  
52                 # Git
53                 # Create a local clone to save disk space and also to
54                 # optimize performance. See git-clone(1).
55                 git clone -l -s $REPOSITORY $SRCDIR
56
57                 # TLA
58                 mkdir $SRCDIR
59                 cd $SRCDIR
60                 tla archive-setup me@localhost--wiki/wiki--0
61                 tla init-tree me@localhost--wiki/wiki--0
62                 # Edit {arch}/=tagging-method and change the precious
63                 # line to add the .ikiwiki directory to the regexp.
64                 tla import
65
66                 # Mercurial
67                 # Mercurial uses a single repo approach, so no need to
68                 # clone anything. Because the following examples
69                 # refer to $SRCDIR, we symlink it:
70                 ln -s $REPOSITORY $SRCDIR
71
72 5. Build your wiki for the first time.
73
74                 ikiwiki --verbose $SRCDIR $DESTDIR --url=http://host/~you/wiki/
75
76    Replace the url with the real url to your wiki. You should now
77    be able to visit the url and see your wiki.
78
79 6. Customise your wiki. The files in `/usr/share/ikiwiki/basewiki/` are
80    used if you don't have a custom version, so let's start by making a
81    custom version of the wiki's index page:
82
83                 cd $SRCDIR
84                 cp /usr/share/ikiwiki/basewiki/index.mdwn .
85                 $EDITOR index.mdwn
86                  
87                 # Subversion
88                 svn add index.mdwn
89                 svn commit -m customised index.mdwn
90                  
91                 # Git
92                 git add index.mdwn
93                 git commit -m customised index.mdwn
94                 git push origin
95
96                 # TLA
97                 tla add index.mdwn
98                 tla commit
99
100                 # Mercurial
101                 hg add index.mdwn
102                 hg commit -m customised index.mdwn
103
104    You can also add any files you like from scratch of course. Use the same
105    command as in step 5 to rebuild the wiki.
106
107 7. Repeat steps 5 and 6 as desired, editing or adding pages and rebuilding
108    the wiki. You can play around with other ikiwiki parameters such as
109    `--wikiname` and `--rebuild` too. Get comfortable with its command line
110    (see [[usage]]).
111
112 8. By now you should be getting tired of typing in all the command line
113    options each time you change something in your wiki's setup. And it's
114    also getting old to have to manualy rebuild the wiki each time you
115    change a file. Time to introduce setup files. 
116    
117    A sample setup file is [[ikiwiki.setup]]. Download it (or copy it from
118    `doc/ikiwiki.setup` in the ikiwiki sources), and edit it. 
119    
120    Most of the options, like `wikiname` in the setup file are the same as
121    ikiwiki's command line options (documented in [[usage]]. `srcdir` and
122    `destdir` are the two directories you specify when running ikiwiki by
123    hand. `svnrepo` is the path to your subversion repository.  Make sure
124    that all of these are pointing to the right directories, and read
125    through and configure the rest of the file to your liking.
126
127    If you want to use something other than subversion, comment out the
128    subversion configuration, and uncomment and edit the configuration for
129    your chosen RCS. Note that the default file has a block to configure a
130    [[post-commit]] wrapper to update the wiki. You need to uncomment the
131    related block for whatever RCS you use and comment out the other rcs
132    blocks.
133
134    When you're satisfied, run `ikiwiki --setup ikiwiki.setup`, and it
135    will set everything up and update your wiki.
136
137 9. Turn on additional features.
138
139    Now you have a basic wiki with a configuration file. Time to experiment
140    with ikiwiki's many features. 
141    
142    Let's first enable a key wiki feature and set up [[CGI]] to allow
143    editing the wiki from the web. Just edit ikiwiki.setup, uncomment the
144    block for the cgi wrapper, make sure the filename for the cgi wrapper
145    is ok, run `ikiwiki --setup ikiwiki.setup`, and you're done!
146
147    There are lots of other configuration options in ikiwiki.setup that you
148    can uncomment, configure, and enable by re-running
149    `ikiwiki --setup ikiwiki.setup`. Be sure to browse through all the
150    [[plugins]]..
151
152 10. Enjoy your new wiki! Add yourself to [[IkiWikiUsers]].