Article Store

This app provides an HTTP API for creating, maintaining and reading articles.

An article is an RDF graph, where the root node is a http://schema.org/Article. We can encode an article in JSON-LD:

{
  "@context": "http://schema.org/",
  "@id": "http://example.com/my-article-store/articles/1234567890",
  "@type": "Article",
  "name": "My article"
}

The API uses the Hydra vocabulary as its hypermedia format. It also follows the Libero API specification.

It's written in TypeScript, uses the Koa framework, and various RDF/JS libraries.

The app persists articles in a PostgreSQL database.

Further reading

• Libero API Specification
• RDF 1.1 Primer
• Hydra Core Vocabulary
• RDF JavaScript Libraries
  • Data Model Specification
  • Dataset Specification

Table of contents

1. Installation
   1. Running an Article Store
      1. Using the Docker CLI
      2. Using Docker Compose
   2. Configuration
2. Development
   1. Running the app
   2. Running the tests
   3. API testing
   4. Linting
3. Contributing
4. Getting help
5. License

Installation

You can find the app on Docker Hub: liberoadmin/article-store.

As it is still under heavy development, there are not yet tagged releases. An image is available for every commit.

Running an Article Store

Using the Docker CLI

1. Start a PostgreSQL container by executing:

   docker run -d --name article-store-database \
     -e "POSTGRES_DB=article-store" \
     -e "POSTGRES_USER=user" \
     postgres:11.5-alpine

2. Run the database creation with an ephemeral Article Store container:

   docker run --rm \
     --link article-store-database \
     -e "DATABASE_HOST=article-store-database" \
     -e "DATABASE_NAME=article-store" \
     -e "DATABASE_USER=user" \
     liberoadmin/article-store:latest npm run initdb

3. Run an Article Store container and link it to the database container:

   docker run \
     --link article-store-database \
     -e "DATABASE_HOST=article-store-database" \
     -e "DATABASE_NAME=article-store" \
     -e "DATABASE_USER=user" \
     -p 8080:8080 \
     liberoadmin/article-store:latest

4. Access the Article Store entry point:

   curl --include http://localhost:8080/

Using Docker Compose

1. Create a file called docker-compose.yml:

   version: '3.4'
   
   services:
   
     db:
       image: postgres:11.5-alpine
       environment:
         POSTGRES_DB: article-store
         POSTGRES_USER: user
    
     initdb:
       image: liberoadmin/article-store:latest
       command: >
         /bin/sh -c '
           while ! nc -z db 5432 ; do sleep 1 ; done
           npm run initdb
         '
       environment:
         DATABASE_HOST: db
         DATABASE_NAME: article-store
         DATABASE_USER: user
    
     app:
       image: liberoadmin/article-store:latest
       environment:
         DATABASE_HOST: db
         DATABASE_NAME: article-store
         DATABASE_USER: user
       ports:
         - '8080:8080'

2. Bring up the containers

   docker-compose up

3. Access the Article Store entry point:

   curl --include http://localhost:8080/

Configuration

The following environment variables can be set:

DATABASE_HOST

This variable is mandatory is the PostgreSQL hostname.

DATABASE_NAME

This variable is mandatory and is the name of the PostgreSQL database.

DATABASE_USER

This variable is mandatory and is the name of the PostgreSQL user.

DATABASE_PASSWORD

This variable is optional and is the password of the PostgreSQL user (default is blank).

DATABASE_PORT

This variable is optional and is the PostgreSQL port (default 5432).

Development

Requirements

• Docker
• GNU Bash
• GNU Make
• Node.js

The project contains a Makefile which uses Docker Compose for development and testing.

You can find the possible commands by executing:

make help

Running the app

To build and run the app for development, execute:

make dev

You can now access the entry point at http://localhost:8080, or view the console at http://localhost:8081.

Rebuilding the container

Code is attached to the containers as volumes so most updates are visible without a need to rebuild the container. However, changes to NPM dependencies, for example, require a rebuild. So you may need to execute

make build

before running further commands.

Running the tests

We use Jest to test the app. You can run it by executing:

make test

You can also run the tests in separate suites:

make unit-test
make integration-test

Integration tests have a @group integration annotation, and can access a PostgreSQL instance.

API testing

You can validate the API using the Hydra validator:

make api-validate

And test it using Hypertest:

make api-test

Linting

We lint the app with ESLint. You can run it by:

make lint

You can fix problems, where possible, by executing:

make fix

Contributing

Pull requests and other contributions are more than welcome. Please take a look at the contributing guidelines for further details.

Getting help

• Report a bug or request a feature on GitHub.
• Ask a question on the Libero Community Slack.
• Read the code of conduct.

License

We released this software under the MIT license. Copyright © 2019 eLife Sciences Publications, Ltd.