Changeset - ff8651b2f14f
Parent rev.
Child rev.
[Not reviewed]
default
0 3 0
Mads Kiilerich (mads) - 6 years ago 2020-06-19 18:24:38
mads@kiilerich.com
Grafted from: d3f2108667ba
docs: augment setup description with more details of http server and database

Dive into more details than in overview.rst .

Databases should perhaps have more mentioning in overview.rst , but there is
nothing but details and thus not much to say in the overview ...
3 files changed with 49 insertions and 21 deletions:
development.ini
2
2
docs/setup.rst
43
15
kallithea/lib/paster_commands/template.ini.mako
4
4
0 comments (0 inline, 0 general)
development.ini
➞
Show inline comments
 
@@ -339,50 +339,50 @@ debug = true
 
## Propagate email settings to ErrorReporter of TurboGears2
 
## You do not normally need to change these lines
 
get trace_errors.smtp_server = smtp_server
 
get trace_errors.smtp_port = smtp_port
 
get trace_errors.from_address = error_email_from
 
get trace_errors.error_email = email_to
 
get trace_errors.smtp_username = smtp_username
 
get trace_errors.smtp_password = smtp_password
 
get trace_errors.smtp_use_tls = smtp_use_tls
 

			




	
	
	
		
 

			




	
	
	
		
 
##################################

			




	
	
	
		
 
##        LOGVIEW CONFIG        ##

			




	
	
	
		
 
##################################

			




	
	
	
		
 

			




	
	
	
		
 
logview.sqlalchemy = #faa

			




	
	
	
		
 
logview.pylons.templating = #bfb

			




	
	
	
		
 
logview.pylons.util = #eee

			




	
	
	
		
 

			




	
	
	
		
 
#########################

			




	
	
	
		
 
##      DB CONFIG      ##

			




	
	
	
		
 
#########################

			




	
	
	
		
 

			




	
	
	
		
 
sqlalchemy.url = sqlite:///%(here)s/kallithea.db?timeout=60

			




	
	
	
		
 
#sqlalchemy.url = postgresql://user:pass@localhost/kallithea

			




	
	
	
		
 
#sqlalchemy.url = mysql://user:pass@localhost/kallithea?charset=utf8

			




	
	
	
		
 
#sqlalchemy.url = postgresql://kallithea:password@localhost/kallithea

			




	
	
	
		
 
#sqlalchemy.url = mysql://kallithea:password@localhost/kallithea?charset=utf8

			




	
	
	
		
 
## Note: the mysql:// prefix should also be used for MariaDB

			




	
	
	
		
 

			




	
	
	
		
 
sqlalchemy.pool_recycle = 3600

			




	
	
	
		
 

			




	
	
	
		
 
################################

			




	
	
	
		
 
##   ALEMBIC CONFIGURATION    ##

			




	
	
	
		
 
################################

			




	
	
	
		
 

			




	
	
	
		
 
[alembic]

			




	
	
	
		
 
script_location = kallithea:alembic

			




	
	
	
		
 

			




	
	
	
		
 
################################

			




	
	
	
		
 
##   LOGGING CONFIGURATION    ##

			




	
	
	
		
 
################################

			




	
	
	
		
 

			




	
	
	
		
 
[loggers]

			




	
	
	
		
 
keys = root, routes, kallithea, sqlalchemy, tg, gearbox, beaker, templates, whoosh_indexer, werkzeug, backlash

			




	
	
	
		
 

			




	
	
	
		
 
[handlers]

			




	
	
	
		
 
keys = console, console_color, console_color_sql, null

			




	
	
	
		
 

			




	
	
	
		
 
[formatters]

			




	
	
	
		
 
keys = generic, color_formatter, color_formatter_sql

			




	
	
	
		
 

			




        

    


    
    

    

        

                

                    docs/setup.rst
                

                

                  
                      
                        

                      ➞

                      
                        
                  

                  
                      
                  
                      
                  
                      
                  
                      
                  
                  
                

                

                    Show inline comments
                    
                

        

        

            



	
	
	
		
 
