Installing and Launching Maqetta on Localhost

Supported browsers: Google Chrome (current release), Mozilla Firefox (current release) and Mac Safari 5.1

Long-term vision: everyone runs a cloud version of Maqetta (i.e., run off server)

This README describes how to launch the locally installed version of Maqetta off of http://localhost. However, it is important to note that the Maqetta open source team's goal is that ultimately everyone will run Maqetta in the cloud (i.e. off of a server), saving files in their cloud workspace. The team features of Maqetta, particularly review and commenting, require users to run the server-based version of the product.

There might be multiple cloud versions of Maqetta. The Maqetta team provides a non-commercial, as-is, non-secure, use at your own risk, etc. cloud-hosted version of Maqetta at Maqetta.org:

http://maqetta.org

Other cloud versions of Maqetta might also be available. For example, your company might be hosting a version of Maqetta on an intranet server, or other web sites might offer cloud-hosted versions of Maqetta.

Instructions for installing and running Maqetta locally

With this option, you download a ZIP file containing Maqetta, double-click on a file to launch the Maqetta server on localhost:50000, and then launch Maqetta by navigating your browser to http://localhost:50000/maqetta. As a result, you will be running Maqetta on a "local cloud" where http://localhost:50000/maqetta simulates a cloud environment. Detailed installation instructions can be found in a subsequent section. This approach allows your data to be stored on your local file system, but you cannot use the team features such as review and commenting.

