This describes the installation of an OED site for production use. If you are a developer, you likely want to follow the directions on the getting started page.

Requirements

OED uses Unix, including Linux, features to work. Mac-OS X is based on Unix and Docker can be installed directly as an application. Windows OS is not based on Unix so other steps are necessary. Given that Windows 10+ is generally needed to install OED and the fact that most systems run at least Windows 10, these directions assume your system is at that level of Windows (and use the OS name Windows 10). If you have Windows 10 Professional, Enterprise or Education, you should be able to directly install Docker via the Hyper-V though it may need to be enabled (this has not been tested by OED). If you have Windows 10 Home then you can use WSL 2 to enable Linux and then install Docker. Once you have Docker installed and working, you can follow the direction given here since they only depend on Docker/docker compose. The developer getting started page has details on WSL and Docker installation.

OED is installed using the Docker containerization tool. This allows it to be segregated from the rest of the system, and makes updates easier to perform, since the dependencies are all taken care of through the container definitions. Under Docker, OED is installed and administered using the docker compose command. (Note more recent versions of Docker have the docker compose command so you no longer need docker-compose. If your Docker does not support this (likely see an error with docker compose of "docker: 'compose' is not a docker command.") then you need to install docker-compose and replace all the docker compose commands with docker-compose.) You will need Docker version 18.06 CE or higher but that should not be an issue if you have any reasonably up-to-date version. Some versions of Linux already have Docker or it can be installed. Docker for MacOS is an app that can easily be installed. For Windows 10 Home you can see the link on the WSL page given in the previous step. General Docker installation information is available from Docker.

It is assumed that your server is set up to respond to web requests (port 80) and that port 3000 is allowed (unless you change the default OED port). It is also assumed the server can access the internet for the installation.

These directions assume someone with root access to the server where OED is being installed and a working knowledge of doing Unix shell commands including editing text files. This is generally someone within the IT department of your organization.

This guide requires that you enter some commands into an operating system shell, or terminal.

• On Windows, this is the terminal that connects to the Linux running under WSL.
• On MacOS, you can use Terminal.app (the default), iTerm2, or any other terminal program.
• On Linux, your distribution will provide a terminal; it can generally be opened with Ctrl+Shift+T or by searching for "Terminal" in your application menu.

Installation

Follow these steps to install a production (OED site for you institution) site:

1. Clone the desired OED code from Github. Note if you leave off directory in the next step then the OED code will be placed in the current directory in the subdirectory OED. If you use "." for the directory (just a period without the quotes) then the OED software will be placed directly into the current directory without a subdirectory. You can place the OED software anywhere you want but be sure to be in the desired directory before you begin the clone.

   • If you want a specific released version of OED (this is most common) then do: git clone --branch <tag_name> https://github.com/OpenEnergyDashboard/OED.git [directory]. You can find the officially released and tagged versions at the OED GitHub release page. In general, you should take the latest release (at the top of the page). Note that the clone will not include git history (with detached head) but that should not be needed in a production environment. For example, to get release v0.7.0 in the subdirectory OED of the current directory do: git clone --branch v0.7.0 https://github.com/OpenEnergyDashboard/OED.git. After this you should see the directory OED where you did the clone.
   • If you want the latest version from development then do: git clone https://github.com/OpenEnergyDashboard/OED.git [directory]. Note this will likely be code that has yet gone through complete testing as done for an official release version but will have the latest OED code base.
2. cd into the directory that has the cloned version of OED. This is known as the root directory of OED. It has a README.md file and others. What follows assumes you are in the root directory of OED (as is the default when you clone).

