Skip to content

Developer VM

Jump to bottom Edit New page
Matt Magoffin edited this page Mar 9, 2021 · 25 revisions

SolarNetwork Developer Virtual Machine Guide

This guide describes how to set up a SolarNetwork development virtual machine (VM) using VirtualBox and Vagrant. This is a convenient way to get started with SolarNetwork development, as all the required software will be available in the VM. The VM features:

  1. Ubuntu host with minimal X window manager
  2. Postgres server with plv8 for SolarNet development
  3. pgAdmin III Postgres GUI
  4. Eclipse IDE
  5. Firefox web browser
  6. Cloned SolarNetwork git repositories
  7. Basic developer configuration

Requirements

The VM requires VirtualBox and is initially set up using Vagrant. Install both of these before continuing. The VM will be allocated 2GB of RAM by default, but you may want to configure more if your system has enough RAM. The VM will also be allocated a 20 GB disk image (although only a few GB will be used at the start), so you must have that much disk space available.

Additionally, the Vagrant disksize plugin is required. Once you have Vagrant installed, simply run

vagrant plugin install vagrant-disksize

to install the plugin.

Virtual Machine setup

Download the solarnetwork-dev repository, or clone it via https://github.com/SolarNetwork/solarnetwork-dev.git. Once downloaded or cloned, perform the following:

cd solarnetwork-dev/vagrant/solarnet-dev
vagrant up

Vagrant will download the VM image and then start configuring the SolarNetwork environment. This can take some time, as the image itself must be downloaded as well several hundred MB of software packages. You should see output similar to this:

Bringing machine 'solarnet' up with 'virtualbox' provider...
==> solarnet: Importing base box 'ubuntu/zesty64'...
==> solarnet: Matching MAC address for NAT networking...
==> solarnet: Checking if box 'ubuntu/zesty64' is up to date...
==> solarnet: Setting the name of the VM: SolarNet Dev
...

SolarNetwork development environment setup complete. Please reboot the
virtual machine like:

vagrant halt
vagrant up

Then log into the VM as solardev:solardev and Eclipse will launch
automatically. Right-click on the desktop to access a menu of other options.

NOTE: If X fails to start via tty1, login on tty2 and run `startx` to
start X and have Eclipse launch automatically.

Follow the instructions to restart the VM:

vagrant halt
vagrant up

More details on the Vagrant setup are available on the project's README.

Tweak swap

The VM image will have a 1GB swap file configured. You might need to enable more swap memory, if your VM is not configured at least 2GB or so. To change the swap file to 2GB, starting again from the solarnetwork-dev directory, execute:

vagrant ssh
sudo swapoff /swapfile
sudo fallocate -l 2G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile

VM tuning

If you have sufficient RAM and CPU cores on your host machine, you might make the development machine a bit snappier by allocating more RAM and/or CPU cores to the VM. Allocating more RAM is especially useful; 2GB makes Eclipse run much more smoothly, and 3GB even more so. You can tweak any of the VM settings you like, you just need to shut down the VM first. An easy way to do this is to run vagrant halt, and once the VM is shut down open VirtualBox directly and modify the VM's settings. By default VirtualBox stores your machine files in ~/VirtualBox VMs.

Note that future use of vagrant up might reset the memory configuration of the VM back to the default. You can avoid that by simply opening VirtualBox directly and starting the VM there.

Log In

Switch over to the VM in VirtualBox, and log in as solardev with the password solardev. You should end up with a screen like this:

Click on the Workbench big-arrow icon to dismiss the welcome screen.

Note if you get an error about X refusing to start, try this approach instead:

  1. Switch to the tty2 virtual console by pressing Alt+F2.
  2. Log in as solardev with the password solardev.
  3. At the shell prompt, type startx to launch the display environment.

Prepare screen resolution

The default screen size might be pretty small to work with when you eventually log in. Minimize Eclipse, then you can open up a shell by right-clicking on the desktop and choose Shells > bash. Then run xrandr -q to get a list of available screen resolutions:

