Installation

Basic Setup

There are two main roads to installing Cata-Log:

Docker

Follow these steps to set up your instance of Cata-Log:

Get the docker-compose.yml file from the git repository.
Adapt it to your needs. For details on the environment variables, refer to the configuration page. Don’t forget to set CATA_LOG_PASSWORD and CATA_LOG_ALLOWED_HOSTS, otherwise you won’t be able to access the instance or log in.
Deploy the stack any way you wish. Common options are via the command-line
```
docker compose up -d
```
or with a container manager like portainer, dockge or many others.
Open <server_ip>:2424 to check whether the container started successfully.

Bare-Metal

Follow these steps to set up your instance of Cata-Log:

Install cata_log_hub from PyPI
```
pip install cata-log-hub
```
See the following section on external databases for details on package extras.
Start the server with
```
python3 -m cata_log_hub --password=<your_password> --allowed-hosts=<server_hostname>
```
Don’t forget the password and allowed_hosts, otherwise you won’t be able to access the instance or log in.
Open <server_hostname>:2424 to check whether the container started successfully.

Important

If you want to access Cata-Log from outside your private network, please reverse-proxy. The basic HTTP authentication that Cata-Log uses is highly insecure without https!

Further Configuration

You can refine the upper basic setup to match your use case.

External Database

Cata-Log uses an internal sqlite3 database by default. This works fine but has some deficits in terms of concurrency and thread-safety.

If you can, please follow the next steps to use an external full-fledged database server instead.

You can pass the URL of a database either by command-line or environment option to be used instead of the internal sqlite database.

Note

You can use a database that is also used by another application.

For example if you deploy Cata-Log in the same environment (machine or docker stack) as a shopping-list server, you can simply make Cata-Log use the same database container as the main service. The two services and their data will not interfere with each other.

Available options are:

MySQL

mysql+pymysql://<db_username>:<db_password>@<database_ip>:<database_port>/cata-log

Support for MySQL can be installed with the mysql extra

pip install cata_log_hub[mysql]

and is always included in the docker image.

PostgreSQL

postgresql+pg8000://<db_username>:<db_password>@<database_ip>:<database_port>/cata-log

Support for MySQL can be installed with the mysql extra

pip install cata_log_hub[postgres]

and is always included in the docker image.

Important

Make sure to use the complete protocol with the driver as given in these templates.

You can use the docker-compose files for both setups as reference.

Reverse-Proxy

If you intend to use Cata-Log outside of your local network, it is strongly advised that you reverse-proxy.

(Sub)domain

This is the standard setup that you probably use for most of your self-hosted applications.

With this setup, Cata-Log will, for example, be available under https://cata-log.domain.tld.

Use Nginx, Traeffic or any other webserver of your choice to proxy Cata-Log behind a domain or subdomain. To ensure correct redirects, set forward-allow-ips to the hostname of the proxy.

Custom location

Alternatively, you can attach Cata-Log to an existing proxy host under a custom location.

With this setup, Cata-Log will, for example, be available under https://sub.domain.tld/cata-log.

You have to set the root_path CLI option (or CATA_LOG_ROOT_PATH env variable) to the path of the custom location for this setup to work correctly. To ensure correct redirects, set forward-allow-ips to the hostname of the proxy.

For Nginx an exemplary config is

location /cata-log/ {
    proxy_pass http://<server_ip>:2424;

    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
}

In this example, root_path must be set to /cata-log.

For more details, see the fastapi docs on this subject.

Settings

Your instance can be configured in many individual settings.

Refer to the configuration page for all details.

Quickstart Guide

Configuration