OED Documentation

Installation Directions

Version V1.0.0

Documentation overview

These features are only available to select people who oversee the OED site (called admins) so this information is not usually of interest to a general user.

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

Requirements

OED uses Unix, including Linux, features to work and run Docker. Most sites have servers running Unix/Linux and can directly run OED. MacOS is based on Unix and Docker can be installed directly as an application. Windows from Microsoft 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 the system is at that level of Windows. If one has Windows 10/11 Professional, Enterprise or Education, one 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 one has Windows 10/11 Home then one can use WSL 2 to enable Linux and then install Docker. Once Docker is installed and working, one 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 isolated 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. One will need Docker version 19.03 or higher (since July 2019) but that should not be an issue if running 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 one 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 the server is set up to respond to web requests (port 80) and that port 3000 is allowed (unless the default OED port is changed). 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 an organization.

This guide requires that one 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, one can use Terminal.app (the default), iTerm2, or any other terminal program.
  • On Linux, the distribution will provide a terminal; it can generally be opened with Ctrl+Shift+T or by searching for "Terminal" in the application menu.

Installation

Follow these steps to install a production (OED site for an organization) site:

  1. Clone the desired OED code from Github. Note if the directory is left off in the next step then the OED code will be placed in the current directory in the subdirectory OED. If "." is used for the directory (just a period without the quotes) then the OED software will be placed directly into the current directory without a subdirectory. The OED software can be placed anywhere desired but the terminal should be using the desired directory before beginning the clone of the OED software.

    • If a specific released version of OED is desired (this is most common) then do: git clone --branch <tag_name> https://github.com/OpenEnergyDashboard/OED.git [directory]. The officially released and tagged versions at the OED GitHub release page list all OED releases. In general, a site 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 v1.0.0 in the subdirectory OED of the current directory do: git clone --branch v1.0.0 https://github.com/OpenEnergyDashboard/OED.git. After this there should be the directory OED where the clone was done.
    • If a site wants the latest version from development then do: git clone https://github.com/OpenEnergyDashboard/OED.git [directory]. Note this will likely be code that has not yet gone through complete testing as done for an official release version but will have the latest OED code base. In general, production sites do not use this code.
  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.

  3. Edit docker-compose.yml. Note that for values with an = one 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: -> database: -> environment:) to a site specific password instead of the pleaseChange that is provided. Keep it secret but it should never need to known unless one wants 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 it should never need to known. It will be: - OED_TOKEN_SECRET=whateverTokenYouChoose
    4. The port (in services: -> web: -> ports:) for mapping from host to container; e.g., to host on the server's port 80, set it to 80:3000. This assumes the site wants to serve OED up on the standard web port. There are multiple lines here and some are commented out (begin with #). Before editing 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 the site wants to have standard web requests (port 80) serve up OED then edit to look like (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 the line - "3000:3000" is uncommented and the line - "9229:9229" is commented out then OED will server up on port 3000 (where the line - "80:3000" is commented out).

    5. Later in these directions, it is suggested to set up a cron job to send an email to someone each day with any issues the OED installation encountered. No email is sent unless an issue is encountered. For this to work, OED needs to have access to a mail system (SMTP server) to send the mail. This is done by setting 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 an SMTP server or none if the site is 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 for sending mail. For example, it could be OED_MAIL_SMTP=smtp.example.com where example.com would become the domain for your organization or one could use OED_MAIL_SMTP=smtp.gmail.com for Google Mail.
      • OED_MAIL_SMTP_PORT gives the port number of the SMTP server for sending mail. 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 the user name email for sending mail.
      • 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 given a token for the credential (an app password for mail for Google has been tested and it works).
      • OED_MAIL_FROM gives 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 the desired email address is used.
      • 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 is desired.
  4. For the remaining steps one needs to be the superuser/root to have sufficient permission to modify system files. Some OS setups allow the install step (next) without being the superuser but it is generally safer not to try.
  5. Make sure the terminal is in the root OED directory (where the README.md file is located).
  6. Install OED on the server by doing 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 the server. The terminal will display a lot of output about installing the database (Postgres), getting needed packages (this can take a while so during this process there may not be more output for a while; this normally happens right after the "database system is ready to accept connections" output line) and starting up the web system (this can take a while so during this process there may not be more output for a while; this normally happens right after the "webpack build --node-env production" output line). Future builds will go much faster. When the terminal displays the lines:
    oed-web-1       | webpack 5.76.0 compiled successfully in 200210 ms
