To start with you must download a binary distribution of BlobCity DB

https://github.com/blobcity/db/tree/master/release

Upon download, extract the contents from the tar.gz file. Your file would be named as blobcity-db-x.x.x.tar.gz where x.x.x is the distribution version.

tar -xvf blobcity-db-x.x.x.tar.gz

Post extraction, you should see a folder called blobcity-db-x.x.x. For the rest of the documentation let us assume that the absolute path to this folder on your computer is $DB

Starting the database

Go inside $DB/bin and run the command sh ./blobcity.sh. You will find a blobcity.sh file located within the bin folder of distribution. This command will only work on a Linux or Mac distribution. Windows users must use the Docker distribution.

sh ./blobcity.sh
......
[INFO ] com.blobcity.lib.database.launcher.main.Startup: BlobCity DB successfully started in 6 seconds

The command will produce some startup logs, with the last logged line reading BlobCity DB successfully started in xx seconds. If you get this line in the logs then the database is now successfully running.

🚧

$JAVA_HOME must be set

For the above command to work the JAVA_HOME environment variable must be set to a Java 8 or later installation. If the environment variable is not set, the same can be set by editing the blobcity.sh file

Setting JAVA_HOME environment variable

If the $JAVA_HOME environment variable is not set on the server, the same can be set by editing the blobcity.sh file. Use a vim editor or any editor of your choice to edit the file.

#!/usr/bin/env bash

#Copyright (C) 2018  BlobCity, Inc

#This program is free software: you can redistribute it and/or modify
#it under the terms of the GNU Affero General Public License as published
#by the Free Software Foundation, either version 3 of the License, or
#(at your option) any later version.

#This program is distributed in the hope that it will be useful,
#but WITHOUT ANY WARRANTY; without even the implied warranty of
#MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
#GNU Affero General Public License for more details.

#You should have received a copy of the GNU Affero General Public License
#along with this program.  If not, see <http://www.gnu.org/licenses/>.



# Set the BlobCity specific environment and add all required libraries to the classpath

# The Java implementation to use. This is required.
#export JAVA_HOME=

Uncomment the line #export JAVA_HOME= and add the path to your java install. For most linux distributions Java is expected to be inside /usr/lib/jvm/ but may vary based on your specific server setup.

A sample blobcity.sh file with JAVA_HOME set is shown below.

#!/usr/bin/env bash

#Copyright (C) 2018  BlobCity, Inc

#This program is free software: you can redistribute it and/or modify
#it under the terms of the GNU Affero General Public License as published
#by the Free Software Foundation, either version 3 of the License, or
#(at your option) any later version.

#This program is distributed in the hope that it will be useful,
#but WITHOUT ANY WARRANTY; without even the implied warranty of
#MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
#GNU Affero General Public License for more details.

#You should have received a copy of the GNU Affero General Public License
#along with this program.  If not, see <http://www.gnu.org/licenses/>.



# Set the BlobCity specific environment and add all required libraries to the classpath

# The Java implementation to use. This is required.
export JAVA_HOME="/usr/lib/jvm/java-8-openjdk-amd64"

Once JAVA_HOME is set, you can try starting the database with sh ./blobcity.sh

Starting as a daemon

sh ./blobcity.sh &

Simply adding an & after the sh ./blobcity.sh command will start the database in daemon mode. It will release your current prompt to do other tasks and the database can be kept running in the background even when you close the prompt.

Configuring disk storage

By default the database will create a folder called data inside the blobcity-db-x.x.x folder. All data loaded into the database along with internal storage used by the database is stored within this folder. However it may not be desirable to have the database to store data in this location.

A custom location can be specified be setting the BLOBCITY_DATA variable inside the blobcity.sh file.

# Use to specify data storage location. Default location is BLOBCITY_HOME/data/
#export BLOBCITY_DATA=

# Use to specify data storage location. Default location is BLOBCITY_HOME/data/
export BLOBCITY_DATA=/mnt/xfs1

For good performance it is highly recommended that data be stored on an XFS formatted volume. Choose the lowest block size possible, typically 512 bytes or 1024 bytes per block. The data storage volume is recommended to the different than the operating system volume on which Java runs. It is important that any Swap space required by Java not be used from the volume that stores data. A data storage volume is required even if you plan to only do in-memory storage.

Getting root user password

On first boot the database creates a default user account named root with a randomly generated password. The randomly generated password is located in a file called root-pass.txt inside the data folder. By default the file will be located at blobcity-db-x.x.x/data/root-pass.txt. If the storage folder is custom configured, then the file will be placed inside BLOBCITY_DATA/root-pass.txt