Show More
@@ -1,212 +1,211 b'' | |||||
1 | ================ |
|
1 | ================ | |
2 | Kallithea README |
|
2 | Kallithea README | |
3 | ================ |
|
3 | ================ | |
4 |
|
4 | |||
5 | About |
|
5 | About | |
6 | ----- |
|
6 | ----- | |
7 |
|
7 | |||
8 | **Kallithea** is a fast and powerful management tool for Mercurial_ and Git_ |
|
8 | **Kallithea** is a fast and powerful management tool for Mercurial_ and Git_ | |
9 | with a built-in push/pull server, full text search and code-review. It works on |
|
9 | with a built-in push/pull server, full text search and code-review. It works on | |
10 | http/https and has a built in permission/authentication system with the ability |
|
10 | http/https and has a built in permission/authentication system with the ability | |
11 | to authenticate via LDAP or ActiveDirectory. Kallithea also provides simple API |
|
11 | to authenticate via LDAP or ActiveDirectory. Kallithea also provides simple API | |
12 | so it's easy to integrate with existing external systems. |
|
12 | so it's easy to integrate with existing external systems. | |
13 |
|
13 | |||
14 | Kallithea is similar in some respects to GitHub_ or Bitbucket_, however |
|
14 | Kallithea is similar in some respects to GitHub_ or Bitbucket_, however | |
15 | Kallithea can be run as standalone hosted application on your own server. It is |
|
15 | Kallithea can be run as standalone hosted application on your own server. It is | |
16 | open-source donationware and focuses more on providing a customised, |
|
16 | open-source donationware and focuses more on providing a customised, | |
17 | self-administered interface for Mercurial_ and Git_ repositories. Kallithea |
|
17 | self-administered interface for Mercurial_ and Git_ repositories. Kallithea | |
18 | works on Unix-like systems and Windows, and is powered by the vcs_ library |
|
18 | works on Unix-like systems and Windows, and is powered by the vcs_ library | |
19 | created by Łukasz Balcerzak and Marcin Kuźmiński to uniformly handle multiple |
|
19 | created by Łukasz Balcerzak and Marcin Kuźmiński to uniformly handle multiple | |
20 | version control systems. |
|
20 | version control systems. | |
21 |
|
21 | |||
22 | Kallithea was forked from RhodeCode in July 2014 and has been heavily modified. |
|
22 | Kallithea was forked from RhodeCode in July 2014 and has been heavily modified. | |
23 |
|
23 | |||
24 | Installation |
|
24 | Installation | |
25 | ------------ |
|
25 | ------------ | |
26 | Kallithea requires Python_ 2.x and it is recommended to install it in a |
|
26 | Kallithea requires Python_ 2.x and it is recommended to install it in a | |
27 | virtualenv_. Official releases of Kallithea can be installed with:: |
|
27 | virtualenv_. Official releases of Kallithea can be installed with:: | |
28 |
|
28 | |||
29 | pip install kallithea |
|
29 | pip install kallithea | |
30 |
|
30 | |||
31 | The development repository is kept very stable and used in production by the |
|
31 | The development repository is kept very stable and used in production by the | |
32 | developers - you can do the same. |
|
32 | developers - you can do the same. | |
33 |
|
33 | |||
34 | Please visit https://docs.kallithea-scm.org/en/latest/installation.html for |
|
34 | Please visit https://docs.kallithea-scm.org/en/latest/installation.html for | |
35 | more details. |
|
35 | more details. | |
36 |
|
36 | |||
37 |
|
37 | |||
38 | Source code |
|
38 | Source code | |
39 | ----------- |
|
39 | ----------- | |
40 |
|
40 | |||
41 | The latest sources can be obtained from |
|
41 | The latest sources can be obtained from | |
42 | https://kallithea-scm.org/repos/kallithea. |
|
42 | https://kallithea-scm.org/repos/kallithea. | |
43 |
|
43 | |||
44 | The issue tracker and a repository mirror can be found at Bitbucket_ on |
|
44 | The issue tracker and a repository mirror can be found at Bitbucket_ on | |
45 | https://bitbucket.org/conservancy/kallithea. |
|
45 | https://bitbucket.org/conservancy/kallithea. | |
46 |
|
46 | |||
47 |
|
47 | |||
48 |
|
48 | Kallithea features | ||
49 | Kallithea Features |
|
|||
50 | ------------------ |
|
49 | ------------------ | |
51 |
|
50 | |||
52 | - Has its own middleware to handle Mercurial_ and Git_ protocol requests. Each |
|
51 | - Has its own middleware to handle Mercurial_ and Git_ protocol requests. Each | |
53 | request is authenticated and logged together with IP address. |
|
52 | request is authenticated and logged together with IP address. | |
54 | - Built for speed and performance. You can make multiple pulls/pushes |
|
53 | - Built for speed and performance. You can make multiple pulls/pushes | |
55 | simultaneously. Proven to work with thousands of repositories and users. |
|
54 | simultaneously. Proven to work with thousands of repositories and users. | |
56 | - Supports http/https, LDAP, AD, proxy-pass authentication. |
|
55 | - Supports http/https, LDAP, AD, proxy-pass authentication. | |
57 | - Full permissions (private/read/write/admin) together with IP restrictions for |
|
56 | - Full permissions (private/read/write/admin) together with IP restrictions for | |
58 | each repository, additional explicit forking, repositories group and |
|
57 | each repository, additional explicit forking, repositories group and | |
59 | repository creation permissions. |
|
58 | repository creation permissions. | |
60 | - User groups for easier permission management. |
|
59 | - User groups for easier permission management. | |
61 | - Repository groups let you group repos and manage them easier. They come with |
|
60 | - Repository groups let you group repos and manage them easier. They come with | |
62 | permission delegation features, so you can delegate groups management. |
|
61 | permission delegation features, so you can delegate groups management. | |
63 | - Users can fork other users repos, and compare them at any time. |
|
62 | - Users can fork other users repos, and compare them at any time. | |
64 | - Built-in versioned paste functionality (Gist) for sharing code snippets. |
|
63 | - Built-in versioned paste functionality (Gist) for sharing code snippets. | |
65 | - Integrates easily with other systems, with custom created mappers you can |
|
64 | - Integrates easily with other systems, with custom created mappers you can | |
66 | connect it to almost any issue tracker, and with a JSON-RPC API you can make |
|
65 | connect it to almost any issue tracker, and with a JSON-RPC API you can make | |
67 | much more. |
|
66 | much more. | |
68 | - Built-in commit API lets you add, edit and commit files right from Kallithea |
|
67 | - Built-in commit API lets you add, edit and commit files right from Kallithea | |
69 | web interface using simple editor or upload binary files using simple form. |
|
68 | web interface using simple editor or upload binary files using simple form. | |
70 | - Powerful pull request driven review system with inline commenting, changeset |
|
69 | - Powerful pull request driven review system with inline commenting, changeset | |
71 | statuses, and notification system. |
|
70 | statuses, and notification system. | |
72 | - Importing and syncing repositories from remote locations for Git_, Mercurial_ |
|
71 | - Importing and syncing repositories from remote locations for Git_, Mercurial_ | |
73 | and Subversion. |
|
72 | and Subversion. | |
74 | - Mako templates let you customize the look and feel of the application. |
|
73 | - Mako templates let you customize the look and feel of the application. | |
75 | - Beautiful diffs, annotations and source code browsing all colored by |
|
74 | - Beautiful diffs, annotations and source code browsing all colored by | |
76 | pygments. Raw diffs are made in Git-diff format for both VCS systems, |
|
75 | pygments. Raw diffs are made in Git-diff format for both VCS systems, | |
77 | including Git_ binary-patches. |
|
76 | including Git_ binary-patches. | |
78 | - Mercurial_ and Git_ DAG graphs and Flot-powered graphs with zooming and |
|
77 | - Mercurial_ and Git_ DAG graphs and Flot-powered graphs with zooming and | |
79 | statistics to track activity for repositories. |
|
78 | statistics to track activity for repositories. | |
80 | - Admin interface with user/permission management. Admin activity journal, logs |
|
79 | - Admin interface with user/permission management. Admin activity journal, logs | |
81 | pulls, pushes, forks, registrations and other actions made by all users. |
|
80 | pulls, pushes, forks, registrations and other actions made by all users. | |
82 | - Server side forks. It is possible to fork a project and modify it freely |
|
81 | - Server side forks. It is possible to fork a project and modify it freely | |
83 | without breaking the main repository. |
|
82 | without breaking the main repository. | |
84 | - reST and Markdown README support for repositories. |
|
83 | - reST and Markdown README support for repositories. | |
85 | - Full text search powered by Whoosh on the source files, commit messages, and |
|
84 | - Full text search powered by Whoosh on the source files, commit messages, and | |
86 | file names. Built-in indexing daemons, with optional incremental index build |
|
85 | file names. Built-in indexing daemons, with optional incremental index build | |
87 | (no external search servers required all in one application). |
|
86 | (no external search servers required all in one application). | |
88 | - Setup project descriptions/tags and info inside built in DB for easy, |
|
87 | - Setup project descriptions/tags and info inside built in DB for easy, | |
89 | non-filesystem operations. |
|
88 | non-filesystem operations. | |
90 | - Intelligent cache with invalidation after push or project change, provides |
|
89 | - Intelligent cache with invalidation after push or project change, provides | |
91 | high performance and always up to date data. |
|
90 | high performance and always up to date data. | |
92 | - RSS/Atom feeds, Gravatar support, downloadable sources as zip/tar/gz. |
|
91 | - RSS/Atom feeds, Gravatar support, downloadable sources as zip/tar/gz. | |
93 | - Optional async tasks for speed and performance using Celery_. |
|
92 | - Optional async tasks for speed and performance using Celery_. | |
94 | - Backup scripts can do backup of whole app and send it over scp to desired |
|
93 | - Backup scripts can do backup of whole app and send it over scp to desired | |
95 | location. |
|
94 | location. | |
96 | - Based on Pylons, SQLAlchemy, SQLite, Whoosh, vcs. |
|
95 | - Based on Pylons, SQLAlchemy, SQLite, Whoosh, vcs. | |
97 |
|
96 | |||
98 |
|
97 | |||
99 | License |
|
98 | License | |
100 | ------- |
|
99 | ------- | |
101 |
|
100 | |||
102 | **Kallithea** is released under the GPLv3 license. Kallithea is a `Software |
|
101 | **Kallithea** is released under the GPLv3 license. Kallithea is a `Software | |
103 | Freedom Conservancy`_ project and thus controlled by a non-profit organization. |
|
102 | Freedom Conservancy`_ project and thus controlled by a non-profit organization. | |
104 | No commercial entity can take ownership of the project and change the |
|
103 | No commercial entity can take ownership of the project and change the | |
105 | direction. |
|
104 | direction. | |
106 |
|
105 | |||
107 | Kallithea started out as an effort to make sure the existing GPLv3 codebase |
|
106 | Kallithea started out as an effort to make sure the existing GPLv3 codebase | |
108 | would stay available under a legal license. Kallithea thus has to stay GPLv3 |
|
107 | would stay available under a legal license. Kallithea thus has to stay GPLv3 | |
109 | compatible ... but we are also happy it is GPLv3 and happy to keep it that way. |
|
108 | compatible ... but we are also happy it is GPLv3 and happy to keep it that way. | |
110 | A different license (such as AGPL) could perhaps help attract a different |
|
109 | A different license (such as AGPL) could perhaps help attract a different | |
111 | community with a different mix of Free Software people and companies but we are |
|
110 | community with a different mix of Free Software people and companies but we are | |
112 | happy with the current focus. |
|
111 | happy with the current focus. | |
113 |
|
112 | |||
114 |
|
113 | |||
115 | Community |
|
114 | Community | |
116 | --------- |
|
115 | --------- | |
117 |
|
116 | |||
118 | **Kallithea** is maintained by its users who contribute the fixes they would |
|
117 | **Kallithea** is maintained by its users who contribute the fixes they would | |
119 | like to see. |
|
118 | like to see. | |
120 |
|
119 | |||
121 | Get in touch with the rest of the community: |
|
120 | Get in touch with the rest of the community: | |
122 |
|
121 | |||
123 | - Join the mailing list users and developers - see |
|
122 | - Join the mailing list users and developers - see | |
124 | http://lists.sfconservancy.org/mailman/listinfo/kallithea-general. |
|
123 | http://lists.sfconservancy.org/mailman/listinfo/kallithea-general. | |
125 |
|
124 | |||
126 | - Use IRC and join #kallithea on FreeNode (irc.freenode.net) or use |
|
125 | - Use IRC and join #kallithea on FreeNode (irc.freenode.net) or use | |
127 | http://webchat.freenode.net/?channels=kallithea. |
|
126 | http://webchat.freenode.net/?channels=kallithea. | |
128 |
|
127 | |||
129 | - Follow Kallithea on Twitter, **@KallitheaSCM**. |
|
128 | - Follow Kallithea on Twitter, **@KallitheaSCM**. | |
130 |
|
129 | |||
131 | - Issues can be reported at `issue tracker |
|
130 | - Issues can be reported at `issue tracker | |
132 | <https://bitbucket.org/conservancy/kallithea/issues>`_. |
|
131 | <https://bitbucket.org/conservancy/kallithea/issues>`_. | |
133 |
|
132 | |||
134 | .. note:: |
|
133 | .. note:: | |
135 |
|
134 | |||
136 | Please try to read the documentation before posting any issues, |
|
135 | Please try to read the documentation before posting any issues, | |
137 | especially the **troubleshooting section** |
|
136 | especially the **troubleshooting section** | |
138 |
|
137 | |||
139 |
|
138 | |||
140 | Online documentation |
|
139 | Online documentation | |
141 | -------------------- |
|
140 | -------------------- | |
142 |
|
141 | |||
143 | Online documentation for the current version of Kallithea is available at |
|
142 | Online documentation for the current version of Kallithea is available at | |
144 | https://pythonhosted.org/Kallithea/. Documentation for the current development |
|
143 | https://pythonhosted.org/Kallithea/. Documentation for the current development | |
145 | version can be found on https://docs.kallithea-scm.org/. |
|
144 | version can be found on https://docs.kallithea-scm.org/. | |
146 |
|
145 | |||
147 | You can also build the documentation locally: go to ``docs/`` and run:: |
|
146 | You can also build the documentation locally: go to ``docs/`` and run:: | |
148 |
|
147 | |||
149 | make html |
|
148 | make html | |
150 |
|
149 | |||
151 | .. note:: You need to have Sphinx_ installed to build the |
|
150 | .. note:: You need to have Sphinx_ installed to build the | |
152 | documentation. If you don't have Sphinx_ installed you can |
|
151 | documentation. If you don't have Sphinx_ installed you can | |
153 | install it via the command: ``pip install sphinx`` . |
|
152 | install it via the command: ``pip install sphinx`` . | |
154 |
|
153 | |||
155 |
|
154 | |||
156 | Converting from RhodeCode |
|
155 | Converting from RhodeCode | |
157 | ------------------------- |
|
156 | ------------------------- | |
158 |
|
157 | |||
159 | Currently, you have two options for working with an existing RhodeCode |
|
158 | Currently, you have two options for working with an existing RhodeCode | |
160 | database: |
|
159 | database: | |
161 |
|
160 | |||
162 | - keep the database unconverted (intended for testing and evaluation) |
|
161 | - keep the database unconverted (intended for testing and evaluation) | |
163 | - convert the database in a one-time step |
|
162 | - convert the database in a one-time step | |
164 |
|
163 | |||
165 |
Maintaining |
|
164 | Maintaining interoperability | |
166 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
|
165 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
167 |
|
166 | |||
168 | Interoperability with RhodeCode 2.2.X installations is provided so you don't |
|
167 | Interoperability with RhodeCode 2.2.X installations is provided so you don't | |
169 | have to immediately commit to switching to Kallithea. This option will most |
|
168 | have to immediately commit to switching to Kallithea. This option will most | |
170 | likely go away once the two projects have diverged significantly. |
|
169 | likely go away once the two projects have diverged significantly. | |
171 |
|
170 | |||
172 | To run Kallithea on a RhodeCode database, run:: |
|
171 | To run Kallithea on a RhodeCode database, run:: | |
173 |
|
172 | |||
174 | echo "BRAND = 'rhodecode'" > kallithea/brand.py |
|
173 | echo "BRAND = 'rhodecode'" > kallithea/brand.py | |
175 |
|
174 | |||
176 | This location will depend on where you installed Kallithea. If you installed |
|
175 | This location will depend on where you installed Kallithea. If you installed | |
177 | via:: |
|
176 | via:: | |
178 |
|
177 | |||
179 | python setup.py install |
|
178 | python setup.py install | |
180 |
|
179 | |||
181 | then you will find this location at |
|
180 | then you will find this location at | |
182 | ``$VIRTUAL_ENV/lib/python2.7/site-packages/Kallithea-0.1-py2.7.egg/kallithea``. |
|
181 | ``$VIRTUAL_ENV/lib/python2.7/site-packages/Kallithea-0.1-py2.7.egg/kallithea``. | |
183 |
|
182 | |||
184 |
One-time |
|
183 | One-time conversion | |
185 | ~~~~~~~~~~~~~~~~~~~ |
|
184 | ~~~~~~~~~~~~~~~~~~~ | |
186 |
|
185 | |||
187 | Alternatively, if you would like to convert the database for good, you can use |
|
186 | Alternatively, if you would like to convert the database for good, you can use | |
188 | a helper script provided by Kallithea. This script will operate directly on the |
|
187 | a helper script provided by Kallithea. This script will operate directly on the | |
189 | database, using the database string you can find in your ``production.ini`` (or |
|
188 | database, using the database string you can find in your ``production.ini`` (or | |
190 | ``development.ini``) file. For example, if using SQLite:: |
|
189 | ``development.ini``) file. For example, if using SQLite:: | |
191 |
|
190 | |||
192 | cd /path/to/kallithea |
|
191 | cd /path/to/kallithea | |
193 | cp /path/to/rhodecode/rhodecode.db kallithea.db |
|
192 | cp /path/to/rhodecode/rhodecode.db kallithea.db | |
194 | pip install sqlalchemy-migrate |
|
193 | pip install sqlalchemy-migrate | |
195 | python kallithea/bin/rebranddb.py sqlite:///kallithea.db |
|
194 | python kallithea/bin/rebranddb.py sqlite:///kallithea.db | |
196 |
|
195 | |||
197 | .. Note:: |
|
196 | .. Note:: | |
198 |
|
197 | |||
199 | If you started out using the branding interoperability approach mentioned |
|
198 | If you started out using the branding interoperability approach mentioned | |
200 | above, watch out for stray brand.pyc after removing brand.py. |
|
199 | above, watch out for stray brand.pyc after removing brand.py. | |
201 |
|
200 | |||
202 | .. _virtualenv: http://pypi.python.org/pypi/virtualenv |
|
201 | .. _virtualenv: http://pypi.python.org/pypi/virtualenv | |
203 | .. _Python: http://www.python.org/ |
|
202 | .. _Python: http://www.python.org/ | |
204 | .. _Sphinx: http://sphinx.pocoo.org/ |
|
203 | .. _Sphinx: http://sphinx.pocoo.org/ | |
205 | .. _Mercurial: http://mercurial.selenic.com/ |
|
204 | .. _Mercurial: http://mercurial.selenic.com/ | |
206 | .. _Bitbucket: http://bitbucket.org/ |
|
205 | .. _Bitbucket: http://bitbucket.org/ | |
207 | .. _GitHub: http://github.com/ |
|
206 | .. _GitHub: http://github.com/ | |
208 | .. _Subversion: http://subversion.tigris.org/ |
|
207 | .. _Subversion: http://subversion.tigris.org/ | |
209 | .. _Git: http://git-scm.com/ |
|
208 | .. _Git: http://git-scm.com/ | |
210 | .. _Celery: http://celeryproject.org/ |
|
209 | .. _Celery: http://celeryproject.org/ | |
211 | .. _vcs: http://pypi.python.org/pypi/vcs |
|
210 | .. _vcs: http://pypi.python.org/pypi/vcs | |
212 | .. _Software Freedom Conservancy: http://sfconservancy.org/ |
|
211 | .. _Software Freedom Conservancy: http://sfconservancy.org/ |
@@ -1,35 +1,35 b'' | |||||
1 | .. _models: |
|
1 | .. _models: | |
2 |
|
2 | |||
3 | ======================== |
|
3 | ======================== | |
4 |
The :mod:`models` |
|
4 | The :mod:`models` module | |
5 | ======================== |
|
5 | ======================== | |
6 |
|
6 | |||
7 | .. automodule:: kallithea.model |
|
7 | .. automodule:: kallithea.model | |
8 | :members: |
|
8 | :members: | |
9 |
|
9 | |||
10 | .. automodule:: kallithea.model.comment |
|
10 | .. automodule:: kallithea.model.comment | |
11 | :members: |
|
11 | :members: | |
12 |
|
12 | |||
13 | .. automodule:: kallithea.model.notification |
|
13 | .. automodule:: kallithea.model.notification | |
14 | :members: |
|
14 | :members: | |
15 |
|
15 | |||
16 | .. automodule:: kallithea.model.permission |
|
16 | .. automodule:: kallithea.model.permission | |
17 | :members: |
|
17 | :members: | |
18 |
|
18 | |||
19 | .. automodule:: kallithea.model.repo_permission |
|
19 | .. automodule:: kallithea.model.repo_permission | |
20 | :members: |
|
20 | :members: | |
21 |
|
21 | |||
22 | .. automodule:: kallithea.model.repo |
|
22 | .. automodule:: kallithea.model.repo | |
23 | :members: |
|
23 | :members: | |
24 |
|
24 | |||
25 | .. automodule:: kallithea.model.repo_group |
|
25 | .. automodule:: kallithea.model.repo_group | |
26 | :members: |
|
26 | :members: | |
27 |
|
27 | |||
28 | .. automodule:: kallithea.model.scm |
|
28 | .. automodule:: kallithea.model.scm | |
29 | :members: |
|
29 | :members: | |
30 |
|
30 | |||
31 | .. automodule:: kallithea.model.user |
|
31 | .. automodule:: kallithea.model.user | |
32 | :members: |
|
32 | :members: | |
33 |
|
33 | |||
34 | .. automodule:: kallithea.model.user_group |
|
34 | .. automodule:: kallithea.model.user_group | |
35 | :members: |
|
35 | :members: |
@@ -1,78 +1,80 b'' | |||||
1 | .. _index: |
|
1 | .. _index: | |
2 |
|
2 | |||
|
3 | ####################### | |||
3 | Kallithea Documentation |
|
4 | Kallithea Documentation | |
4 | ----------------------- |
|
5 | ####################### | |
|
6 | ||||
5 |
|
7 | |||
6 | **Readme** |
|
8 | **Readme** | |
7 |
|
9 | |||
8 | .. toctree:: |
|
10 | .. toctree:: | |
9 | :maxdepth: 1 |
|
11 | :maxdepth: 1 | |
10 |
|
12 | |||
11 | readme |
|
13 | readme | |
12 |
|
14 | |||
13 | **Installation** |
|
15 | **Installation** | |
14 |
|
16 | |||
15 | .. toctree:: |
|
17 | .. toctree:: | |
16 | :maxdepth: 1 |
|
18 | :maxdepth: 1 | |
17 |
|
19 | |||
18 | overview |
|
20 | overview | |
19 | installation |
|
21 | installation | |
20 | installation_win |
|
22 | installation_win | |
21 | installation_win_old |
|
23 | installation_win_old | |
22 | installation_iis |
|
24 | installation_iis | |
23 | setup |
|
25 | setup | |
24 |
|
26 | |||
25 | **Usage** |
|
27 | **Usage** | |
26 |
|
28 | |||
27 | .. toctree:: |
|
29 | .. toctree:: | |
28 | :maxdepth: 1 |
|
30 | :maxdepth: 1 | |
29 |
|
31 | |||
30 | usage/general |
|
32 | usage/general | |
31 | usage/vcs_support |
|
33 | usage/vcs_support | |
32 | usage/locking |
|
34 | usage/locking | |
33 | usage/statistics |
|
35 | usage/statistics | |
34 |
|
36 | |||
35 |
**Administrator |
|
37 | **Administrator's guide** | |
36 |
|
38 | |||
37 | .. toctree:: |
|
39 | .. toctree:: | |
38 | :maxdepth: 1 |
|
40 | :maxdepth: 1 | |
39 |
|
41 | |||
40 | usage/email |
|
42 | usage/email | |
41 | usage/performance |
|
43 | usage/performance | |
42 | usage/backup |
|
44 | usage/backup | |
43 | usage/debugging |
|
45 | usage/debugging | |
44 | usage/troubleshooting |
|
46 | usage/troubleshooting | |
45 |
|
47 | |||
46 | **Develop** |
|
48 | **Development** | |
47 |
|
49 | |||
48 | .. toctree:: |
|
50 | .. toctree:: | |
49 | :maxdepth: 1 |
|
51 | :maxdepth: 1 | |
50 |
|
52 | |||
51 | contributing |
|
53 | contributing | |
52 | changelog |
|
54 | changelog | |
53 |
|
55 | |||
54 | **API** |
|
56 | **API** | |
55 |
|
57 | |||
56 | .. toctree:: |
|
58 | .. toctree:: | |
57 | :maxdepth: 1 |
|
59 | :maxdepth: 1 | |
58 |
|
60 | |||
59 | api/api |
|
61 | api/api | |
60 | api/models |
|
62 | api/models | |
61 |
|
63 | |||
62 |
|
64 | |||
63 | Other topics |
|
65 | Other topics | |
64 | ------------ |
|
66 | ------------ | |
65 |
|
67 | |||
66 | * :ref:`genindex` |
|
68 | * :ref:`genindex` | |
67 | * :ref:`search` |
|
69 | * :ref:`search` | |
68 |
|
70 | |||
69 | .. _virtualenv: http://pypi.python.org/pypi/virtualenv |
|
71 | .. _virtualenv: http://pypi.python.org/pypi/virtualenv | |
70 | .. _python: http://www.python.org/ |
|
72 | .. _python: http://www.python.org/ | |
71 | .. _django: http://www.djangoproject.com/ |
|
73 | .. _django: http://www.djangoproject.com/ | |
72 | .. _mercurial: http://mercurial.selenic.com/ |
|
74 | .. _mercurial: http://mercurial.selenic.com/ | |
73 | .. _bitbucket: http://bitbucket.org/ |
|
75 | .. _bitbucket: http://bitbucket.org/ | |
74 | .. _subversion: http://subversion.tigris.org/ |
|
76 | .. _subversion: http://subversion.tigris.org/ | |
75 | .. _git: http://git-scm.com/ |
|
77 | .. _git: http://git-scm.com/ | |
76 | .. _celery: http://celeryproject.org/ |
|
78 | .. _celery: http://celeryproject.org/ | |
77 | .. _Sphinx: http://sphinx.pocoo.org/ |
|
79 | .. _Sphinx: http://sphinx.pocoo.org/ | |
78 | .. _vcs: http://pypi.python.org/pypi/vcs |
|
80 | .. _vcs: http://pypi.python.org/pypi/vcs |
@@ -1,203 +1,203 b'' | |||||
1 | .. _installation: |
|
1 | .. _installation: | |
2 |
|
2 | |||
3 | ========================== |
|
3 | ========================== | |
4 | Installation on Unix/Linux |
|
4 | Installation on Unix/Linux | |
5 | ========================== |
|
5 | ========================== | |
6 |
|
6 | |||
7 | Here are more details about 3 ways to install Kallithea: |
|
7 | Here are more details about 3 ways to install Kallithea: | |
8 |
|
8 | |||
9 | - :ref:`installation-source`: The simplest way to keep the installation |
|
9 | - :ref:`installation-source`: The simplest way to keep the installation | |
10 | uptodate and keep track of local customizations is to run directly from |
|
10 | uptodate and keep track of local customizations is to run directly from | |
11 | source in a Kallithea repository clone and use virtualenv. |
|
11 | source in a Kallithea repository clone and use virtualenv. | |
12 |
|
12 | |||
13 | - :ref:`installation-virtualenv`: If you prefer to only use released versions |
|
13 | - :ref:`installation-virtualenv`: If you prefer to only use released versions | |
14 | of Kallithea, the recommended method is to install Kallithea in a virtual |
|
14 | of Kallithea, the recommended method is to install Kallithea in a virtual | |
15 | Python environment using `virtualenv`. The advantages of this method over |
|
15 | Python environment using `virtualenv`. The advantages of this method over | |
16 | direct installation is that Kallithea and its dependencies are completely |
|
16 | direct installation is that Kallithea and its dependencies are completely | |
17 | contained inside the virtualenv (which also means you can have multiple |
|
17 | contained inside the virtualenv (which also means you can have multiple | |
18 | installations side by side or remove it entirely by just removing the |
|
18 | installations side by side or remove it entirely by just removing the | |
19 | virtualenv directory) and does not require root privileges. |
|
19 | virtualenv directory) and does not require root privileges. | |
20 |
|
20 | |||
21 | - :ref:`installation-without-virtualenv`: The alternative method of installing |
|
21 | - :ref:`installation-without-virtualenv`: The alternative method of installing | |
22 | a Kallithea release is using standard pip. The package will be installed in |
|
22 | a Kallithea release is using standard pip. The package will be installed in | |
23 | the same location as all other Python packages you have ever installed. As a |
|
23 | the same location as all other Python packages you have ever installed. As a | |
24 | result, removing it is not as straightforward as with a virtualenv, as you'd |
|
24 | result, removing it is not as straightforward as with a virtualenv, as you'd | |
25 | have to remove its dependencies manually and make sure that they are not |
|
25 | have to remove its dependencies manually and make sure that they are not | |
26 | needed by other packages. |
|
26 | needed by other packages. | |
27 |
|
27 | |||
28 | .. _installation-source: |
|
28 | .. _installation-source: | |
29 |
|
29 | |||
30 | Installation from repository source |
|
30 | Installation from repository source | |
31 | ----------------------------------- |
|
31 | ----------------------------------- | |
32 |
|
32 | |||
33 | To install Kallithea in a virtualenv using the stable branch of the development |
|
33 | To install Kallithea in a virtualenv using the stable branch of the development | |
34 | repository, follow the instructions below:: |
|
34 | repository, follow the instructions below:: | |
35 |
|
35 | |||
36 | hg clone https://kallithea-scm.org/repos/kallithea -u stable |
|
36 | hg clone https://kallithea-scm.org/repos/kallithea -u stable | |
37 | cd kallithea |
|
37 | cd kallithea | |
38 | virtualenv ../kallithea-venv |
|
38 | virtualenv ../kallithea-venv | |
39 | source ../kallithea-venv/bin/activate |
|
39 | source ../kallithea-venv/bin/activate | |
40 | python setup.py develop |
|
40 | python setup.py develop | |
41 | python setup.py compile_catalog # for translation of the UI |
|
41 | python setup.py compile_catalog # for translation of the UI | |
42 |
|
42 | |||
43 | You can now proceed to :ref:`setup`. |
|
43 | You can now proceed to :ref:`setup`. | |
44 |
|
44 | |||
45 | To upgrade, simply update the repository with ``hg pull -u`` and restart the |
|
45 | To upgrade, simply update the repository with ``hg pull -u`` and restart the | |
46 | server. |
|
46 | server. | |
47 |
|
47 | |||
48 | .. _installation-virtualenv: |
|
48 | .. _installation-virtualenv: | |
49 |
|
49 | |||
50 | Installing a released version in a virtualenv |
|
50 | Installing a released version in a virtualenv | |
51 | --------------------------------------------- |
|
51 | --------------------------------------------- | |
52 |
|
52 | |||
53 | It is highly recommended to use a separate virtualenv_ for installing Kallithea. |
|
53 | It is highly recommended to use a separate virtualenv_ for installing Kallithea. | |
54 | This way, all libraries required by Kallithea will be installed separately from your |
|
54 | This way, all libraries required by Kallithea will be installed separately from your | |
55 | main Python installation and other applications and things will be less |
|
55 | main Python installation and other applications and things will be less | |
56 | problematic when upgrading the system or Kallithea. |
|
56 | problematic when upgrading the system or Kallithea. | |
57 | An additional benefit of virtualenv_ is that it doesn't require root privileges. |
|
57 | An additional benefit of virtualenv_ is that it doesn't require root privileges. | |
58 |
|
58 | |||
59 | - Assuming you have installed virtualenv_, create a new virtual environment |
|
59 | - Assuming you have installed virtualenv_, create a new virtual environment | |
60 | for example, in `/srv/kallithea/venv`, using the virtualenv command:: |
|
60 | for example, in `/srv/kallithea/venv`, using the virtualenv command:: | |
61 |
|
61 | |||
62 | virtualenv /srv/kallithea/venv |
|
62 | virtualenv /srv/kallithea/venv | |
63 |
|
63 | |||
64 | - Activate the virtualenv_ in your current shell session by running:: |
|
64 | - Activate the virtualenv_ in your current shell session by running:: | |
65 |
|
65 | |||
66 | source /srv/kallithea/venv/bin/activate |
|
66 | source /srv/kallithea/venv/bin/activate | |
67 |
|
67 | |||
68 | .. note:: You can't use UNIX ``sudo`` to source the ``virtualenv`` script; it |
|
68 | .. note:: You can't use UNIX ``sudo`` to source the ``virtualenv`` script; it | |
69 | will "activate" a shell that terminates immediately. It is also perfectly |
|
69 | will "activate" a shell that terminates immediately. It is also perfectly | |
70 | acceptable (and desirable) to create a virtualenv as a normal user. |
|
70 | acceptable (and desirable) to create a virtualenv as a normal user. | |
71 |
|
71 | |||
72 | - Make a folder for Kallithea data files, and configuration somewhere on the |
|
72 | - Make a folder for Kallithea data files, and configuration somewhere on the | |
73 | filesystem. For example:: |
|
73 | filesystem. For example:: | |
74 |
|
74 | |||
75 | mkdir /srv/kallithea |
|
75 | mkdir /srv/kallithea | |
76 |
|
76 | |||
77 | - Go into the created directory and run this command to install Kallithea:: |
|
77 | - Go into the created directory and run this command to install Kallithea:: | |
78 |
|
78 | |||
79 | pip install kallithea |
|
79 | pip install kallithea | |
80 |
|
80 | |||
81 | Alternatively, download a .tar.gz from http://pypi.python.org/pypi/Kallithea, |
|
81 | Alternatively, download a .tar.gz from http://pypi.python.org/pypi/Kallithea, | |
82 | extract it and run:: |
|
82 | extract it and run:: | |
83 |
|
83 | |||
84 | python setup.py install |
|
84 | python setup.py install | |
85 |
|
85 | |||
86 | - This will install Kallithea together with pylons_ and all other required |
|
86 | - This will install Kallithea together with pylons_ and all other required | |
87 | python libraries into the activated virtualenv. |
|
87 | python libraries into the activated virtualenv. | |
88 |
|
88 | |||
89 | You can now proceed to :ref:`setup`. |
|
89 | You can now proceed to :ref:`setup`. | |
90 |
|
90 | |||
91 | .. _installation-without-virtualenv: |
|
91 | .. _installation-without-virtualenv: | |
92 |
|
92 | |||
93 | Installing a released version without virtualenv |
|
93 | Installing a released version without virtualenv | |
94 | ------------------------------------------------ |
|
94 | ------------------------------------------------ | |
95 |
|
95 | |||
96 | For installation without virtualenv, 'just' use:: |
|
96 | For installation without virtualenv, 'just' use:: | |
97 |
|
97 | |||
98 | pip install kallithea |
|
98 | pip install kallithea | |
99 |
|
99 | |||
100 | Note that this method requires root privileges and will install packages |
|
100 | Note that this method requires root privileges and will install packages | |
101 | globally without using the system's package manager. |
|
101 | globally without using the system's package manager. | |
102 |
|
102 | |||
103 | To install as a regular user in ``~/.local``, you can use:: |
|
103 | To install as a regular user in ``~/.local``, you can use:: | |
104 |
|
104 | |||
105 | pip install --user kallithea |
|
105 | pip install --user kallithea | |
106 |
|
106 | |||
107 | You can now proceed to :ref:`setup`. |
|
107 | You can now proceed to :ref:`setup`. | |
108 |
|
108 | |||
109 | Upgrading Kallithea from Python Package Index (PyPI) |
|
109 | Upgrading Kallithea from Python Package Index (PyPI) | |
110 |
---------------------------------------------------- |
|
110 | ---------------------------------------------------- | |
111 |
|
111 | |||
112 | .. note:: |
|
112 | .. note:: | |
113 | It is strongly recommended that you **always** perform a database and |
|
113 | It is strongly recommended that you **always** perform a database and | |
114 | configuration backup before doing an upgrade. |
|
114 | configuration backup before doing an upgrade. | |
115 |
|
115 | |||
116 | These directions will use '{version}' to note that this is the version of |
|
116 | These directions will use '{version}' to note that this is the version of | |
117 | Kallithea that these files were used with. If backing up your Kallithea |
|
117 | Kallithea that these files were used with. If backing up your Kallithea | |
118 | instance from version 0.1 to 0.2, the ``my.ini`` file could be |
|
118 | instance from version 0.1 to 0.2, the ``my.ini`` file could be | |
119 | backed up to ``my.ini.0-1``. |
|
119 | backed up to ``my.ini.0-1``. | |
120 |
|
120 | |||
121 |
|
121 | |||
122 | If using a SQLite database, stop the Kallithea process/daemon/service, and |
|
122 | If using a SQLite database, stop the Kallithea process/daemon/service, and | |
123 | then make a copy of the database file:: |
|
123 | then make a copy of the database file:: | |
124 |
|
124 | |||
125 | service kallithea stop |
|
125 | service kallithea stop | |
126 | cp kallithea.db kallithea.db.{version} |
|
126 | cp kallithea.db kallithea.db.{version} | |
127 |
|
127 | |||
128 |
|
128 | |||
129 | Back up your configuration file:: |
|
129 | Back up your configuration file:: | |
130 |
|
130 | |||
131 | cp my.ini my.ini.{version} |
|
131 | cp my.ini my.ini.{version} | |
132 |
|
132 | |||
133 |
|
133 | |||
134 | Ensure that you are using the Python virtual environment that you originally |
|
134 | Ensure that you are using the Python virtual environment that you originally | |
135 | installed Kallithea in by running:: |
|
135 | installed Kallithea in by running:: | |
136 |
|
136 | |||
137 | pip freeze |
|
137 | pip freeze | |
138 |
|
138 | |||
139 | This will list all packages installed in the current environment. If |
|
139 | This will list all packages installed in the current environment. If | |
140 | Kallithea isn't listed, activate the correct virtual environment:: |
|
140 | Kallithea isn't listed, activate the correct virtual environment:: | |
141 |
|
141 | |||
142 | source /srv/kallithea/venv/bin/activate |
|
142 | source /srv/kallithea/venv/bin/activate | |
143 |
|
143 | |||
144 |
|
144 | |||
145 | Once you have verified the environment you can upgrade Kallithea with:: |
|
145 | Once you have verified the environment you can upgrade Kallithea with:: | |
146 |
|
146 | |||
147 | pip install --upgrade kallithea |
|
147 | pip install --upgrade kallithea | |
148 |
|
148 | |||
149 |
|
149 | |||
150 | Then run the following command from the installation directory:: |
|
150 | Then run the following command from the installation directory:: | |
151 |
|
151 | |||
152 | paster make-config Kallithea my.ini |
|
152 | paster make-config Kallithea my.ini | |
153 |
|
153 | |||
154 | This will display any changes made by the new version of Kallithea to your |
|
154 | This will display any changes made by the new version of Kallithea to your | |
155 | current configuration. It will try to perform an automerge. It is recommended |
|
155 | current configuration. It will try to perform an automerge. It is recommended | |
156 | that you recheck the content after the automerge. |
|
156 | that you recheck the content after the automerge. | |
157 |
|
157 | |||
158 | .. note:: |
|
158 | .. note:: | |
159 | Please always make sure your .ini files are up to date. Errors can |
|
159 | Please always make sure your .ini files are up to date. Errors can | |
160 | often be caused by missing parameters added in new versions. |
|
160 | often be caused by missing parameters added in new versions. | |
161 |
|
161 | |||
162 |
|
162 | |||
163 | It is also recommended that you rebuild the whoosh index after upgrading since |
|
163 | It is also recommended that you rebuild the whoosh index after upgrading since | |
164 | the new whoosh version could introduce some incompatible index changes. Please |
|
164 | the new whoosh version could introduce some incompatible index changes. Please | |
165 | read the changelog to see if there were any changes to whoosh. |
|
165 | read the changelog to see if there were any changes to whoosh. | |
166 |
|
166 | |||
167 |
|
167 | |||
168 | The final step is to upgrade the database. To do this simply run:: |
|
168 | The final step is to upgrade the database. To do this simply run:: | |
169 |
|
169 | |||
170 | paster upgrade-db my.ini |
|
170 | paster upgrade-db my.ini | |
171 |
|
171 | |||
172 | This will upgrade the schema and update some of the defaults in the database, |
|
172 | This will upgrade the schema and update some of the defaults in the database, | |
173 | and will always recheck the settings of the application, if there are no new |
|
173 | and will always recheck the settings of the application, if there are no new | |
174 | options that need to be set. |
|
174 | options that need to be set. | |
175 |
|
175 | |||
176 |
|
176 | |||
177 | .. note:: |
|
177 | .. note:: | |
178 | The DB schema upgrade library has some limitations and can sometimes fail if you try to |
|
178 | The DB schema upgrade library has some limitations and can sometimes fail if you try to | |
179 | upgrade from older major releases. In such a case simply run upgrades sequentially, e.g., |
|
179 | upgrade from older major releases. In such a case simply run upgrades sequentially, e.g., | |
180 | upgrading from 0.1.X to 0.3.X should be done like this: 0.1.X. > 0.2.X > 0.3.X |
|
180 | upgrading from 0.1.X to 0.3.X should be done like this: 0.1.X. > 0.2.X > 0.3.X | |
181 | You can always specify what version of Kallithea you want to install for example in pip |
|
181 | You can always specify what version of Kallithea you want to install for example in pip | |
182 | `pip install Kallithea==0.2` |
|
182 | `pip install Kallithea==0.2` | |
183 |
|
183 | |||
184 | You may find it helpful to clear out your log file so that new errors are |
|
184 | You may find it helpful to clear out your log file so that new errors are | |
185 | readily apparent:: |
|
185 | readily apparent:: | |
186 |
|
186 | |||
187 | echo > kallithea.log |
|
187 | echo > kallithea.log | |
188 |
|
188 | |||
189 | Once that is complete, you may now start your upgraded Kallithea Instance:: |
|
189 | Once that is complete, you may now start your upgraded Kallithea Instance:: | |
190 |
|
190 | |||
191 | service kallithea start |
|
191 | service kallithea start | |
192 |
|
192 | |||
193 | Or:: |
|
193 | Or:: | |
194 |
|
194 | |||
195 | paster serve /srv/kallithea/my.ini |
|
195 | paster serve /srv/kallithea/my.ini | |
196 |
|
196 | |||
197 | .. note:: |
|
197 | .. note:: | |
198 | If you're using Celery, make sure you restart all instances of it after |
|
198 | If you're using Celery, make sure you restart all instances of it after | |
199 | upgrade. |
|
199 | upgrade. | |
200 |
|
200 | |||
201 |
|
201 | |||
202 | .. _virtualenv: http://pypi.python.org/pypi/virtualenv |
|
202 | .. _virtualenv: http://pypi.python.org/pypi/virtualenv | |
203 | .. _pylons: http://www.pylonsproject.org/ |
|
203 | .. _pylons: http://www.pylonsproject.org/ |
@@ -1,107 +1,108 b'' | |||||
1 | .. _installation_iis: |
|
1 | .. _installation_iis: | |
2 |
|
2 | |||
|
3 | ===================================================================== | |||
3 | Installing Kallithea on Microsoft Internet Information Services (IIS) |
|
4 | Installing Kallithea on Microsoft Internet Information Services (IIS) | |
4 | ===================================================================== |
|
5 | ===================================================================== | |
5 |
|
6 | |||
6 | The following is documented using IIS 7/8 terminology. There should be nothing |
|
7 | The following is documented using IIS 7/8 terminology. There should be nothing | |
7 | preventing you from applying this on IIS 6 well. |
|
8 | preventing you from applying this on IIS 6 well. | |
8 |
|
9 | |||
9 | .. note:: |
|
10 | .. note:: | |
10 |
|
11 | |||
11 | For the best security, it is strongly recommended to only host the site over |
|
12 | For the best security, it is strongly recommended to only host the site over | |
12 | a secure connection, e.g. using TLS. |
|
13 | a secure connection, e.g. using TLS. | |
13 |
|
14 | |||
14 | Prerequisites |
|
15 | Prerequisites | |
15 | ------------- |
|
16 | ------------- | |
16 |
|
17 | |||
17 | Apart from the normal requirements for Kallithea, it is also necessary to get an |
|
18 | Apart from the normal requirements for Kallithea, it is also necessary to get an | |
18 | ISAPI-WSGI bridge module, e.g. isapi-wsgi. |
|
19 | ISAPI-WSGI bridge module, e.g. isapi-wsgi. | |
19 |
|
20 | |||
20 | Installation |
|
21 | Installation | |
21 | ------------ |
|
22 | ------------ | |
22 |
|
23 | |||
23 | The following will assume that your Kallithea is at ``c:\inetpub\kallithea`` and |
|
24 | The following will assume that your Kallithea is at ``c:\inetpub\kallithea`` and | |
24 | will be served from the root of its own website. The changes to serve it in its |
|
25 | will be served from the root of its own website. The changes to serve it in its | |
25 | own virtual folder will be noted where appropriate. |
|
26 | own virtual folder will be noted where appropriate. | |
26 |
|
27 | |||
27 |
Application |
|
28 | Application pool | |
28 | ................ |
|
29 | ................ | |
29 |
|
30 | |||
30 | Make sure that there is a unique application pool for the Kallithea application |
|
31 | Make sure that there is a unique application pool for the Kallithea application | |
31 | with an identity that has read access to the Kallithea distribution. |
|
32 | with an identity that has read access to the Kallithea distribution. | |
32 |
|
33 | |||
33 | The application pool does not need to be able to run any managed code. If you |
|
34 | The application pool does not need to be able to run any managed code. If you | |
34 | are using a 32-bit Python installation, then you must enable 32 bit program in |
|
35 | are using a 32-bit Python installation, then you must enable 32 bit program in | |
35 | the advanced settings for the application pool otherwise Python will not be able |
|
36 | the advanced settings for the application pool otherwise Python will not be able | |
36 | to run on the website and consequently, Kallithea will not be able to run. |
|
37 | to run on the website and consequently, Kallithea will not be able to run. | |
37 |
|
38 | |||
38 | .. note:: |
|
39 | .. note:: | |
39 |
|
40 | |||
40 | The application pool can be the same as an existing application pool as long |
|
41 | The application pool can be the same as an existing application pool as long | |
41 | as the requirements to Kallithea are enabled by the existing application |
|
42 | as the requirements to Kallithea are enabled by the existing application | |
42 | pool. |
|
43 | pool. | |
43 |
|
44 | |||
44 |
ISAPI |
|
45 | ISAPI handler | |
45 | ............. |
|
46 | ............. | |
46 |
|
47 | |||
47 | The ISAPI handler can be generated using:: |
|
48 | The ISAPI handler can be generated using:: | |
48 |
|
49 | |||
49 | paster install-iis my.ini --root=/ |
|
50 | paster install-iis my.ini --root=/ | |
50 |
|
51 | |||
51 | This will generate a ``dispatch.py`` file in the current directory that contains |
|
52 | This will generate a ``dispatch.py`` file in the current directory that contains | |
52 | the necessary components to finalize an installation into IIS. Once this file |
|
53 | the necessary components to finalize an installation into IIS. Once this file | |
53 | has been generated, it is necessary to run the following command due to the way |
|
54 | has been generated, it is necessary to run the following command due to the way | |
54 | that ISAPI-WSGI is made:: |
|
55 | that ISAPI-WSGI is made:: | |
55 |
|
56 | |||
56 | python dispatch.py install |
|
57 | python dispatch.py install | |
57 |
|
58 | |||
58 | This accomplishes two things: generating an ISAPI compliant DLL file, |
|
59 | This accomplishes two things: generating an ISAPI compliant DLL file, | |
59 | ``_dispatch.dll``, and installing a script map handler into IIS for the |
|
60 | ``_dispatch.dll``, and installing a script map handler into IIS for the | |
60 | ``--root`` specified above pointing to ``_dispatch.dll``. |
|
61 | ``--root`` specified above pointing to ``_dispatch.dll``. | |
61 |
|
62 | |||
62 | The ISAPI handler is registered to all file extensions, so it will automatically |
|
63 | The ISAPI handler is registered to all file extensions, so it will automatically | |
63 | be the one handling all requests to the specified root. When the website starts |
|
64 | be the one handling all requests to the specified root. When the website starts | |
64 | the ISAPI handler, it will start a thread pool managed wrapper around the paster |
|
65 | the ISAPI handler, it will start a thread pool managed wrapper around the paster | |
65 | middleware WSGI handler that Kallithea runs within and each HTTP request to the |
|
66 | middleware WSGI handler that Kallithea runs within and each HTTP request to the | |
66 | site will be processed through this logic henceforth. |
|
67 | site will be processed through this logic henceforth. | |
67 |
|
68 | |||
68 | Authentication with Kallithea using IIS authentication modules |
|
69 | Authentication with Kallithea using IIS authentication modules | |
69 | .............................................................. |
|
70 | .............................................................. | |
70 |
|
71 | |||
71 | The recommended way to handle authentication with Kallithea using IIS is to let |
|
72 | The recommended way to handle authentication with Kallithea using IIS is to let | |
72 | IIS handle all the authentication and just pass it to Kallithea. |
|
73 | IIS handle all the authentication and just pass it to Kallithea. | |
73 |
|
74 | |||
74 | To move responsibility into IIS from Kallithea, we need to configure Kallithea |
|
75 | To move responsibility into IIS from Kallithea, we need to configure Kallithea | |
75 | to let external systems handle authentication and then let Kallithea create the |
|
76 | to let external systems handle authentication and then let Kallithea create the | |
76 | user automatically. To do this, access the administration's authentication page |
|
77 | user automatically. To do this, access the administration's authentication page | |
77 | and enable the ``kallithea.lib.auth_modules.auth_container`` plugin. Once it is |
|
78 | and enable the ``kallithea.lib.auth_modules.auth_container`` plugin. Once it is | |
78 | added, enable it with the ``REMOTE_USER`` header and check *Clean username*. |
|
79 | added, enable it with the ``REMOTE_USER`` header and check *Clean username*. | |
79 | Finally, save the changes on this page. |
|
80 | Finally, save the changes on this page. | |
80 |
|
81 | |||
81 | Switch to the administration's permissions page and disable anonymous access, |
|
82 | Switch to the administration's permissions page and disable anonymous access, | |
82 | otherwise Kallithea will not attempt to use the authenticated user name. By |
|
83 | otherwise Kallithea will not attempt to use the authenticated user name. By | |
83 | default, Kallithea will populate the list of users lazily as they log in. Either |
|
84 | default, Kallithea will populate the list of users lazily as they log in. Either | |
84 | disable external auth account activation and ensure that you pre-populate the |
|
85 | disable external auth account activation and ensure that you pre-populate the | |
85 | user database with an external tool, or set it to *Automatic activation of |
|
86 | user database with an external tool, or set it to *Automatic activation of | |
86 | external account*. Finally, save the changes. |
|
87 | external account*. Finally, save the changes. | |
87 |
|
88 | |||
88 | The last necessary step is to enable the relevant authentication in IIS, e.g. |
|
89 | The last necessary step is to enable the relevant authentication in IIS, e.g. | |
89 | Windows authentication. |
|
90 | Windows authentication. | |
90 |
|
91 | |||
91 | Troubleshooting |
|
92 | Troubleshooting | |
92 | --------------- |
|
93 | --------------- | |
93 |
|
94 | |||
94 | Typically, any issues in this setup will either be entirely in IIS or entirely |
|
95 | Typically, any issues in this setup will either be entirely in IIS or entirely | |
95 | in Kallithea (or Kallithea's WSGI/paster middleware). Consequently, two |
|
96 | in Kallithea (or Kallithea's WSGI/paster middleware). Consequently, two | |
96 | different options for finding issues exist: IIS' failed request tracking which |
|
97 | different options for finding issues exist: IIS' failed request tracking which | |
97 | is great at finding issues until they exist inside Kallithea, at which point the |
|
98 | is great at finding issues until they exist inside Kallithea, at which point the | |
98 | ISAPI-WSGI wrapper above uses ``win32traceutil``, which is part of ``pywin32``. |
|
99 | ISAPI-WSGI wrapper above uses ``win32traceutil``, which is part of ``pywin32``. | |
99 |
|
100 | |||
100 | In order to dump output from WSGI using ``win32traceutil`` it is sufficient to |
|
101 | In order to dump output from WSGI using ``win32traceutil`` it is sufficient to | |
101 | type the following in a console window:: |
|
102 | type the following in a console window:: | |
102 |
|
103 | |||
103 | python -m win32traceutil |
|
104 | python -m win32traceutil | |
104 |
|
105 | |||
105 | and any exceptions occurring in the WSGI layer and below (i.e. in the Kallithea |
|
106 | and any exceptions occurring in the WSGI layer and below (i.e. in the Kallithea | |
106 | application itself) that are uncaught, will be printed here complete with stack |
|
107 | application itself) that are uncaught, will be printed here complete with stack | |
107 | traces, making it a lot easier to identify issues. |
|
108 | traces, making it a lot easier to identify issues. |
@@ -1,254 +1,254 b'' | |||||
1 | .. _installation_win: |
|
1 | .. _installation_win: | |
2 |
|
2 | |||
3 |
|
3 | ================================================================ | ||
4 | Installation and upgrade on Windows (7/Server 2008 R2 and newer) |
|
4 | Installation and upgrade on Windows (7/Server 2008 R2 and newer) | |
5 | ================================================================ |
|
5 | ================================================================ | |
6 |
|
6 | |||
7 | First time install |
|
7 | First time install | |
8 | :::::::::::::::::: |
|
8 | :::::::::::::::::: | |
9 |
|
9 | |||
10 | Target OS: Windows 7 and newer or Windows Server 2008 R2 and newer |
|
10 | Target OS: Windows 7 and newer or Windows Server 2008 R2 and newer | |
11 |
|
11 | |||
12 | Tested on Windows 8.1, Windows Server 2008 R2 and Windows Server 2012 |
|
12 | Tested on Windows 8.1, Windows Server 2008 R2 and Windows Server 2012 | |
13 |
|
13 | |||
14 | To install on an older version of Windows, see `<installation_win_old.html>`_ |
|
14 | To install on an older version of Windows, see `<installation_win_old.html>`_ | |
15 |
|
15 | |||
16 |
|
16 | |||
17 | Step 1 - Install Python |
|
17 | Step 1 - Install Python | |
18 | ----------------------- |
|
18 | ----------------------- | |
19 |
|
19 | |||
20 | Install Python 2.x.y (x = 6 or 7). Latest version is recommended. If you need another version, they can run side by side. |
|
20 | Install Python 2.x.y (x = 6 or 7). Latest version is recommended. If you need another version, they can run side by side. | |
21 |
|
21 | |||
22 | .. warning:: Python 3.x is not supported. |
|
22 | .. warning:: Python 3.x is not supported. | |
23 |
|
23 | |||
24 | - Download Python 2.x.y from http://www.python.org/download/ |
|
24 | - Download Python 2.x.y from http://www.python.org/download/ | |
25 | - Choose and click on the version |
|
25 | - Choose and click on the version | |
26 | - Click on "Windows X86-64 Installer" for x64 or "Windows x86 MSI installer" for Win32. |
|
26 | - Click on "Windows X86-64 Installer" for x64 or "Windows x86 MSI installer" for Win32. | |
27 | - Disable UAC or run the installer with admin privileges. If you chose to disable UAC, do not forget to reboot afterwards. |
|
27 | - Disable UAC or run the installer with admin privileges. If you chose to disable UAC, do not forget to reboot afterwards. | |
28 |
|
28 | |||
29 | While writing this guide, the latest version was v2.7.9. |
|
29 | While writing this guide, the latest version was v2.7.9. | |
30 | Remember the specific major and minor versions installed, because they will |
|
30 | Remember the specific major and minor versions installed, because they will | |
31 | be needed in the next step. In this case, it is "2.7". |
|
31 | be needed in the next step. In this case, it is "2.7". | |
32 |
|
32 | |||
33 |
|
33 | |||
34 | Step 2 - Python BIN |
|
34 | Step 2 - Python BIN | |
35 | ------------------- |
|
35 | ------------------- | |
36 |
|
36 | |||
37 | Add Python BIN folder to the path. This can be done manually (editing |
|
37 | Add Python BIN folder to the path. This can be done manually (editing | |
38 | "PATH" environment variable) or by using Windows Support Tools that |
|
38 | "PATH" environment variable) or by using Windows Support Tools that | |
39 | come pre-installed in Windows Vista/7 and later. |
|
39 | come pre-installed in Windows Vista/7 and later. | |
40 |
|
40 | |||
41 | Open a CMD and type:: |
|
41 | Open a CMD and type:: | |
42 |
|
42 | |||
43 | SETX PATH "%PATH%;[your-python-path]" /M |
|
43 | SETX PATH "%PATH%;[your-python-path]" /M | |
44 |
|
44 | |||
45 | Please substitute [your-python-path] with your Python installation |
|
45 | Please substitute [your-python-path] with your Python installation | |
46 | path. Typically this is ``C:\\Python27``. |
|
46 | path. Typically this is ``C:\\Python27``. | |
47 |
|
47 | |||
48 |
|
48 | |||
49 | Step 3 - Install pywin32 extensions |
|
49 | Step 3 - Install pywin32 extensions | |
50 | ----------------------------------- |
|
50 | ----------------------------------- | |
51 |
|
51 | |||
52 | Download pywin32 from: |
|
52 | Download pywin32 from: | |
53 | http://sourceforge.net/projects/pywin32/files/ |
|
53 | http://sourceforge.net/projects/pywin32/files/ | |
54 |
|
54 | |||
55 | - Click on "pywin32" folder |
|
55 | - Click on "pywin32" folder | |
56 | - Click on the first folder (in this case, Build 219, maybe newer when you try) |
|
56 | - Click on the first folder (in this case, Build 219, maybe newer when you try) | |
57 | - Choose the file ending with ".amd64-py2.x.exe" (".win32-py2.x.exe" |
|
57 | - Choose the file ending with ".amd64-py2.x.exe" (".win32-py2.x.exe" | |
58 | for Win32) where x is the minor version of Python you installed. |
|
58 | for Win32) where x is the minor version of Python you installed. | |
59 | When writing this guide, the file was: |
|
59 | When writing this guide, the file was: | |
60 | http://sourceforge.net/projects/pywin32/files/pywin32/Build%20219/pywin32-219.win-amd64-py2.7.exe/download |
|
60 | http://sourceforge.net/projects/pywin32/files/pywin32/Build%20219/pywin32-219.win-amd64-py2.7.exe/download | |
61 | (x64) |
|
61 | (x64) | |
62 | http://sourceforge.net/projects/pywin32/files/pywin32/Build%20219/pywin32-219.win32-py2.7.exe/download |
|
62 | http://sourceforge.net/projects/pywin32/files/pywin32/Build%20219/pywin32-219.win32-py2.7.exe/download | |
63 | (Win32) |
|
63 | (Win32) | |
64 |
|
64 | |||
65 |
|
65 | |||
66 | Step 4 - Install pip |
|
66 | Step 4 - Install pip | |
67 | -------------------- |
|
67 | -------------------- | |
68 |
|
68 | |||
69 | pip is a package management system for Python. You will need it to install Kallithea and its dependencies. |
|
69 | pip is a package management system for Python. You will need it to install Kallithea and its dependencies. | |
70 |
|
70 | |||
71 | If you installed Python 2.7.9+, you already have it (as long as you ran the installer with admin privileges or disabled UAC). |
|
71 | If you installed Python 2.7.9+, you already have it (as long as you ran the installer with admin privileges or disabled UAC). | |
72 |
|
72 | |||
73 | If it was not installed or if you are using Python>=2.6,<2.7.9: |
|
73 | If it was not installed or if you are using Python>=2.6,<2.7.9: | |
74 |
|
74 | |||
75 | - Go to https://bootstrap.pypa.io |
|
75 | - Go to https://bootstrap.pypa.io | |
76 | - Right-click on get-pip.py and choose Saves as... |
|
76 | - Right-click on get-pip.py and choose Saves as... | |
77 | - Run "python get-pip.py" in the folder where you downloaded get-pip.py (may require admin access). |
|
77 | - Run "python get-pip.py" in the folder where you downloaded get-pip.py (may require admin access). | |
78 |
|
78 | |||
79 | .. note:: |
|
79 | .. note:: | |
80 |
|
80 | |||
81 | See http://stackoverflow.com/questions/4750806/how-to-install-pip-on-windows |
|
81 | See http://stackoverflow.com/questions/4750806/how-to-install-pip-on-windows | |
82 | for details and alternative methods. |
|
82 | for details and alternative methods. | |
83 |
|
83 | |||
84 | Note that pip.exe will be placed inside your Python installation's |
|
84 | Note that pip.exe will be placed inside your Python installation's | |
85 | Scripts folder, which is likely not on your path. To correct this, |
|
85 | Scripts folder, which is likely not on your path. To correct this, | |
86 | open a CMD and type:: |
|
86 | open a CMD and type:: | |
87 |
|
87 | |||
88 | SETX PATH "%PATH%;[your-python-path]\Scripts" /M |
|
88 | SETX PATH "%PATH%;[your-python-path]\Scripts" /M | |
89 |
|
89 | |||
90 |
|
90 | |||
91 |
Step 5 - Kallithea |
|
91 | Step 5 - Kallithea folder structure | |
92 | ----------------------------------- |
|
92 | ----------------------------------- | |
93 |
|
93 | |||
94 | Create a Kallithea folder structure. |
|
94 | Create a Kallithea folder structure. | |
95 |
|
95 | |||
96 | This is only an example to install Kallithea. Of course, you can |
|
96 | This is only an example to install Kallithea. Of course, you can | |
97 | change it. However, this guide will follow the proposed structure, so |
|
97 | change it. However, this guide will follow the proposed structure, so | |
98 | please later adapt the paths if you change them. Folders without |
|
98 | please later adapt the paths if you change them. Folders without | |
99 | spaces are recommended. |
|
99 | spaces are recommended. | |
100 |
|
100 | |||
101 | Create the following folder structure:: |
|
101 | Create the following folder structure:: | |
102 |
|
102 | |||
103 | C:\Kallithea |
|
103 | C:\Kallithea | |
104 | C:\Kallithea\Bin |
|
104 | C:\Kallithea\Bin | |
105 | C:\Kallithea\Env |
|
105 | C:\Kallithea\Env | |
106 | C:\Kallithea\Repos |
|
106 | C:\Kallithea\Repos | |
107 |
|
107 | |||
108 |
|
108 | |||
109 | Step 6 - Install virtualenv |
|
109 | Step 6 - Install virtualenv | |
110 | --------------------------- |
|
110 | --------------------------- | |
111 |
|
111 | |||
112 | .. note:: |
|
112 | .. note:: | |
113 | A python virtual environment will allow for isolation between the Python packages of your system and those used for Kallithea. |
|
113 | A python virtual environment will allow for isolation between the Python packages of your system and those used for Kallithea. | |
114 | It is strongly recommended to use it to ensure that Kallithea does not change a dependency that other software uses or vice versa. |
|
114 | It is strongly recommended to use it to ensure that Kallithea does not change a dependency that other software uses or vice versa. | |
115 |
|
115 | |||
116 | In a command prompt type:: |
|
116 | In a command prompt type:: | |
117 |
|
117 | |||
118 | pip install virtualenv |
|
118 | pip install virtualenv | |
119 |
|
119 | |||
120 | Virtualenv will now be inside your Python Scripts path (C:\\Python27\\Scripts or similar). |
|
120 | Virtualenv will now be inside your Python Scripts path (C:\\Python27\\Scripts or similar). | |
121 |
|
121 | |||
122 | To create a virtual environment, run:: |
|
122 | To create a virtual environment, run:: | |
123 |
|
123 | |||
124 | virtualenv C:\Kallithea\Env |
|
124 | virtualenv C:\Kallithea\Env | |
125 |
|
125 | |||
126 |
|
126 | |||
127 | Step 7 - Install Kallithea |
|
127 | Step 7 - Install Kallithea | |
128 | -------------------------- |
|
128 | -------------------------- | |
129 |
|
129 | |||
130 | In order to install Kallithea, you need to be able to run "pip install kallithea". It will use pip to install the Kallithea Python package and its dependencies. |
|
130 | In order to install Kallithea, you need to be able to run "pip install kallithea". It will use pip to install the Kallithea Python package and its dependencies. | |
131 | Some Python packages use managed code and need to be compiled. |
|
131 | Some Python packages use managed code and need to be compiled. | |
132 | This can be done on Linux without any special steps. On Windows, you will need to install Microsoft Visual C++ compiler for Python 2.7. |
|
132 | This can be done on Linux without any special steps. On Windows, you will need to install Microsoft Visual C++ compiler for Python 2.7. | |
133 |
|
133 | |||
134 | Download and install "Microsoft Visual C++ Compiler for Python 2.7" from http://aka.ms/vcpython27 |
|
134 | Download and install "Microsoft Visual C++ Compiler for Python 2.7" from http://aka.ms/vcpython27 | |
135 |
|
135 | |||
136 | .. note:: |
|
136 | .. note:: | |
137 | You can also install the dependencies using already compiled Windows binaries packages. A good source of compiled Python packages is http://www.lfd.uci.edu/~gohlke/pythonlibs/. However, not all of the necessary packages for Kallithea are on this site and some are hard to find, so we will stick with using the compiler. |
|
137 | You can also install the dependencies using already compiled Windows binaries packages. A good source of compiled Python packages is http://www.lfd.uci.edu/~gohlke/pythonlibs/. However, not all of the necessary packages for Kallithea are on this site and some are hard to find, so we will stick with using the compiler. | |
138 |
|
138 | |||
139 | In a command prompt type (adapting paths if necessary):: |
|
139 | In a command prompt type (adapting paths if necessary):: | |
140 |
|
140 | |||
141 | cd C:\Kallithea\Env\Scripts |
|
141 | cd C:\Kallithea\Env\Scripts | |
142 | activate |
|
142 | activate | |
143 |
|
143 | |||
144 | The prompt will change into "(Env) C:\\Kallithea\\Env\\Scripts" or similar |
|
144 | The prompt will change into "(Env) C:\\Kallithea\\Env\\Scripts" or similar | |
145 | (depending of your folder structure). Then type:: |
|
145 | (depending of your folder structure). Then type:: | |
146 |
|
146 | |||
147 | pip install kallithea |
|
147 | pip install kallithea | |
148 |
|
148 | |||
149 | .. note:: This will take some time. Please wait patiently until it is fully |
|
149 | .. note:: This will take some time. Please wait patiently until it is fully | |
150 | complete. Some warnings will appear. Don't worry, they are |
|
150 | complete. Some warnings will appear. Don't worry, they are | |
151 | normal. |
|
151 | normal. | |
152 |
|
152 | |||
153 |
|
153 | |||
154 |
Step 8 - |
|
154 | Step 8 - Install git (optional) | |
155 | ------------------------------- |
|
155 | ------------------------------- | |
156 |
|
156 | |||
157 | Mercurial being a python package, it was installed automatically when doing "pip install kallithea". |
|
157 | Mercurial being a python package, it was installed automatically when doing "pip install kallithea". | |
158 |
|
158 | |||
159 | You need to install git manually if you want Kallithea to be able to host git repositories. |
|
159 | You need to install git manually if you want Kallithea to be able to host git repositories. | |
160 |
|
160 | |||
161 | See http://git-scm.com/book/en/v2/Getting-Started-Installing-Git#Installing-on-Windows for instructions. |
|
161 | See http://git-scm.com/book/en/v2/Getting-Started-Installing-Git#Installing-on-Windows for instructions. | |
162 |
|
162 | |||
163 |
|
163 | |||
164 | Step 9 - Configuring Kallithea |
|
164 | Step 9 - Configuring Kallithea | |
165 | ------------------------------ |
|
165 | ------------------------------ | |
166 |
|
166 | |||
167 | Steps taken from `<setup.html>`_ |
|
167 | Steps taken from `<setup.html>`_ | |
168 |
|
168 | |||
169 | You have to use the same command prompt as in Step 7, so if you closed |
|
169 | You have to use the same command prompt as in Step 7, so if you closed | |
170 | it, reopen it following the same commands (including the "activate" |
|
170 | it, reopen it following the same commands (including the "activate" | |
171 | one). When ready, type:: |
|
171 | one). When ready, type:: | |
172 |
|
172 | |||
173 | cd C:\Kallithea\Bin |
|
173 | cd C:\Kallithea\Bin | |
174 | paster make-config Kallithea production.ini |
|
174 | paster make-config Kallithea production.ini | |
175 |
|
175 | |||
176 | Then you must edit production.ini to fit your needs (IP address, IP |
|
176 | Then you must edit production.ini to fit your needs (IP address, IP | |
177 | port, mail settings, database, etc.). `NotePad++`__ or a similar text |
|
177 | port, mail settings, database, etc.). `NotePad++`__ or a similar text | |
178 | editor is recommended to properly handle the newline character |
|
178 | editor is recommended to properly handle the newline character | |
179 | differences between Unix and Windows. |
|
179 | differences between Unix and Windows. | |
180 |
|
180 | |||
181 | __ http://notepad-plus-plus.org/ |
|
181 | __ http://notepad-plus-plus.org/ | |
182 |
|
182 | |||
183 | For the sake of simplicity, run it with the default settings. After your edits (if any) in the previous command prompt, type:: |
|
183 | For the sake of simplicity, run it with the default settings. After your edits (if any) in the previous command prompt, type:: | |
184 |
|
184 | |||
185 | paster setup-db production.ini |
|
185 | paster setup-db production.ini | |
186 |
|
186 | |||
187 | .. warning:: This time a *new* database will be installed. You must |
|
187 | .. warning:: This time a *new* database will be installed. You must | |
188 | follow a different step to later *upgrade* to a newer |
|
188 | follow a different step to later *upgrade* to a newer | |
189 | Kallithea version) |
|
189 | Kallithea version) | |
190 |
|
190 | |||
191 | The script will ask you for confirmation about creating a new database, answer yes (y) |
|
191 | The script will ask you for confirmation about creating a new database, answer yes (y) | |
192 |
|
192 | |||
193 | The script will ask you for the repository path, answer C:\\Kallithea\\Repos (or similar). |
|
193 | The script will ask you for the repository path, answer C:\\Kallithea\\Repos (or similar). | |
194 |
|
194 | |||
195 | The script will ask you for the admin username and password, answer "admin" + "123456" (or whatever you want) |
|
195 | The script will ask you for the admin username and password, answer "admin" + "123456" (or whatever you want) | |
196 |
|
196 | |||
197 | The script will ask you for admin mail, answer "admin@xxxx.com" (or whatever you want). |
|
197 | The script will ask you for admin mail, answer "admin@xxxx.com" (or whatever you want). | |
198 |
|
198 | |||
199 | If you make a mistake and the script doesn't end, don't worry: start it again. |
|
199 | If you make a mistake and the script doesn't end, don't worry: start it again. | |
200 |
|
200 | |||
201 | If you decided not to install git, you will get errors about it that you can ignore. |
|
201 | If you decided not to install git, you will get errors about it that you can ignore. | |
202 |
|
202 | |||
203 |
|
203 | |||
204 | Step 10 - Running Kallithea |
|
204 | Step 10 - Running Kallithea | |
205 | --------------------------- |
|
205 | --------------------------- | |
206 |
|
206 | |||
207 | In the previous command prompt, being in the C:\\Kallithea\\Bin folder, type:: |
|
207 | In the previous command prompt, being in the C:\\Kallithea\\Bin folder, type:: | |
208 |
|
208 | |||
209 | paster serve production.ini |
|
209 | paster serve production.ini | |
210 |
|
210 | |||
211 | Open your web server, and go to http://127.0.0.1:5000 |
|
211 | Open your web server, and go to http://127.0.0.1:5000 | |
212 |
|
212 | |||
213 | It works!! :-) |
|
213 | It works!! :-) | |
214 |
|
214 | |||
215 | Remark: |
|
215 | Remark: | |
216 | If it does not work the first time, Ctrl-C the CMD process and start it again. Don't forget the "http://" in Internet Explorer. |
|
216 | If it does not work the first time, Ctrl-C the CMD process and start it again. Don't forget the "http://" in Internet Explorer. | |
217 |
|
217 | |||
218 |
|
218 | |||
219 | What this guide does not cover: |
|
219 | What this guide does not cover: | |
220 |
|
220 | |||
221 | - Installing Celery |
|
221 | - Installing Celery | |
222 | - Running Kallithea as a Windows Service. You can investigate here: |
|
222 | - Running Kallithea as a Windows Service. You can investigate here: | |
223 |
|
223 | |||
224 | - http://pypi.python.org/pypi/wsgisvc |
|
224 | - http://pypi.python.org/pypi/wsgisvc | |
225 | - http://ryrobes.com/python/running-python-scripts-as-a-windows-service/ |
|
225 | - http://ryrobes.com/python/running-python-scripts-as-a-windows-service/ | |
226 | - http://wiki.pylonshq.com/display/pylonscookbook/How+to+run+Pylons+as+a+Windows+service |
|
226 | - http://wiki.pylonshq.com/display/pylonscookbook/How+to+run+Pylons+as+a+Windows+service | |
227 |
|
227 | |||
228 | - Using Apache. You can investigate here: |
|
228 | - Using Apache. You can investigate here: | |
229 |
|
229 | |||
230 | - https://groups.google.com/group/rhodecode/msg/c433074e813ffdc4 |
|
230 | - https://groups.google.com/group/rhodecode/msg/c433074e813ffdc4 | |
231 |
|
231 | |||
232 |
|
232 | |||
233 | Upgrading |
|
233 | Upgrading | |
234 | ::::::::: |
|
234 | ::::::::: | |
235 |
|
235 | |||
236 | Stop running Kallithea |
|
236 | Stop running Kallithea | |
237 | Open a CommandPrompt like in Step 7 (cd to C:\Kallithea\Env\Scripts and activate) and type:: |
|
237 | Open a CommandPrompt like in Step 7 (cd to C:\Kallithea\Env\Scripts and activate) and type:: | |
238 |
|
238 | |||
239 | pip install kallithea --upgrade |
|
239 | pip install kallithea --upgrade | |
240 | cd \Kallithea\Bin |
|
240 | cd \Kallithea\Bin | |
241 |
|
241 | |||
242 | Backup your production.ini file now. |
|
242 | Backup your production.ini file now. | |
243 |
|
243 | |||
244 | Then run:: |
|
244 | Then run:: | |
245 |
|
245 | |||
246 | paster make-config Kallithea production.ini |
|
246 | paster make-config Kallithea production.ini | |
247 |
|
247 | |||
248 | Look for changes and update your production.ini accordingly. |
|
248 | Look for changes and update your production.ini accordingly. | |
249 |
|
249 | |||
250 | Next, update the database:: |
|
250 | Next, update the database:: | |
251 |
|
251 | |||
252 | paster upgrade-db production.ini |
|
252 | paster upgrade-db production.ini | |
253 |
|
253 | |||
254 | More details can be found in `<upgrade.html>`_. |
|
254 | More details can be found in `<upgrade.html>`_. |
@@ -1,291 +1,291 b'' | |||||
1 | .. _installation_win_old: |
|
1 | .. _installation_win_old: | |
2 |
|
2 | |||
3 |
|
3 | ====================================================================== | ||
4 | Installation and upgrade on Windows (XP/Vista/Server 2003/Server 2008) |
|
4 | Installation and upgrade on Windows (XP/Vista/Server 2003/Server 2008) | |
5 | ====================================================================== |
|
5 | ====================================================================== | |
6 |
|
6 | |||
7 |
First |
|
7 | First-time install | |
8 | :::::::::::::::::: |
|
8 | :::::::::::::::::: | |
9 |
|
9 | |||
10 | Target OS: Windows XP SP3 32bit English (Clean installation) |
|
10 | Target OS: Windows XP SP3 32bit English (Clean installation) | |
11 | + All Windows Updates until 24-may-2012 |
|
11 | + All Windows Updates until 24-may-2012 | |
12 |
|
12 | |||
13 | .. note:: |
|
13 | .. note:: | |
14 |
|
14 | |||
15 | This installation is for 32bit systems, for 64bit windows you might need |
|
15 | This installation is for 32bit systems, for 64bit windows you might need | |
16 | to download proper 64bit versions of the different packages(Windows Installer, Win32py extensions) |
|
16 | to download proper 64bit versions of the different packages(Windows Installer, Win32py extensions) | |
17 | plus some extra tweaks. |
|
17 | plus some extra tweaks. | |
18 | These extra steps haven been marked as "64bit". |
|
18 | These extra steps haven been marked as "64bit". | |
19 | Tested on Windows Server 2008 R2 SP1, 9-feb-2013. |
|
19 | Tested on Windows Server 2008 R2 SP1, 9-feb-2013. | |
20 | If you run into any 64bit related problems, please check these pages: |
|
20 | If you run into any 64bit related problems, please check these pages: | |
21 | - http://blog.victorjabur.com/2011/06/05/compiling-python-2-7-modules-on-windows-32-and-64-using-msvc-2008-express/ |
|
21 | - http://blog.victorjabur.com/2011/06/05/compiling-python-2-7-modules-on-windows-32-and-64-using-msvc-2008-express/ | |
22 | - http://bugs.python.org/issue7511 |
|
22 | - http://bugs.python.org/issue7511 | |
23 |
|
23 | |||
24 | Step1 - Install Visual Studio 2008 Express |
|
24 | Step 1 - Install Visual Studio 2008 Express | |
25 | ------------------------------------------ |
|
25 | ------------------------------------------- | |
26 |
|
26 | |||
27 |
|
27 | |||
28 | Optional: You can also install MinGW, but VS2008 installation is easier. |
|
28 | Optional: You can also install MinGW, but VS2008 installation is easier. | |
29 |
|
29 | |||
30 | Download "Visual C++ 2008 Express Edition with SP1" from: |
|
30 | Download "Visual C++ 2008 Express Edition with SP1" from: | |
31 | http://download.microsoft.com/download/E/8/E/E8EEB394-7F42-4963-A2D8-29559B738298/VS2008ExpressWithSP1ENUX1504728.iso |
|
31 | http://download.microsoft.com/download/E/8/E/E8EEB394-7F42-4963-A2D8-29559B738298/VS2008ExpressWithSP1ENUX1504728.iso | |
32 | (if not found or relocated, google for "visual studio 2008 express" for updated link. This link was taken from http://stackoverflow.com/questions/15318560/visual-c-2008-express-download-link-dead) |
|
32 | (if not found or relocated, google for "visual studio 2008 express" for updated link. This link was taken from http://stackoverflow.com/questions/15318560/visual-c-2008-express-download-link-dead) | |
33 |
|
33 | |||
34 | You can also download full ISO file for offline installation, just |
|
34 | You can also download full ISO file for offline installation, just | |
35 | choose "All - Offline Install ISO image file" in the previous page and |
|
35 | choose "All - Offline Install ISO image file" in the previous page and | |
36 | choose "Visual C++ 2008 Express" when installing. |
|
36 | choose "Visual C++ 2008 Express" when installing. | |
37 |
|
37 | |||
38 | .. note:: |
|
38 | .. note:: | |
39 |
|
39 | |||
40 | Using other versions of Visual Studio will lead to random crashes. |
|
40 | Using other versions of Visual Studio will lead to random crashes. | |
41 | You must use Visual Studio 2008!" |
|
41 | You must use Visual Studio 2008!" | |
42 |
|
42 | |||
43 | .. note:: |
|
43 | .. note:: | |
44 |
|
44 | |||
45 | Silverlight Runtime and SQL Server 2008 Express Edition are not |
|
45 | Silverlight Runtime and SQL Server 2008 Express Edition are not | |
46 | required, you can uncheck them |
|
46 | required, you can uncheck them | |
47 |
|
47 | |||
48 | .. note:: |
|
48 | .. note:: | |
49 |
|
49 | |||
50 | 64bit: You also need to install the Microsoft Windows SDK for .NET 3.5 SP1 (.NET 4.0 won't work). |
|
50 | 64bit: You also need to install the Microsoft Windows SDK for .NET 3.5 SP1 (.NET 4.0 won't work). | |
51 | Download from: http://www.microsoft.com/en-us/download/details.aspx?id=3138 |
|
51 | Download from: http://www.microsoft.com/en-us/download/details.aspx?id=3138 | |
52 |
|
52 | |||
53 | .. note:: |
|
53 | .. note:: | |
54 |
|
54 | |||
55 | 64bit: You also need to copy and rename a .bat file to make the Visual C++ compiler work. |
|
55 | 64bit: You also need to copy and rename a .bat file to make the Visual C++ compiler work. | |
56 | I am not sure why this is not necessary for 32bit. |
|
56 | I am not sure why this is not necessary for 32bit. | |
57 | Copy C:\Program Files (x86)\Microsoft Visual Studio 9.0\VC\bin\vcvars64.bat to C:\Program Files (x86)\Microsoft Visual Studio 9.0\VC\bin\amd64\vcvarsamd64.bat |
|
57 | Copy C:\Program Files (x86)\Microsoft Visual Studio 9.0\VC\bin\vcvars64.bat to C:\Program Files (x86)\Microsoft Visual Studio 9.0\VC\bin\amd64\vcvarsamd64.bat | |
58 |
|
58 | |||
59 |
|
59 | |||
60 | Step2 - Install Python |
|
60 | Step 2 - Install Python | |
61 | ---------------------- |
|
61 | ----------------------- | |
62 |
|
62 | |||
63 | Install Python 2.x.y (x = 6 or 7) x86 version (32bit). DO NOT USE A 3.x version. |
|
63 | Install Python 2.x.y (x = 6 or 7) x86 version (32bit). DO NOT USE A 3.x version. | |
64 | Download Python 2.x.y from: |
|
64 | Download Python 2.x.y from: | |
65 | http://www.python.org/download/ |
|
65 | http://www.python.org/download/ | |
66 |
|
66 | |||
67 | Choose "Windows Installer" (32bit version) not "Windows X86-64 |
|
67 | Choose "Windows Installer" (32bit version) not "Windows X86-64 | |
68 | Installer". While writing this guide, the latest version was v2.7.3. |
|
68 | Installer". While writing this guide, the latest version was v2.7.3. | |
69 | Remember the specific major and minor version installed, because it will |
|
69 | Remember the specific major and minor version installed, because it will | |
70 | be needed in the next step. In this case, it is "2.7". |
|
70 | be needed in the next step. In this case, it is "2.7". | |
71 |
|
71 | |||
72 | .. note:: |
|
72 | .. note:: | |
73 |
|
73 | |||
74 | 64bit: Just download and install the 64bit version of python. |
|
74 | 64bit: Just download and install the 64bit version of python. | |
75 |
|
75 | |||
76 | Step3 - Install Win32py extensions |
|
76 | Step 3 - Install Win32py extensions | |
77 | ---------------------------------- |
|
77 | ----------------------------------- | |
78 |
|
78 | |||
79 | Download pywin32 from: |
|
79 | Download pywin32 from: | |
80 | http://sourceforge.net/projects/pywin32/files/ |
|
80 | http://sourceforge.net/projects/pywin32/files/ | |
81 |
|
81 | |||
82 | - Click on "pywin32" folder |
|
82 | - Click on "pywin32" folder | |
83 | - Click on the first folder (in this case, Build 217, maybe newer when you try) |
|
83 | - Click on the first folder (in this case, Build 217, maybe newer when you try) | |
84 | - Choose the file ending with ".win32-py2.x.exe" -> x being the minor |
|
84 | - Choose the file ending with ".win32-py2.x.exe" -> x being the minor | |
85 | version of Python you installed (in this case, 7) |
|
85 | version of Python you installed (in this case, 7) | |
86 | When writing this guide, the file was: |
|
86 | When writing this guide, the file was: | |
87 | http://sourceforge.net/projects/pywin32/files/pywin32/Build%20217/pywin32-217.win32-py2.7.exe/download |
|
87 | http://sourceforge.net/projects/pywin32/files/pywin32/Build%20217/pywin32-217.win32-py2.7.exe/download | |
88 |
|
88 | |||
89 | .. note:: |
|
89 | .. note:: | |
90 |
|
90 | |||
91 | 64bit: Download and install the 64bit version. |
|
91 | 64bit: Download and install the 64bit version. | |
92 | At the time of writing you can find this at: |
|
92 | At the time of writing you can find this at: | |
93 | http://sourceforge.net/projects/pywin32/files/pywin32/Build%20218/pywin32-218.win-amd64-py2.7.exe/download |
|
93 | http://sourceforge.net/projects/pywin32/files/pywin32/Build%20218/pywin32-218.win-amd64-py2.7.exe/download | |
94 |
|
94 | |||
95 | Step4 - Python BIN |
|
95 | Step 4 - Python BIN | |
96 | ------------------ |
|
96 | ------------------- | |
97 |
|
97 | |||
98 | Add Python BIN folder to the path |
|
98 | Add Python BIN folder to the path | |
99 |
|
99 | |||
100 | You have to add the Python folder to the path, you can do it manually |
|
100 | You have to add the Python folder to the path, you can do it manually | |
101 | (editing "PATH" environment variable) or using Windows Support Tools |
|
101 | (editing "PATH" environment variable) or using Windows Support Tools | |
102 | that came preinstalled in Vista/7 and can be installed in Windows XP. |
|
102 | that came preinstalled in Vista/7 and can be installed in Windows XP. | |
103 |
|
103 | |||
104 | - Using support tools on WINDOWS XP: |
|
104 | - Using support tools on WINDOWS XP: | |
105 | If you use Windows XP you can install them using Windows XP CD and |
|
105 | If you use Windows XP you can install them using Windows XP CD and | |
106 | navigating to \SUPPORT\TOOLS. There, execute Setup.EXE (not MSI). |
|
106 | navigating to \SUPPORT\TOOLS. There, execute Setup.EXE (not MSI). | |
107 | Afterwards, open a CMD and type:: |
|
107 | Afterwards, open a CMD and type:: | |
108 |
|
108 | |||
109 | SETX PATH "%PATH%;[your-python-path]" -M |
|
109 | SETX PATH "%PATH%;[your-python-path]" -M | |
110 |
|
110 | |||
111 | Close CMD (the path variable will be updated then) |
|
111 | Close CMD (the path variable will be updated then) | |
112 |
|
112 | |||
113 | - Using support tools on WINDOWS Vista/7: |
|
113 | - Using support tools on WINDOWS Vista/7: | |
114 |
|
114 | |||
115 | Open a CMD and type:: |
|
115 | Open a CMD and type:: | |
116 |
|
116 | |||
117 | SETX PATH "%PATH%;[your-python-path]" /M |
|
117 | SETX PATH "%PATH%;[your-python-path]" /M | |
118 |
|
118 | |||
119 | Please substitute [your-python-path] with your Python installation path. |
|
119 | Please substitute [your-python-path] with your Python installation path. | |
120 | Typically: C:\\Python27 |
|
120 | Typically: C:\\Python27 | |
121 |
|
121 | |||
122 |
|
122 | |||
123 | Step5 - Kallithea folder structure |
|
123 | Step 5 - Kallithea folder structure | |
124 | ---------------------------------- |
|
124 | ----------------------------------- | |
125 |
|
125 | |||
126 | Create a Kallithea folder structure |
|
126 | Create a Kallithea folder structure | |
127 |
|
127 | |||
128 | This is only a example to install Kallithea, you can of course change |
|
128 | This is only a example to install Kallithea, you can of course change | |
129 | it. However, this guide will follow the proposed structure, so please |
|
129 | it. However, this guide will follow the proposed structure, so please | |
130 | later adapt the paths if you change them. My recommendation is to use |
|
130 | later adapt the paths if you change them. My recommendation is to use | |
131 | folders with NO SPACES. But you can try if you are brave... |
|
131 | folders with NO SPACES. But you can try if you are brave... | |
132 |
|
132 | |||
133 | Create the following folder structure:: |
|
133 | Create the following folder structure:: | |
134 |
|
134 | |||
135 | C:\Kallithea |
|
135 | C:\Kallithea | |
136 | C:\Kallithea\Bin |
|
136 | C:\Kallithea\Bin | |
137 | C:\Kallithea\Env |
|
137 | C:\Kallithea\Env | |
138 | C:\Kallithea\Repos |
|
138 | C:\Kallithea\Repos | |
139 |
|
139 | |||
140 |
|
140 | |||
141 | Step6 - Install virtualenv |
|
141 | Step 6 - Install virtualenv | |
142 | --------------------------- |
|
142 | --------------------------- | |
143 |
|
143 | |||
144 | Install Virtual Env for Python |
|
144 | Install Virtual Env for Python | |
145 |
|
145 | |||
146 | Navigate to: http://www.virtualenv.org/en/latest/index.html#installation |
|
146 | Navigate to: http://www.virtualenv.org/en/latest/index.html#installation | |
147 | Right click on "virtualenv.py" file and choose "Save link as...". |
|
147 | Right click on "virtualenv.py" file and choose "Save link as...". | |
148 | Download to C:\\Kallithea (or whatever you want) |
|
148 | Download to C:\\Kallithea (or whatever you want) | |
149 | (the file is located at |
|
149 | (the file is located at | |
150 | https://raw.github.com/pypa/virtualenv/master/virtualenv.py) |
|
150 | https://raw.github.com/pypa/virtualenv/master/virtualenv.py) | |
151 |
|
151 | |||
152 | Create a virtual Python environment in C:\\Kallithea\\Env (or similar). To |
|
152 | Create a virtual Python environment in C:\\Kallithea\\Env (or similar). To | |
153 | do so, open a CMD (Python Path should be included in Step3), navigate |
|
153 | do so, open a CMD (Python Path should be included in Step3), navigate | |
154 | where you downloaded "virtualenv.py", and write:: |
|
154 | where you downloaded "virtualenv.py", and write:: | |
155 |
|
155 | |||
156 | python virtualenv.py C:\Kallithea\Env |
|
156 | python virtualenv.py C:\Kallithea\Env | |
157 |
|
157 | |||
158 | (--no-site-packages is now the default behaviour of virtualenv, no need |
|
158 | (--no-site-packages is now the default behaviour of virtualenv, no need | |
159 | to include it) |
|
159 | to include it) | |
160 |
|
160 | |||
161 |
|
161 | |||
162 | Step7 - Install Kallithea |
|
162 | Step 7 - Install Kallithea | |
163 | ------------------------- |
|
163 | -------------------------- | |
164 |
|
164 | |||
165 | Finally, install Kallithea |
|
165 | Finally, install Kallithea | |
166 |
|
166 | |||
167 | Close previously opened command prompt/s, and open a Visual Studio 2008 |
|
167 | Close previously opened command prompt/s, and open a Visual Studio 2008 | |
168 | Command Prompt (**IMPORTANT!!**). To do so, go to Start Menu, and then open |
|
168 | Command Prompt (**IMPORTANT!!**). To do so, go to Start Menu, and then open | |
169 | "Microsoft Visual C++ 2008 Express Edition" -> "Visual Studio Tools" -> |
|
169 | "Microsoft Visual C++ 2008 Express Edition" -> "Visual Studio Tools" -> | |
170 | "Visual Studio 2008 Command Prompt" |
|
170 | "Visual Studio 2008 Command Prompt" | |
171 |
|
171 | |||
172 | .. note:: |
|
172 | .. note:: | |
173 |
|
173 | |||
174 | 64bit: For 64bit you need to modify the shortcut that is used to start the |
|
174 | 64bit: For 64bit you need to modify the shortcut that is used to start the | |
175 | Visual Studio 2008 Command Prompt. Use right-mouse click to open properties. |
|
175 | Visual Studio 2008 Command Prompt. Use right-mouse click to open properties. | |
176 |
|
176 | |||
177 | Change commandline from:: |
|
177 | Change commandline from:: | |
178 |
|
178 | |||
179 | %comspec% /k ""C:\Program Files (x86)\Microsoft Visual Studio 9.0\VC\vcvarsall.bat"" x86 |
|
179 | %comspec% /k ""C:\Program Files (x86)\Microsoft Visual Studio 9.0\VC\vcvarsall.bat"" x86 | |
180 |
|
180 | |||
181 | to:: |
|
181 | to:: | |
182 |
|
182 | |||
183 | %comspec% /k ""C:\Program Files (x86)\Microsoft Visual Studio 9.0\VC\vcvarsall.bat"" amd64 |
|
183 | %comspec% /k ""C:\Program Files (x86)\Microsoft Visual Studio 9.0\VC\vcvarsall.bat"" amd64 | |
184 |
|
184 | |||
185 |
|
185 | |||
186 | In that CMD (loaded with VS2008 PATHs) type:: |
|
186 | In that CMD (loaded with VS2008 PATHs) type:: | |
187 |
|
187 | |||
188 | cd C:\Kallithea\Env\Scripts (or similar) |
|
188 | cd C:\Kallithea\Env\Scripts (or similar) | |
189 | activate |
|
189 | activate | |
190 |
|
190 | |||
191 | The prompt will change into "(Env) C:\\Kallithea\\Env\\Scripts" or similar |
|
191 | The prompt will change into "(Env) C:\\Kallithea\\Env\\Scripts" or similar | |
192 | (depending of your folder structure). Then type:: |
|
192 | (depending of your folder structure). Then type:: | |
193 |
|
193 | |||
194 | pip install kallithea |
|
194 | pip install kallithea | |
195 |
|
195 | |||
196 | (long step, please wait until fully complete) |
|
196 | (long step, please wait until fully complete) | |
197 |
|
197 | |||
198 | Some warnings will appear, don't worry as they are normal. |
|
198 | Some warnings will appear, don't worry as they are normal. | |
199 |
|
199 | |||
200 |
|
200 | |||
201 | Step8 - Configuring Kallithea |
|
201 | Step 8 - Configuring Kallithea | |
202 | ----------------------------- |
|
202 | ------------------------------ | |
203 |
|
203 | |||
204 |
|
204 | |||
205 | steps taken from http://packages.python.org/Kallithea/setup.html |
|
205 | steps taken from http://packages.python.org/Kallithea/setup.html | |
206 |
|
206 | |||
207 | You have to use the same Visual Studio 2008 command prompt as Step7, so |
|
207 | You have to use the same Visual Studio 2008 command prompt as Step7, so | |
208 | if you closed it reopen it following the same commands (including the |
|
208 | if you closed it reopen it following the same commands (including the | |
209 | "activate" one). When ready, just type:: |
|
209 | "activate" one). When ready, just type:: | |
210 |
|
210 | |||
211 | cd C:\Kallithea\Bin |
|
211 | cd C:\Kallithea\Bin | |
212 | paster make-config Kallithea production.ini |
|
212 | paster make-config Kallithea production.ini | |
213 |
|
213 | |||
214 | Then, you must edit production.ini to fit your needs (network address and |
|
214 | Then, you must edit production.ini to fit your needs (network address and | |
215 | port, mail settings, database, whatever). I recommend using NotePad++ |
|
215 | port, mail settings, database, whatever). I recommend using NotePad++ | |
216 | (free) or similar text editor, as it handles well the EndOfLine |
|
216 | (free) or similar text editor, as it handles well the EndOfLine | |
217 | character differences between Unix and Windows |
|
217 | character differences between Unix and Windows | |
218 | (http://notepad-plus-plus.org/) |
|
218 | (http://notepad-plus-plus.org/) | |
219 |
|
219 | |||
220 | For the sake of simplicity lets run it with the default settings. After |
|
220 | For the sake of simplicity lets run it with the default settings. After | |
221 | your edits (if any), in the previous Command Prompt, type:: |
|
221 | your edits (if any), in the previous Command Prompt, type:: | |
222 |
|
222 | |||
223 | paster setup-db production.ini |
|
223 | paster setup-db production.ini | |
224 |
|
224 | |||
225 | (this time a NEW database will be installed, you must follow a different |
|
225 | (this time a NEW database will be installed, you must follow a different | |
226 | step to later UPGRADE to a newer Kallithea version) |
|
226 | step to later UPGRADE to a newer Kallithea version) | |
227 |
|
227 | |||
228 | The script will ask you for confirmation about creating a NEW database, |
|
228 | The script will ask you for confirmation about creating a NEW database, | |
229 | answer yes (y) |
|
229 | answer yes (y) | |
230 | The script will ask you for repository path, answer C:\\Kallithea\\Repos |
|
230 | The script will ask you for repository path, answer C:\\Kallithea\\Repos | |
231 | (or similar) |
|
231 | (or similar) | |
232 | The script will ask you for admin username and password, answer "admin" |
|
232 | The script will ask you for admin username and password, answer "admin" | |
233 | + "123456" (or whatever you want) |
|
233 | + "123456" (or whatever you want) | |
234 | The script will ask you for admin mail, answer "admin@xxxx.com" (or |
|
234 | The script will ask you for admin mail, answer "admin@xxxx.com" (or | |
235 | whatever you want) |
|
235 | whatever you want) | |
236 |
|
236 | |||
237 | If you make some mistake and the script does not end, don't worry, start |
|
237 | If you make some mistake and the script does not end, don't worry, start | |
238 | it again. |
|
238 | it again. | |
239 |
|
239 | |||
240 |
|
240 | |||
241 | Step9 - Running Kallithea |
|
241 | Step 9 - Running Kallithea | |
242 | ------------------------- |
|
242 | -------------------------- | |
243 |
|
243 | |||
244 |
|
244 | |||
245 | In the previous command prompt, being in the C:\\Kallithea\\Bin folder, |
|
245 | In the previous command prompt, being in the C:\\Kallithea\\Bin folder, | |
246 | just type:: |
|
246 | just type:: | |
247 |
|
247 | |||
248 | paster serve production.ini |
|
248 | paster serve production.ini | |
249 |
|
249 | |||
250 | Open yout web server, and go to http://127.0.0.1:5000 |
|
250 | Open yout web server, and go to http://127.0.0.1:5000 | |
251 |
|
251 | |||
252 | It works!! :-) |
|
252 | It works!! :-) | |
253 |
|
253 | |||
254 | Remark: |
|
254 | Remark: | |
255 | If it does not work first time, just Ctrl-C the CMD process and start it |
|
255 | If it does not work first time, just Ctrl-C the CMD process and start it | |
256 | again. Don't forget the "http://" in Internet Explorer |
|
256 | again. Don't forget the "http://" in Internet Explorer | |
257 |
|
257 | |||
258 |
|
258 | |||
259 |
|
259 | |||
260 | What this Guide does not cover: |
|
260 | What this Guide does not cover: | |
261 |
|
261 | |||
262 | - Installing Celery |
|
262 | - Installing Celery | |
263 | - Running Kallithea as Windows Service. You can investigate here: |
|
263 | - Running Kallithea as Windows Service. You can investigate here: | |
264 |
|
264 | |||
265 | - http://pypi.python.org/pypi/wsgisvc |
|
265 | - http://pypi.python.org/pypi/wsgisvc | |
266 | - http://ryrobes.com/python/running-python-scripts-as-a-windows-service/ |
|
266 | - http://ryrobes.com/python/running-python-scripts-as-a-windows-service/ | |
267 | - http://wiki.pylonshq.com/display/pylonscookbook/How+to+run+Pylons+as+a+Windows+service |
|
267 | - http://wiki.pylonshq.com/display/pylonscookbook/How+to+run+Pylons+as+a+Windows+service | |
268 |
|
268 | |||
269 | - Using Apache. You can investigate here: |
|
269 | - Using Apache. You can investigate here: | |
270 |
|
270 | |||
271 | - https://groups.google.com/group/rhodecode/msg/c433074e813ffdc4 |
|
271 | - https://groups.google.com/group/rhodecode/msg/c433074e813ffdc4 | |
272 |
|
272 | |||
273 |
|
273 | |||
274 | Upgrading |
|
274 | Upgrading | |
275 | ::::::::: |
|
275 | ::::::::: | |
276 |
|
276 | |||
277 | Stop running Kallithea |
|
277 | Stop running Kallithea | |
278 | Open a CommandPrompt like in Step7 (VS2008 path + activate) and type:: |
|
278 | Open a CommandPrompt like in Step7 (VS2008 path + activate) and type:: | |
279 |
|
279 | |||
280 | easy_install -U kallithea |
|
280 | easy_install -U kallithea | |
281 | cd \Kallithea\Bin |
|
281 | cd \Kallithea\Bin | |
282 |
|
282 | |||
283 | { backup your production.ini file now} :: |
|
283 | { backup your production.ini file now} :: | |
284 |
|
284 | |||
285 | paster make-config Kallithea production.ini |
|
285 | paster make-config Kallithea production.ini | |
286 |
|
286 | |||
287 | (check changes and update your production.ini accordingly) :: |
|
287 | (check changes and update your production.ini accordingly) :: | |
288 |
|
288 | |||
289 | paster upgrade-db production.ini (update database) |
|
289 | paster upgrade-db production.ini (update database) | |
290 |
|
290 | |||
291 | Full steps in http://packages.python.org/Kallithea/upgrade.html |
|
291 | Full steps in http://packages.python.org/Kallithea/upgrade.html |
@@ -1,128 +1,128 b'' | |||||
1 | .. _overview: |
|
1 | .. _overview: | |
2 |
|
2 | |||
3 | ===================== |
|
3 | ===================== | |
4 |
Installation |
|
4 | Installation overview | |
5 | ===================== |
|
5 | ===================== | |
6 |
|
6 | |||
7 |
|
7 | |||
8 | Some overview and some details that can help understanding the options when |
|
8 | Some overview and some details that can help understanding the options when | |
9 | installing Kallithea. |
|
9 | installing Kallithea. | |
10 |
|
10 | |||
11 |
|
11 | |||
12 |
Python |
|
12 | Python environment | |
13 | ------------------ |
|
13 | ------------------ | |
14 |
|
14 | |||
15 | **Kallithea** is written entirely in Python_ and requires Python version |
|
15 | **Kallithea** is written entirely in Python_ and requires Python version | |
16 | 2.6 or higher. Python 3.x is currently not supported. |
|
16 | 2.6 or higher. Python 3.x is currently not supported. | |
17 |
|
17 | |||
18 | Given a Python installation, there are different ways of providing the |
|
18 | Given a Python installation, there are different ways of providing the | |
19 | environment for running Python applications. Each of them pretty much |
|
19 | environment for running Python applications. Each of them pretty much | |
20 | corresponds to a ``site-packages`` directory somewhere where packages can be |
|
20 | corresponds to a ``site-packages`` directory somewhere where packages can be | |
21 | installed. |
|
21 | installed. | |
22 |
|
22 | |||
23 | Kallithea itself can be run from source or be installed, but even when running |
|
23 | Kallithea itself can be run from source or be installed, but even when running | |
24 | from source, there are some dependencies that must be installed in the Python |
|
24 | from source, there are some dependencies that must be installed in the Python | |
25 | environment used for running Kallithea. |
|
25 | environment used for running Kallithea. | |
26 |
|
26 | |||
27 | - Packages *could* be installed in Python's ``site-packages`` directory ... but |
|
27 | - Packages *could* be installed in Python's ``site-packages`` directory ... but | |
28 | that would require running pip_ as root and it would be hard to uninstall or |
|
28 | that would require running pip_ as root and it would be hard to uninstall or | |
29 | upgrade and is probably not a good idea unless using a package manager. |
|
29 | upgrade and is probably not a good idea unless using a package manager. | |
30 |
|
30 | |||
31 | - Packages could also be installed in ``~/.local`` ... but that is probably |
|
31 | - Packages could also be installed in ``~/.local`` ... but that is probably | |
32 | only a good idea if using a dedicated user per application or instance. |
|
32 | only a good idea if using a dedicated user per application or instance. | |
33 |
|
33 | |||
34 | - Finally, it can be installed in a virtualenv_. That is a very lightweight |
|
34 | - Finally, it can be installed in a virtualenv_. That is a very lightweight | |
35 | "container" where each Kallithea instance can get its own dedicated and |
|
35 | "container" where each Kallithea instance can get its own dedicated and | |
36 | self-contained virtual environment. |
|
36 | self-contained virtual environment. | |
37 |
|
37 | |||
38 | We recommend using virtualenv for installing Kallithea. |
|
38 | We recommend using virtualenv for installing Kallithea. | |
39 |
|
39 | |||
40 |
|
40 | |||
41 |
Installation |
|
41 | Installation methods | |
42 | -------------------- |
|
42 | -------------------- | |
43 |
|
43 | |||
44 | Kallithea must be installed on a server. Kallithea is installed in a Python |
|
44 | Kallithea must be installed on a server. Kallithea is installed in a Python | |
45 | environment so it can use packages that are installed there and make itself |
|
45 | environment so it can use packages that are installed there and make itself | |
46 | available for other packages. |
|
46 | available for other packages. | |
47 |
|
47 | |||
48 | Two different cases will pretty much cover the options for how it can be |
|
48 | Two different cases will pretty much cover the options for how it can be | |
49 | installed. |
|
49 | installed. | |
50 |
|
50 | |||
51 | - The Kallithea source repository can be cloned and used - it is kept stable and |
|
51 | - The Kallithea source repository can be cloned and used - it is kept stable and | |
52 | can be used in production. The Kallithea maintainers use the development |
|
52 | can be used in production. The Kallithea maintainers use the development | |
53 | branch in production. The advantage of installation from source and regularly |
|
53 | branch in production. The advantage of installation from source and regularly | |
54 | updating it is that you take advantage of the most recent improvements. Using |
|
54 | updating it is that you take advantage of the most recent improvements. Using | |
55 | it directly from a DVCS also means that it is easy to track local customizations. |
|
55 | it directly from a DVCS also means that it is easy to track local customizations. | |
56 |
|
56 | |||
57 | Running ``setup.py develop`` in the source will use pip to install the |
|
57 | Running ``setup.py develop`` in the source will use pip to install the | |
58 | necessary dependencies in the Python environment and create a |
|
58 | necessary dependencies in the Python environment and create a | |
59 | ``.../site-packages/Kallithea.egg-link`` file there that points at the Kallithea |
|
59 | ``.../site-packages/Kallithea.egg-link`` file there that points at the Kallithea | |
60 | source. |
|
60 | source. | |
61 |
|
61 | |||
62 | - Kallithea can also be installed from ready-made packages using a package manager. |
|
62 | - Kallithea can also be installed from ready-made packages using a package manager. | |
63 | The official released versions are available on PyPI_ and can be downloaded and |
|
63 | The official released versions are available on PyPI_ and can be downloaded and | |
64 | installed with all dependencies using ``pip install kallithea``. |
|
64 | installed with all dependencies using ``pip install kallithea``. | |
65 |
|
65 | |||
66 | With this method, Kallithea is installed in the Python environment as any |
|
66 | With this method, Kallithea is installed in the Python environment as any | |
67 | other package, usually as a ``.../site-packages/Kallithea-X-py2.7.egg/`` |
|
67 | other package, usually as a ``.../site-packages/Kallithea-X-py2.7.egg/`` | |
68 | directory with Python files and everything else that is needed. |
|
68 | directory with Python files and everything else that is needed. | |
69 |
|
69 | |||
70 | (``pip install kallithea`` from a source tree will do pretty much the same |
|
70 | (``pip install kallithea`` from a source tree will do pretty much the same | |
71 | but build the Kallithea package itself locally instead of downloading it.) |
|
71 | but build the Kallithea package itself locally instead of downloading it.) | |
72 |
|
72 | |||
73 |
|
73 | |||
74 |
Web |
|
74 | Web server | |
75 | ---------- |
|
75 | ---------- | |
76 |
|
76 | |||
77 | Kallithea is (primarily) a WSGI_ application that must be run from a web |
|
77 | Kallithea is (primarily) a WSGI_ application that must be run from a web | |
78 | server that expose WSGI as HTTP. |
|
78 | server that expose WSGI as HTTP. | |
79 |
|
79 | |||
80 | - Kallithea uses the Paste_ tool for some admin tasks. Paste provides ``paste |
|
80 | - Kallithea uses the Paste_ tool for some admin tasks. Paste provides ``paste | |
81 | serve`` as a convenient way to launch Python WSGI / web servers. |
|
81 | serve`` as a convenient way to launch Python WSGI / web servers. | |
82 | This method is perfect for development but *can* also be used for production. |
|
82 | This method is perfect for development but *can* also be used for production. | |
83 |
|
83 | |||
84 | ``paste`` is a command line tool. Using it in production requires some way to |
|
84 | ``paste`` is a command line tool. Using it in production requires some way to | |
85 | wrap it as a managable service. |
|
85 | wrap it as a managable service. | |
86 |
|
86 | |||
87 | Paste come with its own web server but Kallithea defaults to use Waitress_. |
|
87 | Paste come with its own web server but Kallithea defaults to use Waitress_. | |
88 | Gunicorn_ is also an option. These web servers have different limited feature |
|
88 | Gunicorn_ is also an option. These web servers have different limited feature | |
89 | sets. |
|
89 | sets. | |
90 |
|
90 | |||
91 | It is also common/mandatory to put another web server or (reverse) proxy in |
|
91 | It is also common/mandatory to put another web server or (reverse) proxy in | |
92 | front of these Python web servers. Nginx_ is a common choice. This simple |
|
92 | front of these Python web servers. Nginx_ is a common choice. This simple | |
93 | setup will thus often end up being quite complex. |
|
93 | setup will thus often end up being quite complex. | |
94 |
|
94 | |||
95 | The configuration of which web server to use is in the ini file passed to |
|
95 | The configuration of which web server to use is in the ini file passed to | |
96 | ``paste``. The entry point for the WSGI application is configured in |
|
96 | ``paste``. The entry point for the WSGI application is configured in | |
97 | ``setup.py`` as ``kallithea.config.middleware:make_app``. |
|
97 | ``setup.py`` as ``kallithea.config.middleware:make_app``. | |
98 |
|
98 | |||
99 | - `Apache httpd`_ can serve WSGI applications directly using mod_wsgi_ and a |
|
99 | - `Apache httpd`_ can serve WSGI applications directly using mod_wsgi_ and a | |
100 | simple Python file with the necessary configuration. This is a good option if |
|
100 | simple Python file with the necessary configuration. This is a good option if | |
101 | Apache is an option. |
|
101 | Apache is an option. | |
102 |
|
102 | |||
103 | - IIS_ can also server WSGI applications directly using isapi-wsgi_. |
|
103 | - IIS_ can also server WSGI applications directly using isapi-wsgi_. | |
104 |
|
104 | |||
105 | - UWSGI_ is also an option. |
|
105 | - UWSGI_ is also an option. | |
106 |
|
106 | |||
107 | The best option depends on what you are familiar with and the requirements for |
|
107 | The best option depends on what you are familiar with and the requirements for | |
108 | performance and stability. Also, keep in mind that Kallithea mainly is serving |
|
108 | performance and stability. Also, keep in mind that Kallithea mainly is serving | |
109 | custom data generated from relatively slow Python process. Kallithea is also |
|
109 | custom data generated from relatively slow Python process. Kallithea is also | |
110 | often used inside organizations with a limited amount of users and thus no |
|
110 | often used inside organizations with a limited amount of users and thus no | |
111 | continuous hammering from the internet. |
|
111 | continuous hammering from the internet. | |
112 |
|
112 | |||
113 |
|
113 | |||
114 | .. _Python: http://www.python.org/ |
|
114 | .. _Python: http://www.python.org/ | |
115 | .. _Gunicorn: http://gunicorn.org/ |
|
115 | .. _Gunicorn: http://gunicorn.org/ | |
116 | .. _Waitress: http://waitress.readthedocs.org/en/latest/ |
|
116 | .. _Waitress: http://waitress.readthedocs.org/en/latest/ | |
117 | .. _virtualenv: http://pypi.python.org/pypi/virtualenv |
|
117 | .. _virtualenv: http://pypi.python.org/pypi/virtualenv | |
118 | .. _Paste: http://pythonpaste.org/ |
|
118 | .. _Paste: http://pythonpaste.org/ | |
119 | .. _PyPI: https://pypi.python.org/pypi |
|
119 | .. _PyPI: https://pypi.python.org/pypi | |
120 | .. _Apache httpd: http://httpd.apache.org/ |
|
120 | .. _Apache httpd: http://httpd.apache.org/ | |
121 | .. _mod_wsgi: https://code.google.com/p/modwsgi/ |
|
121 | .. _mod_wsgi: https://code.google.com/p/modwsgi/ | |
122 | .. _isapi-wsgi: https://github.com/hexdump42/isapi-wsgi |
|
122 | .. _isapi-wsgi: https://github.com/hexdump42/isapi-wsgi | |
123 | .. _UWSGI: https://uwsgi-docs.readthedocs.org/en/latest/ |
|
123 | .. _UWSGI: https://uwsgi-docs.readthedocs.org/en/latest/ | |
124 | .. _nginx: http://nginx.org/en/ |
|
124 | .. _nginx: http://nginx.org/en/ | |
125 | .. _iis: http://en.wikipedia.org/wiki/Internet_Information_Services |
|
125 | .. _iis: http://en.wikipedia.org/wiki/Internet_Information_Services | |
126 | .. _pip: http://en.wikipedia.org/wiki/Pip_%28package_manager%29 |
|
126 | .. _pip: http://en.wikipedia.org/wiki/Pip_%28package_manager%29 | |
127 | .. _WSGI: http://en.wikipedia.org/wiki/Web_Server_Gateway_Interface |
|
127 | .. _WSGI: http://en.wikipedia.org/wiki/Web_Server_Gateway_Interface | |
128 | .. _pylons: http://www.pylonsproject.org/ |
|
128 | .. _pylons: http://www.pylonsproject.org/ |
@@ -1,794 +1,795 b'' | |||||
1 | .. _setup: |
|
1 | .. _setup: | |
2 |
|
2 | |||
3 | ===== |
|
3 | ===== | |
4 | Setup |
|
4 | Setup | |
5 | ===== |
|
5 | ===== | |
6 |
|
6 | |||
7 |
|
7 | |||
8 | Setting up Kallithea |
|
8 | Setting up Kallithea | |
9 | -------------------- |
|
9 | -------------------- | |
10 |
|
10 | |||
11 | First, you will need to create a Kallithea configuration file. Run the |
|
11 | First, you will need to create a Kallithea configuration file. Run the | |
12 | following command to do so:: |
|
12 | following command to do so:: | |
13 |
|
13 | |||
14 | paster make-config Kallithea my.ini |
|
14 | paster make-config Kallithea my.ini | |
15 |
|
15 | |||
16 | This will create the file ``my.ini`` in the current directory. This |
|
16 | This will create the file ``my.ini`` in the current directory. This | |
17 | configuration file contains the various settings for Kallithea, e.g., |
|
17 | configuration file contains the various settings for Kallithea, e.g., | |
18 | proxy port, email settings, usage of static files, cache, Celery |
|
18 | proxy port, email settings, usage of static files, cache, Celery | |
19 | settings, and logging. |
|
19 | settings, and logging. | |
20 |
|
20 | |||
21 |
|
21 | |||
22 | Next, you need to create the databases used by Kallithea. It is recommended to |
|
22 | Next, you need to create the databases used by Kallithea. It is recommended to | |
23 | use PostgreSQL or SQLite (default). If you choose a database other than the |
|
23 | use PostgreSQL or SQLite (default). If you choose a database other than the | |
24 | default, ensure you properly adjust the database URL in your ``my.ini`` |
|
24 | default, ensure you properly adjust the database URL in your ``my.ini`` | |
25 | configuration file to use this other database. Kallithea currently supports |
|
25 | configuration file to use this other database. Kallithea currently supports | |
26 | PostgreSQL, SQLite and MySQL databases. Create the database by running |
|
26 | PostgreSQL, SQLite and MySQL databases. Create the database by running | |
27 | the following command:: |
|
27 | the following command:: | |
28 |
|
28 | |||
29 | paster setup-db my.ini |
|
29 | paster setup-db my.ini | |
30 |
|
30 | |||
31 | This will prompt you for a "root" path. This "root" path is the location where |
|
31 | This will prompt you for a "root" path. This "root" path is the location where | |
32 | Kallithea will store all of its repositories on the current machine. After |
|
32 | Kallithea will store all of its repositories on the current machine. After | |
33 | entering this "root" path ``setup-db`` will also prompt you for a username |
|
33 | entering this "root" path ``setup-db`` will also prompt you for a username | |
34 | and password for the initial admin account which ``setup-db`` sets |
|
34 | and password for the initial admin account which ``setup-db`` sets | |
35 | up for you. |
|
35 | up for you. | |
36 |
|
36 | |||
37 | The setup process can be fully automated, example for lazy:: |
|
37 | The setup process can be fully automated, example for lazy:: | |
38 |
|
38 | |||
39 | paster setup-db my.ini --user=nn --password=secret --email=nn@your.kallithea.server --repos=/srv/repos |
|
39 | paster setup-db my.ini --user=nn --password=secret --email=nn@your.kallithea.server --repos=/srv/repos | |
40 |
|
40 | |||
41 |
|
41 | |||
42 | The ``setup-db`` command will create all of the needed tables and an |
|
42 | The ``setup-db`` command will create all of the needed tables and an | |
43 | admin account. When choosing a root path you can either use a new |
|
43 | admin account. When choosing a root path you can either use a new | |
44 | empty location, or a location which already contains existing |
|
44 | empty location, or a location which already contains existing | |
45 | repositories. If you choose a location which contains existing |
|
45 | repositories. If you choose a location which contains existing | |
46 | repositories Kallithea will add all of the repositories at the chosen |
|
46 | repositories Kallithea will add all of the repositories at the chosen | |
47 | location to its database. (Note: make sure you specify the correct |
|
47 | location to its database. (Note: make sure you specify the correct | |
48 | path to the root). |
|
48 | path to the root). | |
49 |
|
49 | |||
50 | .. note:: the given path for Mercurial_ repositories **must** be write |
|
50 | .. note:: the given path for Mercurial_ repositories **must** be write | |
51 | accessible for the application. It's very important since |
|
51 | accessible for the application. It's very important since | |
52 | the Kallithea web interface will work without write access, |
|
52 | the Kallithea web interface will work without write access, | |
53 | but when trying to do a push it will fail with permission |
|
53 | but when trying to do a push it will fail with permission | |
54 | denied errors unless it has write access. |
|
54 | denied errors unless it has write access. | |
55 |
|
55 | |||
56 | You are now ready to use Kallithea. To run it simply execute:: |
|
56 | You are now ready to use Kallithea. To run it simply execute:: | |
57 |
|
57 | |||
58 | paster serve my.ini |
|
58 | paster serve my.ini | |
59 |
|
59 | |||
60 | - This command runs the Kallithea server. The web app should be available at |
|
60 | - This command runs the Kallithea server. The web app should be available at | |
61 | http://127.0.0.1:5000. This ip and port is configurable via the my.ini |
|
61 | http://127.0.0.1:5000. This ip and port is configurable via the my.ini | |
62 | file created in previous step |
|
62 | file created in previous step | |
63 | - Use the admin account you created above when running ``setup-db`` |
|
63 | - Use the admin account you created above when running ``setup-db`` | |
64 | to login to the web app. |
|
64 | to login to the web app. | |
65 | - The default permissions on each repository is read, and the owner is admin. |
|
65 | - The default permissions on each repository is read, and the owner is admin. | |
66 | Remember to update these if needed. |
|
66 | Remember to update these if needed. | |
67 | - In the admin panel you can toggle LDAP, anonymous, and permissions |
|
67 | - In the admin panel you can toggle LDAP, anonymous, and permissions | |
68 | settings, as well as edit more advanced options on users and |
|
68 | settings, as well as edit more advanced options on users and | |
69 | repositories |
|
69 | repositories | |
70 |
|
70 | |||
71 |
|
71 | |||
72 | Extensions |
|
72 | Extensions | |
73 | ---------- |
|
73 | ---------- | |
74 |
|
74 | |||
75 | Optionally users can create an ``rcextensions`` package that extends Kallithea |
|
75 | Optionally users can create an ``rcextensions`` package that extends Kallithea | |
76 | functionality. To do this simply execute:: |
|
76 | functionality. To do this simply execute:: | |
77 |
|
77 | |||
78 | paster make-rcext my.ini |
|
78 | paster make-rcext my.ini | |
79 |
|
79 | |||
80 | This will create an ``rcextensions`` package next to the specified ``ini`` file. |
|
80 | This will create an ``rcextensions`` package next to the specified ``ini`` file. | |
81 | With ``rcextensions`` it's possible to add additional mapping for whoosh, |
|
81 | With ``rcextensions`` it's possible to add additional mapping for whoosh, | |
82 | stats and add additional code into the push/pull/create/delete repo hooks, |
|
82 | stats and add additional code into the push/pull/create/delete repo hooks, | |
83 | for example for sending signals to build-bots such as Jenkins. |
|
83 | for example for sending signals to build-bots such as Jenkins. | |
84 |
|
84 | |||
85 | See the ``__init__.py`` file inside the generated ``rcextensions`` package |
|
85 | See the ``__init__.py`` file inside the generated ``rcextensions`` package | |
86 | for more details. |
|
86 | for more details. | |
87 |
|
87 | |||
88 |
|
88 | |||
89 | Using Kallithea with SSH |
|
89 | Using Kallithea with SSH | |
90 | ------------------------ |
|
90 | ------------------------ | |
91 |
|
91 | |||
92 | Kallithea currently only hosts repositories using http and https. (The addition |
|
92 | Kallithea currently only hosts repositories using http and https. (The addition | |
93 | of ssh hosting is a planned future feature.) However you can easily use ssh in |
|
93 | of ssh hosting is a planned future feature.) However you can easily use ssh in | |
94 | parallel with Kallithea. (Repository access via ssh is a standard "out of |
|
94 | parallel with Kallithea. (Repository access via ssh is a standard "out of | |
95 | the box" feature of Mercurial_ and you can use this to access any of the |
|
95 | the box" feature of Mercurial_ and you can use this to access any of the | |
96 | repositories that Kallithea is hosting. See PublishingRepositories_) |
|
96 | repositories that Kallithea is hosting. See PublishingRepositories_) | |
97 |
|
97 | |||
98 | Kallithea repository structures are kept in directories with the same name |
|
98 | Kallithea repository structures are kept in directories with the same name | |
99 | as the project. When using repository groups, each group is a subdirectory. |
|
99 | as the project. When using repository groups, each group is a subdirectory. | |
100 | This allows you to easily use ssh for accessing repositories. |
|
100 | This allows you to easily use ssh for accessing repositories. | |
101 |
|
101 | |||
102 | In order to use ssh you need to make sure that your web server and the users' |
|
102 | In order to use ssh you need to make sure that your web server and the users' | |
103 | login accounts have the correct permissions set on the appropriate directories. |
|
103 | login accounts have the correct permissions set on the appropriate directories. | |
104 |
|
104 | |||
105 | .. note:: These permissions are independent of any permissions you |
|
105 | .. note:: These permissions are independent of any permissions you | |
106 | have set up using the Kallithea web interface. |
|
106 | have set up using the Kallithea web interface. | |
107 |
|
107 | |||
108 | If your main directory (the same as set in Kallithea settings) is for |
|
108 | If your main directory (the same as set in Kallithea settings) is for | |
109 | example set to ``/srv/repos`` and the repository you are using is |
|
109 | example set to ``/srv/repos`` and the repository you are using is | |
110 | named ``kallithea``, then to clone via ssh you should run:: |
|
110 | named ``kallithea``, then to clone via ssh you should run:: | |
111 |
|
111 | |||
112 | hg clone ssh://user@server.com//srv/repos/kallithea |
|
112 | hg clone ssh://user@server.com//srv/repos/kallithea | |
113 |
|
113 | |||
114 | Using other external tools such as mercurial-server_ or using ssh key-based |
|
114 | Using other external tools such as mercurial-server_ or using ssh key-based | |
115 | authentication is fully supported. |
|
115 | authentication is fully supported. | |
116 |
|
116 | |||
117 | .. note:: In an advanced setup, in order for your ssh access to use |
|
117 | .. note:: In an advanced setup, in order for your ssh access to use | |
118 | the same permissions as set up via the Kallithea web |
|
118 | the same permissions as set up via the Kallithea web | |
119 | interface, you can create an authentication hook to connect |
|
119 | interface, you can create an authentication hook to connect | |
120 | to the Kallithea db and run check functions for permissions |
|
120 | to the Kallithea db and run check functions for permissions | |
121 | against that. |
|
121 | against that. | |
122 |
|
122 | |||
123 | Setting up Whoosh full text search |
|
123 | Setting up Whoosh full text search | |
124 | ---------------------------------- |
|
124 | ---------------------------------- | |
125 |
|
125 | |||
126 | The whoosh index can be built by using the paster |
|
126 | The whoosh index can be built by using the paster | |
127 | command ``make-index``. To use ``make-index`` you must specify the configuration |
|
127 | command ``make-index``. To use ``make-index`` you must specify the configuration | |
128 | file that stores the location of the index. You may specify the location of the |
|
128 | file that stores the location of the index. You may specify the location of the | |
129 | repositories (``--repo-location``). If not specified, this value is retrieved |
|
129 | repositories (``--repo-location``). If not specified, this value is retrieved | |
130 | from the Kallithea database. |
|
130 | from the Kallithea database. | |
131 | It is also possible to specify a comma separated list of |
|
131 | It is also possible to specify a comma separated list of | |
132 | repositories (``--index-only``) to build index only on chooses repositories |
|
132 | repositories (``--index-only``) to build index only on chooses repositories | |
133 | skipping any other found in repos location |
|
133 | skipping any other found in repos location | |
134 |
|
134 | |||
135 | You may optionally pass the option ``-f`` to enable a full index rebuild. Without |
|
135 | You may optionally pass the option ``-f`` to enable a full index rebuild. Without | |
136 | the ``-f`` option, indexing will run always in "incremental" mode. |
|
136 | the ``-f`` option, indexing will run always in "incremental" mode. | |
137 |
|
137 | |||
138 | For an incremental index build use:: |
|
138 | For an incremental index build use:: | |
139 |
|
139 | |||
140 | paster make-index my.ini |
|
140 | paster make-index my.ini | |
141 |
|
141 | |||
142 | For a full index rebuild use:: |
|
142 | For a full index rebuild use:: | |
143 |
|
143 | |||
144 | paster make-index my.ini -f |
|
144 | paster make-index my.ini -f | |
145 |
|
145 | |||
146 |
|
146 | |||
147 | Building an index for just selected repositories is possible with such command:: |
|
147 | Building an index for just selected repositories is possible with such command:: | |
148 |
|
148 | |||
149 | paster make-index my.ini --index-only=vcs,kallithea |
|
149 | paster make-index my.ini --index-only=vcs,kallithea | |
150 |
|
150 | |||
151 |
|
151 | |||
152 | In order to do periodic index builds and keep your index always up to |
|
152 | In order to do periodic index builds and keep your index always up to | |
153 | date, it is recommended to use a crontab entry. An example entry |
|
153 | date, it is recommended to use a crontab entry. An example entry | |
154 | might look like this:: |
|
154 | might look like this:: | |
155 |
|
155 | |||
156 | /path/to/python/bin/paster make-index /path/to/kallithea/my.ini |
|
156 | /path/to/python/bin/paster make-index /path/to/kallithea/my.ini | |
157 |
|
157 | |||
158 | When using incremental mode (the default) whoosh will check the last |
|
158 | When using incremental mode (the default) whoosh will check the last | |
159 | modification date of each file and add it to be reindexed if a newer file is |
|
159 | modification date of each file and add it to be reindexed if a newer file is | |
160 | available. The indexing daemon checks for any removed files and removes them |
|
160 | available. The indexing daemon checks for any removed files and removes them | |
161 | from index. |
|
161 | from index. | |
162 |
|
162 | |||
163 | If you want to rebuild the index from scratch, you can use the ``-f`` flag as above, |
|
163 | If you want to rebuild the index from scratch, you can use the ``-f`` flag as above, | |
164 | or in the admin panel you can check the "build from scratch" flag. |
|
164 | or in the admin panel you can check the "build from scratch" flag. | |
165 |
|
165 | |||
166 |
|
166 | |||
167 | Setting up LDAP support |
|
167 | Setting up LDAP support | |
168 | ----------------------- |
|
168 | ----------------------- | |
169 |
|
169 | |||
170 | Kallithea supports LDAP authentication. In order |
|
170 | Kallithea supports LDAP authentication. In order | |
171 | to use LDAP, you have to install the python-ldap_ package. This package is |
|
171 | to use LDAP, you have to install the python-ldap_ package. This package is | |
172 | available via pypi, so you can install it by running:: |
|
172 | available via pypi, so you can install it by running:: | |
173 |
|
173 | |||
174 | pip install python-ldap |
|
174 | pip install python-ldap | |
175 |
|
175 | |||
176 | .. note:: ``python-ldap`` requires some libraries to be installed on |
|
176 | .. note:: ``python-ldap`` requires some libraries to be installed on | |
177 | your system, so before installing it check that you have at |
|
177 | your system, so before installing it check that you have at | |
178 | least the ``openldap`` and ``sasl`` libraries. |
|
178 | least the ``openldap`` and ``sasl`` libraries. | |
179 |
|
179 | |||
180 | LDAP settings are located in the Admin->LDAP section. |
|
180 | LDAP settings are located in the Admin->LDAP section. | |
181 |
|
181 | |||
182 | Here's a typical LDAP setup:: |
|
182 | Here's a typical LDAP setup:: | |
183 |
|
183 | |||
184 | Connection settings |
|
184 | Connection settings | |
185 | Enable LDAP = checked |
|
185 | Enable LDAP = checked | |
186 | Host = host.example.org |
|
186 | Host = host.example.org | |
187 | Port = 389 |
|
187 | Port = 389 | |
188 | Account = <account> |
|
188 | Account = <account> | |
189 | Password = <password> |
|
189 | Password = <password> | |
190 | Connection Security = LDAPS connection |
|
190 | Connection Security = LDAPS connection | |
191 | Certificate Checks = DEMAND |
|
191 | Certificate Checks = DEMAND | |
192 |
|
192 | |||
193 | Search settings |
|
193 | Search settings | |
194 | Base DN = CN=users,DC=host,DC=example,DC=org |
|
194 | Base DN = CN=users,DC=host,DC=example,DC=org | |
195 | LDAP Filter = (&(objectClass=user)(!(objectClass=computer))) |
|
195 | LDAP Filter = (&(objectClass=user)(!(objectClass=computer))) | |
196 | LDAP Search Scope = SUBTREE |
|
196 | LDAP Search Scope = SUBTREE | |
197 |
|
197 | |||
198 | Attribute mappings |
|
198 | Attribute mappings | |
199 | Login Attribute = uid |
|
199 | Login Attribute = uid | |
200 | First Name Attribute = firstName |
|
200 | First Name Attribute = firstName | |
201 | Last Name Attribute = lastName |
|
201 | Last Name Attribute = lastName | |
202 | Email Attribute = mail |
|
202 | Email Attribute = mail | |
203 |
|
203 | |||
204 | If your user groups are placed in an Organisation Unit (OU) structure, the Search Settings configuration differs:: |
|
204 | If your user groups are placed in an Organisation Unit (OU) structure, the Search Settings configuration differs:: | |
205 |
|
205 | |||
206 | Search settings |
|
206 | Search settings | |
207 | Base DN = DC=host,DC=example,DC=org |
|
207 | Base DN = DC=host,DC=example,DC=org | |
208 | LDAP Filter = (&(memberOf=CN=your user group,OU=subunit,OU=unit,DC=host,DC=example,DC=org)(objectClass=user)) |
|
208 | LDAP Filter = (&(memberOf=CN=your user group,OU=subunit,OU=unit,DC=host,DC=example,DC=org)(objectClass=user)) | |
209 | LDAP Search Scope = SUBTREE |
|
209 | LDAP Search Scope = SUBTREE | |
210 |
|
210 | |||
211 | .. _enable_ldap: |
|
211 | .. _enable_ldap: | |
212 |
|
212 | |||
213 | Enable LDAP : required |
|
213 | Enable LDAP : required | |
214 | Whether to use LDAP for authenticating users. |
|
214 | Whether to use LDAP for authenticating users. | |
215 |
|
215 | |||
216 | .. _ldap_host: |
|
216 | .. _ldap_host: | |
217 |
|
217 | |||
218 | Host : required |
|
218 | Host : required | |
219 | LDAP server hostname or IP address. Can be also a comma separated |
|
219 | LDAP server hostname or IP address. Can be also a comma separated | |
220 | list of servers to support LDAP fail-over. |
|
220 | list of servers to support LDAP fail-over. | |
221 |
|
221 | |||
222 | .. _Port: |
|
222 | .. _Port: | |
223 |
|
223 | |||
224 | Port : required |
|
224 | Port : required | |
225 | 389 for un-encrypted LDAP, 636 for SSL-encrypted LDAP. |
|
225 | 389 for un-encrypted LDAP, 636 for SSL-encrypted LDAP. | |
226 |
|
226 | |||
227 | .. _ldap_account: |
|
227 | .. _ldap_account: | |
228 |
|
228 | |||
229 | Account : optional |
|
229 | Account : optional | |
230 | Only required if the LDAP server does not allow anonymous browsing of |
|
230 | Only required if the LDAP server does not allow anonymous browsing of | |
231 | records. This should be a special account for record browsing. This |
|
231 | records. This should be a special account for record browsing. This | |
232 | will require `LDAP Password`_ below. |
|
232 | will require `LDAP Password`_ below. | |
233 |
|
233 | |||
234 | .. _LDAP Password: |
|
234 | .. _LDAP Password: | |
235 |
|
235 | |||
236 | Password : optional |
|
236 | Password : optional | |
237 | Only required if the LDAP server does not allow anonymous browsing of |
|
237 | Only required if the LDAP server does not allow anonymous browsing of | |
238 | records. |
|
238 | records. | |
239 |
|
239 | |||
240 | .. _Enable LDAPS: |
|
240 | .. _Enable LDAPS: | |
241 |
|
241 | |||
242 | Connection Security : required |
|
242 | Connection Security : required | |
243 | Defines the connection to LDAP server |
|
243 | Defines the connection to LDAP server | |
244 |
|
244 | |||
245 | No encryption |
|
245 | No encryption | |
246 | Plain non encrypted connection |
|
246 | Plain non encrypted connection | |
247 |
|
247 | |||
248 | LDAPS connection |
|
248 | LDAPS connection | |
249 | Enable LDAPS connections. It will likely require `Port`_ to be set to |
|
249 | Enable LDAPS connections. It will likely require `Port`_ to be set to | |
250 | a different value (standard LDAPS port is 636). When LDAPS is enabled |
|
250 | a different value (standard LDAPS port is 636). When LDAPS is enabled | |
251 | then `Certificate Checks`_ is required. |
|
251 | then `Certificate Checks`_ is required. | |
252 |
|
252 | |||
253 | START_TLS on LDAP connection |
|
253 | START_TLS on LDAP connection | |
254 | START TLS connection |
|
254 | START TLS connection | |
255 |
|
255 | |||
256 | .. _Certificate Checks: |
|
256 | .. _Certificate Checks: | |
257 |
|
257 | |||
258 | Certificate Checks : optional |
|
258 | Certificate Checks : optional | |
259 | How SSL certificates verification is handled - this is only useful when |
|
259 | How SSL certificates verification is handled - this is only useful when | |
260 | `Enable LDAPS`_ is enabled. Only DEMAND or HARD offer full SSL security |
|
260 | `Enable LDAPS`_ is enabled. Only DEMAND or HARD offer full SSL security | |
261 | while the other options are susceptible to man-in-the-middle attacks. SSL |
|
261 | while the other options are susceptible to man-in-the-middle attacks. SSL | |
262 | certificates can be installed to /etc/openldap/cacerts so that the |
|
262 | certificates can be installed to /etc/openldap/cacerts so that the | |
263 | DEMAND or HARD options can be used with self-signed certificates or |
|
263 | DEMAND or HARD options can be used with self-signed certificates or | |
264 | certificates that do not have traceable certificates of authority. |
|
264 | certificates that do not have traceable certificates of authority. | |
265 |
|
265 | |||
266 | NEVER |
|
266 | NEVER | |
267 | A serve certificate will never be requested or checked. |
|
267 | A serve certificate will never be requested or checked. | |
268 |
|
268 | |||
269 | ALLOW |
|
269 | ALLOW | |
270 | A server certificate is requested. Failure to provide a |
|
270 | A server certificate is requested. Failure to provide a | |
271 | certificate or providing a bad certificate will not terminate the |
|
271 | certificate or providing a bad certificate will not terminate the | |
272 | session. |
|
272 | session. | |
273 |
|
273 | |||
274 | TRY |
|
274 | TRY | |
275 | A server certificate is requested. Failure to provide a |
|
275 | A server certificate is requested. Failure to provide a | |
276 | certificate does not halt the session; providing a bad certificate |
|
276 | certificate does not halt the session; providing a bad certificate | |
277 | halts the session. |
|
277 | halts the session. | |
278 |
|
278 | |||
279 | DEMAND |
|
279 | DEMAND | |
280 | A server certificate is requested and must be provided and |
|
280 | A server certificate is requested and must be provided and | |
281 | authenticated for the session to proceed. |
|
281 | authenticated for the session to proceed. | |
282 |
|
282 | |||
283 | HARD |
|
283 | HARD | |
284 | The same as DEMAND. |
|
284 | The same as DEMAND. | |
285 |
|
285 | |||
286 | .. _Base DN: |
|
286 | .. _Base DN: | |
287 |
|
287 | |||
288 | Base DN : required |
|
288 | Base DN : required | |
289 | The Distinguished Name (DN) where searches for users will be performed. |
|
289 | The Distinguished Name (DN) where searches for users will be performed. | |
290 | Searches can be controlled by `LDAP Filter`_ and `LDAP Search Scope`_. |
|
290 | Searches can be controlled by `LDAP Filter`_ and `LDAP Search Scope`_. | |
291 |
|
291 | |||
292 | .. _LDAP Filter: |
|
292 | .. _LDAP Filter: | |
293 |
|
293 | |||
294 | LDAP Filter : optional |
|
294 | LDAP Filter : optional | |
295 | A LDAP filter defined by RFC 2254. This is more useful when `LDAP |
|
295 | A LDAP filter defined by RFC 2254. This is more useful when `LDAP | |
296 | Search Scope`_ is set to SUBTREE. The filter is useful for limiting |
|
296 | Search Scope`_ is set to SUBTREE. The filter is useful for limiting | |
297 | which LDAP objects are identified as representing Users for |
|
297 | which LDAP objects are identified as representing Users for | |
298 | authentication. The filter is augmented by `Login Attribute`_ below. |
|
298 | authentication. The filter is augmented by `Login Attribute`_ below. | |
299 | This can commonly be left blank. |
|
299 | This can commonly be left blank. | |
300 |
|
300 | |||
301 | .. _LDAP Search Scope: |
|
301 | .. _LDAP Search Scope: | |
302 |
|
302 | |||
303 | LDAP Search Scope : required |
|
303 | LDAP Search Scope : required | |
304 | This limits how far LDAP will search for a matching object. |
|
304 | This limits how far LDAP will search for a matching object. | |
305 |
|
305 | |||
306 | BASE |
|
306 | BASE | |
307 | Only allows searching of `Base DN`_ and is usually not what you |
|
307 | Only allows searching of `Base DN`_ and is usually not what you | |
308 | want. |
|
308 | want. | |
309 |
|
309 | |||
310 | ONELEVEL |
|
310 | ONELEVEL | |
311 | Searches all entries under `Base DN`_, but not Base DN itself. |
|
311 | Searches all entries under `Base DN`_, but not Base DN itself. | |
312 |
|
312 | |||
313 | SUBTREE |
|
313 | SUBTREE | |
314 | Searches all entries below `Base DN`_, but not Base DN itself. |
|
314 | Searches all entries below `Base DN`_, but not Base DN itself. | |
315 | When using SUBTREE `LDAP Filter`_ is useful to limit object |
|
315 | When using SUBTREE `LDAP Filter`_ is useful to limit object | |
316 | location. |
|
316 | location. | |
317 |
|
317 | |||
318 | .. _Login Attribute: |
|
318 | .. _Login Attribute: | |
319 |
|
319 | |||
320 | Login Attribute : required |
|
320 | Login Attribute : required | |
321 | The LDAP record attribute that will be matched as the USERNAME or |
|
321 | The LDAP record attribute that will be matched as the USERNAME or | |
322 | ACCOUNT used to connect to Kallithea. This will be added to `LDAP |
|
322 | ACCOUNT used to connect to Kallithea. This will be added to `LDAP | |
323 | Filter`_ for locating the User object. If `LDAP Filter`_ is specified as |
|
323 | Filter`_ for locating the User object. If `LDAP Filter`_ is specified as | |
324 | "LDAPFILTER", `Login Attribute`_ is specified as "uid" and the user has |
|
324 | "LDAPFILTER", `Login Attribute`_ is specified as "uid" and the user has | |
325 | connected as "jsmith" then the `LDAP Filter`_ will be augmented as below |
|
325 | connected as "jsmith" then the `LDAP Filter`_ will be augmented as below | |
326 | :: |
|
326 | :: | |
327 |
|
327 | |||
328 | (&(LDAPFILTER)(uid=jsmith)) |
|
328 | (&(LDAPFILTER)(uid=jsmith)) | |
329 |
|
329 | |||
330 | .. _ldap_attr_firstname: |
|
330 | .. _ldap_attr_firstname: | |
331 |
|
331 | |||
332 | First Name Attribute : required |
|
332 | First Name Attribute : required | |
333 | The LDAP record attribute which represents the user's first name. |
|
333 | The LDAP record attribute which represents the user's first name. | |
334 |
|
334 | |||
335 | .. _ldap_attr_lastname: |
|
335 | .. _ldap_attr_lastname: | |
336 |
|
336 | |||
337 | Last Name Attribute : required |
|
337 | Last Name Attribute : required | |
338 | The LDAP record attribute which represents the user's last name. |
|
338 | The LDAP record attribute which represents the user's last name. | |
339 |
|
339 | |||
340 | .. _ldap_attr_email: |
|
340 | .. _ldap_attr_email: | |
341 |
|
341 | |||
342 | Email Attribute : required |
|
342 | Email Attribute : required | |
343 | The LDAP record attribute which represents the user's email address. |
|
343 | The LDAP record attribute which represents the user's email address. | |
344 |
|
344 | |||
345 | If all data are entered correctly, and python-ldap_ is properly installed |
|
345 | If all data are entered correctly, and python-ldap_ is properly installed | |
346 | users should be granted access to Kallithea with LDAP accounts. At this |
|
346 | users should be granted access to Kallithea with LDAP accounts. At this | |
347 | time user information is copied from LDAP into the Kallithea user database. |
|
347 | time user information is copied from LDAP into the Kallithea user database. | |
348 | This means that updates of an LDAP user object may not be reflected as a |
|
348 | This means that updates of an LDAP user object may not be reflected as a | |
349 | user update in Kallithea. |
|
349 | user update in Kallithea. | |
350 |
|
350 | |||
351 | If You have problems with LDAP access and believe You entered correct |
|
351 | If You have problems with LDAP access and believe You entered correct | |
352 | information check out the Kallithea logs, any error messages sent from LDAP |
|
352 | information check out the Kallithea logs, any error messages sent from LDAP | |
353 | will be saved there. |
|
353 | will be saved there. | |
354 |
|
354 | |||
355 | Active Directory |
|
355 | Active Directory | |
356 | '''''''''''''''' |
|
356 | '''''''''''''''' | |
357 |
|
357 | |||
358 | Kallithea can use Microsoft Active Directory for user authentication. This |
|
358 | Kallithea can use Microsoft Active Directory for user authentication. This | |
359 | is done through an LDAP or LDAPS connection to Active Directory. The |
|
359 | is done through an LDAP or LDAPS connection to Active Directory. The | |
360 | following LDAP configuration settings are typical for using Active |
|
360 | following LDAP configuration settings are typical for using Active | |
361 | Directory :: |
|
361 | Directory :: | |
362 |
|
362 | |||
363 | Base DN = OU=SBSUsers,OU=Users,OU=MyBusiness,DC=v3sys,DC=local |
|
363 | Base DN = OU=SBSUsers,OU=Users,OU=MyBusiness,DC=v3sys,DC=local | |
364 | Login Attribute = sAMAccountName |
|
364 | Login Attribute = sAMAccountName | |
365 | First Name Attribute = givenName |
|
365 | First Name Attribute = givenName | |
366 | Last Name Attribute = sn |
|
366 | Last Name Attribute = sn | |
367 | Email Attribute = mail |
|
367 | Email Attribute = mail | |
368 |
|
368 | |||
369 | All other LDAP settings will likely be site-specific and should be |
|
369 | All other LDAP settings will likely be site-specific and should be | |
370 | appropriately configured. |
|
370 | appropriately configured. | |
371 |
|
371 | |||
372 |
|
372 | |||
373 | Authentication by container or reverse-proxy |
|
373 | Authentication by container or reverse-proxy | |
374 | -------------------------------------------- |
|
374 | -------------------------------------------- | |
375 |
|
375 | |||
376 | Kallithea supports delegating the authentication |
|
376 | Kallithea supports delegating the authentication | |
377 | of users to its WSGI container, or to a reverse-proxy server through which all |
|
377 | of users to its WSGI container, or to a reverse-proxy server through which all | |
378 | clients access the application. |
|
378 | clients access the application. | |
379 |
|
379 | |||
380 | When these authentication methods are enabled in Kallithea, it uses the |
|
380 | When these authentication methods are enabled in Kallithea, it uses the | |
381 | username that the container/proxy (Apache/Nginx/etc) authenticated and doesn't |
|
381 | username that the container/proxy (Apache/Nginx/etc) authenticated and doesn't | |
382 | perform the authentication itself. The authorization, however, is still done by |
|
382 | perform the authentication itself. The authorization, however, is still done by | |
383 | Kallithea according to its settings. |
|
383 | Kallithea according to its settings. | |
384 |
|
384 | |||
385 | When a user logs in for the first time using these authentication methods, |
|
385 | When a user logs in for the first time using these authentication methods, | |
386 | a matching user account is created in Kallithea with default permissions. An |
|
386 | a matching user account is created in Kallithea with default permissions. An | |
387 | administrator can then modify it using Kallithea's admin interface. |
|
387 | administrator can then modify it using Kallithea's admin interface. | |
388 | It's also possible for an administrator to create accounts and configure their |
|
388 | It's also possible for an administrator to create accounts and configure their | |
389 | permissions before the user logs in for the first time. |
|
389 | permissions before the user logs in for the first time. | |
390 |
|
390 | |||
391 |
|
391 | |||
392 | Container-based authentication |
|
392 | Container-based authentication | |
393 | '''''''''''''''''''''''''''''' |
|
393 | '''''''''''''''''''''''''''''' | |
394 |
|
394 | |||
395 | In a container-based authentication setup, Kallithea reads the user name from |
|
395 | In a container-based authentication setup, Kallithea reads the user name from | |
396 | the ``REMOTE_USER`` server variable provided by the WSGI container. |
|
396 | the ``REMOTE_USER`` server variable provided by the WSGI container. | |
397 |
|
397 | |||
398 | After setting up your container (see `Apache's WSGI config`_), you'd need |
|
398 | After setting up your container (see `Apache's WSGI config`_), you'd need | |
399 | to configure it to require authentication on the location configured for |
|
399 | to configure it to require authentication on the location configured for | |
400 | Kallithea. |
|
400 | Kallithea. | |
401 |
|
401 | |||
402 |
|
402 | |||
403 | Proxy pass-through authentication |
|
403 | Proxy pass-through authentication | |
404 | ''''''''''''''''''''''''''''''''' |
|
404 | ''''''''''''''''''''''''''''''''' | |
405 |
|
405 | |||
406 | In a proxy pass-through authentication setup, Kallithea reads the user name |
|
406 | In a proxy pass-through authentication setup, Kallithea reads the user name | |
407 | from the ``X-Forwarded-User`` request header, which should be configured to be |
|
407 | from the ``X-Forwarded-User`` request header, which should be configured to be | |
408 | sent by the reverse-proxy server. |
|
408 | sent by the reverse-proxy server. | |
409 |
|
409 | |||
410 | After setting up your proxy solution (see `Apache virtual host reverse proxy example`_, |
|
410 | After setting up your proxy solution (see `Apache virtual host reverse proxy example`_, | |
411 | `Apache as subdirectory`_ or `Nginx virtual host example`_), you'd need to |
|
411 | `Apache as subdirectory`_ or `Nginx virtual host example`_), you'd need to | |
412 | configure the authentication and add the username in a request header named |
|
412 | configure the authentication and add the username in a request header named | |
413 | ``X-Forwarded-User``. |
|
413 | ``X-Forwarded-User``. | |
414 |
|
414 | |||
415 | For example, the following config section for Apache sets a subdirectory in a |
|
415 | For example, the following config section for Apache sets a subdirectory in a | |
416 | reverse-proxy setup with basic auth:: |
|
416 | reverse-proxy setup with basic auth:: | |
417 |
|
417 | |||
418 | <Location /<someprefix> > |
|
418 | <Location /<someprefix> > | |
419 | ProxyPass http://127.0.0.1:5000/<someprefix> |
|
419 | ProxyPass http://127.0.0.1:5000/<someprefix> | |
420 | ProxyPassReverse http://127.0.0.1:5000/<someprefix> |
|
420 | ProxyPassReverse http://127.0.0.1:5000/<someprefix> | |
421 | SetEnvIf X-Url-Scheme https HTTPS=1 |
|
421 | SetEnvIf X-Url-Scheme https HTTPS=1 | |
422 |
|
422 | |||
423 | AuthType Basic |
|
423 | AuthType Basic | |
424 | AuthName "Kallithea authentication" |
|
424 | AuthName "Kallithea authentication" | |
425 | AuthUserFile /srv/kallithea/.htpasswd |
|
425 | AuthUserFile /srv/kallithea/.htpasswd | |
426 | require valid-user |
|
426 | require valid-user | |
427 |
|
427 | |||
428 | RequestHeader unset X-Forwarded-User |
|
428 | RequestHeader unset X-Forwarded-User | |
429 |
|
429 | |||
430 | RewriteEngine On |
|
430 | RewriteEngine On | |
431 | RewriteCond %{LA-U:REMOTE_USER} (.+) |
|
431 | RewriteCond %{LA-U:REMOTE_USER} (.+) | |
432 | RewriteRule .* - [E=RU:%1] |
|
432 | RewriteRule .* - [E=RU:%1] | |
433 | RequestHeader set X-Forwarded-User %{RU}e |
|
433 | RequestHeader set X-Forwarded-User %{RU}e | |
434 | </Location> |
|
434 | </Location> | |
435 |
|
435 | |||
436 |
|
436 | |||
437 | .. note:: |
|
437 | .. note:: | |
438 | If you enable proxy pass-through authentication, make sure your server is |
|
438 | If you enable proxy pass-through authentication, make sure your server is | |
439 | only accessible through the proxy. Otherwise, any client would be able to |
|
439 | only accessible through the proxy. Otherwise, any client would be able to | |
440 | forge the authentication header and could effectively become authenticated |
|
440 | forge the authentication header and could effectively become authenticated | |
441 | using any account of their liking. |
|
441 | using any account of their liking. | |
442 |
|
442 | |||
443 | Integration with Issue trackers |
|
443 | ||
|
444 | Integration with issue trackers | |||
444 | ------------------------------- |
|
445 | ------------------------------- | |
445 |
|
446 | |||
446 | Kallithea provides a simple integration with issue trackers. It's possible |
|
447 | Kallithea provides a simple integration with issue trackers. It's possible | |
447 | to define a regular expression that will fetch an issue id stored in a commit |
|
448 | to define a regular expression that will fetch an issue id stored in a commit | |
448 | messages and replace that with a URL to the issue. To enable this simply |
|
449 | messages and replace that with a URL to the issue. To enable this simply | |
449 | uncomment the following variables in the ini file:: |
|
450 | uncomment the following variables in the ini file:: | |
450 |
|
451 | |||
451 | issue_pat = (?:^#|\s#)(\w+) |
|
452 | issue_pat = (?:^#|\s#)(\w+) | |
452 | issue_server_link = https://myissueserver.com/{repo}/issue/{id} |
|
453 | issue_server_link = https://myissueserver.com/{repo}/issue/{id} | |
453 | issue_prefix = # |
|
454 | issue_prefix = # | |
454 |
|
455 | |||
455 | ``issue_pat`` is the regular expression describing which strings in |
|
456 | ``issue_pat`` is the regular expression describing which strings in | |
456 | commit messages will be treated as issue references. A match group in |
|
457 | commit messages will be treated as issue references. A match group in | |
457 | parentheses should be used to specify the actual issue id. |
|
458 | parentheses should be used to specify the actual issue id. | |
458 |
|
459 | |||
459 | The default expression matches issues in the format ``#<number>``, e.g., ``#300``. |
|
460 | The default expression matches issues in the format ``#<number>``, e.g., ``#300``. | |
460 |
|
461 | |||
461 | Matched issues are replaced with the link specified as |
|
462 | Matched issues are replaced with the link specified as | |
462 | ``issue_server_link`` ``{id}`` is replaced with issue id, and |
|
463 | ``issue_server_link`` ``{id}`` is replaced with issue id, and | |
463 | ``{repo}`` with the repository name. Since the # is stripped away, |
|
464 | ``{repo}`` with the repository name. Since the # is stripped away, | |
464 | ``issue_prefix`` is prepended to the link text. ``issue_prefix`` doesn't |
|
465 | ``issue_prefix`` is prepended to the link text. ``issue_prefix`` doesn't | |
465 | necessarily need to be ``#``: if you set issue prefix to ``ISSUE-`` this will |
|
466 | necessarily need to be ``#``: if you set issue prefix to ``ISSUE-`` this will | |
466 | generate a URL in the format:: |
|
467 | generate a URL in the format:: | |
467 |
|
468 | |||
468 | <a href="https://myissueserver.com/example_repo/issue/300">ISSUE-300</a> |
|
469 | <a href="https://myissueserver.com/example_repo/issue/300">ISSUE-300</a> | |
469 |
|
470 | |||
470 | If needed, more than one pattern can be specified by appending a unique suffix to |
|
471 | If needed, more than one pattern can be specified by appending a unique suffix to | |
471 | the variables. For example:: |
|
472 | the variables. For example:: | |
472 |
|
473 | |||
473 | issue_pat_wiki = (?:wiki-)(.+) |
|
474 | issue_pat_wiki = (?:wiki-)(.+) | |
474 | issue_server_link_wiki = https://mywiki.com/{id} |
|
475 | issue_server_link_wiki = https://mywiki.com/{id} | |
475 | issue_prefix_wiki = WIKI- |
|
476 | issue_prefix_wiki = WIKI- | |
476 |
|
477 | |||
477 | With these settings, wiki pages can be referenced as wiki-some-id, and every |
|
478 | With these settings, wiki pages can be referenced as wiki-some-id, and every | |
478 | such reference will be transformed into:: |
|
479 | such reference will be transformed into:: | |
479 |
|
480 | |||
480 | <a href="https://mywiki.com/some-id">WIKI-some-id</a> |
|
481 | <a href="https://mywiki.com/some-id">WIKI-some-id</a> | |
481 |
|
482 | |||
482 |
|
483 | |||
483 | Hook management |
|
484 | Hook management | |
484 | --------------- |
|
485 | --------------- | |
485 |
|
486 | |||
486 | Hooks can be managed in similar way to that used in ``.hgrc`` files. |
|
487 | Hooks can be managed in similar way to that used in ``.hgrc`` files. | |
487 | To access hooks setting click `advanced setup` in the `Hooks` section |
|
488 | To access hooks setting click `advanced setup` in the `Hooks` section | |
488 | of Mercurial Settings in Admin. |
|
489 | of Mercurial Settings in Admin. | |
489 |
|
490 | |||
490 | There are four built in hooks that cannot be changed (only enabled/disabled by |
|
491 | There are four built in hooks that cannot be changed (only enabled/disabled by | |
491 | checkboxes in the previous section). |
|
492 | checkboxes in the previous section). | |
492 | To add another custom hook simply fill in the first section with |
|
493 | To add another custom hook simply fill in the first section with | |
493 | ``<name>.<hook_type>`` and the second one with hook path. Example hooks |
|
494 | ``<name>.<hook_type>`` and the second one with hook path. Example hooks | |
494 | can be found in ``kallithea.lib.hooks``. |
|
495 | can be found in ``kallithea.lib.hooks``. | |
495 |
|
496 | |||
496 |
|
497 | |||
497 | Changing default encoding |
|
498 | Changing default encoding | |
498 | ------------------------- |
|
499 | ------------------------- | |
499 |
|
500 | |||
500 | By default, Kallithea uses UTF-8 encoding. |
|
501 | By default, Kallithea uses UTF-8 encoding. | |
501 | This is configurable as ``default_encoding`` in the .ini file. |
|
502 | This is configurable as ``default_encoding`` in the .ini file. | |
502 | This affects many parts in Kallithea including user names, filenames, and |
|
503 | This affects many parts in Kallithea including user names, filenames, and | |
503 | encoding of commit messages. In addition Kallithea can detect if the ``chardet`` |
|
504 | encoding of commit messages. In addition Kallithea can detect if the ``chardet`` | |
504 | library is installed. If ``chardet`` is detected Kallithea will fallback to it |
|
505 | library is installed. If ``chardet`` is detected Kallithea will fallback to it | |
505 | when there are encode/decode errors. |
|
506 | when there are encode/decode errors. | |
506 |
|
507 | |||
507 |
|
508 | |||
508 | Celery configuration |
|
509 | Celery configuration | |
509 | -------------------- |
|
510 | -------------------- | |
510 |
|
511 | |||
511 | Kallithea can use the distributed task queue system Celery_ to run tasks like |
|
512 | Kallithea can use the distributed task queue system Celery_ to run tasks like | |
512 | cloning repositories or sending emails. |
|
513 | cloning repositories or sending emails. | |
513 |
|
514 | |||
514 | Kallithea will in most setups work perfectly fine out of the box (without |
|
515 | Kallithea will in most setups work perfectly fine out of the box (without | |
515 | Celery), executing all tasks in the web server process. Some tasks can however |
|
516 | Celery), executing all tasks in the web server process. Some tasks can however | |
516 | take some time to run and it can be better to run such tasks asynchronously in |
|
517 | take some time to run and it can be better to run such tasks asynchronously in | |
517 | a separate process so the web server can focus on serving web requests. |
|
518 | a separate process so the web server can focus on serving web requests. | |
518 |
|
519 | |||
519 | For installation and configuration of Celery, see the `Celery documentation`_. |
|
520 | For installation and configuration of Celery, see the `Celery documentation`_. | |
520 | Note that Celery requires a message broker service like RabbitMQ_ (recommended) |
|
521 | Note that Celery requires a message broker service like RabbitMQ_ (recommended) | |
521 | or Redis_. |
|
522 | or Redis_. | |
522 |
|
523 | |||
523 | The use of Celery is configured in the Kallithea ini configuration file. |
|
524 | The use of Celery is configured in the Kallithea ini configuration file. | |
524 | To enable it, simply set:: |
|
525 | To enable it, simply set:: | |
525 |
|
526 | |||
526 | use_celery = true |
|
527 | use_celery = true | |
527 |
|
528 | |||
528 | and add or change the ``celery.*`` and ``broker.*`` configuration variables. |
|
529 | and add or change the ``celery.*`` and ``broker.*`` configuration variables. | |
529 |
|
530 | |||
530 | Remember that the ini files use the format with '.' and not with '_' like |
|
531 | Remember that the ini files use the format with '.' and not with '_' like | |
531 | Celery. So for example setting `BROKER_HOST` in Celery means setting |
|
532 | Celery. So for example setting `BROKER_HOST` in Celery means setting | |
532 | `broker.host` in the configuration file. |
|
533 | `broker.host` in the configuration file. | |
533 |
|
534 | |||
534 | To start the Celery process, run:: |
|
535 | To start the Celery process, run:: | |
535 |
|
536 | |||
536 | paster celeryd <configfile.ini> |
|
537 | paster celeryd <configfile.ini> | |
537 |
|
538 | |||
538 |
|
539 | |||
539 | .. note:: |
|
540 | .. note:: | |
540 | Make sure you run this command from the same virtualenv, and with the same |
|
541 | Make sure you run this command from the same virtualenv, and with the same | |
541 | user that Kallithea runs. |
|
542 | user that Kallithea runs. | |
542 |
|
543 | |||
543 | HTTPS support |
|
544 | HTTPS support | |
544 | ------------- |
|
545 | ------------- | |
545 |
|
546 | |||
546 | Kallithea will by default generate URLs based on the WSGI environment. |
|
547 | Kallithea will by default generate URLs based on the WSGI environment. | |
547 |
|
548 | |||
548 | Alternatively, you can use some special configuration settings to control |
|
549 | Alternatively, you can use some special configuration settings to control | |
549 | directly which scheme/protocol Kallithea will use when generating URLs: |
|
550 | directly which scheme/protocol Kallithea will use when generating URLs: | |
550 |
|
551 | |||
551 | - With ``https_fixup = true``, the scheme will be taken from the ``HTTP_X_URL_SCHEME``, |
|
552 | - With ``https_fixup = true``, the scheme will be taken from the ``HTTP_X_URL_SCHEME``, | |
552 | ``HTTP_X_FORWARDED_SCHEME`` or ``HTTP_X_FORWARDED_PROTO HTTP`` header (default ``http``). |
|
553 | ``HTTP_X_FORWARDED_SCHEME`` or ``HTTP_X_FORWARDED_PROTO HTTP`` header (default ``http``). | |
553 | - With ``force_https = true`` the default will be ``https``. |
|
554 | - With ``force_https = true`` the default will be ``https``. | |
554 | - With ``use_htsts = true``, it will set ``Strict-Transport-Security`` when using https. |
|
555 | - With ``use_htsts = true``, it will set ``Strict-Transport-Security`` when using https. | |
555 |
|
556 | |||
556 | Nginx virtual host example |
|
557 | Nginx virtual host example | |
557 | -------------------------- |
|
558 | -------------------------- | |
558 |
|
559 | |||
559 | Sample config for nginx using proxy:: |
|
560 | Sample config for nginx using proxy:: | |
560 |
|
561 | |||
561 | upstream kallithea { |
|
562 | upstream kallithea { | |
562 | server 127.0.0.1:5000; |
|
563 | server 127.0.0.1:5000; | |
563 | # add more instances for load balancing |
|
564 | # add more instances for load balancing | |
564 | #server 127.0.0.1:5001; |
|
565 | #server 127.0.0.1:5001; | |
565 | #server 127.0.0.1:5002; |
|
566 | #server 127.0.0.1:5002; | |
566 | } |
|
567 | } | |
567 |
|
568 | |||
568 | ## gist alias |
|
569 | ## gist alias | |
569 | server { |
|
570 | server { | |
570 | listen 443; |
|
571 | listen 443; | |
571 | server_name gist.myserver.com; |
|
572 | server_name gist.myserver.com; | |
572 | access_log /var/log/nginx/gist.access.log; |
|
573 | access_log /var/log/nginx/gist.access.log; | |
573 | error_log /var/log/nginx/gist.error.log; |
|
574 | error_log /var/log/nginx/gist.error.log; | |
574 |
|
575 | |||
575 | ssl on; |
|
576 | ssl on; | |
576 | ssl_certificate gist.your.kallithea.server.crt; |
|
577 | ssl_certificate gist.your.kallithea.server.crt; | |
577 | ssl_certificate_key gist.your.kallithea.server.key; |
|
578 | ssl_certificate_key gist.your.kallithea.server.key; | |
578 |
|
579 | |||
579 | ssl_session_timeout 5m; |
|
580 | ssl_session_timeout 5m; | |
580 |
|
581 | |||
581 | ssl_protocols SSLv3 TLSv1; |
|
582 | ssl_protocols SSLv3 TLSv1; | |
582 | 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; |
|
583 | 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; | |
583 | ssl_prefer_server_ciphers on; |
|
584 | ssl_prefer_server_ciphers on; | |
584 |
|
585 | |||
585 | rewrite ^/(.+)$ https://your.kallithea.server/_admin/gists/$1; |
|
586 | rewrite ^/(.+)$ https://your.kallithea.server/_admin/gists/$1; | |
586 | rewrite (.*) https://your.kallithea.server/_admin/gists; |
|
587 | rewrite (.*) https://your.kallithea.server/_admin/gists; | |
587 | } |
|
588 | } | |
588 |
|
589 | |||
589 | server { |
|
590 | server { | |
590 | listen 443; |
|
591 | listen 443; | |
591 | server_name your.kallithea.server; |
|
592 | server_name your.kallithea.server; | |
592 | access_log /var/log/nginx/kallithea.access.log; |
|
593 | access_log /var/log/nginx/kallithea.access.log; | |
593 | error_log /var/log/nginx/kallithea.error.log; |
|
594 | error_log /var/log/nginx/kallithea.error.log; | |
594 |
|
595 | |||
595 | ssl on; |
|
596 | ssl on; | |
596 | ssl_certificate your.kallithea.server.crt; |
|
597 | ssl_certificate your.kallithea.server.crt; | |
597 | ssl_certificate_key your.kallithea.server.key; |
|
598 | ssl_certificate_key your.kallithea.server.key; | |
598 |
|
599 | |||
599 | ssl_session_timeout 5m; |
|
600 | ssl_session_timeout 5m; | |
600 |
|
601 | |||
601 | ssl_protocols SSLv3 TLSv1; |
|
602 | ssl_protocols SSLv3 TLSv1; | |
602 | 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; |
|
603 | 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; | |
603 | ssl_prefer_server_ciphers on; |
|
604 | ssl_prefer_server_ciphers on; | |
604 |
|
605 | |||
605 | ## uncomment root directive if you want to serve static files by nginx |
|
606 | ## uncomment root directive if you want to serve static files by nginx | |
606 | ## requires static_files = false in .ini file |
|
607 | ## requires static_files = false in .ini file | |
607 | #root /path/to/installation/kallithea/public; |
|
608 | #root /path/to/installation/kallithea/public; | |
608 | include /etc/nginx/proxy.conf; |
|
609 | include /etc/nginx/proxy.conf; | |
609 | location / { |
|
610 | location / { | |
610 | try_files $uri @kallithea; |
|
611 | try_files $uri @kallithea; | |
611 | } |
|
612 | } | |
612 |
|
613 | |||
613 | location @kallithea { |
|
614 | location @kallithea { | |
614 | proxy_pass http://kallithea; |
|
615 | proxy_pass http://kallithea; | |
615 | } |
|
616 | } | |
616 |
|
617 | |||
617 | } |
|
618 | } | |
618 |
|
619 | |||
619 | Here's the proxy.conf. It's tuned so it will not timeout on long |
|
620 | Here's the proxy.conf. It's tuned so it will not timeout on long | |
620 | pushes or large pushes:: |
|
621 | pushes or large pushes:: | |
621 |
|
622 | |||
622 | proxy_redirect off; |
|
623 | proxy_redirect off; | |
623 | proxy_set_header Host $host; |
|
624 | proxy_set_header Host $host; | |
624 | ## needed for container auth |
|
625 | ## needed for container auth | |
625 | #proxy_set_header REMOTE_USER $remote_user; |
|
626 | #proxy_set_header REMOTE_USER $remote_user; | |
626 | #proxy_set_header X-Forwarded-User $remote_user; |
|
627 | #proxy_set_header X-Forwarded-User $remote_user; | |
627 | proxy_set_header X-Url-Scheme $scheme; |
|
628 | proxy_set_header X-Url-Scheme $scheme; | |
628 | proxy_set_header X-Host $http_host; |
|
629 | proxy_set_header X-Host $http_host; | |
629 | proxy_set_header X-Real-IP $remote_addr; |
|
630 | proxy_set_header X-Real-IP $remote_addr; | |
630 | proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; |
|
631 | proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; | |
631 | proxy_set_header Proxy-host $proxy_host; |
|
632 | proxy_set_header Proxy-host $proxy_host; | |
632 | proxy_buffering off; |
|
633 | proxy_buffering off; | |
633 | proxy_connect_timeout 7200; |
|
634 | proxy_connect_timeout 7200; | |
634 | proxy_send_timeout 7200; |
|
635 | proxy_send_timeout 7200; | |
635 | proxy_read_timeout 7200; |
|
636 | proxy_read_timeout 7200; | |
636 | proxy_buffers 8 32k; |
|
637 | proxy_buffers 8 32k; | |
637 | client_max_body_size 1024m; |
|
638 | client_max_body_size 1024m; | |
638 | client_body_buffer_size 128k; |
|
639 | client_body_buffer_size 128k; | |
639 | large_client_header_buffers 8 64k; |
|
640 | large_client_header_buffers 8 64k; | |
640 |
|
641 | |||
641 |
|
642 | |||
642 | Apache virtual host reverse proxy example |
|
643 | Apache virtual host reverse proxy example | |
643 | ----------------------------------------- |
|
644 | ----------------------------------------- | |
644 |
|
645 | |||
645 | Here is a sample configuration file for apache using proxy:: |
|
646 | Here is a sample configuration file for apache using proxy:: | |
646 |
|
647 | |||
647 | <VirtualHost *:80> |
|
648 | <VirtualHost *:80> | |
648 | ServerName hg.myserver.com |
|
649 | ServerName hg.myserver.com | |
649 | ServerAlias hg.myserver.com |
|
650 | ServerAlias hg.myserver.com | |
650 |
|
651 | |||
651 | <Proxy *> |
|
652 | <Proxy *> | |
652 | Order allow,deny |
|
653 | Order allow,deny | |
653 | Allow from all |
|
654 | Allow from all | |
654 | </Proxy> |
|
655 | </Proxy> | |
655 |
|
656 | |||
656 | #important ! |
|
657 | #important ! | |
657 | #Directive to properly generate url (clone url) for pylons |
|
658 | #Directive to properly generate url (clone url) for pylons | |
658 | ProxyPreserveHost On |
|
659 | ProxyPreserveHost On | |
659 |
|
660 | |||
660 | #kallithea instance |
|
661 | #kallithea instance | |
661 | ProxyPass / http://127.0.0.1:5000/ |
|
662 | ProxyPass / http://127.0.0.1:5000/ | |
662 | ProxyPassReverse / http://127.0.0.1:5000/ |
|
663 | ProxyPassReverse / http://127.0.0.1:5000/ | |
663 |
|
664 | |||
664 | #to enable https use line below |
|
665 | #to enable https use line below | |
665 | #SetEnvIf X-Url-Scheme https HTTPS=1 |
|
666 | #SetEnvIf X-Url-Scheme https HTTPS=1 | |
666 |
|
667 | |||
667 | </VirtualHost> |
|
668 | </VirtualHost> | |
668 |
|
669 | |||
669 |
|
670 | |||
670 | Additional tutorial |
|
671 | Additional tutorial | |
671 | http://pylonsbook.com/en/1.1/deployment.html#using-apache-to-proxy-requests-to-pylons |
|
672 | http://pylonsbook.com/en/1.1/deployment.html#using-apache-to-proxy-requests-to-pylons | |
672 |
|
673 | |||
673 |
|
674 | |||
674 | Apache as subdirectory |
|
675 | Apache as subdirectory | |
675 | ---------------------- |
|
676 | ---------------------- | |
676 |
|
677 | |||
677 | Apache subdirectory part:: |
|
678 | Apache subdirectory part:: | |
678 |
|
679 | |||
679 | <Location /<someprefix> > |
|
680 | <Location /<someprefix> > | |
680 | ProxyPass http://127.0.0.1:5000/<someprefix> |
|
681 | ProxyPass http://127.0.0.1:5000/<someprefix> | |
681 | ProxyPassReverse http://127.0.0.1:5000/<someprefix> |
|
682 | ProxyPassReverse http://127.0.0.1:5000/<someprefix> | |
682 | SetEnvIf X-Url-Scheme https HTTPS=1 |
|
683 | SetEnvIf X-Url-Scheme https HTTPS=1 | |
683 | </Location> |
|
684 | </Location> | |
684 |
|
685 | |||
685 | Besides the regular apache setup you will need to add the following line |
|
686 | Besides the regular apache setup you will need to add the following line | |
686 | into ``[app:main]`` section of your .ini file:: |
|
687 | into ``[app:main]`` section of your .ini file:: | |
687 |
|
688 | |||
688 | filter-with = proxy-prefix |
|
689 | filter-with = proxy-prefix | |
689 |
|
690 | |||
690 | Add the following at the end of the .ini file:: |
|
691 | Add the following at the end of the .ini file:: | |
691 |
|
692 | |||
692 | [filter:proxy-prefix] |
|
693 | [filter:proxy-prefix] | |
693 | use = egg:PasteDeploy#prefix |
|
694 | use = egg:PasteDeploy#prefix | |
694 | prefix = /<someprefix> |
|
695 | prefix = /<someprefix> | |
695 |
|
696 | |||
696 |
|
697 | |||
697 | then change ``<someprefix>`` into your chosen prefix |
|
698 | then change ``<someprefix>`` into your chosen prefix | |
698 |
|
699 | |||
699 | Apache's WSGI config |
|
700 | Apache's WSGI config | |
700 | -------------------- |
|
701 | -------------------- | |
701 |
|
702 | |||
702 | Alternatively, Kallithea can be set up with Apache under mod_wsgi. For |
|
703 | Alternatively, Kallithea can be set up with Apache under mod_wsgi. For | |
703 | that, you'll need to: |
|
704 | that, you'll need to: | |
704 |
|
705 | |||
705 | - Install mod_wsgi. If using a Debian-based distro, you can install |
|
706 | - Install mod_wsgi. If using a Debian-based distro, you can install | |
706 | the package libapache2-mod-wsgi:: |
|
707 | the package libapache2-mod-wsgi:: | |
707 |
|
708 | |||
708 | aptitude install libapache2-mod-wsgi |
|
709 | aptitude install libapache2-mod-wsgi | |
709 |
|
710 | |||
710 | - Enable mod_wsgi:: |
|
711 | - Enable mod_wsgi:: | |
711 |
|
712 | |||
712 | a2enmod wsgi |
|
713 | a2enmod wsgi | |
713 |
|
714 | |||
714 | - Create a wsgi dispatch script, like the one below. Make sure you |
|
715 | - Create a wsgi dispatch script, like the one below. Make sure you | |
715 | check that the paths correctly point to where you installed Kallithea |
|
716 | check that the paths correctly point to where you installed Kallithea | |
716 | and its Python Virtual Environment. |
|
717 | and its Python Virtual Environment. | |
717 | - Enable the ``WSGIScriptAlias`` directive for the WSGI dispatch script, |
|
718 | - Enable the ``WSGIScriptAlias`` directive for the WSGI dispatch script, | |
718 | as in the following example. Once again, check the paths are |
|
719 | as in the following example. Once again, check the paths are | |
719 | correctly specified. |
|
720 | correctly specified. | |
720 |
|
721 | |||
721 | Here is a sample excerpt from an Apache Virtual Host configuration file:: |
|
722 | Here is a sample excerpt from an Apache Virtual Host configuration file:: | |
722 |
|
723 | |||
723 | WSGIDaemonProcess kallithea \ |
|
724 | WSGIDaemonProcess kallithea \ | |
724 | processes=1 threads=4 \ |
|
725 | processes=1 threads=4 \ | |
725 | python-path=/srv/kallithea/pyenv/lib/python2.7/site-packages |
|
726 | python-path=/srv/kallithea/pyenv/lib/python2.7/site-packages | |
726 | WSGIScriptAlias / /srv/kallithea/dispatch.wsgi |
|
727 | WSGIScriptAlias / /srv/kallithea/dispatch.wsgi | |
727 | WSGIPassAuthorization On |
|
728 | WSGIPassAuthorization On | |
728 |
|
729 | |||
729 | Or if using a dispatcher WSGI script with proper virtualenv activation:: |
|
730 | Or if using a dispatcher WSGI script with proper virtualenv activation:: | |
730 |
|
731 | |||
731 | WSGIDaemonProcess kallithea processes=1 threads=4 |
|
732 | WSGIDaemonProcess kallithea processes=1 threads=4 | |
732 | WSGIScriptAlias / /srv/kallithea/dispatch.wsgi |
|
733 | WSGIScriptAlias / /srv/kallithea/dispatch.wsgi | |
733 | WSGIPassAuthorization On |
|
734 | WSGIPassAuthorization On | |
734 |
|
735 | |||
735 |
|
736 | |||
736 | .. note:: |
|
737 | .. note:: | |
737 | When running apache as root, please make sure it doesn't run Kallithea as |
|
738 | When running apache as root, please make sure it doesn't run Kallithea as | |
738 | root, for examply by adding: ``user=www-data group=www-data`` to the configuration. |
|
739 | root, for examply by adding: ``user=www-data group=www-data`` to the configuration. | |
739 |
|
740 | |||
740 | .. note:: |
|
741 | .. note:: | |
741 | If running Kallithea in multiprocess mode, |
|
742 | If running Kallithea in multiprocess mode, | |
742 | make sure you set ``instance_id = *`` in the configuration so each process |
|
743 | make sure you set ``instance_id = *`` in the configuration so each process | |
743 | gets it's own cache invalidation key. |
|
744 | gets it's own cache invalidation key. | |
744 |
|
745 | |||
745 |
|
746 | |||
746 | Example WSGI dispatch script:: |
|
747 | Example WSGI dispatch script:: | |
747 |
|
748 | |||
748 | import os |
|
749 | import os | |
749 | os.environ["HGENCODING"] = "UTF-8" |
|
750 | os.environ["HGENCODING"] = "UTF-8" | |
750 | os.environ['PYTHON_EGG_CACHE'] = '/srv/kallithea/.egg-cache' |
|
751 | os.environ['PYTHON_EGG_CACHE'] = '/srv/kallithea/.egg-cache' | |
751 |
|
752 | |||
752 | # sometimes it's needed to set the curent dir |
|
753 | # sometimes it's needed to set the curent dir | |
753 | os.chdir('/srv/kallithea/') |
|
754 | os.chdir('/srv/kallithea/') | |
754 |
|
755 | |||
755 | import site |
|
756 | import site | |
756 | site.addsitedir("/srv/kallithea/pyenv/lib/python2.7/site-packages") |
|
757 | site.addsitedir("/srv/kallithea/pyenv/lib/python2.7/site-packages") | |
757 |
|
758 | |||
758 | from paste.deploy import loadapp |
|
759 | from paste.deploy import loadapp | |
759 | from paste.script.util.logging_config import fileConfig |
|
760 | from paste.script.util.logging_config import fileConfig | |
760 |
|
761 | |||
761 | fileConfig('/srv/kallithea/my.ini') |
|
762 | fileConfig('/srv/kallithea/my.ini') | |
762 | application = loadapp('config:/srv/kallithea/my.ini') |
|
763 | application = loadapp('config:/srv/kallithea/my.ini') | |
763 |
|
764 | |||
764 | Or using proper virtualenv activation:: |
|
765 | Or using proper virtualenv activation:: | |
765 |
|
766 | |||
766 | activate_this = '/srv/kallithea/venv/bin/activate_this.py' |
|
767 | activate_this = '/srv/kallithea/venv/bin/activate_this.py' | |
767 | execfile(activate_this,dict(__file__=activate_this)) |
|
768 | execfile(activate_this,dict(__file__=activate_this)) | |
768 |
|
769 | |||
769 | import os |
|
770 | import os | |
770 | os.environ['HOME'] = '/srv/kallithea' |
|
771 | os.environ['HOME'] = '/srv/kallithea' | |
771 |
|
772 | |||
772 | ini = '/srv/kallithea/kallithea.ini' |
|
773 | ini = '/srv/kallithea/kallithea.ini' | |
773 | from paste.script.util.logging_config import fileConfig |
|
774 | from paste.script.util.logging_config import fileConfig | |
774 | fileConfig(ini) |
|
775 | fileConfig(ini) | |
775 | from paste.deploy import loadapp |
|
776 | from paste.deploy import loadapp | |
776 | application = loadapp('config:' + ini) |
|
777 | application = loadapp('config:' + ini) | |
777 |
|
778 | |||
778 |
|
779 | |||
779 | Other configuration files |
|
780 | Other configuration files | |
780 | ------------------------- |
|
781 | ------------------------- | |
781 |
|
782 | |||
782 | Some example init.d scripts can be found in the ``init.d`` directory: |
|
783 | Some example init.d scripts can be found in the ``init.d`` directory: | |
783 | https://kallithea-scm.org/repos/kallithea/files/tip/init.d/ . |
|
784 | https://kallithea-scm.org/repos/kallithea/files/tip/init.d/ . | |
784 |
|
785 | |||
785 | .. _virtualenv: http://pypi.python.org/pypi/virtualenv |
|
786 | .. _virtualenv: http://pypi.python.org/pypi/virtualenv | |
786 | .. _python: http://www.python.org/ |
|
787 | .. _python: http://www.python.org/ | |
787 | .. _Mercurial: http://mercurial.selenic.com/ |
|
788 | .. _Mercurial: http://mercurial.selenic.com/ | |
788 | .. _Celery: http://celeryproject.org/ |
|
789 | .. _Celery: http://celeryproject.org/ | |
789 | .. _Celery documentation: http://docs.celeryproject.org/en/latest/getting-started/index.html |
|
790 | .. _Celery documentation: http://docs.celeryproject.org/en/latest/getting-started/index.html | |
790 | .. _RabbitMQ: http://www.rabbitmq.com/ |
|
791 | .. _RabbitMQ: http://www.rabbitmq.com/ | |
791 | .. _Redis: http://redis.io/ |
|
792 | .. _Redis: http://redis.io/ | |
792 | .. _python-ldap: http://www.python-ldap.org/ |
|
793 | .. _python-ldap: http://www.python-ldap.org/ | |
793 | .. _mercurial-server: http://www.lshift.net/mercurial-server.html |
|
794 | .. _mercurial-server: http://www.lshift.net/mercurial-server.html | |
794 | .. _PublishingRepositories: http://mercurial.selenic.com/wiki/PublishingRepositories |
|
795 | .. _PublishingRepositories: http://mercurial.selenic.com/wiki/PublishingRepositories |
@@ -1,69 +1,70 b'' | |||||
1 | .. _email: |
|
1 | .. _email: | |
2 |
|
2 | |||
3 | ============== |
|
3 | ============== | |
4 | Email settings |
|
4 | Email settings | |
5 | ============== |
|
5 | ============== | |
6 |
|
6 | |||
7 | The Kallithea configuration file has several email related settings. When |
|
7 | The Kallithea configuration file has several email related settings. When | |
8 | these contain correct values, Kallithea will send email in the situations |
|
8 | these contain correct values, Kallithea will send email in the situations | |
9 | described below. If the email configuration is not correct so that emails |
|
9 | described below. If the email configuration is not correct so that emails | |
10 | cannot be sent, all mails will show up in the log output. |
|
10 | cannot be sent, all mails will show up in the log output. | |
11 |
|
11 | |||
12 | Before any email can be sent, an SMTP server has to be configured using the |
|
12 | Before any email can be sent, an SMTP server has to be configured using the | |
13 | configuration file setting ``smtp_server``. If required for that server, specify |
|
13 | configuration file setting ``smtp_server``. If required for that server, specify | |
14 | a username (``smtp_username``) and password (``smtp_password``), a non-standard |
|
14 | a username (``smtp_username``) and password (``smtp_password``), a non-standard | |
15 | port (``smtp_port``), encryption settings (``smtp_use_tls`` or ``smtp_use_ssl``) |
|
15 | port (``smtp_port``), encryption settings (``smtp_use_tls`` or ``smtp_use_ssl``) | |
16 | and/or specific authentication parameters (``smtp_auth``). |
|
16 | and/or specific authentication parameters (``smtp_auth``). | |
17 |
|
17 | |||
18 | Application emails |
|
18 | Application emails | |
19 | ------------------ |
|
19 | ------------------ | |
20 |
|
20 | |||
21 | Kallithea sends an email to `users` on several occasions: |
|
21 | Kallithea sends an email to `users` on several occasions: | |
22 |
|
22 | |||
23 | - when comments are given on one of their changesets |
|
23 | - when comments are given on one of their changesets | |
24 | - when comments are given on changesets they are reviewer on or on which they |
|
24 | - when comments are given on changesets they are reviewer on or on which they | |
25 | commented regardless |
|
25 | commented regardless | |
26 | - when they are invited as reviewer in pull requests |
|
26 | - when they are invited as reviewer in pull requests | |
27 | - when they request a password reset |
|
27 | - when they request a password reset | |
28 |
|
28 | |||
29 | Kallithea sends an email to all `administrators` upon new account registration. |
|
29 | Kallithea sends an email to all `administrators` upon new account registration. | |
30 | Administrators are users with the ``Admin`` flag set in the ``Admin->Users`` |
|
30 | Administrators are users with the ``Admin`` flag set in the ``Admin->Users`` | |
31 | section. |
|
31 | section. | |
32 |
|
32 | |||
33 | When Kallithea wants to send an email but due to an error cannot correctly |
|
33 | When Kallithea wants to send an email but due to an error cannot correctly | |
34 | determine the intended recipients, the administrators and the addresses |
|
34 | determine the intended recipients, the administrators and the addresses | |
35 | specified in ``email_to`` in the configuration file are used as fallback. |
|
35 | specified in ``email_to`` in the configuration file are used as fallback. | |
36 |
|
36 | |||
37 | Recipients will see these emails originating from the sender specified in the |
|
37 | Recipients will see these emails originating from the sender specified in the | |
38 | ``app_email_from`` setting in the configuration file. This setting can either |
|
38 | ``app_email_from`` setting in the configuration file. This setting can either | |
39 | contain only an email address, like `kallithea-noreply@example.com`, or both |
|
39 | contain only an email address, like `kallithea-noreply@example.com`, or both | |
40 | a name and an address in the following format: `Kallithea |
|
40 | a name and an address in the following format: `Kallithea | |
41 | <kallithea-noreply@example.com>`. The subject of these emails can |
|
41 | <kallithea-noreply@example.com>`. The subject of these emails can | |
42 | optionally be prefixed with the value of ``email_prefix`` in the configuration |
|
42 | optionally be prefixed with the value of ``email_prefix`` in the configuration | |
43 | file. |
|
43 | file. | |
44 |
|
44 | |||
45 | Error emails |
|
45 | Error emails | |
46 | ------------ |
|
46 | ------------ | |
47 |
|
47 | |||
48 | When an exception occurs in Kallithea -- and unless interactive debugging is |
|
48 | When an exception occurs in Kallithea -- and unless interactive debugging is | |
49 | enabled using ``set debug = true`` in the ``[app:main]`` section of the |
|
49 | enabled using ``set debug = true`` in the ``[app:main]`` section of the | |
50 | configuration file -- an email with exception details is sent by WebError_'s |
|
50 | configuration file -- an email with exception details is sent by WebError_'s | |
51 | ``ErrorMiddleware`` to the addresses specified in ``email_to`` in the |
|
51 | ``ErrorMiddleware`` to the addresses specified in ``email_to`` in the | |
52 | configuration file. |
|
52 | configuration file. | |
53 |
|
53 | |||
54 | Recipients will see these emails originating from the sender specified in the |
|
54 | Recipients will see these emails originating from the sender specified in the | |
55 | ``error_email_from`` setting in the configuration file. This setting can either |
|
55 | ``error_email_from`` setting in the configuration file. This setting can either | |
56 | contain only an email address, like `kallithea-noreply@example.com`, or both |
|
56 | contain only an email address, like `kallithea-noreply@example.com`, or both | |
57 | a name and an address in the following format: `Kallithea Errors |
|
57 | a name and an address in the following format: `Kallithea Errors | |
58 | <kallithea-noreply@example.com>`. |
|
58 | <kallithea-noreply@example.com>`. | |
59 |
|
59 | |||
60 | *Note:* The WebError_ package does not respect ``smtp_port`` and assumes the |
|
60 | *Note:* The WebError_ package does not respect ``smtp_port`` and assumes the | |
61 | standard SMTP port (25). If you have a remote SMTP server with a different port, |
|
61 | standard SMTP port (25). If you have a remote SMTP server with a different port, | |
62 | you could set up a local forwarding SMTP server on port 25. |
|
62 | you could set up a local forwarding SMTP server on port 25. | |
63 |
|
63 | |||
64 | References |
|
64 | References | |
65 | ---------- |
|
65 | ---------- | |
|
66 | ||||
66 | - `Error Middleware (Pylons documentation) <http://pylons-webframework.readthedocs.org/en/latest/debugging.html#error-middleware>`_ |
|
67 | - `Error Middleware (Pylons documentation) <http://pylons-webframework.readthedocs.org/en/latest/debugging.html#error-middleware>`_ | |
67 | - `ErrorHandler (Pylons modules documentation) <http://pylons-webframework.readthedocs.org/en/latest/modules/middleware.html#pylons.middleware.ErrorHandler>`_ |
|
68 | - `ErrorHandler (Pylons modules documentation) <http://pylons-webframework.readthedocs.org/en/latest/modules/middleware.html#pylons.middleware.ErrorHandler>`_ | |
68 |
|
69 | |||
69 | .. _WebError: https://pypi.python.org/pypi/WebError |
|
70 | .. _WebError: https://pypi.python.org/pypi/WebError |
@@ -1,178 +1,178 b'' | |||||
1 | .. _general: |
|
1 | .. _general: | |
2 |
|
2 | |||
3 | ======================= |
|
3 | ======================= | |
4 | General Kallithea usage |
|
4 | General Kallithea usage | |
5 | ======================= |
|
5 | ======================= | |
6 |
|
6 | |||
7 |
|
7 | |||
8 | Repository deleting |
|
8 | Repository deleting | |
9 | ------------------- |
|
9 | ------------------- | |
10 |
|
10 | |||
11 | Currently when an admin or owner deletes a repository, Kallithea does |
|
11 | Currently when an admin or owner deletes a repository, Kallithea does | |
12 | not physically delete said repository from the filesystem, but instead |
|
12 | not physically delete said repository from the filesystem, but instead | |
13 | renames it in a special way so that it is not possible to push, clone |
|
13 | renames it in a special way so that it is not possible to push, clone | |
14 | or access the repository. |
|
14 | or access the repository. | |
15 |
|
15 | |||
16 | There is a special command for cleaning up such archived repos:: |
|
16 | There is a special command for cleaning up such archived repos:: | |
17 |
|
17 | |||
18 | paster cleanup-repos --older-than=30d my.ini |
|
18 | paster cleanup-repos --older-than=30d my.ini | |
19 |
|
19 | |||
20 | This command scans for archived repositories that are older than |
|
20 | This command scans for archived repositories that are older than | |
21 | 30 days, displays them, and asks if you want to delete them (unless given |
|
21 | 30 days, displays them, and asks if you want to delete them (unless given | |
22 | the ``--dont-ask`` flag). If you host a large amount of repositories with |
|
22 | the ``--dont-ask`` flag). If you host a large amount of repositories with | |
23 | forks that are constantly being deleted, it is recommended that you run this |
|
23 | forks that are constantly being deleted, it is recommended that you run this | |
24 | command via crontab. |
|
24 | command via crontab. | |
25 |
|
25 | |||
26 | It is worth noting that even if someone is given administrative access to |
|
26 | It is worth noting that even if someone is given administrative access to | |
27 | Kallithea and deletes a repository, you can easily restore such an action by |
|
27 | Kallithea and deletes a repository, you can easily restore such an action by | |
28 | renaming the repository directory, removing the ``rm__<date>`` prefix. |
|
28 | renaming the repository directory, removing the ``rm__<date>`` prefix. | |
29 |
|
29 | |||
30 | File view: follow current branch |
|
30 | File view: follow current branch | |
31 | -------------------------------- |
|
31 | -------------------------------- | |
32 |
|
32 | |||
33 | In the file view, left and right arrows allow to jump to the previous and next |
|
33 | In the file view, left and right arrows allow to jump to the previous and next | |
34 | revision. Depending on the way revisions were created in the repository, this |
|
34 | revision. Depending on the way revisions were created in the repository, this | |
35 | could jump to a different branch. When the checkbox ``Follow current branch`` |
|
35 | could jump to a different branch. When the checkbox ``Follow current branch`` | |
36 | is checked, these arrows will only jump to revisions on the same branch as the |
|
36 | is checked, these arrows will only jump to revisions on the same branch as the | |
37 | currently visible revision. So for example, if someone is viewing files in the |
|
37 | currently visible revision. So for example, if someone is viewing files in the | |
38 | ``beta`` branch and marks the `Follow current branch` checkbox, the < and > |
|
38 | ``beta`` branch and marks the `Follow current branch` checkbox, the < and > | |
39 | arrows will only show revisions on the ``beta`` branch. |
|
39 | arrows will only show revisions on the ``beta`` branch. | |
40 |
|
40 | |||
41 |
|
41 | |||
42 | Changelog features |
|
42 | Changelog features | |
43 | ------------------ |
|
43 | ------------------ | |
44 |
|
44 | |||
45 | The core feature of a repository's ``changelog`` page is to show the revisions |
|
45 | The core feature of a repository's ``changelog`` page is to show the revisions | |
46 | in a repository. However, there are several other features available from the |
|
46 | in a repository. However, there are several other features available from the | |
47 | changelog. |
|
47 | changelog. | |
48 |
|
48 | |||
49 | Branch filter |
|
49 | Branch filter | |
50 | By default, the changelog shows revisions from all branches in the |
|
50 | By default, the changelog shows revisions from all branches in the | |
51 | repository. Use the branch filter to restrict to a given branch. |
|
51 | repository. Use the branch filter to restrict to a given branch. | |
52 |
|
52 | |||
53 | Viewing a changeset |
|
53 | Viewing a changeset | |
54 | A particular changeset can be opened by clicking on either the changeset |
|
54 | A particular changeset can be opened by clicking on either the changeset | |
55 | hash or the commit message, or by ticking the checkbox and clicking the |
|
55 | hash or the commit message, or by ticking the checkbox and clicking the | |
56 | ``Show selected changeset`` button at the top. |
|
56 | ``Show selected changeset`` button at the top. | |
57 |
|
57 | |||
58 | Viewing all changes between two changesets |
|
58 | Viewing all changes between two changesets | |
59 | To get a list of all changesets between two selected changesets, along with |
|
59 | To get a list of all changesets between two selected changesets, along with | |
60 | the changes in each one of them, tick the checkboxes of the first and |
|
60 | the changes in each one of them, tick the checkboxes of the first and | |
61 | last changeset in the desired range and click the ``Show selected changesets`` |
|
61 | last changeset in the desired range and click the ``Show selected changesets`` | |
62 | button at the top. You can only show the range between the first and last |
|
62 | button at the top. You can only show the range between the first and last | |
63 | checkbox (no cherry-picking). |
|
63 | checkbox (no cherry-picking). | |
64 |
|
64 | |||
65 | From that page, you can proceed to viewing the overall delta between the |
|
65 | From that page, you can proceed to viewing the overall delta between the | |
66 | selected changesets, by clicking the ``Compare revisions`` button. |
|
66 | selected changesets, by clicking the ``Compare revisions`` button. | |
67 |
|
67 | |||
68 | Creating a pull request |
|
68 | Creating a pull request | |
69 | You can create a new pull request for the changes of a particular changeset |
|
69 | You can create a new pull request for the changes of a particular changeset | |
70 | (and its ancestors) by selecting it and clicking the ``Open new pull request |
|
70 | (and its ancestors) by selecting it and clicking the ``Open new pull request | |
71 | for selected changesets`` button. |
|
71 | for selected changesets`` button. | |
72 |
|
72 | |||
73 | Permanent repository URLs |
|
73 | Permanent repository URLs | |
74 | ------------------------- |
|
74 | ------------------------- | |
75 |
|
75 | |||
76 | Due to the complicated nature of repository grouping, URLs of repositories |
|
76 | Due to the complicated nature of repository grouping, URLs of repositories | |
77 | can often change. For example, a repository originally accessible from:: |
|
77 | can often change. For example, a repository originally accessible from:: | |
78 |
|
78 | |||
79 | http://server.com/repo_name |
|
79 | http://server.com/repo_name | |
80 |
|
80 | |||
81 | would get a new URL after moving it to test_group:: |
|
81 | would get a new URL after moving it to test_group:: | |
82 |
|
82 | |||
83 | http://server.com/test_group/repo_name |
|
83 | http://server.com/test_group/repo_name | |
84 |
|
84 | |||
85 | Such moving of a repository to a group can be an issue for build systems and |
|
85 | Such moving of a repository to a group can be an issue for build systems and | |
86 | other scripts where the repository paths are hardcoded. To mitigate this, |
|
86 | other scripts where the repository paths are hardcoded. To mitigate this, | |
87 | Kallithea provides permanent URLs using the repository ID prefixed with an |
|
87 | Kallithea provides permanent URLs using the repository ID prefixed with an | |
88 | underscore. In all Kallithea URLs, for example those for the changelog and the |
|
88 | underscore. In all Kallithea URLs, for example those for the changelog and the | |
89 | file view, a repository name can be replaced by this ``_ID`` string. Since IDs |
|
89 | file view, a repository name can be replaced by this ``_ID`` string. Since IDs | |
90 | are always the same, moving the repository to a different group will not affect |
|
90 | are always the same, moving the repository to a different group will not affect | |
91 | such URLs. |
|
91 | such URLs. | |
92 |
|
92 | |||
93 | In the example, the repository could also be accessible as:: |
|
93 | In the example, the repository could also be accessible as:: | |
94 |
|
94 | |||
95 | http://server.com/_<ID> |
|
95 | http://server.com/_<ID> | |
96 |
|
96 | |||
97 | The ID of a given repository can be shown from the repository ``Summary`` page, |
|
97 | The ID of a given repository can be shown from the repository ``Summary`` page, | |
98 | by selecting the ``Show by ID`` button next to ``Clone URL``. |
|
98 | by selecting the ``Show by ID`` button next to ``Clone URL``. | |
99 |
|
99 | |||
100 | Email notifications |
|
100 | Email notifications | |
101 | ------------------- |
|
101 | ------------------- | |
102 |
|
102 | |||
103 | When the administrator correctly specified the email settings in the Kallithea |
|
103 | When the administrator correctly specified the email settings in the Kallithea | |
104 | configuration file, Kallithea will send emails on user registration and when |
|
104 | configuration file, Kallithea will send emails on user registration and when | |
105 | errors occur. |
|
105 | errors occur. | |
106 |
|
106 | |||
107 | Emails are also sent for comments on changesets. In this case, an email is sent |
|
107 | Emails are also sent for comments on changesets. In this case, an email is sent | |
108 | to the committer of the changeset (if known to Kallithea), to all reviewers of |
|
108 | to the committer of the changeset (if known to Kallithea), to all reviewers of | |
109 | the pull request (if applicable) and to all people mentioned in the comment |
|
109 | the pull request (if applicable) and to all people mentioned in the comment | |
110 | using @mention notation. |
|
110 | using @mention notation. | |
111 |
|
111 | |||
112 |
|
112 | |||
113 | Trending source files |
|
113 | Trending source files | |
114 | --------------------- |
|
114 | --------------------- | |
115 |
|
115 | |||
116 | Trending source files are calculated based on a predefined dictionary of known |
|
116 | Trending source files are calculated based on a predefined dictionary of known | |
117 | types and extensions. If an extension is missing or you would like to scan |
|
117 | types and extensions. If an extension is missing or you would like to scan | |
118 | custom files, it is possible to extend the ``LANGUAGES_EXTENSIONS_MAP`` |
|
118 | custom files, it is possible to extend the ``LANGUAGES_EXTENSIONS_MAP`` | |
119 | dictionary located in ``kallithea/config/conf.py`` with new types. |
|
119 | dictionary located in ``kallithea/config/conf.py`` with new types. | |
120 |
|
120 | |||
121 |
|
121 | |||
122 | Cloning remote repositories |
|
122 | Cloning remote repositories | |
123 | --------------------------- |
|
123 | --------------------------- | |
124 |
|
124 | |||
125 | Kallithea has the ability to clone repositories from given remote locations. |
|
125 | Kallithea has the ability to clone repositories from given remote locations. | |
126 | Currently it supports the following options: |
|
126 | Currently it supports the following options: | |
127 |
|
127 | |||
128 | - hg -> hg clone |
|
128 | - hg -> hg clone | |
129 | - svn -> hg clone |
|
129 | - svn -> hg clone | |
130 | - git -> git clone |
|
130 | - git -> git clone | |
131 |
|
131 | |||
132 |
|
132 | |||
133 | .. note:: svn -> hg cloning requires the ``hgsubversion`` library to be |
|
133 | .. note:: svn -> hg cloning requires the ``hgsubversion`` library to be | |
134 | installed. |
|
134 | installed. | |
135 |
|
135 | |||
136 | If you need to clone repositories that are protected via basic authentication, |
|
136 | If you need to clone repositories that are protected via basic authentication, | |
137 | you can pass the credentials in the URL, e.g. |
|
137 | you can pass the credentials in the URL, e.g. | |
138 | ``http://user:passw@remote.server/repo``. Kallithea will then try to login and |
|
138 | ``http://user:passw@remote.server/repo``. Kallithea will then try to login and | |
139 | clone using the given credentials. Please note that the given credentials will |
|
139 | clone using the given credentials. Please note that the given credentials will | |
140 | be stored as plaintext inside the database. However, the authentication |
|
140 | be stored as plaintext inside the database. However, the authentication | |
141 | information will not be shown in the clone URL on the summary page. |
|
141 | information will not be shown in the clone URL on the summary page. | |
142 |
|
142 | |||
143 |
|
143 | |||
144 | Specific features configurable in the Admin settings |
|
144 | Specific features configurable in the Admin settings | |
145 | ---------------------------------------------------- |
|
145 | ---------------------------------------------------- | |
146 |
|
146 | |||
147 | In general, the Admin settings should be self-explanatory and will not be |
|
147 | In general, the Admin settings should be self-explanatory and will not be | |
148 | described in more detail in this documentation. However, there are a few |
|
148 | described in more detail in this documentation. However, there are a few | |
149 | features that merit further explanation. |
|
149 | features that merit further explanation. | |
150 |
|
150 | |||
151 | Repository extra fields |
|
151 | Repository extra fields | |
152 | ~~~~~~~~~~~~~~~~~~~~~~~ |
|
152 | ~~~~~~~~~~~~~~~~~~~~~~~ | |
153 |
|
153 | |||
154 | In the `Visual` tab, there is an option `Use repository extra |
|
154 | In the `Visual` tab, there is an option `Use repository extra | |
155 | fields`, which allows to set custom fields for each repository in the system. |
|
155 | fields`, which allows to set custom fields for each repository in the system. | |
156 | Each new field consists of 3 attributes: ``field key``, ``field label``, |
|
156 | Each new field consists of 3 attributes: ``field key``, ``field label``, | |
157 | ``field description``. |
|
157 | ``field description``. | |
158 |
|
158 | |||
159 | Example usage of such fields would be to define company-specific information |
|
159 | Example usage of such fields would be to define company-specific information | |
160 | into repositories, e.g., defining a ``repo_manager`` key that would give info |
|
160 | into repositories, e.g., defining a ``repo_manager`` key that would give info | |
161 | about a manager of each repository. There's no limit for adding custom fields. |
|
161 | about a manager of each repository. There's no limit for adding custom fields. | |
162 | Newly created fields are accessible via the API. |
|
162 | Newly created fields are accessible via the API. | |
163 |
|
163 | |||
164 |
Meta |
|
164 | Meta tagging | |
165 | ~~~~~~~~~~~~ |
|
165 | ~~~~~~~~~~~~ | |
166 |
|
166 | |||
167 | In the `Visual` tab, option `Stylify recognised meta tags` will cause Kallithea |
|
167 | In the `Visual` tab, option `Stylify recognised meta tags` will cause Kallithea | |
168 | to turn certain meta-tags, detected in repository and repository group |
|
168 | to turn certain meta-tags, detected in repository and repository group | |
169 | descriptions, into colored tags. Currently recognised tags are:: |
|
169 | descriptions, into colored tags. Currently recognised tags are:: | |
170 |
|
170 | |||
171 | [featured] |
|
171 | [featured] | |
172 | [stale] |
|
172 | [stale] | |
173 | [dead] |
|
173 | [dead] | |
174 | [lang => lang] |
|
174 | [lang => lang] | |
175 | [license => License] |
|
175 | [license => License] | |
176 | [requires => Repo] |
|
176 | [requires => Repo] | |
177 | [recommends => Repo] |
|
177 | [recommends => Repo] | |
178 | [see => URI] |
|
178 | [see => URI] |
@@ -1,57 +1,57 b'' | |||||
1 | .. _performance: |
|
1 | .. _performance: | |
2 |
|
2 | |||
3 | ================================ |
|
3 | ================================ | |
4 |
Optimizing Kallithea |
|
4 | Optimizing Kallithea performance | |
5 | ================================ |
|
5 | ================================ | |
6 |
|
6 | |||
7 | When serving a large amount of big repositories, Kallithea can start |
|
7 | When serving a large amount of big repositories, Kallithea can start | |
8 | performing slower than expected. Because of the demanding nature of handling large |
|
8 | performing slower than expected. Because of the demanding nature of handling large | |
9 | amounts of data from version control systems, here are some tips on how to get |
|
9 | amounts of data from version control systems, here are some tips on how to get | |
10 | the best performance. |
|
10 | the best performance. | |
11 |
|
11 | |||
12 | * Kallithea will perform better on machines with faster disks (SSD/SAN). It's |
|
12 | * Kallithea will perform better on machines with faster disks (SSD/SAN). It's | |
13 | more important to have a faster disk than a faster CPU. |
|
13 | more important to have a faster disk than a faster CPU. | |
14 |
|
14 | |||
15 | * Slowness on initial page can be easily fixed by grouping repositories, and/or |
|
15 | * Slowness on initial page can be easily fixed by grouping repositories, and/or | |
16 | increasing cache size (see below). This includes using the lightweight dashboard |
|
16 | increasing cache size (see below). This includes using the lightweight dashboard | |
17 | option and ``vcs_full_cache`` setting in .ini file |
|
17 | option and ``vcs_full_cache`` setting in .ini file | |
18 |
|
18 | |||
19 |
|
19 | |||
20 | Follow these few steps to improve performance of Kallithea system. |
|
20 | Follow these few steps to improve performance of Kallithea system. | |
21 |
|
21 | |||
22 |
|
22 | |||
23 | 1. Increase cache |
|
23 | 1. Increase cache | |
24 |
|
24 | |||
25 | Tweak beaker cache settings in the ini file. The actual effect of that |
|
25 | Tweak beaker cache settings in the ini file. The actual effect of that | |
26 | is questionable. |
|
26 | is questionable. | |
27 |
|
27 | |||
28 | 2. Switch from sqlite to postgres or mysql |
|
28 | 2. Switch from sqlite to postgres or mysql | |
29 |
|
29 | |||
30 | sqlite is a good option when having a small load on the system. But due to |
|
30 | sqlite is a good option when having a small load on the system. But due to | |
31 | locking issues with sqlite, it is not recommended to use it for larger |
|
31 | locking issues with sqlite, it is not recommended to use it for larger | |
32 | deployments. Switching to mysql or postgres will result in an immediate |
|
32 | deployments. Switching to mysql or postgres will result in an immediate | |
33 | performance increase. A tool like SQLAlchemyGrate_ can be used for |
|
33 | performance increase. A tool like SQLAlchemyGrate_ can be used for | |
34 | migrating to another database platform. |
|
34 | migrating to another database platform. | |
35 |
|
35 | |||
36 | 3. Scale Kallithea horizontally |
|
36 | 3. Scale Kallithea horizontally | |
37 |
|
37 | |||
38 | Scaling horizontally can give huge performance increases when dealing with |
|
38 | Scaling horizontally can give huge performance increases when dealing with | |
39 | large traffic (large amount of users, CI servers etc). Kallithea can be |
|
39 | large traffic (large amount of users, CI servers etc). Kallithea can be | |
40 | scaled horizontally on one (recommended) or multiple machines. In order |
|
40 | scaled horizontally on one (recommended) or multiple machines. In order | |
41 | to scale horizontally you need to do the following: |
|
41 | to scale horizontally you need to do the following: | |
42 |
|
42 | |||
43 | - Each instance needs its own .ini file and unique ``instance_id`` set. |
|
43 | - Each instance needs its own .ini file and unique ``instance_id`` set. | |
44 | - Each instance's ``data`` storage needs to be configured to be stored on a |
|
44 | - Each instance's ``data`` storage needs to be configured to be stored on a | |
45 | shared disk storage, preferably together with repositories. This ``data`` |
|
45 | shared disk storage, preferably together with repositories. This ``data`` | |
46 | dir contains template caches, sessions, whoosh index and is used for |
|
46 | dir contains template caches, sessions, whoosh index and is used for | |
47 | task locking (so it is safe across multiple instances). Set the |
|
47 | task locking (so it is safe across multiple instances). Set the | |
48 | ``cache_dir``, ``index_dir``, ``beaker.cache.data_dir``, ``beaker.cache.lock_dir`` |
|
48 | ``cache_dir``, ``index_dir``, ``beaker.cache.data_dir``, ``beaker.cache.lock_dir`` | |
49 | variables in each .ini file to a shared location across Kallithea instances |
|
49 | variables in each .ini file to a shared location across Kallithea instances | |
50 | - If celery is used each instance should run a separate Celery instance, but |
|
50 | - If celery is used each instance should run a separate Celery instance, but | |
51 | the message broker should be common to all of them (e.g., one |
|
51 | the message broker should be common to all of them (e.g., one | |
52 | shared RabbitMQ server) |
|
52 | shared RabbitMQ server) | |
53 | - Load balance using round robin or IP hash, recommended is writing LB rules |
|
53 | - Load balance using round robin or IP hash, recommended is writing LB rules | |
54 | that will separate regular user traffic from automated processes like CI |
|
54 | that will separate regular user traffic from automated processes like CI | |
55 | servers or build bots. |
|
55 | servers or build bots. | |
56 |
|
56 | |||
57 | .. _SQLAlchemyGrate: https://github.com/shazow/sqlalchemygrate |
|
57 | .. _SQLAlchemyGrate: https://github.com/shazow/sqlalchemygrate |
@@ -1,76 +1,75 b'' | |||||
1 | .. _troubleshooting: |
|
1 | .. _troubleshooting: | |
2 |
|
2 | |||
3 |
|
||||
4 | =============== |
|
3 | =============== | |
5 | Troubleshooting |
|
4 | Troubleshooting | |
6 | =============== |
|
5 | =============== | |
7 |
|
6 | |||
8 | :Q: **Missing static files?** |
|
7 | :Q: **Missing static files?** | |
9 | :A: Make sure either to set the ``static_files = true`` in the .ini file or |
|
8 | :A: Make sure either to set the ``static_files = true`` in the .ini file or | |
10 | double check the root path for your http setup. It should point to |
|
9 | double check the root path for your http setup. It should point to | |
11 | for example: |
|
10 | for example: | |
12 | ``/home/my-virtual-python/lib/python2.7/site-packages/kallithea/public`` |
|
11 | ``/home/my-virtual-python/lib/python2.7/site-packages/kallithea/public`` | |
13 |
|
12 | |||
14 | | |
|
13 | | | |
15 |
|
14 | |||
16 | :Q: **Can't install celery/rabbitmq?** |
|
15 | :Q: **Can't install celery/rabbitmq?** | |
17 | :A: Don't worry. Kallithea works without them, too. No extra setup is required. |
|
16 | :A: Don't worry. Kallithea works without them, too. No extra setup is required. | |
18 | Try out the great Celery docs for further help. |
|
17 | Try out the great Celery docs for further help. | |
19 |
|
18 | |||
20 | | |
|
19 | | | |
21 |
|
20 | |||
22 | :Q: **Long lasting push timeouts?** |
|
21 | :Q: **Long lasting push timeouts?** | |
23 | :A: Make sure you set a longer timeout in your proxy/fcgi settings. Timeouts |
|
22 | :A: Make sure you set a longer timeout in your proxy/fcgi settings. Timeouts | |
24 | are caused by the http server and not Kallithea. |
|
23 | are caused by the http server and not Kallithea. | |
25 |
|
24 | |||
26 | | |
|
25 | | | |
27 |
|
26 | |||
28 | :Q: **Large pushes timeouts?** |
|
27 | :Q: **Large pushes timeouts?** | |
29 | :A: Make sure you set a proper ``max_body_size`` for the http server. Very often |
|
28 | :A: Make sure you set a proper ``max_body_size`` for the http server. Very often | |
30 | Apache, Nginx, or other http servers kill the connection due to to large |
|
29 | Apache, Nginx, or other http servers kill the connection due to to large | |
31 | body. |
|
30 | body. | |
32 |
|
31 | |||
33 | | |
|
32 | | | |
34 |
|
33 | |||
35 | :Q: **Apache doesn't pass basicAuth on pull/push?** |
|
34 | :Q: **Apache doesn't pass basicAuth on pull/push?** | |
36 | :A: Make sure you added ``WSGIPassAuthorization true``. |
|
35 | :A: Make sure you added ``WSGIPassAuthorization true``. | |
37 |
|
36 | |||
38 | | |
|
37 | | | |
39 |
|
38 | |||
40 | :Q: **Git fails on push/pull?** |
|
39 | :Q: **Git fails on push/pull?** | |
41 | :A: Make sure you're using a WSGI http server that can handle chunked encoding |
|
40 | :A: Make sure you're using a WSGI http server that can handle chunked encoding | |
42 | such as ``waitress`` or ``gunicorn``. |
|
41 | such as ``waitress`` or ``gunicorn``. | |
43 |
|
42 | |||
44 | | |
|
43 | | | |
45 |
|
44 | |||
46 | :Q: **How can I use hooks in Kallithea?** |
|
45 | :Q: **How can I use hooks in Kallithea?** | |
47 | :A: It's easy if they are Python hooks: just use advanced link in |
|
46 | :A: It's easy if they are Python hooks: just use advanced link in | |
48 | hooks section in Admin panel, that works only for Mercurial. If |
|
47 | hooks section in Admin panel, that works only for Mercurial. If | |
49 | you want to use Git hooks, just install th proper one in the repository, |
|
48 | you want to use Git hooks, just install th proper one in the repository, | |
50 | e.g., create a file `/gitrepo/hooks/pre-receive`. You can also use |
|
49 | e.g., create a file `/gitrepo/hooks/pre-receive`. You can also use | |
51 | Kallithea-extensions to connect to callback hooks, for both Git |
|
50 | Kallithea-extensions to connect to callback hooks, for both Git | |
52 | and Mercurial. |
|
51 | and Mercurial. | |
53 |
|
52 | |||
54 | | |
|
53 | | | |
55 |
|
54 | |||
56 | :Q: **Kallithea is slow for me, how can I make it faster?** |
|
55 | :Q: **Kallithea is slow for me, how can I make it faster?** | |
57 | :A: See the :ref:`performance` section. |
|
56 | :A: See the :ref:`performance` section. | |
58 |
|
57 | |||
59 | | |
|
58 | | | |
60 |
|
59 | |||
61 | :Q: **UnicodeDecodeError on Apache mod_wsgi** |
|
60 | :Q: **UnicodeDecodeError on Apache mod_wsgi** | |
62 | :A: Please read: https://docs.djangoproject.com/en/dev/howto/deployment/wsgi/modwsgi/#if-you-get-a-unicodeencodeerror. |
|
61 | :A: Please read: https://docs.djangoproject.com/en/dev/howto/deployment/wsgi/modwsgi/#if-you-get-a-unicodeencodeerror. | |
63 |
|
62 | |||
64 | | |
|
63 | | | |
65 |
|
64 | |||
66 | :Q: **Requests hanging on Windows** |
|
65 | :Q: **Requests hanging on Windows** | |
67 | :A: Please try out with disabled Antivirus software, there are some known problems with Eset Anitivirus. Make sure |
|
66 | :A: Please try out with disabled Antivirus software, there are some known problems with Eset Anitivirus. Make sure | |
68 | you have installed the latest Windows patches (especially KB2789397). |
|
67 | you have installed the latest Windows patches (especially KB2789397). | |
69 |
|
68 | |||
70 |
|
69 | |||
71 | .. _virtualenv: http://pypi.python.org/pypi/virtualenv |
|
70 | .. _virtualenv: http://pypi.python.org/pypi/virtualenv | |
72 | .. _python: http://www.python.org/ |
|
71 | .. _python: http://www.python.org/ | |
73 | .. _mercurial: http://mercurial.selenic.com/ |
|
72 | .. _mercurial: http://mercurial.selenic.com/ | |
74 | .. _celery: http://celeryproject.org/ |
|
73 | .. _celery: http://celeryproject.org/ | |
75 | .. _rabbitmq: http://www.rabbitmq.com/ |
|
74 | .. _rabbitmq: http://www.rabbitmq.com/ | |
76 | .. _python-ldap: http://www.python-ldap.org/ |
|
75 | .. _python-ldap: http://www.python-ldap.org/ |
General Comments 0
You need to be logged in to leave comments.
Login now