diff --git a/DEPLOYING.md b/DEPLOYING.md new file mode 100644 index 0000000..00191a8 --- /dev/null +++ b/DEPLOYING.md @@ -0,0 +1,27 @@ +# Deploying + +This guide will provide a high-level outline of the steps required to stand up a new instance of `p8e-cee-api` **for use against an [actual Provenance network](https://github.com/provenance-io/provenance#active-networks)**. + +It is highly recommended one first goes through the process of standing up a local environment for `p8e-cee-api` per the instructions in the [README](README.md) to understand the various processes involved and how they communicate with each other. + +## Services + +A connection will be needed to the following services, which can be either an existing deployment you have permission to connect to or a self-hosted instance: + +- `p8e-cee-api` + - Use one of the [published Docker images](https://hub.docker.com/r/provenanceio/p8e-cee-api/), or build an image from source if you need to make your own customizations +- [Object store](https://github.com/provenance-io/object-store)s which contains or replicates the data in the [metadata scopes](https://developer.provenance.io/docs/pb/modules/metadata-module#scope-data-structures) you will be operating on + - See the [README](https://github.com/provenance-io/object-store#backends) for the currently supported storage backends + - See an [example of an object store gateway](https://github.com/FigureTechnologies/object-store-gateway/) as a possible way to access an object store +- Key Management System (KMS) + - `p8e-cee-api` consumes the [provenance-io/kms-connector](https://github.com/provenance-io/kms-connector) library to allow for fetching of Provenance account keys from any plugin defined there (as of writing, there is default support for [Vault](https://www.vaultproject.io/) & tentative support for Fortanix and Keystone) + +## Common Pitfalls +### Environment Variables +`p8e-cee-api` is a Spring application which sets various application properties based on [definitions determined by the active Spring profile](https://github.com/provenance-io/p8e-cee-api/tree/174f066aa91b510cdb777f1b09010693b34fe838/service/src/main/resources). +Any environment variable defined in the active Spring profile's `*.properties` file will need to be defined in order for the service to run. + +Data types should be inferrable from the corresponding Kotlin classes annotated with `@ConfigurationProperties`. + +Some environment variables, e.g. `DART_UUID` and `PORTFOLIO_MANAGER_ADDRESS`, exist only to tailor to common users of `p8e-cee-api`, and as such, can be deleted if not used. + - ⚠️ Note that doing this deletion requires modification to Kotlin/Spring code and then building the Docker image from the modified source. diff --git a/README.md b/README.md index 1e91d20..2abfe41 100644 --- a/README.md +++ b/README.md @@ -2,18 +2,22 @@ `p8e-cee-api` stands for the Provenance Contract Execution Environment API. -The `p8e-cee-api` allows for operations against the encrypted object store, with included support for multi-store replication, and creating and broadcasting scoped transmissions to the Provenance Blockchain. +`p8e-cee-api` allows for operations against [BlockVault](https://developer.provenance.io/docs/pb/p8e/overview/) (formerly nicknamed "p8e"), with included support for replication across multiple object stores along with other miscellaneous utilities to facilitate creating and broadcasting scoped transmissions to the Provenance Blockchain. ## Status [![stability-release-candidate](https://img.shields.io/badge/stability-pre--release-48c9b0.svg)](https://github.com/mkenney/software-guides/blob/master/STABILITY-BADGES.md#release-candidate) [![Latest Release][release-badge]][release-latest] +[![Docker Hub badge][dockerhub-badge]][dockerhub] [![License][license-badge]][license-url] [![LOC][loc-badge]][loc-report] [release-badge]: https://img.shields.io/github/v/tag/provenance-io/p8e-cee-api.svg [release-latest]: https://github.com/provenance-io/p8e-cee-api/releases/latest +[dockerhub-badge]: https://img.shields.io/docker/pulls/provenanceio/p8e-cee-api +[dockerhub]: https://hub.docker.com/r/provenanceio/p8e-cee-api/ + [license-badge]: https://img.shields.io/github/license/provenance-io/p8e-cee-api.svg [license-url]: https://github.com/provenance-io/p8e-cee-api/blob/main/LICENSE @@ -22,9 +26,12 @@ The `p8e-cee-api` allows for operations against the encrypted object store, with ## Overview -The [Asset Originator's Guide](https://docs.provenance.io/integrating/asset-originators-guide) provides contextual support for the varied use cases supported by this API. Having a fundamental understanding of the Provenance Blockchain is recommended. +The [BlockVault integration guide](https://developer.provenance.io/docs/pb/integrating/integrating-with-p8e/) provides contextual support for the varied use cases supported by this API. Having a fundamental understanding of the Provenance Blockchain & BlockVault is recommended. + +## Deploying/Hosting +[Instructions for how to deploy the service](DEPLOYING.md) -## Local Setup +## Local Development To run this service locally, be sure to have [Docker](https://www.docker.com/) installed: ``` @@ -74,14 +81,14 @@ Then, run the service - either via an Intellij run configuration or via the comm ./gradlew bootRun ``` -## Swagger Documentation +### Swagger Documentation once the service is running, try out some local calls using Swagger! http://localhost:8080/p8e-cee-api/secure/docs/api.html -## Publishing p8e Contracts Locally +### Publishing p8e Contracts Locally As a convenience, you can publish contracts from another repository without leaving this project in the command line.