From 4ceae9ae21737b1362d648d47ab5dab5d3e622c6 Mon Sep 17 00:00:00 2001 From: Oleg Lavrovsky <31819+loleg@users.noreply.github.com> Date: Fri, 20 Oct 2023 22:21:32 +0200 Subject: [PATCH] Installation guide (#396) * Docker build local * Preprod merge to main (#353) * Update README.md * Alternative chains support (#281) * add new smart contract addresses on goerli and mumbai networks, update settings * fix dependencies * update circle checks go version * update readme with chains list * test negative scenario * return goerli cobfig * remove console metamask error (#286) should fix #285 * Update README.md * add console logs on default accounts setup and on sign request * Test autodeploy flow (#290) * Update README.md * add console logs on default accounts setup and on sign request * Update dependabot.yml * Revised Handbook, added Formulas * Added SECURITY doc * Updated notice as per docs * Handbook on first login #311 * Update dependabot.yml (#378) * Update dependabot.yml * Update dependabot.yml * Installation docs --------- Co-authored-by: Oleg Lavrovsky Co-authored-by: Afonina Tatiana <99973342+tafonina@users.noreply.github.com> --- .github/dependabot.yml | 3 +- README.md | 18 --- docker-compose-cnode.override.yml | 22 ---- docs/build_docker.md | 4 +- docs/configure.md | 28 ++++- docs/quickstart.md | 176 ++++++++---------------------- 6 files changed, 75 insertions(+), 176 deletions(-) delete mode 100644 docker-compose-cnode.override.yml diff --git a/.github/dependabot.yml b/.github/dependabot.yml index f16683bd8..e7f2e4717 100644 --- a/.github/dependabot.yml +++ b/.github/dependabot.yml @@ -1,15 +1,16 @@ version: 2 updates: - target-branch: "preprod" # Maintain dependencies for Go - package-ecosystem: "gomod" directory: "/" + target-branch: "preprod" schedule: interval: "weekly" # Maintain dependencies for JS - package-ecosystem: "npm" directory: "/ui/" + target-branch: "preprod" schedule: interval: "weekly" diff --git a/README.md b/README.md index e6fb1302f..0ef165abb 100644 --- a/README.md +++ b/README.md @@ -31,24 +31,6 @@ If you wish to build the project form the source code, follow the instructions i Please read the [Developer Manual](https://doc.proxeus.com) to learn more about the Proxeus platform. -### Infura and SparkPost - -The Proxeus platform currently depends on [Infura](https://infura.io/) for blockchain services. Supported chains include: - -- ethereum: sepolia -- ethereum: goerli -- ethereum: mainnet -- polygon: mumbai -- polygon: mainnet - -Create an account to get an API Keys. These keys need to be added to corresponding environment variables, or entered when deploying a "one-click" instance. - -Proxeus works best with [SparkPost](https://www.sparkpost.com/) for email integration. - -Please note that the domain you set up on SparkPost MUST match the **reply-to** e-mail address that you configure in the next step in order to create accounts and receive e-mails on your instance. - -If all goes well, Proxeus should be available at http://localhost:1323. The next step will be to [configure](docs/configure.md) your instance for the first time. - ## Contributing As an open-source project, we welcome any kind of community involvement, whether that is by contributing code, reporting issues or engaging in insightful discussions. Especially, we are looking forward to receiving contributions for external workflow nodes. diff --git a/docker-compose-cnode.override.yml b/docker-compose-cnode.override.yml deleted file mode 100644 index f142301ab..000000000 --- a/docker-compose-cnode.override.yml +++ /dev/null @@ -1,22 +0,0 @@ ---- -# With a configuration like this, you can enable nodes in production. -# This file is an override and needs to be used like this: -# -# docker-compose -f docker-compose.yml -f docker-compose-cloud.override.yml -f docker-compose-cnode.override.yml up - -version: '3.7' - -services: - node-crypto-forex-rates: - networks: - - reverse-proxy - labels: - com.centurylinklabs.watchtower.enable: "true" - environment: - # Replace values for reverse-proxy - VIRTUAL_HOST: ${NODE_CRYPTO_FOREX_RATES_VIRTUAL_HOST:-proxeus.example.com} - VIRTUAL_PORT: 8011 - # Replace values for letsencrypt - LETSENCRYPT_HOST: ${NODE_CRYPTO_FOREX_RATES_VIRTUAL_HOST:-proxeus.example.com} - LETSENCRYPT_EMAIL: ${LETSENCRYPT_EMAIL:-admin@example.com} - restart: unless-stopped diff --git a/docs/build_docker.md b/docs/build_docker.md index b156c78ed..c98bec556 100644 --- a/docs/build_docker.md +++ b/docs/build_docker.md @@ -97,10 +97,10 @@ For deployment, a `docker-compose-cloud.override.yml` file is provided which inc docker-compose -f docker-compose.yml -f docker-compose-cloud.override.yml up ``` -You may also want to include custom nodes. There is a sample configuration which can be started like this: +You may also want to include custom nodes. There is a sample configuration which can be started like this (also possibly in combination with `docker-compose-cloud`): ``` -docker-compose -f docker-compose.yml -f docker-compose-cloud.override.yml -f docker-compose-cnode.override.yml up +docker-compose -f docker-compose.yml -f docker-compose-example.override.yml up ``` See `docker-compose-extra.override.yml` for examples with several other nodes. diff --git a/docs/configure.md b/docs/configure.md index 4d0a4433f..e18efd5ab 100644 --- a/docs/configure.md +++ b/docs/configure.md @@ -9,7 +9,13 @@ configuration below as an example. ## Infura API Key -## Blockchain contract address +Generate an [Infura API Key](https://infura.io) + +## Blockchain File Storage contract address + +You can switch between the networks using the environment configuration `PROXEUS_BLOCKCHAIN_NET`. +For your convenience, a smart contract is deployed on several networks at the following addresses: + ### Sepolia ``` 0x9bc518Fd070BE3DBB07399261688015744a7FB02 @@ -17,6 +23,26 @@ configuration below as an example. [Verify on Etherscan](https://goerli.etherscan.io/address/0x66FF4FBF80D4a3C85a54974446309a2858221689#code) + +### Mainnet +``` +0xf63e471d8cbc57517c37c39c35381a385628e012 +``` +[Verify on Etherscan](https://etherscan.io/address/0xf63e471d8cbc57517c37c39c35381a385628e012) + +### Polygon-mumbai +``` +0x00119d8C02bbC4c1231D054BB2813792B4411Ed5 +``` +[Verify on Etherscan](https://mumbai.polygonscan.com/address/0x00119d8C02bbC4c1231D054BB2813792B4411Ed5) + + +### Polygon +``` +0x60970BeFda93464A105DD21Dc6a30B69C5B5c6e4 +``` +[Verify on Etherscan](https://polygonscan.com/address/0x60970BeFda93464A105DD21Dc6a30B69C5B5c6e4) + Alternatively: deploy your own smart contract from [ProxeusFS.sol](https://github.com/ProxeusApp/storage-app/blob/master/spp/eth/solidity/ProxeusFS.sol) ## Email from diff --git a/docs/quickstart.md b/docs/quickstart.md index cbf2e5d74..9f21c5b5b 100644 --- a/docs/quickstart.md +++ b/docs/quickstart.md @@ -1,154 +1,66 @@ # Quick Start -A brief installation guide. Find more details and explanation of the configuration settings in [configure.md](configure.md). +This document is a brief installation guide, with links to further details to get started with Proxeus. We hope that you, too, will enjoy working with our product! Please remember to star us on GitHub drop us any questions or feedback in the [Discussion Forum](https://github.com/ProxeusApp/community/discussions). + _"Proxeus is a platform for quick and convenient document digitalization, signing, processing, and distribution. It allows users to keep their important documents secure and registered on the blockchain. Proxeus empowers anyone to create blockchain applications and is available for free as an open-source project." --[S-Pro](https://s-pro.io/)_ +## One-Click Installation -**By installing and using the Proxeus software you agree with the terms of the [Proxeus License Agreement](LICENSE).** +Proxeus is primarily a Web application, intended for access with a web browser. The [Proxeus Association](https://proxeus.org) maintains a demo instances you can use to test the product, and can recommend a service provider to help you or your business get set up. There is also a prototype [desktop application](https://github.com/ProxeusApp/storage-app/blob/master/docs/overview.md). +In addition to the developer guidelines below, several "one-click" deployment configurations are available for select cloud platforms: -_"Proxeus is a platform for quick and convenient document digitalization, signing, processing, and distribution. It allows users to keep their important documents secure and registered on the blockchain. Proxeus empowers anyone to create blockchain applications and is available for free as an open-source project." --[S-Pro](https://s-pro.io/)_ +- [Docker Compose](docs/docker.md) +- [Linode StackScript](deploy/linode/README.md) +- [DigitalOcean Droplet](deploy/digitalocean/README.md) -**By installing and using the Proxeus software you agree with the terms of the [Proxeus License Agreement](LICENSE).** +You will still need API keys for Infura and Sparkpost, as [detailed below](#get-keys). -## Install docker and docker-compose +Join the [Discussions](https://github.com/ProxeusApp/community/discussions/3) if you are interested in seeing additional providers on this list. -The quickest way to try Proxeus is to use `docker-compose`. +Please read the [Developer Manual](https://doc.proxeus.com) to learn more about developing for the Proxeus platform. -1. [Install Docker Engine](https://docs.docker.com/install/) -2. [Install docker-compose](https://docs.docker.com/compose/install/) +**By installing and using the Proxeus software you agree with the terms of the [Proxeus License Agreement](https://github.com/ProxeusApp/proxeus-core/blob/main/LICENSE).** -## Get API Keys for Infura and SparkPost +## Installing from Source + +You can access the source code of this application on the [Proxeus repository](https://github.com/ProxeusApp) on GitHub (a mirror is available on [Codeberg/Proxeus](https://codeberg.org/proxeus/). + +If you wish to build the project from source, follow the instructions in [Build all](build_all.md). + +The quickest way to try Proxeus is to use `docker compose`: + +1. Install [Docker Engine](https://docs.docker.com/install/) or [Docker Desktop](https://docs.docker.com/desktop/) +2. Install [Docker Compose](https://docs.docker.com/compose/install/) if you are not using Docker Desktop +3. Get API keys for Infura and Sparkpost as [detailed below](#get-keys) +4. Configure your environment variables by copying `.env.example` to `.env` and modifying it +5. Start the application using `docker compose up` + +Please make sure that you always pull Docker images from the official `proxeus` DockerHub repository and that you are using the latest version. -The Proxeus platform depends on [Infura](https://infura.io/) and [SparkPost](https://www.sparkpost.com/) -for Ethereum and email integration respectively. +A `docker-compose.yml` file and some other possible configuraitons are in the root folder of the proxeus-core repository. See [Configuration settings](configure.md) and [Building with Docker](build_docker.md) for more details. + + + +## Get API Keys for Infura and SparkPost The Proxeus platform depends on [Infura](https://infura.io/) and [SparkPost](https://www.sparkpost.com/). Please create an account on those platforms to get API Keys. These keys need to be added to corresponding environment variables, or entered when deploying a "one-click" instance. -## Proxeus Demo Smart Contract - -For your convenience, a demo smart contract is deployed on several networks at the following address: - -``` -0x66FF4FBF80D4a3C85a54974446309a2858221689 -``` -[Verify on Etherscan](https://goerli.etherscan.io/address/0x66FF4FBF80D4a3C85a54974446309a2858221689#code) - -`PROXEUS_BLOCKCHAIN_NET=goerli` - -### Ethereum: Mainnet - -``` -0xf63e471d8cbc57517c37c39c35381a385628e012 -``` -[Verify on Etherscan](https://etherscan.io/address/0xf63e471d8cbc57517c37c39c35381a385628e012) - -`PROXEUS_BLOCKCHAIN_NET=main` - -### Polygon: mumbai - -``` -0x00119d8C02bbC4c1231D054BB2813792B4411Ed5 -``` -[Verify on Etherscan](https://mumbai.polygonscan.com/address/0x00119d8C02bbC4c1231D054BB2813792B4411Ed5) - -`PROXEUS_BLOCKCHAIN_NET=polygon-mumbai` - -### Polygon: main - -``` -0x60970BeFda93464A105DD21Dc6a30B69C5B5c6e4 -``` -[Verify on Etherscan](https://polygonscan.com/address/0x60970BeFda93464A105DD21Dc6a30B69C5B5c6e4) - -`PROXEUS_BLOCKCHAIN_NET=polygon` - -## Create a docker-compose.yml file - -**Note: Please make sure that you always pull Docker images from the official `proxeus` DockerHub repository and that you are using the latest version.** - -User the example below as your `docker-compose.yml` file: - -``` ---- -version: '3.7' - -networks: - xes-platform-network: - name: xes-platform-network - -services: - platform: - image: proxeus/proxeus-core:latest - container_name: xes-platform - depends_on: - - document-service - networks: - - xes-platform-network - restart: unless-stopped - environment: - TZ: Europe/Zurich - PROXEUS_PLATFORM_DOMAIN: "${PROXEUS_PLATFORM_DOMAIN:-http://xes-platform:1323}" - PROXEUS_DOCUMENT_SERVICE_URL: "http://document-service:2115/" - PROXEUS_ENCRYPTION_SECRET_KEY: "${PROXEUS_ENCRYPTION_SECRET_KEY}" - PROXEUS_BLOCKCHAIN_CONTRACT_ADDRESS: "${PROXEUS_BLOCKCHAIN_CONTRACT_ADDRESS}" - PROXEUS_INFURA_API_KEY: "${PROXEUS_INFURA_API_KEY}" - PROXEUS_SPARKPOST_API_KEY: "${PROXEUS_SPARKPOST_API_KEY}" - PROXEUS_EMAIL_FROM: "${PROXEUS_EMAIL_FROM:-no-reply@example.com}" - PROXEUS_AIRDROP_WALLET_FILE: "${PROXEUS_AIRDROP_WALLET_FILE:-/root/.proxeus/settings/airdropwallet.json}" - PROXEUS_AIRDROP_WALLET_KEY: "${PROXEUS_AIRDROP_WALLET_KEY:-/root/.proxeus/settings/airdropwallet.key}" - PROXEUS_DATABASE_ENGINE: "${PROXEUS_DATABASE_ENGINE:-storm}" - PROXEUS_DATABASE_URI: "${PROXEUS_DATABASE_URI:-mongodb://root:root@mongo:27017}" - PROXEUS_TEST_MODE: "${PROXEUS_TEST_MODE:-false}" - PROXEUS_ALLOW_HTTP: "${PROXEUS_ALLOW_HTTP:-false}" - ports: - - "1323:1323" - volumes: - - ${PROXEUS_DATA_DIR:-./data}/proxeus-platform/data:/data/hosted - - ${PROXEUS_DATA_DIR:-./data}/proxeus-platform/settings:/root/.proxeus/settings - - document-service: - image: proxeus/document-service:latest - container_name: xes_document_service - networks: - - xes-platform-network - restart: unless-stopped - environment: - TZ: Europe/Zurich - ports: - - "2115:2115" - volumes: - - ${PROXEUS_DATA_DIR:-./data}/document-service/logs:/document-service/logs - - ${PROXEUS_DATA_DIR:-./data}/document-service/fonts:/document-service/fonts -``` - -## Start Proxeus - -Run the following command in the directory containing your `docker-compose.yml` file (Linux and OSX): -``` -export PROXEUS_EMAIL_FROM= -export PROXEUS_INFURA_API_KEY= -export PROXEUS_SPARKPOST_API_KEY= -export PROXEUS_ENCRYPTION_SECRET_KEY= -export PROXEUS_BLOCKCHAIN_CONTRACT_ADDRESS=0x1d3e5c81bf4bc60d41a8fbbb3d1bae6f03a75f71 -export PROXEUS_ALLOW_HTTP=true -docker-compose up -``` - -Proxeus should be available at http://localhost:1323 - -**Note:** that your system configuration at this point will be reflected in the local configuration database under `data/proxeus-platform/settings/main.json`. Any future changes to the configuration must be made here - the environment variables will not be propagated, unless you delete this file to reset the deployment. +We use [Infura](https://infura.io/) for blockchain services. Supported chains include: -The next step is to [configure](configure.md) your instance for the first time. +- Ethereum: sepolia, goerli, mainnet +- Polygon: mumbai, mainnet -## Troubleshooting +Create an account on [SparkPost](https://www.sparkpost.com/) for email integration. -Are you having an issue getting the server up and running, or logging into the console? +- Please note that the domain you set up on SparkPost MUST match the **reply-to** e-mail address that you configure in the next step in order to create accounts and receive e-mails on your instance. + +## Next steps + +Proxeus should at this point be available at http://localhost:1323 or the IP address of your new cloud machine. + +The next step is to [configure](configure.md) your instance for the first time. -1. **Check the logs for any apparent errors.** In particular, an error in your API or contract keys might result in a message like `failed to dial for eth events`. -2. **See if you have issues in the JS console.** Using your web browser's development console, see if you have any issues that may relate to connectivity issues like your server's firewall. -3. **Check the docs.** This guide is the best place to go. Search on [GitHub](https://github.com/search?q=org%3AProxeusApp+houston%2C+we+have+a+problem&type=issues) for your error message. -4. **Ask for help.** Write a note in the [Q&A discussion](https://github.com/orgs/ProxeusApp/discussions/categories/q-a), or put up a [bug report](https://github.com/ProxeusApp/proxeus-core/issues). -5. **Hire a DevOp.** The [Proxeus Association](https://proxeus.org) can recommend a competent developer/system administrator to try to solve your problem. +To learn more about Smart Contracts using Solidity, see the documentation in the [proxeus-contract](https://github.com/ProxeusApp/proxeus-contract). For detailed information about token setup, check the [XES-Payment](xes-payment.md) project. Software architecture and other details are in the [Developer Manual](develop.md). For creating a custom node, visit [External workflow nodes](external_workflow_nodes.md).