This guide describes the installation and usage of the demo or rather test version of Tensei-Data.

1. Installation of the demo version

The demo version is generally deployed as a vagrant box [1] with the following requirements:

Table 1. System requierements for the demo version

CPU

4 cores or more

RAM

3 gb memory or more

HDD

sufficient space on hard disk (at least 12 gb)

VirtualBox

The virtualisation software VirtualBox [2] needs to be installed.

VMWare

As an alternative to VirtualBox, we offer a VMWare version. This box can be executed with Vagrant, too.

Vagrant

Vagrant [1] needs to be installed.

SSH

Alternatively Git [3]

Besides VirtualBox, we offer a VMWare version of the box. This box is basically identical with the VirtualBox version. The necessary adaptations are described in the following section.

1.1. Windows

The following steps describe the installation of the required components to execute the Tensei-Data system.

1.1.1. Installation of VirtualBox

VirtualBox is a virtualization software that is available for various systems.

  1. Download the Windows Installer from https://www.virtualbox.org/

  2. Execute the Installer and follow the instructions

1.1.2. Installation of Vagrant

Vagrant is used to create the system that executes the Tensei-Data components.

  1. Download the Windows Installer from https://www.vagrantup.com/

  2. Execute the Installer and follow the instructions

The system must be rebooted after installing Vagrant.

1.1.3. Installation of the Tensei-Data Demobox

  1. Create an empty folder.

  2. Open a command prompt in the created folder.

  3. Enter the command vagrant init wegtam/tensei-demo at command prompt.

To start the demo version a command prompt has to be opened in the created directory. At the prompt the following command starts the demo version:

vagrant up
windows eingabeaufforderung vagrant up
  • If you are using the VMWare version, you have to add the specific provider

vagrant up --provider vmware_workstation
You need the VMWare plugin from https://www.vagrantup.com/vmware/
windows localhost 9000
The correct IP for the VMWare version can be determined as follows
Determine the correct IP fpr VMWare
* Log into the box from the command line with `vagrant ssh`
* Determine the IP of the ethernet connection with `ifconfig`
* Access the frontend with http://IP-ETHERNET:9000
vagrant halt
  • If you have problems during the start, you have to start the processes by hand: Known problems

  • The demo is installed and can be restarted with vagrant up

1.2. Linux

  1. Create an empty folder.

  2. Open a command prompt in the created folder.

  3. Enter the command vagrant init wegtam/tensei-demo at command prompt.

To start the demo version a command prompt has to be opened in the created directory. At the prompt the following command starts the demo version:

vagrant up
Alternatively booting the VMWare version
vagrant up --provider vmware_workstation
You need the VMWare plugin from https://www.vagrantup.com/vmware/
The first booting of the virtual machine may take longer because the vagrant box must be decompressed and installed.

After the VM has started the application, the frontend is available under the following address: http://localhost:9000

The VMWare version does not provide a correct port and IP forwarding. Therefore, the correct IP can be determined as follows
Determine the correct IP for VMWare
  • Log into the box from the command line via vagrant ssh

  • If a Authentication failure occurs the login is stil possible with the password vagrant

  • Determine the IP of the ethernet connection via ifconfig

  • The frontend is available at http://IP-ETHERNET:9000

If the following error message Server connection unavailable appears on the screen, the services must be started manually. Services do not start

The VM can be shutdown via vagrant halt or via vagrant suspend. To boot it again just use the vagrant up command.

The virtual machine will not shutdown automatically with the shutdown of the host system. The VM may be damaged if it is not shutdown properly.
In addition to the online documentation, an internal documentation is reachable at: http://localhost:9080

1.3. Install VMWare box as image

The file tensei-demo-vmware.box can be decompressed. The image can be included into the VMWare Workstation or VMWare Fusion system.

All additional steps to determine the IP for the access of the frontend can be found in Installation for Windows or Installation for Linux.

1.4. Create an administrator account

After the installation you must create the first user account. This account automatically gets administration permissions for the application. The form to create the administrator account will be shown during the first access.

1.5. License

