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
 
@@ -357,14 +357,14 @@ 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    ##

			




        

    


    
    

    

        

                

                    docs/setup.rst
                

                

                  
                      
                        

                      ➞

                      
                        
                  

                  
                      
                  
                      
                  
                      
                  
                      
                  
                  
                

                

                    Show inline comments
                    
                

        

        

            



	
	
		
 
@@ -10,33 +10,61 @@ 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,

			




	
	
		
 
@@ -53,26 +81,26 @@ admin account. When choosing a root path

			




	
	
	
		
 
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.

			




        

    


    
    

    

        

                

                    kallithea/lib/paster_commands/template.ini.mako
                

                

                  
                      
                        

                      ➞

                      
                        
                  

                  
                      
                  
                      
                  
                      
                  
                      
                  
                  
                

                

                    Show inline comments
                    
                

        

        

            



	
	
		
 
@@ -455,20 +455,20 @@ logview.pylons.util = #eee

			




	
	
	
		
 
%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>##############################

			




        

    



    


    



    



      

      





    
    0 comments (0 inline, 0 general)
    





    


  

  







  


    




    








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