BACKEND DEPLOYMENT GUIDE

Activate the Backend

The website is already live on Vercel. To activate the Telegram bot, SMS intake, and AI forensics pipeline, you need a backend server. This guide walks through the full setup.

ARCHITECTURE
safuu.net (Vercel — already live)
Backend API (Your VPS — this guide)
  ├── safuu-bot.js    ← Telegram intake
  ├── safuu-server.js  ← REST API + WebSocket
  ├── safuu-sms.js    ← SMS intake (21000)
  └── safuu-security.js ← Encryption, JWT, RBAC

SETUP STEPS

01Provision a server

# Ubuntu 24.04 LTS recommended
# Minimum: 2 vCPU · 2GB RAM · 20GB disk
# Recommended: 4 vCPU · 4GB RAM
# Any VPS provider: DigitalOcean, Linode, Hetzner, AWS, etc.

02Clone the repository

git clone https://github.com/sifgamachu/safuu-intel
cd safuu-intel/backend

03Run the setup script

bash setup.sh
# This generates all secrets, installs deps
# and runs the 76 automated security tests

04Fill in environment variables

cp safuu-security.env.example .env
nano .env  # fill in all REPLACE_ME_ values
# See the table above for each variable

05Start with PM2

pm2 start ecosystem.config.js
pm2 save && pm2 startup
# This starts: safuu-server, safuu-bot, safuu-sms

06Set up Nginx

sudo cp safuu-nginx.conf /etc/nginx/sites-available/safuu-intel
sudo ln -s /etc/nginx/sites-available/safuu-intel /etc/nginx/sites-enabled/
sudo certbot --nginx -d your-api-domain.com
sudo nginx -t && sudo nginx -s reload

07Verify everything works

node test.js           # 76 tests — all should pass
curl localhost:3001/health  # should return {status:'ok'}
pm2 status             # all processes should be 'online'

08Activate the Telegram bot

# In BotFather:
# /setdescription — Add your bot description
# /setcommands — Start the bot
# Test: message your bot — should respond with step 1 of 11

ENVIRONMENT VARIABLES

VARIABLE
REQUIRED
DESCRIPTION

TELEGRAM_BOT_TOKEN

required

Create a bot with /newbot, copy the token

Source: @BotFather on Telegram

ADMIN_CHANNEL_ID

required

Create a channel, add the bot as admin, get the -100xxxxxxxxx ID

Source: Telegram private channel

ANTHROPIC_API_KEY

required

Generate at Anthropic console — used for Claude AI analysis

Source: console.anthropic.com

OPENAI_API_KEY

required

Used for Whisper voice transcription — 11 Ethiopian languages

Source: platform.openai.com

HIVE_AI_KEY

required

Free trial available — AI-image detection (94% accuracy)

Source: thehive.ai

ENCRYPTION_MASTER_KEY

required

Run command on your server — never share this key

Source: openssl rand -hex 32

DEDUP_SALT

required

Used for SHA-256 reporter deduplication hashing

Source: openssl rand -hex 32

JWT_SECRET

required

For admin dashboard JWT authentication

Source: openssl rand -hex 32

DASHBOARD_API_KEY

required

API key for programmatic dashboard access

Source: openssl rand -hex 32

HIVE_API_URL

optional

Default: https://api.thehive.ai/api/v2/task/sync

Source: thehive.ai docs

SMS_USERNAME

optional

For SMS intake via shortcode 21000

Source: Africa's Talking dashboard

SMS_API_KEY

optional

Africa's Talking API key for SMS

Source: Africa's Talking dashboard

DISCLOSURE_THRESHOLD

optional

Number of verified reports to trigger name disclosure (default: 15)

Source: Your choice

COMMON ISSUES

Bot not responding

Check TELEGRAM_BOT_TOKEN is correct. Run: curl https://api.telegram.org/bot{TOKEN}/getMe

Database errors on start

The setup.sh script creates the SQLite database. If it's missing, run setup.sh again.

Tests failing

node test.js from the backend/ folder. Most failures are missing env vars — check your .env file.

Port already in use

pm2 delete all && pm2 start ecosystem.config.js — or change PORT in .env

Nginx 502 Bad Gateway

The backend API isn't running. Check pm2 status and pm2 logs safuu-server

NEED HELP?

Open a GitHub issue with the error message, your server OS and Node.js version, and which step failed.

OPEN A GITHUB ISSUE →