oed-web-1       | OED install finished
oed-web-1       | Starting OED in production mode
oed-web-1       | 
oed-web-1       | > open-energy-dashboard@1.0.0 start
oed-web-1       | > node ./src/bin/www
oed-web-1       | 
oed-web-1       | [INFO@2023-10-20T11:22:35.803-05:00] Listening on port 3000
    then OED should be ready to accept web requests. If there was an error in the output then OED might not be running properly. Please contact the OED project if there are questions where sending the terminal text is generally very helpful.

The typical output of the install is available.

  1. A web browser can now be used to check that OED is properly serving up web pages. Use the web address oed.myinstition.org where oed.myinstition.org is replaced with the name of the server where OED is installed. If all is working properly, the main OED page (see Home Navigation documentation page for an image of what it will look like). The page won't be able to graph any data until the site has OED acquire meter data. If the mapping of 80:3000 was not done above, then OED would be reachable at oed.myinstition.org:3000.
  2. The site now needs to create an admin user to log into OED on the website. To do this, a second terminal is opened, go to the root OED directory and become a superuser/root user (as has been done). This is done so OED remains running in the first terminal to add the user. Run the script with: docker compose run web npm run createUser. The code will prompt 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 desired to use with this email to login into OED (passwords must be at least 8 characters long). It is important to remember this email & password to access with OED admin features on the web pages. Run the command docker compose run web npm run editUser to change the password if forgotten or to 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 is typed so this information will be in the terminal. This terminal shouldn't be needed any more so it can be closed to hide the information or usually type clear to remove it from what is shown in the terminal.

    Now log in on the OED web page to make sure this account works. The options menu documentation is available but basically just click the "Log in" choice in the top, right of the OED website under "Options" and then enter the information.

  3. Shut down OED. Soon OED will be set up to run as a service so the OED currently running in the terminal should be shut down. In the terminal where OED was started (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.
  4. The following steps require knowledge of the root directory path of OED. In the terminal located in the OED root directory do: pwd and the output will tell the directory path.

  5. Set up the daily cron job to email the OED admin with any issues that occurred in the past day. It is 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.

  6. 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.

  7. 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 the site wants 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 preferred, the site 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. However, sites generally do not have issues with doing this every hour so it is normally done.

    1. In the root OED directory do (this assumes the site updates 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.

  8. Set up the service so OED runs regularly on the server. There is a chance that the server version of Unix requires a modification of these steps. These steps should work on a Red Hat/Centos Unix. The "User" needed to set below is the one assigned to OED. It is the one logged into the terminal before becoming superuser/root and (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 the site wants 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 this service is disabled 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 whenever the service is started 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 one wants to check this is all set up correctly then restart the server and check it is still serving up web pages (as described above).
  9. Sometimes one wants to see the output of OED when it is running as a service. This can be useful during the install to see why OED did not come up. 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 <CONTAINER ID> is replaced with the value from the previous step.

OED upgrades

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

Admin setup

The designated admin can use the login created above to set the desired features and items of OED. The following may be desired where the links can be used to get more information:

  • Site preferences. Allows for setting of the site name, default actions on the graphic pages, creating other users, and certain limits among other things.
  • data acquisition. Discusses getting meter data into OED so the site can display data.
  • Standard units and conversions. Discusses the units and conversions provided by OED and making more of them visible to the user.
  • Users. To create additional user logins and manage them.
  • Admin features. Discusses the range of actions that admins can take and the related documentation pages. There are many OED features other than the ones linked directly above.

Other information

Though less likely, one may want to consult:

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 an up-to-date node_modules directory in the root OED directory) and skips doing it again to save time. However, a site 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 doing this since it will break the application. Redoing the OED install with docker compose up will recreate this directory.