To be able to actually use the system a license has to be provided. The license file can be uploaded after the login in by accessing the menu Administration ▸ License. If you press the button Update you can upload the license file.

2. Troubleshooting in the VM

Normally, the Tensei-Data services (server,frontend and agent) are automatically started after calling vagrant up. Access the frontend via http://localhost:9000. If there are problems with the services, you can solve them with the following commands. (Additional information in section Known problems)

You can log into the currently running vagrant environment with the following command.

SSH into the running environment
vagrant ssh

The log files of the server, the frontend and the agent are available at.

Log files
cd /srv/tensei/tensei-server/logs
cd /srv/tensei/tensei-frontend/logs
cd /srv/tensei/tensei-agent/logs

The server, frontend and agent services can be stopped and started with the following commands.

Start the services
sudo service tensei-server start
sudo service tensei-frontend start
sudo service tensei-agent start
Stop the services
sudo service tensei-server stop
sudo service tensei-frontend stop
sudo service tensei-agent stop

3. File input and output

Within the working directory of vagrant in which the Vagrantfile resides, a directory named data will be created. This directory is accessible from within the virtual machine at the path /srv/tensei/data meaning that files dropped there are accessible from inside and from outside the virtual machine.

For example, to use the file customers.csv from within that directory inside Tensei-Data, the connection information has to have the following uri:

Example uri for file access
file:///srv/tensei/data/customers.csv

The same principle applies to the writing of data. If Tensei-Data is advised to write to the file file:///srv/tensei/data/test.csv then the result of the migration will be saved to that file and will be accessible from outside the VM in the folder data.

If files don’t appear inside the virtual machine then usually it suffices to reboot the VM to fix that problem.

4. Accessing databases

The access to databases usually is done via network. The database server has to be configured appropriately.

Here are some examples for popular database connections using ip addresses:

Derby
jdbc:derby:///srv/tensei/data/derby-file
H2
jdbc:h2:///srv/tensei/data/h2-file
HyperSQL (HSQLDB)
jdbc:hsqldb:hsql://10.8.1.10/my-db
MariaDB
jdbc:mariadb://192.168.0.42/my-db
Microsoft SQL Server
jdbc:sqlserver://10.8.1.129:1433;databaseName=my-db;applicationName=myApplication
MySQL
jdbc:mysql://192.168.1.23/my-db
Oracle
jdbc:oracle:thin:@10.0.2.2:1521:my-db
PostgreSQL
jdbc:postgresql://10.8.0.42/my-db
SQLite
jdbc:sqlite:///srv/tensei/data/sqlite-datei
The concrete connection parameters will have to be extracted from the database system’s documentation if necessary.
Additional information for connecting network file are available in the User-Guide.
The address localhost or 127.0.0.1 respectively [::1] cannot be used from inside the virtual machine because it points to the VM itself.
The parameter applicationName must be set with a value for the Microsoft SQL Server. e.g.: applicationName=myApplication

4.1. Access a local database from the VM

The access to a local database requires the correct IP from out of the VM for the database connection. This IP can be determined as follows.

SSH into the running environment
vagrant ssh

The output of the shell contains the following information.

Shell output
...

Last login: Wed Jun 24 12:41:36 2015 from 10.0.2.2

The IP (10.0.2.2) of this line will be used for the database connection.

Example of a local database connection
jdbc:mysql://10.0.2.2/my-database

4.2. Acess a local database from VMWare

Basically, the same approach is necessary that is described in Access a local database from the VM.

Additionally, the local databases must be configured correctly for local access and contain users with respective rights.

5. Trigger

If you want to use triggers on network resources pay attention that only ports inside the virtual machine can be used which must be forwarded to the host machine.

The Vagrantfile contains a port forward to port 8192 for exactly this reason.

Furthermore, you have to define a generic ip address like 0.0.0.0 to ensure that the trigger listens on all available network interfaces.

Example trigger url
jetty:http://0.0.0.0:8192/PATH

The trigger can be activated via browser as follows.

Activate the trigger
http://localhost:8192/PFAD

