Skip to content

README.md

Latest commit

 

History

History
252 lines (188 loc) · 8.85 KB

README.md

File metadata and controls

252 lines (188 loc) · 8.85 KB

Hylo Backend

Thanks for checking out our code. The documentation below may be incomplete or incorrect. We welcome pull requests! But we're a very small team, so we can't guarantee timely responses.

❤️, Tibet, Loren, Tom

Code Climate Test Coverage

Setup

You need to install redis locally, then follow the steps to launch it on startup (on the default port of 6379). For OSX/MacOS:

brew install redis

Arch Linux:

pacman -S redis
systemctl enable redis.service
systemctl start redis.service

Ubuntu Linux:

sudo apt-get -y install redis-server
sudo systemctl enable redis
sudo systemctl start redis

Create a .env file in the root directory by copying .env.example. More info about specific keys below:

  • ADMIN_GOOGLE_CLIENT_*: To access the admin console. Get these values from the hylo-admin Google project.
  • DEBUG_SQL: set to true if you want to output the SQL used within knex/bookshelf
  • DATABASE_URL: set to your local DB instance
  • EMAIL_SENDER: set to your email address
  • MAPBOX_TOKEN: get a token from Mapbox or email dev@hylo.com for one
  • OIDC_KEYS: set to a base64 string of a RSA key, you can generate one with openssl genrsa 2048 | base64
  • ROLLBAR_SERVER_TOKEN: use the post_server_item token in Rollbar
  • SENDWITHUS_KEY: set up a test key in SendWithUs to send all email only to you (ask someone with admin rights to set this up)
  • SLACK_APP_CLIENT_ID: set up an app on Slack and reference its' client id, optional for dev installation
  • SLACK_APP_CLIENT_SECRET: reference the client secret from that same app on Slack, optional for dev installation

populating the database

Make sure you have Postgres running with PostGIS installed and your user has create database privileges. Then you should be able to use one of the following scenarios.

creating a fresh instance without fake data

createdb hylo -h localhost
createdb hylo_test -h localhost
cat migrations/schema.sql | psql hylo
yarn knex seed:run

Note: This will trash everything in your current hylo database, so make sure you really want to do that! You can run yarn knex seed:run anytime you want to refresh the database but this will delete groups, users, and posts.

creating a fresh instance with generic data

createdb hylo -h localhost
createdb hylo_test -h localhost
cat migrations/schema.sql | psql hylo
NODE_ENV=dummy yarn knex seed:run

The script will ask for confirmation. By default the test user will be test@hylo.com with password hylo, configurable at the top of seeds/dummy/dummy.js.

Note: This will trash everything in your current hylo database, so make sure you really want to do that! You can run NODE_ENV=dummy yarn knex seed:run anytime you want to refresh the database but this will delete groups, users, and posts.

creating a fresh instance with farm data

If you are working with farm group data, run this command to add fake farm data to either a database copy, or a db copy generated by the seeding function. This function is not designed to be run more than once successfully.

createdb hylo -h localhost
createdb hylo_test -h localhost
cat migrations/schema.sql | psql hylo
NODE_ENV=farmdev yarn knex seed:run

Note: You will not be able to run NODE_ENV=farmdev yarn knex seed:run more than once. Alternatively, drop the production DBs and re-run the script.

creating a fresh instance and loading database snapshot

Scroll down to "loading database snapshots" 👇

running the dev server

yarn dev

This reads the .env file you created above, using dotenv, and starts two processes managed by foreman: one web server process and one background job worker process, as listed in Procfile.dev. If you want to run only one of the processes, pass its name in Procfile.dev as an argument, e.g. yarn dev -- web.

Now visit localhost:3001.

developing locally with SSL (for testing iFrame embedding)

Create a local certificate and make sure your computer trusts it. Here are some up to date instructions for macOS: https://deliciousbrains.com/ssl-certificate-authority-for-local-https-development/

