Installing MetacatUI locally for development with a remote Metacat repository

Step 1. Clone MetacatUI

Step 2. Set up a local web server

While developing on MetacatUI, it’s necessary to run a web server of some sort in order for the application to work completely. It will not work properly by simply opening up the HTML webpage(s) in your browser. This is due to browser security issues that prevent certain Javascript functions from executing on local files, but also because MetacatUI needs certain web server configurations for navigation to work properly (more on that later).

Following are instructions for two local web server options - Node & Express JS (recommended) or Apache.

Server Option 1. NodeJS & ExpressJS (recommended)

Requirements: NodeJS and ExpressJS.

MetacatUI also comes with a simple script that runs a node.js application called Express.js, which can serve MetacatUI.

Before starting the server, ensure the dependencies are installed:

npm install

Then, to start the Express server:

npm run dev # or equivalent to node server.js

Server Option 2. Apache

See the Apache configuration instructions. The Apache instructions are not updated regularly, since we recommend you use the NodeJS Express server instead.

Step 3. Configure MetacatUI

For MetacatUI v2.12.0 and later

MetacatUI will work out-of-box without a configuration file, but if you have customized any part of the Metacat installation process, you may need to configure MetacatUI.

Create a configuration Javascript file, config.js, and define a MetacatUI.AppConfig JS object that contains all of your custom AppConfig values. See the AppConfig documentation to see all available config options.

A quick-start config.js could look like:

MetacatUI.AppConfig = {
  //The path to the root location of MetacatUI, i.e. where index.html is
  root: "/",
  //The path to the root location of Metacat, i.e. name of the Metacat Tomcat webapp
  metacatContext: "/metacat",
  //Your Google Maps API key, for map features
  mapKey: "YOUR-GOOGLE-MAPS-KEY",
};

Change the appConfigPath in index.html to the location where you will be deploying your config.js file.

...
<script type="text/javascript">
  // The path to your configuration file for MetacatUI. This can be any web-accessible location.
  var appConfigPath = "https://my-repo.org/config.js";
</script>
...

For MetacatUI v2.11.5 and earlier

See the config documentation for MetacatUI 2.11.5 and earlier

MetacatUI 2.12.0+ can still be configured via index.html like it used to, but that will be deprecated in future releases. It’s recommended that MetacatUI be configured via an external config.js file in v 2.12.0 and later.

Step 4. DONE!

Go to the installed web location in your web browser (e.g. if you used the Express server above, your install location is http://localhost:3000) and you’re ready to use MetacatUI!

Troubleshooting

See the installation troubleshooting page.