3. Edit docker-compose.yml. Note that for values with an = you should not put spaces before or after the equal sign as is shown in the sample value. The edits are:

   1. POSTGRES_PASSWORD (under services: -> datebase: -> environment:) to a site specific password instead of the pleaseChange that is provided. Keep it secret but you should never need to know this value unless you want to access the PostgreSQL database outside of the docker container. It will be: - POSTGRES_PASSWORD=whateverPasswordYouChoose
   2. OED_PRODUCTION (under services: -> web: -> environment:) to yes so it becomes: - OED_PRODUCTION=yes.
   3. OED_TOKEN_SECRET (under services: -> web: -> environment:) to a random value instead of the ? that is provided. Keep it secret but you should never need to know this value. It will be: - OED_TOKEN_SECRET=whateverTokenYouChoose
   4. The port (in services: -> web: -> ports:) to a mapping from host to container; e.g., to host on your computer's port 80, set it to 80:3000. This assumes you want to serve OED up on the standard web port. There are multiple lines here and some are commented out (begin with #). Before you edit it should look like:

      
          ports:
              - "3000:3000" # Should be commented out if you uncomment 80:3000 below.
              - "9229:9229" # Debug port, should be commented out for production
              # For production you might want something like:
              # - "80:3000"
              # and comment out the debug port and 3000:3000 line above
                 

      If you want to have standard web requests (port 80) serve up OED then edit to look like (you comment out the debug port because it is not normally used in production):

      
          ports:
              # - "3000:3000" # Should be commented out if you uncomment 80:3000 below.
              # - "9229:9229" # Debug port, should be commented out for production
              # For production you might want something like:
              - "80:3000"
              # and comment out the debug port and 3000:3000 line above
                       

      It is possible to use a different port. For example, if you leave the line - "3000:3000" uncommented and comment out - "9229:9229" then OED will server up on port 3000 (where you leave the - "80:3000" line commented out).

   5. OED_SITE_READING_RATE (under services: -> web: -> environment:) might need to be updated. This represents the typical rate that meters at your site provide data. This impacts when OED switches from daily to hourly to original meter data when doing line graphics. The default value is 00:15:00 meaning the meter data is expected every 15 minutes. If the value is roughly right then there should be no issues. Note you do not change OED_TEST_SITE_READING_RATE as that is used internally for the automated tests in OED. More information is available on the help pages.
   6. Later in these directions, it is suggested you set up a cron job to send an email to someone each day with any issues the OED installation encountered. For this to work, OED needs to have access to a mail system (SMTP server) to send the mail. To do this you need to set these environment values under services: -> web: -> environment:
      • OED_MAIL_METHOD gives the way email is sent (SMTP). As the comment says this can be secure-smtp to use your SMTP server or none if you are not going to have OED send mail alerts. OED only supports sending mail via secure channels. Note that the SMTP listed here does not have to relate to the mail recipient. In the end, this usually becomes OED_MAIL_METHOD=secure-smtp.
      • OED_MAIL_SMTP gives the web address of the SMTP server you are using. For example, it could be OED_MAIL_SMTP=smtp.example.com where example.com would become the domain for your organization or you could use OED_MAIL_SMTP=smtp.gmail.com for Google Mail.
      • OED_MAIL_SMTP_PORT gives the port number of the SMTP server you are using. For example, it is often OED_MAIL_SMTP_PORT=465 for the standard SSL connection port.
      • OED_MAIL_IDENT gives the user name on the SMTP server where the mail will be sent. Replace someone@example.com with your user name email.
      • OED_MAIL_CREDENTIAL gives the password for the SMTP user in OED_MAIL_IDENT. Replace credential with that password. Note this setup cannot accommodate two factor authentication (2FA) unless you have access to a token for the credential (an app password for mail for Google has been tested and it works).
      • OED_MAIL_FROM give the email address that the mail will be from. This is often the same as the OED_MAIL_IDENT so it might be OED_MAIL_FROM=mydomain@example.com where you use the desired email address.
      • OED_MAIL_TO gives the email address of who will get the emails. Replace someone@example.com with the desired email. It can be the same as the SMTP email above or something different.
      • OED_MAIL_ORG gives the organization name that will be part of the subject of the email sent. This may be important in recognizing the email, esp. if the person receiving it gets email from multiple OED sites (not common). Replace My Organization Name with whatever name you want.
