Cabrita Tutorial¶
maxdepth: | 2 :caption: Modules: |
---|
In-depth Customization¶
To customize cabrita you can create a yaml file, let’s called cabrita.yml
to create or config _boxes_. You can select which docker containers will
show in each box and what info these boxes will show for each service
inside them.
To understand his basic structure, copy and paste this yaml and save the cabrita.yml
in the
same directory where your docker-compose.yml is located:
version: 2
title: My Docker Project
background_color: grey # options: black, blue, cyan, grey, yellow, white
compose_files:
- ./docker-compose.yml
boxes:
main_box:
main: true
name: My Services
This file will create a dashboard called My Docker Project, which will
read all services from the docker-compose.yml
file and add all of them to the
box called My Services.
This is the main box (main: true
), which means all docker services
which are not included in any other box, will be added here.
To use this file, use the --path
option for cabrita command line. You
can also define the CABRITA_PATH
environment variable for this path.
Using the our docker-compose in /examples
folder:
# You can call directly the app passing the yaml path
$ cd path/to/examples
$ TEST_PROJECT_PATH=$(pwd) docker-compose up -d
$ cabrita --path cabrita.yml
# Or you can use the CABRITA_PATH environment variable
$ export CABRITA_PATH=/path/to/yml
$ cabrita
The new dashboard will show:
Customize Ports¶
You can define, for each box, if the docker ports will be show in
dashboard. Let’s add two new options: port_view
and port_detail
on
cabrita.yml
:
version: 2
title: My Docker Project
background_color: grey # options: black, blue, cyan, grey, yellow, white
compose_files:
- ./docker-compose.yml
boxes:
main_box:
main: true
name: My Services
port_view: status # options: column, name, status
port_detail: internal # options: internal, external or both
The new dashboard will show:
Customize Git info¶
For more git information, let’s add two new options: show_revision
and
watch_branch
:
version: 2
title: My Docker Project
background_color: grey # options: black, blue, cyan, grey, yellow, white
compose_files:
- ./docker-compose.yml
boxes:
main_box:
main: true
name: My Services
port_view: status # options: column, name, status
port_detail: internal # options: internal, external or both
show_revision: true # will show commit hash and git tag if available
The “Branch” column are displayed in each box, by default (you can
disable it with the show_git: false
option). This column shows the
actual branch name for each service in box. If the branch is dirty (i.e.
has non-committed modifications), text color will be yellow.
The show_revision
option show, for each service in box, the commit
hash and git tag, if available.
The watch branch¶
Frequently, we need to know if the local code we are running inside the containers are not up-to-date with
the last modifications in the cloud. To resolve this, in the yaml file we can use the watch_branch
option:
version: 2
title: My Docker Project
background_color: grey # options: black, blue, cyan, grey, yellow, white
compose_files:
- ./docker-compose.yml
boxes:
main_box:
main: true
name: My Services
port_view: status # options: column, name, status
port_detail: internal # options: internal, external or both
show_revision: true # will show commit hash and git tag if available
watch_branch: origin/staging # check how ahead or behind you are regard this branch
The watch_branch
will add on “Branch” column how many commits ahead or
behind the current branch are in comparison of the watched branch.
The new dashboard will show:
The NEED BUILD status¶
Other thing we frequently need to know if the docker image we are running is up-to-date with the last code modifications.
If you’re using `docker volumes`_ docker will automatically run the latest code inside containers. But how about modifications
in Dockerfile
, requirements.txt
, package.json
and such files?
To resolve this, lets use two new options, called watch_for_build_using_files
and watch_for_build_using_git
:
version: 2
title: My Docker Project
background_color: grey # options: black, blue, cyan, grey, yellow, white
compose_files:
- ./docker-compose.yml
boxes:
main_box:
main: true
name: My Services
port_view: status # options: column, name, status
port_detail: internal # options: internal, external or both
show_revision: true # will show commit hash and git tag if available
watch_branch: origin/staging # check how ahead or behind you are regard this branch
watch_for_build_using_files: # check if Dockerfile last modification date is greater than docker image build date
- Dockerfile
watch_for_build_using_git: # check if last commit date in flask project is greater than docker image build date
- flask
The first option, watch_for_build_using_files
, means if any file inside list is located in the code folder, and if his
last modification date is more recent than his docker image, that image needs to be rebuild.
The second option, watch_for_build_using_git
, means if the date for the last commit is more recent than his docker image,
that image needs to be reduild.
Use the first, when you want to track for new builds using a bunch of files. Use the last, if any modification in project needs to start another build.
Adding new boxes¶
Let’s add the docker-compose.override.yml
and create a new box, only
for django applications:
version: 2
title: My Docker Project
background_color: grey # options: black, blue, cyan, grey, yellow, white
compose_files:
- ./docker-compose.yml
boxes:
main_box:
main: true
name: My Services
port_view: status # options: column, name, status
port_detail: internal # options: internal, external or both
show_revision: true # will show commit hash and git tag if available
watch_branch: origin/staging # check how ahead or behind you are regard this branch
watch_for_build_using_files: # check if Dockerfile last modification date is greater than docker image build date
- Dockerfile
watch_for_build_using_git: # check if last commit date in flask project is greater than docker image build date
- flask
django:
name: Django Apps
show_git: false
includes:
- django
This file contains a new box, called django. The includes option is used to create a list of services which will include on this box. This option is mutually exclusive with main option, because every service not included in include for all boxes will be display in the main box.
The new dashboard will show:
The “Django Apps” box will show 3 services. But what if we understand these
docker containers are just one big application in docker? Because they all
got the same name - “django” - we can categorize all services in the
same line, using the categories
option:
version: 2
title: My Docker Project
background_color: grey # options: black, blue, cyan, grey, yellow, white
compose_files:
- ./docker-compose.yml
boxes:
main_box:
main: true
name: My Services
port_view: status # options: column, name, status
port_detail: internal # options: internal, external or both
show_revision: true # will show commit hash and git tag if available
watch_branch: origin/staging # check how ahead or behind you are regard this branch
watch_for_build_using_files: # check if Dockerfile last modification date is greater than docker image build date
- Dockerfile
watch_for_build_using_git: # check if last commit date in flask project is greater than docker image build date
- flask
django:
name: Django Apps
show_git: false
includes:
- django
categories:
- worker
- redis
The new dashboard will show:
Adding watchers¶
Watchers are customized file and ping checkers for your project. Let’s add a new watcher, to check internet connection:
version: 2
title: My Docker Project
background_color: grey # options: black, blue, cyan, grey, yellow, white
compose_files:
- ./docker-compose.yml
boxes:
main_box:
main: true
name: My Services
port_view: status # options: column, name, status
port_detail: internal # options: internal, external or both
show_revision: true # will show commit hash and git tag if available
watch_branch: origin/staging # check how ahead or behind you are regard this branch
watch_for_build_using_files: # check if Dockerfile last modification date is greater than docker image build date
- Dockerfile
watch_for_build_using_git: # check if last commit date in flask project is greater than docker image build date
- flask
django:
name: Django Apps
show_git: false
includes:
- django
categories:
- worker
- redis
watchers:
ping:
google:
name: Check internet connectivity
address: https://www.google.com
message_on_success: UP
message_on_error: DOWN
The new dashboard will show: