- Docker
- Java (v21)
Normal builds resolve dependencies from Maven Central and do not require credentials. GitHub Packages credentials are only needed when resolving a dependency version that has not reached Maven Central yet, such as a SNAPSHOT or pre-release org.vechain:indexer-core.
For local Gradle builds, create a GitHub Personal Access Token (classic) with the read:packages scope and add the following to ~/.gradle/gradle.properties:
gpr.user=your-github-username
gpr.key=your-github-patFor Docker builds, put those same properties in gradle/docker.gradle.properties or pass another readable file with GRADLE_PROPERTIES_FILE=/path/to/gradle.properties make build-image. The default Docker properties file is git-ignored and excluded from the Docker build context.
- To see a list of all available commands, run
make help - After starting the application, the swagger will be made available at
http://localhost:8080
-
Copy env files for the two packages
./package/<package>/.env.exampleto./package/<package>/.envand fill in the values for your environment. They should work as-is for docker -
Run:
make start
- No need to copy the environment files if you are using IntelliJ. The default variables should connect to the infrastructure using localhost variables
- Run:
make pg-up- Go to IndexerApplication.kt inside IntelliJ and run/debug:
Every indexer writes to PostgreSQL. make pg-up starts it on localhost:5432 as database
vechain; roles indexer and api, both with password password. make pg-psql opens a
shell, make pg-clean drops the data.
There are 6 indexers and 6 corresponding APIs. Each indexer can be run in isolation or all together. There is no dependency between indexers for this reason. Each indexer and API pair can be enabled using the corresponding spring profile.
transactions- enabled withtransactionsprofilenfts- enabled withnftsprofiletransfers- enabled withtransfersprofilehistory- enabled withhistoryprofile
As you can see from the list above, the block indexer offers the option to proxy to the Thor node. This is useful if you want the convenience of the Block endpoints without the overhead of indexing the data.
- Run all the tests:
make test- There are 4 packages that can be tested (
api,common,e2e,indexer) - This will run all tests in a package (unit, integration and E2E)
- Run (example for
api):
make test-api
make test-common
make test-indexer
make test-e2e- Running E2E tests will spin up all the docker infrastructure before the test and tears it down after completion.
This is useful for testing the entire system, but it is slow. If you need to debug these tests, it is recommended to
spin up
the network manually using
make clean startand remove the taskspreE2eandpostE2etasks in./packages/e2e/build.gradle.kts(here)
Use the schema-driven harness when you need to validate the public API in a deployed environment. It fetches the OpenAPI document from /api-docs, runs Schemathesis-based checks across every documented operation, and fails if any response exceeds 2 000 ms (override by setting MAX_RESPONSE_MILLISECONDS).
- Local run:
packages/api/scripts/run_api_schema_tests.sh [dead|live|<base-url>] [--base-url <base-url>](defaults to the dead environment). Installschemathesislocally first, for examplepip install "schemathesis>=3.19,<4". - Both colours are reached through CloudFront; the ALB hostnames themselves accept nothing but distribution traffic. Dead is
https://mainnet.dead.veworld.vechain.organdhttps://testnet.dead.veworld.vechain.org, which follow the colour swap automatically. - GitHub Action: trigger API Tests from the Actions tab and choose the target environment, or provide a full base URL override. The workflow uses the same script and publishes Schemathesis logs and JUnit XML as artifacts.
Compares every documented operation between a network's live colour (baseline) and its dead colour (candidate), so a release is checked against the API it replaces.
- Pick the network, not the URLs: API Regression Tests takes
network(mainnetortestnet), andpackages/api/scripts/networks.pyresolves both colours and the Thor node from it. - Each network brings its own chain data.
test_values.jsonholds what is network-independent — ignored paths, page sizes, enum filters — andtest_values.<network>.jsonholds that chain's addresses and ids, laid over it at run time. Most values are re-seeded from the live colour before each run; the files are the fallback. - Run a subset with
tests: a suite name (stargate,b3tr,transfers, …) or a path regex.packages/api/scripts/run_regression_tests.sh --list-suitesprints the names; empty runs all 92 operations. - Local run:
NETWORK=testnet packages/api/scripts/run_regression_tests.sh --path-filter stargate. SetRATE_LIMIT_BYPASS_TOKENso the WAF does not throttle a full run.
RDS keeps 7 days of automated snapshots of every Postgres instance. Recovery of a colour is a restore from the other colour's newest snapshot, which the workflow below drives.
For snapshot-native recovery of the current dead prod color, use the Restore Dead Prod From Live Snapshots workflow. It rebuilds the dead colour's Postgres instances from the live colour's newest automated RDS snapshots.
RDS cannot restore into an existing instance, so each one is replaced from the snapshot under the same identifier — that is the only operation allowed to destroy a Postgres instance, and every other plan is refused by a guard in Plan or Apply Terraform. A net whose live instance does not exist yet is skipped, leaving the dead colour's own data alone. A restored instance lazy-loads its pages from S3, so the job starts a pg-prewarm ECS task per net and reports its ARN; reads stay slow until it stops, which takes hours on mainnet.
This workflow does not stop or start ECS services. The dead environment must already be quiesced before restore. Use the Stop or Start Dead Prod Environment Services workflow first, then run the restore, then start services again once the restore summary looks correct.
Recommended sequence:
- Run Stop or Start Dead Prod Environment Services with
stop. - Run Restore Dead Prod From Live Snapshots. To restore Postgres from a specific snapshot — a manual one taken before a risky operation, or a rehearsal against the dead colour's own data — pass it as
pg_snapshot_main/pg_snapshot_test. - Review the restore summary artifact: the RDS snapshot and prewarm task per net.
- Run Stop or Start Dead Prod Environment Services with
start. - Run the schema or regression tests against the dead environment before switching traffic.
An image's identity is the hash of its Docker build context, printed by make content-hash
(.github/workflows/scripts/content_hash.sh). Each service is hashed separately over the shared
build files plus packages/common and its own package, which is what .dockerignore lets into the
context.
The PR build resolves the hash with the default branch's copy of that script, so a branch cannot
rename its own content into a tag a later release would reuse. It pushes content.<hash> to GHCR and
points pr.<n>.<sha> at it. A release build
re-tags the same manifest instead of building whenever that hash is already published — so a
terraform-, workflow- or docs-only release does no Docker work at all, and a release that touched
only the API leaves the indexer image alone.
A deploy carries this through: it reads the tag each service is actually running on the target
colour — resolved through the ECS service, because a task definition family's latest revision may be
one no rollout ever completed — hashes that tag's tree, and pins the service to it when the hash
matches the release. Only
services that changed are promoted to ECR and only their task definitions move, so the deploy has no
diff for the rest. Terraform receives the four tags (net x service) as image_version_override
rather than an in-place edit of the environment yaml. The step summary lists what was pinned and
why.
APP_VERSION is therefore not baked into the image; it comes from the ECS task definition at
runtime, so cutting a new version does not change image content. The trade-off is that a release
reusing an image does not pick up new Alpine packages — the base image tag is in the hash, so a
Renovate base bump is what refreshes them. Dispatch the GHCR publish with force_rebuild to rebuild
without one.
To deploy, run the Deploy workflow from the version tag you want to deploy, leaving target at auto. Both networks deploy together. The run works out which colour the release should go to and pauses at a Confirm job whose name states the plan, for example "Deploy v.1.2.3 to prod-green (dead), restoring from prod-blue snapshots first". The Plan Release job summary has the reasoning and the per-service image tags. Approve it to proceed. To do something else, reject it (nothing has been applied) and re-dispatch with target set to live or dead.
The plan follows three rules:
- A running dead colour is the one being staged, so it gets the release.
- A cold dead colour and an indexer unchanged against live: live takes the release directly, with no indexing gap.
- A cold dead colour and a changed indexer: the dead colour gets the release after its Postgres instances are restored from the latest live snapshots. A changed indexer on live pauses indexing while it restarts, and a cold colour's data is stale.
target: live is refused for a changed indexer. skip_restore only skips the restore: the colour indexes on from whatever its Postgres instances hold, which for a stopped colour is a stale checkpoint, not genesis. A reindex from genesis is an indexer.version bump (see AGENTS.md "Triggering an Indexer Resync"), not a skipped restore.
One deploy applies every stack — shared infra, observability, the CloudFront distributions, the restore when needed, and the application — in dependency order, so a stack with no change is a no-op rather than a run someone has to remember. AGENTS.md "One Deploy Applies Every Stack" has the order and the reasoning.
A deploy to the dead colour finishes with a Next steps summary. Traffic stays where it was until you run the Switch Live Environment workflow with network all, which also publishes the draft release.
Do that once every indexer on both networks reports fully synced; the summary links the Grafana "blocks behind" panel for that colour and the dead API's indexed head (https://mainnet.dead.veworld.vechain.org/api/v1/blocks?size=1 and the testnet equivalent). A restored colour catches up in hours; a reindex from genesis takes days. If in doubt about which colour is currently live, run the Identify Live/Dead Environments workflow with the default arguments.
Following the DNS switch, please wait at least 48 hours before tearing down the old live (now dead) environment. This is to allow any remote DNS caches to update to the new live environment.
The dead colour doubles as a testing environment: it is an exact replica of live, database included. To put a release on it regardless of what the plan would pick, dispatch the Deploy workflow with target: dead. A cold colour is restored from the live snapshots first unless skip_restore is ticked. Merging to main deploys nothing. While the dead colour is running, auto sends every release to it, so tear it down or switch to it when testing is done.
When testing is complete, or when a DNS switch has migrated traffic from one environment to the other, the dead environment can be safely torn down until needed again. To do this, run the Cluster Destroy workflow, and select the appropriate environment when prompted.
Leave the dead CloudFront workspace in place. A torn-down colour leaves its origin record pointing at a placeholder, so the distributions return errors until the colour is redeployed — but they cost nothing idle, and keeping them avoids re-issuing the certificate every cycle.
Further details on the CICD process can be found here
