Mercurial > wikked

annotate docs/pages/03_configuration.md @ 382:3a61f45702cb

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
docs: Add documentation site.
author Ludovic Chabant <ludovic@chabant.com>
date Sun, 04 Oct 2015 08:02:43 -0700
parents
children c19b8cc11938
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
382
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
1 ---
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
2 title: Configuration
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
3 icon: cog
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
4 ---
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
5
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
6 Wikked can be configured with a few files:
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
7
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
8 * `.wikirc`: this file, located at the root of your wiki, can be submitted into
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
9 revision control, so that various clones of the wiki have the same options
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
10 where it makes sense.
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
11
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
12 * `.wiki/wikirc`: some options, however, don't have to be the same depending on
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
13 where you run the wiki. This file is contained in the ignored-by-default
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
14 `.wiki` folder, and as such is meant to store options valid only for a local
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
15 installation.
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
16
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
17 * `.wiki/app.cfg`: Wikked runs on top of [Flask][]. This file, if it exists,
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
18 will be passed on to Flask for more advanced configuration scenarios. See the
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
19 [Flask configuration documentation][1] for more information.
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
20
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
21 [flask]: http://flask.pocoo.org/
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
22 [1]: http://flask.pocoo.org/docs/0.10/config/
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
23
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
24
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
25 The `wikirc` file is meant to be written with an INI-style format:
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
26
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
27 ```
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
28 [section1]
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
29 foo=bar
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
30 something=some other value
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
31
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
32 [section2]
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
33 blah=whatever
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
34 ```
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
35
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
36
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
37 ## Main options
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
38
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
39 The main Wikked options should be defined in a `[wiki]` section. Here are the
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
40 supported options:
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
41
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
42 * `main_page` (defaults to `Main page`): the name of the page that should be
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
43 displayed when people visit the root URL of your wiki. Page names are case
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
44 sensitive so watch out for the capitalization.
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
45
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
46 * `templates_dir` (defaults to `Templates`): by default, the `include` statement
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
47 (see the [syntax page][2]) will first look into a templates directory for
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
48 a template of the given name. This is the name of that folder.
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
49
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
50 * `indexer` (defaults to `whoosh`): The full-text indexer to use. Only 2 indexers are currently
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
51 supported, `whoosh` (for [Whoosh][]) and `elastic` (for [Elastic Search][elastic]).
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
52
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
53 * `database` (defaults to `sql`): The database system to use for the cache.
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
54 Wikked currently only supports SQL, but see the next option below.
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
55
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
56 * `database_url` (defaults to `sqlite:///%(root)s/.wiki/wiki.db`): the URL to
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
57 pass to [SQLAlchemy][] for connecting to the database. As you can see, the
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
58 default value will read or create an [SQLite][] file in the `.wiki` folder. If
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
59 you want to use a proper SQL server you can specify its URL and login
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
60 information instead. See the [SQLAlchemy connection string format][3] for more
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
61 information.
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
62
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
63 [2]: {{pcurl('syntax')}}
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
64 [3]: http://docs.sqlalchemy.org/en/latest/core/engines.html#database-urls
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
65 [SQLite]: http://sqlite.org
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
66 [SQLAlchemy]: http://sqlalchemy.org
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
67 [whoosh]: https://bitbucket.org/mchaput/whoosh/wiki/Home
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
68 [elastic]: http://www.elasticsearch.org/
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
69
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
70
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
71 ## Permissions
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
72
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
73 The `wikirc` file can also be used to define user permissions. This is done with
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
74 the `[users]` section:
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
75
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
76 [users]
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
77 dorothy=PASSWORD_HASH
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
78
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
79 The `PASSWORD_HASH` is, well, a password hash. You can generate one by using the
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
80 `wk newuser` command:
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
81
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
82 $ wkdev newuser dorothy
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
83 Password: ********
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
84 dorothy = $2a$12$7FR949jt9zq5iNwY5WAZAOzD7pK3P0f/NnrKHAys17HT1Omuk2Asu
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
85
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
86 (copy this into your .wikirc file)
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
87
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
88 Once you have some users defined, you can give them some permissions, using the
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
89 `[permissions]` section. Supported settings are:
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
90
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
91 * `readers`: users able to read the wiki.
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
92 * `writers`: users able to edit the wiki.
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
93
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
94 Multiple usernames must be separated by a comma. You can also use `*` for "all
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
95 users", and `anonymous` for unauthenticated visitors.
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
96
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
97 The following example shows a wiki only accessible to registered users, and that
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
98 can only be edited by `dorothy` and `toto`:
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
99
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
100 [permissions]
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
101 readers = *
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
102 writers = dorothy,toto
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
103
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
104 Those settings can also be overriden at the page level using the `readers` and
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
105 `writers` metadata. So you can still have a public landing page for the
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
106 previously mentioned private wiki by adding this to `Main page.md`:
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
107
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
108 {%raw%}
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
109 {{readers: *,anonymous}}
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
110 {%endraw%}
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
111