Skip to content

Setting up a development Environment

Jump to bottom
Adam Hooper edited this page Aug 10, 2015 · 86 revisions

You need to be comfortable with command-line tools and setting up environment variables.

For the hasty

  1. Install PostgreSQL, a Java 8 Development Kit and Git. Optionally, install LibreOffice.
  2. git clone https://github.com/overview/overview-server.git
  3. cd overview-server
  4. ./dev

That last command will take a long time -- maybe an hour as it downloads and compiles all required components. When the text stops, it's ready.

Too quick? Let's break it down

Prerequisites

  1. Install PostgreSQL. For Mac users we recommend Postgres.app
  2. Install a Java Development Kit.
  3. Install Git.
  4. (optionally) Install LibreOffice.
  5. (On Linux) Install build tools: build-essential on Ubuntu, make and gcc on Fedora, etc.
  6. git clone https://github.com/overview/overview-server.git

Lost? Here's some guidance for the tricky bits:

Installing Postgresql

Install PostgreSQL. Don't worry about starting, stopping, files or permissions: Overview handles that by running its own instance (on port 9010) in its own directory (overview-server/database/).

  • On Windows, we support EnterpriseDB if you install it in the default location.
  • On Mac OS X, we recommend Postgres.app: install it, run it once, shut it down and you'll be done. We also support HomeBrew installation: brew install postgres.
  • On Debian/Ubuntu, sudo apt-get install postgresql.
  • On Fedora, su -c "dnf install postgresql-server"
  • On anything else, try the generic instructions. Overview will run if initdb and postgres are in your PATH.

Installing Java

You need to install a JDK to compile Overview's source code. It needs to be Java 8 or higher.

  • On Mac OS X and Windows, install from the Java SE download page. The "x64" versions are better for Overview; only install "x32" if you know "x64" won't work.

  • On Ubuntu:

         sudo add-apt-repository ppa:openjdk-r/ppa
     sudo apt-get update
     sudo apt-get install openjdk-8-jdk

  • On Fedora, su -c "dnf install java-1.8.0-openjdk-devel"

Installing Git

You can follow the directions at https://help.github.com/articles/set-up-git, which provide native apps for Mac OS X and Windows.

Installing LibreOffice

LibreOffice will help Overview parse several document formats, such as Microsoft Word .doc and .docx files.

  • On Ubuntu, sudo apt-get install libreoffice
  • On Fedora, sudo dnf install libreoffice
  • On Mac OS X or Windows, download and install the official version.
    • Find the location of the installed program called soffice
    • Set an environment variable LIBRE_OFFICE_PATH to the location of soffice. For example:

export LIBRE_OFFICE_PATH=/Applications/LibreOffice.app/Contents/MacOS/soffice

Launching Overview on your development machine

Run this in a terminal from the overview-server directory:

./dev

The first time you launch it, it will take a very long time: it will download all dependencies and compile all source code. Expect to wait 30 minutes on a reasonably fast computer with a decent Internet connection.

On Mac, you may be prompted to install XCode at some point. If you are, click "Install", wait for the install to finish, then run ./dev again.

You'll be able to tell when it's done because you'll see text like this:

[overview-server] --- (Running the application from SBT, auto-reloading is enabled) ---
[overview-server] 
[overview-server] [info] play - Listening for HTTP on /0:0:0:0:0:0:0:0:9000
[overview-server] 
[overview-server] (Server started, use Ctrl+D to stop and go back to the console...)

Kill everything with Ctrl+C (or, as the message suggests, Ctrl+D).

Creating an Overview user

You have three options:

  • Use the default admin login. Email and password are [email protected].
  • Register a new user from the main page. When you register, a confirmation "email" will be output on the console where you ran ./dev. Follow the link in the "email" to complete your registration.
  • Or just run in single-user mode run ./dev -Doverview-server.props.overview.multi_user=false. (This is the default when running downloadable binaries' ./run.)

Deprecation warning Prior to 2014-01-17, the email and password of the default admin login were [email protected] (with a hyphen). If you never changed the default credentials, the upgrade will change them for you. If you did change the default credentials, the upgrade will have no effect.

Developing

Running individual servers

When you're developing the workers, you probably won't want to keep them running all the time. So open one terminal and run this:

./dev --except-servers worker,documentset-worker

Then open a second terminal and run this:

./dev --only-servers worker,documentset-worker --no-database

Now you can run a compile-run-debug-edit cycle, by using Ctrl+C in the second terminal and leaving the first alone.

(The --no-database flag is separate because the runner treats it separately: the database starts first and finishes last.)

To run just the database:

# start the server
postgres -D /full/path/to/overview-server/database -k /full/path/to/overview-server/database

# connect with the client
psql -U overview -p 9010 -h localhost overview-dev

Developing the web server

The overview-server component is special: if you edit files in app/, they will be recompiled on the fly the next time you request a page. Read the Play documentation for more details.

Testing

Postgres must be running before tests can be run. Run ./dev first or ./dev --database --except-servers search-index,message-broker,overview-server,documentset-worker,worker if you only want the database up.

  • ./sbt test runs the server tests and sets up the test database (run this first, or try it if you get weird db errors running the other tests)
  • ./sbt all/test runs all the tests (server, workers)
  • ./sbt {project}/test runs the tests for subproject {project} only.

You may test projects while they are running in other terminals. You may run into problems if you run unit tests at the same time as integration tests, as they use the same database.

JavaScript unit-testing

If you plan on hacking JavaScript, follow the instructions in test/assets/javascripts/autotest/README.md

Setup Eclipse

Clone this wiki locally