There are a few things you need to figure out to install RAMADDA:

1. How are you going to run RAMADDA?
   RAMADDA can run stand alone or under a servlet container like Tomcat.

2. Where is RAMADDA going to store files?
   RAMADDA needs a home directory on your server to store files, databases, etc.

3. What database are you going to use?
   RAMADDA comes with its own built-in database (Java Derby) but can be easily configured to use other databases.

4. Configure RAMADDA
   
   You must create the home directory first and add a <some_file_name>.properties file to it. This .properties file must have the following property set in order to finish the initial web-based installation. When you go to the web to install you will be prompted for this password.

   ramadda.install.password=<some password> 
   

   • Once installed and running you can finish the configuration process through your browser by going to:

     http://<hostname>:<port>/repository 
     

     If you are running on your local machine you go to:

     http://localhost:8080/repository
     

   • Important!. For security you really should configure https (SSL) access.

   • Do further site configuration.

   • During the installation process you can install a common set of plugins to RAMADDA that provide additional functionality. There are other plugins available as well.

We have developed an installer script that does a complete installation of Postgres and RAMADDA. Right now this has just been tested for an Amazon AWS Linux AMI. See aws.html for further details.

You can run RAMADDA stand-alone from the command line. This requires Java 1.7 or greater.

1. Download the ramaddaserver.zip from the Geode Systems site.

2. Unzip the file and consult the README.
   
3. Or, skip reading the documentation and jump right in and start RAMADDA. Figure out where you want RAMADDA to store files in its home directory. The default is <your home dir>/.ramadda. To run RAMADDA there must be a home directory already created and it must contain a .properties file with:

   ramadda.install.password=<some password> 
   

   Just run the script:

      sh ramaddaserver/ramadda.sh -home </your/ramadda/home/dir>
   

   This runs with the built-in Java Derby database which work just fine. If you want to use an external database (e.g., Postgres, MySQL) then go and read the documentation.

4. The rest of the RAMADDA configuration is done through the web at http://localhost:8080/repository.
   
5. By default the server is on port 8080. To change the port do:

       sh ramadda.sh -home </your/ramadda/home/dir> -port <some port>
   

This assumes you have Tomcat or some other servlet (e.g., Glassfish) container already installed.

1. First, download the repository.war from the Geode Systems site.

2. Specify the location of the RAMADDA home directory by setting the property ramadda_home=/home/dir. Either set this as an environmental or Java run time variable as a property in a repository.properties in the ${CATALINA_HOME}/conf directory.
3. To run under Tomcat just place the repository.war in the tomcat webapps directory.

4. Go to the /repository page in your browser to continue the installation process, e.g.: http://<server>/repository

5. By default the repository is accessed at /repository on the web server. With Tomcat the top-level path can only be a single level and corresponds to the name of the war file. If you change the top-level path for Tomcat then you also need to tell RAMADDA what this path is. You do that in a properties file (see below) with:

   ramadda.html.urlbase=/repository
   

6. If you get a memory error - something like "Permgen ..." then you need to increase the memory allocation. in your Tomcat start up script. Add or modify the following arguments of the JAVA_OPTS environment variable in the catalina start script (catalina.sh or catalina.bat):

        -Xmx1024m -XX:MaxPermSize=256m 
   

   to set the memory and permgen size. Consult the Tomcat documentation for more information.

RAMADDA uses a local home directory on the server. This is where RAMADDA looks for properties files and other resources, where the Java derby database is stored (if its used) and where any uploaded data files are stored, etc.

Note: the home directory needs to be owned or writable by the process that the server is running under. So, if you are running Tomcat then the home directory should be owned by the Tomcat process.

By default ramadda will use:

   <server process home directory>/.ramadda

i.e., the home directory of the process that is running the server (.e.g., "~", "tomcat").

You can override this by setting a ramadda_home property. You can do this in a number of ways:

1. When running stand-alone just pass the home directory as a command line argument:

       sh ramadda.sh -Dramadda_home=<home dir>
   Or:
       sh ramadda.sh -home <home dir>
   

2. As a process environment variable.
   Environment variables can be set for the tomcat process Just define:

       ramadda_home=/home/dir

3. As a Java environment variable
   Wherever you define the arguments that are passed to java when starting Tomcat include:

      -Dramadda_home=/home/dir
   

   e.g.:

       java -Xmx1024m  -XX:MaxPermSize=256m -Dramadda_home=/home/dir
   

4. RAMADDA looks for a repository.properties file under the Tomcat "conf" directory. It looks for any of the environment variables CATALINA_HOME (or CATALINA_BASE, catalina.base, catalina.home) and looks for a file under them, e.g.:

   ${CATALINA_HOME}/conf/repository.properties
   

   if found then RAMADDA looks for the property:

        ramadda_home=/home/dir

