Message Box Server

MESSAGE BOX SERVER - USAGE INSTRUCTIONS

This container provides a peer-to-peer message routing server for BSV wallet applications, exposing HTTP endpoints and a WebSocket server for identity-based, encrypted messaging. Nginx fronts the app on port 8080. Image: 709825985650.dkr.ecr.us-east-1.amazonaws.com/bsv-blockchain/message-box-server:<version>

1. PREREQUISITES

• AWS account with permissions to pull from Marketplace ECR and run containers (ECS/EKS/EC2).
• MySQL 8.0 database reachable from the container (Amazon RDS recommended). Tables auto-create on first launch.
• Outbound HTTPS to wallet storage and BSV services; inbound HTTP/WebSocket on port 8080.
• Minimum 1 vCPU, 1 GB RAM; recommended 2 vCPU, 3 GB RAM for production.
• A 32-byte hex private key (store in Secrets Manager).
• URL of a deployed wallet storage service.

2. CONFIGURATION Set these environment variables:

• NODE_ENV: production
• PORT: 3000
• SERVER_PRIVATE_KEY: 64-character hex string (secret)
• WALLET_STORAGE_URL: https://your-wallet-storage-endpoint 
• KNEX_DB_CONNECTION: {"host":"<rds-endpoint>","port":3306,"user":"messagebox_admin","password":"<secret>","database":"messagebox_backend"}
• ENABLE_WEBSOCKETS: true
• HOSTING_DOMAIN: https://your-public-domain 
• BSV_NETWORK: main (or test)

Optional: LOGGING_ENABLED, ROUTING_PREFIX, ENABLE_FIREBASE with FIREBASE_PROJECT_ID and FIREBASE_SERVICE_ACCOUNT_JSON.

Before first launch, create the database: CREATE DATABASE messagebox_backend; CREATE USER 'messagebox_admin'@'%' IDENTIFIED BY '<password>'; GRANT ALL PRIVILEGES ON messagebox_backend.* TO 'messagebox_admin'@'%';

3. STEP-BY-STEP DEPLOYMENT (Amazon ECS on Fargate) Step 1: Authenticate Docker to Marketplace ECR: aws ecr get-login-password --region us-east-1 | docker login --username AWS --password-stdin 709825985650.dkr.ecr.us-east-1.amazonaws.com

Step 2: Provision Amazon RDS for MySQL 8.0 in your VPC. Create the messagebox_backend database and user.

Step 3: Store SERVER_PRIVATE_KEY and KNEX_DB_CONNECTION in AWS Secrets Manager. Grant the ECS task execution role read access.

Step 4: Create an ECS task definition using the Marketplace image. Map container port 8080. Inject env vars from Secrets Manager. Set CPU 1024, memory 3072.

Step 5: Create a Fargate service in a private subnet with outbound internet (NAT gateway). Place behind an Application Load Balancer with HTTPS listener and target group on port 8080. Health check: HTTP GET / expecting 200. Enable sticky sessions for WebSockets.

Step 6: Point Route 53 at the ALB and attach an ACM certificate.

4. VERIFYING THE APPLICATION IS RUNNING

• CloudWatch Logs show the server starting and listening on the configured port.
• Test HTTP: curl https://<your-domain>/ returns 200.
• Verify Knex created tables: connect to MySQL, run "USE messagebox_backend; SHOW TABLES;" - expect messages, notification_permissions, device_registrations.
• WebSocket: connect a BRC-103 authenticated client to wss://<your-domain> and confirm the "authenticated" event fires.
• Confirm ALB target group reports the task as healthy.

5. MONITORING

• CloudWatch Logs via awslogs driver on the ECS task.
• Container Insights for CPU, memory, network metrics. Alarm at 80% CPU/memory and on task count below desired.
• ALB metrics: HealthyHostCount, HTTPCode_Target_5XX_Count, TargetResponseTime, ActiveConnectionCount (WebSockets hold connections open).
• RDS: enable Enhanced Monitoring and Performance Insights. Watch connections, slow queries on the messages table, storage.
• External health checks: poll GET https://<your-domain>/ for 200.

DOCUMENTATION

• Source: https://github.com/bitcoin-sv/messagebox-server 
• API: POST /sendMessage, /listMessages, /acknowledgeMessage

SUPPORT GitHub Issues: https://github.com/bsv-blockchain/message-box-server/issues