Hosting guide

Overview

When deploying Masumi Node and your agents to production, it’s crucial to understand the recommended hosting architecture. This guide explains why separate hosting is essential and provides hosting options and detailed instructions.

This guide uses Digital Ocean as an example, but you can use any cloud provider including AWS, Google Cloud Platform (GCP), Azure, or any other VPS provider. The general principles and setup steps are similar across providers.

Important: Separate hosting requiredMasumi Node and agents must be hosted on separate servers. Hosting them on the same droplet or instance can cause resource conflicts, performance issues, and service interruptions. Each component has different resource requirements and should run independently.

Recommended hosting architecture

Why separate hosting?

Resource isolation - Masumi Node requires dedicated resources for database operations, blockchain interactions, and payment processing. Running agents on the same server can cause resource contention.
Scalability - Agents may need to scale independently based on demand, while the Masumi Node typically runs as a single instance.
Security - Separating services reduces the attack surface and allows for better security configurations.
Reliability - If one service needs maintenance or encounters issues, the other can continue operating independently.

Architecture diagram

┌─────────────────────┐
│   Masumi Node       │
│   (Payment Service) │
│   + PostgreSQL      │
│   Instance 1        │
└─────────────────────┘
         │
         │ API Calls
         │
┌─────────────────────┐
│   Your Agent(s)     │
│   (Agentic Service) │
│   Instance 2        │
└─────────────────────┘

Hosting options

Option 1: Railway (easiest for Masumi Node)

Railway provides the easiest way to host your Masumi Node with minimal configuration. Railway templates are available that handle most of the setup automatically.

For detailed Railway deployment instructions, see the Installation Guide. Railway is an excellent option for getting started quickly, especially for the Masumi Node.

Advantages:

One-click deployment via templates
Automatic database provisioning
Built-in environment variable management
Easy scaling and monitoring
Free trial available

While Railway is great for Masumi Node, you’ll still need to host your agents separately on another platform (Railway, Digital Ocean, AWS, etc.) to maintain proper separation.

Option 2: Docker Compose (recommended for VPS hosting)

Docker Compose is an excellent option for hosting Masumi Node on any VPS provider. It simplifies deployment and management by containerizing all services.

For basic Docker Compose setup instructions, see the Installation Guide. The following section covers production deployment on a VPS.

Advantages:

Easy deployment and updates
Isolated services with automatic dependency management
Includes PostgreSQL database automatically
Simple to backup and restore
Works on any VPS provider (Digital Ocean, AWS, GCP, etc.)

Requirements:

VPS instance with Docker and Docker Compose installed
Minimal plan (2 GB RAM / 1 vCPU) is sufficient

Option 3: Manual setup on cloud providers

For more control and customization, you can manually set up Masumi Node and agents on any cloud provider without Docker. The following sections provide detailed instructions using Digital Ocean as an example, but the same principles apply to:

AWS (EC2 instances)
Google Cloud Platform (Compute Engine)
Azure (Virtual Machines)
Linode, Vultr, Hetzner, or any other VPS provider

Part 1: Hosting Masumi Node with Docker Compose

This section provides step-by-step instructions for deploying Masumi Node using Docker Compose on any VPS provider.

Create a VPS instance

Create a VPS instance on your chosen provider (Digital Ocean, AWS, GCP, Azure, etc.):

Image: Ubuntu 22.04 (LTS) x64
Plan: 2 GB RAM / 1 vCPU (minimal plan is sufficient)
Region: Choose closest to your users

Initial server setup

SSH into your instance:

ssh root@your_instance_ip

Update the system:

apt update && apt upgrade -y

Install Docker and Docker Compose

Install Docker:

apt install -y apt-transport-https ca-certificates curl software-properties-common
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | apt-key add -
add-apt-repository "deb [arch=amd64] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable"
apt update
apt install -y docker-ce

Install Docker Compose:

curl -L "https://github.com/docker/compose/releases/latest/download/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
chmod +x /usr/local/bin/docker-compose

Verify installation:

docker --version
docker-compose --version

Clone Masumi Services repository

Install Git if not already installed:

apt install -y git

Clone the repository:

cd /opt
git clone https://github.com/masumi-network/masumi-services-dev-quickstart.git
cd masumi-services-dev-quickstart

Configure environment variables

Copy the example environment file:

cp .env.example .env

Edit the .env file:

nano .env

Configure the following variables:

# Blockfrost API
BLOCKFROST_API_KEY_PREPROD="your_blockfrost_api_key"
BLOCKFROST_API_KEY_MAINNET="your_mainnet_key_if_using"

