Skip to main content

Setup Iglu Server

For more information on the architecture of the Iglu server, please read the technical documentation.

Available on Terraform Registry​

A Terraform module is available which deploys an Iglu Server on AWS EC2 without the need for this manual setup.

1. Run the Iglu server​

Iglu Server is published on Docker Hub.

$ docker pull snowplow/iglu-server:0.12.0

The application is configured by passing a hocon file on the command line:

$ docker run --rm \
  -v $PWD/config.hocon:/iglu/config.hocon \
  snowplow/iglu-server:0.12.0 --config /iglu/config.hocon

Alternatively, you can download and run a jar file from the github release.

$ java -jar iglu-server-0.12.0.jar --config /path/to/config.hocon

Here is an example of a minimal configuration file:

{
  "database": {
    "host": "postgres"
    "dbname": "igludb"
    "username": "postgres"
    "password": "mysecret"
  }

  "superApiKey": "bb7b7503-40d3-459c-943a-f8d31a6f5638"
}

See the configuration reference for a complete description of all parameters.

We also provide a docker-compose.yml to help you get started.

2. Initialize the database​

With a fresh install you need to manually create the database:

$ psql -U postgres -c "CREATE DATABASE igludb"

And then use the setup command of the iglu server to create the database tables:

$ docker run --rm \
  -v $PWD/config.hocon:/iglu/config.hocon \
  snowplow/iglu-server:0.12.0 setup --config /iglu/config.hocon

3. Use the API key generation service​

The super API key you put in the configuration file is able to generate further API keys for your clients through the API key generation service.

To generate a pair of read and write API keys for a specific vendor prefix, simply send a POST request to this URL using your super API key in an apikey HTTP header:

HOST/api/auth/keygen

For example:

curl \
  HOST/api/auth/keygen \
  -X POST \
  -H 'apikey: your_super_apikey' \
  -d '{"vendorPrefix":"com.acme"}'

Note: From 0.6.0+ the vendor prefix should be vendorPrefix within a JSON body however prior to this it was vendor_prefix as a query parameter.

You should receive a JSON response like this one:

{
  "read": "an-uuid",
  "write": "another-uuid"
}

If you need to revoke a specific API key, you can do so by sending a DELETE request to the following endpoint:

HOST/api/auth/keygen?key=some-uuid

For example:

curl \
  HOST/api/auth/keygen \
  -X DELETE \
  -H 'apikey: your_super_apikey' \
  -d 'key=some-uuid'

You should now be all set up to use the Iglu server, if you would like to know more about the Iglu server, please read the technical documentation.

Dummy mode​

Since 0.6.0 Iglu Server supports new dummy DB mode. In this mode, Server does not require persistent storage as PostgreSQL and stores all data in memory. Use this for debug purposes only, all your data will be lost after restart.

To enable dummy mode, you need to set database.type setting to "dummy".

Dummy Iglu Server works with single hardcoded master API key - 48b267d7-cd2b-4f22-bae4-0f002008b5ad, which you can use to upload your schemas and create new api keys.

Logging​

Iglu Server uses SLF4J Simple Logger underneath. Which can be configured via system properties.

For example:

$ iglu-server-0.12.0.jar \
  -Dorg.slf4j.simpleLogger.logFile=server.log                                   # In order to redirect logs \
  -Dorg.slf4j.simpleLogger.log.org.http4s.blaze.channel.nio1.SelectorLoop=warn  # To suppress very verbose SelectorLoop output

On debug loglevel SchemaService will print all HTTP requests and responses.