{"id":18436059,"url":"https://github.com/codenotary/immugw","last_synced_at":"2025-07-24T12:40:43.717Z","repository":{"id":43040655,"uuid":"289924448","full_name":"codenotary/immugw","owner":"codenotary","description":null,"archived":false,"fork":false,"pushed_at":"2023-11-06T13:01:15.000Z","size":485,"stargazers_count":24,"open_issues_count":8,"forks_count":4,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-04-05T20:33:14.869Z","etag":null,"topics":["communication","cryptographic","immudb","immutability","rest-api","restful"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/codenotary.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2020-08-24T12:41:12.000Z","updated_at":"2025-03-22T13:14:02.000Z","dependencies_parsed_at":"2023-11-06T14:27:19.060Z","dependency_job_id":"5eebfb1f-d1b1-4770-88ae-4299e83a3932","html_url":"https://github.com/codenotary/immugw","commit_stats":null,"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codenotary%2Fimmugw","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codenotary%2Fimmugw/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codenotary%2Fimmugw/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codenotary%2Fimmugw/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/codenotary","download_url":"https://codeload.github.com/codenotary/immugw/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247725571,"owners_count":20985724,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["communication","cryptographic","immudb","immutability","rest-api","restful"],"created_at":"2024-11-06T06:10:13.182Z","updated_at":"2025-04-07T20:32:31.528Z","avatar_url":"https://github.com/codenotary.png","language":"Go","readme":"\u003c!--\n---\n\ntitle: \"immugw\"\n\ncustom_edit_url: https://github.com/codenotary/immudb/edit/master/README.md\n---\n\n--\u003e\n\n# immugw [![License](https://img.shields.io/github/license/codenotary/immudb)](LICENSE) \u003cimg align=\"right\" src=\"img/Black%20logo%20-%20no%20background.png\" height=\"47px\" /\u003e\n\n[![Build Status](https://travis-ci.com/codenotary/immudb.svg?branch=master)](https://travis-ci.com/codenotary/immudb)\n[![Go Report Card](https://goreportcard.com/badge/github.com/codenotary/immugw)](https://goreportcard.com/report/github.com/codenotary/immugw)\n[![Slack](https://img.shields.io/badge/join%20slack-%23immutability-brightgreen.svg)](https://slack.vchain.us/)\n[![Discuss at immudb@googlegroups.com](https://img.shields.io/badge/discuss-immudb%40googlegroups.com-blue.svg)](https://groups.google.com/group/immudb)\n[![Immudb Careers](https://img.shields.io/badge/careers-We%20are%20hiring!-blue?style=flat)](https://immudb.io/careers/)\n\n\n**immugw** is the intelligent REST proxy that connects to immudb and provides a RESTful interface for applications. We recommend to run immudb and immugw on separate machines to enhance security\n\n\n#### Build the binaries yourself\n\nTo build the binaries yourself, simply clone this repo and run\n\n```\nmake all\n```\n\n#### immugw first start\n\n##### Run immugw binary\n\n```bash\n# run immugw in the foreground\n./immugw\n```\n##### Run immugw as a service\n\nService installation and management are supported on Linux, Windows, OSX and FreeBSD operating systems.\n\n```\n# install immugw service\n./immuadmin service immugw install\n\n# check current immugw service status\n./immuadmin service immugw status\n\n# stop immugw service\n./immuadmin service immugw stop\n\n# start immugw service\n./immuadmin service immugw start\n```\n\nThe linux service is using the following defaults:\n\n| File or configuration   | location                   |\n| ----------------------- | -------------------------- |\n| executable              | /usr/sbin/immugw           |\n| all configuration files | /etc/immugw                |\n| pid file                | /var/lib/immugw/immugw.pid |\n| log files               | /var/log/immugw            |\n\nThe FreeBSD service is using the following defaults:\n\n| File or configuration   | location            |\n| ----------------------- | ------------------- |\n| executable              | /usr/sbin/immugw    |\n| all configuration files | /etc/immugw         |\n| pid file                | /var/run/immugw.pid |\n| log files               | /var/log/immugw     |\n\nThe Windows service is using the following defaults:\n\n| File or configuration   | location                             |\n| ----------------------- | ------------------------------------\n| executable              | Program Files\\Immugw\\immugw.exe      |\n| configuration file      | ProgramData\\Immugw\\config\\immugw.toml|\n| all data files          | ProgramData\\Immugw\\                  |\n| pid file                | ProgramData\\Immugw\\config\\immugw.pid |\n| log file                | ProgramData\\Immugw\\config\\immugw.log |\n\n\n\nSimply run `./immugw -d` to start immugw on the same machine as immudb (test or dev environment) or pointing to the remote immudb system ```./immugw --immudb-address \"immudb-server\"```.\n\nIf you want to stop immugw în that case you need to find the process `ps -ax | grep immugw` and then `kill -15 \u003cpid\u003e`. Windows PowerShell would be `Get-Process immugw* | Stop-Process`.\n\n```bash\nimmu gateway: a smart REST proxy for immudb - the lightweight, high-speed immutable database for systems and applications.\nIt exposes all gRPC methods with a REST interface while wrapping all SAFE endpoints with a verification service.\n\nEnvironment variables:\n  IMMUGW_ADDRESS=0.0.0.0\n  IMMUGW_PORT=3323\n  IMMUGW_IMMUDB_ADDRESS=127.0.0.1\n  IMMUGW_IMMUDB_PORT=3322\n  IMMUGW_DIR=.\n  IMMUGW_PIDFILE=\n  IMMUGW_LOGFILE=\n  IMMUGW_DETACHED=false\n  IMMUGW_MTLS=false\n  IMMUGW_SERVERNAME=localhost\n  IMMUGW_AUDIT=false\n  IMMUGW_AUDIT_INTERVAL=5m\n  IMMUGW_AUDIT_USERNAME=immugwauditor\n  IMMUGW_AUDIT_PASSWORD=\n  IMMUGW_AUDIT_SIGNATURE=ignore\n  IMMUGW_PKEY=\n  IMMUGW_CERTIFICATE=\n  IMMUGW_CLIENTCAS=\n\nUsage:\n  immugw [flags]\n  immugw [command]\n\nAvailable Commands:\n  help        Help about any command\n  version     Show the immugw version\n\nFlags:\n  -a, --address string            immugw host address (default \"0.0.0.0\")\n      --audit                     enable audit mode (continuously fetches latest root from server, checks consistency against a local root and saves the latest root locally)\n      --audit-interval duration   interval at which audit should run (default 5m0s)\n      --audit-password string     immudb password used to login during audit; can be plain-text or base64 encoded (must be prefixed with 'enc:' if it is encoded)\n      --audit-username string     immudb username used to login during audit (default \"immugwauditor\")\n      --certificate string        server certificate file path (default \"./tools/mtls/4_client/certs/localhost.cert.pem\")\n      --clientcas string          clients certificates list. Aka certificate authority (default \"./tools/mtls/2_intermediate/certs/ca-chain.cert.pem\")\n      --config string             config file (default path are configs or $HOME. Default filename is immugw.toml)\n  -d, --detached                  run immudb in background\n      --dir string                program files folder (default \".\")\n  -h, --help                      help for immugw\n  -k, --immudb-address string     immudb host address (default \"127.0.0.1\")\n  -j, --immudb-port int           immudb port number (default 3322)\n      --logfile string            log path with filename. E.g. /tmp/immugw/immugw.log\n  -m, --mtls                      enable mutual tls\n      --pidfile string            pid path with filename. E.g. /var/run/immugw.pid\n      --pkey string               server private key path (default \"./tools/mtls/4_client/private/localhost.key.pem\")\n  -p, --port int                  immugw port number (default 3323)\n      --servername string         used to verify the hostname on the returned certificates (default \"localhost\")\n\nUse \"immugw [command] --help\" for more information about a command.\n\n```\n\n### Docker\n\n**immugw**  is also available as docker images on dockerhub.com.\n\n| Component  | Container image                                |\n| ---------- | ---------------------------------------------- |\n| immugw     | https://hub.docker.com/r/codenotary/immugw     |\n\n#### Run immugw\n\n```\ndocker run -it -d -p 3323:3323 --name immugw --env IMMUGW_IMMUDB_ADDRESS=immudb codenotary/immugw:latest\n```\n\n\n#### Build the container images yourself\n\nIf you want to build the container images yourself, simply clone this repo and run\n\n```\ndocker build -t myown/immugw:latest -f Dockerfile .\n```\n\n## Why immugw\n\n**immugw** provides a simple solution to interact with immudb with REST protocol, without taking in charge the merkle tree root hash file management and concurrency related complexity.\n\n#### immugw communication\n\n**immugw**  proxies REST client communication and gRPC server interface. For security purposes immugw should not run on the same server as immudb. The following diagram shows how the communication works:\n\n![immugw communication explained](img/immugw-diagram.png)\n\n### API Documentation\n\nYou can find the swagger schema here:(https://github.com/codenotary/immugw/blob/master/swagger.json).  If you want to run the Swagger UI, simply run the following Docker command after you cloned the immugw repo, or the json file:\n\ndocker run -it -p 8081:8080 --name swagger-immugw -v ${PWD}/swagger.json:/openapi.json -e SWAGGER_JSON=/openapi.json  swaggerapi/swagger-ui\n\n### CURL examples\n\n#### Login\n```shell script\ncurl --location --request POST '127.0.0.1:3323/login' \\\n--header 'Authorization;' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{\n    \"user\": \"aW1tdWRi\",\n    \"password\": \"aW1tdWRi\"\n}'\n```\n#### Use Database\n```shell script\ncurl --location --request GET '127.0.0.1:3323/db/use/defaultdb' \\\n--header 'Content-Type: application/json' \\\n--header 'Authorization: {{token}}'\n```\n#### Login\n```shell script\ncurl --location --request POST '127.0.0.1:3323/login' \\\n--header 'Authorization;' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{\n    \"user\": \"aW1tdWRi\",\n    \"password\": \"aW1tdWRi\"\n}'\n```\n#### Verified Set\n```shell script\ncurl --location --request POST '127.0.0.1:3323/db/{database_name}/verified/set' \\\n--header 'Content-Type: application/json' \\\n--header 'Authorization: {{token}}' \\\n--data-raw '{\n  \"setRequest\": {\n    \"KVs\": [\n      {\n        \"key\": \"a2V5MQ==\",\n\t   \"value\": \"dmFsMQ==\"\n      }\n    ]\n  }\n}'\n```\n#### Verified Get\n```shell script\ncurl --location --request POST '127.0.0.1:3323/db/{database_name}/verified/get' \\\n--header 'Content-Type: application/json' \\\n--header 'Authorization: {{token}}' \\\n--data-raw '{\n  \"keyRequest\": {\n    \"key\": \"a2V5MQ==\"\n  }\n}'\n```\n#### Verified Reference\n```shell script\ncurl --location --request POST '127.0.0.1:3323/db/{database_name}/verified/setreference' \\\n--header 'Content-Type: application/json' \\\n--header 'Authorization: {{token}}' \\\n--data-raw '{\n  \"referenceRequest\": {\n    \"key\": \"dGFnMQ==\",\n    \"referencedKey\": \"a2V5MQ==\",\n    \"atTx\": \"0\"\n  }\n}'\n```\n#### Verified ZAdd\n```shell script\ncurl --location --request POST '127.0.0.1:3323/db/{database_name}/verified/zadd' \\\n--header 'Content-Type: application/json' \\\n--header 'Authorization: {{token}}' \\\n--data-raw '{\n  \"zAddRequest\": {\n    \"set\": \"c2V0MQ==\",\n    \"score\": 15.5,\n    \"key\": \"a2V5MQ==\",\n    \"atTx\": \"0\"\n  }\n}'\n```\n#### ZScan\n```shell script\ncurl --location --request POST '127.0.0.1:3323/db/{database_name}/zscan' \\\n--header 'Content-Type: application/json' \\\n--header 'Authorization: {{token}}' \\\n--data-raw '{\n  \"set\": \"c2V0MQ==\"\n}'\n```\n#### History\n```shell script\ncurl --location --request POST '127.0.0.1:3323/db/{database_name}/history' \\\n--header 'Authorization: {{token}}' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{\n  \"key\": \"a2V5NQ==\"\n}'\n```\n#### Verified Transaction\n```shell script\ncurl --location --request GET '127.0.0.1:3323/db/{database_name}/verified/tx/1' \\\n--header 'Content-Type: application/json' \\\n--header 'Authorization: {{token}}'\n```\n#### SQL Exec\n```shell script\ncurl --location --request POST '127.0.0.1:3323/db/{database_name}/sqlexec' \\\n--header 'Authorization: {{token}}' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{\n    \"sql\":\"CREATE TABLE mytable23 (id INTEGER, amount INTEGER, total INTEGER, title VARCHAR, content BLOB, isPresent BOOLEAN, PRIMARY KEY id)\"\n}'\n```\n\n#### SQL Exec insert\n```shell script\ncurl --location --request POST '127.0.0.1:3323/db/{database_name}/sqlexec' \\\n--header 'Authorization: v2.public.eyJkYXRhYmFzZSI6IjUiLCJleHAiOiIyMDIxLTEwLTI4VDE4OjU1OjAyKzAyOjAwIiwic3ViIjoiaW1tdWRiIn3-aNUXqydajYFR9Aa7-q40JepLuA0tsPXeR1nRo75jA1H45RZZU9Twt6EVi-4bS4gpzeQcRNEdJs8U5oM5urcM.aW1tdWRi' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{\n    \"sql\":\"INSERT INTO myTable23 (id, amount, title, content, isPresent) VALUES (2, 1000, '\\''title 1'\\'', x'\\''626C6F6220636F6E74656E74'\\'', true)\"\n}'\n```\n\u003e byte arrays need to be hex encoded\n#### SQL Query\n```shell script\ncurl --location --request POST '127.0.0.1:3323/db/{database_name}/sqlquery' \\\n--header 'Authorization: {{token}}' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{\n    \"sql\":\"SELECT * from mytable23;\"\n}'\n```\n\n#### SQL Verified sql row\nIts possible also to tamperproof verify a SQL row.\n```shell script\ncurl --location --request POST '127.0.0.1:3323/db/{database_name}/verified/row' \\\n--header 'Authorization: v2.public.eyJkYXRhYmFzZSI6IjUiLCJleHAiOiIyMDIxLTEwLTI4VDE4OjU1OjAyKzAyOjAwIiwic3ViIjoiaW1tdWRiIn3-aNUXqydajYFR9Aa7-q40JepLuA0tsPXeR1nRo75jA1H45RZZU9Twt6EVi-4bS4gpzeQcRNEdJs8U5oM5urcM.aW1tdWRi' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{\n    \"row\": {\n            \"columns\": [\n                \"(testdb1.mytable23.id)\",\n                \"(testdb1.mytable23.amount)\",\n                \"(testdb1.mytable23.total)\",\n                \"(testdb1.mytable23.title)\",\n                \"(testdb1.mytable23.content)\",\n                \"(testdb1.mytable23.ispresent)\"\n            ]\n            },\n            \"values\": [\n                {\n                    \"n\": \"2\"\n                },\n                {\n                    \"n\": \"1000\"\n                },\n                {\n                    \"null\": null\n                },\n                {\n                     \"s\": \"title 1\"\n                },\n                {\n                    \"bs\": \"YmxvYiBjb250ZW50\"\n                },\n                {\n                    \"b\": true\n                }\n            ],\n        \"table\": \"mytable23\",\n        \"pkValues\": [\n            {\n                \"n\": \"2\"\n            }\n        ]\n      }'\n```\n\u003e byte arrays need to be b64 encoded\n#### Logout\n```shell script\ncurl --location --request POST '127.0.0.1:3323/logout' \\\n--header 'Authorization: {{token}}' \\\n--header 'Content-Type: application/json'\n```\n\n\n## License\n\nimmugw is [Apache v2.0 License](LICENSE).\n\nimmudb re-distributes other open-source tools and libraries - [Acknowledgements](https://github.com/codenotary/immudb/blob/master/ACKNOWLEDGEMENTS.md).\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcodenotary%2Fimmugw","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcodenotary%2Fimmugw","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcodenotary%2Fimmugw/lists"}