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.

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

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

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

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

Access the Article Store entry point:
```
curl --include http://localhost:8080/
```

Using Docker Compose

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'

Bring up the containers
```
docker-compose up
```
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

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.

libero / article-store Goto Github PK

article-store's Introduction

Article Store

Table of contents

Installation

Running an Article Store

Using the Docker CLI

Using Docker Compose

Configuration

DATABASE_HOST

DATABASE_NAME

DATABASE_USER

DATABASE_PASSWORD

DATABASE_PORT