SkySpark by SkyFoundry

1. Setup

Overview

SkySpark is distributed as a simple ZIP file. To install it:

  1. Unzip the contents to the host machine
  2. Verify installation by running "skyspark -version"
  3. The Setup Wizard will guide you through setup process using your browser
  4. See upgrades for upgrading an older version
  5. See licensing for acquiring and installing license keys

Before you begin setup you might want to review Deployment chapter.

Verify Setup

In general the only setup required is to put "bin" into your path. On Unix you might need to call "chmod +x" on the shell scripts.

// Windows
set PATH=%PATH%;c:\skyspark\bin

// Unix
PATH=$PATH:/opt/skyspark/bin
chmod +x /opt/skyspark/bin/*

If you don't want to put skyspark/bin into your path, then just make sure you cd to the bin directory to run skyspark. If everything is setup correctly you should be able to run "skyspark -version":

E:\skyspark\bin>skyspark -version
SkySpark Daemon
Copyright (c) 2009-2012, SkyFoundry LLC
All Rights Reserved

skyspark.version: 1.0.37
skyspark.home:    E:\skyspark
java.version:     1.7.0_02
java.vm.name:     Java HotSpot(TM) Client VM
java.vm.vendor:   Oracle Corporation
java.vm.version:  22.0-b10
java.home:        C:\Program Files (x86)\Java\jre7
fan.version:      1.0.62
fan.platform:     win32-x86

The SkySpark installation is a super-set of a standard Fantom installation. If you have any trouble, see Fantom Setup to troubleshoot your environment.

Running

To run use the "bin/skyspark.bat" batch file on Windows or the "bin/skyspark" bash script on Unix and OS X. Summary of options:

When SkySpark is successfully started it will open a HTTP server on the configured port. A successful boot looks like this:

C:\skyspark\bin>skyspark
[10:02:00 17-Jun-11] <host> [info] [skyspark] ### Boot ###
[10:02:00 17-Jun-11] <host> [info] [skyspark] Loading proj 'demo' ...
[10:02:02 17-Jun-11] <demo> [info] [sys] ### Ready (928 records, 1634ms) ###
[10:02:02 17-Jun-11] <host> [info] [web] http started on port 80

If you do not see the "http started on port XX" message then you probably have a port conflict. Try changing to a different port with the "-port" option. On Unix systems, only root can open ports under 1024, so run an alternate port:

~/skyspark/bin> ./skyspark -httpPort 8080

Or you can use sudo to run skyspark on port 80 like this:

~/skyspark/bin> sudo ./skyspark

If you are running on Windows and see security exceptions such messages that the system cannot write files, then you might have UAC issues. If you right click "skyspark.bat" and try "Run as administrator". If you are trying to run from an existing "cmd.exe" terminal, then make sure you started the terminal as administrator.

The skyspark server is just a daemon process. Once it is running successfully you will need to login with your browser.

Running as Windows Service

On Windows, you can use the "fansc.exe" program to install SkySpark as a windows service. For example, to install SkySpark as a service and run it on port 8080:

C:\skyspark-2.1.12\bin\> fansc.exe install SkySpark-2.1.12 C:\skyspark-2.1.12\bin\skyspark.bat -httpPort 8080

See the fansc documentation for general information about the tool. After you have installed the service, you should manage it with the standard windows tools. As a convenience, "fansc" can also be used to uninstall a stopped service:

C:\skyspark-2.1.12\bin\> fansc.exe uninstall SkySpark-2.1.12

64-bit Java

On Windows and Unix, the "fanlaunch" script will use whatever version of java you have mapped in your path, or you can explicitly configure it with the FAN_JAVA environment variable.

To learn more about choosing between 32-bit versus 64-bit, see Deployment and Tuning.

Logging In

Once the software is running you can hit it with your browser using http://localhost:80/ (or whatever port you are using).

The first time you run the software you will be prompted to go through the setup wizard. Once the setup wizard has been completed, you'll be prompted for a login. You can log into any realm using the "su" account created during the setup wizard. The following user accounts are also available in the demo project:

Setup Wizard

The first time you run the SkySpark software the setup wizard will be displayed when you hit the server with your browser. The setup wizard guides you thru the following steps:

  1. Welcome: gets you started
  2. EULA: you must accept the end user license agreement to use the SkySpark software
  3. Settings: gives you a chance to select the password for the super user account; if an older version is detected you will be prompted to copy settings and projects
  4. Upgrade: if an older version was detected and you selected to copy settings or projects, they will be copied to your new installation (for large projects this may take a while)
  5. License: verifies that you have a correct license installed before proceeding
  6. Verify: checks your installation and if any additional updates are available
  7. Complete: gives you a chance to review your licensed installation

Once your setup is complete, you will be prompted for a login: use the username and password you configured during settings.

If for any reason you forget your superuser account settings, you can delete "etc/proj/setup.props" to run through the setup wizard again.

Upgrades

New builds are posted on the Downloads tab of skyfoundry.com. A skyfoundry.com account with appropriate permissions is required to download new builds. You will need to manually download the skyspark zip file and perform a new install for each build.

By convention you should install each skyspark build into the same parent directory. For example:

opt/
  skyspark-1.0.29/
  skyspark-1.0.30/

If you follow this convention then the setup wizard will attempt to find an older version under the same directory as your new installation. If an older version is found you will be prompted to copy settings and projects. You may choose to not copy anything and handle upgrades yourself manually.

Copy settings will copy all your configuration files located under "etc/proj/". This will include your "license.props" and "settings.props" files. You can also manually copy this directory from an older version before starting up the new version.

Project databases are stored under "db/" with a sub-directory per project. Only the "data" directory within a project contains actual data. Other directories such as "snapshots" and "cache" are optional to copy during a manual upgrade. If you choose to copy a project via the setup wizard then the entire project directory is copied (including snapshots and cache). For large projects you might choose to manually copy the files. Projects which ship with the build such as "demo" are not displayed for copy (in general you should always use the version which ships with the build).

Patches

Patches are posted on the Downloads tab of skyfoundry.com. You can manage patches using HostApp | Updates. Press the "Check for updates" button. If a newer build is available it is listed and you can follow normal Setup procedure.

If patches are available for your current build they are listed with options to install. Patches can be automatically installed from the HostApp, you do not need a skyfoundry.com account to download patches. Select the patches you wish to install and hit "Update". The patches are downloaded and when ready you will be prompted to restart SkySpark. Once you restart SkySpark, the patches will be installed into the "lib/fan" directory. You can verify patch versions under DebugApp | Pods.

Licensing

In order to run a copy of SkySpark, a valid license file is required to be installed as "etc/proj/license.props".

A license file unlocks a given recLimit which determines the maximum number of records which may be used by a given instance. This limit is applied to the total pool of all the projects summed together. You can remove unused projects to free up those records. Navigate to the Project Admin screen to review your recLimit and current usage.

If you exceed your record limit or your license becomes invalid for any reason, then the SkySpark software will route all HTTP requests back to a special Setup page until a valid license is installed. You can purchase additional record packs from http://skyfoundry.com/ or remove a project to free up your record count.

License files can be transfered to another server by copying the "license.props" file. However for a given license only one instance of an SkySpark server can be running at one time.

See Licensing for further details.

Documentation

Documentation is available online at http://skyfoundry.com/doc/ with a community user account. The documentation may also be accessed from a local SkySpark installation using the HelpApp from within a project. The first access will generate the documentation to the "{home}/doc" directory. You can also manually generate documentation for a SkySpark installation using the command:

fan docgen

Conversion to Metric

The demo database which ships with SkySpark contains a set of fictional sites in the United States using the imperial unit system. An Axon function named convertToMetric can be used to rewrite the demo data to alternate cities, timezones, and the metric system.

This script should to spawned as a background job as follows:

jobRun( convertToMetric() )

This script applies a number of changes to the database:

  1. Rewrites tags on your regions, sites, and weather recs (default is London/Manchester)
  2. Converts units from imperial to metric (°F -> °C, inH₂O -> kPa, gal -> m³)
  3. Converts all history data to alternate timezones (default is London)
  4. Converts cost unit from $ (default is £)

The top of the script contains a set of constants and mapping tables which may be customized for the cities and countries of your choice. If you wish to switch back and forth between US and metric, then make a copy of the demo database before running the conversion program.

NOTE: restart is required to refresh the weather forecast data. Also please make sure you have added Europe/London to your timezones under HostApp | Settings.