- Deploy OpenOpps as a Docker Container from the Docker Hub
- Step by Step Installation from Source
- For development
- For production
- Host and Configure Application
- Troubleshooting Cross Platform Issues
- Download and install the Docker Toolbox
- Open Kitematic on your Mac (it's installed with the Docker Toolkit), search for "open-opps", and click create:
- You'll see the log of OpenOpps starting up. (You may need to wait a minute for the application to start up.) Click the arrow next to "Web Preview" to open up OpenOpps in your browser:
- You're now running OpenOpps in a local container and you can do all the things you'd usually do with it
- Bonus: you can try our other branches of OpenOpps (useful for reviewing pull requests). Get the branch name from GitHub:
6. Go back to "Settings" in Kitematic, set the BRANCH environment variable, and click "Save":
7. Now on "Home", you'll see the log of OpenOpps rebuilding with the new branch. Give it a chance to build, then relaunch the web preview to try the new branch
After installing docker, as above, you can use it for development, by syncing a local directory with the virtual container.
First, grab the code and clone onto your local machine.
git clone git@github.com:18F/openopps-platform.git docker-openopps
cd docker-openopps
Note: I've created a different directory name to remind myself that this code that will run in Docker. I will be configuring this and installing modules for the Docker environment, which is different than my local machine.
Run Kitematic, and choose menu File > Open Docker Command-Line Terminal
Then on the command-line:
docker login
docker pull 18fgsa/open-opps
docker run -Pti -v `pwd`:/usr/src/app --entrypoint=/bin/bash --name local-opps 18fgsa/open-opps
Every once in a while, there's a timeout when executing this command multiple times. If that happens, resetting the environment can fix it:
docker-machine restart default # Restart environment
eval $(docker-machine env default) # Refresh environment settings
Now, with your Docker machine running and synced to your local directory, run the following commands in the interactive terminal (which runs them in the Docker machine):
npm i -g npm@3
npm install -g node-gyp@3.3.1 grunt-cli@0.1.13
npm install
npm run init
npm start
Now you can see your local code run in the Docker container. You can modify the code locally and stop and start the server to see changes.
The following installation steps for Mac, Linux, and Windows can be used for setting up a development or production environment manually.
The instructions have been tested on 10.9.2, but earlier versions likely work. Also, to follow these steps you will need:
- the popular brew package manager
- XCode (free via Mac AppStore)
In the Terminal:
brew install postgresql
brew install graphicsmagick
When Homebrew is done installing Postgres, follow the instructions at the end to start Postgres.
Next, create the midas database:
initdb /usr/local/var/postgresql
Once you're done installing you'll see two options: Success. You can now start the database server using:
postgres -D /usr/local/var/postgresql
or
pg_ctl -D /usr/local/var/postgresql -l logfile start
When you run either of these commands it will start running the server. It's best to choose the first choice (postgres -D /usr/local/var/postgresql) so if you work on a different tab in your terminal the server will keep running. Next in the Terminal:
createdb midas
Start the postgres console acting on the midas database with: psql midas
CREATE USER midas WITH PASSWORD 'midas';
GRANT ALL PRIVILEGES ON DATABASE midas to midas;
ALTER SCHEMA public OWNER TO midas;
\q
Install node.js. As of Feb 2015 Node.js has moved to 0.12 for its stable version. But many dependencies, especially native compiled packages, don't work with 0.12 yet. So consider running Node.js 0.10. Consider using nvm to manage Node versions. Once installed and sourced into your environment nvm can handle manage versions.
So back to the command line. We assume that nvm is installed and set up
(added to .bashrc or equivalent).
nvm install 4.2.2
nvm alias default 4.2.2
nvm version # should be v4.2.2
Then follow platform-independent steps below starting at clone the git repository.
sudo echo "UTC" | sudo tee /etc/timezone
sudo dpkg-reconfigure --frontend noninteractive tzdata
sudo apt-get install -y python-software-properties python g++ make git
sudo add-apt-repository -y ppa:pitti/postgresql
sudo apt-get update
sudo apt-get remove postgresql
sudo apt-get remove postgresql-9.1
sudo apt-get remove postgresql-client-9.1
sudo apt-get remove postgresql-doc-9.1
sudo rm -rf /etc/postgresql/9.1
sudo apt-get install -y --force-yes postgresql-9.2
sudo apt-get install -y --force-yes postgresql-server-dev-9.2
After installing postgres, you may want to modify the configuration settings so that local applications can make connections to the database server.
Modify pg_hba.conf in /etc/postgresql/*/main (- is for lines to be removed and + is for lines to be added, like a diff):
# "local" is for Unix domain socket connections only
-local all all peer
+local all all md5
For connections outside localhost, modify postgresql.conf:
-#listen_addresses = 'localhost'
+listen_addresses = '*'
AND modify pg_hba.conf:
# IPv4 local connections:
-host all all 127.0.0.1/32 md5
+hostssl all all 0.0.0.0/0 md5
sudo -u postgres createdb midas
sudo -u postgres psql -c "CREATE USER midas WITH PASSWORD 'midas';"
sudo -u postgres psql -c "GRANT ALL PRIVILEGES ON DATABASE midas to midas;"
sudo -u postgres psql -c "ALTER SCHEMA public OWNER TO midas;" midas
sudo add-apt-repository -y ppa:chris-lea/node.js
sudo apt-get update
sudo apt-get install nodejs
sudo apt-get install graphicsmagick
Reboot server once finished
Establish admin user account during the wizard and verify that PostgreSQL is running as a service
Open pgAdmin
Create database 'midas', user account 'midas' with password 'midas', and assign user 'midas' full rights to administer DB 'midas'
Use npm version 3.x
npm i -g npm@3
GraphicsMagick
Select Q8 version along with latest corresponding to 32 bit vs. 64 bit OS
Go to Control Panel -> System -> Advanced System Settings -> Environment Variables Find "Path" Variable in System Variables table and double click to edit it. Make sure it contains all of the following parts (in addition to anything else) separated by a semi-colon.
DRIVE:\program files\graphicsmagick-1.3.18-q8;
(or similar, depending on your graphicsmagick version)
DRIVE:\Program Files\nodejs\;
Save.
Typically we do development without the theme. Tests are designed to run without the theme, which sets up alternate configuration.
This theme is contained in [a separate repository] openopps_theme_repo. To
hook into the npm preinstall hook's theme copy mechanism, you must have an
environment variable pointing the Github URL to the $THEME variable.
Here's an example using export:
export THEME="https://github.com/18F/open-opportunities-theme.git" && \
npm install
Note: the tests don't currently pass when the theme is installed since it also changes configuration.
git clone https://github.com/18F/openopps-platform.git
cd openopps-platform
Then install npm 3.x and run the normal npm package installer
npm i -g npm@3
npm install -g node-gyp@3.3.1 grunt-cli@0.1.13
npm install
See the Configuration Guide
From the root of the openopps directory, initialize the database:
npm run init
If you'd like to include a sample project and users, also run:
npm run demo
This also creates a handful of initial users. By default all those users are disabled, and none are admin. It's usually helpful to have at least one admin user (we picked "Alan Barret") so these commands are helpful:
psql midas
update midas_user set disabled='f';
update midas_user set "isAdmin"='t' where username='alan@test.gov';
Note the quotes around "isAdmin". Postgres by default lowercases all non-keywords, which includes column names. This doesn't play nicely with our schema.
Now you are ready to rock!
Run the tests (all should pass)
npm test
Run the server (watch client files, compiling if needed)
npm run watch
Go to http://localhost:1337 to see the app
Check out the Contributor's Guide for next steps
On Mac OSX, you may receive a stream of
Error: EMFILE, too many open files
messages after running npm start. This is an issue with OSX and Grunt; there are directions to fix the issue here or here.
npm run build
npm run init
Install forever with from npm:
sudo npm install -g forever
This will run the application server on port 1337
forever start app.js --prod
You can now access the server at http://localhost:1337
sudo add-apt-repository -y ppa:nginx/stable
sudo apt-get update
sudo apt-get install nginx
Configure nginx with the files in the tools folder. Use the SSL config file if you want to enable SSL, but be sure to set your SSL key.
cd tools/nginx
sudo cp sites-enabled.default /etc/nginx/sites-enabled/default
sudo service nginx restart
With the application server running and nginx running, you should now be able to access the application at http://localhost
Follow instructions as above in Linux Install Guide to retrieve necessary files from GitHub.
Install NPM Modules as directed above.
Retrieve OpenOpps from GitHub as above on an online pc. Install NPM modules as directed. Copy to offline server your local npm_modules directory (in project home) as well as the contents of the directory found in Users/YOUR_USER_NAME/AppData/Roaming/npm to corresponding locations on offline-server.
Navigate to OpenOpps directory via windows cmd.exe prompt
Enter the following commands
npm install
Start Midas with
npm start
You can now access the server at http://localhost:1337
Having an error on npm start which begins the Sails server with an error along
the lines of the following:
error: Unable to parse HTTP body- error occurred :: { [error: relation "<TABLE_NAME>" does not exist] name: 'error',}
Can mean that your database is corrupt or misconfigured. A potential fix is to
clean your database using the scripts found in tools/postgres. This will
delete everything in your database.
./tools/postgres/cleandb.sh
Once that's done, you need to run npm run init again.
You can also verify that the correct midas user exists for the <TABLE_NAME>.
ALTER TABLE session OWNER TO midas;
--- ^^^^^This should also work if you run into issues with other tables.
ALTER TABLE * OWNER TO midas;
--- ^^^^^