Codabix Docker
ATTENTION: As Docker hub does neither offer a flawless operation nor provide reliable and responsive technical support, we moved our images to GitHub packages. The images and documentation can now be found under https://github.com/Traeger-GmbH/codabix-docker/pkgs/container/codabix.
Please update your applications to use the new image repository:
ghcr.io/traeger-gmbh/codabix
The repository on Docker Hub is just maintained for compatibility reasons, but we do not guarantee that there will be all versions/tags available forever.
Running the latest version
For running the latest image use the following commands.
Interactive mode
docker run -it -p 8181:8181 ghcr.io/traeger-gmbh/codabix:latest
Detached mode
To run the container in detached mode (with docker run parameter -d
instead of -it
) you have to pass the additional parameter --run-as-service
to enable daemon mode:
docker run -d -p 8181:8181 ghcr.io/traeger-gmbh/codabix:latest --run-as-service
Persistence
Per default the directory /home/codabix/data
will be used as project directory where Codabix will store its data.
To persist this data independent of the Codabix container you can either use a docker volume or bind this directory to the filesystem of the host.
Using a volume
- Create a new volume that will hold the application data:
docker volume create codabix-data
- Mount the volume under the project directory path during the start of the Codabix container:
docker run -d -p 8181:8181 -v codabix-data:/home/codabix/data ghcr.io/traeger-gmbh/codabix:latest --run-as-service
Bind to the host's filesystem
Instead of passing the name of a docker volume simply pass the path of the hosts directory as first part of the -v
option.
The Codabix process inside the container is run by the user codabix
with user id 999 and group id 999. So you have to map the user (using the flag -u 999
) to match the respective permissions on your file system.
docker run -d -p 8181:8181 -u 999 -v /path/to/hosts/directory:/home/codabix/data ghcr.io/traeger-gmbh/codabix:latest --run-as-service
Using docker-compose
If you want to use docker-compose to run the application create a new file docker-compose.yml
on your filesystem and copy and paste the following content.
version: "2"
services:
codabix:
image: ghcr.io/traeger-gmbh/codabix:latest
ports:
- "8181:8181"
volumes:
- "codabix-data:/home/codabix/data"
environment:
CODABIX_ADMIN_PASSWORD: StrongAdminPassword
CODABIX_PROJECT_NAME: My Codabix project
command: --run-as-service
volumes:
codabix-data:
Running the docker-compose service
To start the service defined by the docker-compose.yml
navigate into the directory where the file is located and run the following command:
docker-compose up
For detached mode pass the flag -d
:
docker-compose up -d
Stopping the service
Persistent
Executing the following command will remove the container and its corresponding resources but persist the volume that contains the data created by Codabix.
docker-compose down
Cleaning up
If you also want to remove the volume pass the -v
option to the command:
docker-compose down -v
Restoring from a backup file
To restore the configuration from a Codabix backup file the file has to be accessible inside the container (e.g. by mounting its containing directory). An environment variable CODABIX_RESTORE_FILE
is used to pass its path to the startup script.
The following command assumes that the backup file is located on the host's filesystem under the path /home/SomeUser/codabix/restore-file.cbx
.
docker run -d -p 8181:8181 -v /home/SomeUser/codabix/restore-file.cbx:/home/codabix/restore-file.cbx --env CODABIX_RESTORE_FILE=/home/codabix/restore-file.cbx ghcr.io/traeger-gmbh/codabix:latest --run-as-service
Enable access to peripherals
The following section describes the setup that is necessary to access hardware peripherals of the host system (e.g. i2C, USB, serial ports,...).
- Mount the
/dev
directory as volume by passing the command line option-v /dev:/dev
- Usually you need root privileges to access the hardware peripherals. As the default user that runs Codabix inside the docker container does not have these kind of privileges it is necessary to override this by
-u root
- In addition to that a container is not allowed to access any devices of the. So you have to explicitly give permission to that by passing
--privileged
docker run -d -p 8181:8181 -u root -v /dev:/dev -v /path/to/hosts/directory:/home/codabix/data ghcr.io/traeger-gmbh/codabix:latest --run-as-service
Please note:
As this container now is executed as root
user the files created on the host's filesystem will be owned by the root
user and you need root
or sudo
privileges to remove or change them.
Example when using docker-compose:
version: "2"
services:
codabix:
image: ghcr.io/traeger-gmbh/codabix:latest
ports:
- "8181:8181"
volumes:
- "codabix-data:/home/codabix/data"
- "/dev:/dev"
environment:
CODABIX_ADMIN_PASSWORD: StrongAdminPassword
CODABIX_PROJECT_NAME: My Codabix project
command: --run-as-service
user: root
privileged: true
volumes:
codabix-data:
Codabix settings
Default settings
- Default project directory:
/home/codabix/data
- Default admin password:
admin
- Default project name:
data
Overriding the default settings
You can override the default settings by using environment variables passed with --env
to the container on start.
- Project directory:
CODABIX_PROJECT_DIR
- Admin password:
CODABIX_ADMIN_PASSWORD
- Project name:
CODABIX_PROJECT_NAME
For overriding e.g. the admin password with the value MySuperComplexPassword
the container is run like follows:
docker run -d -p 8181:8181 --env CODABIX_ADMIN_PASSWORD=MySuperComplexPassword ghcr.io/traeger-gmbh/codabix:latest
NOTE: When running the Codabix image with persisted data (already existing application data from a previous run) overriding the admin password or the project name will have no effect.
Overriding more settings parameters
It is possible to override the default project settings by passing JSON data via the environment variable CODABIX_PROJECT_SETTINGS
.
docker run -d -p 8181:8181 --env CODABIX_PROJECT_SETTINGS="{'ProjectName': 'My Codabix Project'}" ghcr.io/traeger-gmbh/codabix:latest
This way you can e.g. use Codabix in a docker-compose stack with an MySQL back end database:
version: "2"
services:
codabix:
image: ghcr.io/traeger-gmbh/codabix:latest
ports:
- "8181:8181"
volumes:
- "codabix-data:/home/codabix/data"
depends_on:
- "db"
environment:
CODABIX_ADMIN_PASSWORD: StrongAdminPassword
CODABIX_PROJECT_NAME: My CoDaBix project
CODABIX_PROJECT_SETTINGS: >-
{ 'DatabaseMode': 'MySQL',
'SqlConnection':
{
'Hostname': 'db',
'Database': 'codabix-backend',
'Username': 'codabix',
'Password': 'codabix'
}
}
command: --run-as-service
db:
image: mysql:latest
volumes:
- "db-data:/var/lib/mysql"
environment:
MYSQL_ROOT_PASSWORD: example
MYSQL_DATABASE: codabix-backend
MYSQL_USER: codabix
MYSQL_PASSWORD: codabix
volumes:
codabix-data:
db-data:
Setting the license code
The license code used by Codabix inside the container is set via the environment variable CODABIX_LICENSE_CODE
.
Attention: This environment variable has been introduced in Codabix v1.0 so it will only work for version upwards.
Example when using docker run (<your-license-code>
representates your license code here):
docker run -d -p 8181:8181 -v codabix-data:/home/codabix/data -e CODABIX_LICENSE_CODE=<you-license-code> ghcr.io/traeger-gmbh/codabix:latest --run-as-service
Example when using docker-compose (<your-license-code>
representates your license code here):
version: "2"
services:
codabix:
image: ghcr.io/traeger-gmbh/codabix:latest
ports:
- "8181:8181"
volumes:
- "codabix-data:/home/codabix/data"
environment:
CODABIX_ADMIN_PASSWORD: StrongAdminPassword
CODABIX_PROJECT_NAME: My CoDaBix project
CODABIX_LICENSE_CODE: <you-license-code>
command: --run-as-service
volumes:
codabix-data:
Building the image
During the build process the installer of Codabix will be downloaded from https://codabix.com and installed in the image.
Setting the Codabix version
To choose the Codabix version used in the image two environment variables in the Dockerfile have to be set accordingly:
- VERSION
- This variable holds the version that shall be used for the image.
- RELEASE_DATE
- This variable corresponds to the release date of the version set in the VERSION variable.
- Example:
- For using Codabix v1.3.0 the variables have to be set as follows:
- ENV VERSION 1.3.0
- ENV RELEASE_DATE 2021-12-16
- For using Codabix v1.3.0 the variables have to be set as follows: