Skip to content

Latest commit

聽

History

History
172 lines (116 loc) 路 6.12 KB

INSTALL.md

File metadata and controls

172 lines (116 loc) 路 6.12 KB
Raw

Install instructions

Run with Docker (simple)

Docker makes it easy and safe to install and start the two servers required for Openwhyd: the MongoDB database server, and the web/application server (formerly called whydJS).

Prerequisites

All you need is:

  • access to the shell (a.k.a. terminal);
  • to have Docker;
  • and to have Git installed on your machine.

Docker for Windows Home

Docker for Windows Home runs on a virtual box, so localhost may not work. For all the instructions below, if localhost is not working, replace it with your docker ip. You can find your docker ip with :

$ docker-machine ip

Clone and run

Commands to type in your shell:

$ git clone https://github.com/openwhyd/openwhyd.git
$ cd openwhyd
$ docker-compose up --build --detach  # will start openwhyd's web server and database in the background
$ open http://localhost:8080          # ... in your web browser => you should see Openwhyd's home page! 馃帀
$ docker-compose down                 # when you're done: will stop openwhyd's web server and database

After making changes to the source code, don't forget to stop and re-start it using docker-compose.

Run automated tests

Commands to run all automated tests against the Docker container:

$ make test

Sample data

If you want to import some user data from openwhyd.org into your local/test database, you can use the following script:

$ docker-compose up --build --detach    # starts openwhyd's web server and database in the background
$ make docker-seed                      # clears the database and restarts openwhyd's container
$ node scripts/import-from-prod.js test # imports 21 posts from https://openwhyd.org/test

After that, you will be able to sign in as an administrator using the credentials returned by the script.

The data imported can be seen from http://localhost:8080/all

Connect to the database

If you want to connect to the MongoDB database with the mongo shell using docker-compose container:

$ docker-compose exec mongo mongo mongodb://localhost:27117/openwhyd_test

Deploy to a DigitalOcean instance

Read How to deploy on DigitalOcean.

Install and run manually (advanced)

If you don't want to use Docker (or can't), you can follow these instructions.

Setup (advanced)

  • Install Node.js, MongoDB, GraphicsMagick or ImageMagick
  • Make sure that make and g++ are installed (required for building npm binaries, I had to do this and this)
  • Make sure that a MongoDB server is running
  • Make sure that the necessary environment variables are defined (see below)
  • Make sure that the database is initialized (by running mongo openwhyd_data config/initdb.js and mongo openwhyd_data config/initdb_testing.js)
  • Make sure that dependencies are installed (npm install)

Usage (advanced)

  • Run npm start, or npx pm2 start app.js (auto-restart daemon)
  • Open http://localhost:8080 (or WHYD_URL_PREFIX)
  • During development, you may have to restart the server to have your changes taken into account.

Testing (advanced)

Run unit tests only:

$ npm run test:unit

Run all tests, including approval tests:

$ make test
$ make test-approval

Configuration (advanced)

Command-line arguments

Openwhyd's entry point (app.js) accepts two kinds of command-line arguments:

  • toggles: --no-color, --fakeEmail and --emailAdminsOnly; (see FLAGS from app.js for an up-to-date list)
  • overrides: any app-level configuration parameter can be set, e.g. urlPrefix can be set as --urlPrefix <value>. (see process.appParams from app.js for an up-to-date list)

Advanced use cases

Test email digests

If you want to test email digests locally:

$ node app.js --emailAdminsOnly --digestInterval 5000 --digestImmediate true

Map localhost to a domain name

If you want to test Deezer Connect, you will need your server to be reachable through a domain name. Here's a way to achieve that:

  1. Configure your Deezer app to allow connections from http://local.openwhyd.org:8080;
  2. Add local.openwhyd.org to your /private/etc/hosts file;
  3. Flush the corresponding cache: $ dscacheutil -flushcache;
  4. Start Openwhyd with $ npm start -- --urlPrefix http://local.openwhyd.org:8080.

Environment variables

  • WHYD_GENUINE_SIGNUP_SECRET (mandatory. a secret key that is used to make sure that sign-ups are legit)
  • WHYD_SESSION_SECRET (mandatory. a secret key used to sign session cookies)
  • WHYD_ADMIN_OBJECTID (ObjectId of the user that can access to admin endpoints)
  • WHYD_ADMIN_NAME (Full-text name of the user that can access to admin endpoints)
  • WHYD_ADMIN_EMAIL (mandatory. Email address of the user that can access to admin endpoints)
  • WHYD_CONTACT_EMAIL (mandatory. email for users to contact the site's team)
  • WHYD_URL_PREFIX (default: http://localhost:8080)
  • WHYD_PORT (default: 8080)
  • MONGODB_DATABASE (example: openwhyd_data, or openwhyd_test)
  • MONGODB_HOST (default: localhost)
  • MONGODB_PORT (default: 27017)
  • MONGODB_USER (default: none)
  • MONGODB_PASS (default: none)
  • SENDGRID_API_KEY (mandatory. API key of the Sendgrid account to be used for sending emails)
  • SENDGRID_API_FROM_EMAIL (mandatory. email address of email sender)
  • SENDGRID_API_FROM_NAME (mandatory. name of email sender)
  • LAST_FM_API_KEY (mandatory. for lastfm scrobbling)
  • LAST_FM_API_SECRET (mandatory. for lastfm scrobbling)
  • ALGOLIA_APP_ID (mandatory. for search index)
  • ALGOLIA_API_KEY (mandatory. for search index)

Other variables to update

The value of following constants is required to connect to the corresponding APIs:

  • YOUTUBE_API_KEY
  • SOUNDCLOUD_CLIENT_ID
  • JAMENDO_CLIENT_ID
  • DEEZER_APP_ID