- Docker - Run the stack in containers!
- docker-compose - Basic Docker orchestrator
- Postgresql - Database
- Redis - Cache
- Expressjs - Nodejs web framework
- Flow - Static Type Checker for JavaScript
- ACE - Atlassian Express library
- InversifyJs - Dependency Injection library
- ApolloServer - Graphql server library
- Ngrok - http tunneling service
Nodejs v10.x: Use nvm if you can, it's handy for switching between node versions A Jira Cloud development instance: Click here to get one. Assuming you used nvm, activate v10 and install Yarn globally:
$ nvm install 10
$ nvm use 10
$ npm install -g yarn
Create a copy of .env.sample
as .env
Create a copy of api/credentials.json.sample
as credentials.json
Edit credentials.json. To get an API Token follow these instructions
{
"hosts": {
"<YOUR JIRA INSTANCE ENDPOINT>": {
"product": "jira",
"username": "<YOUR EMAIL>",
"password": "<YOUR API TOKEN>"
}
}
}
Run yarn
in api
and app
to install dependencies.
$ ./start
The script above will
- Install node dependencies on the
api
andapp
directories - Deploy Postgresql and Redis containers
- Start the server and web applications on containers
- Start an nginx reverse proxy that redirects
/app
requests to theweb
container, and everything else to theapi
container
Use ACE's AC_OPTS
environment variable on .env
to control ACE's behaviour.
With the current value of AC_OPTS=force-reg,force-dereg
an Ngrok tunnel will be created and used as your application's enpoint during development.
Use AC_OPTS=no-auth
to start the stack locally, skipping authentication, and USE_GRAPHQL_MOCKS=true
to mock graphql queries and mutations.
This repo comes with a sample create-react-app application that shows some user info and lists the first 10 jira issues from your configured instance.
When deploying to production make sure you replace atlassian-connect.json
with a version of the file that matches your production environment.
Build the production-ready container using Dockerfile.production
yarn build
and yarn prod
start the api listening on the configured port.
This boilerplate creates a dependency injection container named ioc
and adds it to express' req
, used in routes and graphql resolvers. This container has methods that return the bootstrapped dependencies placed under:
api/src/adapters
for db and redis connections:getAdapter('adapter-file-name')
api/src/domains
for domain classes for business logicgetDomain('domain-file-name')
api/src/models
for sequelize data modelsgetModel('model-file-name')
api/src/services
for external integrationsgetService('service-file-name')
.
AddonService
is a wrapper around ace.httpClient
defined in api/src/factories/AddonServiceFactory.js
and it gets loaded into the IoC container in the addon.js
middleware function, due to its per-request nature.
ACE's middleware also includes a context
object in req
which contains jira's context data. In essence, the following variables are added to express' req
object:
{
ioc: ContainerInterface,
context: ACEContext,
ace: ?Object,
}
api/entrypoint.sh
runs a database migration prior to launching the stack.
DB Migrations are created using knex and the node script db
is an alias to it.
The AddonService instance you get from req.ioc.getService('Addon')
gives you get
, post
, put
and delete
methods that proxy ace
's httpClient methods. There are utility methods in api/src/utils/addonServiceUtils
:
getBodyJson
: returns jira api response body as an objectgetResultWithoutPagination
: Paginates through jira's response until there are no more records left and returns the accumulated responses as an object
api/services/JiraClient
's instance obtained with ioc.getService('JiraClient')
is a Jira Api client wrapper to be used outside an instance's http request lifecyle such as scheduled jobs.
Use this class' http method wrappers to interact with Jira's api providing a clientKey and JiraClient
will look up the right information from AddonSettings, sign the request and return the resulting request's response body in a promise.
command | purpose |
---|---|
dev | Starts the stack locally according to the AC_OPTS config in .env |
dev-debug | same as dev but with node's --inspection enabled and listening on port 9229 |
test | Runs automated tests |
cover | Runs automated tests and outputs test coverage with istambul |
db | Alias to knex |
migrate | Runs the latest migrations |
create-migration <migration-name> |
Creates an empty database migration on /db/migrations |
build | Creates production build in api/dist/ |
prod | Starts production build by running node api/dist/src/app.js |
Default create-react-app scripts