setup.rst
301 lines
| 9.3 KiB
| text/x-rst
|
RstLexer
/ docs / setup.rst
r568 | .. _setup: | ||
Setup | |||
===== | |||
r572 | Setting up the application | ||
-------------------------- | |||
r845 | First You'll ned to create RhodeCode config file. Run the following command | ||
to do this | |||
r572 | :: | ||
paster make-config RhodeCode production.ini | |||
- This will create `production.ini` config inside the directory | |||
r715 | this config contains various settings for RhodeCode, e.g proxy port, | ||
r845 | email settings, usage of static files, cache, celery settings and logging. | ||
Next we need to create the database. | |||
r572 | |||
:: | |||
r597 | paster setup-app production.ini | ||
r572 | |||
- This command will create all needed tables and an admin account. | |||
When asked for a path You can either use a new location of one with already | |||
existing ones. RhodeCode will simply add all new found repositories to | |||
it's database. Also make sure You specify correct path to repositories. | |||
- Remember that the given path for mercurial_ repositories must be write | |||
r845 | accessible for the application. It's very important since RhodeCode web | ||
interface will work even without such an access but, when trying to do a | |||
push it'll eventually fail with permission denied errors. | |||
You are ready to use rhodecode, to run it simply execute | |||
r572 | |||
:: | |||
paster serve production.ini | |||
r715 | - This command runs the RhodeCode server the 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 | ||
r572 | - Use admin account you created to login. | ||
- Default permissions on each repository is read, and owner is admin. So | |||
r845 | 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 | |||
r572 | |||
r592 | |||
r683 | Setting up Whoosh full text search | ||
---------------------------------- | |||
Index for whoosh can be build starting from version 1.1 using paster command | |||
passing repo locations to index, as well as Your config file that stores | |||
whoosh index files locations. There is possible to pass `-f` to the options | |||
to enable full index rebuild. Without that indexing will run always in in | |||
incremental mode. | |||
:: | |||
r707 | |||
r845 | paster make-index production.ini --repo-location=<location for repos> | ||
r683 | |||
for full index rebuild You can use | |||
:: | |||
r707 | |||
r845 | paster make-index production.ini -f --repo-location=<location for repos> | ||
r572 | |||
- For full text search You can either put crontab entry for | |||
r683 | This command can be run even from crontab in order to do periodical | ||
index builds and keep Your index always up to date. An example entry might | |||
look like this | |||
r572 | :: | ||
r845 | /path/to/python/bin/paster /path/to/rhodecode/production.ini --repo-location=<location for repos> | ||
r572 | |||
r683 | When using incremental(default) mode whoosh will check last modification date | ||
of each file and add it to reindex if newer file is available. Also indexing | |||
daemon checks for removed files and removes them from index. | |||
Sometime You might want to rebuild index from scratch. You can do that using | |||
the `-f` flag passed to paster command or, in 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 | |||
r733 | to use ldap, You have to install python-ldap package. This package is available | ||
r707 | via pypi, so You can install it by running | ||
:: | |||
r733 | easy_install python-ldap | ||
r707 | |||
:: | |||
r733 | pip install python-ldap | ||
r707 | |||
r770 | .. note:: | ||
python-ldap requires some certain libs on Your system, so before installing | |||
it check that You have at least `openldap`, and `sasl` libraries. | |||
r707 | |||
r770 | ldap settings are located in admin->ldap section, | ||
r707 | |||
Here's a typical ldap setup:: | |||
r770 | Enable ldap = checked #controls if ldap access is enabled | ||
Host = host.domain.org #actual ldap server to connect | |||
r707 | Port = 389 or 689 for ldaps #ldap server ports | ||
Enable LDAPS = unchecked #enable disable ldaps | |||
Account = <account> #access for ldap server(if required) | |||
Password = <password> #password for ldap server(if required) | |||
r770 | Base DN = uid=%(user)s,CN=users,DC=host,DC=domain,DC=org | ||
r707 | |||
`Account` and `Password` are optional, and used for two-phase ldap | |||
authentication so those are credentials to access Your ldap, if it doesn't | |||
r775 | support anonymous search/user lookups. | ||
Base DN must have %(user)s template inside, it's a placer where Your uid used | |||
to login would go, it allows admins to specify not standard schema for uid | |||
variable | |||
r707 | |||
r733 | If all data are entered correctly, and `python-ldap` is properly installed | ||
r770 | Users should be granted to access RhodeCode wit ldap accounts. When | ||
r715 | logging at the first time an special ldap account is created inside RhodeCode, | ||
r707 | so You can control over permissions even on ldap users. If such user exists | ||
r715 | already in RhodeCode database ldap user with the same username would be not | ||
able to access RhodeCode. | |||
r707 | |||
If You have problems with ldap access and believe You entered correct | |||
r715 | information check out the RhodeCode logs,any error messages sent from | ||
r707 | ldap will be saved there. | ||
r777 | |||
Setting Up Celery | |||
----------------- | |||
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 | |||
variables inside the ini file. | |||
Remember that the ini files uses format with '.' not with '_' like celery | |||
so for example setting `BROKER_HOST` in celery means setting `broker.host` in | |||
the config file. | |||
In order to make start using celery run:: | |||
r939 | |||
r777 | paster celeryd <configfile.ini> | ||
r939 | .. note:: | ||
Make sure You run this command from same virtualenv, and with the same user | |||
that rhodecode runs. | |||
r921 | HTTPS support | ||
------------- | |||
There are two ways to enable https, first is to set HTTP_X_URL_SCHEME in | |||
Your http server headers, than rhodecode will recognise this headers and make | |||
proper https redirections, another way is to set `force_https = true` | |||
in the ini cofiguration to force using https, no headers are needed than to | |||
enable https | |||
r572 | Nginx virtual host example | ||
-------------------------- | |||
r707 | Sample config for nginx using proxy:: | ||
r572 | |||
server { | |||
listen 80; | |||
server_name hg.myserver.com; | |||
access_log /var/log/nginx/rhodecode.access.log; | |||
r592 | error_log /var/log/nginx/rhodecode.error.log; | ||
r572 | location / { | ||
root /var/www/rhodecode/rhodecode/public/; | |||
if (!-f $request_filename){ | |||
proxy_pass http://127.0.0.1:5000; | |||
} | |||
r939 | #this is important if You want to use https !!! | ||
r572 | proxy_set_header X-Url-Scheme $scheme; | ||
include /etc/nginx/proxy.conf; | |||
} | |||
} | |||
r568 | |||
r592 | Here's the proxy.conf. It's tuned so it'll not timeout on long | ||
r572 | pushes and also on large pushes:: | ||
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; | |||
proxy_connect_timeout 3600; | |||
proxy_send_timeout 3600; | |||
proxy_read_timeout 3600; | |||
proxy_buffer_size 8k; | |||
proxy_buffers 8 32k; | |||
proxy_busy_buffers_size 64k; | |||
proxy_temp_file_write_size 64k; | |||
Also when using root path with nginx You might set the static files to false | |||
in production.ini file:: | |||
[app:main] | |||
use = egg:rhodecode | |||
full_stack = true | |||
static_files = false | |||
lang=en | |||
cache_dir = %(here)s/data | |||
r592 | To not have the statics served by the application. And improve speed. | ||
r572 | |||
r921 | |||
Apache virtual host example | |||
--------------------------- | |||
Sample config for apache using proxy:: | |||
r926 | <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> | |||
r921 | |||
Additional tutorial | |||
r744 | http://wiki.pylonshq.com/display/pylonscookbook/Apache+as+a+reverse+proxy+for+Pylons | ||
r572 | |||
r707 | |||
Apache's example FCGI config | |||
---------------------------- | |||
TODO ! | |||
r591 | Other configuration files | ||
------------------------- | |||
r939 | Some example init.d script can be found here, for debian and gentoo: | ||
r591 | |||
r939 | https://rhodeocode.org/rhodecode/files/tip/init.d | ||
r591 | |||
r707 | Troubleshooting | ||
--------------- | |||
- missing static files ? | |||
- 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 | |||
for example: | |||
/home/my-virtual-python/lib/python2.6/site-packages/rhodecode/public | |||
- can't install celery/rabbitmq | |||
- don't worry RhodeCode works without them too. No extra setup required | |||
- long lasting push timeouts ? | |||
- make sure You set a longer timeouts in Your proxy/fcgi settings, timeouts | |||
r715 | are caused by https server and not RhodeCode | ||
r707 | |||
- large pushes timeouts ? | |||
- make sure You set a proper max_body_size for the http server | |||
r591 | |||
r572 | .. _virtualenv: http://pypi.python.org/pypi/virtualenv | ||
.. _python: http://www.python.org/ | |||
.. _mercurial: http://mercurial.selenic.com/ | |||
.. _celery: http://celeryproject.org/ | |||
.. _rabbitmq: http://www.rabbitmq.com/ |