diff --git a/README.md b/README.md index 2d2edbef9b..8478e0f453 100644 --- a/README.md +++ b/README.md @@ -1,23 +1,30 @@ +
+ # EQ Author +eq-author logo + [![Build Status](https://travis-ci.com/ONSdigital/eq-author-app.svg?branch=master)](https://travis-ci.com/ONSdigital/eq-author-app) [![codecov](https://codecov.io/gh/ONSdigital/eq-author-app/branch/master/graph/badge.svg)](https://codecov.io/gh/ONSdigital/eq-author-app) -[![Codacy Badge](https://api.codacy.com/project/badge/Grade/f9cbc9e5c531436ca73ee0769a766678)](https://www.codacy.com/app/jchapman68/eq-author-app?utm_source=github.com&utm_medium=referral&utm_content=ONSdigital/eq-author-app&utm_campaign=Badge_Grade) +[![Codacy Badge](https://api.codacy.com/project/badge/Grade/f9cbc9e5c531436ca73ee0769a766678)](https://www.codacy.com/app/ONSDigital/eq-author-app) +![Snyk Vulnerabilities for GitHub Repo](https://img.shields.io/snyk/vulnerabilities/github/ONSDigital/eq-author-app.svg) + +![GitHub](https://img.shields.io/github/license/ONSDigital/eq-author-app.svg) +![GitHub repo size](https://img.shields.io/github/repo-size/ONSDigital/eq-author-app.svg) +![GitHub release](https://img.shields.io/github/release/onsdigital/eq-author-app.svg) + +Author is an application for building questionnaires that run on the [Survey Runner](https://github.com/ONSDigital/eq-survey-runner) platform. -Author is an application for building questionnaires that run on the [Survey Runner](https://github.com/ONSDigital/eq-survey-runner) platform, and was bootstrapped with [Create React App](https://github.com/facebookincubator/create-react-app). +
-The project comprises of three components: +The project is composed of three components: -- [Front end](/eq-author/README.md) -- [API](/eq-author-api/README.md) -- [Publisher](/eq-publisher/README.md) +- [eq-author](/eq-author/README.md) (front end) +- [eq-author-api](/eq-author-api/README.md) (back end) +- [eq-publisher](/eq-publisher/README.md) -## Guides +## Guides -- [Overview](/docs/OVERVIEW.md) - [Installation](/docs/INSTALLATION.md) -- [Running](/docs/RUNNING.md) -- [Testing](/docs/TESTING.md) +- [Authentication](/docs/AUTHENTICATION.md) - [Debugging](/docs/DEBUGGING.md) -- [Build](/docs/BUILD.md) -- [Supplimentary Information](/docs/SUPPLIMENTARY-INFO.md) diff --git a/docs/AUTHENTICATION.md b/docs/AUTHENTICATION.md index 695ea22b0b..0d10f8aa40 100644 --- a/docs/AUTHENTICATION.md +++ b/docs/AUTHENTICATION.md @@ -1,6 +1,6 @@ # Authentication -![firebase_28dp.png](firebase_28dp.png) We currently use Firebase for basic authentication requirements. +![Firebase logo](images/firebase_logo.png) We currently use Firebase for basic authentication requirements. - Go to [Firebase](https://firebase.google.com) - Add a project @@ -11,40 +11,25 @@ - Select settings by Project Overview - Copy down Project ID AND API Key -## eq-author - -The following environment variables are required for firebase: +Note: CLI env vars taken precedence over `.env.development.local` vars. For more information about precedence of config files, see: -| Name | Description | Required | -| ------------------------------- | ------------------------------------------------------------------------------------ | -------- | -| `REACT_APP_FIREBASE_PROJECT_ID` | The project ID for your Firebase project. Can be obtained from your Firebase project | | -| `REACT_APP_FIREBASE_API_KEY` | The api key for your Firebase project. Can be obtained from your Firebase project | Yes | +## eq-author -They should be added to an `.env.development.local` file in the eq-author sub folder: +The following environment variables are required for eq-author: ``` -REACT_APP_FIREBASE_PROJECT_ID="ABC" -REACT_APP_FIREBASE_API_KEY="DEF" -``` - -These can also be passed on command line: - -```bash -REACT_APP_FIREBASE_PROJECT_ID=ABC REACT_APP_FIREBASE_API_KEY=DEF yarn start +REACT_APP_FIREBASE_PROJECT_ID="YOUR_FIREBASE_APP_ID" +REACT_APP_FIREBASE_API_KEY="YOUR_API_KEY" ``` -Note: CLI env vars taken precedence over `.env.development.local` vars. For more information about precedence of config files, see: +They should be added to an `.env.development.local` file in the eq-author sub folder: ## eq-author-api -The following environment variables are required for firebase: - -| Name | Description | Required | -| --------------------- | ------------------------------------------------------------------------------------ | -------- | -| `FIREBASE_PROJECT_ID` | The project ID for your Firebase project. Can be obtained from your Firebase project | Yes | - -They should be added to an `.env` file in the eq-author-api sub folder: +The following environment variables are required for eq-author-api: ``` FIREBASE_PROJECT_ID="YOUR_FIREBASE_APP_ID" ``` + +They should be added to an `.env` file in the eq-author-api sub folder: diff --git a/docs/BUILD.md b/docs/BUILD.md deleted file mode 100644 index eec1bf5e05..0000000000 --- a/docs/BUILD.md +++ /dev/null @@ -1,21 +0,0 @@ -# Build - -## Front End - -### Build configuration - -| Name | Description | Required | -| ----------------------------- | ------------------------------------------------------------------------------ | -------- | -| `BABEL_ENV` | Sets the environment the code is running in | Yes | -| `NODE_ENV` | Sets the environment the code is running in | Yes | -| `NODE_PATH` | Folder path for the code folder structure | Yes | -| `CI` | Switch that if is set to true will treat warnings as errors | No | -| `REACT_APP_EQ_AUTHOR_VERSION` | The current Author version. This is what gets reported on the /status endpoint | No | - -### `yarn build` - -Builds the app for production to the `build` folder. -It correctly bundles React in production mode and optimizes the build for the best performance. - -The build is minified and the filenames include the hashes. -The build will produce the static assets for the front end. diff --git a/docs/DEBUGGING.md b/docs/DEBUGGING.md index 9c4b720348..a519af8a62 100644 --- a/docs/DEBUGGING.md +++ b/docs/DEBUGGING.md @@ -1,38 +1,11 @@ # Debugging (with VS Code) -## Debugging app - Follow [this guide](https://github.com/docker/labs/blob/83514855aff21eaed3925d1fd28091b23de0e147/developer-tools/nodejs-debugging/VSCode-README.md) to enable debugging through VS Code. If you have started the app with `docker-compose` then you can attach a debugger. This is the `launch.json` configuration you must use instead of that detailed in the guide, it will attach _to the running docker container_: -### Debugging eq-author-api - -`launch.json` - -```json -{ - "version": "0.2.0", - "configurations": [ - { - "name": "Attach to Container", - "type": "node", - "request": "attach", - "port": 5858, - "address": "localhost", - "restart": true, - "sourceMaps": false, - "localRoot": "${workspaceRoot}", - "remoteRoot": "/app", - "protocol": "inspector" - } - ] -} -``` - -### Debugging eq-publisher - -`launch.json` +Change the ports with the following: +`eq-publisher` uses port `5859`, `eq-author-api` uses port `5858` ```json { @@ -54,7 +27,7 @@ If you have started the app with `docker-compose` then you can attach a debugger } ``` -## Debugging tests +## Debugging tests in eq-author-api Add the following to your `launch.json` configuration: @@ -67,4 +40,4 @@ Add the following to your `launch.json` configuration: } ``` -Then start your tests [as described above](#tests). You can now start a debugging session, and pick the jest process to attach to. +Then start your tests [as described above](#running-tests). You can now start a debugging session, and pick the jest process to attach to. diff --git a/docs/INSTALLATION.md b/docs/INSTALLATION.md index 176f8f219d..c2dc789b75 100644 --- a/docs/INSTALLATION.md +++ b/docs/INSTALLATION.md @@ -2,16 +2,16 @@ ## Prerequisites -- Install [Node](https://nodejs.org/en/) using `nvm install` in each component folder. -- Install [Yarn](https://yarnpkg.com/en/) -- Google Chrome +- Install [Node.js](https://nodejs.org/en/) version 10 or later. +- Install [Node Version Manager](https://github.com/nvm-sh/nvm/blob/master/README.md) +- Install [Yarn Dependency Manager](https://yarnpkg.com/en/docs/install) +- Install [Google Chrome](https://www.google.com/chrome/) +- Install [Docker](https://docs.docker.com/install/) with [Docker Compose](https://docs.docker.com/compose/install/) -## Authentication +## Setting up Authentication -Follow this guide to set up [Authentication](AUTHENTICATION.md) +Follow [this guide](AUTHENTICATION.md) to set up authentication. -## Install Dependencies +## Installing Dependencies -Just run `yarn` to install all dependencies. - -Follow this guide for more information on installing dependencies [Yarn Guide](https://yarnpkg.com/en/docs/installing-dependencies) +Follow [this Yarn guide](https://yarnpkg.com/en/docs/installing-dependencies) for more information on installing dependencies. diff --git a/docs/OVERVIEW.md b/docs/OVERVIEW.md deleted file mode 100644 index 80ea593060..0000000000 --- a/docs/OVERVIEW.md +++ /dev/null @@ -1,13 +0,0 @@ -# Overview - -## Publisher - -The conversion between the GraphQL JSON output and the EQ runner schema can be thought of as a pipeline. - -The conversion pipeline is made up of a series of steps to convert each part of the GraphQL JSON. - -Each step applies a series of transforms to manipulate the resulting JSON. - -The final validate process is passed on to [eq-schema-validator](https://github.com/ONSdigital/eq-schema-validator) - -![process.jpg](/eq-publisher/docs/images/process.png) diff --git a/docs/RUNNING.md b/docs/RUNNING.md deleted file mode 100644 index dc52ca6d90..0000000000 --- a/docs/RUNNING.md +++ /dev/null @@ -1,74 +0,0 @@ -# Running - -## Running Components Automatically - -### eq-author - -The following environment variables should be placed in a .env.[environment] file in the eq-author folder. - -| Name | Description | Required | -| ---------------------- | --------------------------------------- | -------- | -| `REACT_APP_API_URL` | Set Author API URL | Yes | -| `REACT_APP_LAUNCH_URL` | Set the launch-a-survey target | No | -| `PUBLIC_URL` | The public URL inferred if not provided | No | - -From a terminal open the `eq-author` folder and run - -```bash -yarn start -``` - -When the process completes a browser window will be opened pointing to [http://localhost:3000](http://localhost:3000) - -The page will reload if you make edits. You will also see any lint errors in the console. - -### eq-author-api - -The compose file orchestrates the Publisher application and the EQ schema validation service. -A benefit of this approach is that there is no need to run the schema validation service manually. - -From a terminal open the `eq-author-api` folder and run - -```bash -docker-compose up --build -``` - -Changes to the application should hot reload via `nodemon`. - -### eq-publisher - -From a terminal open the `eq-publisher` folder and run - -```bash -docker-compose up --build -``` - -## Running Components Manually - -### Publisher - -#### Installation - -To install dependencies, simply run: - -```bash -yarn install -``` - -#### Starting the application - -To run the application: - -```bash -yarn start -``` - -#### Environment Variables - -Note that some Environment Variables may be necessary to run the service in isolation. The following environment variables can be configured. - -| Name | Description | Required | -| ------------------------- | --------------------------------------------------------------------------------------------------------- | -------- | -| `EQ_SCHEMA_VALIDATOR_URL` | The URL of the schema validation service. See [Running with Docker Compose](#running-with-docker-compose) | Yes | -| `EQ_AUTHOR_API_URL` | The URL of the GraphQL API server | Yes | -| `EQ_PUBLISHER_VERSION` | The current Publisher version. This is what gets reported on the /status endpoint | No | diff --git a/docs/SUPPLIMENTARY-INFO.md b/docs/SUPPLIMENTARY-INFO.md deleted file mode 100644 index 7957f02a5c..0000000000 --- a/docs/SUPPLIMENTARY-INFO.md +++ /dev/null @@ -1,38 +0,0 @@ -# Supplimentary Information - -## Front End Folder Structure - -`/config` Webpack config. - -`/data` Example Runner JSON schemas. - -`/public` Public static assets. - -`/scripts` NPM scripts for running the app. - -`/src` JavaScript source files. - -`/src/actions` Redux action creators. - -`/src/components` React components. - -`/src/constants` Constants that can be used throughout the application such as theme colours and action names. - -`/src/containers` Redux container components. - -`/src/helpers` Helper functions, etc. - -`/src/layouts` Layout components. - -`/src/pages` Page components rendered via a route. - -`/src/reducers` Redux reducer functions. - -`/src/schema` Schema for Normalizr. - -For the project to build, **these files must exist with exact filenames**: - -- `public/index.html` is the page template; -- `src/index.js` is the JavaScript entry point. - -You can delete or rename the other files. diff --git a/docs/TESTING.md b/docs/TESTING.md deleted file mode 100644 index 00c75e5376..0000000000 --- a/docs/TESTING.md +++ /dev/null @@ -1,88 +0,0 @@ -# Testing - -## Front End - -### Environment Variables eq-author - -| Name | Description | Required | -| --------------------------- | -------------------------- | -------- | -| `REACT_APP_FUNCTIONAL_TEST` | Run functional test switch | No | - -In the project directory, you can run: - -### `yarn lint` - -Lints the `src` directory using the rules defined in `.eslintrc`. Run `yarn lint -- --fix` if you want eslint to fix any issues it can. - -### `yarn test` - -Launches the test runner in the interactive watch mode. -See the section about [running tests](#running-tests) for more information. - -If you would like to collect code coverage run `yarn test -- --coverage`. - -### Filename Conventions - -Tests are colocated next to the code they are testing. For example, a test for `/src/components/Button/index.js` could be in a file `/src/components/Button/test.js`. - -### Command Line Interface - -When you run `yarn test`, Jest will launch in the watch mode. Every time you save a file, it will re-run the tests, just like `yarn start` recompiles the code. - -The watcher includes an interactive command-line interface with the ability to run all tests, or focus on a search pattern. It is designed this way so that you can keep it open and enjoy fast re-runs. - -## EQ API - -### Testing through GraphiQL - -There are [queries](tests/fixtures/queries.gql) and [example data](tests/fixtures/data.json) in the [fixtures folder](tests/fixtures). These can be used with graphiql to manually build up a questionnaire. - -### DB migrations - -First start app using Docker. - -#### Create migration - -```bash -yarn knex migrate:make name_of_migration -``` - -Where `name_of_migration` is the name you wish to use. e.g. `create_questionnaires_table` - -#### Apply migrations - -```bash -docker-compose exec web yarn knex migrate:latest -``` - -#### Rollback migrations - -```bash -docker-compose exec web yarn knex migrate:rollback -``` - -### Tests - -`yarn test` will start a single run of unit and integration tests. - -`yarn test --watch` will start unit and integration tests in watch mode. - -### Importing questionnaires - -There is a dev only endpoint exposed in the dev environment to be able to import questionnaires from other environments. - -#### How to use it - -1. Run the following query against the environment to retrieve the questionnaire. You need to provide the id as well. (You could use ) -[query examples](/eq-publisher/src/queries.js) - -2. `POST` the result to `/import`. (You could use ) -3. The questionnaire should be there. - -## EQ Publisher - -To run all tests: - -```bash -yarn test -``` diff --git a/eq-author/doc/001-typescript.md b/docs/architecture/0005-typescript.md similarity index 98% rename from eq-author/doc/001-typescript.md rename to docs/architecture/0005-typescript.md index 3630ab8f67..519dbff915 100644 --- a/eq-author/doc/001-typescript.md +++ b/docs/architecture/0005-typescript.md @@ -1,4 +1,4 @@ -# 1. Investigate TypeScript / Flow +# 5. Investigate TypeScript / Flow Date: 20/09/2017 diff --git a/docs/firebase_28dp.png b/docs/images/firebase_logo.png similarity index 100% rename from docs/firebase_28dp.png rename to docs/images/firebase_logo.png diff --git a/eq-publisher/docs/images/process.png b/docs/images/publisher_process.png similarity index 100% rename from eq-publisher/docs/images/process.png rename to docs/images/publisher_process.png diff --git a/eq-author-api/README.md b/eq-author-api/README.md index d42f7e5c25..4a8140facc 100644 --- a/eq-author-api/README.md +++ b/eq-author-api/README.md @@ -3,20 +3,26 @@ A GraphQL based API for the [eq-author](https://github.com/ONSdigital/eq-author) application. -## Installation +## Running -### Configuration +### Running with Docker Compose -Environment variables can be used to configure various aspects of the API. -In most cases sensible defaults have been selected. +> The `docker-compose` configuration should ensure that all required environment variables are set up correctly so there should be no need to manually configure the environment variables when running with docker compose. -> **Tip** -> -> If you decide to run the Author API directly using `yarn` you will need to -> ensure that the environment variables listed below are configured appropriately. -> -> The `docker-compose` configuration should ensure that all required environment variables are set up correctly so there -> should be no need to manually configure the environment variables when [running with docker compose](#run-using-docker). +To build and run the Author GraphQL API inside a docker container, ensure that +Docker is installed for your platform, navigate to the project directory, then run: + +```bash +docker-compose up --build +``` + +The `--build` flag is only required on the first run. + +Changes to the application should hot reload via `nodemon`. + +### Running with Yarn + +> If you decide to run the Author API directly using `yarn` you will need to ensure that the environment variables listed below are configured appropriately. ## Environment Variables @@ -24,7 +30,7 @@ In most cases sensible defaults have been selected. | ----------------------- | ---------------------------------------------------------------------------------- | -------- | | `RUNNER_SESSION_URL` | Authentication URL for survey runner | Yes | | `PUBLISHER_URL` | URL that produces valid survey runner JSON | Yes | -| `FIREBASE_PROJECT_ID` | Your Firebase App Id | Yes | +| `FIREBASE_PROJECT_ID` | The project ID for your Firebase project. | Yes | | `SECRETS_S3_BUCKET` | Name of S3 bucket where secrets are stored | No | | `KEYS_FILE` | Name of the keys file to use inside the bucket | No | | `AUTH_HEADER_KEY` | Name of the header values that contains the Auth token | No | @@ -33,52 +39,54 @@ In most cases sensible defaults have been selected. | `NODE_ENV` | Sets the environment the code is running in | No | | `ENABLE_IMPORT` | When enabled it exposes a post endpoint for importing questionnaires | No | -## Run using Docker - -To build and run the Author GraphQL API inside a docker container, ensure that -Docker is installed for your platform, navigate to the project directory, then run: - -Build the docker image (1st time run): - -``` -docker-compose build -``` - +## Running tests + +`yarn test` will start a single run of unit and integration tests. + +`yarn test --watch` will start unit and integration tests in watch mode. + +## Querying pages + +There is no concrete `Page` type in the GraphQL schema. Instead we use a `Page` interface, which other types implement e.g. `QuestionPage` and `InterstitialPage`. + +To query all pages, and request different fields depending on the type, use [inline fragments](https://graphql.org/learn/queries/#inline-fragments): + +```gql +query { + getQuestionnaire(id: 1) { + questionnaire { + sections { + pages { + id + + # inline fragment for `QuestionPage` type + ... on QuestionPage { + guidance + answers { + id + label + } + } + + # For purposes of example only. `InterstitialPage` doesn't exist yet + ... on InterstitialPage { + # doesn't exist yet + someField + } + } + } + } + } +} ``` -docker-compose up -``` - -Changes to the application should hot reload via `nodemon`. - -## Migrations -`runQuestionnaireMigrations` middleware is responsible for updating the schema version and running any necessary migrations. +## Creating a new migration - `yarn create-migration [name]` will create a new migration in the `/migrations` directory. - Add the created migration to the bottom of the `migrations/index.js` array. - `runQuestionnaireMigrations` will execute necessary migrations on every request providing the schema has not already been migrated. -## DynamoDB - -### Running DynamoDB GUI locally - -To run DynamoDB GUI locally, ensure that you are in the eq-author-api folder and then run: - -``` -yarn dynamodb-admin -``` - -Then open in the web browser to access the database GUI. - -### AWS CLI - -To set up AWS access you first need to install [AWS Command Line Interface](https://aws.amazon.com/cli/). - -Then follow the [instructions for setting up the CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-welcome.html). - -For available commands, see [reference for CLI](https://docs.aws.amazon.com/cli/latest/index.html). - -## Import/Export +## Import/Export Questionnaires It is possible to retrieve the full questionnaire data by making a `GET` request to `/export/:questionnaireId` @@ -91,16 +99,16 @@ Instrumenting the GraphQL API is useful for troubleshooting errors and to help i The Author GraphQL API can be instrumented using [opentracing](https://opentracing.io) via the [apollo-opentracing](https://www.npmjs.com/package/apollo-opentracing) package. -To enable instrumentation and to allow request tracing set the environment variable `ENABLE_OPENTRACING=true`. For convenience the [docker-compose-with-tracing.yml](docker-compose.yml) configuration that has been pre-configured to instrument the API, produce tracing metrics using Prometheus and collect the tracing output using [Jaeger](https://www.npmjs.com/package/jaeger-client). +To enable instrumentation and to allow request tracing set the environment variable `ENABLE_OPENTRACING=true`. For convenience the [docker-compose.yml](docker-compose.yml) configuration that has been pre-configured to instrument the API, produce tracing metrics using [Prometheus](https://prometheus.io/) and collect the tracing output using [Jaeger](https://www.npmjs.com/package/jaeger-client). This configuration is only intended for local development and should not be used for production. To run the author API with instrumentation and request tracing enabled, simply run: -``` +```bash docker-compose up ``` Once running, the trace metrics and spans can be viewed by browsing to the Jaeger UI which is exposed on port `16686`. -[http://localhost:16686](http://0.0.0.0:16686) + diff --git a/eq-author/README.md b/eq-author/README.md index 754efb904b..d6445bd625 100644 --- a/eq-author/README.md +++ b/eq-author/README.md @@ -1,40 +1,25 @@ -# eq-author (Front End) +# eq-author -This project was bootstrapped with [Create React App](https://github.com/facebookincubator/create-react-app). +This project was bootstrapped with [Create React App](https://github.com/facebook/create-react-app). -## Available Scripts +## Running with Yarn -In the project directory, you can run: +`yarn` - Will install all dependencies. -### `yarn start` +`yarn start` - Will start the application in development mode. Open to view it in the browser. -Runs the app in the development mode. -Open to view it in the browser. +`yarn lint` - Lints the `src` directory using the rules defined in `.eslintrc`. -The page will reload if you make edits. -You will also see any lint errors in the console. +`yarn lint -- --fix` - If you want eslint to fix any issues it can. -### `yarn build` +`yarn build` - Builds the app for production to the `build` folder. See [Creating a Production Build](https://facebook.github.io/create-react-app/docs/production-build) for more information. -Builds the app for production to the `build` folder. -It correctly bundles React in production mode and optimizes the build for the best performance. - -The build is minified and the filenames include the hashes. -Your app is ready to be deployed! - -See the section about [deployment](#deployment) for more information. +`yarn test` - Launches the test runner in the interactive watch mode. +`yarn test -- --coverage` - Collects code coverage in `./coverage` folder. ## Environment Variables -### Third party services - -| Name | Description | Required | -| ------------------------- | ----------------------------------------------- | -------- | -| `REACT_APP_SENTRY_DSN` | Use Sentry for error checking, by providing dsn | No | -| `REACT_APP_SENTRY_ENV` | Use Sentry to sort errors by environment | No | -| `REACT_APP_FULLSTORY_ORG` | Use fullstory, by providing org id | No | - ### Runtime | Name | Description | Required | @@ -47,8 +32,71 @@ See the section about [deployment](#deployment) for more information. There are two ways we use environment variables in the application: -1. Build time environment variables. These are values that are known at build time and cannot be changed once the docker image is built. Currently this is only `NODE_ENV`. This is referenced in the code as `process.env.{key}`. +1. Build time environment variables. These are values that are known at build + time and cannot be changed once the docker image is built. Currently this + is only `NODE_ENV`. This is referenced in the code as `process.env.{key}`. 2. Runtime configurable variables. These are values that can change for each place we run the app for example in staging we want the API url to be different to production. In the code these values are read using the config object for example `config.{key}`. - - Dev - Values are read from the environment. - - Docker - Values are read from `window.config` (as defined in `index.html`) and then `process.env`. `index.html` is rewritten in docker to read the available environment variables and pass them to the application every time the docker image starts. + +- Dev - Values are read from the environment. +- Docker - Values are read from `window.config` (as defined in `index.html`) and then `process.env`. `index.html` is rewritten in docker to read the available environment variables and pass them to the application every time the docker image starts. + +### Authentication + +See [docs on authentication](../docs/AUTHENTICATION.md) on setting up a Firebase account. The following environment variables are required for Firebase: + +| Name | Description | Required | +| ------------------------------- | ------------------------ | -------- | +| `REACT_APP_FIREBASE_PROJECT_ID` | Your firebase project id | Yes | +| `REACT_APP_FIREBASE_API_KEY` | Your firebase API key | Yes | + +They can be added to an `.env.development.local` file in the eq-author folder: + +Or you can run: + +```bash +REACT_APP_FIREBASE_PROJECT_ID=ABC REACT_APP_FIREBASE_API_KEY=DEF yarn start +``` + +### Functional + +The following environment variables should be placed in a `.env` file in the eq-author folder. + +| Name | Description | Required | +| ---------------------- | --------------------------------------- | -------- | +| `REACT_APP_API_URL` | Set Author API URL | Yes | +| `REACT_APP_LAUNCH_URL` | Set the launch-a-survey target | No | +| `PUBLIC_URL` | The public URL inferred if not provided | No | + +### Build configuration + +| Name | Description | Required | +| ----------------------------- | ------------------------------------------------------------------------------ | -------- | +| `BABEL_ENV` | Sets the environment the code is running in | Yes | +| `NODE_ENV` | Sets the environment the code is running in | Yes | +| `NODE_PATH` | Folder path for the code folder structure | Yes | +| `CI` | Switch that if is set to true will treat warnings as errors | No | +| `REACT_APP_EQ_AUTHOR_VERSION` | The current Author version. This is what gets reported on the /status endpoint | No | + +### Third party services + +| Name | Description | Required | +| ------------------------- | ----------------------------------------------- | -------- | +| `REACT_APP_SENTRY_DSN` | Use Sentry for error checking, by providing dsn | No | +| `REACT_APP_SENTRY_ENV` | Use Sentry to sort errors by environment | No | +| `REACT_APP_FULLSTORY_ORG` | Use fullstory, by providing org id | No | + +## Folder Structure + +`/config` Webpack config. + +`/public` Public static assets. + +`/scripts` NPM scripts for running the app. + +`/src` JavaScript source files. + +`/src/components` React components. + +`/src/constants` Constants that can be used throughout the application such as +theme colours and action names. diff --git a/eq-publisher/README.md b/eq-publisher/README.md index 57583c08ca..77a0c36153 100644 --- a/eq-publisher/README.md +++ b/eq-publisher/README.md @@ -1,8 +1,8 @@ # eq-publisher -An API for publishing [eq-author](http://github.com/ONSDigital/eq-author) questionnaires. +An API for publishing [Author](https://github.com/ONSdigital/eq-author-app) questionnaires. -## Oveview +## Overview The conversion between the GraphQL JSON output and the EQ runner schema can be thought of as a pipeline. @@ -10,34 +10,55 @@ The conversion pipeline is made up of a series of steps to convert each part of Each step applies a series of transforms to manipulate the resulting JSON. -![process.jpg](docs/images/process.png) +The final validate process is passed on to [eq-schema-validator](https://github.com/ONSdigital/eq-schema-validator). -## Running with Docker Compose +![eq-publisher process](../docs/images/publisher_process.png) + +## Running + +### Running with Docker Compose For convenience, a `docker-compose.yml` configuration is supplied with this project. The compose file orchestrates the Publisher application and the EQ schema validation service. A benefit of this approach is that there is no need to run the schema validation service manually. -Using Docker Compose the application can be run using the following command: + +From a terminal open the `eq-publisher` folder and run ```bash docker-compose up --build ``` -**Note that the `--build` flag is only required on first run.** +The `--build` flag is only required on the first run. -## Testing +### Running with Yarn -To run all tests: +> Note that some [environment variables](#environment-variables) may be necessary to run the service in isolation. -``` -yarn test -``` +`yarn install` - Will install dependencies. + +`yarn start` - Will start the application. + +## Environment Variables + +The following environment variables can be configured. + +| Name | Description | Required | +| ------------------------- | --------------------------------------------------------------------------------------------------------- | -------- | +| `EQ_SCHEMA_VALIDATOR_URL` | The URL of the schema validation service. See [Running with Docker Compose](#running-with-docker-compose) | Yes | +| `EQ_AUTHOR_API_URL` | The URL of the GraphQL API server | Yes | +| `EQ_PUBLISHER_VERSION` | The current Publisher version. This is what gets reported on the /status endpoint | No | + +Note that some Environment Variables may be necessary to run the service in isolation. The following environment variables can be configured. + +## Running tests + +`yarn test` - Will run all tests. ## Routes By default, the express server will bind to port `9000`. -You can then navigate to [http://localhost:9000](http://localhost:9000). +You can then navigate to . Since the API is still under active development, there are only two routes at present: