The following steps should get you ready to contribute to OED in a fairly short period of time. Please know that
we are here to help you so use the link at the bottom of the page to email us with any issues.
First, we strongly encourage you to contact us as a
potential developer. That way we know about you and can help you select tasks that will be interesting to
you and also benefit the project.
The OED project resides on GitHub so you need a
login to contribute to the
OED uses the fork model for development. (There are many descriptions of this process on the web but GitHub
ones include a general
one and one with more operational
This means you need to go to the main OED GitHub page (after login
to GitHub), fork the
project onto your own GitHub account and then clone the forked copy onto you own development machine to work
code base. You can place the clone anywhere you want on your machine. Note the clone will place all the
files inside a new directory named OED. This model has the advantage that you
can commit and push to your account without needing write
permission on the main OED project repository. There are separate directions of the
steps for creating a
pull request to integrate your code into OED.
OED uses the Docker container system to run the software so you need to download and install
Docker. (You need both Docker and docker-compose but you generally get those together during the
has the advantage that our configuration
files for Docker can get any needed software and also means we do not modify your normal system since the
setup is in a separate container that does not impact other programs on your computer. Note that Docker
should run on all OSes (Linux, Mac OS X, Windows - see below for information on using Docker with WSL on
Windows) so you should be able to use it.
You will want to install your forked/cloned copy of OED on your development machine. While there is further
information on more advanced options for doing this, the initial install can be done by following
Open a terminal on your computer (it is the "command prompt" on some Windows systems).
In the terminal do the following:
cd "directory with cloned OED" You need to replace "directory with cloned
of the cloned copy of OED. This is where the "README.md" and other main OED files are
Some people find it easiest to locate that directory using the file
manager on their OS and then use that information to get to the needed directory. As an
might do cd /home/username/projects/OED if you cloned OED in the
docker-compose up This will run the entire OED install process. Note that on
some systems (mostly some Linux systems), depending on how you installed Docker, you may get
permission error so you will need to do: sudo docker-compose up which
the process with root privileges. If this is
the case then you need to do sudo before all docker commands on your system.
Depending on the speed of your machine and internet
connection, this can take a few to ten minutes. It should go faster after the first install
you follow the developer details elsewhere. You will see a lot
output about installing
the database (Postgres), getting needed packages (this can take a while so you may
output for a while) and starting up the web system. When you see the
+ 2073 hidden modules
where the actual number will likely be different then OED should be running normally unless
there was an error in the output.
If you have any issues please copy all the output from your terminal and email it to us. We will look it over
get back to you. We try to do that quickly.
Open a web browser. It should not matter which one you use. (Some developers prefer to work with
Chrome when debugging code due to their debugging tools but other web browsers have good tools.)
Enter the address: localhost:3000 and load the page. "localhost" indicates the page is being
served up from your machine and "3000" is the default port that OED uses to accept web connections.
If all went well, you will see the main OED web page that looks something like:
If you see that then the basic OED install worked and your system is properly serving up the OED web
Though not common, it is possible for the OED web system to run without starting the underlying
database system. To verify that the database is running properly, you should log into OED as the
admin. The username and password were shown during the install process. By default they are:
Yes, the password really is password but remember it is running on your local machine in a container
so it should not be accessible to others. Test by clicking on the "Log in" button in the top, right
corner of the main OED page. This will take you to the login page where you enter the admin
credentials and click "Submit". If it works you will have another button in the top, right of the
page for the "Admin
Panel". If it fails you should see a message appear briefly in the top, right corner of the page. If
this happens, please follow the steps above to email us the output in
If all went well, you now have a fully running development version of OED that can be used to begin
When you install OED, it does not have any data. An actual site would connect up meters to gather data. For
a developer, we have standard test data you can use. The OED test data page has
information and directions for doing this. We suggest you load up the data now so you can try any features
you want in OED. Note that an advantage of this test data is that it is the same for all developers so
people should be able to reproduce what you mention if you have a question or issue.
You will want a coding environment to work on the OED code. We do not care what you use but note that many
developers use Visual Studio Code
that is freely available for all OSes.
OED uses a number of technologies. You may want further information on these and some are provided on the OED technologies page. We welcome your input on other areas you
to know about or other resources you find valuable. Note that you can work on parts of OED without knowing
many of the technologies in any depth. For example, you can work on database queries without knowing about
the front-end. Thus, many developers begin in areas they know or want to learn first and focus on that
understanding of that is usually needed to get started.
There are two areas on our GitHub repo that are worth noting. First, the discussion
board has several areas
including one for developers. You are encouraged to subscribe to this discussion by clicking the button on
the right side of the page with this discussion group. Second, the projects have
an overview of the status
of work and major initiatives.