]> git.vanrenterghem.biz Git - git.ikiwiki.info.git/blobdiff - doc/setup.mdwn
anonymous git push broken again
[git.ikiwiki.info.git] / doc / setup.mdwn
index 7f2661ec06e919df822ab85f295f096eacd06765..9fc37c0b11bcd7d7e084af6b61e81f9ff1f79a46 100644 (file)
@@ -2,11 +2,15 @@ This tutorial will walk you through setting up a wiki with ikiwiki.
 
 [[!toc ]]
 
-## [[Download]] and [[install]] ikiwiki
+## Install ikiwiki
 
-If you're using Debian or Ubuntu, ikiwiki is an `apt-get install ikiwiki` away.
+If you're using Debian or Ubuntu, ikiwiki is an <code><a href="http://www.debian.org/doc/manuals/debian-reference/ch02.en.html#_basic_package_management_operations">apt-get</a> install ikiwiki</code> away.
 If you're not, see the [[download]] and [[install]] pages.
 
+You may also want to try out a sandboxed [[Docker image|https://github.com/elecnix/ikiwiki-docker]]
+with ikiwiki pre-installed or this other [[one|https://github.com/dgsb/docker-ikiwiki]] which will use a volume to access a local git repository
+for the wiki content.
+
 ## Create your wiki
 
 All it takes to create a fully functional wiki using ikiwiki is running
@@ -16,11 +20,13 @@ For more control, advanced users may prefer to set up a wiki
 [[by_hand|byhand]].
 """]]
 
-       % ikiwiki -setup /etc/ikiwiki/auto.setup
+       % ikiwiki --setup /etc/ikiwiki/auto.setup
 
 Or, set up a blog with ikiwiki, run this command instead.
 
-       % ikiwiki -setup /etc/ikiwiki/auto-blog.setup
+       % ikiwiki --setup /etc/ikiwiki/auto-blog.setup
+
+`librpc-xml-perl` and `python-docutils` dependencies are needed.
 
 Either way, it will ask you a couple of questions.
 
@@ -37,7 +43,7 @@ Then, wait for it to tell you an url for your new site..
                destdir:     ~/public_html/foo
                repository:  ~/foo.git
        To modify settings, edit ~/foo.setup and then run:
-               ikiwiki -setup ~/foo.setup
+               ikiwiki --setup ~/foo.setup
 
 Done! 
 
@@ -46,14 +52,8 @@ Done!
 Now you can go to the url it told you, and edit pages in your new wiki
 using the web interface.
 
-You can log in using the wiki user and password (or the openid)
-that you told it to set up earlier. That user is an admin, so you can
-go to the Preferences page and click on "Wiki Setup" to further
-configure the wiki.
-
 (If the web interface doesn't seem to allow editing or login, you may
-need to configure [[apache|tips/apache_cgi]] or 
-[[lighttpd|tips/lighttpd_cgi]].)
+need to [[configure_the_web_server|tips/dot_cgi]].)
 
 ## Checkout and edit wiki source
 
@@ -62,8 +62,8 @@ web for editing pages, and instead using your favorite text editor and
 [[Revision_Control_System|rcs]]. 
 
 To do this, you need to check out a copy of the source to your wiki.
-You should avoid making changes directly to the `srcdir`, as that
-checkout is reserved for use by ikiwiki itself.
+(You should avoid making changes directly to the `srcdir`, as that
+checkout is reserved for use by ikiwiki itself.)
 
 Depending on which [[Revision_Control_System|rcs]] you chose to use,
 you can run one of these commands to check out your own copy of your wiki's
@@ -71,8 +71,10 @@ source. (Remember to replace "foo" with the real directory name.)
 
        git clone foo.git foo.src
        svn checkout file://`pwd`/foo.svn/trunk foo.src
+       cvs -d `pwd`/foo get -P ikiwiki
        bzr clone foo foo.src
        hg clone foo foo.src
+       darcs get foo.darcs foo.src
        # TODO monotone, tla
 
 Now to edit pages by hand, go into the directory you checked out (ie,
@@ -94,7 +96,7 @@ These range from changing the wiki's name, to enabling [[plugins]],
 to banning users and locking pages.
 
 If you log in as the admin user you configured earlier, and go to
-your Preferences page, you can click on "Wiki Setup" to customize many
+your Preferences page, you can click on "Setup" to customize many
 wiki settings and plugins.
 
 Some settings cannot be configured on the web, for security reasons or
@@ -105,7 +107,13 @@ and gives a brief description of each.
 
 After making changes to this file, you need to tell ikiwiki to use it:
 
-       % ikiwiki -setup foo.setup
+       % ikiwiki --setup foo.setup
+
+Alternatively, you can ask ikiwiki to change settings in the file for you:
+
+       % ikiwiki --changesetup foo.setup --plugin goodstuff
+
+See [[usage]] for more options.
 
 ## Customizing file locations
 
@@ -116,28 +124,33 @@ a working copy checked out from the version control system repository.
 When you used `auto.setup`, ikiwiki put the source directory, destination
 directory, and repository in your home directory, and told you the location
 of each. Those locations were chosen to work without customization, but you
-might want to move them to different directories. There are three steps to
-this process.
-
-1. Move the destination directory and repository around.
+might want to move them to different directories.
 
+First, move the destination directory and repository around.
+   
        % mv public_html/foo /srv/web/foo.com
        % mv foo.git /srv/git/foo.git
 
-2. Create a new source directory checkout. If you moved the repository
-   to a new location, checkouts pointing at the old location won't work,
-   and the easiest way to deal with this is to delete them and re-checkout
-   from the new repository location.
-
+If you moved the repository to a new location, checkouts pointing at the
+old location won't work, and the easiest way to deal with this is to delete
+them and re-checkout from the new repository location.
+   
        % rm -rf foo
-       % git clone /src/git/foo.git
+       % git clone /srv/git/foo.git
 
-3. Edit the setup file. Modify the settings for `srcdir`, `destdir`,
-   `url`, `cgiurl`, `cgi_wrapper`, `git_wrapper`, etc to reflect where
-   you moved things. Remember to run `ikiwiki -setup` after editing the
-   setup file.
+Finally, edit the setup file. Modify the settings for `srcdir`, `destdir`,
+`url`, `cgiurl`, `cgi_wrapper`, `git_wrapper`, etc to reflect where
+you moved things. Remember to run `ikiwiki --setup` after editing the
+setup file.
 
 ## Enjoy your new wiki!
 
 Add yourself to [[IkiWikiUsers]]. And check out
 the [[tips]] to find out how to get more out of ikiwiki.
+
+----
+
+_Notes_:
+
+- If you are searching for the file where the users are stored, it's in `your_repository/.ikiwiki/userdb`. The one which is in YOUR REPOSITORY, it cannot be found into your `~/.ikiwiki`.
+- If you want to enable a plugin you **WILL HAVE** to add it to the `add_plugins` array in the `*.setup` file (or to use the `--plugin` switch while calling `ikiwiki`). Uncommenting the plugin options/configuration fields in the setup is not **ALWAYS** sufficient. You have been warned.