Hexarc is a scalable platform for web app development, which integrates a fault-tolerant data store, a distributed computing engine, and an asynchronous web server. It is designed to host everything from simple static web sites to multi-machine render farms.

Core Concepts

A Hexarc installation, known as an arcology, is a collection of one or more machines, each with zero or more hard drives.

One of the machines is considered the prime machine in the arcology and the others are secondary machines. Currently, the prime machine is fixed, but in the future you can imagine automated fail-over to promote a secondary to prime.

Each machine contains a set of modules, each implemented as a .exe and provides well-defined functionality. For example, data storage is provided by the AeonDB.exe module. The Arcology.exe module provides the core functionality of Hexarc including web services.

An arcology can have one or more volumes on which it stores data. An installation (particularly a test installation) can function with a single volume; additional volumes are used for fault tolerance. Currently, only the prime machine can host the data store, but in the future you can imagine different tables stored on different machines or even a single table sharded across machines.

An arcology can have packages, which are the equivalent of apps running on the arcology. For example, a web site would be implemented as a package.

Creating an Arcology

This section contains instruction for installing the prime machine and its data store. Once installed, you will have a functioning arcology, though you may need to install additional modules and packages.

Preparations

  1. You must have the Hexarc binaries. See: Hexarc Development Environment for instructions on building them.
  2. You will need a machine running Windows 64-bit.
  3. Hexarc is a web server, so it needs access to port 80. Make sure no other application is listening on port 80. [You can change the port that Hexarc listens on, but it is somewhat complicated at this point.]
  4. Create a directory for the binary modules (e.g., c:\hexarc\modules). It should be a writable directory (for now, the server writes log files to its own directory).
  5. Compile all module files and put them in the modules directory. At minimum you should have: Arcology.exe and AeonDb.exe.
  6. Create a development directory to upload packages (e.g., c:\hexarc\dev). Put AI1.exe in the development directory.
  7. The Packages directory (in the repo) contains the default packages for the installation. Put each package under its own directory under the development directory. For example, the AI2 package should be at c:\hexarc\dev\AI2.

Creating the Arcology

  1. Open a command prompt at the modules directory (c:\hexarc\modules). Type:
    2. start arcology /debug

    This will run the arcology server and show debug output in a window. You may get a Windows prompt to open up some ports (which is required).

  2. The arcology server is running under the Arcology.exe process. You can shut down the server by closing the output window (though there is a bug which might output some errors). If you run into problems, you can always kill the Arcology.exe process. The server is fault-tolerant, so it will not lose any data (barring bugs, which still exist).
  3. Now change to the development directory (c:\hexarc\dev). Run ai1.exe. You will see something like this:
    4. AI1 1.0
Copyright (c) 2011-2015 by Kronosaur Productions. All Rights Reserved.

Connecting to localhost...OK
Accessing Arc.console interface...OK
Arcology requires an admin account.
Username:
  4. This is prompting you to create an administrator account. Enter an admin account name (e.g., admin).
  5. Next you will be prompted to create a password for the admin account.
  6. The AI1 program ("Arcology Interface 1") is the low-level connection to the arcology. It is used to configure the arcology before we have a web service running.
  7. Type help to see a list of commands. Note: There are a couple of bugs in the protocol, so if AI1 times out or fails for whatever reason, just run it again.
  8. By default, the arcology creates a data volume at c:\Arcology. If that's OK, then leave everything alone. See below for instructions on managing volumes.

The arcology is now running, though it doesn't do much. You can kill Arcology.exe and restart it. If you wish, you can also install it as a Windows service by typing: arcology /install (in an elevated command prompt). Once installed as a service, you can set it to run automatically on Windows start.

Otherwise, you will have to run Arcology.exe (with the /debug switch) each time you want to use it (which is safer anyways).

Installing AI2

Next we will install the AI2 package. AI2 is a slightly more advanced web-based interface to the arcology.

  1. For ease of deployment, we deploy each package to its own subdomain. You will need to edit the hosts file to create a subdomain for AI2.
  2. Edit c:\windows\system32\drivers\etc\hosts.
  3. Add an entry pointing to 127.0.0.1 for ai2.dev.com. [We've commandeered the dev.com domain here. It's OK as long as it all points to localhost.]
  4. Now make sure you have the AI2 package files in the right place under you development directory.
  5. In an editor, open up c:\hexarc\dev\AI2\AI2Package.ars. This file defines the web interface for the service. Look at line #24 where the hosts are defined. These are the host that we expect the service to be. It lists two hosts (parentheses indicate a list, and the whitespace is the separator). One of the hosts is ai2.dev.com, just as expected. If you chose a different subdomain in the hosts file, make sure you change it here too.
  6. The second host, ai2.hierosteel.com, is the running production version. If you wish to access your arcology from the internet, specify a real domain here.
  7. Once you've made all your subdomain edits, run AI1 again and type:
    8. uploadPackage AI2 AI2\AI2Package.ars
  8. You will see it upload several files.
  9. Now to test everything, open up a web browser to http://ai2.dev.com/. If you see the AI2 Hexarc Command Interface, then everything worked.

Using AI2

The AI2 web interface is a simple command-line interface for managing the arcology. You will need to sign in with your admin account to use it.

The help command will show you all available commands. Commands are case-sensitive.

The arc.modules command shows the list of modules loaded in the arcology. The arc.packages command shows the list of packages installed.

If you've gotten this far, you've got a running arcology. You may now install new modules and packages. For example, see: https://ministry.kronosaur.com/record.hexm?id=58530.

Uninstalling

Hexarc does not modify the registry or any other system resources. You can uninstall it by deleting all the directories. If you installed it as a Windows service, run arcology /remove to uninstall it.