# Developer Installation Guide
# Supported Platforms
- BCO Runtime
- Ubuntu / Debian
- BCO UIs
- Ubuntu / Debian / Linux
- Mac OS
- Java JDK 11 (AZUL Zulu JDK recommended)
- Download: https://www.azul.com/downloads/zulu
- Ubuntu Install Example
- Add Key:
sudo apt-key adv --keyserver hkp://keyserver.ubuntu.com:80 --recv-keys 0xB1998361219BD9C9
- Add Repo:
sudo apt-add-repository 'deb http://repos.azulsystems.com/ubuntu stable main'
- Update Index:
sudo apt-get update
sudo apt-get install zulu-11
- Make Default:
echo 'export JAVA_HOME="/usr/lib/jvm/zulu-11-amd64/"' >> ~/.bashrc && . ~/.bashrc
- Add Key:
sudo apt-get install git
# Toolchain Setup
Define where to install the bco distribution via the
echo 'export BCO_DIST="$HOME/usr/bco"' >> ~/.bashrc
bin folder to your global
$PATH variable to support direct binary execution.
echo 'export PATH="$PATH:$BCO_DIST/bin"' >> ~/.bashrc
Reload your bash configuration
Make sure the
$BCO_DIST folder exists.
mkdir -p $BCO_DIST
Make sure you have right permissions to
sudo chown -R $USER $BCO_DIST chmod -R 750 $BCO_DIST
# BCO Installation
After preparing the toolchain and middleware we need to prepare our workspace.
Create a new development directory if it not already exist (e.g.
~/workspace/openbase) and change into these directory.
mkdir -p ~/workspace/openbase cd ~/workspace/openbase
# Openbase Developer Tool Installation
There exist different openbase tools which help to to simplify the installation and maintenance of bco. Therefore, before downloading bco we should install those tools via:
cd ~/workspace/openbase git clone -b master https://github.com/openbase/developer.tools.git cd developer.tools ./install.sh
# Main Repository Download
Download the bco main repository into your development workspace.
cd ~/workspace/openbase git clone -b master https://github.com/openbase/bco.git
We recommend to checkout and install the
dev branch in order to start the development of new components.
Be aware to setup the snapshot repository before building the
# Setup Snapshot Repository
This step is only required if you are using a non release branch (e.g. dev) or link against it.
BCO is using gradle as build tool. All dependencies are deployed at the central maven repositories and will be downloaded without any specific configuration for stable releases.
In case you want to build a bco nightly release or your project depends on any snapshots you have to add the following public repository configuration profile to your maven settings file (
<?xml version="1.0"?> <settings> <!-- ... --> <profiles> <profile> <id>openbase</id> <activation> <activeByDefault>true</activeByDefault> </activation> <properties> <downloadJavadocs>true</downloadJavadocs> <downloadSources>true</downloadSources> </properties> </profile> <profile> <id>sonatype</id> <activation> <activeByDefault>true</activeByDefault> </activation> <repositories> <repository> <id>sonatype-oss-public</id> <url>https://oss.sonatype.org/content/groups/public/</url> <releases> <enabled>true</enabled> <updatePolicy>daily</updatePolicy> </releases> <snapshots> <enabled>true</enabled> <updatePolicy>interval:60</updatePolicy> </snapshots> </repository> </repositories> </profile> </profiles> <!-- ... --> </settings>
# Download and Prepare BCO Submodules
BCO is based on the openbase Java Utility Library (JUL) and on the openbase Type Library. Both dependencies are linked as git sub-module in the
lib folder. The
./prepare.sh stored in the BCO repo root folder downloads the source-code of each dependency.
Therefore, please execute
cd ~/workspace/openbase/bco ./prepare.sh ./update.sh
If the workspace is prepared, we can use the
all script provided by the developer tools to build the dependencies:
cd ~/workspace/openbase/bco all ./install.sh
The initial installation can take a while, so grab a coffee and relax while the scripts do the work.
Now everything should be ready to start the development of new bco components and apps. We recommend to use IntelliJ as IDE for BCO.
~/workspace/openbase/bco in the IDE or just execute
idea ~/workspace/openbase/bco in case IntelliJ is provided by your shell.
You can update bco including its dependencies by executing
./update.sh. Just make sure all local changes are committed and pushed before performing the update. After updating all components you can compile and install all changes via the
./install.sh script. Therefore, a full update can be performed as followed:
# Database Setup
A fresh and empty database is generated during the first start of BCO.
This database is placed at
~/.config/bco/var/registry/db and only contains a root location and some system user accounts as well as the default admin account.
Please do not modify any database entries by hand as long as you exactly know what you are doing since manual modifications can lead into an inconsistent database.
Once bco is started you can add further units by adding them via the
bco-registry-editor. User accounts can be created and passwords changed via
In general bco takes care of all class and template database entries. Those will be updated during each startup of bco as long as an internet connection is provided.
In case you want to backup your individual setup entries just create a local git repository in the database folder
git init, link it to any git remote repository of your choice
git remote add origin https://github.com/$YOUR_ACCOUNT/bco.registry.$YOUR_HOME_ID-db.git, and upload the db via
git push --set-upstream origin master.
# How to setup a Demo Database
Sometimes during development its useful to play around with an already complex environment setup. The following steps explain how to setup the bco demo database that already entails a bunch of devices and units.
mkdir -p ~/.config/bco/var/registry cd ~/.config/bco/var/registry git clone https://github.com/openbase/bco.registry.demo-db db
# How to Restore a Backup
To restore an already existing bco setup, just place the related
db directory within