Installation
Before the configuration and general installation procedure, please consider this overview to help plan your installation.
The service layer is primarily built from this github code source, although there are some storage dependencies that will be briefly covered here.
Standalone mode vs Grid mode is basically a question of if you need to use this for personal or development use (standalone), or in a larger more dedicated setup (grid mode). That said, the system does run slightly different in the two modes, so developers are encouraged to use grid mode when testing changes.
- Asset: Storage of immutable assets (better explanation is very much welcome).
- Inventory: A directory service for the assets in the user's inventory. Does not contain the assets themselves, just the folders and references to the actual assets that are stored on the Asset server.
- Data storage: General server data, there exist a lot of different modules that use SQL as the default storage mechanism.
These default storage types are covered by a default mechanism: it's possible to change the data layer in Halcyon, it's just not done yet.
- Whip (Asset): Specialized peice of software for this purpose https://github.com/InWorldz/whip-server
- Cassandra (Inventory): Performant key/value noSQL storage. Optional since MySQL can do the job, but Cassandra is faster at it.
- MySQL: SQL storage (currently only MySQL is supported) works as the go-to place for all non-performance related storage.
In case of using grids, there are 5 services mainly in use:
- Halcyon: The simulator, this can (if set) rely on a UserServer and a GridServer called "Grid mode"
- UserServer: Abstraction of all user authentication to a single user service.
- GridServer: Coordinates the regions and is responsible for making sure each region can communicate.
- MessagingServer: Handles group messaging, IMs, and all other message traffic that's outside the local region.
- Aperture: asset http manager handles asset calls by the viewer. This only needs to be set up one time for each region server.
Consider installing all storage related services inside a Virtual machine, this will allow us some abstraction in service, and therefore allows us to only install "on-demand" services on the local development environment. Windows with VirtualBox hosting Debian is working well for some of our developers. Others run straight on the hardware under Ubuntu. Containers work too, but will be easier later after a few changes are put in place.
Using virtualization technology can make your life easier, but is not required.
Install: VirtualBox 5.0.22 for Windows hosts https://www.virtualbox.org/wiki/Downloads
Cassandra is a very powerful tool if your grid is going to grow to having multiple millions of inventory items. If you are just testing or developing, you can have the MySQL server handle the inventory instead.
Netinstall AMD64 found in https://www.debian.org/releases/jessie/debian-installer/
- Memory: 4 Gb
- Network: Host Adapter
Use the default disk settings (full disk) Install with no modules but “SSH tools” and “Utilities”
Cassandra default installation OS is Debian, use the following command to add the repo (in console or via ssh)
These commands are executed as root
Open sources list, add Cassandra 3.7, then save in
/etc/apt/sources.list
#Cassandra 3.7
deb http://www.apache.org/dist/cassandra/debian 37x main
deb-src http://www.apache.org/dist/cassandra/debian 37x main
#Java 8
deb http://http.debian.net/debian jessie-backports main
Add keys
gpg --keyserver pgp.mit.edu --recv-keys F758CE318D77295D
gpg --export --armor F758CE318D77295D | apt-key add -
gpg --keyserver pgp.mit.edu --recv-keys 2B5C1B00
gpg --export --armor 2B5C1B00 | apt-key add -
gpg --keyserver pgp.mit.edu --recv-keys 0353B12C
gpg --export --armor 0353B12C | apt-key add -
Update packages and install Java & Cassandra
aptitude update
aptitude install openjdk-8-jdk
aptitude install Cassandra
See more here https://wiki.apache.org/cassandra/DebianPackaging
aptitude install mysql-server
When all components have been installed, we want to ensure connectivity between the two machines reliably.
On the Debian server, run the following command
nano /etc/network/interfaces
Ensure that the configuration looks similar to this (based on desired IP)
#The primary network interface
allow-hotplug eth0
iface eth0 inet static
address 10.0.2.10
netmask 255.255.255.0
network 10.0.2.0
broadcast 10.0.2.255
gateway 10.0.2.1
Restart the network interface
/etc/init.d/networking restart
Inside the Virtual Machine, make sure the network card is connected to the host virtual adapter, so we can ping between the host and the virtual machine.
Edit the MySQL configuration /etc/mysql/my.cnf to use the following.
bind-address = 10.0.2.10
Restart the database
/etc/init.d/mysql restart
Create mysql user and setup proper permissions to access data
mysql -p
CREATE DATABASE inworldz;
CREATE USER 'inworldz'@'%' IDENTIFIED BY ‘OperationPassword’;
GRANT ALL PRIVILEGES ON inworldz TO 'inworldz'@'%';
Initialize the database on windows Given the default installation dir of halcyon was used on windows, adjust your root pass and run the following inside cmd.
C:\Dev\halcyon\bin\hc-database.exe --init --type core -h 10.0.2.10 -u inworldz -p OperationPassword
Test if the database is running: /etc/init.d/cassandra status
try local connect
cqlsh
Cassandra does not provide any monitoring by itself, use netstat -c to keep an eye on the incoming connections
Run the following commands ( you may want to adjust the download link accordingly https://github.com/InWorldz/whip-server/releases)
aptitude install libboost-all-dev -y
mkdir /etc/whip
mkdir /etc/whip/assets
wget https://github.com/InWorldz/whip-server/releases/download/v5.0/whip-v5.0.tar /etc/whip
tar -xvf /etc/whip/whip-v5.0.tar
useradd -M whip
chown whip:whip /etc/whip -R
Now add a init.d script that will help us start and stop whip automatically. create the file /etc/init.d/whip (using nano or vi) with the following
#! /bin/sh
cd /etc/whip
case "$1" in
start)
echo "Starting whip"
su whip -c "/etc/whip/whip > /dev/null 2>&1 &"
;;
stop)
echo "Stopping whip"
skill -u whip
;;
*)
echo "Usage: /etc/init.d/whip {start|stop}"
exit 1
;;
esac
exit 0
Afterwards adjust permission and register the service accordingly
chmod 755 /etc/init.d/whip
update-rc.d whip defaults
Move over the whip configuration (and adjust it to your needs)
mv /etc/whip/whip.sample.cfg /etc/whip/whip.cfg
nano /etc/whip/whip.cfg