Manual Installation

Manual installation is intended for developers and experienced system administrators. Production deployments should follow the production guide.

Overview

This guide covers manual installation of both the Mempool backend (Node.js/TypeScript) and frontend (Angular). You’ll have complete control over the setup, making it ideal for development or custom deployments.

Mempool provides support for custom production setups only to project sponsors through Mempool Enterprise®.

Prerequisites

System Requirements

OS: Linux, macOS, or FreeBSD
CPU: 2+ cores recommended
RAM: 4GB minimum, 8GB+ recommended
Storage: 50GB+ SSD for Bitcoin blockchain data

Required Software

Install the following before proceeding:

Node.js & npm

Version: Node.js 20.x and npm 9.x or later

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.0/install.sh | bash
source ~/.bashrc
nvm install 20
nvm use 20

Rust

Required for building backend components:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source ~/.cargo/env

MariaDB

Version: MariaDB 10.5 or later

sudo apt-get install mariadb-server mariadb-client
sudo systemctl start mariadb
sudo systemctl enable mariadb

Backend Installation

1. Clone Repository

Get the source code

git clone https://github.com/mempool/mempool
cd mempool

Checkout latest release

latestrelease=$(curl -s https://api.github.com/repos/mempool/mempool/releases/latest|grep tag_name|head -1|cut -d '"' -f4)
git checkout $latestrelease

2. Configure Bitcoin Core

Ensure your bitcoin.conf includes:

bitcoin.conf

txindex=1
server=1
rpcuser=mempool
rpcpassword=mempool

If Bitcoin Core is already running, restart it after updating the configuration:

bitcoin-cli stop
bitcoind -daemon

3. Configure Electrum Server

This step is optional. You can run Mempool without an Electrum Server, but address lookups will be disabled.

Choose and set up one of these Electrum Server implementations:

Electrs

Efficient Rust implementation

Fulcrum

Fast C++ server

Esplora

Mempool’s fork with extra features

Ensure your Electrum Server is fully synced before proceeding.

4. Configure MariaDB

Access MariaDB

sudo mysql -u root

Create database and user

CREATE DATABASE mempool;
GRANT ALL PRIVILEGES ON mempool.* TO 'mempool'@'localhost' IDENTIFIED BY 'mempool';
FLUSH PRIVILEGES;
EXIT;

Change ‘mempool’ password to something secure in production!

Verify connection

mysql -u mempool -pmempool mempool

5. Build Backend

Navigate to backend directory

cd backend

Install dependencies

npm install --no-install-links

npm 9.4.2+ can omit the --no-install-links flag

Build the backend

npm run build

This compiles TypeScript to JavaScript in the dist/ folder.

6. Configure Backend

Copy sample configuration

cp mempool-config.sample.json mempool-config.json

Edit configuration

nano mempool-config.json

Key settings to configure:

"CORE_RPC": {
  "HOST": "127.0.0.1",
  "PORT": 8332,
  "USERNAME": "mempool",
  "PASSWORD": "mempool",
  "TIMEOUT": 60000
}

Backend Configuration Values

Set MEMPOOL.BACKEND based on your Electrum Server:

"electrum" - For romanz/electrs or Fulcrum
"esplora" - For Blockstream/electrs or mempool/electrs
"none" - No Electrum Server (disables address lookups)

Network Options

"MEMPOOL": {
  "NETWORK": "mainnet"  // Options: mainnet, testnet, signet
}

Advanced Options

"MEMPOOL": {
  "INDEXING_BLOCKS_AMOUNT": 11000,
  "BLOCKS_SUMMARIES_INDEXING": false,
  "CPFP_INDEXING": false,
  "AUTOMATIC_POOLS_UPDATE": false,
  "POLL_RATE_MS": 2000
}

7. Start Backend

Production
Development
Custom Config

npm run start

You should see output like:

Mempool updated in 0.189 seconds
Updating mempool
Mempool updated in 0.096 seconds

Use nodemon for auto-reload during development:

# Install globally
npm install -g ts-node nodemon

# Run with watcher
nodemon src/index.ts --ignore cache/

Specify a custom config file location:

MEMPOOL_CONFIG_FILE=/path/to/mempool-config.json npm run start

The backend API runs on port 8999 by default. Test it:

curl http://localhost:8999/api/v1/backend-info

Frontend Installation

1. Navigate to Frontend

cd ../frontend

2. Install Dependencies

npm install

3. Configure Frontend

Choose your target site:

npm run config:defaults:mempool

4. Build & Run

Development with Local Backend
Development with Production API
Production Build

Run frontend with your local backend:

npm run serve

Access at http://localhost:4200

Run frontend proxied to mempool.space backend:

npm run serve:local-prod

Useful for frontend-only development without backend setup.

Build static files for production:

npm run build

Output will be in dist/ directory. Serve with nginx or another web server.

Production Deployment

For production, you’ll need a web server like nginx:

1. Build Frontend

cd frontend
npm run build

2. Configure Nginx

Sample nginx configuration from the repository:

nginx.conf

server {
  listen 80;
  listen [::]:80;
  server_name your-domain.com;

  root /path/to/mempool/frontend/dist/mempool;
  index index.html;

  # API proxy
  location /api/ {
    proxy_pass http://127.0.0.1:8999;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection 'upgrade';
    proxy_set_header Host $host;
    proxy_cache_bypass $http_upgrade;
  }

  # WebSocket proxy
  location /ws {
    proxy_pass http://127.0.0.1:8999;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "Upgrade";
    proxy_set_header Host $host;
  }

  # Frontend
  location / {
    try_files $uri $uri/ /index.html;
  }
}

See nginx.conf and nginx-mempool.conf in the repository root for complete production configurations.

3. Enable Site

sudo ln -s /etc/nginx/sites-available/mempool /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx

Process Management

Use a process manager to keep the backend running:

systemd
PM2
Screen/Tmux

Create /etc/systemd/system/mempool.service:

[Unit]
Description=Mempool Backend
After=network.target mariadb.service

[Service]
Type=simple
User=mempool
WorkingDirectory=/path/to/mempool/backend
ExecStart=/usr/bin/npm run start
Restart=on-failure
RestartSec=10

[Install]
WantedBy=multi-user.target

Enable and start:

sudo systemctl daemon-reload
sudo systemctl enable mempool
sudo systemctl start mempool

Install and use PM2:

npm install -g pm2
cd /path/to/mempool/backend
pm2 start dist/index.js --name mempool
pm2 startup
pm2 save

For development/testing:

screen -S mempool
cd /path/to/mempool/backend
npm run start
# Detach with Ctrl+A then D

Testing

Run End-to-End Tests

cd frontend
npm run config:defaults:mempool
npm run cypress:run

Troubleshooting

Backend won't start

Check logs for errors:

Database connection issues
Bitcoin Core RPC not accessible
Port 8999 already in use

Verify services:

# Bitcoin Core
bitcoin-cli getblockchaininfo

# MariaDB
mysql -u mempool -pmempool mempool

# Port availability
netstat -tuln | grep 8999

Frontend build fails

Ensure Node.js 20.x is installed
Clear npm cache: npm cache clean --force
Delete node_modules and reinstall: rm -rf node_modules && npm install

Address lookups not working

Verify Electrum Server is running and synced
Check MEMPOOL.BACKEND setting matches your server type
Test Electrum connection:
```
telnet 127.0.0.1 50002
```

Database errors

Reset and reinitialize:

mysql -u root -e "DROP DATABASE mempool; CREATE DATABASE mempool; GRANT ALL PRIVILEGES ON mempool.* TO 'mempool'@'localhost';"

Restart backend to recreate tables.

Development Tips

Backend Hot Reload

Use nodemon for automatic restart on code changes:

npm install -g ts-node nodemon
nodemon src/index.ts --ignore cache/

Regtest Testing

Use Bitcoin regtest for development:

# Start bitcoind in regtest
bitcoind -regtest -daemon

# Create wallet
bitcoin-cli -regtest createwallet test

# Mine blocks
address=$(bitcoin-cli -regtest getnewaddress)
bitcoin-cli -regtest generatetoaddress 101 $address

# Generate transactions
bitcoin-cli -regtest -named sendtoaddress \
  address=$(bitcoin-cli -regtest getnewaddress) \
  amount=0.1 fee_rate=5

Update Mining Pools

Manually update mining pool data:

npm run start --update-pools

Or enable automatic updates in config:

"MEMPOOL": {
  "AUTOMATIC_POOLS_UPDATE": true
}

Re-index Tables

Force re-indexing of specific tables:

npm run start --reindex=blocks,hashrates

This will delete existing data for the specified tables.

Next Steps

Production Deployment

Scale to production with advanced setup

Configuration Reference

Complete configuration documentation

API Documentation

Integrate with Mempool’s API

Contributing Guide

Contribute to Mempool development

Get Started

Installation

Core Features

Configuration

Self-Hosting

Development

Manual Installation

Overview

Prerequisites

Backend Installation

1. Clone Repository

2. Configure Bitcoin Core

3. Configure Electrum Server

Electrs

Fulcrum

Esplora

4. Configure MariaDB

5. Build Backend

6. Configure Backend

7. Start Backend

Frontend Installation

1. Navigate to Frontend

2. Install Dependencies

3. Configure Frontend

4. Build & Run

Production Deployment

1. Build Frontend

2. Configure Nginx

3. Enable Site

Process Management

Testing

Run End-to-End Tests

Troubleshooting

Development Tips

Next Steps

Production Deployment

Configuration Reference

API Documentation

Contributing Guide

Build docs developers (and LLMs) love

Get Started

Installation

Core Features

Configuration

Self-Hosting

Development

Documentation Index

​Overview

​Prerequisites

​Backend Installation

​1. Clone Repository

​2. Configure Bitcoin Core

​3. Configure Electrum Server

Electrs

Fulcrum

Esplora

​4. Configure MariaDB

​5. Build Backend

​6. Configure Backend

​7. Start Backend

​Frontend Installation

​1. Navigate to Frontend

​2. Install Dependencies

​3. Configure Frontend

​4. Build & Run

​Production Deployment

​1. Build Frontend

​2. Configure Nginx

​3. Enable Site

​Process Management

​Testing

​Run End-to-End Tests

​Troubleshooting

​Development Tips

​Next Steps

Production Deployment

Configuration Reference

API Documentation

Contributing Guide

Build docs developers (and LLMs) love

Overview

Prerequisites

Backend Installation

1. Clone Repository

2. Configure Bitcoin Core

3. Configure Electrum Server

4. Configure MariaDB

5. Build Backend

6. Configure Backend

7. Start Backend

Frontend Installation

1. Navigate to Frontend

2. Install Dependencies

3. Configure Frontend

4. Build & Run

Production Deployment

1. Build Frontend

2. Configure Nginx

3. Enable Site

Process Management

Testing

Run End-to-End Tests

Troubleshooting

Development Tips

Next Steps