Running in a Linux Cloud○Running on Windows○Running Standalone○Running under Tomcat○RAMADDA Home Directory○Browser Configuration○RAMADDA Property Files○Directory Structure○Site Administration○Configuring SSL under Tomcat○Configuring SSL when running standalone
There are a few things you need to figure out to install RAMADDA:
|
- How are you going to run RAMADDA?
RAMADDA can run stand alone or under a servlet container like Tomcat. - Where is RAMADDA going to store files?
RAMADDA needs a home directory on your server to store files, databases, etc. When RAMADDA first starts up it will create a number of directories and files in this home directory. - 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. - Configure https (SSL) access.
- Do the final configuration steps through the browser
- 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.
Running in a Linux Cloud
Running on Windows
Running Standalone
mkdir ramaddainstallChange directory into the ramaddainstall directory and download the ramaddaserver.zip file from the https://ramadda.org/repository/release/latest/ramaddaserver.zip The file download URL to use is:
wget https://ramadda.org/repository/release/latest/ramaddaserver.zipOnce downloaded unzip the file:
unzip ramaddaserver.zipThis creates a ramaddaserver directory that has everything that is needed to run RAMADDA. You can consult the README. You shouldn't have to change anything in this directory so when updating RAMADDA simply shut down your RAMADDA server, delete the ramaddaserver directory and repeat the download/unzip steps above. Copy the ramaddaenv.sh file from ramaddaserver into the parent directory (ramaddainstall). This file gets sourced by ramaddaserver/ramadda.sh and defines where your RAMADDA home is, what port RAMADDA should run on and where Java is found.
cp ramaddaserver/ramaddaenv.sh .Edit this file and set the following environment variables:
export RAMADDA_HOME=/path/to/ramaddahome export RAMADDA_PORT=80 export JAVA=/usr/bin/java
Note: Running with port 80 requires the RAMADDA process to be run as the root user.
If you do not want to run it as root for security reasons you can set the port to
a higher port (e.g., 8080).
If you do this and also have SSL enabled (as described below) the SSL port should also
be set to a high port, e.g. 8443
|
ramadda.install.password=<some password>To run RAMADDA just run the script:
sh ramaddaserver/ramadda.shIf not configured in ramadda.env you can specify the home directory and port as command line arguments:
sh ramaddaserver/ramadda.sh -home </your/ramadda/home/dir> -port <8080>You can also specify the install password with
sh ramaddaserver/ramadda.sh -home </your/ramadda/home/dir> -installpassword <password>This runs with the built-in Java Derby database which work just fine. To use an external database (e.g., Postgres, MySQL) consult the documentation. The rest of the RAMADDA configuration is done through the web at http://localhost:8080/repository.
Running under Tomcat
- First, download the repository.war from the ramadda.org downloads site at https://ramadda.org/release/latest/repository.war.
- 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. - To run under Tomcat just place the repository.war in the tomcat webapps directory.
- Go to the /repository page in your browser to continue the installation process, e.g.: http://<server>/repository
- 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
- 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
to set the memory and permgen size. Consult the Tomcat documentation for more information.
RAMADDA Home Directory
Note: the home directory needs to be owned or writable by the process that the server is running under.
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>/.ramaddai.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:
- 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>
- As a process environment variable.
Environment variables can be set for the tomcat process Just define:ramadda_home=/home/dir
- 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 -Dramadda_home=/home/dir
- 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
Browser Configuration
http://<hostname>:<port>/repositoryIf you are running on your local machine you go to:
http://localhost:8080/repositoryTo ensure only authenticated users can do this final configuration step RAMADDA will prompt for an install password. You can find the install password on your server in:
<RAMADDA home directory>/install.properties
RAMADDA Property Files
When loading properties files the first one that is loaded (if it exists) is "repository.properties". An initial repository.properties is written out when RAMADDA is first configured. RAMADDA will then load any other .properties file in the home directory. It then loads any properties files found in the plugins directory.
Directory Structure
- 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
Site Administration
- 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
ramadda.ssl.port=<the ssl port>to a properties file in the RAMADDA home directory (See above).
Note: When you define an SSL port then RAMADDA will automatically redirect all login and admin requests
to that port. If your Tomcat server is not really configured for SSL then you will not be able to access RAMADDA.
See the FAQ for how to fix this.
Configuring SSL when running standalone
keytool -genkey -keyalg RSA -keystore keystore.jksThis will prompt you for some information and a password. There is more information here. If you have an existing certificate you need both the keytool and openssl installed. Consult web documentation on how to generate the keystore.jks file from your existing certificate. Once you have your keystore.jks file generated copy it to the RAMADDA home directory then specify the below configuration options in the install.properties file in your RAMADDA home directory.
ramadda.ssl.password=<the password> ramadda.ssl.keypassword=<the keystore password> ramadda.ssl.port=443 #You can override the location of the keystore. The default is: #<repository dir>/keystore.jks #ramadda.ssl.keystore=alternative path to keystore #If you want to disable ssl set this to true #ramadda.ssl.ignore=true
Using letsencrypt.org to create a certificate
If you want to have a valid signed certificate you can use https://letsencrypt.org/ to create free self-signed certificate. This requires you to have a domain name for your server's IP address and the following packages installed:- certbot-auto: https://certbot.eff.org/docs/install.html#certbot-auto
- openssl: https://www.openssl.org/
- keytool - as described above
sh letsencrypt.sh -helpThe only downside to using a certificate from letsencrypt is that you need to update it every 3 months.
Building RAMADDA from source
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)