Ultra quick recap
- prepare docker
- git clone https://www.github.com/cavaliba/cavaliba.git
- cp env.template .env
- vi .env to customize URL, DB and admin passwords
- docker compose up
- 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 .env
file 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 admin
built-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.