.. _setup:

			




	
	
	
		
 

			




	
	
	
		
 
=====

			




	
	
	
		
 
Setup

			




	
	
	
		
 
=====

			




	
	
	
		
 

			




	
	
	
		
 

			




	
	
	
		
 
Setting up Kallithea

			




	
	
	
		
 
--------------------

			




	
	
	
		
 

			




	
	
	
		
 
Some further details to the steps mentioned in the overview.

			




	
	
	
		
 

			




	
	
	
		
 
Create low level configuration file

			




	
	
	
		
 
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

			




	
	
	
		
 

			




	
	
	
		
 
First, you will need to create a Kallithea configuration file. Run the

			




	
	
	
		
 
following command to do so::

			




	
	
	
		
 
First, you will need to create a Kallithea configuration file. The

			




	
	
	
		
 
configuration file is a ``.ini`` file that contains various low level settings

			




	
	
	
		
 
for Kallithea, e.g. configuration of how to use database, web server, email,

			




	
	
	
		
 
and logging.

			




	
	
	
		
 

			




	
	
	
		
 
    kallithea-cli config-create my.ini

			




	
	
	
		
 
Run the following command to create the file ``my.ini`` in the current

			




	
	
	
		
 
directory::

			




	
	
	
		
 

			




	
	
	
		
 
This will create the file ``my.ini`` in the current directory. This

			




	
	
	
		
 
configuration file contains the various settings for Kallithea, e.g.

			




	
	
	
		
 
proxy port, email settings, usage of static files, cache, Celery

			




	
	
	
		
 
settings, and logging. Extra settings can be specified like::

			




	
	
	
		
 
    kallithea-cli config-create my.ini http_server=waitress

			




	
	
	
		
 

			




	
	
	
		
 
To get a good starting point for your configuration, specify the http server

			




	
	
	
		
 
you intend to use. It can be ``waitress``, ``gearbox``, ``gevent``,

			




	
	
	
		
 
``gunicorn``, or ``uwsgi``. (Apache ``mod_wsgi`` will not use this

			




	
	
	
		
 
configuration file, and it is fine to keep the default http_server configuration

			




	
	
	
		
 
unused. ``mod_wsgi`` is configured using ``httpd.conf`` directives and a WSGI

			




	
	
	
		
 
wrapper script.)

			




	
	
	
		
 

			




	
	
	
		
 
Extra custom settings can be specified like::

			




	
	
	
		
 

			




	
	
	
		
 
    kallithea-cli config-create my.ini host=8.8.8.8 "[handler_console]" formatter=color_formatter

			




	
	
	
		
 

			




	
	
	
		
 
Populate the database

			




	
	
	
		
 
^^^^^^^^^^^^^^^^^^^^^

			




	
	
	
		
 

			




	
	
	
		
 
Next, you need to create the databases used by Kallithea. It is recommended to

			




	
	
	
		
 
use PostgreSQL or SQLite (default). If you choose a database other than the

			




	
	
	
		
 
default, ensure you properly adjust the database URL in your ``my.ini``

			




	
	
	
		
 
configuration file to use this other database. Kallithea currently supports

			




	
	
	
		
 
PostgreSQL, SQLite and MariaDB/MySQL databases. Create the database by running

			




	
	
	
		
 
the following command::

			




	
	
	
		
 
Next, you need to create the databases used by Kallithea. Kallithea currently

			




	
	
	
		
 
supports PostgreSQL, SQLite and MariaDB/MySQL databases. It is recommended to

			




	
	
	
		
 
start out using SQLite (the default) and move to PostgreSQL if it becomes a

			




	
	
	
		
 
bottleneck or to get a "proper" database. MariaDB/MySQL is also supported.

			




	
	
	
		
 

			




	
	
	
		
 
For PostgreSQL, run ``pip install psycopg2`` to get the database driver. Make

			




	
	
	
		
 
sure the PostgreSQL server is initialized and running. Make sure you have a

			




	
	
	
		
 
database user with password authentication with permissions to create databases

			




	
	
	
		
 
- for example by running::

			




	
	
	
		
 

			




	
	
	
		
 
    sudo -u postgres createuser 'kallithea' --pwprompt --createdb

			




	
	
	
		
 

			




	
	
	
		
 
For MariaDB/MySQL, run ``pip install mysqlclient`` to get the ``MySQLdb``

			




	
	
	
		
 
database driver. Make sure the database server is initialized and running. Make

			




	
	
	
		
 
sure you have a database user with password authentication with permissions to

			




	
	
	
		
 
create the database - for example by running::

			




	
	
	
		
 

			




	
	
	
		
 
    echo 'CREATE USER "kallithea"@"localhost" IDENTIFIED BY "password"' | sudo -u mysql mysql

			




	
	
	
		
 
    echo 'GRANT ALL PRIVILEGES ON `kallithea`.* TO "kallithea"@"localhost"' | sudo -u mysql mysql

			




	
	
	
		
 

			




	
	
	
		
 
