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
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.
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.
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:
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
services: -> web: -> environment:
) to yes
so
it becomes: - OED_PRODUCTION=yes
.
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
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-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=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=465
for the standard SSL connection port.someone@example.com
with the user name email for sending mail.
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=mydomain@example.com
where the
desired email address is used.someone@example.com
with the desired email. It can be the same as the SMTP
email above or something different.
My Organization Name
with
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 | > 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 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.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
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
oed.myinstition.org:3000
.
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.pwd
and 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.bash
to 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.bash
to 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.bash
to 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.service
to make the service start on server boot.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
.
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> | more
where <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.