Create a directory config/ssl and copy the .crt, key and .pem (CA certificate) files to it. Assuming the names are localhost.crt, localhost.key and localhost.pem then add a file at config/local.js with the contents:

var fs = require('fs')
var path = require('path')

module.exports = {

  /**** Setup an SSL certificate for local development with SSL (so we can test iFrame embedding) ***/
  ssl: process.env.PROTOCOL === 'https' ? {
    ca: fs.readFileSync(path.resolve(__dirname, './ssl/localhost.pem')),
    key: fs.readFileSync(path.resolve(__dirname, './ssl/localhost.key')),
    cert: fs.readFileSync(path.resolve(__dirname, './ssl/localhost.crt'))
  } : false

}

Change your .env file to have:

PROTOCOL=https

Setting up to handle auth with JWTs and become an OpenID Connect provider

  • Run yarn generate-rsa-key-base64
  • Copy generated base64 string to .env file: OIDC_KEYS=base64key
  • You can add multiple keys by separating them with a comma (to rotate keys in the future)

running tests

Run yarn test or yarn cover. The tests should use a different database (see below), because it creates and drops the database schema on each run.

Create a file called .env.test to set environment variables for the test environment.

# NOTE: don't put comments after a variable initialization.  it will break your tests!

# run tests against a different database
DATABASE_URL=postgres://localhost/hylo_test
DOMAIN=testdomain
# this prevents jobs that were queued during testing from being run in development
KUE_NAMESPACE=qtest
PROTOCOL=http
# don't log errors to Rollbar
ROLLBAR_SERVER_TOKEN=
# you can set up a SendWithUs API key to return valid responses but send no email
SENDWITHUS_KEY=test_...
INBOUND_EMAIL_SALT=FFFFAAAA123456789
INBOUND_EMAIL_DOMAIN=inbound-staging.hylo.com
PLAY_APP_SECRET=quxgrault12345678
AWS_ACCESS_KEY_ID=foo
UPLOADER_PATH_PREFIX=foo

(Without the above values, you'll see a failing test in the suite.) Since the test database was created above, npm test should work at this point.

creating and running database migrations

Migrations are managed by the knex library. Create a new migration with this command:

knex migrate:make my_migration_name

(You can either install knex globally with npm install -g knex, or run the version in your node_modules with ./node_modules/.bin/knex.)

Run migrations with yarn migrate and rollback the last one with yarn rollback.

loading database snapshots

The values of DB_USERNAME, DB_HOST, DB_PORT, and DB_NAME below can be obtained from DATABASE_URL in heroku config.

LOCAL_DB_NAME=hylo
DUMP_FILENAME=dbdump
pg_dump -O -U $DB_USERNAME -h $DB_HOST -p $DB_PORT $DB_NAME > $DUMP_FILENAME
# stop all processes that have open database connections, then:
dropdb $LOCAL_DB_NAME -h localhost
createdb $LOCAL_DB_NAME -h localhost
cat $DUMP_FILENAME | psql -h localhost $LOCAL_DB_NAME

Design guidelines

  • GET methods on FooController should return instances of Foo. (See policies.js for some related FIXME's)

Style guidelines

We're gradually migrating to Javascript Standard Style. The standard-formatter Atom package helps out a lot. The linter-js-standard package is also very helpful.

GraphQL API

Our main API uses GraphQL. You can browse the queries and mutations by going to http://localhost:3001/noo/graphql and using the Documentation Explorer in the right sidebar.

Example Queries:

type Query {
  me: Me
  person(id: ID): Person
  ...
}

where Me is the currently logged-in user. For example, to load all current user's posts:

{
  me {
    posts {
      id,
      title,
      type,
      details,
      creator {
        id,
        name,
        avatarUrl
      }
      followers {
        id,
        name,
        avatarUrl
      }
      followersTotal,
      groups {
        id,
        name
      },
      groupsTotal,
      comments {
        id,
        createdAt,
        text,
        creator {
          id
        }
      },
      commentsTotal,
      createdAt,
      fulfilledAt
    }
  }
}