Quickstart

Quick deployment of a first instance

In order to get started fast, you have to perform the following tasks, described in the rest of this page.

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
$ cd cavaliba

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

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

To check downloaded content:

$ tree -L 1
├── LICENSE
├── README.md
├── conf                  <= conf examples for advanced deployment
├── django                <= source code
├── docker-compose.yml    <= docker configuration
├── env.template          <= configuration template
├── export                <= empty
├── import                <= empty
├── mail                  <= empty
├── nginx.conf            <= web server (nginx container) configuration
├── sms                   <= empty
└── web                   <= logo/ and custom web templates

If you are not interested by the source code (django folder), you may limit your github download to the following elements: docker-compose file, nginx.conf, and env.template. Other empty folder may be created manually (export, import, mail, sms, web, …).

Prepare a .env file from env.template

You must provide a .env file to docker. Create it next to the docker-compose.yml file by copying the provided env.template. This is a standard pattern with docker. This .envfile contains important parameters such as passwords and security items needed to start the application.

First, copy the provided template. Don’t forget the dot at the beginning of the .env file name :

$ cp env.template .env

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
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
SIRENE_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.

Access and login

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:

 docker logs -f cavaliba_nginx

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.