NOAA ERDDAP
Easier access to scientific data
   
Brought to you by NOAA NMFS SWFSC ERD    
 

Set Up Your Own ERDDAP

Why? | Initial Setup | Update | Need To Know | Don't Need To Know |
Slide Shows | Programmer's Guide | List of Changes | Credits | License | Contact
 
And see the related document Working with the datasets.xml File

ERDDAP is a Free and Open Source (external link), all-Java (servlet), web application that runs in a web application server (for example, Tomcat (recommended), or Jetty (it works, but we don't support it)). This web page is mostly for people ("ERDDAP administrators") who want to set up their own ERDDAP installation at their own website.

Why use ERDDAP to distribute your data?

Because the small effort to set up ERDDAP brings many benefits. You can customize your ERDDAP's appearance so ERDDAP reflects your organization and fits in with the rest of your website.

ERDDAP has been installed by approximately 100 organizations in at least 17 countries

(Australia, Belgium, Canada, China, France, India, Ireland, Italy, New Zealand, Russia, South Africa, Spain, Sri Lanka, Sweden, Thailand, UK, USA), including: This is a list of just some of the organizations where ERDDAP has been installed by some individual or some group. It does not imply that the individual, the group, or the organization recommends or endorses ERDDAP.

ERDDAP is recommended within NOAA and CNRS
NOAA's Data Access Procedural Directive (external link) includes ERDDAP in its list of recommended data servers for use by groups within NOAA. ERDDAP is favorably mentioned in section 4.2.3 of the
Guide de bonnes pratiques sur la gestion des données de la recherche
(Research Data Management Best Practices Guide) (external link)
of the Centre National de la Recherche Scientifique (CNRS) in France.

Is the installation procedure hard? Can I do it?

The initial installation takes some time, but it isn't very hard. You can do it. If you get stuck, email me at erd dot data at noaa dot gov . I will help you.
Or, you can join the ERDDAP Google Group / Mailing List and post your question there.

How To Do the Initial Setup of ERDDAP on Your Server

ERDDAP can run on any server that supports Java and Tomcat (and other application servers like Jetty, but we don't support them). ERDDAP has been tested on Linux (including on Amazon's AWS), Mac, and Windows computers.

The standard ERDDAP installation instructions for Linux, Macs, and Windows computers are:

  1. For ERDDAP v2.19+, set up Java 17.
    For security reasons, it is almost always best to use the latest version of Java 17.
    Please download and install the latest version of
    Adoptium's OpenJDK (Temurin) 17 (LTS) (external link). To verify the installation, type "/javaJreBinDirectory/java -version", for example
    /usr/local/jdk-17.0.4+8/jre/bin/java -version

    [For ERDDAP versions before v2.19, use Java 8.]

    ERDDAP works with Java from other sources, but we recommend Adoptium because it is the main, community-supported, free (as in beer and speech) version of Java 17 that offers Long Term Support (free upgrades for many years past the initial release). For security reasons, please update your ERDDAP's version of Java periodically as new versions of Java 17 become available from Adoptium.

    ERDDAP has been tested and used extensively with Java 17, not other versions. For various reasons, we don't test with nor support other versions of Java.
     

  2. Set up Tomcat (external link).
    Tomcat is the most widely used Java Application Server, which is Java software that stands between the operating system's network services and Java server software like ERDDAP. It is Free and Open Source Software (FOSS).

    You can use another Java Application Server (e.g., Jetty), but we only test with and support Tomcat.
     

    • Download Tomcat and unpack it on your server or PC.
      For security reasons, it is almost always best to use the latest version of Tomcat 10 (version 9 and below are not acceptable) which is designed to work with Java 17. Below, the Tomcat directory will be referred to as tomcat.

      Warning! If you already have a Tomcat running some other web application (especially THREDDS), we recommend that you install ERDDAP in a second Tomcat, because ERDDAP needs different Tomcat settings and shouldn't have to contend with other applications for memory.

      • On Linux, download the "Core" "tar.gz" Tomcat distribution (external link) and unpack it. We recommend unpacking it in /usr/local.
      • On a Mac, Tomcat is probably already installed in /Library/Tomcat, but should update it to the latest version of Tomcat 10.
        If you download it, download the "Core" "tar.gz" Tomcat distribution (external link) and unpack it in /Library/Tomcat.
      • On Windows, you can download the "Core" "zip" Tomcat distribution (external link) (which doesn't mess with the Windows registry and which you control from a DOS command line) and unpack it in an appropriate directory. (For development, we use the "Core" "zip" distribution. We make a /programs directory and unpack it there.) Or you can download the "Core" "64-bit Windows zip" distribution, which includes more features. If the distribution is a Windows installer, it will probably put Tomcat in, for example, /Program Files/apache-tomcat-10.0.23 .
         
    • server.xml - In tomcat/conf/server.xml file, there are two changes that you should make to each of the two <Connector> tags (one for '<Connector port="8080" ' and one for '<Connector port="8443" '):
      1. (Recommended) Increase the connectionTimeout parameter value, perhaps to 300000 (milliseconds) (which is 5 minutes).
      2. (Recommended) Add a new parameter: relaxedQueryChars="[]|" This is optional and slightly less secure, but removes the need for users to percent-encode these characters when they occur in the parameters of a user's request URL.
         
    • context.xml -- Resources Cache - In tomcat/conf/context.xml, right before the </Context> tag, change the Resources tag (or add it if it isn't already there) to set the cacheMaxSize parameter to 80000:
      <Resources cachingAllowed="true" cacheMaxSize="80000" />
      This avoids numerous warnings in catalina.out that all start with
      "WARNING [main] org.apache.catalina.webresources.Cache.getResource Unable to add the resource at [/WEB-INF/classes/..."
       
    • On Linux computers, change the Apache timeout settings so that time-consuming user requests don't timeout (with what often appears as a "Proxy" or "Bad Gateway" error). As the root user:
      1. Modify the Apache httpd.conf file (usually in /etc/httpd/conf/ ):
        Change the existing <Timeout> setting (or add one at the end of the file) to 3600 (seconds), instead of the default 60 or 120 seconds.
        Change the existing <ProxyTimeout> setting (or add one at the end of the file) to 3600 (seconds), instead of the default 60 or 120 seconds.
      2. Restart Apache: /usr/sbin/apachectl -k graceful (but sometimes it is in a different directory).
         
    • Security recommendation: See these instructions (external link) to increase the security of your Tomcat installation, especially for public servers.
       
    • For public ERDDAP installations on Linux and Macs, it is best to set up Tomcat (the program) as belonging to user "tomcat" (a separate user with limited permissions and which has no password. Thus, only the super user can switch to acting as user tomcat. This makes it impossible for hackers to log in to your server as user tomcat. And in any case, you should make it so that the tomcat user has very limited permissions on the server's file system (read+write+execute privileges for the apache-tomcat directory tree and <bigParentDirectory> and read-only privileges for directories with data that ERDDAP needs access to).
      • You can create the tomcat user account (which has no password) by using the command
        sudo useradd tomcat -s /bin/bash -p '*'
      • You can switch to working as user tomcat by using the command
        sudo su - tomcat
        (It will ask you for the superuser password for permission to do this.)
      • You can stop working as user tomcat by using the command
        exit
      • Do most of the rest of the Tomcat and ERDDAP setup instructions as user "tomcat". Later, run the startup.sh and shutdown.sh scripts as user "tomcat" so that Tomcat has permission to write to its log files.
      • After unpacking Tomcat, from the parent of the apache-tomcat directory:
        • Change ownership of the apache-tomcat directory tree to the tomcat user.
          chown -R tomcat apache-tomcat-10.0.23
          (but substitute the actual name of your tomcat directory).
        • Change the "group" to be tomcat, your username, or the name of a small group that includes tomcat and all the administrators of Tomcat/ERDDAP, e.g.,
          chgrp -R yourUserName apache-tomcat-10.0.23
        • Change permissions so that tomcat and the group have read, write, execute privileges, e.g,.
          chmod -R ug+rwx apache-tomcat-10.0.23
        • Remove "other" user's permissions to read, write, or execute:
          chmod -R o-rwx apache-tomcat-10.0.23
          This is important, because it prevents other users from reading possibly sensitive information in ERDDAP setup files.

         
    • Set Tomcat's Environment Variables

      On Linux and Macs:
      Create a file tomcat/bin/setenv.sh (or in Red Hat Enterprise Linux [RHEL], edit ~tomcat/conf/tomcat10.conf) to set Tomcat's environment variables. This file will be used by tomcat/bin/startup.sh and shutdown.sh. The file should contain something like:
      export JAVA_HOME=/usr/local/jdk-17.0.4+8
      export JAVA_OPTS='-server -Djava.awt.headless=true -Xmx1500M -Xms1500M'
      export TOMCAT_HOME=/usr/local/apache-tomcat-10.0.23
      export CATALINA_HOME=/usr/local/apache-tomcat-10.0.23

      (but substitute the directory names from your computer).
      (If you previously set JRE_HOME, you can remove that.)
      On Macs, you probably don't need to set JAVA_HOME.

      On Windows:
      Create a file tomcat\bin\setenv.bat to set Tomcat's environment variables. This file will be used by tomcat\bin\startup.bat and shutdown.bat. The file should contain something like:
      SET "JAVA_HOME=\someDirectory\jdk-17.0.4+8"
      SET "JAVA_OPTS=-server -Xmx1500M -Xms1500M"
      SET "TOMCAT_HOME=\Program Files\apache-tomcat-10.0.23"
      SET "CATALINA_HOME=\Program Files\apache-tomcat-10.0.23"

      (but substitute the directory names from your computer).
      If this is just for local testing, remove "-server".
      (If you previously set JRE_HOME, you can remove that.)

      The -Xmx and -Xms memory settings are important because ERDDAP works better with more memory. Always set -Xms to the same value as -Xmx.

      • For 32 bit Operating Systems and 32 bit Java:
        64 bit Java is much better than 32 bit Java, but 32 bit Java will work as long as the server isn't really busy. The more physical memory in the server the better: 4+ GB is really good, 2 GB is okay, less is not recommended. With 32 bit Java, even with abundant physical memory, Tomcat and Java won't run if you try to set -Xmx much above 1500M (1200M on some computers). If your server has less than 2GB of memory, reduce the -Xmx value (in 'M'egaBytes) to 1/2 of the computer's physical memory.
      • For 64 bit Operating Systems and 64 bit Java:
        64 bit Java will only work on a 64 bit operating system.
        • With Java 8, you need to add -d64 to the Tomcat CATALINA_OPTS parameter in setenv.bat
        • With Java 17, you choose 64 bit Java when you download a version of Java marked "64 bit".
        With 64 bit Java, Tomcat and Java can use very high -Xmx and -Xms settings. The more physical memory in the server the better. As a simplistic suggestion: we recommend you set -Xmx and -Xms to (in 'M'egaBytes) to 1/2 (or less) of the computer's physical memory. You can see if Tomcat, Java, and ERDDAP are indeed running in 64 bit mode by searching for " bit," in ERDDAP's Daily Report email or in the bigParentDirectory/logs/log.txt file (bigParentDirectory is specified in setup.xml).
      • In ERDDAP's log.txt file, you will see many "GC (Allocation Failure)" messages.
        This is usually not a problem. It is a frequent message from a normally operating Java saying that it just finished a minor garbage collection because it ran out of room in Eden (the section of the Java heap for very young objects). Usually the message shows you memoryUseBefore->memoryUseAfter. If those two numbers are close together, it means that the garbage collection wasn't productive. The message is only a sign of trouble if it is very frequent (every few seconds), not productive, and the numbers are large and not growing, which together indicate that Java needs more memory, is struggling to free up memory, and is unable to free up memory. This may happen during a stressful time, then go away. But if it persists, that is a sign of trouble.
      • If you see java.lang.OutOfMemoryError's in ERDDAP's log.txt file, see OutOfMemoryError for tips on how to diagnose and resolve the problems.
         
    • On Linux and Macs, change the permissions of all *.sh files in tomcat/bin/ to be executable by the owner, e.g., with
      chmod +x *.sh
       
    • Fonts for images: We strongly prefer the free DejaVu fonts (external link) to the other Java fonts. Using these fonts is strongly recommended but not required.

      If you choose not to use the DejaVu fonts, you need to change the fontFamily setting in setup.xml to <fontFamily>SansSerif</fontFamily>, which is available with all Java distributions. If you set fontFamily to the name of a font that isn't available, ERDDAP won't load and will print a list of available fonts in the log.txt file. You must use one of those fonts.

      If you choose to use the DejaVu fonts, please make sure the fontFamily setting in setup.xml is <fontFamily>DejaVu Sans</fontFamily>.

      To install the DejaVu fonts, please download DejaVuFonts.zip (5,522,795 bytes, MD5=33E1E61FAB06A547851ED308B4FFEF42) and unzip the font files to a temporary directory.

      • On Linux:
        • For Linux Adoptium Java distributions, see these instructions (external link).
        • With other Java distributions: As the Tomcat user, copy the font files into JAVA_HOME/lib/fonts so Java can find the fonts. Remember: if/when you later upgrade to a newer version of Java, you need to reinstall these fonts.
      • On Macs: for each font file, double click on it and then click Install Font.
      • On Windows 7 and 10: in Windows Explorer, select all of the font files. Right click. Click on Install.
         
    • Test your Tomcat installation.
      • Linux:
        • As user "tomcat", run tomcat/bin/startup.sh
        • View your URL + ":8080/" in your browser (e.g., http://coastwatch.pfeg.noaa.gov:8080/).
        • You should see the Tomcat "Congratulations" page.
          If there is trouble, see the Tomcat log file tomcat/logs/catalina.out.
      • Mac (run tomcat as the system administrator user):
        • Run tomcat/bin/startup.sh
        • View your URL + ":8080/" in your browser (e.g., http://coastwatch.pfeg.noaa.gov:8080/). Note that by default, your Tomcat is only accessible by you. It is not publicly accessible.
        • You should see the Tomcat "Congratulations" page.
          If there is trouble, see the Tomcat log file tomcat/logs/catalina.out.
      • Windows localhost:
        • Right click on the Tomcat icon in the system tray, and choose "Start service".
        • View http://127.0.0.1:8080/ (or perhaps http://localhost:8080/) in your browser. Note that by default, your Tomcat is only accessible by you. It is not publicly accessible.
        • You should see the Tomcat "Congratulations" page.
          If there is trouble, see the Tomcat log file tomcat/logs/catalina.out.

         
    • Troubles with the Tomcat installation?
      • On Linux and Mac, if you can't reach Tomcat or ERDDAP (or perhaps you just can't reach them from a computer outside your firewall), you can test if Tomcat is listening to port 8080, by typing (as root) on a command line of the server:
        netstat -tuplen | grep 8080
        That should return one line with something like:
        tcp 0 0 :::8080 :::* LISTEN ## ##### ####/java
        (where '#' is some digit), indicating that a "java" process (presumably Tomcat) is listening on port "8080" for "tcp" traffic. If no lines were returned, if the line returned is significantly different, or if two or more lines were returned, then there may be a problem with the port settings.
      • See the Tomcat log file tomcat/logs/catalina.out. Tomcat problems and some ERDDAP startup problems are almost always indicated there. This is common when you are first setting up ERDDAP.
      • See the Tomcat (external link) website or search the web for help, but please let us know the problems you had and the solutions you found.
      • Email me at erd dot data at noaa dot gov . I will try to help you.
      • Or, you can join the ERDDAP Google Group / Mailing List and post your question there.
         
  3. Set up the tomcat/content/erddap configuration files.
    On Linux, Mac, and Windows, download erddapContent.zip (version 2.22, 19810 bytes, MD5=1E26F62E7A06191EE6868C40B9A29362, dated 2022-12-08) and unzip it into tomcat, creating tomcat/content/erddap .

    Other Directory: For Red Hat Enterprise Linux (RHEL) or for other situations where you aren't allowed to modify the Tomcat directory or where you want/need to put the ERDDAP content directory in some other location for some other reason (for example, if you use Jetty instead of Tomcat), unzip erddapContent.zip into the desired directory (to which only user=tomcat has access) and set the erddapContentDirectory system property (e.g., erddapContentDirectory=~tomcat/content/erddap) so ERDDAP can find this new content directory.

    [Some previous versions are also available:
    2.17 (19,792 bytes, MD5=8F892616BAEEF2DF0F4BB036DCB4AD7C, dated 2022-02-16)
    2.18 (19,792 bytes, MD5=8F892616BAEEF2DF0F4BB036DCB4AD7C, dated 2022-02-16)
    2.21 (19,810 bytes, MD5=1E26F62E7A06191EE6868C40B9A29362, dated 2022-10-09) ]

    Then,

    • Read the comments in tomcat/content/erddap/setup.xml and make the requested changes. setup.xml is the file with all of the settings which specify how your ERDDAP behaves.
      For the initial setup, you MUST at least change these settings: <bigParentDirectory>, <emailEverythingTo>, <baseUrl>, <email.*>, <admin.*> (and <baseHttpsUrl> when you set up https).

      When you create the bigParentDirectory, from the parent directory of bigParentDirectory:

      • Make user=tomcat the owner of the bigParentDirectory, e.g.,
        chown -R tomcat bigParentDirectory
      • Change the "group" to be tomcat, your username, or the name of a small group that includes tomcat and all the administrators of Tomcat/ERDDAP, e.g.,
        chgrp -R yourUserName bigParentDirectory
      • Change permissions so that tomcat and the group have read, write, execute privileges, e.g,.
        chmod -R ug+rwx bigParentDirectory
      • Remove "other" user's permissions to read, write, or execute:
        chmod -R o-rwx bigParentDirectory reading possibly sensitive information in ERDDAP log files and files with information about private datasets.

      Environment Variables - Starting with ERDDAP v2.13, ERDDAP administrators can override any value in setup.xml by specifying an environment variable named ERDDAP_valueName before running ERDDAP. For example, use ERDDAP_baseUrl overrides the <baseUrl> value. This can be handy when deploying ERDDAP with a container, as you can put standard settings in setup.xml and then supply special settings via environment variables. If you supply secret information to ERDDAP via this method, be sure to check that the information will remain secret. ERDDAP only reads environment variables once per startup, in the first second of startup, so one way to use this is: set the environment variables, start ERDDAP, wait until ERDDAP is started, then unset the environment variables.

    • Read the comments in Working with the datasets.xml File. Later, after you get ERDDAP running for the first time (usually with just the default datasets), you will modify the XML in tomcat/content/erddap/datasets.xml to specify all of the datasets you want your ERDDAP to serve. This is where you will you spend the bulk of your time while setting up ERDDAP and later while maintaining your ERDDAP.
       
    • (Unlikely) Now or (slightly more likely) in the future, if you want to modify erddap's CSS file, make a copy of tomcat/content/erddap/images/erddapStart2.css called erddap2.css and then make changes to it. Changes to erddap2.css only take effect when ERDDAP is restarted and often also require the user to clear the browser's cached files.
       
    ERDDAP will not work correctly if the setup.xml or datasets.xml file isn't a well-formed XML file. So, after you edit these files, it is a good idea to verify that the result is well-formed XML by pasting the XML text into an XML checker like xmlvalidation (external link).
     
  4. Install the erddap.war file.
    On Linux, Mac, and Windows, download erddap.war into tomcat/webapps .
    (version 2.22, 567,742,765 bytes, MD5=2B33354F633294213AE2AFDDCF4DA6D0, dated 2022-12-08)
    The .war file is big because it contains high resolution coastline, boundary, and elevation data needed to create maps.

    [Some previous versions are also available.
    2.17 (551,068,245 bytes, MD5=5FEA912B5D42E50EAB9591F773EA848D, dated 2022-02-16)
    2.18 (551,069,844 bytes, MD5=461325E97E7577EC671DD50246CCFB8B, dated 2022-02-23)
    2.21 (568,644,411 bytes, MD5=F2CFF805893146E932E498FDDBD519B6, dated 2022-10-09) ]

  5. Use ProxyPass so users don't have to put the port number, e.g., :8080, in the URL.
    On Linux computers, if Tomcat is running in Apache, please modify the Apache httpd.conf file (usually in /etc/httpd/conf/ ) to allow HTTP traffic to/from ERDDAP without requiring the port number, e.g., :8080, in the URL. As the root user:
    1. Modify the existing <VirtualHost> tag (if there is one), or add one at the end of the file:
      <VirtualHost *:80>
         ServerName YourDomain.org
         ProxyRequests Off
         ProxyPreserveHost On
         ProxyPass /erddap http://localhost:8080/erddap
         ProxyPassReverse /erddap http://localhost:8080/erddap
      </VirtualHost>
      
    2. Then restart Apache: /usr/sbin/apachectl -k graceful (but sometimes it is in a different directory).
       
  6. (UNCOMMON) If you are using NGINX (external link) (a web server and load balancer):
    in order to get NGINX and ERDDAP working correctly with https, you need to put the following snippet inside the Tomcat server.xml <Host> block:
    <Valve className="org.apache.catalina.valves.RemoteIpValve"  
      remoteIpHeader="X-Forwarded-For"  
      protocolHeader="X-Forwarded-Proto"  
      protocolHeaderHttpsValue="https" /> 
    
    And in the nginx config file, you need to set these headers:
      proxy_set_header Host              $host;
      proxy_set_header X-Real-IP         $remote_addr;
      proxy_set_header REMOTE_ADDR       $remote_addr;
      proxy_set_header HTTP_CLIENT_IP    $remote_addr;
      proxy_set_header X-Forwarded-For   $proxy_add_x_forwarded_for;
      proxy_set_header X-Forwarded-Proto $scheme;
    
    (Thanks to Kyle Wilcox.)
     
  7. Start Tomcat.
    • (I don't recommend using the Tomcat Web Application Manager. If you don't fully shutdown and startup Tomcat, sooner or later you will have PermGen memory issues.)
       
    • (In Linux or Mac OS, if you have created a special user to run Tomcat, e.g., tomcat, remember to do the following steps as that user.)
       
    • If Tomcat is already running, shut down Tomcat with (in Linux or Mac OS) tomcat/bin/shutdown.sh
      or (in Windows) tomcat\bin\shutdown.bat

      On Linux, use ps -ef | grep tomcat before and after shutdown.sh to make sure the tomcat process has stopped. The process should be listed before the shutdown and eventually not listed after the shutdown. It may take a minute or two for ERDDAP to fully shut down. Be patient. Or if it looks like it won't stop on its own, use:
      kill -9 processID

    • Start Tomcat with (in Linux or Mac OS) tomcat/bin/startup.sh
      or (in Windows) tomcat\bin\startup.bat
       
  8. Is ERDDAP running?
    Use a browser to try to view http://www.YourServer.org/erddap/status.html
    ERDDAP starts up without any datasets loaded. Datasets are loaded in a background thread and so become available one-by-one.

    Trouble? Look in the log files.

    • When a request from a user comes in, it goes to Apache (on Linux and Mac OS computers), then Tomcat, then ERDDAP.
    • You can see what comes to Apache (and related errors) in the Apache log files.
    • You can see what comes to Tomcat (and related errors) in the Tomcat log files (tomcat/logs/catalina.out and other files in that directory).
    • You can see what comes to ERDDAP, diagnostic messages from ERDDAP, and error messages from ERDDAP, in the ERDDAP <bigParentDirectory>logs/log.txt file.
    • Tomcat doesn't start ERDDAP until Tomcat gets a request for ERDDAP. So you can see in the Tomcat log files if it started ERDDAP or if there is an error message related to that attempt.
    • When ERDDAP starts up, it renames the old ERDDAP log.txt file (logArchivedAtCurrentTime.txt) and creates a new log.txt file. So if the log.txt file is old, it is a sign that ERDDAP hasn't recently restarted. ERDDAP writes log info to a buffer and only writes the buffer to the log file periodically, but you can force ERDDAP to write the buffer to the log file by visiting .../erddap/status.html.

    Trouble: Old Version of Java
    If you are using a version of Java that is too old for ERDDAP, ERDDAP won't run and you will see an error message in Tomcat's log file like
    Exception in thread "main" java.lang.UnsupportedClassVersionError:
    some/class/name: Unsupported major.minor version someNumber

    The solution is to update to the most recent version of Java and make sure that Tomcat is using it.

    Trouble: Slow Startup First Time
    Tomcat has to do a lot of work the first time an application like ERDDAP is started; notably, it has to unpack the erddap.war file (which is like a .zip file). On some servers, the first attempt to view ERDDAP stalls (30 seconds?) until this work is finished. On other servers, the first attempt will fail immediately. But if you wait 30 seconds and try again, it will succeed if ERDDAP was installed correctly.
    There is no fix for this. This is simply how Tomcat works. But it only occurs the first time after you install a new version of ERDDAP.

  9. In the future, to shut down (and restart) ERDDAP, see
    How to Shut Down and Restart Tomcat and ERDDAP.
     
  10. Troubles installing Tomcat or ERDDAP?
    Email me at erd dot data at noaa dot gov . I will help you.
    Or, you can join the ERDDAP Google Group / Mailing List and post your question there.
     
  11. Email Notification of New Versions of ERDDAP
    If you want to receive an email whenever a new version of ERDDAP is available, send an email to erd dot data at noaa dot gov requesting to be added to the ERDDAP Announcements mailing list. This list averages roughly one email every three months.
     
  12. Customize your ERDDAP to highlight your organization (not NOAA ERD).
    • Change the banner that appears at the top of all ERDDAP .html pages by editing the <startBodyHtml5> tag in your datasets.xml file. (If there isn't one, copy the default from ERDDAP's
      [tomcat]/webapps/erddap/WEB-INF/classes/gov/noaa/pfel/erddap/util/messages.xml file into datasets.xml and edit it.) For example, you could:
      • Use a different image (i.e., your organization's logo).
      • Change the background color.
      • Change "ERDDAP" to "YourOrganization's ERDDAP"
      • Change "Easier access to scientific data" to "Easier access to YourOrganization's data".
      • Change the "Brought to you by" links to be links to your organization and funding sources.
    • Change the information on the left side of the home page by editing the <theShortDescriptionHtml> tag in your datasets.xml file. (If there isn't one, copy the default from ERDDAP's
      [tomcat]/webapps/erddap/WEB-INF/classes/gov/noaa/pfel/erddap/util/messages.xml file into datasets.xml and edit it.) For example, you could:
      • Describe what your organization and/or group does.
      • Describe what kind of data this ERDDAP has.
    • To change the icon that appears on browser tabs, put your organization's favicon.ico in tomcat/content/erddap/images/ . See https://en.wikipedia.org/wiki/Favicon (external link).

How To Do an Update of an Existing ERDDAP on Your Server

  1. Make the changes listed in Changes in the section entitled "Things ERDDAP Administrators Need to Know and Do" for all of the ERDDAP versions since the version you were using.
     
  2. If you are upgrading from ERDDAP version 2.18 or below, you need to switch to Java 17 and the related Tomcat 10. See the regular ERDDAP installation instructions for Java and Tomcat. You'll also have to copy your tomcat/content/erddap directory from your old Tomcat installation to your new Tomcat installation.
     
  3. Download erddap.war into tomcat/webapps .
    (version 2.22, 567,742,765 bytes, MD5=2B33354F633294213AE2AFDDCF4DA6D0, dated 2022-12-08)
     
  4. messages.xml
    • Common: If you are upgrading from ERDDAP version 1.46 (or above) and you just use the standard messages, the new standard messages.xml will be installed automatically (amongst the .class files via erddap.war).
       
    • Rare: If you are upgrading from ERDDAP version 1.44 (or below),
      you MUST delete the old messages.xml file:
      tomcat/content/erddap/messages.xml .
      The new standard messages.xml will be installed automatically (amongst the .class files via erddap.war).
       
    • Rare: If you always make changes to the standard messages.xml file (in place),
      you need to make those changes to the new messages.xml file (which is
      WEB-INF/classes/gov/noaa/pfel/erddap/util/messages.xml after erddap.war is decompressed by Tomcat).
       
    • Rare: If you maintain a custom messages.xml file in tomcat/content/erddap/,
      you need to figure out (via diff) what changes have been made to the default messages.xml (which are in the new erddap.war as
      WEB-INF/classes/gov/noaa/pfel/erddap/util/messages.xml) and modify your custom messages.xml file accordingly.
       
  5. Install the new ERDDAP in Tomcat:
    * Don't use Tomcat Manager. Sooner or later there will be PermGen memory issues. It is better to actually shutdown and startup Tomcat.
    * Replace references to tomcat below with the actual Tomcat directory on your computer.
     
    • For Linux and Macs:
      1. Shutdown Tomcat: From a command line, use: tomcat/bin/shutdown.sh
        And use ps -ef | grep tomcat to see if/when the process has been stopped. (It may take a minute or two.)
      2. Remove the decompressed ERDDAP installation: In tomcat/webapps, use
        rm -rf erddap
      3. Delete the old erddap.war file: In tomcat/webapps, use rm erddap.war
      4. Copy the new erddap.war file from the temporary directory to tomcat/webapps
      5. Restart Tomcat and ERDDAP: use tomcat/bin/startup.sh
      6. View ERDDAP in your browser to check that the restart succeeded.
        (Often, you have to try a few times and wait a minute before you see ERDDAP.)
         
    • For Windows:
      1. Shutdown Tomcat: From a command line, use: tomcat\bin\shutdown.bat
      2. Remove the decompressed ERDDAP installation: In tomcat/webapps, use
        del /S/Q erddap
      3. Delete the old erddap.war file: In tomcat\webapps, use del erddap.war
      4. Copy the new erddap.war file from the temporary directory to tomcat\webapps
      5. Restart Tomcat and ERDDAP: use tomcat\bin\startup.bat
      6. View ERDDAP in your browser to check that the restart succeeded.
        (Often, you have to try a few times and wait a minute before you see ERDDAP.)
Troubles updating ERDDAP?
Email me at erd dot data at noaa dot gov . I will help you.
Or, you can join the ERDDAP Google Group / Mailing List and post your question there.

Things You Need To Know

Things You Don't Need To Know

These are details that you don't need to know until a need arises.

Slide Shows

Here are some PowerPoint slide shows and documents that Bob Simons has created related to ERDDAP.

DISCLAIMER: The content and opinions expressed in these documents are Bob Simons' personal opinions and do not necessarily reflect any position of the Government or the National Oceanic and Atmospheric Administration.

The Four Main Documents:

Other Presentations:

Presentations By Other People:


 

Programmer's Guide

These are things that only a programmer who intends to work with ERDDAP's Java classes needs to know.

List of Changes

The List of Changes for each ERDDAP release is now on a separate web page.

Credits

ERDDAP is a product of the NOAA (external link) NMFS (external link) SWFSC ERD.

Bob Simons is the original and still the main author of ERDDAP (the designer and software developer who wrote the ERDDAP-specific code). The starting point was Roy Mendelssohn's (Bob's boss) suggestion that Bob turn his ConvertTable program (a small utility which converts tabular data from one format to another and which was largely code from Bob's pre-NOAA work that Bob re-licensed to be open source) into a web service.

It was and is Roy Mendelssohn's ideas about distributed data systems, his initial suggestion to Bob, and his ongoing support (including hardware, network, and other software support, and by freeing up Bob's time so he could spend more time on the ERDDAP code) that has made this project possible and enabled its growth.

The ERDDAP-specific code is licensed as copyrighted open source, with NOAA (external link) holding the copyright. See the ERDDAP license.
ERDDAP uses copyrighted open source, Apache, LGPL, MIT/X, Mozilla, and public domain libraries and data.
ERDDAP does not require any GPL code or commercial programs.

The bulk of the funding for work on ERDDAP has come from NOAA, in that it paid Bob Simons' salary. For the first year of ERDDAP, when he was a government contractor, funding came from the NOAA CoastWatch (external link) program, the NOAA IOOS (external link) program, and the now defunct Pacific Ocean Shelf Tracking (POST) program.

Much credit goes to the many ERDDAP administrators and users who have made suggestions and comments which have led to many improvements in ERDDAP. Many are mentioned by name in the List of Changes. Thank you all (named and unnamed) very much. Thus, ERDDAP is a great example of User-Driven Innovation (external link), where product innovation often comes from consumers (ERDDAP users), not just the producers (ERDDAP developers).

Here is the list of software and datasets that are in the ERDDAP distribution. We are very grateful for all of these. Thank you very much.
[Starting in 2021, it has become almost impossible to properly list all of the sources of code for ERDDAP because a few of the libraries we use (notably netcdf-java and especially AWS) in turn use many, many other libraries. All of the libraries that ERDDAP code calls directly are included below, as are many of the libraries that the other libraries call in turn. If you see that we have omitted a project below, please let us know so we can add the project below and give credit where credit is due.]

We are also very grateful for all of the software and websites that we use when developing ERDDAP, including
Chrome (external link),
curl (external link),
DuckDuckGo (external link),
EditPlus (external link),
FileZilla (external link).
GitHub (external link),
Google Search (external link),
PuTTY (external link),
stack overflow (external link),
todoist (external link),
Wikipedia (external link),
the Internet, the World Wide Web, and all the other, great, helpful websites.
Thank you very much.

License

The ERDDAP-specific code is licensed as copyrighted open source, with NOAA (external link) holding the copyright. The license is:
ERDDAP, Copyright 2022, NOAA.

PERMISSION TO USE, COPY, MODIFY, AND DISTRIBUTE THIS SOFTWARE AND ITS DOCUMENTATION FOR ANY PURPOSE AND WITHOUT FEE IS HEREBY GRANTED, PROVIDED THAT THE ABOVE COPYRIGHT NOTICE APPEAR IN ALL COPIES, THAT BOTH THE COPYRIGHT NOTICE AND THIS PERMISSION NOTICE APPEAR IN SUPPORTING DOCUMENTATION, AND THAT REDISTRIBUTIONS OF MODIFIED FORMS OF THE SOURCE OR BINARY CODE CARRY PROMINENT NOTICES STATING THAT THE ORIGINAL CODE WAS CHANGED AND THE DATE OF THE CHANGE. THIS SOFTWARE IS PROVIDED "AS IS" WITHOUT EXPRESS OR IMPLIED WARRANTY.

Contact

Questions, comments, suggestions? Please send an email to erd dot data at noaa dot gov and include the ERDDAP URL directly related to your question or comment.

Or, you can join the ERDDAP Google Group / Mailing List by visiting https://groups.google.com/forum/#!forum/erddap (external link) and clicking on "Apply for membership". Once you are a member, you can post your question there or search to see if the question has already been asked and answered.
 


ERDDAP, Version 2.22
Disclaimers | Privacy Policy