52ef204fceb48077137c5c70261071fd8b4871a6
[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 \
75                         --url=http://host/~you/wiki/
76
77    Replace the url with the real url to your wiki. You should now
78    be able to visit the url and see your wiki.
79
80 6. Customise your wiki. The files in `/usr/share/ikiwiki/basewiki/` are
81    used if you don't have a custom version, so let's start by making a
82    custom version of the wiki's index page:
83
84                 cd $SRCDIR
85                 cp /usr/share/ikiwiki/basewiki/index.mdwn .
86                 $EDITOR index.mdwn
87                  
88                 # Subversion
89                 svn add index.mdwn
90                 svn commit -m customised index.mdwn
91                  
92                 # Git
93                 git add index.mdwn
94                 git commit -m customised index.mdwn
95                 git push origin
96
97                 # TLA
98                 tla add index.mdwn
99                 tla commit
100
101                 # Mercurial
102                 hg add index.mdwn
103                 hg commit -m customised index.mdwn
104
105    You can also add any files you like from scratch of course. Use the same
106    command as in step 5 to rebuild the wiki.
107
108 7. Repeat steps 5 and 6 as desired, editing or adding pages and rebuilding
109    the wiki. You can play around with other ikiwiki parameters such as
110    `--wikiname` and `--rebuild` too. Get comfortable with its command line
111    (see [[usage]]).
112
113 8. By now you should be getting tired of typing in all the command line
114    options each time you change something in your wiki's setup. And it's
115    also getting old to have to manualy rebuild the wiki each time you
116    change a file. Time to introduce setup files. 
117    
118    A sample setup file is [[ikiwiki.setup]]. Download it (or copy it from
119    `doc/ikiwiki.setup` in the ikiwiki sources), and edit it. 
120    
121    Most of the options, like `wikiname` in the setup file are the same as
122    ikiwiki's command line options (documented in [[usage]]. `srcdir` and
123    `destdir` are the two directories you specify when running ikiwiki by
124    hand. `svnrepo` is the path to your subversion repository.  Make sure
125    that all of these are pointing to the right directories, and read
126    through and configure the rest of the file to your liking.
127
128    If you want to use something other than subversion, comment out the
129    subversion configuration, and uncomment and edit the configuration for
130    your chosen RCS. Note that the default file has a block to configure a
131    [[post-commit]] wrapper to update the wiki. You need to uncomment the
132    related block for whatever RCS you use and comment out the other rcs
133    blocks.
134
135    When you're satisfied, run `ikiwiki --setup ikiwiki.setup`, and it
136    will set everything up and update your wiki.
137
138 9. Turn on additional features.
139
140    Now you have a basic wiki with a configuration file. Time to experiment
141    with ikiwiki's many features. 
142    
143    Let's first enable a key wiki feature and set up [[CGI]] to allow
144    editing the wiki from the web. Just edit ikiwiki.setup, uncomment the
145    block for the cgi wrapper, make sure the filename for the cgi wrapper
146    is ok, run `ikiwiki --setup ikiwiki.setup`, and you're done!
147
148    There are lots of other configuration options in ikiwiki.setup that you
149    can uncomment, configure, and enable by re-running
150    `ikiwiki --setup ikiwiki.setup`. Be sure to browse through all the
151    [[plugins]]..
152
153 10. Enjoy your new wiki! Add yourself to [[IkiWikiUsers]].