Check and adjust ``sqlalchemy.url`` in your ``my.ini`` configuration file to use

			




	
	
	
		
 
this database.

			




	
	
	
		
 

			




	
	
	
		
 
Create the database, tables, and initial content by running the following

			




	
	
	
		
 
command::

			




	
	
	
		
 

			




	
	
	
		
 
    kallithea-cli db-create -c my.ini

			




	
	
	
		
 

			




	
	
	
		
 
This will first prompt you for a "root" path. This "root" path is the location

			




	
	
	
		
 
where Kallithea will store all of its repositories on the current machine. This

			




	
	
	
		
 
location must be writable for the running Kallithea application. Next,

			




	
	
	
		
 
``db-create`` will prompt you for a username and password for the initial admin

			




	
	
	
		
 
account it sets up for you.

			




	
	
	
		
 

			




	
	
	
		
 
The ``db-create`` values can also be given on the command line.

			




	
	
	
		
 
Example::

			




	
	
	
		
 

			




	
	
	
		
 
    kallithea-cli db-create -c my.ini --user=nn --password=secret --email=nn@example.com --repos=/srv/repos

			




	
	
	
		
 

			




	
	
	
		
 
The ``db-create`` command will create all 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 Kallithea will add all of the repositories at the chosen

			




	
	
	
		
 
location to its database.  (Note: make sure you specify the correct

			




	
	
	
		
 
path to the root).

			




	
	
	
		
 

			




	
	
	
		
 

			




	
	
	
		
 
Prepare front-end files

			




	
	
	
		
 
^^^^^^^^^^^^^^^^^^^^^^^

			




	
	
	
		
 

			




	
	
	
		
 
Finally, the front-end files must be prepared. This requires ``npm`` version 6

			




	
	
	
		
 
or later, which needs ``node.js`` (version 12 or later). Prepare the front-end

			




	
	
	
		
 
by running::

			




	
	
	
		
 

			




	
	
	
		
 
    kallithea-cli front-end-build

			




	
	
	
		
 

			




	
	
	
		
 
Running

			




	
	
	
		
 
^^^^^^^

			




	
	
	
		
 

			




	
	
	
		
 
You are now ready to use Kallithea. To run it simply execute::

			




	
	
	
		
 
You are now ready to use Kallithea. To run it using a gearbox web server,

			




	
	
	
		
 
simply execute::

			




	
	
	
		
 

			




	
	
	
		
 
    gearbox serve -c my.ini

			




	
	
	
		
 

			




	
	
	
		
 
- This command runs the Kallithea server. The web app should be available at

			




	
	
	
		
 
  http://127.0.0.1:5000. The IP address and port is configurable via the

			




	
	
	
		
 
  configuration file created in the previous step.

			




	
	
	
		
 
- Log in to Kallithea using the admin account created when running ``db-create``.

			




	
	
	
		
 
- 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, and permissions

			




	
	
	
		
 
  settings, as well as edit more advanced options on users and

			




	
	
	
		
 
  repositories.

			




	
	
	
		
 

			




	
	
	
		
 

			




	
	
	
		
 
Internationalization (i18n support)

			




	
	
	
		
 
-----------------------------------

			




	
	
	
		
 

			




	
	
	
		
 
The Kallithea web interface is automatically displayed in the user's preferred

			




	
	
	
		
 
language, as indicated by the browser. Thus, different users may see the

			




	
	
	
		
 
application in different languages. If the requested language is not available

			




	
	
	
		
 
(because the translation file for that language does not yet exist or is

			




	
	
	
		
 
incomplete), English is used.

			




	
	
	
		
 

			




	
	
	
		
 
If you want to disable automatic language detection and instead configure a

			




        

    


    
    

    

        

                

                    kallithea/lib/paster_commands/template.ini.mako
                

                

                  
                      
                        

                      ➞

                      
                        
                  

                  
                      
                  
                      
                  
                      
                  
                      
                  
                  
                

                

                    Show inline comments
                    
                

        

        

            



	
	
		
 