4. For the remaining steps you need to be the superuser/root to have sufficient permission to modify system files. On some OS setups you can do the install step (next) without being the superuser but it is generally safer to not to try.
5. Make sure you are in the root OED directory (where the README.md file is located).
6. Install OED on the server by doing docker compose up. (On older versions of Docker you must do docker-compose up.) This will get all the needed software including Postgres, all node packages and then installs all the needed software. This can take from a minute to 10+ minutes depending on the speed of your server. You will see a lot of output about installing the database (Postgres), getting needed packages (this can take a while so you may not see output for a while normally happening right after the " database system is ready to accept connections" output line) and starting up the web system. When you see the lines:

   oed-web-1       | <s> [webpack.Progress] 100% 
   oed-web-1       | 
   oed-web-1       | ℹ ｢atl｣: Time: 24033ms    
               

   then OED should be ready to accept web requests, where the actual number of hidden modules will likely be different. Note is says is is listening on port 3000 since that is what OED listens on but the ports: changes you made above mean the web requests to port 80 (or whatever you chose) will be sent on to port 3000 for OED. If there was an error in the output then OED might not be running properly. Please contact the OED project if you have questions where sending the terminal text is generally very helpful.

   If you quickly get the error Invalid interpolation format for "command" option in service "web": "${install_args:-}" then it is likely you are running an older version of docker-compose (less than version 2). You can fix this error by editing the docker-compose.yml file (as you did above). At the end of the file you will see (Note OED v0.7.0 and earlier does not have the last three lines to deal with older versions of docker compose so you will need to add them during your edits. It also has the reverse proxy line comment that has since been removed.):

                   # Lets docker-compose up work right
                   # If environment variable install_args is not set the it becomes blank without warning user.
                   command: ["bash", "./src/scripts/installOED.sh", "${install_args:-}"]
                   # Use this if you are using a docker-compose that is earlier than version 2 and comment out the one above.
                   # command: ["bash", "./src/scripts/installOED.sh"]
               

   Edit this to be:

                   # Lets docker-compose up work right
                   # If environment variable install_args is not set the it becomes blank without warning user.
                   # command: ["bash", "./src/scripts/installOED.sh", "${install_args:-}"]
                   # Use this if you are using a docker-compose that is earlier than version 2 and comment out the one above.
                   command: ["bash", "./src/scripts/installOED.sh"]
               

   If you redo the docker compose up then you should now get the expected output described above.

   The typical output of the install is available.

7. You can now use a web browser to check that OED is properly serving up web pages. Use the web address oed.myinstition.org where you replace oed.myinstition.org with the name of the server where you installed OED. If all is working properly you will see the main OED page (see Graph Type help page for an image of what it will look like). You won't be able to graph any data until you have OED acquire meter data. If you did not do the mapping of 80:3000 above, then OED would be reachable at oed.myinstition.org:3000.
8. You now need to create an admin user so you can log into OED on the website. To do this you will need a second terminal where you go to the root OED directory and are a superuser/root (as you have been). This is done so you don't have to shut down OED to add the user. Run the script with: docker compose run web npm run createUser. The code will prompt you to enter an email address and password:

   # docker compose run web npm run createUser
   Starting checkoed_database_1 ... done
   
   > Open-Energy-Dashboard@0.6.0 createUser
   > node ./src/server/services/user/createUser.js
   
   Email of user to create: someEmail@yourInstitution.org
   Password: passwordYouChoose
   [INFO@2021-10-13T21:40:31.853Z] User created or already exists
               

   where you replace someEmail@yourInstitution.org with any email (it does not have to be an active one) and passwordYouChoose with the password you want to use with this email to login to OED (passwords must be at least 8 characters long). It is important to remember this email & password so you have access to OED admin features on the web pages. You can run the command docker compose run web npm run editUser to change the password if you forget it or you can create a new user. Note an OED admin user can create more users on the site so this is normally a one-time step.

   Note that OED echos what you type so this information will be in the terminal. You shouldn't need this terminal any more so you can close it to hide the information or usually type clear to remove it from what is shown in the terminal.

   You should now log in to make sure this account works. Logging in directions are available but basically you click the "Log in" button in the top, right of the OED website and then enter the information.

9. Shut down OED. You will soon be setting up OED to run as a service so you want to stop the one running in the terminal. In the terminal where you started OED (with docker compose up), do "^c" to shut down OED. Be a little patient since doing a second "^c" will cause a rapid stop of docker without the normal cleanup.
10. In the following steps you need to know the root directory of OED. In the terminal where you are in the OED root directory do: pwd and the output will tell you the directory path.

