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.
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 beginning of the WSL page has details on WSL and Docker installation on Windows 10 Home.
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.
Follow these steps to install a production (OED site for you institution) site:
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.
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.
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.
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:
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
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 you should never
need to know this value. It will be:
- OED_TOKEN_SECRET=whateverTokenYouChoose
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).
services: -> web: -> environment:
OED_MAIL_METHOD=gmail
or OED_MAIL_METHOD=mailgun
.
someone@example.com
with your user name email.
credential
with that password. Note this setup cannot accommodate two factor
authentication (2FA).
OED_MAIL_FROM=mydomain@example.com
where you use the
desired email address.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
you
want.services: -> web: -> environment:
) to what will be used so you replace
pleaseChange
with what you want.
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:
web_1 | + 1836 hidden modules web_1 | OED install finished web_1 | Starting OED in production mode web_1 | web_1 | > Open-Energy-Dashboard@0.7.0 start web_1 | > node ./src/bin/www web_1 | web_1 | [INFO@2021-09-23T20:52:14.190Z] Listening on port 3000then 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.
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
.
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 existswhere 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.
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 you the directory path.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.
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 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.
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
you
disable this service with: systemctl disable oed.service
.
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.
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 you replace <CONTAINER ID> with the one
you want from the previous step.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.
Though less likely, you 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 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.