For other configuration options RAMADDA looks in its home directory for any .properties files. While most of the RAMADDA configuration is accomplished through the web ADMIN interface there are a number of configuration options that need to be placed in a properties file, e.g. database configuration, ssl options, etc.

When loading properties files the first one that is loaded (if it exists) is "repository.properties". RAMADDA will then load any other .properties file in the home directory. It then loads any properties files found in the plugins directory.

To configure RAMADDA copy this example and rename it repository.properties.

Under the home directory RAMADDA will create the following subdirectories:

• htdocs
  This is where RAMADDA will first look for any static web content that it is serving. If it cannot find the file here it looks in its internal system area. So, if you want to change the system style sheet, the logo.png file or any other web content just place it here.

  Note: Files here are relative to the top-level repository path. For example, if you have a URL:

      http://yourserver.edu/repository/somefile.gif
  

  Then RAMADDA will strip off the "repository" prefix and look for a file in the RAMADDA home dir:

      htdocs/somefile.gif
  

  If you had a URL:

      http://yourserver.edu/repository/somedir/somefile.gif
  

  Then RAMADDA looks in:

      htdocs/somedir/somefile.gif
  

• logs
  Holds the log files.
• plugins
  RAMADDA has a plugin mechanism and it looks in this directory for the plugins.
• resources
  This is where RAMADDA will first look for any internal resources (e.g., html template files, etc.)
• storage
  This is where the uploaded files are stored. The directory strucuture is:

  y<the year>/m<the month>/d<the day>/the files
  

  There is also an upload directory that holds any anonymously uploaded files.
• entries
  This is where any attachments or any other file associated with an entry (except for the actual entry file) is held.
• tmp
  A temporary file space. RAMADDA manages the scouring ,etc., of old files.
• derby
  If you are running with the Derby database this directory holds the database

RAMADDA for the most part can be configured through the Admin pages. When you are logged in to RAMADDA as an administrator there should be a "Admin" on the left side of the page.

Common tasks include:

• Change the repository title and logo in the Admin->Settings->Display
• Setting up an email server so RAMADDA can send email to users (e.g., for password notification). This is done on the Admin->Settings->Site and Contact Information page.
• Adding new users.
• Creating new folders and uploading files.
• Defining where RAMADDA can serve files from.
• Limiting access to certain parts of the repository.

Changing the Main Page

To change the presentation of the main entry page (the top-level RAMADDA page) you simply change the name and description for the Entry. You do this with the Edit->Edit Entry menu.

Configuring SSL under Tomcat

If you have your Tomcat server configured for SSL access all you need to do is to tell RAMADDA what port it is running under. Add the property:

ramadda.ssl.port=<the ssl port>

to a properties file in the RAMADDA home directory (See above).

Configuring SSL when running standalone

To configure secure SSL access to a stand-alone version of RAMADDA you need to generate a keystore. Since you are running stand-alone you must already have Java installed on your machine. Java provides a command line tool - keytool for generating a keystore. There is more information here. From the command line run:

keytool -genkey -keystore keystore

Once you have your keystore file generated you can copy it to the RAMADDA home directory as file "keystore". You then need to specify some configuration options for RAMADDA through a .properties file that you place in the RAMADDA home directory. e.g., ssl.properties:

ramadda.ssl.password=<the password>
ramadda.ssl.keypassword=<the keystore password>
ramadda.ssl.port=<the ssl port>

#You can override the location of the keystore. The default is:
#<repository dir>/keystore
#ramadda.ssl.keystore=alternative path to keystore

#If you want to skip ssl for now set this to true
#ramadda.ssl.ignore=true

It is easy to build and run RAMADDA from Github. The RAMADDA Gihub site is at https://github.com/geodesystems/ramadda. To build RAMADDA you need to have GIT, ANT and a Java compiler (1.7 or greater) installed on your machine.

To build RAMADDA:

• Check out RAMADDA from Github:

  git clone https://github.com/geodesystems/ramadda.git
  

• Build RAMADDA. This creates a stand-alone version in dist/ramaddaserver

  cd ramadda
  ant
  

• Run ramadda. This creates a ramadda home directory in: ~/.ramadda.

  cd dist/ramaddaserver
  sh ramadda.sh
  

• Note: when you first run RAMADDA it will prompt you to add a installation password into a local .properties file in the RAMADDA home directory (~/.ramadda). This is for security purposes to disallow someone else from finishing the installation process on a publicly available server.
• Go to http://localhost:8080/repository to finish the RAMADDA install
• Once configured shutdown the ramadda server (just kill the ramadda.sh run)