11. Set up the daily cron job to email the OED admin with any issues that occurred in the past day. You are not required to do this but it is a very good idea. It gives someone a daily email of any issue so they are not missed. See above about needed values in docker-compose.yml to support sending emails.

    1. In the root OED directory do: cp src/scripts/sendLogEmailCron.bash /etc/cron.daily/sendLogEmailCron.bash
    2. Edit /etc/cron.daily/sendLogEmailCron.bash to make the necessary modifications to the script. See the script for more detail.
    3. Do: chmod +x /etc/cron.daily/sendLogEmailCron.bash to make the script executable.

12. Set up the daily cron job to aggregate the daily readings needed for the fast data access OED does to the database.

    1. In the root OED directory do: cp src/scripts/refreshReadingViewsCron.bash /etc/cron.daily/refreshReadingViewsCron.bash
    2. Edit /etc/cron.daily/refreshReadingViewsCron.bash to make the necessary modifications to the script. See the script for more detail.
    3. Do: chmod +x /etc/cron.daily/refreshReadingViewsCron.bash to make the script executable.

13. Set up the cron job to aggregate the hourly readings needed for the fast data access OED does to the database when zoomed in on data. The site can choose how frequently to do this. If you want to see the latest meter data quickly then this should be done hourly. Note the update takes a modest amount of CPU and can delay when users see data. If you prefer, you could run the script daily just before running the daily updates. This would mean the new hourly data would only become visible after the day completes.

    1. In the root OED directory do (this assumes you do the update every hour): cp src/scripts/refreshHourlyReadingViewsCron.bash /etc/cron.hourly/refreshHourlyReadingViewsCron.bash
    2. Edit /etc/cron.daily/refreshHourlyReadingViewsCron.bash to make the necessary modifications to the script. See the script for more detail but it should be the same as the daily script changes.
    3. Do: chmod +x /etc/cron.hourly/refreshHourlyReadingViewsCron.bash to make the script executable.

14. Set up the service so OED runs regularly on your system. There is a chance that your version of Unix requires a modification of these steps. These steps should work on a Red Hat/Centos Unix. The "User" you need to set below is the one assigned to OED, the one you logged in as before becoming superuser/root or (hopefully not) the superuser/root.

    1. In the root OED directory do: cp src/scripts/oed.service /etc/systemd/system/oed.service
    2. Edit /etc/systemd/system/oed.service to make the necessary modifications to the script. See the script for more detail.
    3. Do: systemctl enable oed.service to make the service start on server boot.
    4. Assuming you want to start OED at this time do: systemctl start oed.service. Stop the app at any time by doing: systemctl stop oed.service but note it will restart on the next reboot unless you disable this service with: systemctl disable oed.service.
    5. To check the status of the OED service do: systemctl list-units --type=service | grep -i oed. Note that OED needs to reinstall/restart when you start the service again so it will take a little while from the time this lists the service as loaded and active running until it is ready to serve up web pages.
    6. If you want to check this is all set up correctly then restart the server and check it is still serving up web pages (as described above).
15. Sometimes you want to see the output of OED when it is running as a service. This can be useful during the install if you want to see why OED did not come up. You do this by:
    1. Get the container ID by using: docker ps -a. The CONTAINER ID will be the one with the IMAGE of ...oed_web (where there may be some name in the ...) for the install/web output and IMAGE of ...oed_database for any database output.
    2. docker logs <CONTAINER ID> | more where you replace <CONTAINER ID> with the one you want from the previous step.
16. You will want to get meter data into OED so the site can display data. See the data acquisition page for more information on doing this.

OED upgrades

The OED project is regularly improving the code and releasing new versions of OED. To get the latest features, you will probably want to upgrade OED over time. Information on officially released and tagged versions is given on the OED GitHub release page. If you see a newer version that you want to upgrade to then consult the directions on the OED Upgrading page.

Other information

Though less likely, you may want to consult:

• Environment variable page about all the OED environment variables.
• NPM script page about the available scripts to support the OED setup.

It is rare that the node/npm installation is not okay in a production environment. The OED installation detects if the node install already happened (because there is a node_modules directory in the root OED directory) and skips doing it again to save time. However you can force OED to do the node install by going to the root OED directory and deleting the node_modules directory with: rm -rf node_modules/. Make sure OED is not running (see stopping the service above) before you do this since it will break the application. Redoing the OED install with docker compose up will recreate this directory.