Docker PostgREST Swagger Example

John Lombardo

Nov 26, 2020

Introduction

This example docker compose app makes it easy to try out postgREST using docker. It's derived from the postgREST tutorials 0 and 1. It ends up being a bit more complicated than you might expect because postgREST does not add the securityDefinitions to the swagger JSON that it generates. To get around this, I added a proxy nginx server that stuffs the necessary JSON into the result that postgREST generates. I hope to remove this hack in the near future when the postgREST is fixed.

So the stack for this example is:

swagger
nginx acting as a proxy for...
... postgREST
postgres

The following tutorials and web sites were helpful in making this example

The postgREST tutorials: tutorial0 and tutorial1
postgREST docker config
jwt.io

tl;dr

To run it simply:

git clone https://github.com/johnnylambada/docker-postgrest-swagger-sample.git
cd docker-postgrest-swagger-sample
./start.sh

The start.sh script sets up the host environment then fires off a docker-compose to start the four docker containers that comprise this app. When the app is fully up, you'll see a line that looks like this:

postgrest_1        | Connection successful

At that point you can visit http://localhost:8080 and you'll see the swagger screen.

Press the Authorize button and an authorization dialog will appear.
Paste the following in the "value" box:

Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjQ3NjIxMDY4NTYsImlhdCI6MTYwNjQxMTY1Niwicm9sZSI6InRvZG9fdXNlciJ9.rDSsIAyahco2KySYs6m8Mj4M3oHwC3ncf86itJdLahc

Then click Authorize then Close.

You can now hit all of the APIs using swagger. First, hit the GET /todos API to see that there are only two todo items. Then add another todo item using the POST /todos api. When you do use the POST api, make sure you trim the sample JSON to just:

{
  "task": "type something here"
}

Once you've done that, re-execute the GET /todos API to see that there is a new task.

The configuration files

There are only four files involved involved in this app.

`start.sh`

The start.sh app is quite simple. It removes any previous database, defines the TODO_SECRET used to generate JWT tokens, then starts the docker containers using docker-compose.

`todo.sql`

The todo.sql file creates the api schema that is exposed through postgREST. It also creates the todo table and various roles. This is all explained well in the postgREST tutorials #0 and #1.

`docker-compose.yml`

This file sets up the docker containers used in this example.

`nginx.conf`

This file sets up the nginx proxy that re-writes postgREST's JSON output to include the necessary securityDefinitions section. Without this, the Authorize button would not appear on the swagger web page.

johnnylambada / docker-postgrest-swagger-sample