Mercurial > kallithea

annotate docs/setup.rst @ 8592:307c876a6e89

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
db: introduce db-create --reuse option Support use of an existing database so the Kallithea database user doesn't have to be granted permissions to create databases. The existing database must of course have been created "correctly", for example using the right charset and collation on MariaDB/MySQL. Creating the database manually also provides a way to avoid the hardcoded defaults.
author Mads Kiilerich <mads@kiilerich.com>
date Thu, 25 Jun 2020 01:51:18 +0200
parents ff8651b2f14f
children 61bd04b90f58
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
568
5f481e4e888b updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff changeset
1 .. _setup:
5f481e4e888b updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff changeset
2
2095
Marcin Kuzminski <marcin@python-works.com>
parents: 2076
diff changeset
3 =====
568
5f481e4e888b updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff changeset
4 Setup
5f481e4e888b updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff changeset
5 =====
5f481e4e888b updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff changeset
6
5f481e4e888b updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff changeset
7
4192
e73a69cb98dc Rename some strings examples and commands in documentation
Bradley M. Kuhn <bkuhn@sfconservancy.org>
parents: 4186
diff changeset
8 Setting up Kallithea
1448
b05eb16ea105 fixes #206
Marcin Kuzminski <marcin@python-works.com>
parents: 1420
diff changeset
9 --------------------
572
a60cd29ba7e2 more docs update
Marcin Kuzminski <marcin@python-works.com>
parents: 568
diff changeset
10
8576
a63ccbc632d1 docs: add more section headings to setup description to show how it corresponds to the overview
Mads Kiilerich <mads@kiilerich.com>
parents: 8444
diff changeset
11 Some further details to the steps mentioned in the overview.
a63ccbc632d1 docs: add more section headings to setup description to show how it corresponds to the overview
Mads Kiilerich <mads@kiilerich.com>
parents: 8444
diff changeset
12
a63ccbc632d1 docs: add more section headings to setup description to show how it corresponds to the overview
Mads Kiilerich <mads@kiilerich.com>
parents: 8444
diff changeset
13 Create low level configuration file
a63ccbc632d1 docs: add more section headings to setup description to show how it corresponds to the overview
Mads Kiilerich <mads@kiilerich.com>
parents: 8444
diff changeset
14 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
a63ccbc632d1 docs: add more section headings to setup description to show how it corresponds to the overview
Mads Kiilerich <mads@kiilerich.com>
parents: 8444
diff changeset
15
8578
ff8651b2f14f docs: augment setup description with more details of http server and database
Mads Kiilerich <mads@kiilerich.com>
parents: 8577
diff changeset
16 First, you will need to create a Kallithea configuration file. The
ff8651b2f14f docs: augment setup description with more details of http server and database
Mads Kiilerich <mads@kiilerich.com>
parents: 8577
diff changeset
17 configuration file is a ``.ini`` file that contains various low level settings
ff8651b2f14f docs: augment setup description with more details of http server and database
Mads Kiilerich <mads@kiilerich.com>
parents: 8577
diff changeset
18 for Kallithea, e.g. configuration of how to use database, web server, email,
ff8651b2f14f docs: augment setup description with more details of http server and database
Mads Kiilerich <mads@kiilerich.com>
parents: 8577
diff changeset
19 and logging.
3224
8b8edfc25856 whitespace cleanup
Marcin Kuzminski <marcin@python-works.com>
parents: 2916
diff changeset
20
8578
ff8651b2f14f docs: augment setup description with more details of http server and database
Mads Kiilerich <mads@kiilerich.com>
parents: 8577
diff changeset
21 Run the following command to create the file ``my.ini`` in the current
ff8651b2f14f docs: augment setup description with more details of http server and database
Mads Kiilerich <mads@kiilerich.com>
parents: 8577
diff changeset
22 directory::
572
a60cd29ba7e2 more docs update
Marcin Kuzminski <marcin@python-works.com>
parents: 568
diff changeset
23
8578
ff8651b2f14f docs: augment setup description with more details of http server and database
Mads Kiilerich <mads@kiilerich.com>
parents: 8577
diff changeset
24 kallithea-cli config-create my.ini http_server=waitress
ff8651b2f14f docs: augment setup description with more details of http server and database
Mads Kiilerich <mads@kiilerich.com>
parents: 8577
diff changeset
25
ff8651b2f14f docs: augment setup description with more details of http server and database
Mads Kiilerich <mads@kiilerich.com>
parents: 8577
diff changeset
26 To get a good starting point for your configuration, specify the http server
ff8651b2f14f docs: augment setup description with more details of http server and database
Mads Kiilerich <mads@kiilerich.com>
parents: 8577
diff changeset
27 you intend to use. It can be ``waitress``, ``gearbox``, ``gevent``,
ff8651b2f14f docs: augment setup description with more details of http server and database
Mads Kiilerich <mads@kiilerich.com>
parents: 8577
diff changeset
28 ``gunicorn``, or ``uwsgi``. (Apache ``mod_wsgi`` will not use this
ff8651b2f14f docs: augment setup description with more details of http server and database
Mads Kiilerich <mads@kiilerich.com>
parents: 8577
diff changeset
29 configuration file, and it is fine to keep the default http_server configuration
ff8651b2f14f docs: augment setup description with more details of http server and database
Mads Kiilerich <mads@kiilerich.com>
parents: 8577
diff changeset
30 unused. ``mod_wsgi`` is configured using ``httpd.conf`` directives and a WSGI
ff8651b2f14f docs: augment setup description with more details of http server and database
Mads Kiilerich <mads@kiilerich.com>
parents: 8577
diff changeset
31 wrapper script.)
ff8651b2f14f docs: augment setup description with more details of http server and database
Mads Kiilerich <mads@kiilerich.com>
parents: 8577
diff changeset
32
ff8651b2f14f docs: augment setup description with more details of http server and database
Mads Kiilerich <mads@kiilerich.com>
parents: 8577
diff changeset
33 Extra custom settings can be specified like::
6898
a8b9f2d68e7d make-config: allow configuration of any ini value
Mads Kiilerich <mads@kiilerich.com>
parents: 6789
diff changeset
34
7406
7784a1212471 cli: convert 'gearbox make-config' into 'kallithea-cli config-create'
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7389
diff changeset
35 kallithea-cli config-create my.ini host=8.8.8.8 "[handler_console]" formatter=color_formatter
845
a040597b070b docs update
Marcin Kuzminski <marcin@python-works.com>
parents: 777
diff changeset
36
8576
a63ccbc632d1 docs: add more section headings to setup description to show how it corresponds to the overview
Mads Kiilerich <mads@kiilerich.com>
parents: 8444
diff changeset
37 Populate the database
a63ccbc632d1 docs: add more section headings to setup description to show how it corresponds to the overview
Mads Kiilerich <mads@kiilerich.com>
parents: 8444
diff changeset
38 ^^^^^^^^^^^^^^^^^^^^^
a63ccbc632d1 docs: add more section headings to setup description to show how it corresponds to the overview
Mads Kiilerich <mads@kiilerich.com>
parents: 8444
diff changeset
39
8578
ff8651b2f14f docs: augment setup description with more details of http server and database
Mads Kiilerich <mads@kiilerich.com>
parents: 8577
diff changeset
40 Next, you need to create the databases used by Kallithea. Kallithea currently
ff8651b2f14f docs: augment setup description with more details of http server and database
Mads Kiilerich <mads@kiilerich.com>
parents: 8577
diff changeset
41 supports PostgreSQL, SQLite and MariaDB/MySQL databases. It is recommended to
ff8651b2f14f docs: augment setup description with more details of http server and database
Mads Kiilerich <mads@kiilerich.com>
parents: 8577
diff changeset
42 start out using SQLite (the default) and move to PostgreSQL if it becomes a
ff8651b2f14f docs: augment setup description with more details of http server and database
Mads Kiilerich <mads@kiilerich.com>
parents: 8577
diff changeset
43 bottleneck or to get a "proper" database. MariaDB/MySQL is also supported.
ff8651b2f14f docs: augment setup description with more details of http server and database
Mads Kiilerich <mads@kiilerich.com>
parents: 8577
diff changeset
44
ff8651b2f14f docs: augment setup description with more details of http server and database
Mads Kiilerich <mads@kiilerich.com>
parents: 8577
diff changeset
45 For PostgreSQL, run ``pip install psycopg2`` to get the database driver. Make
ff8651b2f14f docs: augment setup description with more details of http server and database
Mads Kiilerich <mads@kiilerich.com>
parents: 8577
diff changeset
46 sure the PostgreSQL server is initialized and running. Make sure you have a
ff8651b2f14f docs: augment setup description with more details of http server and database
Mads Kiilerich <mads@kiilerich.com>
parents: 8577
diff changeset
47 database user with password authentication with permissions to create databases
ff8651b2f14f docs: augment setup description with more details of http server and database
Mads Kiilerich <mads@kiilerich.com>
parents: 8577
diff changeset
48 - for example by running::
ff8651b2f14f docs: augment setup description with more details of http server and database
Mads Kiilerich <mads@kiilerich.com>
parents: 8577
diff changeset
49
ff8651b2f14f docs: augment setup description with more details of http server and database
Mads Kiilerich <mads@kiilerich.com>
parents: 8577
diff changeset
50 sudo -u postgres createuser 'kallithea' --pwprompt --createdb
ff8651b2f14f docs: augment setup description with more details of http server and database
Mads Kiilerich <mads@kiilerich.com>
parents: 8577
diff changeset
51
ff8651b2f14f docs: augment setup description with more details of http server and database
Mads Kiilerich <mads@kiilerich.com>
parents: 8577
diff changeset
52 For MariaDB/MySQL, run ``pip install mysqlclient`` to get the ``MySQLdb``
ff8651b2f14f docs: augment setup description with more details of http server and database
Mads Kiilerich <mads@kiilerich.com>
parents: 8577
diff changeset
53 database driver. Make sure the database server is initialized and running. Make
ff8651b2f14f docs: augment setup description with more details of http server and database
Mads Kiilerich <mads@kiilerich.com>
parents: 8577
diff changeset
54 sure you have a database user with password authentication with permissions to
ff8651b2f14f docs: augment setup description with more details of http server and database
Mads Kiilerich <mads@kiilerich.com>
parents: 8577
diff changeset
55 create the database - for example by running::
ff8651b2f14f docs: augment setup description with more details of http server and database
Mads Kiilerich <mads@kiilerich.com>
parents: 8577
diff changeset
56
ff8651b2f14f docs: augment setup description with more details of http server and database
Mads Kiilerich <mads@kiilerich.com>
parents: 8577
diff changeset
57 echo 'CREATE USER "kallithea"@"localhost" IDENTIFIED BY "password"' | sudo -u mysql mysql
ff8651b2f14f docs: augment setup description with more details of http server and database
Mads Kiilerich <mads@kiilerich.com>
parents: 8577
diff changeset
58 echo 'GRANT ALL PRIVILEGES ON `kallithea`.* TO "kallithea"@"localhost"' | sudo -u mysql mysql
ff8651b2f14f docs: augment setup description with more details of http server and database
Mads Kiilerich <mads@kiilerich.com>
parents: 8577
diff changeset
59
ff8651b2f14f docs: augment setup description with more details of http server and database
Mads Kiilerich <mads@kiilerich.com>
parents: 8577
diff changeset
60 Check and adjust ``sqlalchemy.url`` in your ``my.ini`` configuration file to use
ff8651b2f14f docs: augment setup description with more details of http server and database
Mads Kiilerich <mads@kiilerich.com>
parents: 8577
diff changeset
61 this database.
ff8651b2f14f docs: augment setup description with more details of http server and database
Mads Kiilerich <mads@kiilerich.com>
parents: 8577
diff changeset
62
ff8651b2f14f docs: augment setup description with more details of http server and database
Mads Kiilerich <mads@kiilerich.com>
parents: 8577
diff changeset
63 Create the database, tables, and initial content by running the following
ff8651b2f14f docs: augment setup description with more details of http server and database
Mads Kiilerich <mads@kiilerich.com>
parents: 8577
diff changeset
64 command::
572
a60cd29ba7e2 more docs update
Marcin Kuzminski <marcin@python-works.com>
parents: 568
diff changeset
65
7414
3158cf0dafb7 cli: convert 'gearbox setup-db' into 'kallithea-cli db-create'
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7406
diff changeset
66 kallithea-cli db-create -c my.ini
572
a60cd29ba7e2 more docs update
Marcin Kuzminski <marcin@python-works.com>
parents: 568
diff changeset
67
8577
4742b8c89472 docs: drop odd verbose note on writeable root path
Mads Kiilerich <mads@kiilerich.com>
parents: 8576
diff changeset
68 This will first prompt you for a "root" path. This "root" path is the location
4742b8c89472 docs: drop odd verbose note on writeable root path
Mads Kiilerich <mads@kiilerich.com>
parents: 8576
diff changeset
69 where Kallithea will store all of its repositories on the current machine. This
4742b8c89472 docs: drop odd verbose note on writeable root path
Mads Kiilerich <mads@kiilerich.com>
parents: 8576
diff changeset
70 location must be writable for the running Kallithea application. Next,
4742b8c89472 docs: drop odd verbose note on writeable root path
Mads Kiilerich <mads@kiilerich.com>
parents: 8576
diff changeset
71 ``db-create`` will prompt you for a username and password for the initial admin
4742b8c89472 docs: drop odd verbose note on writeable root path
Mads Kiilerich <mads@kiilerich.com>
parents: 8576
diff changeset
72 account it sets up for you.
845
a040597b070b docs update
Marcin Kuzminski <marcin@python-works.com>
parents: 777
diff changeset
73
7414
3158cf0dafb7 cli: convert 'gearbox setup-db' into 'kallithea-cli db-create'
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7406
diff changeset
74 The ``db-create`` values can also be given on the command line.
5425
5ae8e644aa88 docs: spelling, grammar, content and typography
Søren Løvborg <sorenl@unity3d.com>
parents: 5413
diff changeset
75 Example::
2358
69df04ee1e2b added detailed step-by-step installation instruction for windows
Marcin Kuzminski <marcin@python-works.com>
parents: 2284
diff changeset
76
7414
3158cf0dafb7 cli: convert 'gearbox setup-db' into 'kallithea-cli db-create'
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7406
diff changeset
77 kallithea-cli db-create -c my.ini --user=nn --password=secret --email=nn@example.com --repos=/srv/repos
3224
8b8edfc25856 whitespace cleanup
Marcin Kuzminski <marcin@python-works.com>
parents: 2916
diff changeset
78
7414
3158cf0dafb7 cli: convert 'gearbox setup-db' into 'kallithea-cli db-create'
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7406
diff changeset
79 The ``db-create`` command will create all needed tables and an
4955
4e6dfdb3fa01 docs: English and consistency corrections
Michael V. DePalatis <mike@depalatis.net>
parents: 4925
diff changeset
80 admin account. When choosing a root path you can either use a new
4e6dfdb3fa01 docs: English and consistency corrections
Michael V. DePalatis <mike@depalatis.net>
parents: 4925
diff changeset
81 empty location, or a location which already contains existing
4e6dfdb3fa01 docs: English and consistency corrections
Michael V. DePalatis <mike@depalatis.net>
parents: 4925
diff changeset
82 repositories. If you choose a location which contains existing
4e6dfdb3fa01 docs: English and consistency corrections
Michael V. DePalatis <mike@depalatis.net>
parents: 4925
diff changeset
83 repositories Kallithea will add all of the repositories at the chosen
4e6dfdb3fa01 docs: English and consistency corrections
Michael V. DePalatis <mike@depalatis.net>
parents: 4925
diff changeset
84 location to its database. (Note: make sure you specify the correct
4e6dfdb3fa01 docs: English and consistency corrections
Michael V. DePalatis <mike@depalatis.net>
parents: 4925
diff changeset
85 path to the root).
572
a60cd29ba7e2 more docs update
Marcin Kuzminski <marcin@python-works.com>
parents: 568
diff changeset
86
8592
307c876a6e89 db: introduce db-create --reuse option
Mads Kiilerich <mads@kiilerich.com>
parents: 8578
diff changeset
87 .. note:: It is also possible to use an existing database. For example,
307c876a6e89 db: introduce db-create --reuse option
Mads Kiilerich <mads@kiilerich.com>
parents: 8578
diff changeset
88 when using PostgreSQL without granting general createdb privileges to
307c876a6e89 db: introduce db-create --reuse option
Mads Kiilerich <mads@kiilerich.com>
parents: 8578
diff changeset
89 the PostgreSQL kallithea user, set ``sqlalchemy.url =
307c876a6e89 db: introduce db-create --reuse option
Mads Kiilerich <mads@kiilerich.com>
parents: 8578
diff changeset
90 postgresql://kallithea:password@localhost/kallithea`` and create the
307c876a6e89 db: introduce db-create --reuse option
Mads Kiilerich <mads@kiilerich.com>
parents: 8578
diff changeset
91 database like::
307c876a6e89 db: introduce db-create --reuse option
Mads Kiilerich <mads@kiilerich.com>
parents: 8578
diff changeset
92
307c876a6e89 db: introduce db-create --reuse option
Mads Kiilerich <mads@kiilerich.com>
parents: 8578
diff changeset
93 sudo -u postgres createdb 'kallithea' --owner 'kallithea'
307c876a6e89 db: introduce db-create --reuse option
Mads Kiilerich <mads@kiilerich.com>
parents: 8578
diff changeset
94 kallithea-cli db-create -c my.ini --reuse
307c876a6e89 db: introduce db-create --reuse option
Mads Kiilerich <mads@kiilerich.com>
parents: 8578
diff changeset
95
8576
a63ccbc632d1 docs: add more section headings to setup description to show how it corresponds to the overview
Mads Kiilerich <mads@kiilerich.com>
parents: 8444
diff changeset
96 Prepare front-end files
a63ccbc632d1 docs: add more section headings to setup description to show how it corresponds to the overview
Mads Kiilerich <mads@kiilerich.com>
parents: 8444
diff changeset
97 ^^^^^^^^^^^^^^^^^^^^^^^
a63ccbc632d1 docs: add more section headings to setup description to show how it corresponds to the overview
Mads Kiilerich <mads@kiilerich.com>
parents: 8444
diff changeset
98
8444
850f096505ac docs: mention the npm dependency more clearly (Issue #345)
Mads Kiilerich <mads@kiilerich.com>
parents: 8443
diff changeset
99 Finally, the front-end files must be prepared. This requires ``npm`` version 6
850f096505ac docs: mention the npm dependency more clearly (Issue #345)
Mads Kiilerich <mads@kiilerich.com>
parents: 8443
diff changeset
100 or later, which needs ``node.js`` (version 12 or later). Prepare the front-end
850f096505ac docs: mention the npm dependency more clearly (Issue #345)
Mads Kiilerich <mads@kiilerich.com>
parents: 8443
diff changeset
101 by running::
7437
b66725ba01ed cli: add command 'kallithea-cli front-end-build'
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7417
diff changeset
102
b66725ba01ed cli: add command 'kallithea-cli front-end-build'
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7417
diff changeset
103 kallithea-cli front-end-build
b66725ba01ed cli: add command 'kallithea-cli front-end-build'
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7417
diff changeset
104
8576
a63ccbc632d1 docs: add more section headings to setup description to show how it corresponds to the overview
Mads Kiilerich <mads@kiilerich.com>
parents: 8444
diff changeset
105 Running
a63ccbc632d1 docs: add more section headings to setup description to show how it corresponds to the overview
Mads Kiilerich <mads@kiilerich.com>
parents: 8444
diff changeset
106 ^^^^^^^
a63ccbc632d1 docs: add more section headings to setup description to show how it corresponds to the overview
Mads Kiilerich <mads@kiilerich.com>
parents: 8444
diff changeset
107
8578
ff8651b2f14f docs: augment setup description with more details of http server and database
Mads Kiilerich <mads@kiilerich.com>
parents: 8577
diff changeset
108 You are now ready to use Kallithea. To run it using a gearbox web server,
ff8651b2f14f docs: augment setup description with more details of http server and database
Mads Kiilerich <mads@kiilerich.com>
parents: 8577
diff changeset
109 simply execute::
3224
8b8edfc25856 whitespace cleanup
Marcin Kuzminski <marcin@python-works.com>
parents: 2916
diff changeset
110
6554
2c3d30095d5e gearbox: replace paster with something TurboGears2-ish that still works with the Pylons stack
Mads Kiilerich <madski@unity3d.com>
parents: 6457
diff changeset
111 gearbox serve -c my.ini
3224
8b8edfc25856 whitespace cleanup
Marcin Kuzminski <marcin@python-works.com>
parents: 2916
diff changeset
112
4955
4e6dfdb3fa01 docs: English and consistency corrections
Michael V. DePalatis <mike@depalatis.net>
parents: 4925
diff changeset
113 - This command runs the Kallithea server. The web app should be available at
5425
5ae8e644aa88 docs: spelling, grammar, content and typography
Søren Løvborg <sorenl@unity3d.com>
parents: 5413
diff changeset
114 http://127.0.0.1:5000. The IP address and port is configurable via the
5ae8e644aa88 docs: spelling, grammar, content and typography
Søren Løvborg <sorenl@unity3d.com>
parents: 5413
diff changeset
115 configuration file created in the previous step.
7414
3158cf0dafb7 cli: convert 'gearbox setup-db' into 'kallithea-cli db-create'
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7406
diff changeset
116 - Log in to Kallithea using the admin account created when running ``db-create``.
3224
8b8edfc25856 whitespace cleanup
Marcin Kuzminski <marcin@python-works.com>
parents: 2916
diff changeset
117 - The default permissions on each repository is read, and the owner is admin.
1092
8af52e1224ff merge docs in beta with those corrected by Jason Harris
Marcin Kuzminski <marcin@python-works.com>
parents: 1062
diff changeset
118 Remember to update these if needed.
4955
4e6dfdb3fa01 docs: English and consistency corrections
Michael V. DePalatis <mike@depalatis.net>
parents: 4925
diff changeset
119 - In the admin panel you can toggle LDAP, anonymous, and permissions
4e6dfdb3fa01 docs: English and consistency corrections
Michael V. DePalatis <mike@depalatis.net>
parents: 4925
diff changeset
120 settings, as well as edit more advanced options on users and
5425
5ae8e644aa88 docs: spelling, grammar, content and typography
Søren Løvborg <sorenl@unity3d.com>
parents: 5413
diff changeset
121 repositories.
1092
8af52e1224ff merge docs in beta with those corrected by Jason Harris
Marcin Kuzminski <marcin@python-works.com>
parents: 1062
diff changeset
122
5077
faf943716616 rcextensions: cleanup of code and documentation
Mads Kiilerich <madski@unity3d.com>
parents: 4955
diff changeset
123
6695
8931078f70db docs: add documentation about internationalization from a user perspective
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 6555
diff changeset
124 Internationalization (i18n support)
8931078f70db docs: add documentation about internationalization from a user perspective
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 6555
diff changeset
125 -----------------------------------
2105
926f55b038bc added initial rc-extension module
Marcin Kuzminski <marcin@python-works.com>
parents: 2095
diff changeset
126
6695
8931078f70db docs: add documentation about internationalization from a user perspective
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 6555
diff changeset
127 The Kallithea web interface is automatically displayed in the user's preferred
8931078f70db docs: add documentation about internationalization from a user perspective
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 6555
diff changeset
128 language, as indicated by the browser. Thus, different users may see the
8931078f70db docs: add documentation about internationalization from a user perspective
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 6555
diff changeset
129 application in different languages. If the requested language is not available
8931078f70db docs: add documentation about internationalization from a user perspective
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 6555
diff changeset
130 (because the translation file for that language does not yet exist or is
8095
7c7d6b5c07c7 i18n: make sure 'en' in Accept-Language is recognized as having 100% coverage - i18n.lang is for source language
Mads Kiilerich <mads@kiilerich.com>
parents: 8086
diff changeset
131 incomplete), English is used.
1092
8af52e1224ff merge docs in beta with those corrected by Jason Harris
Marcin Kuzminski <marcin@python-works.com>
parents: 1062
diff changeset
132
6695
8931078f70db docs: add documentation about internationalization from a user perspective
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 6555
diff changeset
133 If you want to disable automatic language detection and instead configure a
8931078f70db docs: add documentation about internationalization from a user perspective
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 6555
diff changeset
134 fixed language regardless of user preference, set ``i18n.enabled = false`` and
8095
7c7d6b5c07c7 i18n: make sure 'en' in Accept-Language is recognized as having 100% coverage - i18n.lang is for source language
Mads Kiilerich <mads@kiilerich.com>
parents: 8086
diff changeset
135 specify another language by setting ``i18n.lang`` in the Kallithea
7c7d6b5c07c7 i18n: make sure 'en' in Accept-Language is recognized as having 100% coverage - i18n.lang is for source language
Mads Kiilerich <mads@kiilerich.com>
parents: 8086
diff changeset
136 configuration file.
1092
8af52e1224ff merge docs in beta with those corrected by Jason Harris
Marcin Kuzminski <marcin@python-works.com>
parents: 1062
diff changeset
137
8af52e1224ff merge docs in beta with those corrected by Jason Harris
Marcin Kuzminski <marcin@python-works.com>
parents: 1062
diff changeset
138
4192
e73a69cb98dc Rename some strings examples and commands in documentation
Bradley M. Kuhn <bkuhn@sfconservancy.org>
parents: 4186
diff changeset
139 Using Kallithea with SSH
912
8378122aa408 docs: changelog + setup update
Marcin Kuzminski <marcin@python-works.com>
parents: 894
diff changeset
140 ------------------------
8378122aa408 docs: changelog + setup update
Marcin Kuzminski <marcin@python-works.com>
parents: 894
diff changeset
141
7783
e4f27ab7cbea ssh: add documentation of SSH support
Christian Oyarzun <oyarzun@gmail.com>
parents: 7653
diff changeset
142 Kallithea supports repository access via SSH key based authentication.
7829
ee4fc2d20d09 docs: add high-level description of SSH repository access
Mads Kiilerich <mads@kiilerich.com>
parents: 7783
diff changeset
143 This means:
ee4fc2d20d09 docs: add high-level description of SSH repository access
Mads Kiilerich <mads@kiilerich.com>
parents: 7783
diff changeset
144
ee4fc2d20d09 docs: add high-level description of SSH repository access
Mads Kiilerich <mads@kiilerich.com>
parents: 7783
diff changeset
145 - repository URLs like ``ssh://kallithea@example.com/name/of/repository``
ee4fc2d20d09 docs: add high-level description of SSH repository access
Mads Kiilerich <mads@kiilerich.com>
parents: 7783
diff changeset
146
ee4fc2d20d09 docs: add high-level description of SSH repository access
Mads Kiilerich <mads@kiilerich.com>
parents: 7783
diff changeset
147 - all network traffic for both read and write happens over the SSH protocol on
ee4fc2d20d09 docs: add high-level description of SSH repository access
Mads Kiilerich <mads@kiilerich.com>
parents: 7783
diff changeset
148 port 22, without using HTTP/HTTPS nor the Kallithea WSGI application
ee4fc2d20d09 docs: add high-level description of SSH repository access
Mads Kiilerich <mads@kiilerich.com>
parents: 7783
diff changeset
149
ee4fc2d20d09 docs: add high-level description of SSH repository access
Mads Kiilerich <mads@kiilerich.com>
parents: 7783
diff changeset
150 - encryption and authentication protocols are managed by the system's ``sshd``
ee4fc2d20d09 docs: add high-level description of SSH repository access
Mads Kiilerich <mads@kiilerich.com>
parents: 7783
diff changeset
151 process, with all users using the same Kallithea system user (e.g.
ee4fc2d20d09 docs: add high-level description of SSH repository access
Mads Kiilerich <mads@kiilerich.com>
parents: 7783
diff changeset
152 ``kallithea``) when connecting to the SSH server, but with users' public keys
ee4fc2d20d09 docs: add high-level description of SSH repository access
Mads Kiilerich <mads@kiilerich.com>
parents: 7783
diff changeset
153 in the Kallithea system user's `.ssh/authorized_keys` file granting each user
ee4fc2d20d09 docs: add high-level description of SSH repository access
Mads Kiilerich <mads@kiilerich.com>
parents: 7783
diff changeset
154 sandboxed access to the repositories.
ee4fc2d20d09 docs: add high-level description of SSH repository access
Mads Kiilerich <mads@kiilerich.com>
parents: 7783
diff changeset
155
ee4fc2d20d09 docs: add high-level description of SSH repository access
Mads Kiilerich <mads@kiilerich.com>
parents: 7783
diff changeset
156 - users and admins can manage SSH public keys in the web UI
ee4fc2d20d09 docs: add high-level description of SSH repository access
Mads Kiilerich <mads@kiilerich.com>
parents: 7783
diff changeset
157
ee4fc2d20d09 docs: add high-level description of SSH repository access
Mads Kiilerich <mads@kiilerich.com>
parents: 7783
diff changeset
158 - in their SSH client configuration, users can configure how the client should
ee4fc2d20d09 docs: add high-level description of SSH repository access
Mads Kiilerich <mads@kiilerich.com>
parents: 7783
diff changeset
159 control access to their SSH key - without passphrase, with passphrase, and
ee4fc2d20d09 docs: add high-level description of SSH repository access
Mads Kiilerich <mads@kiilerich.com>
parents: 7783
diff changeset
160 optionally with passphrase caching in the local shell session (``ssh-agent``).
ee4fc2d20d09 docs: add high-level description of SSH repository access
Mads Kiilerich <mads@kiilerich.com>
parents: 7783
diff changeset
161 This is standard SSH functionality, not something Kallithea provides or
ee4fc2d20d09 docs: add high-level description of SSH repository access
Mads Kiilerich <mads@kiilerich.com>
parents: 7783
diff changeset
162 interferes with.
ee4fc2d20d09 docs: add high-level description of SSH repository access
Mads Kiilerich <mads@kiilerich.com>
parents: 7783
diff changeset
163
ee4fc2d20d09 docs: add high-level description of SSH repository access
Mads Kiilerich <mads@kiilerich.com>
parents: 7783
diff changeset
164 - network communication between client and server happens in a bidirectional
ee4fc2d20d09 docs: add high-level description of SSH repository access
Mads Kiilerich <mads@kiilerich.com>
parents: 7783
diff changeset
165 stateful stream, and will in some cases be faster than HTTP/HTTPS with several
ee4fc2d20d09 docs: add high-level description of SSH repository access
Mads Kiilerich <mads@kiilerich.com>
parents: 7783
diff changeset
166 stateless round-trips.
ee4fc2d20d09 docs: add high-level description of SSH repository access
Mads Kiilerich <mads@kiilerich.com>
parents: 7783
diff changeset
167
7783
e4f27ab7cbea ssh: add documentation of SSH support
Christian Oyarzun <oyarzun@gmail.com>
parents: 7653
diff changeset
168 .. note:: At this moment, repository access via SSH has been tested on Unix
e4f27ab7cbea ssh: add documentation of SSH support
Christian Oyarzun <oyarzun@gmail.com>
parents: 7653
diff changeset
169 only. Windows users that care about SSH are invited to test it and report
e4f27ab7cbea ssh: add documentation of SSH support
Christian Oyarzun <oyarzun@gmail.com>
parents: 7653
diff changeset
170 problems, ideally contributing patches that solve these problems.
e4f27ab7cbea ssh: add documentation of SSH support
Christian Oyarzun <oyarzun@gmail.com>
parents: 7653
diff changeset
171
e4f27ab7cbea ssh: add documentation of SSH support
Christian Oyarzun <oyarzun@gmail.com>
parents: 7653
diff changeset
172 Users and admins can upload SSH public keys (e.g. ``.ssh/id_rsa.pub``) through
e4f27ab7cbea ssh: add documentation of SSH support
Christian Oyarzun <oyarzun@gmail.com>
parents: 7653
diff changeset
173 the web interface. The server's ``.ssh/authorized_keys`` file is automatically
e4f27ab7cbea ssh: add documentation of SSH support
Christian Oyarzun <oyarzun@gmail.com>
parents: 7653
diff changeset
174 maintained with an entry for each SSH key. Each entry will tell ``sshd`` to run
e4f27ab7cbea ssh: add documentation of SSH support
Christian Oyarzun <oyarzun@gmail.com>
parents: 7653
diff changeset
175 ``kallithea-cli`` with the ``ssh-serve`` sub-command and the right Kallithea user ID
e4f27ab7cbea ssh: add documentation of SSH support
Christian Oyarzun <oyarzun@gmail.com>
parents: 7653
diff changeset
176 when encountering the corresponding SSH key.
1092
8af52e1224ff merge docs in beta with those corrected by Jason Harris
Marcin Kuzminski <marcin@python-works.com>
parents: 1062
diff changeset
177
7783
e4f27ab7cbea ssh: add documentation of SSH support
Christian Oyarzun <oyarzun@gmail.com>
parents: 7653
diff changeset
178 To enable SSH repository access, Kallithea must be configured with the path to
e4f27ab7cbea ssh: add documentation of SSH support
Christian Oyarzun <oyarzun@gmail.com>
parents: 7653
diff changeset
179 the ``.ssh/authorized_keys`` file for the Kallithea user, and the path to the
e4f27ab7cbea ssh: add documentation of SSH support
Christian Oyarzun <oyarzun@gmail.com>
parents: 7653
diff changeset
180 ``kallithea-cli`` command. Put something like this in the ``.ini`` file::
912
8378122aa408 docs: changelog + setup update
Marcin Kuzminski <marcin@python-works.com>
parents: 894
diff changeset
181
7783
e4f27ab7cbea ssh: add documentation of SSH support
Christian Oyarzun <oyarzun@gmail.com>
parents: 7653
diff changeset
182 ssh_enabled = true
e4f27ab7cbea ssh: add documentation of SSH support
Christian Oyarzun <oyarzun@gmail.com>
parents: 7653
diff changeset
183 ssh_authorized_keys = /home/kallithea/.ssh/authorized_keys
e4f27ab7cbea ssh: add documentation of SSH support
Christian Oyarzun <oyarzun@gmail.com>
parents: 7653
diff changeset
184 kallithea_cli_path = /srv/kallithea/venv/bin/kallithea-cli
e4f27ab7cbea ssh: add documentation of SSH support
Christian Oyarzun <oyarzun@gmail.com>
parents: 7653
diff changeset
185
e4f27ab7cbea ssh: add documentation of SSH support
Christian Oyarzun <oyarzun@gmail.com>
parents: 7653
diff changeset
186 The SSH service must be running, and the Kallithea user account must be active
e4f27ab7cbea ssh: add documentation of SSH support
Christian Oyarzun <oyarzun@gmail.com>
parents: 7653
diff changeset
187 (not necessarily with password access, but public key access must be enabled),
e4f27ab7cbea ssh: add documentation of SSH support
Christian Oyarzun <oyarzun@gmail.com>
parents: 7653
diff changeset
188 all file permissions must be set as sshd wants it, and ``authorized_keys`` must
e4f27ab7cbea ssh: add documentation of SSH support
Christian Oyarzun <oyarzun@gmail.com>
parents: 7653
diff changeset
189 be writeable by the Kallithea user.
4955
4e6dfdb3fa01 docs: English and consistency corrections
Michael V. DePalatis <mike@depalatis.net>
parents: 4925
diff changeset
190
7783
e4f27ab7cbea ssh: add documentation of SSH support
Christian Oyarzun <oyarzun@gmail.com>
parents: 7653
diff changeset
191 .. note:: The ``authorized_keys`` file will be rewritten from scratch on
e4f27ab7cbea ssh: add documentation of SSH support
Christian Oyarzun <oyarzun@gmail.com>
parents: 7653
diff changeset
192 each update. If it already exists with other data, Kallithea will not
e4f27ab7cbea ssh: add documentation of SSH support
Christian Oyarzun <oyarzun@gmail.com>
parents: 7653
diff changeset
193 overwrite the existing ``authorized_keys``, and the server process will
e4f27ab7cbea ssh: add documentation of SSH support
Christian Oyarzun <oyarzun@gmail.com>
parents: 7653
diff changeset
194 instead throw an exception. The system administrator thus cannot ssh
e4f27ab7cbea ssh: add documentation of SSH support
Christian Oyarzun <oyarzun@gmail.com>
parents: 7653
diff changeset
195 directly to the Kallithea user but must use su/sudo from another account.
912
8378122aa408 docs: changelog + setup update
Marcin Kuzminski <marcin@python-works.com>
parents: 894
diff changeset
196
7783
e4f27ab7cbea ssh: add documentation of SSH support
Christian Oyarzun <oyarzun@gmail.com>
parents: 7653
diff changeset
197 If ``/home/kallithea/.ssh/`` (the directory of the path specified in the
e4f27ab7cbea ssh: add documentation of SSH support
Christian Oyarzun <oyarzun@gmail.com>
parents: 7653
diff changeset
198 ``ssh_authorized_keys`` setting of the ``.ini`` file) does not exist as a
e4f27ab7cbea ssh: add documentation of SSH support
Christian Oyarzun <oyarzun@gmail.com>
parents: 7653
diff changeset
199 directory, Kallithea will attempt to create it. If that path exists but is
e4f27ab7cbea ssh: add documentation of SSH support
Christian Oyarzun <oyarzun@gmail.com>
parents: 7653
diff changeset
200 *not* a directory, or is not readable-writable-executable by the server
e4f27ab7cbea ssh: add documentation of SSH support
Christian Oyarzun <oyarzun@gmail.com>
parents: 7653
diff changeset
201 process, the server process will raise an exception each time it attempts to
e4f27ab7cbea ssh: add documentation of SSH support
Christian Oyarzun <oyarzun@gmail.com>
parents: 7653
diff changeset
202 write the ``authorized_keys`` file.
1092
8af52e1224ff merge docs in beta with those corrected by Jason Harris
Marcin Kuzminski <marcin@python-works.com>
parents: 1062
diff changeset
203
8372
a9e71e61cedf ssh: mention in docs how to use multiple authorized_keys files
Mads Kiilerich <mads@kiilerich.com>
parents: 8268
diff changeset
204 .. note:: It is possible to configure the SSH server to look for authorized
a9e71e61cedf ssh: mention in docs how to use multiple authorized_keys files
Mads Kiilerich <mads@kiilerich.com>
parents: 8268
diff changeset
205 keys in multiple files, for example reserving ``ssh/authorized_keys`` to be
a9e71e61cedf ssh: mention in docs how to use multiple authorized_keys files
Mads Kiilerich <mads@kiilerich.com>
parents: 8268
diff changeset
206 used for normal SSH and with Kallithea using
a9e71e61cedf ssh: mention in docs how to use multiple authorized_keys files
Mads Kiilerich <mads@kiilerich.com>
parents: 8268
diff changeset
207 ``.ssh/authorized_keys_kallithea``. In ``/etc/ssh/sshd_config`` set
a9e71e61cedf ssh: mention in docs how to use multiple authorized_keys files
Mads Kiilerich <mads@kiilerich.com>
parents: 8268
diff changeset
208 ``AuthorizedKeysFile .ssh/authorized_keys .ssh/authorized_keys_kallithea``
a9e71e61cedf ssh: mention in docs how to use multiple authorized_keys files
Mads Kiilerich <mads@kiilerich.com>
parents: 8268
diff changeset
209 and restart sshd, and in ``my.ini`` set ``ssh_authorized_keys =
a9e71e61cedf ssh: mention in docs how to use multiple authorized_keys files
Mads Kiilerich <mads@kiilerich.com>
parents: 8268
diff changeset
210 /home/kallithea/.ssh/authorized_keys_kallithea``. Note that this new
a9e71e61cedf ssh: mention in docs how to use multiple authorized_keys files
Mads Kiilerich <mads@kiilerich.com>
parents: 8268
diff changeset
211 location will apply to all system users, and that multiple entries for the
a9e71e61cedf ssh: mention in docs how to use multiple authorized_keys files
Mads Kiilerich <mads@kiilerich.com>
parents: 8268
diff changeset
212 same SSH key will shadow each other.
a9e71e61cedf ssh: mention in docs how to use multiple authorized_keys files
Mads Kiilerich <mads@kiilerich.com>
parents: 8268
diff changeset
213
7783
e4f27ab7cbea ssh: add documentation of SSH support
Christian Oyarzun <oyarzun@gmail.com>
parents: 7653
diff changeset
214 .. warning:: The handling of SSH access is steered directly by the command
e4f27ab7cbea ssh: add documentation of SSH support
Christian Oyarzun <oyarzun@gmail.com>
parents: 7653
diff changeset
215 specified in the ``authorized_keys`` file. There is no interaction with the
e4f27ab7cbea ssh: add documentation of SSH support
Christian Oyarzun <oyarzun@gmail.com>
parents: 7653
diff changeset
216 web UI. Once SSH access is correctly configured and enabled, it will work
e4f27ab7cbea ssh: add documentation of SSH support
Christian Oyarzun <oyarzun@gmail.com>
parents: 7653
diff changeset
217 regardless of whether the Kallithea web process is actually running. Hence,
e4f27ab7cbea ssh: add documentation of SSH support
Christian Oyarzun <oyarzun@gmail.com>
parents: 7653
diff changeset
218 if you want to perform repository or server maintenance and want to fully
e4f27ab7cbea ssh: add documentation of SSH support
Christian Oyarzun <oyarzun@gmail.com>
parents: 7653
diff changeset
219 disable all access to the repositories, disable SSH access by setting
e4f27ab7cbea ssh: add documentation of SSH support
Christian Oyarzun <oyarzun@gmail.com>
parents: 7653
diff changeset
220 ``ssh_enabled = false`` in the correct ``.ini`` file (i.e. the ``.ini`` file
e4f27ab7cbea ssh: add documentation of SSH support
Christian Oyarzun <oyarzun@gmail.com>
parents: 7653
diff changeset
221 specified in the ``authorized_keys`` file.)
912
8378122aa408 docs: changelog + setup update
Marcin Kuzminski <marcin@python-works.com>
parents: 894
diff changeset
222
7783
e4f27ab7cbea ssh: add documentation of SSH support
Christian Oyarzun <oyarzun@gmail.com>
parents: 7653
diff changeset
223 The ``authorized_keys`` file can be updated manually with ``kallithea-cli
e4f27ab7cbea ssh: add documentation of SSH support
Christian Oyarzun <oyarzun@gmail.com>
parents: 7653
diff changeset
224 ssh-update-authorized-keys -c my.ini``. This command is not needed in normal
e4f27ab7cbea ssh: add documentation of SSH support
Christian Oyarzun <oyarzun@gmail.com>
parents: 7653
diff changeset
225 operation but is for example useful after changing SSH-related settings in the
e4f27ab7cbea ssh: add documentation of SSH support
Christian Oyarzun <oyarzun@gmail.com>
parents: 7653
diff changeset
226 ``.ini`` file or renaming that file. (The path to the ``.ini`` file is used in
e4f27ab7cbea ssh: add documentation of SSH support
Christian Oyarzun <oyarzun@gmail.com>
parents: 7653
diff changeset
227 the generated ``authorized_keys`` file).
3224
8b8edfc25856 whitespace cleanup
Marcin Kuzminski <marcin@python-works.com>
parents: 2916
diff changeset
228
5433
fbbe80e3322b docs: consistent spacing around headings
Mads Kiilerich <madski@unity3d.com>
parents: 5426
diff changeset
229
683
341beaa9edba Implemented whoosh index building as paster command.
Marcin Kuzminski <marcin@python-works.com>
parents: 597
diff changeset
230 Setting up Whoosh full text search
341beaa9edba Implemented whoosh index building as paster command.
Marcin Kuzminski <marcin@python-works.com>
parents: 597
diff changeset
231 ----------------------------------
341beaa9edba Implemented whoosh index building as paster command.
Marcin Kuzminski <marcin@python-works.com>
parents: 597
diff changeset
232
5425
5ae8e644aa88 docs: spelling, grammar, content and typography
Søren Løvborg <sorenl@unity3d.com>
parents: 5413
diff changeset
233 Kallithea provides full text search of repositories using `Whoosh`__.
894
1fed3c9161bb fixes #90 + docs update
Marcin Kuzminski <marcin@python-works.com>
parents: 881
diff changeset
234
7333
99cd328da2a1 remove references to pythonhosted.org (issue #293)
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 6762
diff changeset
235 .. __: https://whoosh.readthedocs.io/en/latest/
683
341beaa9edba Implemented whoosh index building as paster command.
Marcin Kuzminski <marcin@python-works.com>
parents: 597
diff changeset
236
5425
5ae8e644aa88 docs: spelling, grammar, content and typography
Søren Løvborg <sorenl@unity3d.com>
parents: 5413
diff changeset
237 For an incremental index build, run::
707
1105531ae572 docs update, added ldap section, added troubleshooting section
Marcin Kuzminski <marcin@python-works.com>
parents: 683
diff changeset
238
7416
502b9bd0a24d cli: convert 'gearbox make-index' into 'kallithea-cli index-create'
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7414
diff changeset
239 kallithea-cli index-create -c my.ini
683
341beaa9edba Implemented whoosh index building as paster command.
Marcin Kuzminski <marcin@python-works.com>
parents: 597
diff changeset
240
5425
5ae8e644aa88 docs: spelling, grammar, content and typography
Søren Løvborg <sorenl@unity3d.com>
parents: 5413
diff changeset
241 For a full index rebuild, run::
707
1105531ae572 docs update, added ldap section, added troubleshooting section
Marcin Kuzminski <marcin@python-works.com>
parents: 683
diff changeset
242
7416
502b9bd0a24d cli: convert 'gearbox make-index' into 'kallithea-cli index-create'
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7414
diff changeset
243 kallithea-cli index-create -c my.ini --full
572
a60cd29ba7e2 more docs update
Marcin Kuzminski <marcin@python-works.com>
parents: 568
diff changeset
244
5855
1048307eb1f5 spelling: overridden
timeless@gmail.com
parents: 5832
diff changeset
245 The ``--repo-location`` option allows the location of the repositories to be overridden;
5425
5ae8e644aa88 docs: spelling, grammar, content and typography
Søren Løvborg <sorenl@unity3d.com>
parents: 5413
diff changeset
246 usually, the location is retrieved from the Kallithea database.
894
1fed3c9161bb fixes #90 + docs update
Marcin Kuzminski <marcin@python-works.com>
parents: 881
diff changeset
247
5425
5ae8e644aa88 docs: spelling, grammar, content and typography
Søren Løvborg <sorenl@unity3d.com>
parents: 5413
diff changeset
248 The ``--index-only`` option can be used to limit the indexed repositories to a comma-separated list::
3224
8b8edfc25856 whitespace cleanup
Marcin Kuzminski <marcin@python-works.com>
parents: 2916
diff changeset
249
7416
502b9bd0a24d cli: convert 'gearbox make-index' into 'kallithea-cli index-create'
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7414
diff changeset
250 kallithea-cli index-create -c my.ini --index-only=vcs,kallithea
572
a60cd29ba7e2 more docs update
Marcin Kuzminski <marcin@python-works.com>
parents: 568
diff changeset
251
5425
5ae8e644aa88 docs: spelling, grammar, content and typography
Søren Løvborg <sorenl@unity3d.com>
parents: 5413
diff changeset
252 To keep your index up-to-date it is necessary to do periodic index builds;
5ae8e644aa88 docs: spelling, grammar, content and typography
Søren Løvborg <sorenl@unity3d.com>
parents: 5413
diff changeset
253 for this, it is recommended to use a crontab entry. Example::
3224
8b8edfc25856 whitespace cleanup
Marcin Kuzminski <marcin@python-works.com>
parents: 2916
diff changeset
254
7416
502b9bd0a24d cli: convert 'gearbox make-index' into 'kallithea-cli index-create'
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7414
diff changeset
255 0 3 * * * /path/to/virtualenv/bin/kallithea-cli index-create -c /path/to/kallithea/my.ini
3224
8b8edfc25856 whitespace cleanup
Marcin Kuzminski <marcin@python-works.com>
parents: 2916
diff changeset
256
5425
5ae8e644aa88 docs: spelling, grammar, content and typography
Søren Løvborg <sorenl@unity3d.com>
parents: 5413
diff changeset
257 When using incremental mode (the default), Whoosh will check the last
1092
8af52e1224ff merge docs in beta with those corrected by Jason Harris
Marcin Kuzminski <marcin@python-works.com>
parents: 1062
diff changeset
258 modification date of each file and add it to be reindexed if a newer file is
8af52e1224ff merge docs in beta with those corrected by Jason Harris
Marcin Kuzminski <marcin@python-works.com>
parents: 1062
diff changeset
259 available. The indexing daemon checks for any removed files and removes them
8af52e1224ff merge docs in beta with those corrected by Jason Harris
Marcin Kuzminski <marcin@python-works.com>
parents: 1062
diff changeset
260 from index.
683
341beaa9edba Implemented whoosh index building as paster command.
Marcin Kuzminski <marcin@python-works.com>
parents: 597
diff changeset
261
4955
4e6dfdb3fa01 docs: English and consistency corrections
Michael V. DePalatis <mike@depalatis.net>
parents: 4925
diff changeset
262 If you want to rebuild the index from scratch, you can use the ``-f`` flag as above,
5425
5ae8e644aa88 docs: spelling, grammar, content and typography
Søren Løvborg <sorenl@unity3d.com>
parents: 5413
diff changeset
263 or in the admin panel you can check the "build from scratch" checkbox.
572
a60cd29ba7e2 more docs update
Marcin Kuzminski <marcin@python-works.com>
parents: 568
diff changeset
264
5413
22a3fa3c4254 docs: cleanup of casing, markup and spacing of headings
Mads Kiilerich <madski@unity3d.com>
parents: 5412
diff changeset
265
22a3fa3c4254 docs: cleanup of casing, markup and spacing of headings
Mads Kiilerich <madski@unity3d.com>
parents: 5412
diff changeset
266 Integration with issue trackers
1838
2ef309c3175d docs update
Marcin Kuzminski <marcin@python-works.com>
parents: 1745
diff changeset
267 -------------------------------
1657
d2a108366f8f Added documentation for container-based and proxy pass-through authentication
Liad Shani <liadff@gmail.com>
parents: 1559
diff changeset
268
4192
e73a69cb98dc Rename some strings examples and commands in documentation
Bradley M. Kuhn <bkuhn@sfconservancy.org>
parents: 4186
diff changeset
269 Kallithea provides a simple integration with issue trackers. It's possible
5425
5ae8e644aa88 docs: spelling, grammar, content and typography
Søren Løvborg <sorenl@unity3d.com>
parents: 5413
diff changeset
270 to define a regular expression that will match an issue ID in commit messages,
7230
d24051ce961c issues: support generic regex replacements in issue_url and issue_prefix
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7099
diff changeset
271 and have that replaced with a URL to the issue.
d24051ce961c issues: support generic regex replacements in issue_url and issue_prefix
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7099
diff changeset
272
d24051ce961c issues: support generic regex replacements in issue_url and issue_prefix
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7099
diff changeset
273 This is achieved with following three variables in the ini file::
1838
2ef309c3175d docs update
Marcin Kuzminski <marcin@python-works.com>
parents: 1745
diff changeset
274
7230
d24051ce961c issues: support generic regex replacements in issue_url and issue_prefix
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7099
diff changeset
275 issue_pat = #(\d+)
d24051ce961c issues: support generic regex replacements in issue_url and issue_prefix
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7099
diff changeset
276 issue_server_link = https://issues.example.com/{repo}/issue/\1
d24051ce961c issues: support generic regex replacements in issue_url and issue_prefix
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7099
diff changeset
277 issue_sub =
1838
2ef309c3175d docs update
Marcin Kuzminski <marcin@python-works.com>
parents: 1745
diff changeset
278
4955
4e6dfdb3fa01 docs: English and consistency corrections
Michael V. DePalatis <mike@depalatis.net>
parents: 4925
diff changeset
279 ``issue_pat`` is the regular expression describing which strings in
7230
d24051ce961c issues: support generic regex replacements in issue_url and issue_prefix
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7099
diff changeset
280 commit messages will be treated as issue references. The expression can/should
d24051ce961c issues: support generic regex replacements in issue_url and issue_prefix
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7099
diff changeset
281 have one or more parenthesized groups that can later be referred to in
d24051ce961c issues: support generic regex replacements in issue_url and issue_prefix
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7099
diff changeset
282 ``issue_server_link`` and ``issue_sub`` (see below). If you prefer, named groups
d24051ce961c issues: support generic regex replacements in issue_url and issue_prefix
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7099
diff changeset
283 can be used instead of simple parenthesized groups.
4848
570a4e40f0bb docs: improve issue tracker integration docs
Andrew Shadura <andrew@shadura.me>
parents: 4522
diff changeset
284
7230
d24051ce961c issues: support generic regex replacements in issue_url and issue_prefix
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7099
diff changeset
285 If the pattern should only match if it is preceded by whitespace, add the
d24051ce961c issues: support generic regex replacements in issue_url and issue_prefix
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7099
diff changeset
286 following string before the actual pattern: ``(?:^|(?<=\s))``.
d24051ce961c issues: support generic regex replacements in issue_url and issue_prefix
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7099
diff changeset
287 If the pattern should only match if it is followed by whitespace, add the
d24051ce961c issues: support generic regex replacements in issue_url and issue_prefix
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7099
diff changeset
288 following string after the actual pattern: ``(?:$|(?=\s))``.
d24051ce961c issues: support generic regex replacements in issue_url and issue_prefix
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7099
diff changeset
289 These expressions use lookbehind and lookahead assertions of the Python regular
d24051ce961c issues: support generic regex replacements in issue_url and issue_prefix
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7099
diff changeset
290 expression module to avoid the whitespace to be part of the actual pattern,
d24051ce961c issues: support generic regex replacements in issue_url and issue_prefix
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7099
diff changeset
291 otherwise the link text will also contain that whitespace.
3224
8b8edfc25856 whitespace cleanup
Marcin Kuzminski <marcin@python-works.com>
parents: 2916
diff changeset
292
5425
5ae8e644aa88 docs: spelling, grammar, content and typography
Søren Løvborg <sorenl@unity3d.com>
parents: 5413
diff changeset
293 Matched issue references are replaced with the link specified in
7230
d24051ce961c issues: support generic regex replacements in issue_url and issue_prefix
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7099
diff changeset
294 ``issue_server_link``, in which any backreferences are resolved. Backreferences
d24051ce961c issues: support generic regex replacements in issue_url and issue_prefix
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7099
diff changeset
295 can be ``\1``, ``\2``, ... or for named groups ``\g<groupname>``.
d24051ce961c issues: support generic regex replacements in issue_url and issue_prefix
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7099
diff changeset
296 The special token ``{repo}`` is replaced with the full repository path
d24051ce961c issues: support generic regex replacements in issue_url and issue_prefix
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7099
diff changeset
297 (including repository groups), while token ``{repo_name}`` is replaced with the
d24051ce961c issues: support generic regex replacements in issue_url and issue_prefix
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7099
diff changeset
298 repository name (without repository groups).
d24051ce961c issues: support generic regex replacements in issue_url and issue_prefix
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7099
diff changeset
299
d24051ce961c issues: support generic regex replacements in issue_url and issue_prefix
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7099
diff changeset
300 The link text is determined by ``issue_sub``, which can be a string containing
d24051ce961c issues: support generic regex replacements in issue_url and issue_prefix
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7099
diff changeset
301 backreferences to the groups specified in ``issue_pat``. If ``issue_sub`` is
d24051ce961c issues: support generic regex replacements in issue_url and issue_prefix
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7099
diff changeset
302 empty, then the text matched by ``issue_pat`` is used verbatim.
d24051ce961c issues: support generic regex replacements in issue_url and issue_prefix
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7099
diff changeset
303
d24051ce961c issues: support generic regex replacements in issue_url and issue_prefix
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7099
diff changeset
304 The example settings shown above match issues in the format ``#<number>``.
d24051ce961c issues: support generic regex replacements in issue_url and issue_prefix
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7099
diff changeset
305 This will cause the text ``#300`` to be transformed into a link:
5425
5ae8e644aa88 docs: spelling, grammar, content and typography
Søren Løvborg <sorenl@unity3d.com>
parents: 5413
diff changeset
306
5ae8e644aa88 docs: spelling, grammar, content and typography
Søren Løvborg <sorenl@unity3d.com>
parents: 5413
diff changeset
307 .. code-block:: html
3224
8b8edfc25856 whitespace cleanup
Marcin Kuzminski <marcin@python-works.com>
parents: 2916
diff changeset
308
7230
d24051ce961c issues: support generic regex replacements in issue_url and issue_prefix
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7099
diff changeset
309 <a href="https://issues.example.com/example_repo/issue/300">#300</a>
d24051ce961c issues: support generic regex replacements in issue_url and issue_prefix
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7099
diff changeset
310
d24051ce961c issues: support generic regex replacements in issue_url and issue_prefix
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7099
diff changeset
311 The following example transforms a text starting with either of 'pullrequest',
d24051ce961c issues: support generic regex replacements in issue_url and issue_prefix
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7099
diff changeset
312 'pull request' or 'PR', followed by an optional space, then a pound character
d24051ce961c issues: support generic regex replacements in issue_url and issue_prefix
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7099
diff changeset
313 (#) and one or more digits, into a link with the text 'PR #' followed by the
d24051ce961c issues: support generic regex replacements in issue_url and issue_prefix
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7099
diff changeset
314 digits::
d24051ce961c issues: support generic regex replacements in issue_url and issue_prefix
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7099
diff changeset
315
d24051ce961c issues: support generic regex replacements in issue_url and issue_prefix
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7099
diff changeset
316 issue_pat = (pullrequest|pull request|PR) ?#(\d+)
d24051ce961c issues: support generic regex replacements in issue_url and issue_prefix
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7099
diff changeset
317 issue_server_link = https://issues.example.com/\2
d24051ce961c issues: support generic regex replacements in issue_url and issue_prefix
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7099
diff changeset
318 issue_sub = PR #\2
d24051ce961c issues: support generic regex replacements in issue_url and issue_prefix
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7099
diff changeset
319
d24051ce961c issues: support generic regex replacements in issue_url and issue_prefix
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7099
diff changeset
320 The following example demonstrates how to require whitespace before the issue
d24051ce961c issues: support generic regex replacements in issue_url and issue_prefix
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7099
diff changeset
321 reference in order for it to be recognized, such that the text ``issue#123`` will
d24051ce961c issues: support generic regex replacements in issue_url and issue_prefix
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7099
diff changeset
322 not cause a match, but ``issue #123`` will::
d24051ce961c issues: support generic regex replacements in issue_url and issue_prefix
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7099
diff changeset
323
d24051ce961c issues: support generic regex replacements in issue_url and issue_prefix
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7099
diff changeset
324 issue_pat = (?:^|(?<=\s))#(\d+)
d24051ce961c issues: support generic regex replacements in issue_url and issue_prefix
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7099
diff changeset
325 issue_server_link = https://issues.example.com/\1
d24051ce961c issues: support generic regex replacements in issue_url and issue_prefix
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7099
diff changeset
326 issue_sub =
1657
d2a108366f8f Added documentation for container-based and proxy pass-through authentication
Liad Shani <liadff@gmail.com>
parents: 1559
diff changeset
327
4848
570a4e40f0bb docs: improve issue tracker integration docs
Andrew Shadura <andrew@shadura.me>
parents: 4522
diff changeset
328 If needed, more than one pattern can be specified by appending a unique suffix to
7230
d24051ce961c issues: support generic regex replacements in issue_url and issue_prefix
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7099
diff changeset
329 the variables. For example, also demonstrating the use of named groups::
4848
570a4e40f0bb docs: improve issue tracker integration docs
Andrew Shadura <andrew@shadura.me>
parents: 4522
diff changeset
330
7230
d24051ce961c issues: support generic regex replacements in issue_url and issue_prefix
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7099
diff changeset
331 issue_pat_wiki = wiki-(?P<pagename>\S+)
d24051ce961c issues: support generic regex replacements in issue_url and issue_prefix
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7099
diff changeset
332 issue_server_link_wiki = https://wiki.example.com/\g<pagename>
d24051ce961c issues: support generic regex replacements in issue_url and issue_prefix
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7099
diff changeset
333 issue_sub_wiki = WIKI-\g<pagename>
4848
570a4e40f0bb docs: improve issue tracker integration docs
Andrew Shadura <andrew@shadura.me>
parents: 4522
diff changeset
334
570a4e40f0bb docs: improve issue tracker integration docs
Andrew Shadura <andrew@shadura.me>
parents: 4522
diff changeset
335 With these settings, wiki pages can be referenced as wiki-some-id, and every
5425
5ae8e644aa88 docs: spelling, grammar, content and typography
Søren Løvborg <sorenl@unity3d.com>
parents: 5413
diff changeset
336 such reference will be transformed into:
5ae8e644aa88 docs: spelling, grammar, content and typography
Søren Løvborg <sorenl@unity3d.com>
parents: 5413
diff changeset
337
5ae8e644aa88 docs: spelling, grammar, content and typography
Søren Løvborg <sorenl@unity3d.com>
parents: 5413
diff changeset
338 .. code-block:: html
4848
570a4e40f0bb docs: improve issue tracker integration docs
Andrew Shadura <andrew@shadura.me>
parents: 4522
diff changeset
339
5497
12b47803189f cleanup: use example.com for tests and examples
Søren Løvborg <sorenl@unity3d.com>
parents: 5496
diff changeset
340 <a href="https://wiki.example.com/some-id">WIKI-some-id</a>
4848
570a4e40f0bb docs: improve issue tracker integration docs
Andrew Shadura <andrew@shadura.me>
parents: 4522
diff changeset
341
7230
d24051ce961c issues: support generic regex replacements in issue_url and issue_prefix
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7099
diff changeset
342 Refer to the `Python regular expression documentation`_ for more details about
d24051ce961c issues: support generic regex replacements in issue_url and issue_prefix
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7099
diff changeset
343 the supported syntax in ``issue_pat``, ``issue_server_link`` and ``issue_sub``.
d24051ce961c issues: support generic regex replacements in issue_url and issue_prefix
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7099
diff changeset
344
4848
570a4e40f0bb docs: improve issue tracker integration docs
Andrew Shadura <andrew@shadura.me>
parents: 4522
diff changeset
345
1467
da60cdb41969 doc update - hooks
Marcin Kuzminski <marcin@python-works.com>
parents: 1448
diff changeset
346 Hook management
da60cdb41969 doc update - hooks
Marcin Kuzminski <marcin@python-works.com>
parents: 1448
diff changeset
347 ---------------
da60cdb41969 doc update - hooks
Marcin Kuzminski <marcin@python-works.com>
parents: 1448
diff changeset
348
4955
4e6dfdb3fa01 docs: English and consistency corrections
Michael V. DePalatis <mike@depalatis.net>
parents: 4925
diff changeset
349 Hooks can be managed in similar way to that used in ``.hgrc`` files.
5426
66f1b9745905 docs: update menu navigation notation to use *Menu > Menu Item*
Søren Løvborg <sorenl@unity3d.com>
parents: 5425
diff changeset
350 To manage hooks, choose *Admin > Settings > Hooks*.
1467
da60cdb41969 doc update - hooks
Marcin Kuzminski <marcin@python-works.com>
parents: 1448
diff changeset
351
5425
5ae8e644aa88 docs: spelling, grammar, content and typography
Søren Løvborg <sorenl@unity3d.com>
parents: 5413
diff changeset
352 The built-in hooks cannot be modified, though they can be enabled or disabled in the *VCS* section.
5ae8e644aa88 docs: spelling, grammar, content and typography
Søren Løvborg <sorenl@unity3d.com>
parents: 5413
diff changeset
353
5ae8e644aa88 docs: spelling, grammar, content and typography
Søren Løvborg <sorenl@unity3d.com>
parents: 5413
diff changeset
354 To add another custom hook simply fill in the first textbox with
5ae8e644aa88 docs: spelling, grammar, content and typography
Søren Løvborg <sorenl@unity3d.com>
parents: 5413
diff changeset
355 ``<name>.<hook_type>`` and the second with the hook path. Example hooks
4955
4e6dfdb3fa01 docs: English and consistency corrections
Michael V. DePalatis <mike@depalatis.net>
parents: 4925
diff changeset
356 can be found in ``kallithea.lib.hooks``.
1467
da60cdb41969 doc update - hooks
Marcin Kuzminski <marcin@python-works.com>
parents: 1448
diff changeset
357
da60cdb41969 doc update - hooks
Marcin Kuzminski <marcin@python-works.com>
parents: 1448
diff changeset
358
2017
03a549b35c57 updated setup docs about encoding
Marcin Kuzminski <marcin@python-works.com>
parents: 1870
diff changeset
359 Changing default encoding
03a549b35c57 updated setup docs about encoding
Marcin Kuzminski <marcin@python-works.com>
parents: 1870
diff changeset
360 -------------------------
03a549b35c57 updated setup docs about encoding
Marcin Kuzminski <marcin@python-works.com>
parents: 1870
diff changeset
361
4914
95fe05b1e5f8 docs: better capitalisation
Andrew Shadura <andrew@shadura.me>
parents: 4902
diff changeset
362 By default, Kallithea uses UTF-8 encoding.
4955
4e6dfdb3fa01 docs: English and consistency corrections
Michael V. DePalatis <mike@depalatis.net>
parents: 4925
diff changeset
363 This is configurable as ``default_encoding`` in the .ini file.
4902
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4848
diff changeset
364 This affects many parts in Kallithea including user names, filenames, and
4955
4e6dfdb3fa01 docs: English and consistency corrections
Michael V. DePalatis <mike@depalatis.net>
parents: 4925
diff changeset
365 encoding of commit messages. In addition Kallithea can detect if the ``chardet``
4e6dfdb3fa01 docs: English and consistency corrections
Michael V. DePalatis <mike@depalatis.net>
parents: 4925
diff changeset
366 library is installed. If ``chardet`` is detected Kallithea will fallback to it
2017
03a549b35c57 updated setup docs about encoding
Marcin Kuzminski <marcin@python-works.com>
parents: 1870
diff changeset
367 when there are encode/decode errors.
03a549b35c57 updated setup docs about encoding
Marcin Kuzminski <marcin@python-works.com>
parents: 1870
diff changeset
368
7327
9937ae52f167 hg: set encoding to utf-8 by default to always show unicode characters correctly
Mads Kiilerich <mads@kiilerich.com>
parents: 7230
diff changeset
369 The Mercurial encoding is configurable as ``hgencoding``. It is similar to
9937ae52f167 hg: set encoding to utf-8 by default to always show unicode characters correctly
Mads Kiilerich <mads@kiilerich.com>
parents: 7230
diff changeset
370 setting the ``HGENCODING`` environment variable, but will override it.
9937ae52f167 hg: set encoding to utf-8 by default to always show unicode characters correctly
Mads Kiilerich <mads@kiilerich.com>
parents: 7230
diff changeset
371
2017
03a549b35c57 updated setup docs about encoding
Marcin Kuzminski <marcin@python-works.com>
parents: 1870
diff changeset
372
4902
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4848
diff changeset
373 Celery configuration
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4848
diff changeset
374 --------------------
777
aac24db58ce8 fixed cache problem,
Marcin Kuzminski <marcin@python-works.com>
parents: 775
diff changeset
375
4925
56cd202b777e docs: move all instructions on Celery to Setup
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 4915
diff changeset
376 Kallithea can use the distributed task queue system Celery_ to run tasks like
5412
2079e864ce51 spelling: use "email" consistently
Søren Løvborg <sorenl@unity3d.com>
parents: 5077
diff changeset
377 cloning repositories or sending emails.
4925
56cd202b777e docs: move all instructions on Celery to Setup
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 4915
diff changeset
378
56cd202b777e docs: move all instructions on Celery to Setup
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 4915
diff changeset
379 Kallithea will in most setups work perfectly fine out of the box (without
56cd202b777e docs: move all instructions on Celery to Setup
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 4915
diff changeset
380 Celery), executing all tasks in the web server process. Some tasks can however
56cd202b777e docs: move all instructions on Celery to Setup
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 4915
diff changeset
381 take some time to run and it can be better to run such tasks asynchronously in
56cd202b777e docs: move all instructions on Celery to Setup
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 4915
diff changeset
382 a separate process so the web server can focus on serving web requests.
56cd202b777e docs: move all instructions on Celery to Setup
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 4915
diff changeset
383
56cd202b777e docs: move all instructions on Celery to Setup
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 4915
diff changeset
384 For installation and configuration of Celery, see the `Celery documentation`_.
56cd202b777e docs: move all instructions on Celery to Setup
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 4915
diff changeset
385 Note that Celery requires a message broker service like RabbitMQ_ (recommended)
56cd202b777e docs: move all instructions on Celery to Setup
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 4915
diff changeset
386 or Redis_.
777
aac24db58ce8 fixed cache problem,
Marcin Kuzminski <marcin@python-works.com>
parents: 775
diff changeset
387
4925
56cd202b777e docs: move all instructions on Celery to Setup
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 4915
diff changeset
388 The use of Celery is configured in the Kallithea ini configuration file.
56cd202b777e docs: move all instructions on Celery to Setup
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 4915
diff changeset
389 To enable it, simply set::
56cd202b777e docs: move all instructions on Celery to Setup
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 4915
diff changeset
390
4955
4e6dfdb3fa01 docs: English and consistency corrections
Michael V. DePalatis <mike@depalatis.net>
parents: 4925
diff changeset
391 use_celery = true
777
aac24db58ce8 fixed cache problem,
Marcin Kuzminski <marcin@python-works.com>
parents: 775
diff changeset
392
8268
f8f50d3b6512 celery: upgrade to Celery 4
Mads Kiilerich <mads@kiilerich.com>
parents: 8209
diff changeset
393 and add or change the ``celery.*`` configuration variables.
4925
56cd202b777e docs: move all instructions on Celery to Setup
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 4915
diff changeset
394
8268
f8f50d3b6512 celery: upgrade to Celery 4
Mads Kiilerich <mads@kiilerich.com>
parents: 8209
diff changeset
395 Configuration settings are prefixed with 'celery.', so for example setting
f8f50d3b6512 celery: upgrade to Celery 4
Mads Kiilerich <mads@kiilerich.com>
parents: 8209
diff changeset
396 `broker_url` in Celery means setting `celery.broker_url` in the configuration
f8f50d3b6512 celery: upgrade to Celery 4
Mads Kiilerich <mads@kiilerich.com>
parents: 8209
diff changeset
397 file.
4925
56cd202b777e docs: move all instructions on Celery to Setup
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 4915
diff changeset
398
56cd202b777e docs: move all instructions on Celery to Setup
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 4915
diff changeset
399 To start the Celery process, run::
938
442ccfe939d0 fixed changelog, and setup docs. Yeeee a 1000 commit :)
Marcin Kuzminski <marcin@python-works.com>
parents: 929
diff changeset
400
7417
1d539bb18165 cli: convert 'gearbox celeryd' into 'kallithea-cli celery-run'
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7416
diff changeset
401 kallithea-cli celery-run -c my.ini
6554
2c3d30095d5e gearbox: replace paster with something TurboGears2-ish that still works with the Pylons stack
Mads Kiilerich <madski@unity3d.com>
parents: 6457
diff changeset
402
2c3d30095d5e gearbox: replace paster with something TurboGears2-ish that still works with the Pylons stack
Mads Kiilerich <madski@unity3d.com>
parents: 6457
diff changeset
403 Extra options to the Celery worker can be passed after ``--`` - see ``-- -h``
2c3d30095d5e gearbox: replace paster with something TurboGears2-ish that still works with the Pylons stack
Mads Kiilerich <madski@unity3d.com>
parents: 6457
diff changeset
404 for more info.
777
aac24db58ce8 fixed cache problem,
Marcin Kuzminski <marcin@python-works.com>
parents: 775
diff changeset
405
871
7f9e006aa26f docs update for celeryd
Marcin Kuzminski <marcin@python-works.com>
parents: 845
diff changeset
406 .. note::
3224
8b8edfc25856 whitespace cleanup
Marcin Kuzminski <marcin@python-works.com>
parents: 2916
diff changeset
407 Make sure you run this command from the same virtualenv, and with the same
4192
e73a69cb98dc Rename some strings examples and commands in documentation
Bradley M. Kuhn <bkuhn@sfconservancy.org>
parents: 4186
diff changeset
408 user that Kallithea runs.
3224
8b8edfc25856 whitespace cleanup
Marcin Kuzminski <marcin@python-works.com>
parents: 2916
diff changeset
409
5425
5ae8e644aa88 docs: spelling, grammar, content and typography
Søren Løvborg <sorenl@unity3d.com>
parents: 5413
diff changeset
410
1062
053983a464e4 docs and readme update
Marcin Kuzminski <marcin@python-works.com>
parents: 992
diff changeset
411 HTTPS support
053983a464e4 docs and readme update
Marcin Kuzminski <marcin@python-works.com>
parents: 992
diff changeset
412 -------------
053983a464e4 docs and readme update
Marcin Kuzminski <marcin@python-works.com>
parents: 992
diff changeset
413
4448
8e26c46e9abe https: introduce https_fixup config setting to enable the special https hacks
Mads Kiilerich <madski@unity3d.com>
parents: 4192
diff changeset
414 Kallithea will by default generate URLs based on the WSGI environment.
8e26c46e9abe https: introduce https_fixup config setting to enable the special https hacks
Mads Kiilerich <madski@unity3d.com>
parents: 4192
diff changeset
415
8e26c46e9abe https: introduce https_fixup config setting to enable the special https hacks
Mads Kiilerich <madski@unity3d.com>
parents: 4192
diff changeset
416 Alternatively, you can use some special configuration settings to control
8e26c46e9abe https: introduce https_fixup config setting to enable the special https hacks
Mads Kiilerich <madski@unity3d.com>
parents: 4192
diff changeset
417 directly which scheme/protocol Kallithea will use when generating URLs:
1092
8af52e1224ff merge docs in beta with those corrected by Jason Harris
Marcin Kuzminski <marcin@python-works.com>
parents: 1062
diff changeset
418
5425
5ae8e644aa88 docs: spelling, grammar, content and typography
Søren Løvborg <sorenl@unity3d.com>
parents: 5413
diff changeset
419 - With ``https_fixup = true``, the scheme will be taken from the
5ae8e644aa88 docs: spelling, grammar, content and typography
Søren Løvborg <sorenl@unity3d.com>
parents: 5413
diff changeset
420 ``X-Url-Scheme``, ``X-Forwarded-Scheme`` or ``X-Forwarded-Proto`` HTTP header
5ae8e644aa88 docs: spelling, grammar, content and typography
Søren Løvborg <sorenl@unity3d.com>
parents: 5413
diff changeset
421 (default ``http``).
4955
4e6dfdb3fa01 docs: English and consistency corrections
Michael V. DePalatis <mike@depalatis.net>
parents: 4925
diff changeset
422 - With ``force_https = true`` the default will be ``https``.
5425
5ae8e644aa88 docs: spelling, grammar, content and typography
Søren Løvborg <sorenl@unity3d.com>
parents: 5413
diff changeset
423 - With ``use_htsts = true``, Kallithea will set ``Strict-Transport-Security`` when using https.
5ae8e644aa88 docs: spelling, grammar, content and typography
Søren Løvborg <sorenl@unity3d.com>
parents: 5413
diff changeset
424
7340
2898ea3ff76c docs: move authentication info to separate file
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7337
diff changeset
425 .. _nginx_virtual_host:
2898ea3ff76c docs: move authentication info to separate file
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7337
diff changeset
426
871
7f9e006aa26f docs update for celeryd
Marcin Kuzminski <marcin@python-works.com>
parents: 845
diff changeset
427
572
a60cd29ba7e2 more docs update
Marcin Kuzminski <marcin@python-works.com>
parents: 568
diff changeset
428 Nginx virtual host example
a60cd29ba7e2 more docs update
Marcin Kuzminski <marcin@python-works.com>
parents: 568
diff changeset
429 --------------------------
a60cd29ba7e2 more docs update
Marcin Kuzminski <marcin@python-works.com>
parents: 568
diff changeset
430
5425
5ae8e644aa88 docs: spelling, grammar, content and typography
Søren Løvborg <sorenl@unity3d.com>
parents: 5413
diff changeset
431 Sample config for Nginx using proxy:
5ae8e644aa88 docs: spelling, grammar, content and typography
Søren Løvborg <sorenl@unity3d.com>
parents: 5413
diff changeset
432
5ae8e644aa88 docs: spelling, grammar, content and typography
Søren Løvborg <sorenl@unity3d.com>
parents: 5413
diff changeset
433 .. code-block:: nginx
572
a60cd29ba7e2 more docs update
Marcin Kuzminski <marcin@python-works.com>
parents: 568
diff changeset
434
4902
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4848
diff changeset
435 upstream kallithea {
1745
456e1e3ce4eb fixes #305 User guide suggests sub-optimal nginx configuration
Marcin Kuzminski <marcin@python-works.com>
parents: 1657
diff changeset
436 server 127.0.0.1:5000;
456e1e3ce4eb fixes #305 User guide suggests sub-optimal nginx configuration
Marcin Kuzminski <marcin@python-works.com>
parents: 1657
diff changeset
437 # add more instances for load balancing
456e1e3ce4eb fixes #305 User guide suggests sub-optimal nginx configuration
Marcin Kuzminski <marcin@python-works.com>
parents: 1657
diff changeset
438 #server 127.0.0.1:5001;
456e1e3ce4eb fixes #305 User guide suggests sub-optimal nginx configuration
Marcin Kuzminski <marcin@python-works.com>
parents: 1657
diff changeset
439 #server 127.0.0.1:5002;
456e1e3ce4eb fixes #305 User guide suggests sub-optimal nginx configuration
Marcin Kuzminski <marcin@python-works.com>
parents: 1657
diff changeset
440 }
3224
8b8edfc25856 whitespace cleanup
Marcin Kuzminski <marcin@python-works.com>
parents: 2916
diff changeset
441
3850
7a4df261a375 added alias configuration option for gists.
Marcin Kuzminski <marcin@python-works.com>
parents: 3801
diff changeset
442 ## gist alias
7a4df261a375 added alias configuration option for gists.
Marcin Kuzminski <marcin@python-works.com>
parents: 3801
diff changeset
443 server {
7a4df261a375 added alias configuration option for gists.
Marcin Kuzminski <marcin@python-works.com>
parents: 3801
diff changeset
444 listen 443;
5497
12b47803189f cleanup: use example.com for tests and examples
Søren Løvborg <sorenl@unity3d.com>
parents: 5496
diff changeset
445 server_name gist.example.com;
3850
7a4df261a375 added alias configuration option for gists.
Marcin Kuzminski <marcin@python-works.com>
parents: 3801
diff changeset
446 access_log /var/log/nginx/gist.access.log;
7a4df261a375 added alias configuration option for gists.
Marcin Kuzminski <marcin@python-works.com>
parents: 3801
diff changeset
447 error_log /var/log/nginx/gist.error.log;
7a4df261a375 added alias configuration option for gists.
Marcin Kuzminski <marcin@python-works.com>
parents: 3801
diff changeset
448
7a4df261a375 added alias configuration option for gists.
Marcin Kuzminski <marcin@python-works.com>
parents: 3801
diff changeset
449 ssl on;
4182
05cabd91f7c3 Change example URL
Bradley M. Kuhn <bkuhn@sfconservancy.org>
parents: 4180
diff changeset
450 ssl_certificate gist.your.kallithea.server.crt;
05cabd91f7c3 Change example URL
Bradley M. Kuhn <bkuhn@sfconservancy.org>
parents: 4180
diff changeset
451 ssl_certificate_key gist.your.kallithea.server.key;
3850
7a4df261a375 added alias configuration option for gists.
Marcin Kuzminski <marcin@python-works.com>
parents: 3801
diff changeset
452
7a4df261a375 added alias configuration option for gists.
Marcin Kuzminski <marcin@python-works.com>
parents: 3801
diff changeset
453 ssl_session_timeout 5m;
7a4df261a375 added alias configuration option for gists.
Marcin Kuzminski <marcin@python-works.com>
parents: 3801
diff changeset
454
7a4df261a375 added alias configuration option for gists.
Marcin Kuzminski <marcin@python-works.com>
parents: 3801
diff changeset
455 ssl_protocols SSLv3 TLSv1;
7a4df261a375 added alias configuration option for gists.
Marcin Kuzminski <marcin@python-works.com>
parents: 3801
diff changeset
456 ssl_ciphers DHE-RSA-AES256-SHA:DHE-RSA-AES128-SHA:EDH-RSA-DES-CBC3-SHA:AES256-SHA:DES-CBC3-SHA:AES128-SHA:RC4-SHA:RC4-MD5;
7a4df261a375 added alias configuration option for gists.
Marcin Kuzminski <marcin@python-works.com>
parents: 3801
diff changeset
457 ssl_prefer_server_ciphers on;
7a4df261a375 added alias configuration option for gists.
Marcin Kuzminski <marcin@python-works.com>
parents: 3801
diff changeset
458
5497
12b47803189f cleanup: use example.com for tests and examples
Søren Løvborg <sorenl@unity3d.com>
parents: 5496
diff changeset
459 rewrite ^/(.+)$ https://kallithea.example.com/_admin/gists/$1;
12b47803189f cleanup: use example.com for tests and examples
Søren Løvborg <sorenl@unity3d.com>
parents: 5496
diff changeset
460 rewrite (.*) https://kallithea.example.com/_admin/gists;
3850
7a4df261a375 added alias configuration option for gists.
Marcin Kuzminski <marcin@python-works.com>
parents: 3801
diff changeset
461 }
7a4df261a375 added alias configuration option for gists.
Marcin Kuzminski <marcin@python-works.com>
parents: 3801
diff changeset
462
1092
8af52e1224ff merge docs in beta with those corrected by Jason Harris
Marcin Kuzminski <marcin@python-works.com>
parents: 1062
diff changeset
463 server {
3243
c759c0912642 switch to SSL configuration example on nginx
Marcin Kuzminski <marcin@python-works.com>
parents: 3224
diff changeset
464 listen 443;
5497
12b47803189f cleanup: use example.com for tests and examples
Søren Løvborg <sorenl@unity3d.com>
parents: 5496
diff changeset
465 server_name kallithea.example.com
4192
e73a69cb98dc Rename some strings examples and commands in documentation
Bradley M. Kuhn <bkuhn@sfconservancy.org>
parents: 4186
diff changeset
466 access_log /var/log/nginx/kallithea.access.log;
e73a69cb98dc Rename some strings examples and commands in documentation
Bradley M. Kuhn <bkuhn@sfconservancy.org>
parents: 4186
diff changeset
467 error_log /var/log/nginx/kallithea.error.log;
1745
456e1e3ce4eb fixes #305 User guide suggests sub-optimal nginx configuration
Marcin Kuzminski <marcin@python-works.com>
parents: 1657
diff changeset
468
3243
c759c0912642 switch to SSL configuration example on nginx
Marcin Kuzminski <marcin@python-works.com>
parents: 3224
diff changeset
469 ssl on;
4182
05cabd91f7c3 Change example URL
Bradley M. Kuhn <bkuhn@sfconservancy.org>
parents: 4180
diff changeset
470 ssl_certificate your.kallithea.server.crt;
05cabd91f7c3 Change example URL
Bradley M. Kuhn <bkuhn@sfconservancy.org>
parents: 4180
diff changeset
471 ssl_certificate_key your.kallithea.server.key;
3243
c759c0912642 switch to SSL configuration example on nginx
Marcin Kuzminski <marcin@python-works.com>
parents: 3224
diff changeset
472
c759c0912642 switch to SSL configuration example on nginx
Marcin Kuzminski <marcin@python-works.com>
parents: 3224
diff changeset
473 ssl_session_timeout 5m;
c759c0912642 switch to SSL configuration example on nginx
Marcin Kuzminski <marcin@python-works.com>
parents: 3224
diff changeset
474
c759c0912642 switch to SSL configuration example on nginx
Marcin Kuzminski <marcin@python-works.com>
parents: 3224
diff changeset
475 ssl_protocols SSLv3 TLSv1;
c759c0912642 switch to SSL configuration example on nginx
Marcin Kuzminski <marcin@python-works.com>
parents: 3224
diff changeset
476 ssl_ciphers DHE-RSA-AES256-SHA:DHE-RSA-AES128-SHA:EDH-RSA-DES-CBC3-SHA:AES256-SHA:DES-CBC3-SHA:AES128-SHA:RC4-SHA:RC4-MD5;
c759c0912642 switch to SSL configuration example on nginx
Marcin Kuzminski <marcin@python-works.com>
parents: 3224
diff changeset
477 ssl_prefer_server_ciphers on;
c759c0912642 switch to SSL configuration example on nginx
Marcin Kuzminski <marcin@python-works.com>
parents: 3224
diff changeset
478
3850
7a4df261a375 added alias configuration option for gists.
Marcin Kuzminski <marcin@python-works.com>
parents: 3801
diff changeset
479 ## uncomment root directive if you want to serve static files by nginx
7a4df261a375 added alias configuration option for gists.
Marcin Kuzminski <marcin@python-works.com>
parents: 3801
diff changeset
480 ## requires static_files = false in .ini file
5880
61954577a0df docs: mention use of static_files, it's setup and implications
Mads Kiilerich <madski@unity3d.com>
parents: 5855
diff changeset
481 #root /srv/kallithea/kallithea/kallithea/public;
3917
35c0c62583cd Moved proxy include of nginx to place where
Marcin Kuzminski <marcin@python-works.com>
parents: 3852
diff changeset
482 include /etc/nginx/proxy.conf;
1092
8af52e1224ff merge docs in beta with those corrected by Jason Harris
Marcin Kuzminski <marcin@python-works.com>
parents: 1062
diff changeset
483 location / {
4902
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4848
diff changeset
484 try_files $uri @kallithea;
1092
8af52e1224ff merge docs in beta with those corrected by Jason Harris
Marcin Kuzminski <marcin@python-works.com>
parents: 1062
diff changeset
485 }
3224
8b8edfc25856 whitespace cleanup
Marcin Kuzminski <marcin@python-works.com>
parents: 2916
diff changeset
486
4902
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4848
diff changeset
487 location @kallithea {
5496
2b2216e8af36 docs: update example output and example server configs
Søren Løvborg <sorenl@unity3d.com>
parents: 5435
diff changeset
488 proxy_pass http://127.0.0.1:5000;
1745
456e1e3ce4eb fixes #305 User guide suggests sub-optimal nginx configuration
Marcin Kuzminski <marcin@python-works.com>
parents: 1657
diff changeset
489 }
456e1e3ce4eb fixes #305 User guide suggests sub-optimal nginx configuration
Marcin Kuzminski <marcin@python-works.com>
parents: 1657
diff changeset
490
3224
8b8edfc25856 whitespace cleanup
Marcin Kuzminski <marcin@python-works.com>
parents: 2916
diff changeset
491 }
8b8edfc25856 whitespace cleanup
Marcin Kuzminski <marcin@python-works.com>
parents: 2916
diff changeset
492
1092
8af52e1224ff merge docs in beta with those corrected by Jason Harris
Marcin Kuzminski <marcin@python-works.com>
parents: 1062
diff changeset
493 Here's the proxy.conf. It's tuned so it will not timeout on long
8af52e1224ff merge docs in beta with those corrected by Jason Harris
Marcin Kuzminski <marcin@python-works.com>
parents: 1062
diff changeset
494 pushes or large pushes::
3224
8b8edfc25856 whitespace cleanup
Marcin Kuzminski <marcin@python-works.com>
parents: 2916
diff changeset
495
572
a60cd29ba7e2 more docs update
Marcin Kuzminski <marcin@python-works.com>
parents: 568
diff changeset
496 proxy_redirect off;
a60cd29ba7e2 more docs update
Marcin Kuzminski <marcin@python-works.com>
parents: 568
diff changeset
497 proxy_set_header Host $host;
4073
2c82dd8ba318 Added two headers into example nginx proxy conf that allows container auth
Marcin Kuzminski <marcin@python-works.com>
parents: 3960
diff changeset
498 ## needed for container auth
2c82dd8ba318 Added two headers into example nginx proxy conf that allows container auth
Marcin Kuzminski <marcin@python-works.com>
parents: 3960
diff changeset
499 #proxy_set_header REMOTE_USER $remote_user;
2c82dd8ba318 Added two headers into example nginx proxy conf that allows container auth
Marcin Kuzminski <marcin@python-works.com>
parents: 3960
diff changeset
500 #proxy_set_header X-Forwarded-User $remote_user;
1745
456e1e3ce4eb fixes #305 User guide suggests sub-optimal nginx configuration
Marcin Kuzminski <marcin@python-works.com>
parents: 1657
diff changeset
501 proxy_set_header X-Url-Scheme $scheme;
572
a60cd29ba7e2 more docs update
Marcin Kuzminski <marcin@python-works.com>
parents: 568
diff changeset
502 proxy_set_header X-Host $http_host;
a60cd29ba7e2 more docs update
Marcin Kuzminski <marcin@python-works.com>
parents: 568
diff changeset
503 proxy_set_header X-Real-IP $remote_addr;
a60cd29ba7e2 more docs update
Marcin Kuzminski <marcin@python-works.com>
parents: 568
diff changeset
504 proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
a60cd29ba7e2 more docs update
Marcin Kuzminski <marcin@python-works.com>
parents: 568
diff changeset
505 proxy_set_header Proxy-host $proxy_host;
a60cd29ba7e2 more docs update
Marcin Kuzminski <marcin@python-works.com>
parents: 568
diff changeset
506 proxy_buffering off;
1420
a2fe0ac8d007 Updated nginx proxy example to work better with large pushes
Marcin Kuzminski <marcin@python-works.com>
parents: 1408
diff changeset
507 proxy_connect_timeout 7200;
a2fe0ac8d007 Updated nginx proxy example to work better with large pushes
Marcin Kuzminski <marcin@python-works.com>
parents: 1408
diff changeset
508 proxy_send_timeout 7200;
a2fe0ac8d007 Updated nginx proxy example to work better with large pushes
Marcin Kuzminski <marcin@python-works.com>
parents: 1408
diff changeset
509 proxy_read_timeout 7200;
a2fe0ac8d007 Updated nginx proxy example to work better with large pushes
Marcin Kuzminski <marcin@python-works.com>
parents: 1408
diff changeset
510 proxy_buffers 8 32k;
3919
b367b016ee39 Added large_client_header_buffers directive into example nginx
Marcin Kuzminski <marcin@python-works.com>
parents: 3917
diff changeset
511 client_max_body_size 1024m;
b367b016ee39 Added large_client_header_buffers directive into example nginx
Marcin Kuzminski <marcin@python-works.com>
parents: 3917
diff changeset
512 client_body_buffer_size 128k;
b367b016ee39 Added large_client_header_buffers directive into example nginx
Marcin Kuzminski <marcin@python-works.com>
parents: 3917
diff changeset
513 large_client_header_buffers 8 64k;
3224
8b8edfc25856 whitespace cleanup
Marcin Kuzminski <marcin@python-works.com>
parents: 2916
diff changeset
514
7340
2898ea3ff76c docs: move authentication info to separate file
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7337
diff changeset
515 .. _apache_virtual_host_reverse_proxy:
2898ea3ff76c docs: move authentication info to separate file
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7337
diff changeset
516
881
68aaa0aca0d2 Updated docs, added apache proxy example config
Marcin Kuzminski <marcin@python-works.com>
parents: 871
diff changeset
517
1558
662173ba1846 Improvements to mod_wsgi setup documentation.
Augusto Herrmann <augusto.herrmann@planejamento.gov.br>
parents: 1467
diff changeset
518 Apache virtual host reverse proxy example
662173ba1846 Improvements to mod_wsgi setup documentation.
Augusto Herrmann <augusto.herrmann@planejamento.gov.br>
parents: 1467
diff changeset
519 -----------------------------------------
881
68aaa0aca0d2 Updated docs, added apache proxy example config
Marcin Kuzminski <marcin@python-works.com>
parents: 871
diff changeset
520
5425
5ae8e644aa88 docs: spelling, grammar, content and typography
Søren Løvborg <sorenl@unity3d.com>
parents: 5413
diff changeset
521 Here is a sample configuration file for Apache using proxy:
5ae8e644aa88 docs: spelling, grammar, content and typography
Søren Løvborg <sorenl@unity3d.com>
parents: 5413
diff changeset
522
5ae8e644aa88 docs: spelling, grammar, content and typography
Søren Løvborg <sorenl@unity3d.com>
parents: 5413
diff changeset
523 .. code-block:: apache
881
68aaa0aca0d2 Updated docs, added apache proxy example config
Marcin Kuzminski <marcin@python-works.com>
parents: 871
diff changeset
524
929
c44b3c9b9f7f doc fix
Marcin Kuzminski <marcin@python-works.com>
parents: 912
diff changeset
525 <VirtualHost *:80>
5497
12b47803189f cleanup: use example.com for tests and examples
Søren Løvborg <sorenl@unity3d.com>
parents: 5496
diff changeset
526 ServerName kallithea.example.com
3224
8b8edfc25856 whitespace cleanup
Marcin Kuzminski <marcin@python-works.com>
parents: 2916
diff changeset
527
929
c44b3c9b9f7f doc fix
Marcin Kuzminski <marcin@python-works.com>
parents: 912
diff changeset
528 <Proxy *>
5425
5ae8e644aa88 docs: spelling, grammar, content and typography
Søren Løvborg <sorenl@unity3d.com>
parents: 5413
diff changeset
529 # For Apache 2.4 and later:
5ae8e644aa88 docs: spelling, grammar, content and typography
Søren Løvborg <sorenl@unity3d.com>
parents: 5413
diff changeset
530 Require all granted
5ae8e644aa88 docs: spelling, grammar, content and typography
Søren Løvborg <sorenl@unity3d.com>
parents: 5413
diff changeset
531
5ae8e644aa88 docs: spelling, grammar, content and typography
Søren Løvborg <sorenl@unity3d.com>
parents: 5413
diff changeset
532 # For Apache 2.2 and earlier, instead use:
5ae8e644aa88 docs: spelling, grammar, content and typography
Søren Løvborg <sorenl@unity3d.com>
parents: 5413
diff changeset
533 # Order allow,deny
5ae8e644aa88 docs: spelling, grammar, content and typography
Søren Løvborg <sorenl@unity3d.com>
parents: 5413
diff changeset
534 # Allow from all
929
c44b3c9b9f7f doc fix
Marcin Kuzminski <marcin@python-works.com>
parents: 912
diff changeset
535 </Proxy>
3224
8b8edfc25856 whitespace cleanup
Marcin Kuzminski <marcin@python-works.com>
parents: 2916
diff changeset
536
929
c44b3c9b9f7f doc fix
Marcin Kuzminski <marcin@python-works.com>
parents: 912
diff changeset
537 #important !
6339
8845ece50d51 docs: remove some references to Pylons
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 6335
diff changeset
538 #Directive to properly generate url (clone url) for Kallithea
929
c44b3c9b9f7f doc fix
Marcin Kuzminski <marcin@python-works.com>
parents: 912
diff changeset
539 ProxyPreserveHost On
3224
8b8edfc25856 whitespace cleanup
Marcin Kuzminski <marcin@python-works.com>
parents: 2916
diff changeset
540
4192
e73a69cb98dc Rename some strings examples and commands in documentation
Bradley M. Kuhn <bkuhn@sfconservancy.org>
parents: 4186
diff changeset
541 #kallithea instance
929
c44b3c9b9f7f doc fix
Marcin Kuzminski <marcin@python-works.com>
parents: 912
diff changeset
542 ProxyPass / http://127.0.0.1:5000/
c44b3c9b9f7f doc fix
Marcin Kuzminski <marcin@python-works.com>
parents: 912
diff changeset
543 ProxyPassReverse / http://127.0.0.1:5000/
3224
8b8edfc25856 whitespace cleanup
Marcin Kuzminski <marcin@python-works.com>
parents: 2916
diff changeset
544
929
c44b3c9b9f7f doc fix
Marcin Kuzminski <marcin@python-works.com>
parents: 912
diff changeset
545 #to enable https use line below
c44b3c9b9f7f doc fix
Marcin Kuzminski <marcin@python-works.com>
parents: 912
diff changeset
546 #SetEnvIf X-Url-Scheme https HTTPS=1
3224
8b8edfc25856 whitespace cleanup
Marcin Kuzminski <marcin@python-works.com>
parents: 2916
diff changeset
547 </VirtualHost>
881
68aaa0aca0d2 Updated docs, added apache proxy example config
Marcin Kuzminski <marcin@python-works.com>
parents: 871
diff changeset
548
68aaa0aca0d2 Updated docs, added apache proxy example config
Marcin Kuzminski <marcin@python-works.com>
parents: 871
diff changeset
549 Additional tutorial
4915
6892b0515af9 docs: replace a dead link to the pylons cookbook
Andrew Shadura <andrew@shadura.me>
parents: 4914
diff changeset
550 http://pylonsbook.com/en/1.1/deployment.html#using-apache-to-proxy-requests-to-pylons
572
a60cd29ba7e2 more docs update
Marcin Kuzminski <marcin@python-works.com>
parents: 568
diff changeset
551
7340
2898ea3ff76c docs: move authentication info to separate file
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7337
diff changeset
552 .. _apache_subdirectory:
2898ea3ff76c docs: move authentication info to separate file
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7337
diff changeset
553
707
1105531ae572 docs update, added ldap section, added troubleshooting section
Marcin Kuzminski <marcin@python-works.com>
parents: 683
diff changeset
554
1062
053983a464e4 docs and readme update
Marcin Kuzminski <marcin@python-works.com>
parents: 992
diff changeset
555 Apache as subdirectory
053983a464e4 docs and readme update
Marcin Kuzminski <marcin@python-works.com>
parents: 992
diff changeset
556 ----------------------
053983a464e4 docs and readme update
Marcin Kuzminski <marcin@python-works.com>
parents: 992
diff changeset
557
5425
5ae8e644aa88 docs: spelling, grammar, content and typography
Søren Løvborg <sorenl@unity3d.com>
parents: 5413
diff changeset
558 Apache subdirectory part:
5ae8e644aa88 docs: spelling, grammar, content and typography
Søren Løvborg <sorenl@unity3d.com>
parents: 5413
diff changeset
559
5ae8e644aa88 docs: spelling, grammar, content and typography
Søren Løvborg <sorenl@unity3d.com>
parents: 5413
diff changeset
560 .. code-block:: apache
1062
053983a464e4 docs and readme update
Marcin Kuzminski <marcin@python-works.com>
parents: 992
diff changeset
561
6789
4d04ac08fff7 docs: fix some sphinx warnings
Mads Kiilerich <mads@kiilerich.com>
parents: 6732
diff changeset
562 <Location /PREFIX >
4d04ac08fff7 docs: fix some sphinx warnings
Mads Kiilerich <mads@kiilerich.com>
parents: 6732
diff changeset
563 ProxyPass http://127.0.0.1:5000/PREFIX
4d04ac08fff7 docs: fix some sphinx warnings
Mads Kiilerich <mads@kiilerich.com>
parents: 6732
diff changeset
564 ProxyPassReverse http://127.0.0.1:5000/PREFIX
1062
053983a464e4 docs and readme update
Marcin Kuzminski <marcin@python-works.com>
parents: 992
diff changeset
565 SetEnvIf X-Url-Scheme https HTTPS=1
3224
8b8edfc25856 whitespace cleanup
Marcin Kuzminski <marcin@python-works.com>
parents: 2916
diff changeset
566 </Location>
1062
053983a464e4 docs and readme update
Marcin Kuzminski <marcin@python-works.com>
parents: 992
diff changeset
567
1392
00b8fca6886c fixes issue #206
Marcin Kuzminski <marcin@python-works.com>
parents: 1386
diff changeset
568 Besides the regular apache setup you will need to add the following line
4955
4e6dfdb3fa01 docs: English and consistency corrections
Michael V. DePalatis <mike@depalatis.net>
parents: 4925
diff changeset
569 into ``[app:main]`` section of your .ini file::
1062
053983a464e4 docs and readme update
Marcin Kuzminski <marcin@python-works.com>
parents: 992
diff changeset
570
053983a464e4 docs and readme update
Marcin Kuzminski <marcin@python-works.com>
parents: 992
diff changeset
571 filter-with = proxy-prefix
053983a464e4 docs and readme update
Marcin Kuzminski <marcin@python-works.com>
parents: 992
diff changeset
572
053983a464e4 docs and readme update
Marcin Kuzminski <marcin@python-works.com>
parents: 992
diff changeset
573 Add the following at the end of the .ini file::
053983a464e4 docs and readme update
Marcin Kuzminski <marcin@python-works.com>
parents: 992
diff changeset
574
053983a464e4 docs and readme update
Marcin Kuzminski <marcin@python-works.com>
parents: 992
diff changeset
575 [filter:proxy-prefix]
053983a464e4 docs and readme update
Marcin Kuzminski <marcin@python-works.com>
parents: 992
diff changeset
576 use = egg:PasteDeploy#prefix
6789
4d04ac08fff7 docs: fix some sphinx warnings
Mads Kiilerich <mads@kiilerich.com>
parents: 6732
diff changeset
577 prefix = /PREFIX
1062
053983a464e4 docs and readme update
Marcin Kuzminski <marcin@python-works.com>
parents: 992
diff changeset
578
6789
4d04ac08fff7 docs: fix some sphinx warnings
Mads Kiilerich <mads@kiilerich.com>
parents: 6732
diff changeset
579 then change ``PREFIX`` into your chosen prefix
1226
f17fdbe86ab9 update docs for setup
Marcin Kuzminski <marcin@python-works.com>
parents: 1123
diff changeset
580
7340
2898ea3ff76c docs: move authentication info to separate file
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7337
diff changeset
581 .. _apache_mod_wsgi:
1226
f17fdbe86ab9 update docs for setup
Marcin Kuzminski <marcin@python-works.com>
parents: 1123
diff changeset
582
5433
fbbe80e3322b docs: consistent spacing around headings
Mads Kiilerich <madski@unity3d.com>
parents: 5426
diff changeset
583
5425
5ae8e644aa88 docs: spelling, grammar, content and typography
Søren Løvborg <sorenl@unity3d.com>
parents: 5413
diff changeset
584 Apache with mod_wsgi
1386
5a31d387f347 Added example wsgi config into docs
Marcin Kuzminski <marcin@python-works.com>
parents: 1309
diff changeset
585 --------------------
5a31d387f347 Added example wsgi config into docs
Marcin Kuzminski <marcin@python-works.com>
parents: 1309
diff changeset
586
4192
e73a69cb98dc Rename some strings examples and commands in documentation
Bradley M. Kuhn <bkuhn@sfconservancy.org>
parents: 4186
diff changeset
587 Alternatively, Kallithea can be set up with Apache under mod_wsgi. For
1558
662173ba1846 Improvements to mod_wsgi setup documentation.
Augusto Herrmann <augusto.herrmann@planejamento.gov.br>
parents: 1467
diff changeset
588 that, you'll need to:
662173ba1846 Improvements to mod_wsgi setup documentation.
Augusto Herrmann <augusto.herrmann@planejamento.gov.br>
parents: 1467
diff changeset
589
662173ba1846 Improvements to mod_wsgi setup documentation.
Augusto Herrmann <augusto.herrmann@planejamento.gov.br>
parents: 1467
diff changeset
590 - Install mod_wsgi. If using a Debian-based distro, you can install
662173ba1846 Improvements to mod_wsgi setup documentation.
Augusto Herrmann <augusto.herrmann@planejamento.gov.br>
parents: 1467
diff changeset
591 the package libapache2-mod-wsgi::
1559
a9fef2e6c1ff Syntax correction on the recently changed documentation.
Augusto Herrmann <augusto.herrmann@planejamento.gov.br>
parents: 1558
diff changeset
592
1558
662173ba1846 Improvements to mod_wsgi setup documentation.
Augusto Herrmann <augusto.herrmann@planejamento.gov.br>
parents: 1467
diff changeset
593 aptitude install libapache2-mod-wsgi
1559
a9fef2e6c1ff Syntax correction on the recently changed documentation.
Augusto Herrmann <augusto.herrmann@planejamento.gov.br>
parents: 1558
diff changeset
594
1558
662173ba1846 Improvements to mod_wsgi setup documentation.
Augusto Herrmann <augusto.herrmann@planejamento.gov.br>
parents: 1467
diff changeset
595 - Enable mod_wsgi::
1559
a9fef2e6c1ff Syntax correction on the recently changed documentation.
Augusto Herrmann <augusto.herrmann@planejamento.gov.br>
parents: 1558
diff changeset
596
1558
662173ba1846 Improvements to mod_wsgi setup documentation.
Augusto Herrmann <augusto.herrmann@planejamento.gov.br>
parents: 1467
diff changeset
597 a2enmod wsgi
1559
a9fef2e6c1ff Syntax correction on the recently changed documentation.
Augusto Herrmann <augusto.herrmann@planejamento.gov.br>
parents: 1558
diff changeset
598
5789
8c479b274e03 docs: improve mod_wsgi documentation (Issue #203)
Mads Kiilerich <madski@unity3d.com>
parents: 5788
diff changeset
599 - Add global Apache configuration to tell mod_wsgi that Python only will be
8c479b274e03 docs: improve mod_wsgi documentation (Issue #203)
Mads Kiilerich <madski@unity3d.com>
parents: 5788
diff changeset
600 used in the WSGI processes and shouldn't be initialized in the Apache
8c479b274e03 docs: improve mod_wsgi documentation (Issue #203)
Mads Kiilerich <madski@unity3d.com>
parents: 5788
diff changeset
601 processes::
8c479b274e03 docs: improve mod_wsgi documentation (Issue #203)
Mads Kiilerich <madski@unity3d.com>
parents: 5788
diff changeset
602
8c479b274e03 docs: improve mod_wsgi documentation (Issue #203)
Mads Kiilerich <madski@unity3d.com>
parents: 5788
diff changeset
603 WSGIRestrictEmbedded On
8c479b274e03 docs: improve mod_wsgi documentation (Issue #203)
Mads Kiilerich <madski@unity3d.com>
parents: 5788
diff changeset
604
7651
ee37a78c6950 docs: move Apache+mod_wsgi example code to the corresponding bullets
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7497
diff changeset
605 - Create a WSGI dispatch script, like the one below. Make sure you
4955
4e6dfdb3fa01 docs: English and consistency corrections
Michael V. DePalatis <mike@depalatis.net>
parents: 4925
diff changeset
606 check that the paths correctly point to where you installed Kallithea
1558
662173ba1846 Improvements to mod_wsgi setup documentation.
Augusto Herrmann <augusto.herrmann@planejamento.gov.br>
parents: 1467
diff changeset
607 and its Python Virtual Environment.
7651
ee37a78c6950 docs: move Apache+mod_wsgi example code to the corresponding bullets
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7497
diff changeset
608
ee37a78c6950 docs: move Apache+mod_wsgi example code to the corresponding bullets
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7497
diff changeset
609 .. code-block:: python
1558
662173ba1846 Improvements to mod_wsgi setup documentation.
Augusto Herrmann <augusto.herrmann@planejamento.gov.br>
parents: 1467
diff changeset
610
7651
ee37a78c6950 docs: move Apache+mod_wsgi example code to the corresponding bullets
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7497
diff changeset
611 import os
ee37a78c6950 docs: move Apache+mod_wsgi example code to the corresponding bullets
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7497
diff changeset
612 os.environ['PYTHON_EGG_CACHE'] = '/srv/kallithea/.egg-cache'
5425
5ae8e644aa88 docs: spelling, grammar, content and typography
Søren Løvborg <sorenl@unity3d.com>
parents: 5413
diff changeset
613
7651
ee37a78c6950 docs: move Apache+mod_wsgi example code to the corresponding bullets
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7497
diff changeset
614 # sometimes it's needed to set the current dir
ee37a78c6950 docs: move Apache+mod_wsgi example code to the corresponding bullets
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7497
diff changeset
615 os.chdir('/srv/kallithea/')
1558
662173ba1846 Improvements to mod_wsgi setup documentation.
Augusto Herrmann <augusto.herrmann@planejamento.gov.br>
parents: 1467
diff changeset
616
7651
ee37a78c6950 docs: move Apache+mod_wsgi example code to the corresponding bullets
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7497
diff changeset
617 import site
8209
01aca0a4f876 py3: officially support Python 3
Mads Kiilerich <mads@kiilerich.com>
parents: 8193
diff changeset
618 site.addsitedir("/srv/kallithea/venv/lib/python3.7/site-packages")
1386
5a31d387f347 Added example wsgi config into docs
Marcin Kuzminski <marcin@python-works.com>
parents: 1309
diff changeset
619
7651
ee37a78c6950 docs: move Apache+mod_wsgi example code to the corresponding bullets
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7497
diff changeset
620 ini = '/srv/kallithea/my.ini'
ee37a78c6950 docs: move Apache+mod_wsgi example code to the corresponding bullets
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7497
diff changeset
621 from logging.config import fileConfig
8086
488b52cad890 logging: always invoke fileConfig with '__file__' and 'here'
Wolfgang Scherer <Wolfgang.Scherer@gmx.de>
parents: 7936
diff changeset
622 fileConfig(ini, {'__file__': ini, 'here': '/srv/kallithea'})
7651
ee37a78c6950 docs: move Apache+mod_wsgi example code to the corresponding bullets
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7497
diff changeset
623 from paste.deploy import loadapp
ee37a78c6950 docs: move Apache+mod_wsgi example code to the corresponding bullets
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7497
diff changeset
624 application = loadapp('config:' + ini)
5425
5ae8e644aa88 docs: spelling, grammar, content and typography
Søren Løvborg <sorenl@unity3d.com>
parents: 5413
diff changeset
625
7651
ee37a78c6950 docs: move Apache+mod_wsgi example code to the corresponding bullets
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7497
diff changeset
626 Or using proper virtualenv activation:
4902
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4848
diff changeset
627
7651
ee37a78c6950 docs: move Apache+mod_wsgi example code to the corresponding bullets
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7497
diff changeset
628 .. code-block:: python
4902
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4848
diff changeset
629
7651
ee37a78c6950 docs: move Apache+mod_wsgi example code to the corresponding bullets
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7497
diff changeset
630 activate_this = '/srv/kallithea/venv/bin/activate_this.py'
ee37a78c6950 docs: move Apache+mod_wsgi example code to the corresponding bullets
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7497
diff changeset
631 execfile(activate_this, dict(__file__=activate_this))
2800
6540ee9179da updated apache wsgi example ref #535
Marcin Kuzminski <marcin@python-works.com>
parents: 2748
diff changeset
632
7651
ee37a78c6950 docs: move Apache+mod_wsgi example code to the corresponding bullets
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7497
diff changeset
633 import os
ee37a78c6950 docs: move Apache+mod_wsgi example code to the corresponding bullets
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7497
diff changeset
634 os.environ['HOME'] = '/srv/kallithea'
5425
5ae8e644aa88 docs: spelling, grammar, content and typography
Søren Løvborg <sorenl@unity3d.com>
parents: 5413
diff changeset
635
7651
ee37a78c6950 docs: move Apache+mod_wsgi example code to the corresponding bullets
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7497
diff changeset
636 ini = '/srv/kallithea/kallithea.ini'
ee37a78c6950 docs: move Apache+mod_wsgi example code to the corresponding bullets
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7497
diff changeset
637 from logging.config import fileConfig
8086
488b52cad890 logging: always invoke fileConfig with '__file__' and 'here'
Wolfgang Scherer <Wolfgang.Scherer@gmx.de>
parents: 7936
diff changeset
638 fileConfig(ini, {'__file__': ini, 'here': '/srv/kallithea'})
7651
ee37a78c6950 docs: move Apache+mod_wsgi example code to the corresponding bullets
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7497
diff changeset
639 from paste.deploy import loadapp
ee37a78c6950 docs: move Apache+mod_wsgi example code to the corresponding bullets
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7497
diff changeset
640 application = loadapp('config:' + ini)
3224
8b8edfc25856 whitespace cleanup
Marcin Kuzminski <marcin@python-works.com>
parents: 2916
diff changeset
641
7652
759d5143042c docs: tweak documentation of Apache+mod_wsgi further
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7651
diff changeset
642 - Add the necessary ``WSGI*`` directives to the Apache Virtual Host configuration
759d5143042c docs: tweak documentation of Apache+mod_wsgi further
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7651
diff changeset
643 file, like in the example below. Notice that the WSGI dispatch script created
759d5143042c docs: tweak documentation of Apache+mod_wsgi further
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7651
diff changeset
644 above is referred to with the ``WSGIScriptAlias`` directive.
7653
9bae11163c31 docs: outline the challenges of specifying a locale for services (Issue #340)
Mads Kiilerich <mads@kiilerich.com>
parents: 7652
diff changeset
645 The default locale settings Apache provides for web services are often not
9bae11163c31 docs: outline the challenges of specifying a locale for services (Issue #340)
Mads Kiilerich <mads@kiilerich.com>
parents: 7652
diff changeset
646 adequate, with `C` as the default language and `ASCII` as the encoding.
9bae11163c31 docs: outline the challenges of specifying a locale for services (Issue #340)
Mads Kiilerich <mads@kiilerich.com>
parents: 7652
diff changeset
647 Instead, use the ``lang`` parameter of ``WSGIDaemonProcess`` to specify a
9bae11163c31 docs: outline the challenges of specifying a locale for services (Issue #340)
Mads Kiilerich <mads@kiilerich.com>
parents: 7652
diff changeset
648 suitable locale. See also the :ref:`overview` section and the
9bae11163c31 docs: outline the challenges of specifying a locale for services (Issue #340)
Mads Kiilerich <mads@kiilerich.com>
parents: 7652
diff changeset
649 `WSGIDaemonProcess documentation`_.
9bae11163c31 docs: outline the challenges of specifying a locale for services (Issue #340)
Mads Kiilerich <mads@kiilerich.com>
parents: 7652
diff changeset
650
7652
759d5143042c docs: tweak documentation of Apache+mod_wsgi further
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7651
diff changeset
651 Apache will by default run as a special Apache user, on Linux systems
759d5143042c docs: tweak documentation of Apache+mod_wsgi further
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7651
diff changeset
652 usually ``www-data`` or ``apache``. If you need to have the repositories
759d5143042c docs: tweak documentation of Apache+mod_wsgi further
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7651
diff changeset
653 directory owned by a different user, use the user and group options to
759d5143042c docs: tweak documentation of Apache+mod_wsgi further
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7651
diff changeset
654 WSGIDaemonProcess to set the name of the user and group.
759d5143042c docs: tweak documentation of Apache+mod_wsgi further
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7651
diff changeset
655
759d5143042c docs: tweak documentation of Apache+mod_wsgi further
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7651
diff changeset
656 Once again, check that all paths are correctly specified.
1558
662173ba1846 Improvements to mod_wsgi setup documentation.
Augusto Herrmann <augusto.herrmann@planejamento.gov.br>
parents: 1467
diff changeset
657
7651
ee37a78c6950 docs: move Apache+mod_wsgi example code to the corresponding bullets
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7497
diff changeset
658 .. code-block:: apache
3224
8b8edfc25856 whitespace cleanup
Marcin Kuzminski <marcin@python-works.com>
parents: 2916
diff changeset
659
7651
ee37a78c6950 docs: move Apache+mod_wsgi example code to the corresponding bullets
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7497
diff changeset
660 WSGIDaemonProcess kallithea processes=5 threads=1 maximum-requests=100 \
7653
9bae11163c31 docs: outline the challenges of specifying a locale for services (Issue #340)
Mads Kiilerich <mads@kiilerich.com>
parents: 7652
diff changeset
661 python-home=/srv/kallithea/venv lang=C.UTF-8
7651
ee37a78c6950 docs: move Apache+mod_wsgi example code to the corresponding bullets
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7497
diff changeset
662 WSGIProcessGroup kallithea
ee37a78c6950 docs: move Apache+mod_wsgi example code to the corresponding bullets
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7497
diff changeset
663 WSGIScriptAlias / /srv/kallithea/dispatch.wsgi
ee37a78c6950 docs: move Apache+mod_wsgi example code to the corresponding bullets
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7497
diff changeset
664 WSGIPassAuthorization On
4902
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4848
diff changeset
665
7651
ee37a78c6950 docs: move Apache+mod_wsgi example code to the corresponding bullets
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7497
diff changeset
666 Or if using a dispatcher WSGI script with proper virtualenv activation:
5425
5ae8e644aa88 docs: spelling, grammar, content and typography
Søren Løvborg <sorenl@unity3d.com>
parents: 5413
diff changeset
667
7651
ee37a78c6950 docs: move Apache+mod_wsgi example code to the corresponding bullets
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7497
diff changeset
668 .. code-block:: apache
4902
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4848
diff changeset
669
7653
9bae11163c31 docs: outline the challenges of specifying a locale for services (Issue #340)
Mads Kiilerich <mads@kiilerich.com>
parents: 7652
diff changeset
670 WSGIDaemonProcess kallithea processes=5 threads=1 maximum-requests=100 lang=en_US.utf8
7651
ee37a78c6950 docs: move Apache+mod_wsgi example code to the corresponding bullets
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7497
diff changeset
671 WSGIProcessGroup kallithea
ee37a78c6950 docs: move Apache+mod_wsgi example code to the corresponding bullets
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7497
diff changeset
672 WSGIScriptAlias / /srv/kallithea/dispatch.wsgi
ee37a78c6950 docs: move Apache+mod_wsgi example code to the corresponding bullets
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7497
diff changeset
673 WSGIPassAuthorization On
4902
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4848
diff changeset
674
707
1105531ae572 docs update, added ldap section, added troubleshooting section
Marcin Kuzminski <marcin@python-works.com>
parents: 683
diff changeset
675
591
1e2adb37cab6 docs update
Marcin Kuzminski <marcin@python-works.com>
parents: 572
diff changeset
676 Other configuration files
1e2adb37cab6 docs update
Marcin Kuzminski <marcin@python-works.com>
parents: 572
diff changeset
677 -------------------------
1e2adb37cab6 docs update
Marcin Kuzminski <marcin@python-works.com>
parents: 572
diff changeset
678
5425
5ae8e644aa88 docs: spelling, grammar, content and typography
Søren Løvborg <sorenl@unity3d.com>
parents: 5413
diff changeset
679 A number of `example init.d scripts`__ can be found in
5ae8e644aa88 docs: spelling, grammar, content and typography
Søren Løvborg <sorenl@unity3d.com>
parents: 5413
diff changeset
680 the ``init.d`` directory of the Kallithea source.
5ae8e644aa88 docs: spelling, grammar, content and typography
Søren Løvborg <sorenl@unity3d.com>
parents: 5413
diff changeset
681
5ae8e644aa88 docs: spelling, grammar, content and typography
Søren Løvborg <sorenl@unity3d.com>
parents: 5413
diff changeset
682 .. __: https://kallithea-scm.org/repos/kallithea/files/tip/init.d/ .
591
1e2adb37cab6 docs update
Marcin Kuzminski <marcin@python-works.com>
parents: 572
diff changeset
683
5433
fbbe80e3322b docs: consistent spacing around headings
Mads Kiilerich <madski@unity3d.com>
parents: 5426
diff changeset
684
572
a60cd29ba7e2 more docs update
Marcin Kuzminski <marcin@python-works.com>
parents: 568
diff changeset
685 .. _python: http://www.python.org/
7230
d24051ce961c issues: support generic regex replacements in issue_url and issue_prefix
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7099
diff changeset
686 .. _Python regular expression documentation: https://docs.python.org/2/library/re.html
6334
cc21a2b86a30 docs: update links to Mercurial's website and wiki
Anton Shestakov <av6@dwimlabs.net>
parents: 5791
diff changeset
687 .. _Mercurial: https://www.mercurial-scm.org/
4925
56cd202b777e docs: move all instructions on Celery to Setup
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 4915
diff changeset
688 .. _Celery: http://celeryproject.org/
56cd202b777e docs: move all instructions on Celery to Setup
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 4915
diff changeset
689 .. _Celery documentation: http://docs.celeryproject.org/en/latest/getting-started/index.html
56cd202b777e docs: move all instructions on Celery to Setup
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 4915
diff changeset
690 .. _RabbitMQ: http://www.rabbitmq.com/
56cd202b777e docs: move all instructions on Celery to Setup
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 4915
diff changeset
691 .. _Redis: http://redis.io/
1092
8af52e1224ff merge docs in beta with those corrected by Jason Harris
Marcin Kuzminski <marcin@python-works.com>
parents: 1062
diff changeset
692 .. _mercurial-server: http://www.lshift.net/mercurial-server.html
6334
cc21a2b86a30 docs: update links to Mercurial's website and wiki
Anton Shestakov <av6@dwimlabs.net>
parents: 5791
diff changeset
693 .. _PublishingRepositories: https://www.mercurial-scm.org/wiki/PublishingRepositories
7653
9bae11163c31 docs: outline the challenges of specifying a locale for services (Issue #340)
Mads Kiilerich <mads@kiilerich.com>
parents: 7652
diff changeset
694 .. _WSGIDaemonProcess documentation: https://modwsgi.readthedocs.io/en/develop/configuration-directives/WSGIDaemonProcess.html