Mercurial > wikked

annotate docs/pages/05_deployment.md @ 435:d8a1a031ad7d 0.7.0

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