# HG changeset patch
# User Mads Kiilerich <mads@kiilerich.com>
# Date 1598274136 -7200
# Node ID c354d1a7537f6c4358ceaddf0b179cb3a8f17e30
# Parent  bff02bfbe2d4aaa21bd171c4948e7d55940bd3f4
docs: give "File system location" overview

Also make some other adjustments for consistency.

diff -r bff02bfbe2d4 -r c354d1a7537f docs/installation.rst
--- a/docs/installation.rst	Mon Aug 24 14:00:58 2020 +0200
+++ b/docs/installation.rst	Mon Aug 24 15:02:16 2020 +0200
@@ -80,8 +80,10 @@
 problematic when upgrading the system or Kallithea.
 An additional benefit of virtualenv is that it doesn't require root privileges.
 
-- Assuming you have installed virtualenv, create a new virtual environment
-  for example, in `/srv/kallithea/venv`, using the venv command::
+- Don't install as root - install as a dedicated user like ``kallithea``.
+
+- Create a new virtual environment, for example in ``/srv/kallithea/venv``,
+  specifying the right Python binary::
 
     python3 -m venv /srv/kallithea/venv
 
@@ -92,16 +94,10 @@
     . /srv/kallithea/venv/bin/activate
     pip install --upgrade pip setuptools
 
-.. note:: You can't use UNIX ``sudo`` to source the ``virtualenv`` script; it
-   will "activate" a shell that terminates immediately. It is also perfectly
-   acceptable (and desirable) to create a virtualenv as a normal user.
+.. note:: You can't use UNIX ``sudo`` to source the ``activate`` script; it
+   will "activate" a shell that terminates immediately.
 
-- Make a folder for Kallithea data files, and configuration somewhere on the
-  filesystem. For example::
-
-    mkdir /srv/kallithea
-
-- Go into the created directory and run this command to install Kallithea::
+- Install Kallithea in the activated virtualenv::
 
     pip install --upgrade kallithea
 
diff -r bff02bfbe2d4 -r c354d1a7537f docs/overview.rst
--- a/docs/overview.rst	Mon Aug 24 14:00:58 2020 +0200
+++ b/docs/overview.rst	Mon Aug 24 15:02:16 2020 +0200
@@ -48,6 +48,40 @@
 :ref:`setup` for details on these steps.
 
 
+File system location
+--------------------
+
+Kallithea can be installed in many different ways. The main parts are:
+
+- A location for the Kallithea software and its dependencies. This includes
+  the Python code, template files, and front-end code. After installation, this
+  will be read-only (except when upgrading).
+
+- A location for the ``.ini`` configuration file that tells the Kallithea
+  instance which database to use (and thus also the repository location).
+  After installation, this will be read-only (except when upgrading).
+
+- A location for various data files and caches for the Kallithea instance. This
+  is by default in a ``data`` directory next to the ``.ini`` file. This will
+  have to be writable by the running Kallithea service.
+
+- A database. The ``.ini`` file specifies which database to use. The database
+  will be a separate service and live elsewhere in the filesystem if using
+  PostgreSQL or MariaDB/MySQL. If using SQLite, it will by default live next to
+  the ``.ini`` file, as ``kallithea.db``.
+
+- A location for the repositories that are hosted by this Kallithea instance.
+  This will have to be writable by the running Kallithea service. The path to
+  this location will be configured in the database.
+
+For simple setups, it is fine to just use something like a ``kallithea`` user
+with home in ``/home/kallithea`` and place everything there.
+
+For experiments, it might be convenient to run everything as yourself and work
+inside a clone of Kallithea, with the ``.ini`` and SQLite database in the root
+of the clone.
+
+
 Python environment
 ------------------
 
diff -r bff02bfbe2d4 -r c354d1a7537f docs/setup.rst
--- a/docs/setup.rst	Mon Aug 24 14:00:58 2020 +0200
+++ b/docs/setup.rst	Mon Aug 24 15:02:16 2020 +0200
@@ -5,8 +5,8 @@
 =====
 
 
-Setting up Kallithea
---------------------
+Setting up a Kallithea instance
+-------------------------------
 
 Some further details to the steps mentioned in the overview.
 
@@ -18,7 +18,8 @@
 for Kallithea, e.g. configuration of how to use database, web server, email,
 and logging.
 
-Run the following command to create the file ``my.ini`` in the current
+Change to the desired directory (such as ``/srv/kallithea``) as the right user
+and run the following command to create the file ``my.ini`` in the current
 directory::
 
     kallithea-cli config-create my.ini http_server=waitress