setup.rst
735 lines
| 24.9 KiB
| text/x-rst
|
RstLexer
/ docs / setup.rst
r568 | .. _setup: | |||
r2095 | ===== | |||
r568 | Setup | |||
===== | ||||
r1092 | Setting up RhodeCode | |||
r1448 | -------------------- | |||
r572 | ||||
r3363 | First, you will need to create a RhodeCode configuration file. Run the | |||
r1309 | following command to do this:: | |||
r3363 | ||||
r1123 | paster make-config RhodeCode production.ini | |||
r572 | ||||
r1092 | - This will create the file `production.ini` in the current directory. This | |||
r3363 | configuration file contains the various settings for RhodeCode, e.g proxy | |||
port, email settings, usage of static files, cache, celery settings and | ||||
r1309 | logging. | |||
r845 | ||||
r1092 | Next, you need to create the databases used by RhodeCode. I recommend that you | |||
r2105 | use postgresql or sqlite (default). If you choose a database other than the | |||
r1092 | default ensure you properly adjust the db url in your production.ini | |||
r2105 | configuration file to use this other database. RhodeCode currently supports | |||
postgresql, sqlite and mysql databases. Create the database by running | ||||
r1092 | the following command:: | |||
r572 | ||||
r2284 | paster setup-rhodecode production.ini | |||
r572 | ||||
r1092 | This will prompt you for a "root" path. This "root" path is the location where | |||
RhodeCode will store all of its repositories on the current machine. After | ||||
r3363 | entering this "root" path ``setup-rhodecode`` will also prompt you for a username | |||
and password for the initial admin account which ``setup-rhodecode`` sets | ||||
r2284 | up for you. | |||
r845 | ||||
r2358 | setup process can be fully automated, example for lazy:: | |||
paster setup-rhodecode production.ini --user=marcink --password=secret --email=marcin@rhodecode.org --repos=/home/marcink/my_repos | ||||
r3363 | ||||
r2358 | ||||
r3363 | - The ``setup-rhodecode`` command will create all of the needed tables and an | |||
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 | |||
r3363 | choose a location which contains existing repositories RhodeCode will simply | |||
add all of the repositories at the chosen location to it's database. | ||||
r2284 | (Note: make sure you specify the correct path to the root). | |||
r1092 | - Note: the given path for mercurial_ repositories **must** be write accessible | |||
r3363 | for the application. It's very important since the RhodeCode web interface | |||
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 | ||||
r1092 | You are now ready to use RhodeCode, to run it simply execute:: | |||
r3363 | ||||
r1123 | paster serve production.ini | |||
r3363 | ||||
- This command runs the RhodeCode server. The web app should be available at the | ||||
127.0.0.1:5000. This ip and port is configurable via the production.ini | ||||
r845 | file created in previous step | |||
r3363 | - Use the admin account you created above when running ``setup-rhodecode`` | |||
r2284 | to login to the web app. | |||
r3363 | - The default permissions on each repository is read, and the owner is admin. | |||
r1092 | Remember to update these if needed. | |||
- In the admin panel you can toggle ldap, anonymous, permissions settings. As | ||||
well as edit more advanced options on users and repositories | ||||
r2105 | Optionally users can create `rcextensions` package that extends RhodeCode | |||
functionality. To do this simply execute:: | ||||
paster make-rcext production.ini | ||||
r1092 | ||||
r2105 | This will create `rcextensions` package in the same place that your `ini` file | |||
r3363 | 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. | |||
For example for sending signals to build-bots such as jenkins. | ||||
r3363 | Please see the `__init__.py` file inside `rcextensions` package | |||
r2105 | for more details. | |||
r1092 | ||||
r912 | Using RhodeCode with SSH | |||
------------------------ | ||||
r1309 | RhodeCode currently only hosts repositories using http and https. (The addition | |||
of ssh hosting is a planned future feature.) However you can easily use ssh in | ||||
r1092 | parallel with RhodeCode. (Repository access via ssh is a standard "out of | |||
the box" feature of mercurial_ and you can use this to access any of the | ||||
repositories that RhodeCode is hosting. See PublishingRepositories_) | ||||
r3363 | RhodeCode 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 | ||||
r3363 | 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 | ||||
using the RhodeCode web interface.) | ||||
r912 | ||||
r1092 | If your main directory (the same as set in RhodeCode settings) is for example | |||
set to **/home/hg** and the repository you are using is named `rhodecode`, then | ||||
to clone via ssh you should run:: | ||||
r912 | ||||
r1092 | hg clone ssh://user@server.com/home/hg/rhodecode | |||
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 | |||
permissions as set up via the RhodeCode web interface, you can create an | ||||
authentication hook to connect to the rhodecode db and runs check functions for | ||||
permissions against that. | ||||
r3363 | ||||
r683 | Setting up Whoosh full text search | |||
---------------------------------- | ||||
r1092 | Starting from version 1.1 the whoosh index can be build by using the paster | |||
command ``make-index``. To use ``make-index`` you must specify the configuration | ||||
r3363 | 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 | ||||
from the RhodeCode database. This was required prior to 1.2. Starting from | ||||
version 1.2 it is also possible to specify a comma separated list of | ||||
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 | ||||
r3363 | paster make-index production.ini | |||
r683 | ||||
r1092 | For a full index rebuild use:: | |||
r707 | ||||
r3363 | paster make-index production.ini -f | |||
r572 | ||||
r894 | ||||
building index just for chosen repositories is possible with such command:: | ||||
r3363 | ||||
|
r1408 | paster make-index production.ini --index-only=vcs,rhodecode | ||
r572 | ||||
r894 | ||||
r1092 | In order to do periodical index builds and keep your index always up to date. | |||
r3363 | It's recommended to do a crontab entry for incremental indexing. | |||
r1092 | An example entry might look like this:: | |||
r3363 | ||||
/path/to/python/bin/paster make-index /path/to/rhodecode/production.ini | ||||
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 | ||||
----------------------- | ||||
RhodeCode starting from version 1.1 supports ldap authentication. In order | ||||
r3363 | 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 | ||||
r1292 | using easy_install:: | |||
r707 | ||||
r1123 | easy_install python-ldap | |||
r3363 | ||||
r1292 | using pip:: | |||
r707 | ||||
r1123 | pip install python-ldap | |||
r707 | ||||
r770 | .. note:: | |||
r3363 | 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 | ||||
|
r992 | LDAP settings are located in admin->ldap section, | ||
r1092 | 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 | ||||
.. _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 | ||||
r3363 | ||||
r1292 | LDAPS connection | |||
r3363 | Enable ldaps connection. It will likely require `Port`_ to be set to | |||
a different value (standard LDAPS port is 636). When LDAPS is enabled | ||||
r1292 | then `Certificate Checks`_ is required. | |||
r3363 | ||||
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 | ||||
r3363 | `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 | ||||
r3363 | Login Attribute : required | |||
|
r992 | The LDAP record attribute that will be matched as the USERNAME or | ||
ACCOUNT used to connect to RhodeCode. This will be added to `LDAP | ||||
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 | ||
users should be granted access to RhodeCode with ldap accounts. At this | ||||
time user information is copied from LDAP into the RhodeCode user database. | ||||
This means that updates of an LDAP user object may not be reflected as a | ||||
user update in RhodeCode. | ||||
If You have problems with LDAP access and believe You entered correct | ||||
information check out the RhodeCode logs, any error messages sent from LDAP | ||||
will be saved there. | ||||
Active Directory | ||||
'''''''''''''''' | ||||
r707 | ||||
|
r992 | RhodeCode can use Microsoft Active Directory for user authentication. This | ||
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 | ||
-------------------------------------------- | ||||
Starting with version 1.3, RhodeCode supports delegating the authentication | ||||
of users to its WSGI container, or to a reverse-proxy server through which all | ||||
clients access the application. | ||||
When these authentication methods are enabled in RhodeCode, it uses the | ||||
username that the container/proxy (Apache/Nginx/etc) authenticated and doesn't | ||||
perform the authentication itself. The authorization, however, is still done by | ||||
RhodeCode according to its settings. | ||||
When a user logs in for the first time using these authentication methods, | ||||
a matching user account is created in RhodeCode with default permissions. An | ||||
administrator can then modify it using RhodeCode's admin interface. | ||||
It's also possible for an administrator to create accounts and configure their | ||||
permissions before the user logs in for the first time. | ||||
Container-based authentication | ||||
'''''''''''''''''''''''''''''' | ||||
In a container-based authentication setup, RhodeCode reads the user name from | ||||
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 | ||||
RhodeCode. | ||||
In order for RhodeCode to start using the provided username, you should set the | ||||
following in the [app:main] section of your .ini file:: | ||||
container_auth_enabled = true | ||||
Proxy pass-through authentication | ||||
''''''''''''''''''''''''''''''''' | ||||
In a proxy pass-through authentication setup, RhodeCode reads the user name | ||||
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 | ||||
AuthName "RhodeCode authentication" | ||||
AuthUserFile /home/web/rhodecode/.htpasswd | ||||
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 | ||||
r3363 | </Location> | |||
|
r1657 | |||
In order for RhodeCode to start using the forwarded username, you should set | ||||
the following in the [app:main] section of your .ini file:: | ||||
proxypass_auth_enabled = true | ||||
.. 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 | |||
r1838 | RhodeCode provides a simple integration with issue trackers. It's possible | |||
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:: | ||||
url_pat = (?:^#|\s#)(\w+) | ||||
r1870 | issue_server_link = https://myissueserver.com/{repo}/issue/{id} | |||
r1838 | issue_prefix = # | |||
r1870 | `url_pat` is the regular expression that will fetch issues from commit messages. | |||
Default regex will match issues in format of #<number> eg. #300. | ||||
r3363 | ||||
Matched issues will be replace with the link specified as `issue_server_link` | ||||
r1870 | {id} will be replaced with issue id, and {repo} with repository name. | |||
r3363 | Since the # is striped `issue_prefix` is added as a prefix to url. | |||
`issue_prefix` can be something different than # if you pass | ||||
r1870 | ISSUE- as issue prefix this will generate an url in format:: | |||
r3363 | ||||
<a href="https://myissueserver.com/example_repo/issue/300">ISSUE-300</a> | ||||
|
r1657 | |||
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 | ||||
r3363 | Settings in Admin. | |||
r1467 | ||||
There are 4 built in hooks that cannot be changed (only enable/disable by | ||||
checkboxes on previos section). | ||||
r3363 | To add another custom hook simply fill in first section with | |||
r1467 | <name>.<hook_type> and the second one with hook path. Example hooks | |||
r3363 | can be found at *rhodecode.lib.hooks*. | |||
r1467 | ||||
r2017 | Changing default encoding | |||
------------------------- | ||||
By default RhodeCode uses utf8 encoding, starting from 1.3 series this | ||||
can be changed, simply edit default_encoding in .ini file to desired one. | ||||
This affects many parts in rhodecode including commiters names, filenames, | ||||
encoding of commit messages. In addition RhodeCode can detect if `chardet` | ||||
library is installed. If `chardet` is detected RhodeCode will fallback to it | ||||
when there are encode/decode errors. | ||||
r777 | Setting Up Celery | |||
----------------- | ||||
r1092 | Since version 1.1 celery is configured by the rhodecode ini configuration files. | |||
r3363 | Simply set use_celery=true in the ini file then add / change the configuration | |||
r777 | variables inside the ini file. | |||
r1092 | Remember that the ini files use the format with '.' not with '_' like celery. | |||
So for example setting `BROKER_HOST` in celery means setting `broker.host` in | ||||
r777 | the config file. | |||
r1092 | In order to start using celery run:: | |||
r938 | ||||
r777 | paster celeryd <configfile.ini> | |||
r871 | .. note:: | |||
r3363 | Make sure you run this command from the same virtualenv, and with the same | |||
r1309 | user that rhodecode runs. | |||
r3363 | ||||
r1062 | HTTPS support | |||
------------- | ||||
r1092 | There are two ways to enable https: | |||
- Set HTTP_X_URL_SCHEME in your http server headers, than rhodecode will | ||||
recognize this headers and make proper https redirections | ||||
r3363 | - Alternatively, change the `force_https = true` flag in the ini configuration | |||
r1448 | to force using https, no headers are needed than to enable https | |||
r871 | ||||
r572 | Nginx virtual host example | |||
-------------------------- | ||||
r707 | Sample config for nginx using proxy:: | |||
r572 | ||||
r1745 | upstream rc { | |||
server 127.0.0.1:5000; | ||||
# add more instances for load balancing | ||||
#server 127.0.0.1:5001; | ||||
#server 127.0.0.1:5002; | ||||
} | ||||
r3363 | ||||
r1092 | server { | |||
r3363 | listen 443; | |||
server_name rhodecode.myserver.com; | ||||
r1092 | access_log /var/log/nginx/rhodecode.access.log; | |||
error_log /var/log/nginx/rhodecode.error.log; | ||||
r1745 | ||||
r3363 | ssl on; | |||
ssl_certificate rhodecode.myserver.com.crt; | ||||
ssl_certificate_key rhodecode.myserver.com.key; | ||||
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; | ||||
r2682 | # uncomment if you have nginx with chunking module compiled | |||
# fixes the issues of having to put postBuffer data for large git | ||||
r3363 | # pushes | |||
r2682 | #chunkin on; | |||
#error_page 411 = @my_411_error; | ||||
#location @my_411_error { | ||||
# chunkin_resume; | ||||
#} | ||||
r3363 | ||||
r2748 | # uncomment if you want to serve static files by nginx | |||
#root /path/to/installation/rhodecode/public; | ||||
r3363 | ||||
r1092 | location / { | |||
r1745 | try_files $uri @rhode; | |||
r1092 | } | |||
r3363 | ||||
r1745 | location @rhode { | |||
proxy_pass http://rc; | ||||
include /etc/nginx/proxy.conf; | ||||
} | ||||
r3363 | } | |||
r1092 | Here's the proxy.conf. It's tuned so it will not timeout on long | |||
pushes or large pushes:: | ||||
r3363 | ||||
r572 | proxy_redirect off; | |||
proxy_set_header Host $host; | ||||
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; | ||||
client_max_body_size 400m; | ||||
client_body_buffer_size 128k; | ||||
proxy_buffering off; | ||||
r1420 | proxy_connect_timeout 7200; | |||
proxy_send_timeout 7200; | ||||
proxy_read_timeout 7200; | ||||
proxy_buffers 8 32k; | ||||
r3363 | ||||
r1092 | Also, when using root path with nginx you might set the static files to false | |||
in the production.ini file:: | ||||
r572 | ||||
r1092 | [app:main] | |||
use = egg:rhodecode | ||||
full_stack = true | ||||
static_files = false | ||||
lang=en | ||||
cache_dir = %(here)s/data | ||||
r572 | ||||
r1092 | In order to not have the statics served by the application. This improves speed. | |||
r572 | ||||
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 | ||||
r3363 | ||||
r929 | <Proxy *> | |||
Order allow,deny | ||||
Allow from all | ||||
</Proxy> | ||||
r3363 | ||||
r929 | #important ! | |||
#Directive to properly generate url (clone url) for pylons | ||||
ProxyPreserveHost On | ||||
r3363 | ||||
r929 | #rhodecode instance | |||
ProxyPass / http://127.0.0.1:5000/ | ||||
ProxyPassReverse / http://127.0.0.1:5000/ | ||||
r3363 | ||||
r929 | #to enable https use line below | |||
#SetEnvIf X-Url-Scheme https HTTPS=1 | ||||
r3363 | ||||
</VirtualHost> | ||||
r881 | ||||
Additional tutorial | ||||
r744 | http://wiki.pylonshq.com/display/pylonscookbook/Apache+as+a+reverse+proxy+for+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 | |||
r3363 | </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 | ||||
r3363 | prefix = /<someprefix> | |||
r1062 | ||||
r1226 | then change <someprefix> into your choosen prefix | |||
r1386 | Apache's WSGI config | |||
-------------------- | ||||
|
r1558 | Alternatively, RhodeCode can be set up with Apache under mod_wsgi. For | ||
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 | ||
check the paths correctly point to where you installed RhodeCode | ||||
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:: | ||||
r2800 | WSGIDaemonProcess pylons \ | |||
|
r1558 | threads=4 \ | ||
python-path=/home/web/rhodecode/pyenv/lib/python2.6/site-packages | ||||
WSGIScriptAlias / /home/web/rhodecode/dispatch.wsgi | ||||
r2076 | WSGIPassAuthorization On | |||
r1386 | ||||
r2800 | .. note:: | |||
r3363 | when running apache as root please add: `user=www-data group=www-data` | |||
r2800 | into above configuration | |||
.. note:: | ||||
r3363 | Running RhodeCode in multiprocess mode in apache is not supported, | |||
make sure you don't specify `processes=num` directive in the config | ||||
r2800 | ||||
r1386 | Example wsgi dispatch script:: | |||
r707 | ||||
r1386 | import os | |||
os.environ["HGENCODING"] = "UTF-8" | ||||
os.environ['PYTHON_EGG_CACHE'] = '/home/web/rhodecode/.egg-cache' | ||||
r3363 | ||||
r1386 | # sometimes it's needed to set the curent dir | |||
r3363 | os.chdir('/home/web/rhodecode/') | |||
|
r1558 | |||
import site | ||||
site.addsitedir("/home/web/rhodecode/pyenv/lib/python2.6/site-packages") | ||||
r3363 | ||||
r1386 | from paste.deploy import loadapp | |||
from paste.script.util.logging_config import fileConfig | ||||
fileConfig('/home/web/rhodecode/production.ini') | ||||
application = loadapp('config:/home/web/rhodecode/production.ini') | ||||
|
r1558 | Note: when using mod_wsgi you'll need to install the same version of | ||
Mercurial that's inside RhodeCode's virtualenv also on the system's Python | ||||
environment. | ||||
r707 | ||||
r591 | Other configuration files | |||
------------------------- | ||||
r2601 | Some example init.d scripts can be found in init.d directory:: | |||
r707 | ||||
r2601 | https://secure.rhodecode.org/rhodecode/files/beta/init.d | |||
r591 | ||||
r572 | .. _virtualenv: http://pypi.python.org/pypi/virtualenv | |||
.. _python: http://www.python.org/ | ||||
.. _mercurial: http://mercurial.selenic.com/ | ||||
.. _celery: http://celeryproject.org/ | ||||
|
r992 | .. _rabbitmq: http://www.rabbitmq.com/ | ||
.. _python-ldap: http://www.python-ldap.org/ | ||||
r1092 | .. _mercurial-server: http://www.lshift.net/mercurial-server.html | |||
.. _PublishingRepositories: http://mercurial.selenic.com/wiki/PublishingRepositories | ||||
.. _Issues tracker: https://bitbucket.org/marcinkuzminski/rhodecode/issues | ||||
r3363 | .. _google group rhodecode: http://groups.google.com/group/rhodecode | |||