Skip to content

Installation

Jump to bottom Edit New page
dflemstr edited this page Aug 12, 2010 · 7 revisions

Installing The Box involves the following steps:

  1. Producing a Web Archive that will be deployed to a Servlet Container
  2. Creating a database for the application
  3. Creating a storage directory for the application
  4. Setting up a Servlet container for the application
  5. Specifying the configuration for The Box
  6. Publishing and running the application

The WAR

A WAR (Web Archive) is a simple ZIP file that contains all of the files necessary for the web application to run. You need to obtain such a file to be able to insert it into a servlet container.

Precompiled WARs

Pre-compiled WARs have been made available here. Just go there and download the latest version.

Compiling your own WAR

You need to have a JDK version 5 or later before doing this.
Download The Box’s source code with:

git clone git://github.com/dflemstr/box.git

Then, download SBT (The simple build tool, a native build tool for Scala) by following these instructions under the section “Launching Sbt”.

You now have all of the build tools you need; now invoke the following command from the box source code directory:

sbt update compile test package

This will, in order, download all of the needed dependencies that The Box has, compile the distribution, run all of the unit tests, and package the compiled application into a WAR file. The generated file can be found in target/.

The Database

The web app needs a database. The Box supports MySQL, PostgreSQL (tested quite a while ago), H2 (not fully tested yet) and OracleDB (not fully tested yet). This means that a database needs to be created (With e.g. CREATE DATABASE box; in a SQL prompt; for mysql, you reach a SQL prompt with mysql -u root -p) and an user needs to be added; maybe with:

GRANT ALL ON box.* TO 'box_user'@'localhost' IDENTIFIED BY 'mypassword';

The Storage folder

A folder for data storage must be created. This folder should be writable, and accessible by the server daemon (see below). It’s recommended to choose e.g. /var/box or similar. (If you’re using Windows, just use e.g. C:\Box)

The Servlet container

A Servlet container must be installed. I personally recommend Jetty because of its great support for persisted session continuations, but your needs may vary (Tomcat is a great alternative). To install Jetty on a Debian-based machine (I did this in Ubuntu as a test; the current test server runs Fedora), do this:

  1. Do sudo apt-get install jetty libjetty6-java libjetty6-extra-java (Debian Sid or later)
  2. Enable the Jetty daemon on startup (no instructions needed for this, hopefully)
  3. Edit /etc/default/jetty and
    1. Change NO_START to be 0
    2. Uncomment and change JETTY_HOST to be empty or 0.0.0.0 (means the same thing)
    3. Uncomment and change JAVA_OPTIONS to reflect your machine’s capabilities; e.g. if you want to give the service 2 gigabytes of heap memory (useful for cache and performance in general etc) you change it to -Xmx2048m. Google “java options” to learn about more options, e.g. how to enable escape analysis (only supported by Sun JVMs) etc.
    4. You SHOULD also enable production mode (an optimized run mode for the Box that enables template caching among other things) by adding the option -Drun.mode=production to JAVA_OPTIONS.
    5. See the port 80 page for instructions on how to use Jetty on port 80 (by default it runs on port 8080) or use a router-based/os-based/iptables-based redirect to redirect packages coming to 80 so that they go to 8080.
    6. Because of a Debian-related bug, you have to do sudo mkdir /usr/share/java/webapps. The reason why is… complicated, but just enter this command and be happy.
  4. The storage folder must be made accessible to the daemon. This can be done with chown jetty:jetty folder for Jetty.

Note that you don’t need to actually start the daemon yet.

The Box Configuration

Now you have to actually tell The Box about your settings. Download the default.props file and fill in your settings by either uncommenting the defaults that are provided or by adding your own lines. Note that the email system is unstable and shouldn’t be used yet. Also note the importance of specifying the correct database driver and URL (you have to have the correct driver for your URL). Some combinations have been given as examples. For MySQL, use the MySQL driver and the jdbc:mysql://localhost:3306/databasename?autoReconnect=true URL, remembering to replace localhost with the server’s address that the database is hosted on, and databasename with your database’s name. Also, don’t forget to specify the user and password further down.
Rename the default.props file to whatever your host name is (aka mv default.props `uname -n`.props). If you enabled production mode above, you have to include the mode name in the configuration file, aka mv default.props production.`uname -n`.props

This mechanism exists so that a cluster can be used for The Box; you can specify multiple config files for the WAR, and then just copy it to all of your servers.

Now you have to add the props file to the WAR file so that The box has access to it. The WAR file is actually just a ZIP file (as stated above), so you can open it with your favorite ZIP browser, and add your modified props file to WEB-INF/classes/props (you’ll see that the default.props file already is there; don’t remove it – it is used as a fallback)

Publishing the WAR

You are now able to publish your WAR to your container:

  1. Rename it to root.war
  2. Open the folder /usr/share/jetty/webapps
  3. Remove the current root folder that is there if you’ve just installed jetty.
  4. Copy the root.war file into this directory. (Don’t extract it!)
  5. (Re)Start jetty
  6. Jetty now tries to start the server by listening to port 8080 (if you didn’t follow the port 80 guide above). You can see in /var/log/jetty/$year-$month-$day.stderrout.log whether there were any problems.

Testing the site

Now, open the web site with “http://hostname:8080/”, create an user, and add some applications.

Administration

If you want to make yourself into an administrator (so that you can delete packages; more security features to come soon), open an SQL prompt and type USE <your database name>; and then UPDATE users SET admin = 1 WHERE username = 'myuser'; (I don’t have a GUI for administration for security reasons). You can delete packages by going to an application’s details page and pressing the “Delete pkg.” button (package owners can do this too). All applications in that package (along with comments and statistics etc) will be deleted.

Updates

To update to a newer version of Box in the future, download the new WAR, insert your props file again, copy the WAR to the webapps directory, and restart jetty/other container. See the updates page for information about eventual additional steps that have to be taken when upgrading a specific version of The Box.

Add a custom footer
Add a custom sidebar
Clone this wiki locally