diff --git a/docs/ensnode.io/astro.config.mjs b/docs/ensnode.io/astro.config.mjs
index 9ed94d704c..3079fee6d2 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 b164f78a55..7f6c4ddf72 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,20 +4,50 @@ export const selfHostSidebarTopic = {
icon: "seti:docker",
items: [
{
- label: "Overview",
+ label: "Getting started",
link: "/docs/self-host",
},
{
- label: "Docker",
- link: "/docs/self-host/docker",
+ label: "Operations",
+ items: [
+ {
+ label: "Overview",
+ link: "/docs/self-host/operations",
+ },
+ {
+ label: "Critical workloads 🚨",
+ link: "/docs/self-host/operations/critical-workloads",
+ },
+ {
+ label: "Scalability",
+ link: "/docs/self-host/operations/scalability",
+ },
+ {
+ label: "Monitoring",
+ link: "/docs/self-host/operations/monitoring",
+ },
+ ],
},
{
- label: "Terraform",
- link: "/docs/self-host/terraform",
- },
- {
- label: "Scalability",
- link: "/docs/self-host/scalability",
+ label: "Deployment options",
+ items: [
+ {
+ label: "Overview",
+ link: "/docs/self-host/deployment-options",
+ },
+ {
+ label: "Docker",
+ link: "/docs/self-host/deployment-options/docker",
+ },
+ {
+ label: "Railway",
+ link: "/docs/self-host/deployment-options/railway",
+ },
+ {
+ 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 0000000000..531e125ff9
--- /dev/null
+++ b/docs/ensnode.io/public/ensnode-high-level-architecture.svg
@@ -0,0 +1,4 @@
+
+
+
+
\ No newline at end of file
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 5fe5819163..4f1ad2f425 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/docker.mdx b/docs/ensnode.io/src/content/docs/docs/self-host/deployment-options/docker.mdx
similarity index 99%
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
index 4f8cb5be6e..c8f50b46fd 100644
--- 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
@@ -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/deployment-options/index.mdx b/docs/ensnode.io/src/content/docs/docs/self-host/deployment-options/index.mdx
new file mode 100644
index 0000000000..bb7e45becf
--- /dev/null
+++ b/docs/ensnode.io/src/content/docs/docs/self-host/deployment-options/index.mdx
@@ -0,0 +1,26 @@
+---
+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/deployment-options/railway.mdx b/docs/ensnode.io/src/content/docs/docs/self-host/deployment-options/railway.mdx
new file mode 100644
index 0000000000..a48b29b16a
--- /dev/null
+++ b/docs/ensnode.io/src/content/docs/docs/self-host/deployment-options/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/terraform.mdx b/docs/ensnode.io/src/content/docs/docs/self-host/deployment-options/terraform.mdx
similarity index 99%
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
index 8c1aef6b51..2aa04595e9 100644
--- 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
@@ -2,7 +2,6 @@
title: Deploying ENSNode with Terraform
sidebar:
label: Terraform
- order: 2
---
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 b3a240a15b..1254573273 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,56 +1,38 @@
---
title: Self-host ENSNode
description: Decide whether to self-host ENSNode and understand the architecture.
+sidebar:
+ label: Overview
---
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).
+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:
-:::note
-Follow these guides to deploy an ENSNode instance to the cloud.
-:::
+- **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 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 strategies for ensuring high availability and uptime guarantees.
-Running your own ENSNode instance is helpful for those that wish to:
+## High-level architecture
-- 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
+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.
-:::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.
-:::
+[](/ensnode-high-level-architecture.svg)
-### Bootstrap from a snapshot (coming soon)
-
-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.
-
-
+## Next steps
-### Massive 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
-
-An example Terraform deployment reference is available, showing an example of deploying the full ENSNode suite on Render with AWS managed domain names.
-
-
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 0000000000..ca56c8b892
--- /dev/null
+++ b/docs/ensnode.io/src/content/docs/docs/self-host/operations/critical-workloads.mdx
@@ -0,0 +1,73 @@
+---
+title: Critical Workloads
+description: Understand the critical workloads to consider while choosing infrastructure for self-hosting ENSNode.
+
+---
+
+import { LinkCard } from "@astrojs/starlight/components";
+
+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 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.
+
+#### ENSRainbow
+
+The key requirements for the [ENSRainbow](/docs/services/ensrainbow) instance are:
+
+- **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
+
+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?_
+
+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.
+
+:::
+
+### 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/index.mdx b/docs/ensnode.io/src/content/docs/docs/self-host/operations/index.mdx
new file mode 100644
index 0000000000..34ae34882c
--- /dev/null
+++ b/docs/ensnode.io/src/content/docs/docs/self-host/operations/index.mdx
@@ -0,0 +1,30 @@
+---
+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 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/monitoring.mdx b/docs/ensnode.io/src/content/docs/docs/self-host/operations/monitoring.mdx
new file mode 100644
index 0000000000..e1be4127c8
--- /dev/null
+++ b/docs/ensnode.io/src/content/docs/docs/self-host/operations/monitoring.mdx
@@ -0,0 +1,6 @@
+---
+title: ENSNode Monitoring
+description: Learn about monitoring strategies for ENSNode deployments.
+---
+
+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/scalability.mdx b/docs/ensnode.io/src/content/docs/docs/self-host/operations/scalability.mdx
similarity index 95%
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
index cd14090fa7..8e186e16fb 100644
--- 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
@@ -3,13 +3,18 @@ title: ENSNode Scalability
description: Understand how ENSNode's architecture enables horizontal scaling.
sidebar:
label: Scalability
- order: 3
---
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: