setup.rst
781 lines
| 26.6 KiB
| text/x-rst
|
RstLexer
/ docs / setup.rst
r568 | .. _setup: | |||
r2095 | ===== | |||
r568 | Setup | |||
===== | ||||
|
r4192 | Setting up Kallithea | ||
r1448 | -------------------- | |||
r572 | ||||
|
r4192 | First, you will need to create a Kallithea configuration file. Run the | ||
r1309 | following command to do this:: | |||
r3224 | ||||
|
r4902 | paster make-config Kallithea my.ini | ||
r572 | ||||
|
r4902 | - This will create the file `my.ini` in the current directory. This | ||
|
r4192 | configuration file contains the various settings for Kallithea, e.g proxy | ||
|
r4925 | port, email settings, usage of static files, cache, Celery settings and | ||
r1309 | logging. | |||
r845 | ||||
|
r4902 | Next, you need to create the databases used by Kallithea. It is recommended to | ||
|
r4914 | use PostgreSQL or SQLite (default). If you choose a database other than the | ||
default ensure you properly adjust the database URL in your my.ini | ||||
|
r4192 | configuration file to use this other database. Kallithea currently supports | ||
|
r4914 | PostgreSQL, SQLite and MySQL databases. Create the database by running | ||
r1092 | the following command:: | |||
r572 | ||||
|
r4902 | paster setup-db my.ini | ||
r572 | ||||
r1092 | This will prompt you for a "root" path. This "root" path is the location where | |||
|
r4192 | Kallithea will store all of its repositories on the current machine. After | ||
|
r4185 | entering this "root" path ``setup-db`` will also prompt you for a username | ||
and password for the initial admin account which ``setup-db`` sets | ||||
r2284 | up for you. | |||
r845 | ||||
r2358 | setup process can be fully automated, example for lazy:: | |||
|
r4902 | paster setup-db my.ini --user=nn --password=secret --email=nn@your.kallithea.server --repos=/srv/repos | ||
r3224 | ||||
r2358 | ||||
|
r4185 | - The ``setup-db`` command will create all of the needed tables and an | ||
r3224 | admin account. When choosing a root path you can either use a new empty | |||
r2284 | location, or a location which already contains existing repositories. If you | |||
|
r4914 | choose a location which contains existing repositories Kallithea will | ||
add all of the repositories at the chosen location to its database. | ||||
r2284 | (Note: make sure you specify the correct path to the root). | |||
|
r4914 | - Note: the given path for Mercurial_ repositories **must** be write accessible | ||
|
r4192 | for the application. It's very important since the Kallithea web interface | ||
r3224 | will work without write access, but when trying to do a push it will | |||
r1309 | eventually fail with permission denied errors unless it has write access. | |||
r572 | ||||
|
r4192 | You are now ready to use Kallithea, to run it simply execute:: | ||
r3224 | ||||
|
r4902 | paster serve my.ini | ||
r3224 | ||||
|
r4192 | - This command runs the Kallithea server. The web app should be available at the | ||
|
r4902 | 127.0.0.1:5000. This ip and port is configurable via the my.ini | ||
r845 | file created in previous step | |||
|
r4185 | - Use the admin account you created above when running ``setup-db`` | ||
r2284 | to login to the web app. | |||
r3224 | - The default permissions on each repository is read, and the owner is admin. | |||
r1092 | Remember to update these if needed. | |||
|
r4902 | - In the admin panel you can toggle LDAP, anonymous, permissions settings. As | ||
r1092 | well as edit more advanced options on users and repositories | |||
|
r4192 | Optionally users can create `rcextensions` package that extends Kallithea | ||
r2105 | functionality. To do this simply execute:: | |||
|
r4902 | paster make-rcext my.ini | ||
r1092 | ||||
r2105 | This will create `rcextensions` package in the same place that your `ini` file | |||
r3224 | lives. With `rcextensions` it's possible to add additional mapping for whoosh, | |||
r2906 | stats and add additional code into the push/pull/create/delete repo hooks. | |||
|
r4914 | For example for sending signals to build-bots such as Jenkins. | ||
r3224 | Please see the `__init__.py` file inside `rcextensions` package | |||
r2105 | for more details. | |||
r1092 | ||||
|
r4192 | Using Kallithea with SSH | ||
r912 | ------------------------ | |||
|
r4192 | Kallithea currently only hosts repositories using http and https. (The addition | ||
r1309 | of ssh hosting is a planned future feature.) However you can easily use ssh in | |||
|
r4192 | parallel with Kallithea. (Repository access via ssh is a standard "out of | ||
|
r4914 | the box" feature of Mercurial_ and you can use this to access any of the | ||
|
r4192 | repositories that Kallithea is hosting. See PublishingRepositories_) | ||
r1092 | ||||
|
r4192 | Kallithea repository structures are kept in directories with the same name | ||
r1092 | as the project. When using repository groups, each group is a subdirectory. | |||
This allows you to easily use ssh for accessing repositories. | ||||
r912 | ||||
r3224 | In order to use ssh you need to make sure that your web-server and the users | |||
r1309 | login accounts have the correct permissions set on the appropriate directories. | |||
(Note that these permissions are independent of any permissions you have set up | ||||
|
r4192 | using the Kallithea web interface.) | ||
r912 | ||||
|
r4192 | If your main directory (the same as set in Kallithea settings) is for example | ||
|
r4902 | set to **/srv/repos** and the repository you are using is named `kallithea`, then | ||
r1092 | to clone via ssh you should run:: | |||
r912 | ||||
|
r4902 | hg clone ssh://user@server.com//srv/repos/kallithea | ||
r1092 | ||||
Using other external tools such as mercurial-server_ or using ssh key based | ||||
authentication is fully supported. | ||||
r912 | ||||
r1092 | Note: In an advanced setup, in order for your ssh access to use the same | |||
|
r4192 | permissions as set up via the Kallithea web interface, you can create an | ||
authentication hook to connect to the Kallithea db and runs check functions for | ||||
r1092 | permissions against that. | |||
r3224 | ||||
r683 | Setting up Whoosh full text search | |||
---------------------------------- | ||||
|
r4902 | The whoosh index can be build by using the paster | ||
r1092 | command ``make-index``. To use ``make-index`` you must specify the configuration | |||
r3224 | file that stores the location of the index. You may specify the location of the | |||
repositories (`--repo-location`). If not specified, this value is retrieved | ||||
|
r4902 | from the Kallithea database. | ||
It is also possible to specify a comma separated list of | ||||
r3224 | repositories (`--index-only`) to build index only on chooses repositories | |||
|
r1408 | skipping any other found in repos location | ||
r894 | ||||
r1092 | You may optionally pass the option `-f` to enable a full index rebuild. Without | |||
the `-f` option, indexing will run always in "incremental" mode. | ||||
r683 | ||||
r1092 | For an incremental index build use:: | |||
r707 | ||||
|
r4902 | paster make-index my.ini | ||
r683 | ||||
r1092 | For a full index rebuild use:: | |||
r707 | ||||
|
r4902 | paster make-index my.ini -f | ||
r572 | ||||
r894 | ||||
building index just for chosen repositories is possible with such command:: | ||||
r3224 | ||||
|
r4902 | paster make-index my.ini --index-only=vcs,kallithea | ||
r572 | ||||
r894 | ||||
r1092 | In order to do periodical index builds and keep your index always up to date. | |||
r3224 | It's recommended to do a crontab entry for incremental indexing. | |||
r1092 | An example entry might look like this:: | |||
r3224 | ||||
|
r4902 | /path/to/python/bin/paster make-index /path/to/kallithea/my.ini | ||
r3224 | ||||
r1092 | When using incremental mode (the default) whoosh will check the last | |||
modification date of each file and add it to be reindexed if a newer file is | ||||
available. The indexing daemon checks for any removed files and removes them | ||||
from index. | ||||
r683 | ||||
r1092 | If you want to rebuild index from scratch, you can use the `-f` flag as above, | |||
or in the admin panel you can check `build from scratch` flag. | ||||
r572 | ||||
r707 | ||||
Setting up LDAP support | ||||
----------------------- | ||||
|
r4902 | Kallithea supports LDAP authentication. In order | ||
r3224 | to use LDAP, you have to install the python-ldap_ package. This package is | |||
r1292 | available via pypi, so you can install it by running | |||
r707 | ||||
r1123 | pip install python-ldap | |||
r707 | ||||
r770 | .. note:: | |||
r3224 | python-ldap requires some certain libs on your system, so before installing | |||
r1092 | it check that you have at least `openldap`, and `sasl` libraries. | |||
r707 | ||||
|
r4902 | LDAP settings are located in Admin->LDAP section. | ||
|
r992 | |||
|
r4902 | Here's a typical LDAP setup:: | ||
|
r992 | |||
Connection settings | ||||
Enable LDAP = checked | ||||
Host = host.example.org | ||||
Port = 389 | ||||
Account = <account> | ||||
Password = <password> | ||||
r1292 | Connection Security = LDAPS connection | |||
|
r992 | Certificate Checks = DEMAND | ||
Search settings | ||||
Base DN = CN=users,DC=host,DC=example,DC=org | ||||
LDAP Filter = (&(objectClass=user)(!(objectClass=computer))) | ||||
LDAP Search Scope = SUBTREE | ||||
r707 | ||||
|
r992 | Attribute mappings | ||
Login Attribute = uid | ||||
First Name Attribute = firstName | ||||
Last Name Attribute = lastName | ||||
E-mail Attribute = mail | ||||
|
r3801 | If your user groups are placed in a Organisation Unit (OU) structure the Search Settings configuration differs:: | ||
Search settings | ||||
Base DN = DC=host,DC=example,DC=org | ||||
LDAP Filter = (&(memberOf=CN=your user group,OU=subunit,OU=unit,DC=host,DC=example,DC=org)(objectClass=user)) | ||||
LDAP Search Scope = SUBTREE | ||||
|
r992 | .. _enable_ldap: | ||
Enable LDAP : required | ||||
Whether to use LDAP for authenticating users. | ||||
.. _ldap_host: | ||||
Host : required | ||||
r2916 | LDAP server hostname or IP address. Can be also a comma separated | |||
list of servers to support LDAP fail-over. | ||||
|
r992 | |||
.. _Port: | ||||
Port : required | ||||
389 for un-encrypted LDAP, 636 for SSL-encrypted LDAP. | ||||
.. _ldap_account: | ||||
r707 | ||||
|
r992 | Account : optional | ||
Only required if the LDAP server does not allow anonymous browsing of | ||||
records. This should be a special account for record browsing. This | ||||
will require `LDAP Password`_ below. | ||||
.. _LDAP Password: | ||||
Password : optional | ||||
Only required if the LDAP server does not allow anonymous browsing of | ||||
records. | ||||
.. _Enable LDAPS: | ||||
r1292 | Connection Security : required | |||
Defines the connection to LDAP server | ||||
No encryption | ||||
Plain non encrypted connection | ||||
r3224 | ||||
r1292 | LDAPS connection | |||
|
r4902 | Enable LDAPS connections. It will likely require `Port`_ to be set to | ||
r3224 | a different value (standard LDAPS port is 636). When LDAPS is enabled | |||
r1292 | then `Certificate Checks`_ is required. | |||
r3224 | ||||
r1292 | START_TLS on LDAP connection | |||
START TLS connection | ||||
|
r992 | |||
.. _Certificate Checks: | ||||
r707 | ||||
|
r992 | Certificate Checks : optional | ||
How SSL certificates verification is handled - this is only useful when | ||||
r3224 | `Enable LDAPS`_ is enabled. Only DEMAND or HARD offer full SSL security | |||
r1309 | while the other options are susceptible to man-in-the-middle attacks. SSL | |||
|
r992 | certificates can be installed to /etc/openldap/cacerts so that the | ||
DEMAND or HARD options can be used with self-signed certificates or | ||||
certificates that do not have traceable certificates of authority. | ||||
NEVER | ||||
A serve certificate will never be requested or checked. | ||||
ALLOW | ||||
A server certificate is requested. Failure to provide a | ||||
certificate or providing a bad certificate will not terminate the | ||||
session. | ||||
TRY | ||||
A server certificate is requested. Failure to provide a | ||||
certificate does not halt the session; providing a bad certificate | ||||
halts the session. | ||||
DEMAND | ||||
A server certificate is requested and must be provided and | ||||
authenticated for the session to proceed. | ||||
r775 | ||||
|
r992 | HARD | ||
The same as DEMAND. | ||||
.. _Base DN: | ||||
Base DN : required | ||||
The Distinguished Name (DN) where searches for users will be performed. | ||||
Searches can be controlled by `LDAP Filter`_ and `LDAP Search Scope`_. | ||||
.. _LDAP Filter: | ||||
LDAP Filter : optional | ||||
A LDAP filter defined by RFC 2254. This is more useful when `LDAP | ||||
Search Scope`_ is set to SUBTREE. The filter is useful for limiting | ||||
which LDAP objects are identified as representing Users for | ||||
authentication. The filter is augmented by `Login Attribute`_ below. | ||||
This can commonly be left blank. | ||||
.. _LDAP Search Scope: | ||||
LDAP Search Scope : required | ||||
This limits how far LDAP will search for a matching object. | ||||
BASE | ||||
Only allows searching of `Base DN`_ and is usually not what you | ||||
want. | ||||
ONELEVEL | ||||
Searches all entries under `Base DN`_, but not Base DN itself. | ||||
SUBTREE | ||||
Searches all entries below `Base DN`_, but not Base DN itself. | ||||
When using SUBTREE `LDAP Filter`_ is useful to limit object | ||||
location. | ||||
.. _Login Attribute: | ||||
r707 | ||||
r3224 | Login Attribute : required | |||
|
r992 | The LDAP record attribute that will be matched as the USERNAME or | ||
|
r4192 | ACCOUNT used to connect to Kallithea. This will be added to `LDAP | ||
|
r992 | Filter`_ for locating the User object. If `LDAP Filter`_ is specified as | ||
"LDAPFILTER", `Login Attribute`_ is specified as "uid" and the user has | ||||
connected as "jsmith" then the `LDAP Filter`_ will be augmented as below | ||||
:: | ||||
(&(LDAPFILTER)(uid=jsmith)) | ||||
.. _ldap_attr_firstname: | ||||
First Name Attribute : required | ||||
The LDAP record attribute which represents the user's first name. | ||||
.. _ldap_attr_lastname: | ||||
Last Name Attribute : required | ||||
The LDAP record attribute which represents the user's last name. | ||||
.. _ldap_attr_email: | ||||
Email Attribute : required | ||||
The LDAP record attribute which represents the user's email address. | ||||
r707 | ||||
|
r992 | If all data are entered correctly, and python-ldap_ is properly installed | ||
|
r4902 | users should be granted access to Kallithea with LDAP accounts. At this | ||
|
r4192 | time user information is copied from LDAP into the Kallithea user database. | ||
|
r992 | This means that updates of an LDAP user object may not be reflected as a | ||
|
r4192 | user update in Kallithea. | ||
|
r992 | |||
If You have problems with LDAP access and believe You entered correct | ||||
|
r4192 | information check out the Kallithea logs, any error messages sent from LDAP | ||
|
r992 | will be saved there. | ||
Active Directory | ||||
'''''''''''''''' | ||||
r707 | ||||
|
r4192 | Kallithea can use Microsoft Active Directory for user authentication. This | ||
|
r992 | is done through an LDAP or LDAPS connection to Active Directory. The | ||
following LDAP configuration settings are typical for using Active | ||||
Directory :: | ||||
r707 | ||||
|
r992 | Base DN = OU=SBSUsers,OU=Users,OU=MyBusiness,DC=v3sys,DC=local | ||
Login Attribute = sAMAccountName | ||||
First Name Attribute = givenName | ||||
Last Name Attribute = sn | ||||
E-mail Attribute = mail | ||||
All other LDAP settings will likely be site-specific and should be | ||||
appropriately configured. | ||||
r777 | ||||
r1467 | ||||
|
r1657 | Authentication by container or reverse-proxy | ||
-------------------------------------------- | ||||
|
r4501 | Kallithea supports delegating the authentication | ||
|
r1657 | of users to its WSGI container, or to a reverse-proxy server through which all | ||
clients access the application. | ||||
|
r4192 | When these authentication methods are enabled in Kallithea, it uses the | ||
|
r1657 | username that the container/proxy (Apache/Nginx/etc) authenticated and doesn't | ||
perform the authentication itself. The authorization, however, is still done by | ||||
|
r4192 | Kallithea according to its settings. | ||
|
r1657 | |||
When a user logs in for the first time using these authentication methods, | ||||
|
r4192 | a matching user account is created in Kallithea with default permissions. An | ||
administrator can then modify it using Kallithea's admin interface. | ||||
|
r1657 | It's also possible for an administrator to create accounts and configure their | ||
permissions before the user logs in for the first time. | ||||
|
r4501 | |||
|
r1657 | Container-based authentication | ||
'''''''''''''''''''''''''''''' | ||||
|
r4192 | In a container-based authentication setup, Kallithea reads the user name from | ||
|
r1657 | the ``REMOTE_USER`` server variable provided by the WSGI container. | ||
After setting up your container (see `Apache's WSGI config`_), you'd need | ||||
to configure it to require authentication on the location configured for | ||||
|
r4192 | Kallithea. | ||
|
r1657 | |||
Proxy pass-through authentication | ||||
''''''''''''''''''''''''''''''''' | ||||
|
r4192 | In a proxy pass-through authentication setup, Kallithea reads the user name | ||
|
r1657 | from the ``X-Forwarded-User`` request header, which should be configured to be | ||
sent by the reverse-proxy server. | ||||
After setting up your proxy solution (see `Apache virtual host reverse proxy example`_, | ||||
`Apache as subdirectory`_ or `Nginx virtual host example`_), you'd need to | ||||
configure the authentication and add the username in a request header named | ||||
``X-Forwarded-User``. | ||||
For example, the following config section for Apache sets a subdirectory in a | ||||
reverse-proxy setup with basic auth:: | ||||
<Location /<someprefix> > | ||||
ProxyPass http://127.0.0.1:5000/<someprefix> | ||||
ProxyPassReverse http://127.0.0.1:5000/<someprefix> | ||||
SetEnvIf X-Url-Scheme https HTTPS=1 | ||||
AuthType Basic | ||||
|
r4192 | AuthName "Kallithea authentication" | ||
|
r4902 | AuthUserFile /srv/kallithea/.htpasswd | ||
|
r1657 | require valid-user | ||
RequestHeader unset X-Forwarded-User | ||||
RewriteEngine On | ||||
RewriteCond %{LA-U:REMOTE_USER} (.+) | ||||
RewriteRule .* - [E=RU:%1] | ||||
RequestHeader set X-Forwarded-User %{RU}e | ||||
r3224 | </Location> | |||
|
r1657 | |||
.. note:: | ||||
If you enable proxy pass-through authentication, make sure your server is | ||||
only accessible through the proxy. Otherwise, any client would be able to | ||||
forge the authentication header and could effectively become authenticated | ||||
using any account of their liking. | ||||
r1838 | Integration with Issue trackers | |||
------------------------------- | ||||
|
r1657 | |||
|
r4192 | Kallithea provides a simple integration with issue trackers. It's possible | ||
r1838 | to define a regular expression that will fetch issue id stored in commit | |||
messages and replace that with an url to this issue. To enable this simply | ||||
uncomment following variables in the ini file:: | ||||
r3943 | issue_pat = (?:^#|\s#)(\w+) | |||
r1870 | issue_server_link = https://myissueserver.com/{repo}/issue/{id} | |||
r1838 | issue_prefix = # | |||
|
r4848 | `issue_pat` is the regular expression describing which strings in | ||
commit messages will be treated as issue references. A match group in | ||||
parentheses should be used to specify the actual issue id. | ||||
The default expression matches issues in the format '#<number>', e.g. '#300'. | ||||
r3224 | ||||
|
r4848 | Matched issues are replaced with the link specified as `issue_server_link` | ||
{id} is replaced with issue id, and {repo} with repository name. | ||||
Since the # is stripped away, `issue_prefix` is prepended to the link text. | ||||
`issue_prefix` doesn't necessarily need to be #: if you set issue | ||||
prefix to ISSUE- this will generate a URL in format:: | ||||
r3224 | ||||
<a href="https://myissueserver.com/example_repo/issue/300">ISSUE-300</a> | ||||
|
r1657 | |||
|
r4848 | If needed, more than one pattern can be specified by appending a unique suffix to | ||
the variables. For example:: | ||||
issue_pat_wiki = (?:wiki-)(.+) | ||||
issue_server_link_wiki = https://mywiki.com/{id} | ||||
issue_prefix_wiki = WIKI- | ||||
With these settings, wiki pages can be referenced as wiki-some-id, and every | ||||
such reference will be transformed into:: | ||||
<a href="https://mywiki.com/some-id">WIKI-some-id</a> | ||||
r1467 | Hook management | |||
--------------- | ||||
Hooks can be managed in similar way to this used in .hgrc files. | ||||
To access hooks setting click `advanced setup` on Hooks section of Mercurial | ||||
r3224 | Settings in Admin. | |||
r1467 | ||||
There are 4 built in hooks that cannot be changed (only enable/disable by | ||||
checkboxes on previos section). | ||||
r3224 | To add another custom hook simply fill in first section with | |||
r1467 | <name>.<hook_type> and the second one with hook path. Example hooks | |||
|
r4186 | can be found at *kallithea.lib.hooks*. | ||
r1467 | ||||
r2017 | Changing default encoding | |||
------------------------- | ||||
|
r4914 | By default, Kallithea uses UTF-8 encoding. | ||
|
r4902 | It is configurable as `default_encoding` in the .ini file. | ||
This affects many parts in Kallithea including user names, filenames, and | ||||
|
r4192 | encoding of commit messages. In addition Kallithea can detect if `chardet` | ||
library is installed. If `chardet` is detected Kallithea will fallback to it | ||||
r2017 | when there are encode/decode errors. | |||
|
r4902 | Celery configuration | ||
-------------------- | ||||
r777 | ||||
|
r4925 | Kallithea can use the distributed task queue system Celery_ to run tasks like | ||
cloning repositories or sending mails. | ||||
Kallithea will in most setups work perfectly fine out of the box (without | ||||
Celery), executing all tasks in the web server process. Some tasks can however | ||||
take some time to run and it can be better to run such tasks asynchronously in | ||||
a separate process so the web server can focus on serving web requests. | ||||
For installation and configuration of Celery, see the `Celery documentation`_. | ||||
Note that Celery requires a message broker service like RabbitMQ_ (recommended) | ||||
or Redis_. | ||||
r777 | ||||
|
r4925 | The use of Celery is configured in the Kallithea ini configuration file. | ||
To enable it, simply set:: | ||||
use_celery = true | ||||
r777 | ||||
|
r4925 | and add or change the celery.* and broker.* configuration variables. | ||
Remember that the ini files use the format with '.' and not with '_' like | ||||
Celery. So for example setting `BROKER_HOST` in Celery means setting | ||||
`broker.host` in the configuration file. | ||||
To start the Celery process, run:: | ||||
r938 | ||||
r777 | paster celeryd <configfile.ini> | |||
r871 | .. note:: | |||
r3224 | Make sure you run this command from the same virtualenv, and with the same | |||
|
r4192 | user that Kallithea runs. | ||
r3224 | ||||
r1062 | HTTPS support | |||
------------- | ||||
|
r4448 | Kallithea will by default generate URLs based on the WSGI environment. | ||
Alternatively, you can use some special configuration settings to control | ||||
directly which scheme/protocol Kallithea will use when generating URLs: | ||||
r1092 | ||||
|
r4448 | - With `https_fixup = true`, the scheme will be taken from the HTTP_X_URL_SCHEME, | ||
HTTP_X_FORWARDED_SCHEME or HTTP_X_FORWARDED_PROTO HTTP header (default 'http'). | ||||
- With `force_https = true` the default will be 'https'. | ||||
- With `use_htsts = true`, it will set Strict-Transport-Security when using https. | ||||
r871 | ||||
r572 | Nginx virtual host example | |||
-------------------------- | ||||
r707 | Sample config for nginx using proxy:: | |||
r572 | ||||
|
r4902 | upstream kallithea { | ||
r1745 | server 127.0.0.1:5000; | |||
# add more instances for load balancing | ||||
#server 127.0.0.1:5001; | ||||
#server 127.0.0.1:5002; | ||||
} | ||||
r3224 | ||||
r3850 | ## gist alias | |||
server { | ||||
listen 443; | ||||
server_name gist.myserver.com; | ||||
access_log /var/log/nginx/gist.access.log; | ||||
error_log /var/log/nginx/gist.error.log; | ||||
ssl on; | ||||
|
r4182 | ssl_certificate gist.your.kallithea.server.crt; | ||
ssl_certificate_key gist.your.kallithea.server.key; | ||||
r3850 | ||||
ssl_session_timeout 5m; | ||||
ssl_protocols SSLv3 TLSv1; | ||||
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; | ||||
ssl_prefer_server_ciphers on; | ||||
|
r4182 | rewrite ^/(.+)$ https://your.kallithea.server/_admin/gists/$1; | ||
rewrite (.*) https://your.kallithea.server/_admin/gists; | ||||
r3850 | } | |||
r1092 | server { | |||
r3243 | listen 443; | |||
|
r4182 | server_name your.kallithea.server; | ||
|
r4192 | access_log /var/log/nginx/kallithea.access.log; | ||
error_log /var/log/nginx/kallithea.error.log; | ||||
r1745 | ||||
r3243 | ssl on; | |||
|
r4182 | ssl_certificate your.kallithea.server.crt; | ||
ssl_certificate_key your.kallithea.server.key; | ||||
r3243 | ||||
ssl_session_timeout 5m; | ||||
ssl_protocols SSLv3 TLSv1; | ||||
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; | ||||
ssl_prefer_server_ciphers on; | ||||
r3850 | ## uncomment root directive if you want to serve static files by nginx | |||
## requires static_files = false in .ini file | ||||
|
r4186 | #root /path/to/installation/kallithea/public; | ||
r3917 | include /etc/nginx/proxy.conf; | |||
r1092 | location / { | |||
|
r4902 | try_files $uri @kallithea; | ||
r1092 | } | |||
r3224 | ||||
|
r4902 | location @kallithea { | ||
proxy_pass http://kallithea; | ||||
r1745 | } | |||
r3224 | } | |||
r1092 | Here's the proxy.conf. It's tuned so it will not timeout on long | |||
pushes or large pushes:: | ||||
r3224 | ||||
r572 | proxy_redirect off; | |||
proxy_set_header Host $host; | ||||
r4073 | ## needed for container auth | |||
#proxy_set_header REMOTE_USER $remote_user; | ||||
#proxy_set_header X-Forwarded-User $remote_user; | ||||
r1745 | proxy_set_header X-Url-Scheme $scheme; | |||
r572 | proxy_set_header X-Host $http_host; | |||
proxy_set_header X-Real-IP $remote_addr; | ||||
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; | ||||
proxy_set_header Proxy-host $proxy_host; | ||||
proxy_buffering off; | ||||
r1420 | proxy_connect_timeout 7200; | |||
proxy_send_timeout 7200; | ||||
proxy_read_timeout 7200; | ||||
proxy_buffers 8 32k; | ||||
r3919 | client_max_body_size 1024m; | |||
client_body_buffer_size 128k; | ||||
large_client_header_buffers 8 64k; | ||||
r3224 | ||||
r881 | ||||
|
r1558 | Apache virtual host reverse proxy example | ||
----------------------------------------- | ||||
r881 | ||||
r1092 | Here is a sample configuration file for apache using proxy:: | |||
r881 | ||||
r929 | <VirtualHost *:80> | |||
ServerName hg.myserver.com | ||||
ServerAlias hg.myserver.com | ||||
r3224 | ||||
r929 | <Proxy *> | |||
Order allow,deny | ||||
Allow from all | ||||
</Proxy> | ||||
r3224 | ||||
r929 | #important ! | |||
#Directive to properly generate url (clone url) for pylons | ||||
ProxyPreserveHost On | ||||
r3224 | ||||
|
r4192 | #kallithea instance | ||
r929 | ProxyPass / http://127.0.0.1:5000/ | |||
ProxyPassReverse / http://127.0.0.1:5000/ | ||||
r3224 | ||||
r929 | #to enable https use line below | |||
#SetEnvIf X-Url-Scheme https HTTPS=1 | ||||
r3224 | ||||
</VirtualHost> | ||||
r881 | ||||
Additional tutorial | ||||
|
r4915 | http://pylonsbook.com/en/1.1/deployment.html#using-apache-to-proxy-requests-to-pylons | ||
r572 | ||||
r707 | ||||
r1062 | Apache as subdirectory | |||
---------------------- | ||||
Apache subdirectory part:: | ||||
r1226 | <Location /<someprefix> > | |||
ProxyPass http://127.0.0.1:5000/<someprefix> | ||||
ProxyPassReverse http://127.0.0.1:5000/<someprefix> | ||||
r1062 | SetEnvIf X-Url-Scheme https HTTPS=1 | |||
r3224 | </Location> | |||
r1062 | ||||
r1392 | Besides the regular apache setup you will need to add the following line | |||
into [app:main] section of your .ini file:: | ||||
r1062 | ||||
filter-with = proxy-prefix | ||||
Add the following at the end of the .ini file:: | ||||
[filter:proxy-prefix] | ||||
use = egg:PasteDeploy#prefix | ||||
r3224 | prefix = /<someprefix> | |||
r1062 | ||||
|
r3622 | then change <someprefix> into your chosen prefix | ||
r1226 | ||||
r1386 | Apache's WSGI config | |||
-------------------- | ||||
|
r4192 | Alternatively, Kallithea can be set up with Apache under mod_wsgi. For | ||
|
r1558 | that, you'll need to: | ||
- Install mod_wsgi. If using a Debian-based distro, you can install | ||||
the package libapache2-mod-wsgi:: | ||||
|
r1559 | |||
|
r1558 | aptitude install libapache2-mod-wsgi | ||
|
r1559 | |||
|
r1558 | - Enable mod_wsgi:: | ||
|
r1559 | |||
|
r1558 | a2enmod wsgi | ||
|
r1559 | |||
|
r1558 | - Create a wsgi dispatch script, like the one below. Make sure you | ||
|
r4192 | check the paths correctly point to where you installed Kallithea | ||
|
r1558 | and its Python Virtual Environment. | ||
- Enable the WSGIScriptAlias directive for the wsgi dispatch script, | ||||
as in the following example. Once again, check the paths are | ||||
correctly specified. | ||||
Here is a sample excerpt from an Apache Virtual Host configuration file:: | ||||
|
r4902 | WSGIDaemonProcess kallithea \ | ||
processes=1 threads=4 \ | ||||
python-path=/srv/kallithea/pyenv/lib/python2.7/site-packages | ||||
WSGIScriptAlias / /srv/kallithea/dispatch.wsgi | ||||
r2076 | WSGIPassAuthorization On | |||
r1386 | ||||
|
r4902 | Or if using a dispatcher wsgi script with proper virtualenv activation:: | ||
WSGIDaemonProcess kallithea processes=1 threads=4 | ||||
WSGIScriptAlias / /srv/kallithea/dispatch.wsgi | ||||
WSGIPassAuthorization On | ||||
r2800 | .. note:: | |||
|
r4902 | When running apache as root, please make sure it doesn't run Kallithea as | ||
root, for examply by adding: `user=www-data group=www-data` to the configuration. | ||||
r2800 | ||||
.. note:: | ||||
|
r4902 | If running Kallithea in multiprocess mode, | ||
make sure you set `instance_id = \*` in the configuration so each process | ||||
gets it's own cache invalidationkey. | ||||
r2800 | ||||
r1386 | Example wsgi dispatch script:: | |||
r707 | ||||
r1386 | import os | |||
os.environ["HGENCODING"] = "UTF-8" | ||||
|
r4902 | os.environ['PYTHON_EGG_CACHE'] = '/srv/kallithea/.egg-cache' | ||
r3224 | ||||
r1386 | # sometimes it's needed to set the curent dir | |||
|
r4902 | os.chdir('/srv/kallithea/') | ||
|
r1558 | |||
import site | ||||
|
r4902 | site.addsitedir("/srv/kallithea/pyenv/lib/python2.7/site-packages") | ||
r3224 | ||||
r1386 | from paste.deploy import loadapp | |||
from paste.script.util.logging_config import fileConfig | ||||
|
r4902 | fileConfig('/srv/kallithea/my.ini') | ||
application = loadapp('config:/srv/kallithea/my.ini') | ||||
Or using proper virtualenv activation:: | ||||
activate_this = '/srv/kallithea/venv/bin/activate_this.py' | ||||
execfile(activate_this,dict(__file__=activate_this)) | ||||
r1386 | ||||
|
r4902 | import os | ||
os.environ['HOME'] = '/srv/kallithea' | ||||
ini = '/srv/kallithea/kallithea.ini' | ||||
from paste.script.util.logging_config import fileConfig | ||||
fileConfig(ini) | ||||
from paste.deploy import loadapp | ||||
application = loadapp('config:' + ini) | ||||
|
r1558 | |||
r707 | ||||
r591 | Other configuration files | |||
------------------------- | ||||
|
r4902 | Some example init.d scripts can be found in init.d directory: https://kallithea-scm.org/repos/kallithea/files/tip/init.d/ | ||
r591 | ||||
r572 | .. _virtualenv: http://pypi.python.org/pypi/virtualenv | |||
.. _python: http://www.python.org/ | ||||
|
r4914 | .. _Mercurial: http://mercurial.selenic.com/ | ||
|
r4925 | .. _Celery: http://celeryproject.org/ | ||
.. _Celery documentation: http://docs.celeryproject.org/en/latest/getting-started/index.html | ||||
.. _RabbitMQ: http://www.rabbitmq.com/ | ||||
.. _Redis: http://redis.io/ | ||||
|
r992 | .. _python-ldap: http://www.python-ldap.org/ | ||
r1092 | .. _mercurial-server: http://www.lshift.net/mercurial-server.html | |||
.. _PublishingRepositories: http://mercurial.selenic.com/wiki/PublishingRepositories | ||||