diff --git a/docs/setup.rst b/docs/setup.rst --- a/docs/setup.rst +++ b/docs/setup.rst @@ -4,126 +4,134 @@ Setup ===== -Setting up the application +Setting up RhodeCode -------------------------- -First You'll need to create RhodeCode config file. Run the following command -to do this - -:: +First, you will need to create a RhodeCode configuration file. Run the following +command to do this:: paster make-config RhodeCode production.ini -- This will create `production.ini` config inside the directory - this config contains various settings for RhodeCode, e.g proxy port, +- This will create the file `production.ini` in the current directory. This + configuration file contains the various settings for RhodeCode, e.g proxy port, email settings, usage of static files, cache, celery settings and logging. -Next we need to create the database. I'll recommend to use sqlite (default) -or postgresql. Make sure You properly adjust the db url in the .ini file to use -other than the default sqlite database - - -:: +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:: paster setup-app production.ini -- 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 - 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. +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 +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. -You are ready to use RhodeCode, to run it simply execute +- The ``setup-app`` command will create all of the needed tables and an admin + 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). +- Note: the given path for mercurial_ repositories **must** be write accessible + 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. -:: +You are now ready to use RhodeCode, to run it simply execute:: paster serve production.ini -- This command runs the RhodeCode server the app should be available at the +- 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 file created in previous step -- Use admin account you created to login. -- Default permissions on each repository is read, and owner is admin. So - 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 - +- Use the admin account you created above when running ``setup-app`` to login to the web app. +- 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 > +repositories. Then choose Add New Repository. Add the repository you copied into +the root. Test that you can browse your repository from within RhodCode and then +try cloning your repository from RhodeCode with:: + + hg clone http://127.0.0.1:5000/ + +where *repository name* is replaced by the name of your repository. + Using RhodeCode with SSH ------------------------ RhodeCode repository structures are kept in directories with the same name -as the project, when using repository groups, each group is a a subdirectory. -This will allow You to use ssh for accessing repositories quite easy. There +as the project, when using repository groups, each group is a subdirectory. +This will allow you to use ssh for accessing repositories quite easily. There are some exceptions when using ssh for accessing repositories. -You have to make sure that the webserver as well as the ssh users have unix -permission for directories. Secondly when using ssh rhodecode will not -authenticate those requests and permissions set by the web interface will not -work on the repositories accessed via ssh. There is a solution to this to use -auth hooks, that connects to rhodecode db, and runs check functions for +You have to make sure that the web-server as well as the ssh users have unix +permission for the appropriate directories. Secondly, when using ssh rhodecode +will not authenticate those requests and permissions set by the web interface +will not work on the repositories accessed via ssh. There is a solution to this +to use auth hooks, that connects to rhodecode db, and runs check functions for permissions. -if Your main directory (the same as set in RhodeCode settings) is for example -set for to **/home/hg** and repository You are using is `rhodecode` - -The command runned should look like this:: +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:: hg clone ssh://user@server.com/home/hg/rhodecode -Using external tools such as mercurial server or using ssh key based auth is -fully supported. +Using external tools such as mercurial server or using ssh key based +authentication is fully supported. Setting up Whoosh full text search ---------------------------------- -Starting from version 1.1 whoosh index can be build using paster command. -You have to specify the config file that stores location of index, and -location of repositories (`--repo-location`). +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 +file that stores the location of the index, and the location of the repositories +(`--repo-location`). -There is possible also to pass `-f` to the options -to enable full index rebuild. Without that indexing will run always in in -incremental mode. +You may optionally pass the option `-f` to enable a full index rebuild. Without +the `-f` option, indexing will run always in "incremental" mode. -incremental mode:: +For an incremental index build use:: paster make-index production.ini --repo-location= - -for full index rebuild You can use:: +For a full index rebuild use:: paster make-index production.ini -f --repo-location= -- For full text search You can either put crontab entry for +- For full text search you can either put crontab entry for -In order to do periodical index builds and keep Your index always up to date. +In order to do periodical index builds and keep your index always up to date. It's recommended to do a crontab entry for incremental indexing. -An example entry might look like this - -:: +An example entry might look like this:: /path/to/python/bin/paster /path/to/rhodecode/production.ini --repo-location= -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. +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. -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. +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. Setting up LDAP support ----------------------- RhodeCode starting from version 1.1 supports ldap authentication. In order -to use LDAP, You have to install python-ldap_ package. This package is available -via pypi, so You can install it by running +to use LDAP, you have to install python-ldap_ package. This package is available +via pypi, so you can install it by running :: @@ -134,8 +142,8 @@ via pypi, so You can install it by runni pip install python-ldap .. note:: - python-ldap requires some certain libs on Your system, so before installing - it check that You have at least `openldap`, and `sasl` libraries. + python-ldap requires some certain libs on your system, so before installing + it check that you have at least `openldap`, and `sasl` libraries. ldap settings are located in admin->ldap section, @@ -151,21 +159,21 @@ Here's a typical ldap setup:: `Account` and `Password` are optional, and used for two-phase ldap -authentication so those are credentials to access Your ldap, if it doesn't +authentication so those are credentials to access your ldap, if it doesn't support anonymous search/user lookups. -Base DN must have %(user)s template inside, it's a placer where Your uid used +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 If all data are entered correctly, and `python-ldap` is properly installed Users should be granted to access RhodeCode wit ldap accounts. When logging at the first time an special ldap account is created inside RhodeCode, -so You can control over permissions even on ldap users. If such user exists +so you can control over permissions even on ldap users. If such user exists already in RhodeCode database ldap user with the same username would be not able to access RhodeCode. -If You have problems with ldap access and believe You entered correct +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. @@ -188,14 +196,14 @@ In order to make start using celery run: .. note:: - Make sure You run this command from same virtualenv, and with the same user + Make sure you run this command from same virtualenv, and with the same user that rhodecode runs. 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 +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 @@ -216,7 +224,7 @@ Sample config for nginx using proxy:: if (!-f $request_filename){ proxy_pass http://127.0.0.1:5000; } - #this is important if You want to use https !!! + #this is important if you want to use https !!! proxy_set_header X-Url-Scheme $scheme; include /etc/nginx/proxy.conf; } @@ -242,7 +250,7 @@ pushes and also on large pushes:: 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 +Also when using root path with nginx you might set the static files to false in production.ini file:: [app:main] @@ -299,7 +307,7 @@ Apache subdirectory part:: SetEnvIf X-Url-Scheme https HTTPS=1 -Besides the regular apache setup You'll need to add such part to .ini file:: +Besides the regular apache setup you will need to add such part to .ini file:: filter-with = proxy-prefix @@ -329,7 +337,7 @@ 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 + 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 @@ -339,16 +347,16 @@ Troubleshooting - long lasting push timeouts ? - - make sure You set a longer timeouts in Your proxy/fcgi settings, timeouts + - make sure you set a longer timeouts in your proxy/fcgi settings, timeouts are caused by https server and not RhodeCode - large pushes timeouts ? - - make sure You set a proper max_body_size for the http server + - make sure you set a proper max_body_size for the http server - Apache doesn't pass basicAuth on pull/push ? - - Make sure You added `WSGIPassAuthorization true` + - Make sure you added `WSGIPassAuthorization true` .. _virtualenv: http://pypi.python.org/pypi/virtualenv .. _python: http://www.python.org/