Screen 0: minimum 64 x 64, current 800 x 600, maximum 32766 x 32766
VGA-0 connected 800x600+0+0 0mm x 0mm
   800x600       60.00*+  60.00*
   2560x1600     60.00
   2560x1440     60.00
   2048x1536     60.00
   1920x1600     60.00
   1920x1080     60.00
   1600x1200     60.00
   1680x1050     60.00
   1400x1050     60.00
   1280x1024     60.00
   1024x768      60.00
   640x480       60.00

You can tell X to switch to one of those resolutions by executing

xrandr --size 1400x1050

(using whatever resolution you like). You can that change permanent by editing .fluxbox/startup and adding that same line to the start of that file, right after the #!/bin/sh line. That might lead to unusually large fonts in some places, however, so an alternative is to use vagrant ssh from your host environment to log in as an administrator, and then create a 10-monitor.conf configuration file:

sudo mkdir /etc/X11/xorg.conf.d
sudo nano /etc/X11/xorg.conf.d/10-monitor.conf

with content like this:

Section "Monitor"
    Identifier             "Monitor0"
EndSection

Section "Device"
    Identifier             "Device0"
EndSection

Section "Screen"
    Identifier             "Screen0"
    Device                 "Device0"
    Monitor                "Monitor0"
    SubSection             "Display"
        Modes              "1400x1050" # Use one of the sizes returned by xrandr
    EndSubSection
EndSection

Just replace the Modes line with the size you want from the xrandr output.

Eclipse Java setup

You need to make sure Eclipse is using the system-provided Java 8 JDK. Newer versions of Eclipse come with a newer Java runtime that can cause compatibility issues with some SolarNet plugins. Go to Window > Preferences > Java > Installed JREs and check that the default JRE is /usr/lib/jvm/java-8-openjdk-amd64. It might not, and instead look something like this:

Eclipse JRE setup using builtin JRE

To use the system JDK, click Add... and choose Standard VM in the next dialog:

Eclipse JRE add Standard VM

In the next dialog, click the Directory... button, or manually fill in, this path: /usr/lib/jvm/java-8-openjdk-amd64. Once selected, you can rename the JRE to OpenJDK 8:

Eclipse JRE OpenJDK 8

Finally, make the OpenJDK 8 JRE the default by checking the box next to it:

Eclipse JRE OpenJDK 8 as default JRE

Eclipse setup

When Eclipse first launches, it won't have any projects configured. A Team Project Set will have been created for you that contains all the SolarNetwork projects. Import this now by selecting File > Import... > Team > Team Project Set.

Click Next > and in the dialog that follows, enter a File path of /home/solardev/workspace/SolarNetworkTeamProjectSet.psf (or use the Browse... button to select this file), and then click Finished. This will import all the projects into Eclipse.

Once the import completes, you should have all the SolarNetwork projects available in your Eclipse workspace. Eclipse will compile all projects, which can take a couple of minutes.

⚠️ Note you may see some projects reporting compile errors when importing the projects the first time. If that is the case, often selecting Project > Clean... > Clean all projects can sort things out.

Run SolarNetwork platform for the first time

You need to launch the SolarNetwork platform once and it will generate the necessary X.509 certificates to enable your development SolarNode to communicate with your development SolarNet service.

Go to Run > Run Configurations... > OSGi Framework > SolarNetwork and click Run.

After a few minutes, the SolarNetwork platform should finish starting up, and you'll see many log messages printed to the Eclipse console, including some errors. Some of the errors will be as a result of the missing keystores, which the net.solarnetwork.central.user.pki.dev bundle will create these when it starts up if they don't already exist.

Once the SolarNetwork platform has completed starting up, stop it by either clicking on the red square "stop" icon that appears with the Eclipse console, or type shutdown (and return) in the Eclipse console. The next time the platform starts, the keystore related errors will not occur.

Create a development SolarNet account