@@ -437,56 +437,56 @@ sentry.project =

			




	
	
	
		
 
sentry.site =

			




	
	
	
		
 
sentry.include_paths =

			




	
	
	
		
 
sentry.exclude_paths =

			




	
	
	
		
 

			




	
	
	
		
 
%endif

			




	
	
	
		
 

			




	
	
	
		
 
<%text>##</%text>################################

			




	
	
	
		
 
<%text>##</%text>        LOGVIEW CONFIG        ##

			




	
	
	
		
 
<%text>##</%text>################################

			




	
	
	
		
 

			




	
	
	
		
 
logview.sqlalchemy = #faa

			




	
	
	
		
 
logview.pylons.templating = #bfb

			




	
	
	
		
 
logview.pylons.util = #eee

			




	
	
	
		
 

			




	
	
	
		
 
<%text>##</%text>#######################

			




	
	
	
		
 
<%text>##</%text>      DB CONFIG      ##

			




	
	
	
		
 
<%text>##</%text>#######################

			




	
	
	
		
 

			




	
	
	
		
 
%if database_engine == 'sqlite':

			




	
	
	
		
 
sqlalchemy.url = sqlite:///%(here)s/kallithea.db?timeout=60

			




	
	
	
		
 
%else:

			




	
	
	
		
 
#sqlalchemy.url = sqlite:///%(here)s/kallithea.db?timeout=60

			




	
	
	
		
 
%endif

			




	
	
	
		
 
%if database_engine == 'postgres':

			




	
	
	
		
 
sqlalchemy.url = postgresql://user:pass@localhost/kallithea

			




	
	
	
		
 
sqlalchemy.url = postgresql://kallithea:password@localhost/kallithea

			




	
	
	
		
 
%else:

			




	
	
	
		
 
#sqlalchemy.url = postgresql://user:pass@localhost/kallithea

			




	
	
	
		
 
#sqlalchemy.url = postgresql://kallithea:password@localhost/kallithea

			




	
	
	
		
 
%endif

			




	
	
	
		
 
%if database_engine == 'mysql':

			




	
	
	
		
 
sqlalchemy.url = mysql://user:pass@localhost/kallithea?charset=utf8

			




	
	
	
		
 
sqlalchemy.url = mysql://kallithea:password@localhost/kallithea?charset=utf8

			




	
	
	
		
 
%else:

			




	
	
	
		
 
#sqlalchemy.url = mysql://user:pass@localhost/kallithea?charset=utf8

			




	
	
	
		
 
#sqlalchemy.url = mysql://kallithea:password@localhost/kallithea?charset=utf8

			




	
	
	
		
 
%endif

			




	
	
	
		
 
<%text>##</%text> Note: the mysql:// prefix should also be used for MariaDB

			




	
	
	
		
 

			




	
	
	
		
 
sqlalchemy.pool_recycle = 3600

			




	
	
	
		
 

			




	
	
	
		
 
<%text>##</%text>##############################

			




	
	
	
		
 
<%text>##</%text>   ALEMBIC CONFIGURATION    ##

			




	
	
	
		
 
<%text>##</%text>##############################

			




	
	
	
		
 

			




	
	
	
		
 
[alembic]

			




	
	
	
		
 
script_location = kallithea:alembic

			




	
	
	
		
 

			




	
	
	
		
 
<%text>##</%text>##############################

			




	
	
	
		
 
<%text>##</%text>   LOGGING CONFIGURATION    ##

			




	
	
	
		
 
<%text>##</%text>##############################

			




	
	
	
		
 

			




	
	
	
		
 
[loggers]

			




	
	
	
		
 
keys = root, routes, kallithea, sqlalchemy, tg, gearbox, beaker, templates, whoosh_indexer, werkzeug, backlash

			




	
	
	
		
 

			




	
	
	
		
 
[handlers]

			




	
	
	
		
 
keys = console, console_color, console_color_sql, null

			




	
	
	
		
 

			




	
	
	
		
 
[formatters]

			




	
	
	
		
 
keys = generic, color_formatter, color_formatter_sql

			




        

    



    


    



    



      

      





    
    0 comments (0 inline, 0 general)
    





    


  

  







  


    




    








    
        Server instance: clio-13690
    
    
        This site is powered by
            Kallithea 0.7.0,
        which is
        © 2010–2025 by various authors & licensed under GPLv3.
            – Support