# Security
ENCRYPTION_KEY="your_secure_encryption_key_32_chars_min"
ADMIN_KEY="your_admin_password_15_chars_min"

# Network
NETWORK=Preprod

# Server Configuration
PORT=3001
HOST=0.0.0.0

Generate a secure encryption key: openssl rand -hex 32
Get your Blockfrost API key from blockfrost.io
The ADMIN_KEY must be at least 15 characters long
For more details on environment variables, see the Environment Variables section

Start services with Docker Compose

Start all services:

docker compose up -d

Check service status:

docker compose ps

View logs:

docker compose logs -f

Configure firewall

Allow necessary ports:

ufw allow 22/tcp   # SSH
ufw allow 3001/tcp # Masumi Node API
ufw enable

Set up auto-restart (optional)

To ensure services restart automatically on reboot, Docker Compose services are typically configured to restart automatically. Verify this in your docker-compose.yml file - it should include restart: unless-stopped or restart: always for each service.

Set up reverse proxy (optional but recommended)

Install Nginx:

apt install -y nginx

Create an Nginx configuration file:

nano /etc/nginx/sites-available/masumi-node

Add the following configuration:

server {
    listen 80;
    server_name your_domain.com;  # Replace with your domain or instance IP

    location / {
        proxy_pass http://localhost:3001;
        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;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Enable the site:

ln -s /etc/nginx/sites-available/masumi-node /etc/nginx/sites-enabled/
nginx -t  # Test configuration
systemctl restart nginx

For production, consider setting up SSL/TLS with Let’s Encrypt using Certbot for HTTPS.

Verify installation

Test the API:

curl http://localhost:3001/api/v1/health/

You should receive:

{
  "status": "success",
  "data": {
    "status": "ok"
  }
}

Access the admin dashboard at: http://your_instance_ip:3001/admin

Useful Docker Compose commands

View logs:

docker compose logs -f

Restart services:

docker compose restart

Stop services:

docker compose down

Update services:

cd /opt/masumi-services-dev-quickstart
git pull
docker compose down
docker compose up -d --build

Backup database:

docker compose exec postgres pg_dump -U postgres masumi_payment > backup.sql

Part 2: Manual setup on Digital Ocean

This section walks you through hosting both components on Digital Ocean using separate droplets. These same steps can be adapted for AWS, GCP, Azure, or any other VPS provider.

Prerequisites

Digital Ocean account (or account with your chosen cloud provider)
Basic knowledge of Linux command line
SSH access to your local machine

Hosting Masumi Node

Create a droplet

Log in to your Digital Ocean dashboard
Click “Create” → “Droplets”
Configure your droplet:
- Image: Ubuntu 22.04 (LTS) x64
- Plan: 2 GB RAM / 1 vCPU - This minimal plan is sufficient for Masumi Node
- Datacenter region: Choose closest to your users
- Authentication: SSH keys (recommended) or root password
- Hostname: masumi-node (or your preferred name)
Click “Create Droplet”

Initial server setup

Once your droplet is created, SSH into it:

ssh root@your_droplet_ip

Update the system:

apt update && apt upgrade -y

Install Node.js

Install Node.js 18.x (required for Masumi Node):

curl -fsSL https://deb.nodesource.com/setup_18.x | bash -
apt install -y nodejs

Verify installation:

node --version  # Should show v18.x.x
npm --version

Install PostgreSQL

Install PostgreSQL 15:

apt install -y postgresql postgresql-contrib

Start and enable PostgreSQL:

systemctl start postgresql
systemctl enable postgresql

Create the database and user:

sudo -u postgres psql

Inside the PostgreSQL prompt:

CREATE DATABASE masumi_payment;
CREATE USER masumi_user WITH ENCRYPTED PASSWORD 'your_secure_password';
GRANT ALL PRIVILEGES ON DATABASE masumi_payment TO masumi_user;
\q

Clone and configure Masumi Payment Service

Install Git if not already installed:

apt install -y git

Clone the repository:

cd /opt
git clone https://github.com/masumi-network/masumi-payment-service.git
cd masumi-payment-service

Check out the latest stable version:

git fetch --tags
git checkout $(git tag -l | sort -V | tail -n 1)

Install dependencies:

npm install

Configure environment variables

Copy the example environment file:

cp .env.example .env

Edit the .env file with your configuration:

nano .env

Configure the following variables:

# Database
DATABASE_URL="postgresql://masumi_user:your_secure_password@localhost:5432/masumi_payment?schema=public"

# Security
ENCRYPTION_KEY="your_secure_encryption_key_32_chars_min"
ADMIN_KEY="your_admin_password_15_chars_min"

# Blockfrost API
BLOCKFROST_API_KEY_PREPROD="your_blockfrost_api_key"
BLOCKFROST_API_KEY_MAINNET="your_mainnet_key_if_using"

# Network
NETWORK=Preprod

# Server Configuration
PORT=3001
HOST=0.0.0.0

Generate a secure encryption key: openssl rand -hex 32
Get your Blockfrost API key from blockfrost.io
The ADMIN_KEY must be at least 15 characters long

Build frontend and run migrations

Build the admin interface:

cd frontend
npm install
npm run build
cd ..

Run database migrations:

npm run prisma:migrate
npm run prisma:seed

Set up process manager (PM2)

Install PM2 to keep the service running:

npm install -g pm2

Start the Masumi Node:

npm run build
pm2 start npm --name "masumi-node" -- start

Save PM2 configuration:

pm2 save
pm2 startup

Follow the instructions provided by the pm2 startup command to enable auto-start on reboot.

Configure firewall

Allow necessary ports:

ufw allow 22/tcp   # SSH
ufw allow 3001/tcp  # Masumi Node API
ufw enable

Set up reverse proxy (optional but recommended)

Install Nginx:

apt install -y nginx

Create an Nginx configuration file:

nano /etc/nginx/sites-available/masumi-node

Add the following configuration:

server {
    listen 80;
    server_name your_domain.com;  # Replace with your domain or droplet IP

    location / {
        proxy_pass http://localhost:3001;
        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;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Enable the site:

ln -s /etc/nginx/sites-available/masumi-node /etc/nginx/sites-enabled/
nginx -t  # Test configuration
systemctl restart nginx

For production, consider setting up SSL/TLS with Let’s Encrypt using Certbot for HTTPS.

Verify installation

Test the API:

curl http://localhost:3001/api/v1/health/

You should receive:

{
  "status": "success",
  "data": {
    "status": "ok"
  }
}

Access the admin dashboard at: http://your_droplet_ip:3001/admin

Hosting your agent

Create a separate droplet

Create a new droplet following the same process as above
Important: This must be a separate droplet from your Masumi Node
Recommended specs:
- Minimum: 2 GB RAM / 1 vCPU
- For AI agents: 4 GB RAM / 2 vCPU or higher depending on your agent’s requirements

Set up your agent environment

SSH into your agent droplet:

ssh root@your_agent_droplet_ip

Update the system:

apt update && apt upgrade -y

Install required dependencies

The dependencies depend on your agent’s technology stack. Common examples:For Python-based agents:

apt install -y python3 python3-pip python3-venv git

For Node.js-based agents:

curl -fsSL https://deb.nodesource.com/setup_18.x | bash -
apt install -y nodejs git

For Docker-based agents:

apt install -y docker.io docker-compose git
systemctl start docker
systemctl enable docker

Deploy your agent

Clone your agent repository:

cd /opt
git clone https://github.com/your-username/your-agent-repo.git
cd your-agent-repo

Follow your agent’s specific installation instructions. Typically:For Python:

python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

For Node.js:

npm install

Configure agent environment variables

Create or edit your agent’s .env file:

nano .env

Configure the connection to your Masumi Node:

# Masumi Node Connection
PAYMENT_SERVICE_URL=http://your_masumi_node_ip:3001/api/v1
# Or if using domain: https://your-domain.com/api/v1

PAYMENT_API_KEY=your_payment_api_key_from_masumi_node

# Agent Configuration
AGENT_IDENTIFIER=your_agent_identifier
PAYMENT_AMOUNT=10000000
PAYMENT_UNIT=lovelace
SELLER_VKEY=your_selling_wallet_vkey

# Network
NETWORK=Preprod

# Your agent's specific variables
# ...

Get your PAYMENT_API_KEY from the Masumi Node admin dashboard
Get your AGENT_IDENTIFIER after registering your agent on the Masumi Network
The PAYMENT_SERVICE_URL should point to your Masumi Node droplet’s IP or domain

Run your agent with PM2

Install PM2:

npm install -g pm2

Start your agent (adjust command based on your agent):For Python agents:

pm2 start "python3 main.py api" --name "my-agent" --interpreter python3

For Node.js agents:

pm2 start npm --name "my-agent" -- start

For other setups:

pm2 start your-start-command --name "my-agent"

Save PM2 configuration:

pm2 save
pm2 startup

Configure firewall

Allow necessary ports:

ufw allow 22/tcp   # SSH
ufw allow 8000/tcp # Agent API (adjust port as needed)
ufw enable

Set up reverse proxy (optional)

If you want to expose your agent via a domain, set up Nginx similar to the Masumi Node setup, but point to your agent’s port (typically 8000).

Verification and testing

Test Masumi Node

Access admin dashboard: http://your_masumi_node_ip:3001/admin
Verify health endpoint: curl http://your_masumi_node_ip:3001/api/v1/health/
Check PM2 status: pm2 status

Test your agent

Verify agent is running: pm2 status
Test agent health endpoint (if available): curl http://your_agent_ip:8000/availability
Check agent logs: pm2 logs my-agent

Test integration

Register your agent on the Masumi Network through the admin dashboard
Test a payment flow to ensure connectivity between agent and Masumi Node

Monitoring and maintenance

View logs

Masumi Node:

pm2 logs masumi-node

Your Agent:

pm2 logs my-agent

Restart services

Masumi Node:

pm2 restart masumi-node

Your Agent:

pm2 restart my-agent

Update services

When updating either service:

Pull latest changes: git pull
Install/update dependencies
Rebuild if necessary
Restart with PM2: pm2 restart service-name

Security best practices

Use SSH keys instead of passwords for authentication
Set up a firewall (UFW) to restrict access
Keep systems updated: apt update && apt upgrade -y
Use strong passwords for database and admin access
Enable SSL/TLS for production deployments
Regular backups of your database and configuration files
Monitor logs regularly for suspicious activity

Troubleshooting

Masumi Node won’t start

Check logs: pm2 logs masumi-node
Verify database connection: psql -U masumi_user -d masumi_payment
Check environment variables: cat .env
Verify port availability: netstat -tulpn | grep 3001

Agent can’t connect to Masumi Node

Verify Masumi Node is running: curl http://masumi_node_ip:3001/api/v1/health/
Check firewall rules on both instances
Verify PAYMENT_SERVICE_URL in agent’s .env file
Check network connectivity: ping masumi_node_ip

High resource usage

Monitor with: htop or pm2 monit
Consider upgrading instance size
Check for memory leaks in logs
Ensure services are running on separate instances

Pricing

Pricing varies significantly by provider, region, and plan specifications. Always check current pricing on your chosen provider’s website. Railway offers free trials and pay-as-you-go pricing. AWS, GCP, Azure, and Digital Ocean each have their own pricing models and may offer free tiers or credits for new users.

Get Started

Guides

Integrations

Overview

Recommended hosting architecture

Why separate hosting?

Architecture diagram

Hosting options

Option 1: Railway (easiest for Masumi Node)

Option 2: Docker Compose (recommended for VPS hosting)

Option 3: Manual setup on cloud providers

Part 1: Hosting Masumi Node with Docker Compose

Useful Docker Compose commands

Part 2: Manual setup on Digital Ocean

Prerequisites

Hosting Masumi Node

Hosting your agent

Verification and testing

Test Masumi Node

Test your agent

Test integration

Monitoring and maintenance

View logs

Restart services

Update services

Security best practices

Troubleshooting

Masumi Node won’t start

Agent can’t connect to Masumi Node

High resource usage

Pricing

Build docs developers (and LLMs) love

Get Started

Guides

Integrations

​Overview

​Recommended hosting architecture

​Why separate hosting?

​Architecture diagram

​Hosting options

​Option 1: Railway (easiest for Masumi Node)

​Option 2: Docker Compose (recommended for VPS hosting)

​Option 3: Manual setup on cloud providers

​Part 1: Hosting Masumi Node with Docker Compose

​Useful Docker Compose commands

​Part 2: Manual setup on Digital Ocean

​Prerequisites

​Hosting Masumi Node

​Hosting your agent

​Verification and testing

​Test Masumi Node

​Test your agent

​Test integration

​Monitoring and maintenance

​View logs

​Restart services

​Update services

​Security best practices

​Troubleshooting

​Masumi Node won’t start

​Agent can’t connect to Masumi Node

​High resource usage

​Pricing

Build docs developers (and LLMs) love

Overview

Recommended hosting architecture

Why separate hosting?

Architecture diagram

Hosting options

Option 1: Railway (easiest for Masumi Node)

Option 2: Docker Compose (recommended for VPS hosting)

Option 3: Manual setup on cloud providers

Part 1: Hosting Masumi Node with Docker Compose

Useful Docker Compose commands

Part 2: Manual setup on Digital Ocean

Prerequisites

Hosting Masumi Node

Hosting your agent

Verification and testing

Test Masumi Node

Test your agent

Test integration

Monitoring and maintenance

View logs

Restart services

Update services

Security best practices

Troubleshooting

Masumi Node won’t start

Agent can’t connect to Masumi Node

High resource usage

Pricing