kallithea Changeset - d59cb6068e55

Changeset - d59cb6068e55

Parent rev.

Child rev.

[Not reviewed]

stable

0 1 0

Mads Kiilerich - 6 years ago 2020-05-15 18:50:59
mads@kiilerich.com

docs: clarify the installation steps and how things fit together

Hint that create-db user information is for creating the initial local user
and that the database connection (which also might use some kind of user) is
something else.

1 file changed with 36 insertions and 0 deletions:

docs/overview.rst

0 comments (0 inline, 0 general)

docs/overview.rst

➞

Show inline comments

 .. _overview:
 =====================
 Installation overview
 =====================
 Some overview and some details that can help understanding the options when
 installing Kallithea.
 . **Prepare environment and external dependencies.**
     Kallithea needs:
     * A filesystem where the Mercurial and Git repositories can be stored.
     * A database where meta data can be stored.
     * A Python environment where the Kallithea application and its dependencies
       can be installed.
     * A web server that can host the Kallithea web application using the WSGI
       API.
 . **Install Kallithea software.**
     This makes the ``kallithea-cli`` command line tool available.
 . **Create low level configuration file.**
     Use ``kallithea-cli config-create`` to create a ``.ini`` file with database
     connection info, mail server information, some web server configuration,
     etc.
 . **Populate the database.**
     Use ``kallithea-cli db-create`` with the ``.ini`` file to create the
     database schema and insert the most basic information: the location of the
     repository store and an initial local admin user.
 . **Configure the web server.**
     The web server must invoke the WSGI entrypoint for the Kallithea software
     using the ``.ini`` file (and thus the database). This makes the web
     application available so the local admin user can log in and tweak the
     configuration further.
 . **Configure users.**
     The initial admin user can create additional local users, or configure how
     users can be created and authenticated from other user directories.
 See the subsequent sections, the separate OS-specific instructions, and
 :ref:`setup` for details on these steps.
 Python environment
 ------------------
 **Kallithea** is written entirely in Python_ and requires Python version
 .6 or higher.
 Given a Python installation, there are different ways of providing the
 environment for running Python applications. Each of them pretty much
 corresponds to a ``site-packages`` directory somewhere where packages can be
 installed.
 Kallithea itself can be run from source or be installed, but even when running
 from source, there are some dependencies that must be installed in the Python
 environment used for running Kallithea.
 - Packages *could* be installed in Python's ``site-packages`` directory ... but
   that would require running pip_ as root and it would be hard to uninstall or
   upgrade and is probably not a good idea unless using a package manager.
 - Packages could also be installed in ``~/.local`` ... but that is probably
   only a good idea if using a dedicated user per application or instance.
 - Finally, it can be installed in a virtualenv. That is a very lightweight

0 comments (0 inline, 0 general)