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.

Recommended Hosting Architecture

Why Separate Hosting?

1. 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.

2. Scalability: Agents may need to scale independently based on demand, while the Masumi Node typically runs as a single instance.

3. Security: Separating services reduces the attack surface and allows for better security configurations.

4. 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.

Advantages:

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

Note: 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.

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

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.

Step 1: 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

Step 2: Initial Server Setup

SSH into your instance:

ssh root@your_instance_ip

Update the system:

apt update && apt upgrade -y

Step 3: 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

Step 4: 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

Step 5: 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

Step 6: Start Services with Docker Compose

Start all services:

docker compose up -d

Check service status:

docker compose ps

View logs:

docker compose logs -f

Step 7: Configure Firewall

Allow necessary ports:

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

Step 8: 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.

Step 9: 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

Step 10: 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

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 2: Manual Setup on Digital Ocean (Example)

This section walks you through hosting both components on Digital Ocean using separate droplets. Remember: These same steps can be adapted for AWS, GCP, Azure, or any other VPS provider - just replace "droplet" with "instance" or "VM" as appropriate.

Prerequisites

• Digital Ocean account
• Basic knowledge of Linux command line
• SSH access to your local machine

Part 1: Hosting Masumi Node

Step 1: Create a Droplet

1. Log in to your Digital Ocean dashboard

2. Click "Create" → "Droplets"

3. 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)

4. Click "Create Droplet"

Step 2: Initial Server Setup

Once your droplet is created, SSH into it:

ssh root@your_droplet_ip

Update the system:

apt update && apt upgrade -y

Step 3: 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

Step 4: 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

Step 5: 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

Step 6: 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

Step 7: 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

Step 8: 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.

Step 9: Configure Firewall

Allow necessary ports:

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

Step 10: 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

Step 11: 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

Part 3: Hosting Your Agent

Step 1: Create a Separate Droplet

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

Step 2: Set Up Your Agent Environment

SSH into your agent droplet:

ssh root@your_agent_droplet_ip

Update the system:

apt update && apt upgrade -y

Step 3: 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

Step 4: 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

Step 5: 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
# ...

Step 6: 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

Step 7: Configure Firewall

Allow necessary ports:

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

Step 8: Set Up Reverse Proxy (Optional)

If you want to expose your agent via a domain, set up Nginx similar to Part 1, Step 10, but point to your agent's port (typically 8000).

Verification and Testing

Test Masumi Node

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

Test Your Agent

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

Test Integration

1. Register your agent on the Masumi Network through the admin dashboard
2. 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:

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

Security Best Practices

1. Use SSH keys instead of passwords for authentication
2. Set up a firewall (UFW) to restrict access
3. Keep systems updated: apt update && apt upgrade -y
4. Use strong passwords for database and admin access
5. Enable SSL/TLS for production deployments
6. Regular backups of your database and configuration files
7. 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