Quickstart

Initial instructions to get started fast

Ultra quick recap

  1. prepare docker
  2. git clone https://www.github.com/cavaliba/cavaliba.git
  3. cp env.template .env
  4. vi .env to customize URL, DB and admin passwords
  5. docker compose up
  6. open browser to root URL , sign-in with configured admin account

Prerequisite : setup docker

You need a docker available environment. You can skip this part if your docker environment is already setup.

You don’t have to provide other middleware such as a web server, database server, etc. They are provided as docker containers with cavaliba.

For example, on a Linux Debian/Ubuntu fresh install such as a Virtual Machine or a Desktop you may have to perform the following actions:

$ sudo apt-get update
$ sudo apt-get install ca-certificates curl
$ sudo install -m 0755 -d /etc/apt/keyrings
$ sudo curl -fsSL https://download.docker.com/linux/debian/gpg -o /etc/apt/keyrings/docker.asc
$ sudo chmod a+r /etc/apt/keyrings/docker.asc
$ echo   "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/debian \
       $(. /etc/os-release && echo "$VERSION_CODENAME") stable" |   sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

$ sudo apt-get update
$ sudo apt-get install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

$ sudo groupadd docker
$ sudo usermod -aG docker $USER
$ newgrp docker

Then, perform a quick docker confirmation test, by running a minimal hello world public docker image:

$ docker version
$ docker run hello-world

If you see dcoker versions, and a Docker Hello world message, everything is fine. The Hello-World image was downloded and started successfully on your host.

Get Cavaliba from Github

In your working directory, enter the following command to download cavaliba from its github public repository:

$ cd myworkdir/
$ git clone --depth=1  https://www.github.com/cavaliba/cavaliba.git

You should see a new cavaliba/ directory with startup files, source code, and empty data folders.

To check downloaded content:

$ cd cavaliba

$ tree -L 1
├── LICENSE
├── README.md
├── files/                       <= files in/out with Cavaliba (import, mail, ...)
├── django/                      <= source code
├── docker-compose.yml.template  <= docker starter
├── env.template                 <= cavaliba configuration template
└── nginx.conf.template          <= logo/ and custom web templates

$ tree files
files
├── dev
├── export
├── import
├── logo
│   ├── logo_cavaliba.png
│   └── logo.png
├── mail
├── sms
└── templates
    └── app_sirene
        ├── _footer.html.OFF
        ├── _navbar.html.OFF
        ├── _pub_critical.html.OFF
        ├── _pub_info.html.OFF
        ├── _pub_major.html.OFF
        ├── _pub_minor.html.OFF
        ├── _pub_ok.html.OFF
        └── _pub_other.html.OFF

alternative to git

If you don’t want or have git tools you can proceed like this:

$ cd myworkdir/

$ curl -L -o cavaliba.zip https://github.com/cavaliba/cavaliba/archive/refs/heads/main.zip
$ unzip cavaliba.zip
$ cd cavaliba-main

# or
$ wget https://github.com/cavaliba/cavaliba/archive/refs/heads/main.zip
$ unzip main.zip

Prepare files from templates

$ cp nginx.conf.template nginx.conf
$ cp docker-compose.yml.template docker-compose.yml
$ cp env.template .env

Don’t forget the dot at the beginning of the .env filename.

Customize .env

This is the only file you need to customize to get started quickly.

The .envfile contains important parameters such as passwords and security items needed to start the application.

Edit the relevant part in this newly created .env file like this:

$ vi .env


# HERE, important security configuration : set allowed hostnames (FQDN, URL and port) 
DJANGO_CSRF_TRUSTED_ORIGINS="http://localhost:8000 http://myhost.mydomain.com:8000 http://192.168.0.1"

CAVALIBA_TENANT=cavaliba                        <= HERE, change if you run multiple cavaliba instance on your host
CAVALIBA_PORT=8000                              <= HERE, set an available "http like" port on your host ; 80, 8000, 8080
CAVALIBA_DOCKER_IMAGE=cavaliba/cavaliba:3.10    

CAVALIBA_DB_ENGINE=django.db.backends.mysql
CAVALIBA_DB_HOST=cavaliba_db                    <= don't change, this is the container name
CAVALIBA_DB_PORT=3306
CAVALIBA_DB_DATABASE=cavaliba
CAVALIBA_DB_USER=cavaliba                       
CAVALIBA_DB_PASSWORD=changeme_please            <= HERE, set a password for the internal cavaliba Database
CAVALIBA_DB_ROOT_PASSWORD=changeme_please_also  <= HERE, set a different password for the DB root account

CAVALIBA_ADMIN_PASSWORD=change_again            <= HERE, set a cavaliba app 'admin' built-in account inital password
CAVALIBA_ADMIN_EMAIL=admin@mydomain.com         <= Later, after cavaliba email advanced configuration

# sensitive fields encryption in DB
CAVALIBA_CIPHER_KEY="Change me. Please..."               <= HERE, set an encryption key for sensistive DB content. Keep it safe.

# cookie protection
DJANGO_SECRET_KEY=changeme_with_a_long_string   <= HERE, set a long random string for cookie protection

Start the application

Once the .env file is ready you may start cavaliba as follow:

$ docker compose up

You may later add a -d option to run docker in the background.

You may observe the different startup steps:

  • download of various docker images : nginx, mariadb, redis, and cavaliba (from Docker Hub)
  • mariadb database initial creation and startup
  • redis cache server startup
  • cavaliba async tasks container startup (celery)
  • cavaliba app container startup (init app, translations, admin account update, DB migrations, etc.)
  • web server startup (nginx)

Inspect the result like this (truncated) :

$ docker ps
IMAGE                  (...) STATUS                    PORTS                      NAMES
nginx:1.25.2                Up 10 seconds             0.0.0.0:8000->80/tcp       cavaliba_nginx
cavaliba/cavaliba:3.10      Up 10 seconds             8001/tcp                   cavaliba_app
cavaliba/cavaliba:3.10      Up 10 seconds                                        cavaliba_celery
redis:7.0.2-alpine3.16      Up 13 seconds (healthy)   6379/tcp                   cavaliba_redis
mariadb:10.10               Up 13 seconds (healthy)   3306/tcp                   cavaliba_db

You’ll notice a new db folder in your cavaliba/ main folder. It contains the (persistent) database content.

Connect and sign-in with admin account

Open your browser to your host / port combination :

firefox http://myhost:8000/home/private/

You’ll presented with the sign-in screen. Use the adminbuilt-in account, with the password you provided in the .env file.

If anything went wrong

Check running containers:

docker ps -a

Check logs for error messages:

 docker logs -f cavaliba_nginx
 docker logs -f cavaliba_app
 docker logs -f cavaliba_celery
 docker logs -f cavaliba_db
 docker logs -f cavaliba_redis

CSRF error message in the app ?

 verify the .env file and the DJANGO CSRF_ALLOWED_HOSTS value

Error in sign-in Web form

 double-check your admin password in the .env file

What to do next ?

You may :

  • have a quick tour of the application including importing demo data

  • go to additional setup : configuration, authentication, TLS/SSL, permissions, backups, emails, sms, etc.