6. Configuration

The demo system is configurable to adjust for certain needs.

6.1. Vagrant

Experienced users can configure several details directly within the Vagrantfile. The following sections shortly introduce the most important settings.

6.1.1. Port

If the default port of the application (9000) should be changed, the following section within the config file needs to be adjusted:

Adjust port number
# Forward network port for ui.
config.vm.network :forwarded_port, guest: 9000, host: PORTNUMBER

6.1.2. System resources

If sufficient hardware is available, the VM can be set to more generous resources.

Adjust system resources
# Configure multiple cpus and memory requirements.
config.vm.provider :virtualbox do |vb|
  vb.customize ["modifyvm", :id, "--ioapic", "on"]
  vb.memory = MEMORY-FOR-THE-VM
  vb.cpus = NUMBER-OF-PROCESSORS-FOR-THE-VM
end
The number of processors has to be at least four (4)! The memory is specified in mb (gb * 1024) meaning you have to specify 8192 for 8 gb for example.

6.1.3. Synchronised folders

It is possible to configure other directories besides /srv/tensei/data for data sharing. In principle the configuration is as follows:

Synchronise folders
config.vm.synced_folder "PATH_ON_HOST", "PATH_IN_VM", owner: "tensei-agent", create: true
The parameters owner and create are important and must not be omitted!

For details please consult the documentation of vagrant.

7. Known problems

7.1. Installation of SSH support

If no SSH support is available on the system, you can install Git as one alternative.

  1. Download the Windows Installer from https://git-scm.com/

  2. Execute the Installer and follow the instructions

SSH is neccessary to execute the vagrant ssh command

7.2. The system is not correctly loaded by vagrant

If the system does not run correctly after the first vagrant up, you should reload the system.

Reload the system
% vagrant reload

7.3. Services do not start

In rare circumstances some services may not be started correctly for example the tensei-server or the tensei-agent.

Sometimes it is enough to reload the VM. If not, the following steps can be executed.

To resolve this issue you should login to the virtual machine using the vagrant ssh command. From within the VM you can restart the services:

Connect to VM from Shell
% vagrant ssh
Restart server
% sudo service tensei-server restart
Restart agent
% sudo service tensei-agent restart
Restart frontend
% sudo service tensei-frontend restart

If it generates an error message during the restart of one of the services (because the service is not running), this service can be started with one of the following commands.

Start the server
% sudo service tensei-server start
Start the agent
% sudo service tensei-agent start
Start the frontend
% sudo service tensei-frontend start

7.4. Frontend doesn’t run and can not be restarted

If the VM was incorrectly stopped, the frontend service can be corrupted. The service can not be restarted.

If so, you have to delete the RUNNING_PID file within the frontend folder.

Connect to the VM in the shell
% vagrant ssh
Delete the RUNNING_PID file
% rm /srv/tensei/tensei-frontend/RUNNING_PID

Restart the frontend service.

Restart frontend
% sudo service tensei-frontend restart

8. Replace an existing Demo-Box

If you want to replace an existing Demo-Box, you must execute the following steps.

If you want to keep existing cookbooks, you must export them.
  1. Switch to the folder where the actual Demo-Box is installed

  2. You can see the status of the box with vagrant status

  3. Destroy the box with vagrant destroy

  4. List the added boxes with vagrant box list

  5. Delete the actual Demo-Box with vagrant box remove NAME-OF-THE-BOX

    1. If the box has the name tensei-demo, the box can be removed with the following line: vagrant box remove tensei-demo

  6. Install the new box like described in the installation.

9. Uninstall

For a properly uninstallation of the application the command vagrant destroy has to be executed. Afterwards the working directory may be deleted.

In C:\Users\<username>.vagrant.d\boxes\ (Windows) or /home/<username>/.vagrant.d/boxes/ (Linux), a copy of the VM is stored that can be removed manually.

1. Vagrant Homepage: https://www.vagrantup.com/
2. VirtualBox Homepage: https://www.virtualbox.org/
3. Git Hompeage: https://git-scm.com/