Here are the instructions for installing and running Maqetta locally (i.e. http://localhost:50000).

Step 1: Verify you have Java Version 6 or greater installed on your machine.

Maqetta requires Java Version 6 or greater installed on your machine in order to run Maqetta locally. (NOTE: It is best to install the latest version of Java so that you have all of the latest security updates.)

To see if Java is installed, and if so which version, follow these steps:

Open a Command Prompt window
- On Windows: Click Start > Run, type in cmd and click OK
- On Mac: Open Finder > Applications > Utilites > Terminal
Type in java -version
If the version number 1.6.0 or higher, no further action is required.
If the version number is lower than 1.6.0, or you don't have Java on your machine, then you'll need to install Java 1.6 (or later) onto your machine.

NOTE: If you need to download and install Java onto your system, we strongly recommend installing the Java JDK (Java Development Kit) instead of the JRE (Java Runtime Environment), particularly on Windows. On Windows, the JDK makes the "java" command available to command line tools, whereas with the JRE, you'll need to manually update the PATH environment variable to point to the bin folder for your Java installation.

Step 2: Launch the Maqetta server

NOTE: On some Windows systems, you need to expand the Maqetta download ZIP file into a folder for which you have full read/write permissions. The recommended approach is to expand the Maqetta ZIP file somewhere inside your user file area at \Users\<mylogin>.

NOTE: On some MacOS systems, you will need to make sure your Security and Privacy settings allow applications to run that are downloaded from anywhere. See instructions at: OS X: About Gatekeeper.

With the Explorer (Windows) or Finder (Mac), navigate to the directory into which you unzipped the Maqetta files.
Launch the Maqetta server process.
- On Windows, double-click on the file maqetta.server.win.bat (depending on your settings, the Windows explorer might not show the ".bat" extension).
- On Mac, double-click on the file maqetta.server.mac.command (depending on your settings, the Mac finder might not show the ".command" extension).

You can tell that the server has launched if you see the following message in the shell window:

!!!!!!!!!!!!!!
NOTE: CLOSING THIS WINDOW WILL 
      STOP THE MAQETTA SERVER PROCESS
!!!!!!!!!!!!!

Using directory : <maqetta-unzip-dir>\users
start your browser at http://localhost:50000/maqetta

...(various messages might appear here)...

osgi>

Be sure to wait until you see the osgi> prompt appear. That indicates that the server has initialized.

The Maqetta server will continue to run until you close the shell window that comes up after you double-click on the server launch file. Therefore, if you close the shell window, the Maqetta server process will stop running, at which point you can't run http://localhost:50000/maqetta anymore.

One possible problem is that you might already be running a different localhost server on your system at http://localhost:50000 (the default for Maqetta). Refer to the detailed notes immediately below about how to change the Maqetta launch script to use a different port number.

Detailed notes about the Maqetta server

On the Mac, you can launch the Maqetta server from the Dock by dragging the maqetta.server.mac.command onto the right part of the doc.
The launch scripts (maqetta.server.win.bat and maqetta.server.mac.command) have some default parameters:
- HTTP port number - The scripts default to port 50000. If you prefer to use 8080 or some other port number, hand-edit the launch script and change 50000 to something else (any number in the 50000's is OK).
- User workspace folder - Any files that you create in Maqetta will be saved into a folder managed by the Maqetta server process. You can change the location for where your workspace is saved by hand-editing the launch scripts. Note that a future version of Maqetta will allow you to open any file on your local system. The current release can only open files within the workspace area.
  
  The default user workspace folder locations are:
  - Windows: <maqetta-unzip-dir>\users
  - Macintosh: <maqetta-unzip-dir>/users

Step 3: Launch Maqetta application in Google Chrome, Firefox 4 or Mac Safari 5.1

Once the Maqetta server has been launched (see previous steps), open Chrome, Firefox or Safari and go to the following URL:

http://localhost:50000/maqetta

You will now see a Maqetta login screen.

The first time you bring up a locally installed version of Maqetta in the browser, you will need create a new user account by clicking on the Register button, which will take you to the account creation screen. For a local installation of Maqetta, the login name can be an email address or any string (e.g., your name). (Note: Local installations do not require that new accounts get verified via activation emails.) After clicking Register, the Maqetta application should appear.

In subsequent sessions, you will need to enter the same login and password.

Detailed instructions for clearing caches and cookies in various browsers

When using a new release of Maqetta for the first time, it is generally a good idea to restart your browser and clear caches and any cookies associated with the Maqetta server. Details instructions:

Quit and restart your browser before launching a new version of Maqetta for the first time. We have found occasional issues when switching from an old version of Maqetta to a newer version.
Clear both the browser's cache, cookes and "appcache" (offline storage):
- Chrome (version 19)
  - (Windows only): Click on the tools icon (looks like a wrench) and choose "Settings". This will open a new browser tab titled "Settings".
  - (Mac only) Under the "Chrome" menu, choose "Preferences". This will open a new browser tab titled "Settings".
  - Make sure that advanced settings such as "Content settings" and "Clear browser cache" are visible on the page. In some cases, you might have to toggle the "Show advanced settings / Hide advanced settings" control (found at the bottom of the page content for the Settings page).
  - To clear the browser cache, click on the "Clear browsing data" button. In the dialog that follows, make sure "Empty the cache" is checked. You might want to uncheck the other items so that other things are not also cleared. Once the check boxes are set correctly, click on the "Clear browsing data" button.
  - To clear the appcache (offline storage) and Maqetta's cookies:
    - Click on "Content settings...." to bring up the Content Settings dialog.
    - In the "Cookies" section towards the top, click on the "All Cookies and Site Data..." button to bring up the Cookies and Other Data panel.
    - In the top right search box, type in part of the URL for the web server where you are running Maqetta. For example:
      - If you run Maqetta at Maqetta.org, then you can start typing "maqetta.org" into the search box and immediately you will see the subset of sites that match the pattern (e.g., maqetta.org).
      - If run run locally on http://localhost, then you can start typing "localhost" into the search box.
    - When the listing of sites shows the site from which you run Maqetta, click on the row for that site to select that row.
    - Then click on the "x" in the top-right of that row to delete all cookies and offline storage for that site.
- Firefox
  - (Windows only): On main menubar, invoke Tools->Options. This brings up the Options dialog. Click on the "Advanced" button and then click on the "Network" tab.
  - (Mac only) Under the "Firefox" menu, choose "Preferences". Click on the "Advanced" button and then click on the "Network" tab.
  - Clear cache: Under "Cached Web Content", click on "Clear Now".
  - Clear appcache: Under "Offline Storage", at the bottom is a box labelled as follows: "The following websites have stored data for offline use:". See if the server which hosts Maqetta is listed. If you installed locally, the server is "localhost". If running off of http://maqetta.org, the server is "maqetta.org". If the Maqetta server is listed, click on it and then click "Remove" (and then "Remove offline data").
  - Clear cookies: Click on the "Privacy" tab, then click on the hyperlink that says "remove individual cookies". This brings up a "Cookies" dialog. In the search text entry box at the top, type in the URL for the web server where you are running Maqetta. For example:
    - If you run Maqetta at Maqetta.org, then type "maqetta.org" into the search box.
    - If run run locally on http://localhost, then type "localhost" into the search box.
    Select all cookies listed and then click the "Remove cookie" button.
- Safari
  - (Mac only) Clear both the browser cache and the application cache: Under the "Safari" menu, invoke the "Reset Safari..." command, make sure the "Remove all website data" checkbox is set, and then click on the "Reset"" button.
  - (Mac only) Clear cookies: Under the "Safari" menu, invoke the "Preferences..." command to bring up the Preferences dialog. Click on the "Security" tab, then click on the "Details" button under the "Remove all website data" button. This brings up a dialog. In the search text entry box at the top, type in the URL for the web server where you are running Maqetta. For example:
    - If you run Maqetta at Maqetta.org, then type "maqetta.org" into the search box.
    - If run run locally on http://localhost, then type "localhost" into the search box.
    Click-select the entry(ies) that correspond to your server and then click the "Remove" button.