diff --git a/README.md b/README.md index ba19c865..a72c67a4 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,16 @@ # Alephium explorer backend +Alephium's explorer backend is an indexer that provides a RESTful API to query the Alephium blockchain. + +It serves https://explorer.alephium.org/ as well as our wallets. + + +## Prerequisites + +- Java (11 or 17 is recommended) +- [PostgreSQL](https://www.postgresql.org) +- A running [full node](full-node/getting-started.md) + ## Development ### 1. Install the dependencies @@ -27,13 +38,15 @@ You need to have [Postgresql][postgresql] and [sbt][sbt] installed in your syste postgres=# CREATE DATABASE explorer; ``` -### 3. Start the server +### 3. Run explorer-backend +#### 3.1 Using `sbt` +##### Start the server ```shell sbt app/run ``` -### 4. Single Jar +##### Build the Jar ```shell sbt app/assembly @@ -41,19 +54,59 @@ sbt app/assembly The resulting assembly file will appear in `app/target/scala-2.13/` directory. +#### 3.2 Run the released jar + +Download the lastest jar in our [release page](https://github.com/alephium/explorer-backend/releases/latest) + +Run it with: + +```shell +java -jar explorer-backend-x.x.x.jar +``` + +### 4. Configuration + +Configuration file at [`/app/src/main/resources/application.conf`](https://github.com/alephium/explorer-backend/blob/master/app/src/main/resources/application.conf) can be customized using environment variables + +Everything can be overridden in two ways: + +#### `user.conf` file + +You can change the config in the `~/.alephium-explorer-backend/user.conf` file. e.g: + +```conf +alephium { + explorer { + port = 9191 //Change default 9090 port + } +} +``` + +#### Environment variables + +Every value has a corresponding environment variable, you can find all of them in the [application.conf](https://github.com/alephium/explorer-backend/blob/master/app/src/main/resources/application.conf). e.g: + +```shell +export EXPLORER_PORT=9191 +``` ### 5. Restore archived database Syncing all data from scratch can take a while, you can choose to start from a snapshot instead. -Snapshots are available at https://archives.alephium.org/ -Download the `explore-db` dump you want and simply run: + +Alephium [archives repository](https://archives.alephium.org) contains the snapshots for explorer backend database. +The snapshot can be loaded in the postgresql database of the explorer-backend at the first run, using the command below. + +* Make sure to use the network you want to load the snapshot for, and the correct database name and user. +* The database must be created before running the command and must be empty. ```shell -psql database_name < dump_file +alephium_network=mainnet +pg_user=postgres +database=explorer +curl -L $(curl -L -s https://archives.alephium.org/archives/${alephium_network}/explorer-db/_latest.txt) | gunzip -c | psql -U $pg_user -d $database ``` -Please note that `database_name` must have been created before, see point 2 on how to do it. - ### Querying hashes Hash strings are stored as [bytea][bytea]. To query a hash string in @@ -151,38 +204,3 @@ apiMappings ++= ) ) ``` - -## Node Customization - -The steps below are for developers who want to reference a full node on another computer, such as a Raspberry Pi, that is on the same subnet. - -### Explorer: `/app/src/main/resources/application.conf` - -```shell -blockflow { - host = "full-node-ip-address" - port = 12973 - - direct-clique-access = false - direct-clique-access = ${?BLOCKFLOW_DIRECT_CLIQUE_ACCESS} - - network-id = 0 - network-id = ${?BLOCKFLOW_NETWORK_ID} - groupNum = 4 - api-key = "full-node-api-key" -} -``` - -### Full Node: `user.conf` - -```shell -alephium.api.api-key = "full-node-api-key" -alephium.api.network-interface = "0.0.0.0" - -alephium.network.bind-address = "0.0.0.0:9973" -alephium.network.internal-address = "full-node-ip-address:9973" -alephium.network.coordinator-address = "full-node-ip-address:9973" -``` - - -