Mercurial > kallithea
annotate docs/installation.rst @ 4912:295900ff473d
docs: don't use fixed-width fonts when not needed
| author | Andrew Shadura <andrew@shadura.me> |
|---|---|
| date | Thu, 12 Mar 2015 09:43:05 +0100 |
| parents | 03bbd33bc084 |
| children | 95fe05b1e5f8 |
| rev | line source |
|---|---|
|
568
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
1 .. _installation: |
|
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
2 |
|
4814
d95ea48af67b
docs: rename docs/installation_win.rst to docs/installation_win_old.rst, preparing for new docs
Mads Kiilerich <madski@unity3d.com>
parents:
4522
diff
changeset
|
3 ========================== |
|
d95ea48af67b
docs: rename docs/installation_win.rst to docs/installation_win_old.rst, preparing for new docs
Mads Kiilerich <madski@unity3d.com>
parents:
4522
diff
changeset
|
4 Installation on Unix/Linux |
|
d95ea48af67b
docs: rename docs/installation_win.rst to docs/installation_win_old.rst, preparing for new docs
Mads Kiilerich <madski@unity3d.com>
parents:
4522
diff
changeset
|
5 ========================== |
|
568
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
6 |
|
4912
295900ff473d
docs: don't use fixed-width fonts when not needed
Andrew Shadura <andrew@shadura.me>
parents:
4902
diff
changeset
|
7 **Kallithea** is written entirely in Python. Kallithea requires Python version |
| 4902 | 8 2.6 or higher. |
| 9 | |
| 10 .. Note:: Alternative very detailed installation instructions for Ubuntu Server | |
| 11 with celery, indexer and daemon scripts: https://gist.github.com/4546398 | |
|
568
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
12 |
|
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
13 |
| 4902 | 14 Installing Kallithea from Python Package Index (PyPI) |
| 15 ----------------------------------------------------- | |
|
1092
8af52e1224ff
merge docs in beta with those corrected by Jason Harris
Marcin Kuzminski <marcin@python-works.com>
parents:
1062
diff
changeset
|
16 |
|
4912
295900ff473d
docs: don't use fixed-width fonts when not needed
Andrew Shadura <andrew@shadura.me>
parents:
4902
diff
changeset
|
17 **Kallithea** can be installed from PyPI with:: |
|
568
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
18 |
|
4192
e73a69cb98dc
Rename some strings examples and commands in documentation
Bradley M. Kuhn <bkuhn@sfconservancy.org>
parents:
3700
diff
changeset
|
19 pip install kallithea |
|
568
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
20 |
|
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
21 |
| 4902 | 22 Installation in virtualenv |
| 23 -------------------------- | |
|
2358
69df04ee1e2b
added detailed step-by-step installation instruction for windows
Marcin Kuzminski <marcin@python-works.com>
parents:
2351
diff
changeset
|
24 |
| 4902 | 25 It is highly recommended to use a separate virtualenv_ for installing Kallithea. |
| 26 This way, all libraries required by Kallithea will be installed separately from your | |
| 27 main Python installation and things will be less problematic when upgrading the | |
| 28 system or Kallithea. | |
| 29 An additional benefit of virtualenv_ is that it doesn't require root privileges. | |
|
568
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
30 |
| 4902 | 31 - Assuming you have installed virtualenv_, create a new virtual environment |
|
3224
8b8edfc25856
whitespace cleanup
Marcin Kuzminski <marcin@python-works.com>
parents:
3169
diff
changeset
|
32 using virtualenv command:: |
|
572
a60cd29ba7e2
more docs update
Marcin Kuzminski <marcin@python-works.com>
parents:
568
diff
changeset
|
33 |
| 4902 | 34 virtualenv /srv/kallithea/venv |
|
572
a60cd29ba7e2
more docs update
Marcin Kuzminski <marcin@python-works.com>
parents:
568
diff
changeset
|
35 |
| 4902 | 36 .. note:: Older versions of virtualenv required ``--no-site-packages`` to work |
| 37 correctly. It should no longer be necessary. | |
|
1092
8af52e1224ff
merge docs in beta with those corrected by Jason Harris
Marcin Kuzminski <marcin@python-works.com>
parents:
1062
diff
changeset
|
38 |
| 4902 | 39 - this will install new virtualenv_ into `/srv/kallithea/venv`. |
| 40 - Activate the virtualenv_ in your current shell session by running:: | |
|
1092
8af52e1224ff
merge docs in beta with those corrected by Jason Harris
Marcin Kuzminski <marcin@python-works.com>
parents:
1062
diff
changeset
|
41 |
| 4902 | 42 source /srv/kallithea/venv/bin/activate |
|
1092
8af52e1224ff
merge docs in beta with those corrected by Jason Harris
Marcin Kuzminski <marcin@python-works.com>
parents:
1062
diff
changeset
|
43 |
|
8af52e1224ff
merge docs in beta with those corrected by Jason Harris
Marcin Kuzminski <marcin@python-works.com>
parents:
1062
diff
changeset
|
44 .. note:: If you're using UNIX, *do not* use ``sudo`` to run the |
|
8af52e1224ff
merge docs in beta with those corrected by Jason Harris
Marcin Kuzminski <marcin@python-works.com>
parents:
1062
diff
changeset
|
45 ``virtualenv`` script. It's perfectly acceptable (and desirable) |
|
8af52e1224ff
merge docs in beta with those corrected by Jason Harris
Marcin Kuzminski <marcin@python-works.com>
parents:
1062
diff
changeset
|
46 to create a virtualenv as a normal user. |
|
3224
8b8edfc25856
whitespace cleanup
Marcin Kuzminski <marcin@python-works.com>
parents:
3169
diff
changeset
|
47 |
|
4192
e73a69cb98dc
Rename some strings examples and commands in documentation
Bradley M. Kuhn <bkuhn@sfconservancy.org>
parents:
3700
diff
changeset
|
48 - Make a folder for Kallithea data files, and configuration somewhere on the |
|
1309
61a6a7bf2cbd
small docs updates
Marcin Kuzminski <marcin@python-works.com>
parents:
1123
diff
changeset
|
49 filesystem. For example:: |
|
572
a60cd29ba7e2
more docs update
Marcin Kuzminski <marcin@python-works.com>
parents:
568
diff
changeset
|
50 |
| 4902 | 51 mkdir /srv/kallithea |
|
3224
8b8edfc25856
whitespace cleanup
Marcin Kuzminski <marcin@python-works.com>
parents:
3169
diff
changeset
|
52 |
|
4192
e73a69cb98dc
Rename some strings examples and commands in documentation
Bradley M. Kuhn <bkuhn@sfconservancy.org>
parents:
3700
diff
changeset
|
53 - Go into the created directory run this command to install kallithea:: |
|
572
a60cd29ba7e2
more docs update
Marcin Kuzminski <marcin@python-works.com>
parents:
568
diff
changeset
|
54 |
|
4192
e73a69cb98dc
Rename some strings examples and commands in documentation
Bradley M. Kuhn <bkuhn@sfconservancy.org>
parents:
3700
diff
changeset
|
55 pip install kallithea |
|
3224
8b8edfc25856
whitespace cleanup
Marcin Kuzminski <marcin@python-works.com>
parents:
3169
diff
changeset
|
56 |
| 4902 | 57 Alternatively, download a .tar.gz from http://pypi.python.org/pypi/Kallithea, |
| 58 extract it and run:: | |
| 59 | |
| 60 python setup.py install | |
| 61 | |
|
4192
e73a69cb98dc
Rename some strings examples and commands in documentation
Bradley M. Kuhn <bkuhn@sfconservancy.org>
parents:
3700
diff
changeset
|
62 - This will install Kallithea together with pylons and all other required |
| 4902 | 63 python libraries into the activated virtualenv. |
| 64 | |
|
572
a60cd29ba7e2
more docs update
Marcin Kuzminski <marcin@python-works.com>
parents:
568
diff
changeset
|
65 |
|
855
8bbe9ab76371
cleaned installation docs a little
Marcin Kuzminski <marcin@python-works.com>
parents:
845
diff
changeset
|
66 Requirements for Celery (optional) |
|
8bbe9ab76371
cleaned installation docs a little
Marcin Kuzminski <marcin@python-works.com>
parents:
845
diff
changeset
|
67 ---------------------------------- |
|
8bbe9ab76371
cleaned installation docs a little
Marcin Kuzminski <marcin@python-works.com>
parents:
845
diff
changeset
|
68 |
|
1309
61a6a7bf2cbd
small docs updates
Marcin Kuzminski <marcin@python-works.com>
parents:
1123
diff
changeset
|
69 In order to gain maximum performance |
|
4192
e73a69cb98dc
Rename some strings examples and commands in documentation
Bradley M. Kuhn <bkuhn@sfconservancy.org>
parents:
3700
diff
changeset
|
70 there are some third-party you must install. When Kallithea is used |
|
1309
61a6a7bf2cbd
small docs updates
Marcin Kuzminski <marcin@python-works.com>
parents:
1123
diff
changeset
|
71 together with celery you have to install some kind of message broker, |
|
61a6a7bf2cbd
small docs updates
Marcin Kuzminski <marcin@python-works.com>
parents:
1123
diff
changeset
|
72 recommended one is rabbitmq_ to make the async tasks work. |
|
61a6a7bf2cbd
small docs updates
Marcin Kuzminski <marcin@python-works.com>
parents:
1123
diff
changeset
|
73 |
|
4192
e73a69cb98dc
Rename some strings examples and commands in documentation
Bradley M. Kuhn <bkuhn@sfconservancy.org>
parents:
3700
diff
changeset
|
74 Of course Kallithea works in sync mode also and then you do not have to install |
|
3224
8b8edfc25856
whitespace cleanup
Marcin Kuzminski <marcin@python-works.com>
parents:
3169
diff
changeset
|
75 any third party applications. However, using Celery_ will give you a large |
|
8b8edfc25856
whitespace cleanup
Marcin Kuzminski <marcin@python-works.com>
parents:
3169
diff
changeset
|
76 speed improvement when using many big repositories. If you plan to use |
|
4192
e73a69cb98dc
Rename some strings examples and commands in documentation
Bradley M. Kuhn <bkuhn@sfconservancy.org>
parents:
3700
diff
changeset
|
77 Kallithea for say 7 to 10 repositories, Kallithea will perform perfectly well |
|
1309
61a6a7bf2cbd
small docs updates
Marcin Kuzminski <marcin@python-works.com>
parents:
1123
diff
changeset
|
78 without celery running. |
|
3224
8b8edfc25856
whitespace cleanup
Marcin Kuzminski <marcin@python-works.com>
parents:
3169
diff
changeset
|
79 |
|
4192
e73a69cb98dc
Rename some strings examples and commands in documentation
Bradley M. Kuhn <bkuhn@sfconservancy.org>
parents:
3700
diff
changeset
|
80 If you make the decision to run Kallithea with celery make sure you run |
|
3224
8b8edfc25856
whitespace cleanup
Marcin Kuzminski <marcin@python-works.com>
parents:
3169
diff
changeset
|
81 celeryd using paster and message broker together with the application. |
|
1309
61a6a7bf2cbd
small docs updates
Marcin Kuzminski <marcin@python-works.com>
parents:
1123
diff
changeset
|
82 |
|
855
8bbe9ab76371
cleaned installation docs a little
Marcin Kuzminski <marcin@python-works.com>
parents:
845
diff
changeset
|
83 .. note:: |
|
4192
e73a69cb98dc
Rename some strings examples and commands in documentation
Bradley M. Kuhn <bkuhn@sfconservancy.org>
parents:
3700
diff
changeset
|
84 Installing message broker and using celery is optional, Kallithea will |
|
1092
8af52e1224ff
merge docs in beta with those corrected by Jason Harris
Marcin Kuzminski <marcin@python-works.com>
parents:
1062
diff
changeset
|
85 work perfectly fine without them. |
|
855
8bbe9ab76371
cleaned installation docs a little
Marcin Kuzminski <marcin@python-works.com>
parents:
845
diff
changeset
|
86 |
|
8bbe9ab76371
cleaned installation docs a little
Marcin Kuzminski <marcin@python-works.com>
parents:
845
diff
changeset
|
87 |
|
3224
8b8edfc25856
whitespace cleanup
Marcin Kuzminski <marcin@python-works.com>
parents:
3169
diff
changeset
|
88 **Message Broker** |
|
855
8bbe9ab76371
cleaned installation docs a little
Marcin Kuzminski <marcin@python-works.com>
parents:
845
diff
changeset
|
89 |
|
8bbe9ab76371
cleaned installation docs a little
Marcin Kuzminski <marcin@python-works.com>
parents:
845
diff
changeset
|
90 - preferred is `RabbitMq <http://www.rabbitmq.com/>`_ |
|
1092
8af52e1224ff
merge docs in beta with those corrected by Jason Harris
Marcin Kuzminski <marcin@python-works.com>
parents:
1062
diff
changeset
|
91 - A possible alternative is `Redis <http://code.google.com/p/redis/>`_ |
|
855
8bbe9ab76371
cleaned installation docs a little
Marcin Kuzminski <marcin@python-works.com>
parents:
845
diff
changeset
|
92 |
|
3224
8b8edfc25856
whitespace cleanup
Marcin Kuzminski <marcin@python-works.com>
parents:
3169
diff
changeset
|
93 For installation instructions you can visit: |
|
1092
8af52e1224ff
merge docs in beta with those corrected by Jason Harris
Marcin Kuzminski <marcin@python-works.com>
parents:
1062
diff
changeset
|
94 http://ask.github.com/celery/getting-started/index.html. |
|
8af52e1224ff
merge docs in beta with those corrected by Jason Harris
Marcin Kuzminski <marcin@python-works.com>
parents:
1062
diff
changeset
|
95 This is a very nice tutorial on how to start using celery_ with rabbitmq_ |
|
855
8bbe9ab76371
cleaned installation docs a little
Marcin Kuzminski <marcin@python-works.com>
parents:
845
diff
changeset
|
96 |
|
572
a60cd29ba7e2
more docs update
Marcin Kuzminski <marcin@python-works.com>
parents:
568
diff
changeset
|
97 |
| 4902 | 98 Next |
| 99 ---- | |
| 100 | |
| 101 You can now proceed to :ref:`setup`. | |
| 102 | |
| 103 | |
| 104 Upgrading Kallithea from Python Package Index (PyPI) | |
| 105 ----------------------------------------------------- | |
| 106 | |
| 107 .. note:: | |
| 108 Firstly, it is recommended that you **always** perform a database and | |
| 109 configuration backup before doing an upgrade. | |
| 110 | |
| 111 (These directions will use '{version}' to note that this is the version of | |
| 112 Kallithea that these files were used with. If backing up your Kallithea | |
| 113 instance from version 0.1 to 0.2, the ``my.ini`` file could be | |
| 114 backed up to ``my.ini.0-1``.) | |
| 115 | |
| 116 | |
| 117 If using a sqlite database, stop the Kallithea process/daemon/service, and | |
| 118 then make a copy of the database file:: | |
| 119 | |
| 120 service kallithea stop | |
| 121 cp kallithea.db kallithea.db.{version} | |
| 122 | |
| 123 | |
| 124 Back up your configuration file:: | |
| 125 | |
| 126 cp my.ini my.ini.{version} | |
| 127 | |
| 128 | |
| 129 Ensure that you are using the Python Virtual Environment that you'd originally | |
| 130 installed Kallithea in:: | |
| 131 | |
| 132 pip freeze | |
| 133 | |
| 134 will list all packages installed in the current environment. If Kallithea | |
| 135 isn't listed, change virtual environments to your venv location:: | |
| 136 | |
| 137 source /srv/kallithea/venv/bin/activate | |
| 138 | |
| 139 | |
|
4912
295900ff473d
docs: don't use fixed-width fonts when not needed
Andrew Shadura <andrew@shadura.me>
parents:
4902
diff
changeset
|
140 Once you have verified the environment you can upgrade Kallithea with:: |
| 4902 | 141 |
| 142 pip install --upgrade kallithea | |
| 143 | |
| 144 | |
| 145 Then run the following command from the installation directory:: | |
|
855
8bbe9ab76371
cleaned installation docs a little
Marcin Kuzminski <marcin@python-works.com>
parents:
845
diff
changeset
|
146 |
| 4902 | 147 paster make-config Kallithea my.ini |
| 148 | |
| 149 This will display any changes made by the new version of Kallithea to your | |
| 150 current configuration. It will try to perform an automerge. It's recommended | |
| 151 that you re-check the content after the automerge. | |
| 152 | |
| 153 .. note:: | |
| 154 Please always make sure your .ini files are up to date. Often errors are | |
| 155 caused by missing params added in new versions. | |
| 156 | |
| 157 | |
| 158 It is also recommended that you rebuild the whoosh index after upgrading since | |
| 159 the new whoosh version could introduce some incompatible index changes. Please | |
| 160 read the changelog to see if there were any changes to whoosh. | |
| 161 | |
| 162 | |
| 163 The final step is to upgrade the database. To do this simply run:: | |
| 164 | |
| 165 paster upgrade-db my.ini | |
| 166 | |
| 167 This will upgrade the schema and update some of the defaults in the database, | |
| 168 and will always recheck the settings of the application, if there are no new | |
| 169 options that need to be set. | |
| 170 | |
| 171 | |
| 172 .. note:: | |
| 173 DB schema upgrade library has some limitations and can sometimes fail if you try to | |
| 174 upgrade from older major releases. In such case simply run upgrades sequentially, eg. | |
| 175 upgrading from 0.1.X to 0.3.X should be done like that: 0.1.X. > 0.2.X > 0.3.X | |
| 176 You can always specify what version of Kallithea you want to install for example in pip | |
| 177 `pip install Kallithea==0.2` | |
| 178 | |
| 179 You may find it helpful to clear out your log file so that new errors are | |
| 180 readily apparent:: | |
| 181 | |
| 182 echo > kallithea.log | |
| 183 | |
| 184 Once that is complete, you may now start your upgraded Kallithea Instance:: | |
| 185 | |
| 186 service kallithea start | |
| 187 | |
| 188 Or:: | |
| 189 | |
| 190 paster serve /srv/kallithea/my.ini | |
| 191 | |
| 192 .. note:: | |
| 193 If you're using Celery, make sure you restart all instances of it after | |
| 194 upgrade. | |
|
855
8bbe9ab76371
cleaned installation docs a little
Marcin Kuzminski <marcin@python-works.com>
parents:
845
diff
changeset
|
195 |
|
568
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
196 |
|
3224
8b8edfc25856
whitespace cleanup
Marcin Kuzminski <marcin@python-works.com>
parents:
3169
diff
changeset
|
197 .. _virtualenv: http://pypi.python.org/pypi/virtualenv |
|
572
a60cd29ba7e2
more docs update
Marcin Kuzminski <marcin@python-works.com>
parents:
568
diff
changeset
|
198 .. _python: http://www.python.org/ |
|
a60cd29ba7e2
more docs update
Marcin Kuzminski <marcin@python-works.com>
parents:
568
diff
changeset
|
199 .. _mercurial: http://mercurial.selenic.com/ |
|
a60cd29ba7e2
more docs update
Marcin Kuzminski <marcin@python-works.com>
parents:
568
diff
changeset
|
200 .. _celery: http://celeryproject.org/ |
|
2806
008d9c6f7c92
fleshing out the Upgrade doc, and modified the references to Cheeseshop in the Install doc
H Waldo G <gwaldo@gmail.com>
parents:
2650
diff
changeset
|
201 .. _rabbitmq: http://www.rabbitmq.com/ |