Now you should set up a SolarNet account so you can set up a development SolarNode. Launch the SolarNetwork framework again (it should show up under Run > Run History > SolarNetwork now) and wait for the platform to start up. After everything settles down, open a browser window (click the little earth icon in Eclipse) and visit http://localhost:8080/solaruser/. You should see a page like this:

Click on the Login link, then click goto the User Registration page to register as a new user. Fill in the form and submit it.

When you submit the registration, SolarNet will send a confirmation email to the address provided with a confirmation URL in the message body. The development environment is set up to simply log outbound email messages, so look in the Eclipse console and you should see the confirmation URL there. Is will take the form of

http://localhost:8080/solaruser/register/confirm.do?...

Copy that entire URL, and paste it into the browser to visit it. That will complete the registration process, and you should then log in. That will land you on the My Nodes page:

Set up development SolarNode

Now you are ready to set up your development SolarNode. Start by clicking on the Invite New SolarNode button on the My Nodes page you landed on after logging in. Fill in and submit the form that appears, which will generate an invitation code like this:

Copy the entire invitation code, and then visit http://localhost:8080/. You will be greeted with a form that you can paste the invitation code into. Paste in the code and click the Verify button. You will be guided through the association process. Note the host will be shown as solarnetworkdev.net, which the VM has configured to map to 127.0.0.1 (e.g. localhost). Be sure to enter a certificate password when asked, so SolarNet can generate the node's certificate for you.

When the association is complete, you should see a screen like this (your node ID might differ):

Eclipse code formatting

If you plan on contributing code to the SolarNetwork project, you should also import the SolarNetwork Eclipse code templates and formatter configuration. The templates are located in the solarnetwork-build/solarnetwork-osgi-target/defs/solarnetwork-codetemplates.xml file. To import them, open the Eclipse preferences, go to Java > Code Style > Code Templates and click the Import... button, and select the solarnetwork-codetemplates.xml file. To import the formatter configuration, open the Eclipse preferences, go to Java > Code Style > Formatter and click the Import... button, and select the solarnetwork-codeformat.xml file.

You can also let Eclipse apply this formatting when files are saved, and then you don't have to worry about remembering to apply the formatting. Go to Java > Editor > Save Actions and check the Perform the selected actions on save checkbox. Then check the Format source code and Additional actions checkboxes (the Organize imports checkbox should already be checked, but check that if not, too).

Setup complete!

Congratulations, your SolarNetwork development environment is set up, and you have created your own development SolarNet server and SolarNode to work with. Your node probably started collecting mock data and uploading it to your local SolarNet service. You can visit file:///home/solardev/git/solarnetwork-central/net.solarnetwork.central.query.web/example/web-service/sample.html in the VM (either using the included Firefox or the Eclipse internal browser) to explore the data posted by your node. Make sure the host points to http://localhost:8080 and enter a service URL like /solarquery/api/v1/pub/datum/mostRecent?nodeId=1 to see the most recently collected data:

See the API Guide for more information on the available web services.

Parting thoughts

If you only want to work on SolarNet development, you can streamline your workspace by closing all Eclipse projects whose name matches net.solarnetwork.node*. Simply select the projects in Eclipse and choose Project > Close Project. See the SolarNet Development Guide for more information, keeping in mind the VM has already been configured with the various settings described there.

Similarly if you only want to work on SolarNode development, you can close all Eclipse projects whose name matches net.solarnetwork.central*. If you do so, you can also import the solarnetwork-node/net.solarnetwork.node.upload.mock Git project and close the net.solarnetwork.node.upload.bulkjsonwebpost project so your node isn't trying to post data to your local SolarNet. Also, your development environment will start with all the available SolarNet and SolarNode projects enabled, which can slow your environment down. You can selectively close projects you know you don't need, such as all net.solarnetwork.node* projects if you're only working on SolarNet. See the SolarNode Development Guide for more information, keeping in mind the VM has already been configured with the various settings described there.

That's it for this guide. Happy coding!

Add a custom footer
Add a custom sidebar

Clone this wiki locally