Note: These features are only available to select people who oversee the OED site (called admins) so these features are 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.
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 beginning of the WSL page has details on WSL and Docker installation on Windows 10/11 Home.
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.
Follow these steps to install a production (OED site for an organization) site:
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
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
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.
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.
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:
services: -> database: -> environment:) to a site specific password instead of the
pleaseChangethat 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:
services: -> web: -> environment:) to
yesso it becomes:
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:
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).
services: -> web: -> environment:
secure-smtpto use an SMTP server or
noneif 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_SMTP=smtp.example.comwhere example.com would become the domain for your organization or one could use
OED_MAIL_SMTP=smtp.gmail.comfor Google Mail.
OED_MAIL_SMTP_PORT=465for the standard SSL connection port.
firstname.lastname@example.org the user name email for sending mail.
credentialwith 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_FROMemail@example.com the desired email address is used.
firstname.lastname@example.org the desired email. It can be the same as the SMTP email above or something different.
My Organization Namewith whatever name is desired.
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 | > email@example.com 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 3000then 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.
oed.myinstition.orgwhere 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 help 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
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 help 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.
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.
pwdand the output will tell the directory path.
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.
cp src/scripts/sendLogEmailCron.bash /etc/cron.daily/sendLogEmailCron.bash
chmod +x /etc/cron.daily/sendLogEmailCron.bashto make the script executable.
Set up the daily cron job to aggregate the daily readings needed for the fast data access OED does to the database.
cp src/scripts/refreshReadingViewsCron.bash /etc/cron.daily/refreshReadingViewsCron.bash
chmod +x /etc/cron.daily/refreshReadingViewsCron.bashto make the script executable.
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.
cp src/scripts/refreshHourlyReadingViewsCron.bash /etc/cron.hourly/refreshHourlyReadingViewsCron.bash
chmod +x /etc/cron.hourly/refreshHourlyReadingViewsCron.bashto make the script executable.
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.
cp src/scripts/oed.service /etc/systemd/system/oed.service
systemctl enable oed.serviceto make the service start on server boot.
systemctl start oed.service. Stop the app at any time by doing:
systemctl stop oed.servicebut note it will restart on the next reboot unless this service is disabled with:
systemctl disable oed.service.
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.
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.
docker logs <CONTAINER ID> | morewhere <CONTAINER ID> is replaced with the value from the previous step.
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.
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:
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.