> ## Documentation Index
> Fetch the complete documentation index at: https://docs.towns.com/llms.txt
> Use this file to discover all available pages before exploring further.
# System Requirements & Installation
> The following guide describes system requirements, dependencies, and installation details recommended for running a Towns Stream Node. This guide applies to nodes running in either Testnet or Mainnet.
By adhering to the guidelines outlined in this guide, node operators can contribute to the stability and efficiency of the Towns Network. Effective node operation not only benefits the individual operator by ensuring optimal node performance but also supports the health and reliability of the entire network.
### System Requirements & Dependencies
To run a Towns Stream Node, an operator will need to run a Node Frontend (FE) and Node Storage layer, postgres database, with a specific network configuration.
Please read the below requirements carefully prior to proceeding with node setup.
* **CPU**: Minimum 8 virtual CPUs.
* **Memory**: At least 32 GB of RAM.
- **Architecture**: x64 or ARM64 supported.
* **Network**: Dedicated, static public IP address, capable of handling up to 1 Gbps ingress and egress for HTTP 1.1/2
traffic.
* **Blockchain RPC Access**: Access to blockchain RPC provider endpoints for
Base Chain, Towns Chain, and cross-chain chain ids.
* **Database Compatibility**: Postgres 15.4 or newer.
* **Transaction Processing**: Capable of handling up to 10k IOps.
* **Storage Capacity**: Minimum 2 TB of storage.
* **Keypair store**: Location to store ECDSA keypair associated with the data stored in the database.
It is highly recommended to run a distinct Postgres instance for each Node FE to ensure resource isolation during upgrades.
* **Towns Chain Eth Balance**: Minimum 1 ETH on all stream node wallets in Towns Chain to support gas needed for miniblock validation.
* **Base Chain Eth Balance**: Minimum 0.5 ETH on all stream node wallets in Base Chain to support gas needed for cross-chain entitlement checks.
Set up alerts to monitor the balance of the node's Eth balance on Towns Chain and Base Chain at a minimum alert threshold of 0.25 ETH and 0.1 ETH respectively.
### Installation
Node FE's can be installed either from docker with the Towns public [ECR image registry](https://public.ecr.aws/h5v6m2x1/river) or built from [source code](https://github.com/towns-protocol/towns/tree/main/core/node).
#### Installation from Docker
The Towns Protocol maintains a public docker image registry `public.ecr.aws/h5v6m2x1/river` for images that are built officially from [source](https://github.com/towns-protocol/towns) during CI/CD.
As such, node operators can easily install the latest Node FE software from images stored in the public ECR registry. Images are tagged during [releases](/node-operator/release-process) with the associated commit as well as mutable tags `mainnet`, `testnet`, for each network respectively.
```bash theme={null}
docker pull public.ecr.aws/h5v6m2x1/river:testnet
docker tag public.ecr.aws/h5v6m2x1/river:testnet river-node
```
Images are tagged by their merge commit hash so to install a specific version of the Node FE software, use the commit hash from source instead of the `testnet` or `mainnet` tag, which references the latest built image.
```bash theme={null}
git clone git@github.com:towns-protocol/towns.git
# print out shorthand commit hashes
git log --pretty=format:'%h' | cut -c 1-7
# choose one to pull
COMMIT_HASH=1dd452a
docker pull public.ecr.aws/h5v6m2x1/river:$COMMIT_HASH
```
The CI job that builds docker images to the river public ecr registry can be found
[here](https://github.com/towns-protocol/towns/blob/main/.github/workflows/River_node_docker.yml).
As of October 2024, as an alternative to the public ECR registry, it is recommended to build the docker image from the source [Dockerfile](https://github.com/towns-protocol/towns/blob/main/core/Dockerfile) to ensure compatibility with the latest software version.
```bash theme={null}
git clone git@github.com:towns-protocol/towns.git
cd river/core
docker build -t river-node .
```
### Node FE Environment Variables
Towns Stream Nodes run expecting certain environment variables to be present in the process environment and set at runtime. Config, which is described in [config.go](https://github.com/towns-protocol/towns/blob/main/core/config/config.go), is injected into the binary at runtime using [viper](https://github.com/spf13/viper).
For the list of contracts required to run nodes and their addresses, see [contracts](/node-operator/contracts).
| Environment Variable | Purpose | Required | Testnet Value | Secret |
| ------------------------------------------- | -------------------------------------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------ | ------ |
| ARCHITECTCONTRACT\_\_ADDRESS | SpaceFactory contract address in Base Network | Yes | 0x5A077e686545c541476D3a99711dE42339357467 | - |
| ARCHITECTCONTRACT\_\_VERSION | Contract interface version | Yes | v3 | - |
| BASECHAIN\_\_CHAINID | Base ChainId | Yes | 84532 | - |
| BASECHAIN\_\_NETWORKURL | Base Chain RPC Url | Yes | [https://sepolia.base.org](https://sepolia.base.org) | Yes |
| CHAINSSTRING | List of chainIds and network RPC Urls supported | Yes | see [Cross-chain Requirements](/node-operator/tutorials/system-requirements-installation#cross-chain-requirements) | - |
| DATABASE\_\_DATABASE | Postgres DB Name | Yes | river | - |
| DATABASE\_\_EXTRA | Extra Postgres Options | Yes | ?sslmode=disable\&pool\_max\_conns=1000 | - |
| DATABASE\_\_HOST | Postgres DB Host Url | Yes | - | - |
| DATABASE\_\_PASSWORD | Postgres DB Password | Yes | - | Yes |
| DATABASE\_\_PORT | Postgres DB port | Yes | 5432 | - |
| DATABASE\_\_USER | Postgres DB username | Yes | - | - |
| DD\_TAGS | Used by Datadog for metrics collection | No | env: (gamma), node\_url:(your complete node url) | No |
| DEBUGENDPOINTS\_\_PPROF | Enable pprof endpoints | No | false | - |
| DEBUGENDPOINTS\_\_PRIVATEDEBUGSERVERADDRESS | Private debug server address | No | :8080 | - |
| DEBUGENDPOINTS\_\_MEMPROFILEDIR | Directory for memory profile files | No | ./mem\_profile | - |
| ENTITLEMENT\_CONTRACT\_\_ADDRESS | Entitlement contract address in Base Network | Yes | 0x0d7eC5826626070b6a250C9878940D070128A265 | - |
| LOG\_\_FORMAT | Log format option | No | text | - |
| LOG\_\_LEVEL | Default log level | No | info | - |
| LOG\_\_NOCOLOR | Logging without color | No | true | - |
| METRICS\_\_ENABLED | Metrics exporter enabled | No | true | - |
| METRICS\_\_PORT | Metrics export port | No | 8081 | - |
| PERFORMANCETRACKING\_\_PROFILINGENABLED | Used by Datadog for cpu profiling | no | true | No |
| PERFORMANCETRACKING\_\_TRACINGENABLED | Used by Datadog for tracing | no | true | No |
| PORT | Port RPC service listens on | Yes | 443 | - |
| REGISTRYCONTRACT\_\_ADDRESS | River Registry contract address in Towns Chain Network | Yes | 0x94bdc7016057fc47cC006Bc837bF0Aed5Dc5C6D6 | - |
| RIVERCHAIN\_\_CHAINID | Towns Chain chainId | Yes | 6524490 | - |
| RIVERCHAIN\_\_NETWORKURL | Towns Chain RPC Url | Yes | [https://testnet.rpc.towns.com/http](https://testnet.rpc.towns.com/http) | Yes |
| RUN\_MODE | Stream Node Run Mode (full, archive) | No | full | - |
| SKIP\_GENKEY | Skip generating node ECDSA wallet keypair | Yes | true | - |
| STANDBYONSTART | Start node in standby mode | No | false | - |
| STORAGE\_TYPE | postgres or in-memory | No | postgres | - |
| TLSCONFIG\_\_CERT | TLS certificate value for node hostname | Yes | - | Yes |
| TLSCONFIG\_\_KEY | TLS certificate key for node hostname | Yes | - | Yes |
| TOWNS\_ENV | Environment name for network configuration (beta for testnet, omega for mainnet) | Yes | beta | - |
| WALLETPRIVATEKEY | Node ECDSA private key string | Yes | - | Yes |
Testnet Values provided above are as of May 2024. New contract addresses can
be found in `packages/generated/**` of river repo.
Environment variables marked as Secret require proper encrypted storage and
management. It is up to node operators to choose a secure store for such
secrets depending on their runtime operating environment be it cloud or
on-premise.
### Cross-chain Requirements
`CHAINSSTRING` environment variable is a comma-separated, colon delimited list of chain ID's and RPC Urls that is required for nodes to support cross-chain entitlement checks.
As of June 2024, the Towns network must support the following chainIds listed in the below table for testnet, mainnet, respectively.
As an example, using redacted RPC urls from Web3 providers, the `CHAINSSTRING` environment variable for Mainnet would look like:
```
1:https://eth-mainnet.g.alchemy.com/v2/$ETHEREUM_API_KEY,8453:https://base-mainnet.g.alchemy.com/v2/$BASE_API_KEY,42161:https://arb-mainnet.g.alchemy.com/v2/$ARBITRUM_MAINNET_API_KEY,137:https://polygon-mainnet.g.alchemy.com/v2/$POLYGON_API_KEY,10:https://opt-mainnet.g.alchemy.com/v2/$OPTIMISM_API_KEY
```
Do not use public RPC provider urls found on [chainlist](https://chainlist.org/) or elsewhere as these are notoriously unstable. Node Operators are encouraged to provision RPC Urls for high availability for each supported chainId by using custom provisioned provider urls from [Alchemy](https://www.alchemy.com/) or [Infura](https://www.infura.io/).
### Testnet Cross-Chain Chain Ids Required
On testnet, nodes should support the following chain ids with configured RPC endpoints for cross-chain entitlement checks.
| Chain Id | Network |
| -------- | ---------------- |
| 1 | Ethereum Mainnet |
| 11155111 | Ethereum Sepolia |
| 8453 | Base Mainnet |
| 84532 | Base Sepolia |
| 42161 | Arbitrum One |
| 137 | Polygon Mainnet |
| 10 | Optimism Mainnet |
| 10200 | Gnosis Chiado |
### Mainnet Cross-Chain Chain Ids Required
On mainnet, nodes should support the following 6 chain ids for cross-chain entitlement checks.
| Chain Id | Network |
| -------- | ---------------- |
| 1 | Ethereum Mainnet |
| 8453 | Base Mainnet |
| 42161 | Arbitrum One |
| 137 | Polygon Mainnet |
| 10 | Optimism Mainnet |
| 100 | Gnosis |