Mercurial > wikked

comparison docs/pages/05_deployment.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 dcaa41b39c23
comparison
equal deleted inserted replaced
381:d5511d832af3 382:3a61f45702cb
1 ---
2 title: Deployment
3 icon: server
4 ---
5
6 Wikked runs by default with an "easy" configuration, _i.e._ something that will
7 "just work" when you play around locally. In this default setup, it uses
8 [SQLite][] for the cache, and [Whoosh][] for the full-text search, all running
9 in Flask's built-in server.
10
11 [whoosh]: https://bitbucket.org/mchaput/whoosh/wiki/Home
12 [sqlite]: https://sqlite.org/
13
14 This technology stack works very well for running your wiki locally, or for
15 private websites. It has some limitations, however:
16
17 * The `wk runserver` command runs the Flask development server, which you
18 [shouldn't use in production][flaskdeploy]. You'll probably need to run Wikked
19 inside a proper server instead.
20 * When a page has been edited, Wikked will immediately evaluate and reformat all
21 pages that have a dependency on it. You probably want to have this done in the
22 background instead.
23
24 In this chapter we'll therefore look at deployment options, and follow-up with
25 some more advanced configurations for those with special requirements.
26
27 [flaskdeploy]: http://flask.pocoo.org/docs/deploying/
28
29
30 ## Apache and WSGI
31
32 A simple way to run Wikked on a production server is to use [Apache][] with
33 [`mod_wsgi`][wsgi]. For a proper introduction to the matter, you can see
34 [Flask's documentation on the subject][flask_wsgi]. Otherwise, you can probably
35 reuse the following examples.
36
37 [apache]: https://httpd.apache.org/
38 [wsgi]: http://code.google.com/p/modwsgi/
39 [flask_wsgi]: http://flask.pocoo.org/docs/deploying/mod_wsgi/
40
41 The first thing is to create a `.wsgi` file somewhere on your server. You only
42 need to create the Wikked WSGI app in it, and optionally activate your
43 `virtualenv` if you're using that:
44
45 # Activate your virtualenv
46 activate_this = '/path/to/venv/bin/activate_this.py'
47 execfile(activate_this, dict(__file__=activate_this))
48
49 # Get the Wikked WSGI app
50 from wikked.wsgiutil import get_wsgi_app
51 application = get_wsgi_app('/path/to/your/wiki/root')
52
53 The second thing to do is to add a new virtual host to your Apache
54 configuration. The [Flask documentation][flask_wsgi] shows an example that you
55 should be able to use directly, although you'll also need to tell Apache where
56 to serve some static files: Wikked's static files (Javascript, CSS, icons,
57 etc.), and your own wiki's files (your pictures and other attachments). This
58 means your Apache configuration will look like this in the end:
59
60 <VirtualHost *:80>
61 ServerName yourwikidomain.com
62
63 WSGIDaemonProcess yourwiki user=user1 group=group1 threads=5
64 WSGIScriptAlias / /path/to/your/wsgi/file.wsgi
65
66 DocumentRoot /path/to/your/wiki/_files
67 Alias /static/ /path/to/wikked/static/
68
69 <Directory /path/to/your/wiki>
70 WSGIProcessGroup yourwiki
71 WSGIApplicationGroup %{GLOBAL}
72 Order deny,allow
73 Allow from all
74 </Directory>
75 </VirtualHost>
76
77 > You will have to create the `_files` directory in your wiki before
78 > reloading Apache, otherwise it may complain about it.
79 >
80 > Also, the path to Wikked's `static` directory is going to point directly into
81 > your installed Wikked package. So if you installed it with `virtualenv`, it
82 > would be something like:
83 > `/path/to/your/wiki/venv/lib/python/site-packages/wikked/static`.
84
85
86 ## Background updates
87
88 The second thing to do is to enable background wiki updates. Good news: they're
89 already enabled if you used the `get_wsgi_app` function from the previous
90 section (you can disable it by passing `async_update=False` if you really need
91 to).
92
93 > If you want to use background updates locally, you can do `wk runserver
94 > --usetasks`.
95
96 However, you'll still need to run a separate process that, well, runs those
97 updates in the background. To do this:
98
99 cd /path/to/my/wiki
100 wk runtasks
101
102 > The background task handling is done with [Celery][]. By default, Wikked will
103 > use the [SQLAlchemy transport][celerysqlite].
104
105 [celery]: http://www.celeryproject.org/
106 [celerysqlite]: http://docs.celeryproject.org/en/latest/getting-started/brokers/sqlalchemy.html
107
108
109 ## Backend options
110
111 **This is for advanced use only**
112
113 If you want to use a different storage than SQLite, set the `database_url`
114 setting in your `wikirc` to an [SQLAlchemy-supported database URL][SQLAlchemy].
115 For instance, if you're using MySQL with `pymsql` installed:
116
117 [wiki]
118 database_url=mysql+pymysql://username:password123@localhost/db_name
119
120 [sqlalchemy]: http://docs.sqlalchemy.org/en/rel_0_9/core/engines.html#database-urls
121
122 > Note that you'll have to install the appropriate SQL layer. For instance: `pip
123 > install pymsql`. You will also obviously need to setup and configure your SQL
124 > server.
125
126
127 If Whoosh is also not suited to your needs, you can use [Elastic
128 Search][elastic] instead:
129
130 [wiki]
131 indexer=elastic
132
133 You'll obviously have to install and run Elastic Search.
134
135 [elastic]: http://www.elasticsearch.org/
136