setup.rst
573 lines
| 18.8 KiB
| text/x-rst
|
RstLexer
/ docs / setup.rst
r568 | .. _setup: | |||
Setup | ||||
===== | ||||
r1092 | Setting up RhodeCode | |||
r1448 | -------------------- | |||
r572 | ||||
r1309 | First, you will need to create a RhodeCode configuration file. Run the | |||
following command to do this:: | ||||
r572 | ||||
r1123 | paster make-config RhodeCode production.ini | |||
r572 | ||||
r1092 | - This will create the file `production.ini` in the current directory. This | |||
r1309 | configuration file contains the various settings for RhodeCode, e.g proxy | |||
port, email settings, usage of static files, cache, celery settings and | ||||
logging. | ||||
r845 | ||||
r1092 | Next, you need to create the databases used by RhodeCode. I recommend that you | |||
use sqlite (default) or postgresql. If you choose a database other than the | ||||
default ensure you properly adjust the db url in your production.ini | ||||
configuration file to use this other database. Create the databases by running | ||||
the following command:: | ||||
r572 | ||||
r1123 | paster setup-app 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 | ||||
r1309 | entering this "root" path ``setup-app`` will also prompt you for a username | |||
and password for the initial admin account which ``setup-app`` sets up for you. | ||||
r845 | ||||
r1092 | - The ``setup-app`` command will create all of the needed tables and an admin | |||
r1309 | account. When choosing a root path you can either use a new empty location, | |||
or a location which already contains existing repositories. If you choose a | ||||
location which contains existing repositories RhodeCode will simply add all | ||||
of the repositories at the chosen location to it's database. (Note: make | ||||
sure you specify the correct path to the root). | ||||
r1092 | - Note: the given path for mercurial_ repositories **must** be write accessible | |||
r1309 | 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 | ||||
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:: | |||
r572 | ||||
r1123 | paster serve production.ini | |||
r572 | ||||
r1092 | - This command runs the RhodeCode server. The web app should be available at the | |||
r572 | 127.0.0.1:5000. This ip and port is configurable via the production.ini | |||
r845 | file created in previous step | |||
r1309 | - Use the admin account you created above when running ``setup-app`` to login | |||
to the web app. | ||||
r1092 | - The default permissions on each repository is read, and the owner is admin. | |||
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 | ||||
Try copying your own mercurial repository into the "root" directory you are | ||||
using, then from within the RhodeCode web application choose Admin > | ||||
r1309 | repositories. Then choose Add New Repository. Add the repository you copied | |||
into the root. Test that you can browse your repository from within RhodeCode | ||||
and then try cloning your repository from RhodeCode with:: | ||||
r1092 | ||||
r1123 | hg clone http://127.0.0.1:5000/<repository name> | |||
r1092 | ||||
where *repository name* is replaced by the name of your repository. | ||||
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_) | ||||
r912 | 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 | ||||
r1309 | In order to use ssh you need to make sure that your web-server and the users | |||
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. | ||||
r592 | ||||
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 | ||||
Jared Bunting
|
r1408 | 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 | ||||
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 | ||||
Jared Bunting
|
r1408 | paster make-index production.ini | ||
r683 | ||||
r1092 | For a full index rebuild use:: | |||
r707 | ||||
Jared Bunting
|
r1408 | paster make-index production.ini -f | ||
r572 | ||||
r894 | ||||
building index just for chosen repositories is possible with such command:: | ||||
Jared Bunting
|
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. | |||
r894 | It's recommended to do a crontab entry for incremental indexing. | |||
r1092 | An example entry might look like this:: | |||
r572 | ||||
Jared Bunting
|
r1408 | /path/to/python/bin/paster make-index /path/to/rhodecode/production.ini | ||
r572 | ||||
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 | ||||
r1292 | to use LDAP, you have to install the python-ldap_ package. This package is | |||
available via pypi, so you can install it by running | ||||
r707 | ||||
r1292 | using easy_install:: | |||
r707 | ||||
r1123 | easy_install python-ldap | |||
r707 | ||||
r1292 | using pip:: | |||
r707 | ||||
r1123 | pip install python-ldap | |||
r707 | ||||
r770 | .. note:: | |||
r1092 | python-ldap requires some certain libs on your system, so before installing | |||
it check that you have at least `openldap`, and `sasl` libraries. | ||||
r707 | ||||
Thayne Harbaugh
|
r992 | LDAP settings are located in admin->ldap section, | ||
r1092 | Here's a typical ldap setup:: | |||
Thayne Harbaugh
|
r992 | |||
Connection settings | ||||
Enable LDAP = checked | ||||
Host = host.example.org | ||||
Port = 389 | ||||
Account = <account> | ||||
Password = <password> | ||||
r1292 | Connection Security = LDAPS connection | |||
Thayne Harbaugh
|
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 | ||||
Thayne Harbaugh
|
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 | ||||
LDAP server hostname or IP address. | ||||
.. _Port: | ||||
Port : required | ||||
389 for un-encrypted LDAP, 636 for SSL-encrypted LDAP. | ||||
.. _ldap_account: | ||||
r707 | ||||
Thayne Harbaugh
|
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 | ||||
LDAPS connection | ||||
Enable ldaps connection. It will likely require `Port`_ to be set to | ||||
a different value (standard LDAPS port is 636). When LDAPS is enabled | ||||
then `Certificate Checks`_ is required. | ||||
START_TLS on LDAP connection | ||||
START TLS connection | ||||
Thayne Harbaugh
|
r992 | |||
.. _Certificate Checks: | ||||
r707 | ||||
Thayne Harbaugh
|
r992 | Certificate Checks : optional | ||
How SSL certificates verification is handled - this is only useful when | ||||
r1309 | `Enable LDAPS`_ is enabled. Only DEMAND or HARD offer full SSL security | |||
while the other options are susceptible to man-in-the-middle attacks. SSL | ||||
Thayne Harbaugh
|
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 | ||||
Thayne Harbaugh
|
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 | ||||
Thayne Harbaugh
|
r992 | Login Attribute : required | ||
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 | ||||
Thayne Harbaugh
|
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 | ||||
Thayne Harbaugh
|
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 | ||||
Thayne Harbaugh
|
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 | ||||
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 | ||||
Settings in Admin. | ||||
There are 4 built in hooks that cannot be changed (only enable/disable by | ||||
checkboxes on previos section). | ||||
To add another custom hook simply fill in first section with | ||||
<name>.<hook_type> and the second one with hook path. Example hooks | ||||
can be found at *rhodecode.lib.hooks*. | ||||
r777 | Setting Up Celery | |||
----------------- | ||||
r1092 | Since version 1.1 celery is configured by the rhodecode ini configuration files. | |||
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:: | |||
r1309 | Make sure you run this command from the same virtualenv, and with the same | |||
user that rhodecode runs. | ||||
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 | ||||
r1448 | - Alternatively, change the `force_https = true` flag in the ini configuration | |||
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 | ||||
r1092 | server { | |||
listen 80; | ||||
server_name hg.myserver.com; | ||||
access_log /var/log/nginx/rhodecode.access.log; | ||||
error_log /var/log/nginx/rhodecode.error.log; | ||||
location / { | ||||
root /var/www/rhodecode/rhodecode/public/; | ||||
if (!-f $request_filename){ | ||||
proxy_pass http://127.0.0.1:5000; | ||||
} | ||||
#this is important if you want to use https !!! | ||||
proxy_set_header X-Url-Scheme $scheme; | ||||
include /etc/nginx/proxy.conf; | ||||
} | ||||
} | ||||
r568 | ||||
r1092 | Here's the proxy.conf. It's tuned so it will not timeout on long | |||
pushes or large pushes:: | ||||
r572 | ||||
proxy_redirect off; | ||||
proxy_set_header Host $host; | ||||
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; | ||||
r572 | ||||
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 | ||||
Apache virtual host example | ||||
--------------------------- | ||||
r1092 | Here is a sample configuration file for apache using proxy:: | |||
r881 | ||||
r929 | <VirtualHost *:80> | |||
ServerName hg.myserver.com | ||||
ServerAlias hg.myserver.com | ||||
<Proxy *> | ||||
Order allow,deny | ||||
Allow from all | ||||
</Proxy> | ||||
#important ! | ||||
#Directive to properly generate url (clone url) for pylons | ||||
ProxyPreserveHost On | ||||
#rhodecode instance | ||||
ProxyPass / http://127.0.0.1:5000/ | ||||
ProxyPassReverse / http://127.0.0.1:5000/ | ||||
#to enable https use line below | ||||
#SetEnvIf X-Url-Scheme https HTTPS=1 | ||||
</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 | |||
</Location> | ||||
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 | ||||
prefix = /<someprefix> | ||||
r1226 | then change <someprefix> into your choosen prefix | |||
r1386 | Apache's WSGI config | |||
-------------------- | ||||
Example wsgi dispatch script:: | ||||
r707 | ||||
r1386 | import os | |||
os.environ["HGENCODING"] = "UTF-8" | ||||
os.environ['PYTHON_EGG_CACHE'] = '/home/web/rhodecode/.egg-cache' | ||||
# sometimes it's needed to set the curent dir | ||||
os.chdir('/home/web/rhodecode/') | ||||
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') | ||||
r707 | ||||
r591 | Other configuration files | |||
------------------------- | ||||
r1092 | Some example init.d scripts can be found here, for debian and gentoo: | |||
r591 | ||||
r1284 | https://rhodecode.org/rhodecode/files/tip/init.d | |||
r881 | ||||
r591 | ||||
r707 | Troubleshooting | |||
--------------- | ||||
r1092 | :Q: **Missing static files?** | |||
:A: Make sure either to set the `static_files = true` in the .ini file or | ||||
double check the root path for your http setup. It should point to | ||||
r707 | for example: | |||
/home/my-virtual-python/lib/python2.6/site-packages/rhodecode/public | ||||
r1092 | | | |||
r707 | ||||
r1092 | :Q: **Can't install celery/rabbitmq** | |||
:A: Don't worry RhodeCode works without them too. No extra setup is required. | ||||
r707 | ||||
r1092 | | | |||
r707 | ||||
r1092 | :Q: **Long lasting push timeouts?** | |||
:A: Make sure you set a longer timeouts in your proxy/fcgi settings, timeouts | ||||
are caused by https server and not RhodeCode. | ||||
| | ||||
r707 | ||||
r1092 | :Q: **Large pushes timeouts?** | |||
:A: Make sure you set a proper max_body_size for the http server. | ||||
| | ||||
r591 | ||||
r1092 | :Q: **Apache doesn't pass basicAuth on pull/push?** | |||
:A: Make sure you added `WSGIPassAuthorization true`. | ||||
r1309 | For further questions search the `Issues tracker`_, or post a message in the | |||
`google group rhodecode`_ | ||||
r591 | ||||
r572 | .. _virtualenv: http://pypi.python.org/pypi/virtualenv | |||
.. _python: http://www.python.org/ | ||||
.. _mercurial: http://mercurial.selenic.com/ | ||||
.. _celery: http://celeryproject.org/ | ||||
Thayne Harbaugh
|
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 | ||||
Jared Bunting
|
r1408 | .. _google group rhodecode: http://groups.google.com/group/rhodecode | ||