immu Gateway

immugw is a REST proxy that connects to immudb and provides a RESTful interface for applications. We recommend running immudb and immugw on separate machines to enhance security.

You may download the immugw binary from the latest releases on Github . Once you have downloaded immugw, rename it to immugw, make sure to mark it as executable, then run it. The following example shows how to obtain v1.3.0 for linux amd64:

1$ wget https://github.com/codenotary/immugw/releases/download/v1.3.0/immugw-v1.3.0-linux-amd64
2$ mv immugw-v1.3.0-linux-amd64 immugw
3$ chmod +x immugw
4
5# run help to find out about possible arguments
6$ ./immugw help
7
8# and run immugw in the background
9$ ./immugw -d --immudb-address {immudb-server-address}

Alternatively, you may pull immudb docker image from DockerHub and run it in a ready-to-use container:

1$ docker run -it -d -p 3323:3323 --name immugw --env IMMUGW_IMMUDB_ADDRESS={immudb-server-address} codenotary/immugw:latest

Build from sources#

Building binaries requires a Linux operating system.

To build the binaries yourself, simply clone immugw repository and run:

1$ make all

immugw can be cross compiled for different systems and architectures by setting GOOS and GOARCH variables, i.e.:

1GOOS=windows GOARCH=amd64 make all

To build immugw docker container locally:

1docker build -t myown/immugw:latest -f Dockerfile .

Installing with immuadmin#

 1# install immugw service
 2$ ./immugw service install
 3
 4# check current immugw service status
 5$ ./immugw service status
 6
 7# stop immugw service
 8$ ./immugw service stop
 9
10# start immugw service
11$ ./immugw service start

The Linux service is using the following defaults:

Configuration#

immugw can be configured using environment variables, flags or a config file.

• immugw --help shows you all available flags and environment variables.
• /etc/immudb/immugw.toml is used as a default configuration file

RESTful API reference#

You can find the swagger schema here:

swagger immugw

If you want to run the Swagger UI, simply run the following Docker command after you cloned this repo:

1$ wget https://github.com/codenotary/immugw/blob/master/swagger.json
2$ docker run -d -it -p 8081:8080 --name swagger-immugw -v ${PWD}/swagger.json:/openapi.json -e SWAGGER_JSON=/openapi.json  swaggerapi/swagger-ui

immugw as auditor#

immugw can be also run as auditor.

1$ ./immugw --audit

If you are running immugw as a service, you need to edit /etc/immudb/immugw.toml and add the following section:

1audit = true # false is default
2audit-interval = "5m" # suffixes: "s", "m", "h", examples: 10s, 5m 1h
3audit-username = "" # when immudb authentication is enabled, use read-only user credentials here
4audit-password = "" # and the password