From 95a9393101b8e2875edf376f80dde0f27a3bcc32 Mon Sep 17 00:00:00 2001 From: Tomasz Kopacki Date: Thu, 11 Jun 2026 13:07:31 +0200 Subject: [PATCH 1/7] Highlight benefits of ENSNode self-hosting --- .../src/content/docs/docs/self-host/index.mdx | 35 ++++++------------- 1 file changed, 11 insertions(+), 24 deletions(-) diff --git a/docs/ensnode.io/src/content/docs/docs/self-host/index.mdx b/docs/ensnode.io/src/content/docs/docs/self-host/index.mdx index b3a240a15..14c66f92b 100644 --- a/docs/ensnode.io/src/content/docs/docs/self-host/index.mdx +++ b/docs/ensnode.io/src/content/docs/docs/self-host/index.mdx @@ -6,22 +6,15 @@ description: Decide whether to self-host ENSNode and understand the architecture import { LinkCard } from "@astrojs/starlight/components"; import EnsDbSnapshotsTeaser from "@components/molecules/EnsDbSnapshotsTeaser.astro"; -This page will help you decide whether to self-host ENSNode or use the hosted instances. Includes architecture overview of the ENSNode stack (ENSIndexer, ENSDb, ENSRainbow, ENSApi). +Get extra benefits compared to using one of the publicly [Hosted Instances](/docs/hosted-instances). Having your own ENSNode instance allows you to: -:::note -Follow these guides to deploy an ENSNode instance to the cloud. -::: - -Running your own ENSNode instance is helpful for those that wish to: - -- Maintain control over their own infrastructure -- Ensure control over their own availability and uptime guarantees -- Customize ENSNode's behavior -- Own the resulting Postgres index for custom queries or `JOIN`s - -:::caution[Private Networking] -Note that because ENSNode makes many label healing requests to ENSRainbow while indexing, it's _imperative_ that they be on the same local network to minimize request time. -::: +- **Select [ENS Namespace](/docs/hosted-instances#ens-namespaces)**: choose which ENS protocol deployment ENSNode will provide data for (ex: `mainnet` or `sepolia`). Great for testing and development. +- **Select [ENSNode Plugins](/docs/hosted-instances#ensnode-plugins)**: activate only the plugins you need for your use cases, reducing resource usage and improving performance. +- **Tailor "name healing" coverage**: apply selected [label set](/docs/services/ensrainbow/usage/available-label-sets#available-label-sets) that fits your needs for [ENSRainbow to perform "name healing"](/docs/services/ensrainbow#how-ensrainbow-helps). +- **Index ENS data the way you want**: customize indexing logic and indexed data model stored in your own [ENSDb instance](/docs/integrate/integration-options/ensdb) by implementing an [ENSDb Writer](/docs/integrate/integration-options/ensdb-writers). +- **Build custom APIs and data pipelines**: implement an [ENSDb Reader](/docs/integrate/integration-options/ensdb-readers) to build apps using your own ENSDb instance as a source of truth for ENS live data. +- **Control versioning and updates**: choose when to update your ENSNode instance to new versions, giving you control over when to adopt new features or breaking changes. +- **Manage uptime**: apply your own strategies for ensuring high availability and uptime guarantees. ### Bootstrap from a snapshot (coming soon) @@ -43,14 +36,8 @@ Self-hosting today means standing up a fresh ENSNode instance from zero and wait href="/docs/self-host/scalability" /> -### Deploying with Docker - -The Docker deployment option provides the easiest way to run the full ENSNode suite of services both locally and in the cloud. - - - -### Deploying with Terraform +### Deployment options -An example Terraform deployment reference is available, showing an example of deploying the full ENSNode suite on Render with AWS managed domain names. + - + From 03d44dcf0a91ca3cf31bc92ddbb6caca9d72a16f Mon Sep 17 00:00:00 2001 From: Tomasz Kopacki Date: Thu, 11 Jun 2026 13:57:33 +0200 Subject: [PATCH 2/7] Apply AI PR feedback --- docs/ensnode.io/src/content/docs/docs/hosted-instances.mdx | 4 ++-- docs/ensnode.io/src/content/docs/docs/self-host/index.mdx | 6 +++--- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/ensnode.io/src/content/docs/docs/hosted-instances.mdx b/docs/ensnode.io/src/content/docs/docs/hosted-instances.mdx index 5fe581916..4f1ad2f42 100644 --- a/docs/ensnode.io/src/content/docs/docs/hosted-instances.mdx +++ b/docs/ensnode.io/src/content/docs/docs/hosted-instances.mdx @@ -56,11 +56,11 @@ Each ENSNode instance is also configured for a specific set of activated [ENSNod The activated plugins determine the specific indexed data model and data records ENSIndexer will produce in ENSDb and therefore which APIs and data records ENSApi will make available to query. -### ENSv1 + ENSv2 Instances +## ENSv1 + ENSv2 Instances These instances are associated with an ENS namespace that has upgraded to ENSv1 + ENSv2 and demonstrate the latest support in ENSNode for ENSv1 and ENSv2 being concurrently activated together. -#### ENSNode 'v2 Sepolia' +### ENSNode 'v2 Sepolia' :::caution[v2 Sepolia] The `sepolia-v2` namespace is undergoing active development by the ENS Labs team who is continuing to release updated ENSv2 contracts. It should be considered experimental. diff --git a/docs/ensnode.io/src/content/docs/docs/self-host/index.mdx b/docs/ensnode.io/src/content/docs/docs/self-host/index.mdx index 14c66f92b..bff0b2e0a 100644 --- a/docs/ensnode.io/src/content/docs/docs/self-host/index.mdx +++ b/docs/ensnode.io/src/content/docs/docs/self-host/index.mdx @@ -6,15 +6,15 @@ description: Decide whether to self-host ENSNode and understand the architecture import { LinkCard } from "@astrojs/starlight/components"; import EnsDbSnapshotsTeaser from "@components/molecules/EnsDbSnapshotsTeaser.astro"; -Get extra benefits compared to using one of the publicly [Hosted Instances](/docs/hosted-instances). Having your own ENSNode instance allows you to: +Self-hosting provides extra benefits compared to using one of the publicly [Hosted Instances](/docs/hosted-instances). Having your own ENSNode instance allows you to: - **Select [ENS Namespace](/docs/hosted-instances#ens-namespaces)**: choose which ENS protocol deployment ENSNode will provide data for (ex: `mainnet` or `sepolia`). Great for testing and development. - **Select [ENSNode Plugins](/docs/hosted-instances#ensnode-plugins)**: activate only the plugins you need for your use cases, reducing resource usage and improving performance. -- **Tailor "name healing" coverage**: apply selected [label set](/docs/services/ensrainbow/usage/available-label-sets#available-label-sets) that fits your needs for [ENSRainbow to perform "name healing"](/docs/services/ensrainbow#how-ensrainbow-helps). +- **Tailor "name healing" coverage**: apply a [label set](/docs/services/ensrainbow/usage/available-label-sets#available-label-sets) that fits your needs for [ENSRainbow to perform "name healing"](/docs/services/ensrainbow#how-ensrainbow-helps). - **Index ENS data the way you want**: customize indexing logic and indexed data model stored in your own [ENSDb instance](/docs/integrate/integration-options/ensdb) by implementing an [ENSDb Writer](/docs/integrate/integration-options/ensdb-writers). - **Build custom APIs and data pipelines**: implement an [ENSDb Reader](/docs/integrate/integration-options/ensdb-readers) to build apps using your own ENSDb instance as a source of truth for ENS live data. - **Control versioning and updates**: choose when to update your ENSNode instance to new versions, giving you control over when to adopt new features or breaking changes. -- **Manage uptime**: apply your own strategies for ensuring high availability and uptime guarantees. +- **Manage uptime**: apply strategies for ensuring high availability and uptime guarantees. ### Bootstrap from a snapshot (coming soon) From cf7f980660ea24db0e3c65ca96152fc9e3e5ad9e Mon Sep 17 00:00:00 2001 From: Tomasz Kopacki Date: Thu, 11 Jun 2026 20:39:50 +0200 Subject: [PATCH 3/7] Add deployment option: Railway --- .../starlight/sidebar-topics/self-host.ts | 21 +++++++++++++------ .../content/docs/docs/self-host/docker.mdx | 1 - .../src/content/docs/docs/self-host/index.mdx | 4 ++++ .../content/docs/docs/self-host/railway.mdx | 13 ++++++++++++ .../docs/docs/self-host/scalability.mdx | 1 - .../content/docs/docs/self-host/terraform.mdx | 1 - 6 files changed, 32 insertions(+), 9 deletions(-) create mode 100644 docs/ensnode.io/src/content/docs/docs/self-host/railway.mdx diff --git a/docs/ensnode.io/config/integrations/starlight/sidebar-topics/self-host.ts b/docs/ensnode.io/config/integrations/starlight/sidebar-topics/self-host.ts index b164f78a5..9725ac35b 100644 --- a/docs/ensnode.io/config/integrations/starlight/sidebar-topics/self-host.ts +++ b/docs/ensnode.io/config/integrations/starlight/sidebar-topics/self-host.ts @@ -8,12 +8,21 @@ export const selfHostSidebarTopic = { link: "/docs/self-host", }, { - label: "Docker", - link: "/docs/self-host/docker", - }, - { - label: "Terraform", - link: "/docs/self-host/terraform", + label: "Deployment options", + items: [ + { + label: "Docker", + link: "/docs/self-host/docker", + }, + { + label: "Railway", + link: "/docs/self-host/railway", + }, + { + label: "Terraform", + link: "/docs/self-host/terraform", + }, + ], }, { label: "Scalability", diff --git a/docs/ensnode.io/src/content/docs/docs/self-host/docker.mdx b/docs/ensnode.io/src/content/docs/docs/self-host/docker.mdx index 4f8cb5be6..c8f50b46f 100644 --- a/docs/ensnode.io/src/content/docs/docs/self-host/docker.mdx +++ b/docs/ensnode.io/src/content/docs/docs/self-host/docker.mdx @@ -2,7 +2,6 @@ title: Deploying ENSNode with Docker sidebar: label: Docker - order: 1 --- import { LinkCard } from "@astrojs/starlight/components"; diff --git a/docs/ensnode.io/src/content/docs/docs/self-host/index.mdx b/docs/ensnode.io/src/content/docs/docs/self-host/index.mdx index bff0b2e0a..b38cebd89 100644 --- a/docs/ensnode.io/src/content/docs/docs/self-host/index.mdx +++ b/docs/ensnode.io/src/content/docs/docs/self-host/index.mdx @@ -1,6 +1,8 @@ --- title: Self-host ENSNode description: Decide whether to self-host ENSNode and understand the architecture. +sidebar: + label: Overview --- import { LinkCard } from "@astrojs/starlight/components"; @@ -40,4 +42,6 @@ Self-hosting today means standing up a fresh ENSNode instance from zero and wait + + diff --git a/docs/ensnode.io/src/content/docs/docs/self-host/railway.mdx b/docs/ensnode.io/src/content/docs/docs/self-host/railway.mdx new file mode 100644 index 000000000..a48b29b16 --- /dev/null +++ b/docs/ensnode.io/src/content/docs/docs/self-host/railway.mdx @@ -0,0 +1,13 @@ +--- +title: Deploying ENSNode to Railway +--- + +import { LinkCard } from "@astrojs/starlight/components"; + +This guide provides an example of deploying the full ENSNode Alpha instance suite to [Railway](https://railway.app/), a popular cloud hosting provider. It uses the [Railway Templates](https://docs.railway.app/templates) approach, which allows you to apply a pre-configured infrastructure template to your Railway project with a single click. + + diff --git a/docs/ensnode.io/src/content/docs/docs/self-host/scalability.mdx b/docs/ensnode.io/src/content/docs/docs/self-host/scalability.mdx index cd14090fa..6c6363d5d 100644 --- a/docs/ensnode.io/src/content/docs/docs/self-host/scalability.mdx +++ b/docs/ensnode.io/src/content/docs/docs/self-host/scalability.mdx @@ -3,7 +3,6 @@ title: ENSNode Scalability description: Understand how ENSNode's architecture enables horizontal scaling. sidebar: label: Scalability - order: 3 --- import { LinkCard } from "@astrojs/starlight/components"; diff --git a/docs/ensnode.io/src/content/docs/docs/self-host/terraform.mdx b/docs/ensnode.io/src/content/docs/docs/self-host/terraform.mdx index 8c1aef6b5..2aa04595e 100644 --- a/docs/ensnode.io/src/content/docs/docs/self-host/terraform.mdx +++ b/docs/ensnode.io/src/content/docs/docs/self-host/terraform.mdx @@ -2,7 +2,6 @@ title: Deploying ENSNode with Terraform sidebar: label: Terraform - order: 2 --- import { LinkCard } from "@astrojs/starlight/components"; From e66051c8b20ae0c85a318ee7eaded47cdb9c64ed Mon Sep 17 00:00:00 2001 From: Tomasz Kopacki Date: Fri, 12 Jun 2026 14:16:15 +0200 Subject: [PATCH 4/7] Build content about ENSNode Operations for "Self-Hosting" --- docs/ensnode.io/astro.config.mjs | 3 + .../starlight/sidebar-topics/self-host.ts | 29 +++++-- .../{ => deployment-options}/docker.mdx | 0 .../self-host/deployment-options/index.mdx | 14 ++++ .../{ => deployment-options}/railway.mdx | 0 .../{ => deployment-options}/terraform.mdx | 0 .../src/content/docs/docs/self-host/index.mdx | 12 +-- .../operations/critical-workloads.mdx | 75 +++++++++++++++++++ .../docs/self-host/operations/overview.mdx | 16 ++++ .../{ => operations}/scalability.mdx | 0 10 files changed, 137 insertions(+), 12 deletions(-) rename docs/ensnode.io/src/content/docs/docs/self-host/{ => deployment-options}/docker.mdx (100%) create mode 100644 docs/ensnode.io/src/content/docs/docs/self-host/deployment-options/index.mdx rename docs/ensnode.io/src/content/docs/docs/self-host/{ => deployment-options}/railway.mdx (100%) rename docs/ensnode.io/src/content/docs/docs/self-host/{ => deployment-options}/terraform.mdx (100%) create mode 100644 docs/ensnode.io/src/content/docs/docs/self-host/operations/critical-workloads.mdx create mode 100644 docs/ensnode.io/src/content/docs/docs/self-host/operations/overview.mdx rename docs/ensnode.io/src/content/docs/docs/self-host/{ => operations}/scalability.mdx (100%) diff --git a/docs/ensnode.io/astro.config.mjs b/docs/ensnode.io/astro.config.mjs index 9ed94d704..3079fee6d 100644 --- a/docs/ensnode.io/astro.config.mjs +++ b/docs/ensnode.io/astro.config.mjs @@ -90,6 +90,9 @@ export default defineConfig({ "/docs/reference/roadmap": "/docs/integrate/why-ensnode/ensv2-readiness", "/docs/reference/what-is-ensnode": "/docs/integrate/why-ensnode", "/docs/integrate/ensv2-readiness": "/docs/integrate/why-ensnode/ensv2-readiness", + "/docs/self-host/docker": "/docs/self-host/deployment-options/docker", + "/docs/self-host/terraform": "/docs/self-host/deployment-options/terraform", + "/docs/self-host/scalability": "/docs/self-host/operations/scalability", }, env: { schema: { diff --git a/docs/ensnode.io/config/integrations/starlight/sidebar-topics/self-host.ts b/docs/ensnode.io/config/integrations/starlight/sidebar-topics/self-host.ts index 9725ac35b..51070b943 100644 --- a/docs/ensnode.io/config/integrations/starlight/sidebar-topics/self-host.ts +++ b/docs/ensnode.io/config/integrations/starlight/sidebar-topics/self-host.ts @@ -4,29 +4,46 @@ export const selfHostSidebarTopic = { icon: "seti:docker", items: [ { - label: "Overview", + label: "Getting started", link: "/docs/self-host", }, { label: "Deployment options", items: [ + { + label: "Overview", + link: "/docs/self-host/deployment-options", + }, { label: "Docker", - link: "/docs/self-host/docker", + link: "/docs/self-host/deployment-options/docker", }, { label: "Railway", - link: "/docs/self-host/railway", + link: "/docs/self-host/deployment-options/railway", }, { label: "Terraform", - link: "/docs/self-host/terraform", + link: "/docs/self-host/deployment-options/terraform", }, ], }, { - label: "Scalability", - link: "/docs/self-host/scalability", + label: "Operations", + items: [ + { + label: "Overview", + link: "/docs/self-host/operations/overview", + }, + { + label: "Critical workloads 🚨", + link: "/docs/self-host/operations/critical-workloads", + }, + { + label: "Scalability", + link: "/docs/self-host/operations/scalability", + }, + ], }, ], }; diff --git a/docs/ensnode.io/src/content/docs/docs/self-host/docker.mdx b/docs/ensnode.io/src/content/docs/docs/self-host/deployment-options/docker.mdx similarity index 100% rename from docs/ensnode.io/src/content/docs/docs/self-host/docker.mdx rename to docs/ensnode.io/src/content/docs/docs/self-host/deployment-options/docker.mdx diff --git a/docs/ensnode.io/src/content/docs/docs/self-host/deployment-options/index.mdx b/docs/ensnode.io/src/content/docs/docs/self-host/deployment-options/index.mdx new file mode 100644 index 000000000..29d6246bb --- /dev/null +++ b/docs/ensnode.io/src/content/docs/docs/self-host/deployment-options/index.mdx @@ -0,0 +1,14 @@ +--- +title: ENSNode Deployment Options +description: Explore different deployment options for self-hosting ENSNode. +--- + +import { LinkCard } from "@astrojs/starlight/components"; + +ENSNode can be deployed in various ways to fit different needs and preferences. This section provides an overview of the available deployment options for self-hosting ENSNode. + + + + + + diff --git a/docs/ensnode.io/src/content/docs/docs/self-host/railway.mdx b/docs/ensnode.io/src/content/docs/docs/self-host/deployment-options/railway.mdx similarity index 100% rename from docs/ensnode.io/src/content/docs/docs/self-host/railway.mdx rename to docs/ensnode.io/src/content/docs/docs/self-host/deployment-options/railway.mdx diff --git a/docs/ensnode.io/src/content/docs/docs/self-host/terraform.mdx b/docs/ensnode.io/src/content/docs/docs/self-host/deployment-options/terraform.mdx similarity index 100% rename from docs/ensnode.io/src/content/docs/docs/self-host/terraform.mdx rename to docs/ensnode.io/src/content/docs/docs/self-host/deployment-options/terraform.mdx diff --git a/docs/ensnode.io/src/content/docs/docs/self-host/index.mdx b/docs/ensnode.io/src/content/docs/docs/self-host/index.mdx index b38cebd89..c7e2bf9dc 100644 --- a/docs/ensnode.io/src/content/docs/docs/self-host/index.mdx +++ b/docs/ensnode.io/src/content/docs/docs/self-host/index.mdx @@ -38,10 +38,10 @@ Self-hosting today means standing up a fresh ENSNode instance from zero and wait href="/docs/self-host/scalability" /> -### Deployment options +## Deployment options - - - - - + diff --git a/docs/ensnode.io/src/content/docs/docs/self-host/operations/critical-workloads.mdx b/docs/ensnode.io/src/content/docs/docs/self-host/operations/critical-workloads.mdx new file mode 100644 index 000000000..834df277b --- /dev/null +++ b/docs/ensnode.io/src/content/docs/docs/self-host/operations/critical-workloads.mdx @@ -0,0 +1,75 @@ +--- +title: Critical Workloads +description: Understand the critical workloads to consider while choosing infrastructure for self-hosting ENSNode. + +--- + +import { LinkCard } from "@astrojs/starlight/components"; + +Self-hosting ENSNode requires running several critical workloads that are essential for the proper functioning of ENSNode. Understanding these workloads can help you make informed decisions about the infrastructure and resources needed to run your own ENSNode instance effectively. + +## Critical workloads + +ENSNode is responsible for several critical workloads. Understanding these workloads can help you make better decisions about the infrastructure you will need to run your own ENSNode effectively. + +### Indexing historical ENS data (backfill) + +Indexing historical onchain ENS data is the most resource-intensive ENSNode workload. It involves processing and indexing all ENS-related events across multiple chains over multiple years. Deploying an ENSNode instance from scratch requires catching up with the entire history of ENS events. At this stage, you should expect different resource requirements among ENSNode services. + +#### ENSIndexer + +When starting from scratch, the [ENSIndexer](/docs/services/ensindexer) instance may need to fetch and process all historical ENS events from multiple chains across many years. The key bottlenecks at this stage are: + +- **RPC throughput**: fetching historical events requires making a large number of RPC calls to the blockchain, which can be time-consuming and may require a high-throughput RPC provider or multiple providers. Ensure that your RPC provider can handle the volume of requests needed for the initial backfill. +- **Single-threaded CPU performance**: the indexing process is currently single-threaded, so the CPU performance of the machine running ENSIndexer can significantly impact the time it takes to complete the initial backfill. A more powerful CPU can help speed up this process. +- **Fast network connections**: ENSIndexer may require executing some read and write operations for each onchain event being indexed. Collectively, these can add up to a significant amount of network traffic to handle: + - **ENSRainbow reads**: ENSIndexer may need to send a large number of requests to the [ENSRainbow instance](/docs/services/ensrainbow) to perform "name healing", which can be a bottleneck if the network connection is slow. + - **ENSDb writes**: ENSIndexer needs to write indexed data to the ENSDb instance, which can also be a bottleneck if the network connection is slow or if the database server is not optimized for high write throughput. + +#### ENSDb + +The key requirements for the database server hosting the [ENSDb instance](/docs/services/ensdb/concepts/glossary#ensdb-instance) are: + +- **Co-location with the [ENSIndexer](/docs/services/ensindexer) instance**: to minimize requests latency and maximize throughput. +- **High write throughput**: to handle the large volume of write operations during the initial backfill process. This may require optimizing the database configuration for high write performance or using a managed database service that can scale resources as needed. +- **Sufficient disk space**: to store the indexed ENS data. The exact disk space required will depend on multiple factors, for example, the activated [ENSNode Plugins](/docs/hosted-instances#ensnode-plugins) and the [ENS namespace](/docs/services/ensdb#ens-namespace) you choose to index. To give you a rough idea, the ENSNode Alpha hosted instance requires at least `380 GB` of disk space and is expected to grow over time as more future ENS events will need to be indexed. + +#### ENSRainbow + +The key requirements for the [ENSRainbow](/docs/services/ensrainbow) instance are: + +- **Co-location with the [ENSIndexer](/docs/services/ensindexer) instance**: to minimize requests latency and maximize throughput. +- **Sufficient disk space**: to store the ENSRainbow database. The exact disk space required will depend on the label set config you set for the ENSRainbow instance. For example, you may need at least `55 GB` to serve the `searchlight` label set. + +### Indexing live ENS data + +After the initial backfill is complete, the resource requirements for indexing live ENS data are significantly lower as there are way fewer events to process and index at any given time compared to the backfill. The key requirements for indexing live ENS data remain the same when it comes to **Fast network connections** among ENSIndexer, ENSRainbow, and ENSDb, but the overall resource requirements are much more manageable and can be handled by more modest infrastructure. + +### Serving API requests + +ENSNode serves API requests through the [ENSApi](/docs/services/ensapi) instance, which queries the indexed ENS data stored in the [ENSDb instance](/docs/services/ensdb/concepts/glossary#ensdb-instance). Depending on the volume of API requests and the complexity of the queries, you may need to consider scaling your infrastructure to ensure that the ENSApi instance can handle the load and provide fast responses. This may involve optimizing database queries, implementing caching strategies, or scaling the ENSApi instance horizontally by running multiple instances behind a load balancer. + + + +## Recommendations + +### Bootstrap from a snapshot + +Deploying ENSNode from scratch can be costly (i.e. high use of RPC credits) and time-consuming (i.e. it can take several days or weeks to complete the initial backfill). You may wonder: + +- _What if I could avoid fetching all historical onchain events from an RPC Provider?_ +- _What if I could skip the long indexing time?_ + +:::tip[The ENSDb snapshot shortcut] + +You can avoid the resource-intensive initial backfill by bootstrapping from an [ENSDb snapshot](/docs/integrate/integration-options/ensdb-cli#ensdb-snapshots), which includes RPC cache and an indexed state of ENS data up to a certain point in time. This allows ENSIndexer to shorten the backfill process to only the most recent events that occurred after the snapshot point, significantly reducing both the time and cost required to get your ENSNode instance up and running. + +::: + +### Hybrid setup + +To optimize resource usage and costs, you can consider a hybrid setup where the initial backfill is performed on a more powerful machine (e.g. a cloud instance with high CPU performance and fast network connections), and then switch to a more modest machine for indexing live ENS data once the backfill is complete. This approach allows you to efficiently manage resources while ensuring that your ENSNode instance remains responsive and up-to-date with the latest ENS events. diff --git a/docs/ensnode.io/src/content/docs/docs/self-host/operations/overview.mdx b/docs/ensnode.io/src/content/docs/docs/self-host/operations/overview.mdx new file mode 100644 index 000000000..caef07334 --- /dev/null +++ b/docs/ensnode.io/src/content/docs/docs/self-host/operations/overview.mdx @@ -0,0 +1,16 @@ +--- +title: ENSNode Operations +description: Understand how to operate and manage ENSNode deployments. +sidebar: + label: Operations +--- + +import { LinkCard } from "@astrojs/starlight/components"; + +Operating an ENSNode deployment requires understanding the architecture and components of ENSNode, how to monitor and maintain your deployment, and how to scale as your needs grow. This section provides an overview of ENSNode operations, including best practices for deployment, monitoring, and scaling. + +## Deployment Options + + + + diff --git a/docs/ensnode.io/src/content/docs/docs/self-host/scalability.mdx b/docs/ensnode.io/src/content/docs/docs/self-host/operations/scalability.mdx similarity index 100% rename from docs/ensnode.io/src/content/docs/docs/self-host/scalability.mdx rename to docs/ensnode.io/src/content/docs/docs/self-host/operations/scalability.mdx From fc882aed6dcaed36e72bd0bf916d9ad83b70cfbd Mon Sep 17 00:00:00 2001 From: Tomasz Kopacki Date: Fri, 12 Jun 2026 16:26:38 +0200 Subject: [PATCH 5/7] Apply AI PR feedback --- .../starlight/sidebar-topics/self-host.ts | 4 ++++ .../self-host/deployment-options/index.mdx | 18 ++++++++++++--- .../operations/critical-workloads.mdx | 2 +- .../docs/self-host/operations/monitoring.mdx | 8 +++++++ .../docs/self-host/operations/overview.mdx | 22 ++++++++++++++----- 5 files changed, 45 insertions(+), 9 deletions(-) create mode 100644 docs/ensnode.io/src/content/docs/docs/self-host/operations/monitoring.mdx diff --git a/docs/ensnode.io/config/integrations/starlight/sidebar-topics/self-host.ts b/docs/ensnode.io/config/integrations/starlight/sidebar-topics/self-host.ts index 51070b943..4d30ebe93 100644 --- a/docs/ensnode.io/config/integrations/starlight/sidebar-topics/self-host.ts +++ b/docs/ensnode.io/config/integrations/starlight/sidebar-topics/self-host.ts @@ -43,6 +43,10 @@ export const selfHostSidebarTopic = { label: "Scalability", link: "/docs/self-host/operations/scalability", }, + { + label: "Monitoring", + link: "/docs/self-host/operations/monitoring", + }, ], }, ], diff --git a/docs/ensnode.io/src/content/docs/docs/self-host/deployment-options/index.mdx b/docs/ensnode.io/src/content/docs/docs/self-host/deployment-options/index.mdx index 29d6246bb..bb7e45bec 100644 --- a/docs/ensnode.io/src/content/docs/docs/self-host/deployment-options/index.mdx +++ b/docs/ensnode.io/src/content/docs/docs/self-host/deployment-options/index.mdx @@ -7,8 +7,20 @@ import { LinkCard } from "@astrojs/starlight/components"; ENSNode can be deployed in various ways to fit different needs and preferences. This section provides an overview of the available deployment options for self-hosting ENSNode. - + - + - + diff --git a/docs/ensnode.io/src/content/docs/docs/self-host/operations/critical-workloads.mdx b/docs/ensnode.io/src/content/docs/docs/self-host/operations/critical-workloads.mdx index 834df277b..78ea923cb 100644 --- a/docs/ensnode.io/src/content/docs/docs/self-host/operations/critical-workloads.mdx +++ b/docs/ensnode.io/src/content/docs/docs/self-host/operations/critical-workloads.mdx @@ -66,7 +66,7 @@ Deploying ENSNode from scratch can be costly (i.e. high use of RPC credits) and :::tip[The ENSDb snapshot shortcut] -You can avoid the resource-intensive initial backfill by bootstrapping from an [ENSDb snapshot](/docs/integrate/integration-options/ensdb-cli#ensdb-snapshots), which includes RPC cache and an indexed state of ENS data up to a certain point in time. This allows ENSIndexer to shorten the backfill process to only the most recent events that occurred after the snapshot point, significantly reducing both the time and cost required to get your ENSNode instance up and running. +You can avoid the resource-intensive initial backfill by bootstrapping from an [ENSDb snapshot](/docs/integrate/integration-options/ensdb-cli#ensdb-snapshots), which includes RPC cache and an indexed state of ENS data as of a certain date. This allows ENSIndexer to shorten the backfill process to only the most recent events that occurred after the snapshot point, significantly reducing both the time and cost required to get your ENSNode instance up and running. ::: diff --git a/docs/ensnode.io/src/content/docs/docs/self-host/operations/monitoring.mdx b/docs/ensnode.io/src/content/docs/docs/self-host/operations/monitoring.mdx new file mode 100644 index 000000000..cdcd73889 --- /dev/null +++ b/docs/ensnode.io/src/content/docs/docs/self-host/operations/monitoring.mdx @@ -0,0 +1,8 @@ +--- +title: ENSNode Monitoring +description: Learn about monitoring strategies for ENSNode deployments. +--- + +import { LinkCard } from "@astrojs/starlight/components"; + +Monitoring is a critical aspect of operating an ENSNode deployment. It involves tracking the performance, health, and resource usage of your ENSNode instance to ensure it runs smoothly and efficiently. This section provides an overview of monitoring strategies for ENSNode deployments, including best practices and tools to help you keep your ENSNode instance in optimal condition. diff --git a/docs/ensnode.io/src/content/docs/docs/self-host/operations/overview.mdx b/docs/ensnode.io/src/content/docs/docs/self-host/operations/overview.mdx index caef07334..61833ef2b 100644 --- a/docs/ensnode.io/src/content/docs/docs/self-host/operations/overview.mdx +++ b/docs/ensnode.io/src/content/docs/docs/self-host/operations/overview.mdx @@ -7,10 +7,22 @@ sidebar: import { LinkCard } from "@astrojs/starlight/components"; -Operating an ENSNode deployment requires understanding the architecture and components of ENSNode, how to monitor and maintain your deployment, and how to scale as your needs grow. This section provides an overview of ENSNode operations, including best practices for deployment, monitoring, and scaling. +Operating an ENSNode deployment requires understanding the critical workloads that ENSNode is responsible for, as well as the best practices for managing and optimizing these workloads, including monitoring, scaling, and resource management. This section provides an overview of the key operational considerations for running your own ENSNode instance effectively. -## Deployment Options + - - - + + + From 88526dd906ab9dd850ee1cb902df4d8a96ff3911 Mon Sep 17 00:00:00 2001 From: Tomasz Kopacki Date: Fri, 12 Jun 2026 17:36:35 +0200 Subject: [PATCH 6/7] Include a high-level architecture diagram for ENSNode --- .../starlight/sidebar-topics/self-host.ts | 32 +++++++++---------- .../ensnode-high-level-architecture.svg | 4 +++ .../src/content/docs/docs/self-host/index.mdx | 24 +++++--------- .../operations/critical-workloads.mdx | 12 +++---- .../operations/{overview.mdx => index.mdx} | 18 ++++++----- .../docs/self-host/operations/scalability.mdx | 6 ++++ 6 files changed, 49 insertions(+), 47 deletions(-) create mode 100644 docs/ensnode.io/public/ensnode-high-level-architecture.svg rename docs/ensnode.io/src/content/docs/docs/self-host/operations/{overview.mdx => index.mdx} (85%) diff --git a/docs/ensnode.io/config/integrations/starlight/sidebar-topics/self-host.ts b/docs/ensnode.io/config/integrations/starlight/sidebar-topics/self-host.ts index 4d30ebe93..7f6c4ddf7 100644 --- a/docs/ensnode.io/config/integrations/starlight/sidebar-topics/self-host.ts +++ b/docs/ensnode.io/config/integrations/starlight/sidebar-topics/self-host.ts @@ -8,44 +8,44 @@ export const selfHostSidebarTopic = { link: "/docs/self-host", }, { - label: "Deployment options", + label: "Operations", items: [ { label: "Overview", - link: "/docs/self-host/deployment-options", + link: "/docs/self-host/operations", }, { - label: "Docker", - link: "/docs/self-host/deployment-options/docker", + label: "Critical workloads 🚨", + link: "/docs/self-host/operations/critical-workloads", }, { - label: "Railway", - link: "/docs/self-host/deployment-options/railway", + label: "Scalability", + link: "/docs/self-host/operations/scalability", }, { - label: "Terraform", - link: "/docs/self-host/deployment-options/terraform", + label: "Monitoring", + link: "/docs/self-host/operations/monitoring", }, ], }, { - label: "Operations", + label: "Deployment options", items: [ { label: "Overview", - link: "/docs/self-host/operations/overview", + link: "/docs/self-host/deployment-options", }, { - label: "Critical workloads 🚨", - link: "/docs/self-host/operations/critical-workloads", + label: "Docker", + link: "/docs/self-host/deployment-options/docker", }, { - label: "Scalability", - link: "/docs/self-host/operations/scalability", + label: "Railway", + link: "/docs/self-host/deployment-options/railway", }, { - label: "Monitoring", - link: "/docs/self-host/operations/monitoring", + label: "Terraform", + link: "/docs/self-host/deployment-options/terraform", }, ], }, diff --git a/docs/ensnode.io/public/ensnode-high-level-architecture.svg b/docs/ensnode.io/public/ensnode-high-level-architecture.svg new file mode 100644 index 000000000..531e125ff --- /dev/null +++ b/docs/ensnode.io/public/ensnode-high-level-architecture.svg @@ -0,0 +1,4 @@ + + + +

ENSNode

A high-level architecture diagram presenting relationships among ENSNode services and how they relate to each other.

ENSNode...
...
...
ENSNode
ENSNode
ENSDb Reader
ENSDb Reader
ENSApi
ENSApi
ENS Omnigraph API
ENS Omnigraph API
ENS Subgraph API
ENS Subgraph API
Metadata API
Metadata API
... additional APIs
... additional APIs
ENSAdmin
ENSAdmin
ENSNode Client App A
ENSNode Client App A
ENSNode Client App B
ENSNode Client App B
ENSNode Client App Z
ENSNode Client App Z
ENSIndexer
ENSIndex...
Implementation of
ENSNode Plugin: Unigraph
Implementation of...
Implementation of
ENSNode Plugin: Subgraph
Implementation of...
Implementation of
ENSDb Metadata Writer
Implementation of...
Implementations of
additional ENSNode Plugins
Implementations of...
ENSDb Writer
ENSDb Writer
ENSRainbow
ENSRainb...
Label Set
Label Set
Label-healing
Label-healing
ENSDb
ENSDb
ENS Unigraph
Indexed Data Model
ENS Unigraph...
ENS Subgraph
Indexed Data Model
ENS Subgraph...
Metadata
Metadata
... additional data models
... additional data m...
ENSDb Metadata Writer
ENSDb Metadata Writer \ No newline at end of file diff --git a/docs/ensnode.io/src/content/docs/docs/self-host/index.mdx b/docs/ensnode.io/src/content/docs/docs/self-host/index.mdx index c7e2bf9dc..a684a3546 100644 --- a/docs/ensnode.io/src/content/docs/docs/self-host/index.mdx +++ b/docs/ensnode.io/src/content/docs/docs/self-host/index.mdx @@ -18,30 +18,22 @@ Self-hosting provides extra benefits compared to using one of the publicly [Host - **Control versioning and updates**: choose when to update your ENSNode instance to new versions, giving you control over when to adopt new features or breaking changes. - **Manage uptime**: apply strategies for ensuring high availability and uptime guarantees. -### Bootstrap from a snapshot (coming soon) +## High-level architecture -Self-hosting today means standing up a fresh ENSNode instance from zero and waiting on an initial backfill - including the RPC bill that comes with it. **[ENSDb snapshots and `ensdb-cli`](/docs/integrate/integration-options/ensdb-cli)** will make it cheap and easy to begin working with indexed ENS data. +Before diving into the details of self-hosting, it's important to understand the high-level architecture of ENSNode. This will give you a better understanding of how the different components of ENSNode work together and what infrastructure requirements you may need to consider when self-hosting. - +[![ENSNode High-Level Architecture](/ensnode-high-level-architecture.svg)](/ensnode-high-level-architecture.svg) - - -### Massive scalability +## Next steps -## Deployment options - diff --git a/docs/ensnode.io/src/content/docs/docs/self-host/operations/critical-workloads.mdx b/docs/ensnode.io/src/content/docs/docs/self-host/operations/critical-workloads.mdx index 78ea923cb..ca56c8b89 100644 --- a/docs/ensnode.io/src/content/docs/docs/self-host/operations/critical-workloads.mdx +++ b/docs/ensnode.io/src/content/docs/docs/self-host/operations/critical-workloads.mdx @@ -6,10 +6,6 @@ description: Understand the critical workloads to consider while choosing infras import { LinkCard } from "@astrojs/starlight/components"; -Self-hosting ENSNode requires running several critical workloads that are essential for the proper functioning of ENSNode. Understanding these workloads can help you make informed decisions about the infrastructure and resources needed to run your own ENSNode instance effectively. - -## Critical workloads - ENSNode is responsible for several critical workloads. Understanding these workloads can help you make better decisions about the infrastructure you will need to run your own ENSNode effectively. ### Indexing historical ENS data (backfill) @@ -30,7 +26,7 @@ When starting from scratch, the [ENSIndexer](/docs/services/ensindexer) instance The key requirements for the database server hosting the [ENSDb instance](/docs/services/ensdb/concepts/glossary#ensdb-instance) are: -- **Co-location with the [ENSIndexer](/docs/services/ensindexer) instance**: to minimize requests latency and maximize throughput. +- **Co-location with the [ENSIndexer](/docs/services/ensindexer) instance**: to minimize request latency and maximize throughput. - **High write throughput**: to handle the large volume of write operations during the initial backfill process. This may require optimizing the database configuration for high write performance or using a managed database service that can scale resources as needed. - **Sufficient disk space**: to store the indexed ENS data. The exact disk space required will depend on multiple factors, for example, the activated [ENSNode Plugins](/docs/hosted-instances#ensnode-plugins) and the [ENS namespace](/docs/services/ensdb#ens-namespace) you choose to index. To give you a rough idea, the ENSNode Alpha hosted instance requires at least `380 GB` of disk space and is expected to grow over time as more future ENS events will need to be indexed. @@ -38,7 +34,7 @@ The key requirements for the database server hosting the [ENSDb instance](/docs/ The key requirements for the [ENSRainbow](/docs/services/ensrainbow) instance are: -- **Co-location with the [ENSIndexer](/docs/services/ensindexer) instance**: to minimize requests latency and maximize throughput. +- **Co-location with the [ENSIndexer](/docs/services/ensindexer) instance**: to minimize request latency and maximize throughput. - **Sufficient disk space**: to store the ENSRainbow database. The exact disk space required will depend on the label set config you set for the ENSRainbow instance. For example, you may need at least `55 GB` to serve the `searchlight` label set. ### Indexing live ENS data @@ -50,7 +46,7 @@ After the initial backfill is complete, the resource requirements for indexing l ENSNode serves API requests through the [ENSApi](/docs/services/ensapi) instance, which queries the indexed ENS data stored in the [ENSDb instance](/docs/services/ensdb/concepts/glossary#ensdb-instance). Depending on the volume of API requests and the complexity of the queries, you may need to consider scaling your infrastructure to ensure that the ENSApi instance can handle the load and provide fast responses. This may involve optimizing database queries, implementing caching strategies, or scaling the ENSApi instance horizontally by running multiple instances behind a load balancer. @@ -64,6 +60,8 @@ Deploying ENSNode from scratch can be costly (i.e. high use of RPC credits) and - _What if I could avoid fetching all historical onchain events from an RPC Provider?_ - _What if I could skip the long indexing time?_ +You can do both by leveraging ENSDb snapshots! + :::tip[The ENSDb snapshot shortcut] You can avoid the resource-intensive initial backfill by bootstrapping from an [ENSDb snapshot](/docs/integrate/integration-options/ensdb-cli#ensdb-snapshots), which includes RPC cache and an indexed state of ENS data as of a certain date. This allows ENSIndexer to shorten the backfill process to only the most recent events that occurred after the snapshot point, significantly reducing both the time and cost required to get your ENSNode instance up and running. diff --git a/docs/ensnode.io/src/content/docs/docs/self-host/operations/overview.mdx b/docs/ensnode.io/src/content/docs/docs/self-host/operations/index.mdx similarity index 85% rename from docs/ensnode.io/src/content/docs/docs/self-host/operations/overview.mdx rename to docs/ensnode.io/src/content/docs/docs/self-host/operations/index.mdx index 61833ef2b..34ae34882 100644 --- a/docs/ensnode.io/src/content/docs/docs/self-host/operations/overview.mdx +++ b/docs/ensnode.io/src/content/docs/docs/self-host/operations/index.mdx @@ -9,16 +9,12 @@ import { LinkCard } from "@astrojs/starlight/components"; Operating an ENSNode deployment requires understanding the critical workloads that ENSNode is responsible for, as well as the best practices for managing and optimizing these workloads, including monitoring, scaling, and resource management. This section provides an overview of the key operational considerations for running your own ENSNode instance effectively. - +### Next steps + + diff --git a/docs/ensnode.io/src/content/docs/docs/self-host/operations/scalability.mdx b/docs/ensnode.io/src/content/docs/docs/self-host/operations/scalability.mdx index 6c6363d5d..8e186e16f 100644 --- a/docs/ensnode.io/src/content/docs/docs/self-host/operations/scalability.mdx +++ b/docs/ensnode.io/src/content/docs/docs/self-host/operations/scalability.mdx @@ -9,6 +9,12 @@ import { LinkCard } from "@astrojs/starlight/components"; ENSNode's architecture achieves effectively limitless horizontal scalability, no matter how large your query demands might be. By separating read / write workloads and making use of PostgreSQL's async replication you can scale your ENSNode deployment to handle any request volumes while continuing to index the latest ENS data without impact to indexing performance. + + ## Horizontally scale ENSApi The ENSNode architecture naturally separates writes from reads: From 7b0125e9e3910913f27d0c75b95253535979433f Mon Sep 17 00:00:00 2001 From: Tomasz Kopacki Date: Fri, 12 Jun 2026 17:54:28 +0200 Subject: [PATCH 7/7] Apply AI PR feedback --- docs/ensnode.io/src/content/docs/docs/self-host/index.mdx | 1 - .../src/content/docs/docs/self-host/operations/monitoring.mdx | 2 -- 2 files changed, 3 deletions(-) diff --git a/docs/ensnode.io/src/content/docs/docs/self-host/index.mdx b/docs/ensnode.io/src/content/docs/docs/self-host/index.mdx index a684a3546..125457327 100644 --- a/docs/ensnode.io/src/content/docs/docs/self-host/index.mdx +++ b/docs/ensnode.io/src/content/docs/docs/self-host/index.mdx @@ -6,7 +6,6 @@ sidebar: --- import { LinkCard } from "@astrojs/starlight/components"; -import EnsDbSnapshotsTeaser from "@components/molecules/EnsDbSnapshotsTeaser.astro"; Self-hosting provides extra benefits compared to using one of the publicly [Hosted Instances](/docs/hosted-instances). Having your own ENSNode instance allows you to: diff --git a/docs/ensnode.io/src/content/docs/docs/self-host/operations/monitoring.mdx b/docs/ensnode.io/src/content/docs/docs/self-host/operations/monitoring.mdx index cdcd73889..e1be4127c 100644 --- a/docs/ensnode.io/src/content/docs/docs/self-host/operations/monitoring.mdx +++ b/docs/ensnode.io/src/content/docs/docs/self-host/operations/monitoring.mdx @@ -3,6 +3,4 @@ title: ENSNode Monitoring description: Learn about monitoring strategies for ENSNode deployments. --- -import { LinkCard } from "@astrojs/starlight/components"; - Monitoring is a critical aspect of operating an ENSNode deployment. It involves tracking the performance, health, and resource usage of your ENSNode instance to ensure it runs smoothly and efficiently. This section provides an overview of monitoring strategies for ENSNode deployments, including best practices and tools to help you keep your ENSNode instance in optimal condition.