Skip to content

VM_DEPLOYMENT_GUIDE.md

Latest commit

 

History

History
433 lines (322 loc) · 20.8 KB

VM_DEPLOYMENT_GUIDE.md

File metadata and controls

433 lines (322 loc) · 20.8 KB
Raw

OmniRoute — Deployment Guide on VM with Cloudflare (Hausa)

🌐 Languages: 🇺🇸 English · 🇪🇹 am · 🇸🇦 ar · 🇦🇿 az · 🇧🇬 bg · 🇧🇩 bn · 🇧🇦 bs · 🇨🇿 cs · 🇩🇰 da · 🇩🇪 de · 🇬🇷 el · 🇪🇸 es · 🇪🇪 et · 🇮🇷 fa · 🇫🇮 fi · 🇫🇷 fr · 🇮🇪 ga · 🇮🇳 gu · 🇮🇱 he · 🇮🇳 hi · 🇭🇷 hr · 🇭🇺 hu · 🇦🇲 hy · 🇮🇩 id · 🇳🇬 ig · 🇮🇹 it · 🇯🇵 ja · 🇬🇪 ka · 🇰🇭 km · 🇮🇳 kn · 🇰🇷 ko · 🇱🇹 lt · 🇱🇻 lv · 🇮🇳 ml · 🇮🇳 mr · 🇲🇾 ms · 🇲🇹 mt · 🇲🇲 my · 🇳🇵 ne · 🇳🇱 nl · 🇳🇴 no · 🇮🇳 or · 🇮🇳 pa · 🇵🇭 phi · 🇵🇱 pl · 🇵🇹 pt · 🇧🇷 pt-BR · 🇷🇴 ro · 🇷🇺 ru · 🇱🇰 si · 🇸🇰 sk · 🇸🇮 sl · 🇷🇸 sr · 🇸🇪 sv · 🇰🇪 sw · 🇮🇳 ta · 🇮🇳 te · 🇹🇭 th · 🇹🇷 tr · 🇺🇦 uk-UA · 🇵🇰 ur · 🇺🇿 uz · 🇻🇳 vi · 🇳🇬 yo · 🇨🇳 zh-CN · 🇹🇼 zh-TW

🌐 Languages: 🇺🇸 English · 🇪🇹 am · 🇸🇦 ar · 🇦🇿 az · 🇧🇬 bg · 🇧🇩 bn · 🇧🇦 bs · 🇨🇿 cs · 🇩🇰 da · 🇩🇪 de · 🇬🇷 el · 🇪🇸 es · 🇪🇪 et · 🇮🇷 fa · 🇫🇮 fi · 🇫🇷 fr · 🇮🇪 ga · 🇮🇳 gu · 🇮🇱 he · 🇮🇳 hi · 🇭🇷 hr · 🇭🇺 hu · 🇦🇲 hy · 🇮🇩 id · 🇳🇬 ig · 🇮🇹 it · 🇯🇵 ja · 🇬🇪 ka · 🇰🇭 km · 🇮🇳 kn · 🇰🇷 ko · 🇱🇹 lt · 🇱🇻 lv · 🇮🇳 ml · 🇮🇳 mr · 🇲🇾 ms · 🇲🇹 mt · 🇲🇲 my · 🇳🇵 ne · 🇳🇱 nl · 🇳🇴 no · 🇮🇳 or · 🇮🇳 pa · 🇵🇭 phi · 🇵🇱 pl · 🇵🇹 pt · 🇧🇷 pt-BR · 🇷🇴 ro · 🇷🇺 ru · 🇱🇰 si · 🇸🇰 sk · 🇸🇮 sl · 🇷🇸 sr · 🇸🇪 sv · 🇰🇪 sw · 🇮🇳 ta · 🇮🇳 te · 🇹🇭 th · 🇹🇷 tr · 🇺🇦 uk-UA · 🇵🇰 ur · 🇺🇿 uz · 🇻🇳 vi · 🇳🇬 yo · 🇨🇳 zh-CN · 🇹🇼 zh-TW

Cikakken jagora don girka da saita OmniRoute a kan VM (VPS) mai yankin yanar gizo da ake sarrafawa ta Cloudflare.

Abubuwan da ake buƙata tun farko

Abu Mafi ƙaranci Wanda aka ba da shawara
CPU 1 vCPU 2 vCPU
RAM 1 GB 2 GB
Faifai 10 GB SSD 25 GB SSD
OS Ubuntu 22.04 LTS Ubuntu 24.04 LTS
Domain An yi rajista a Cloudflare —
Docker Docker Engine 24+ Docker 27+

Masu samar da sabis da aka gwada: Akamai (Linode), DigitalOcean, Vultr, Hetzner, AWS Lightsail.

1. Saita VM

1.1 Ƙirƙiri instance

A wurin mai samar da VPS da ka fi so:

  • Zaɓi Ubuntu 24.04 LTS
  • Zaɓi tsari mafi ƙaranci (1 vCPU / 1 GB RAM)
  • Saita kalmar sirrin root mai ƙarfi ko saita maɓallin SSH
  • Rubuta public IP ɗin (misali, 203.0.113.10)

1.2 Haɗa ta SSH

ssh root@203.0.113.10

1.3 Sabunta tsarin

apt update && apt upgrade -y

1.4 Shigar da Docker

# Shigar da abubuwan dogaro
apt install -y ca-certificates curl gnupg

# Ƙara ma'ajiyar Docker ta hukuma
install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | gpg --dearmor -o /etc/apt/keyrings/docker.gpg
chmod a+r /etc/apt/keyrings/docker.gpg
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu $ (. /etc/os-release && echo "$VERSION_CODENAME") stable" | tee /etc/apt/sources.list.d/docker.list > /dev/null
apt update
apt install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin

1.5 Shigar da nginx

apt install -y nginx

1.6 Saita Firewall (UFW)

ufw default deny incoming
ufw default allow outgoing
ufw allow 22/tcp    # SSH
ufw allow 80/tcp    # HTTP (turawa)
ufw allow 443/tcp   # HTTPS
ufw enable

Shawara: Don samun tsaro mafi ƙarfi, taƙaita tashoshin 80 da 443 ga IP na Cloudflare kawai. Duba sashen Tsaro na Ci-gaba.

2. Shigar da OmniRoute

2.1 Ƙirƙiri kundin saituna

mkdir -p /opt/omniroute

2.2 Ƙirƙiri fayil ɗin environment variables

cat > /opt/omniroute/.env << 'EOF'
# === Tsaro ===
JWT_SECRET=CHANGE-TO-A-UNIQUE-64-CHAR-SECRET-KEY
INITIAL_PASSWORD=YourSecurePassword123!
API_KEY_SECRET=REPLACE-WITH-ANOTHER-SECRET-KEY
STORAGE_ENCRYPTION_KEY=REPLACE-WITH-THIRD-SECRET-KEY
STORAGE_ENCRYPTION_KEY_VERSION=v1
MACHINE_ID_SALT=CHANGE-TO-A-UNIQUE-SALT
OMNIROUTE_WS_BRIDGE_SECRET=REPLACE-WITH-WS-BRIDGE-SECRET  # ANA BUƘATA a production: Codex Responses WS bridge ne ke amfani da shi

# === Manhaja ===
PORT=20128
NODE_ENV=production
HOSTNAME=0.0.0.0
DATA_DIR=/app/data
APP_LOG_TO_FILE=true
AUTH_COOKIE_SECURE=true
REQUIRE_API_KEY=false

# === URLs (canza zuwa domain ɗinka) ===
# Base URL na cikin gida tsakanin server-da-server don ayyukan da aka tsara / self-fetches.
BASE_URL=http://127.0.0.1:20128
# URL da browser ke gani wanda ake amfani da shi don OAuth callbacks, dashboard links, da public URLs da aka samar.
NEXT_PUBLIC_BASE_URL=https://llms.seudominio.com
# Zaɓin bayyanannen public origin override don public asset URLs da aka samar.
# OMNIROUTE_PUBLIC_BASE_URL=https://llms.seudominio.com

# === Cloud Sync (na zaɓi) ===
# CLOUD_URL=https://cloud.omniroute.online
# NEXT_PUBLIC_CLOUD_URL=https://cloud.omniroute.online
EOF

⚠️ MUHIMMI: Samar da maɓallan sirri na musamman! Yi amfani da openssl rand -hex 32 ga kowane maɓalli.

2.3 Fara container

docker pull diegosouzapw/omniroute:latest

docker run -d \
  --name omniroute \
  --restart unless-stopped \
  --env-file /opt/omniroute/.env \
  -p 20128:20128 \
  -v omniroute-data:/app/data \
  diegosouzapw/omniroute:latest

2.4 Tabbatar cewa yana aiki

docker ps | grep omniroute
docker logs omniroute --tail 20

Ya kamata ya nuna: [DB] SQLite database ready da listening on port 20128.

3. Saita nginx (Reverse Proxy)

3.1 Samar da takardar shaidar SSL (Cloudflare Origin)

A cikin dashboard na Cloudflare:

  1. Je zuwa SSL/TLS → Origin Server
  2. Danna Create Certificate
  3. Bar saitunan asali (shekaru 15, *.yourdomain.com)
  4. Kwafi Origin Certificate da Private Key
mkdir -p /etc/nginx/ssl

# Liƙa takardar shaidar
nano /etc/nginx/ssl/origin.crt

# Liƙa maɓallin sirri
nano /etc/nginx/ssl/origin.key

chmod 600 /etc/nginx/ssl/origin.key

3.2 Tsarin Saitin Nginx

cat > /etc/nginx/sites-available/omniroute << 'NGINX'
# Sabar asali — tana hana shiga kai tsaye ta hanyar IP
server {
    listen 80 default_server;
    listen [::]:80 default_server;
    listen 443 ssl default_server;
    listen [::]:443 ssl default_server;
    ssl_certificate     /etc/nginx/ssl/origin.crt;
    ssl_certificate_key /etc/nginx/ssl/origin.key;
    server_name _;
    return 444;
}

# OmniRoute — HTTPS
server {
    listen 443 ssl;
    listen [::]:443 ssl;
    server_name llms.yourdomain.com;  # Canja zuwa domain ɗinka

    ssl_certificate     /etc/nginx/ssl/origin.crt;
    ssl_certificate_key /etc/nginx/ssl/origin.key;
    ssl_protocols TLSv1.2 TLSv1.3;

    client_max_body_size 100M;

    location / {
        proxy_pass http://127.0.0.1:20128;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-Host $host;
        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;

        # Tallafin WebSocket
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";

        # SSE (Abubuwan da Saba ke Aikowa) — aika martanin AI kai tsaye
        proxy_buffering off;
        proxy_cache off;
        proxy_read_timeout 600s;
        proxy_send_timeout 600s;
    }
}

# Mayar da HTTP → HTTPS
server {
    listen 80;
    listen [::]:80;
    server_name llms.yourdomain.com;
    return 301 https://$server_name$request_uri;
}
NGINX

Ka daidaita wa'adin ƙarewar lokaci na rafin reverse-proxy da env vars na wa'adin ƙarewar lokaci na OmniRoute. Idan ka ƙara FETCH_TIMEOUT_MS / STREAM_IDLE_TIMEOUT_MS, ƙara proxy_read_timeout / proxy_send_timeout sama da wannan iyaka.

OmniRoute yana amfani da NEXT_PUBLIC_BASE_URL a matsayin tushen adireshin da browser ke fuskanta don callbacks na OAuth da hanyoyin haɗin jama'a da aka samar. Rubuce-rubucen dashboard da aka tabbatar da izini suna amfani da buƙatun same-origin tare da kariyar CSRF mai alaƙa da session, saboda haka ba sa buƙatar tsayayyen URL na jama'a. Headers na X-Forwarded-* da ke sama har yanzu metadata ne masu amfani wajen routing, amma ba sa maye gurbin saita takamaiman URL na jama'a lokacin da OAuth ko hanyoyin haɗin browser da aka samar suke buƙatarsa. Kunna OMNIROUTE_TRUST_PROXY kawai idan clients ba za su iya isa ga OmniRoute kai tsaye ba kuma proxy ɗinka yana cirewa/sake gina forwarded headers masu shigowa.

3.3 Kunna kuma Gwada

# Cire tsarin saitin asali
rm -f /etc/nginx/sites-enabled/default

# Kunna OmniRoute
ln -sf /etc/nginx/sites-available/omniroute /etc/nginx/sites-enabled/omniroute

# Gwada kuma sake lodawa
nginx -t && systemctl reload nginx

4. Saita Cloudflare DNS

4.1 Ƙara rikodin DNS

A cikin dashboard na Cloudflare → DNS:

Nau'i Suna Abun ciki Proxy
A llms 203.0.113.10 (IP na VM) ✅ An yi Proxy

4.2 Saita SSL

A ƙarƙashin SSL/TLS → Overview:

  • Yanayi: Full (Strict)

A ƙarƙashin SSL/TLS → Edge Certificates:

  • Koyaushe Yi Amfani da HTTPS: ✅ Kunna
  • Mafi Ƙarancin Sigar TLS: TLS 1.2
  • Sake Rubuta HTTPS ta Atomatik: ✅ Kunna

4.3 Gwaji

curl -sI https://llms.seudominio.com/health
# Ya kamata ya mayar da HTTP/2 200

5. Ayyuka da Kulawa

Ɗaukaka zuwa sabuwar siga

docker pull diegosouzapw/omniroute:latest
docker stop omniroute && docker rm omniroute
docker run -d --name omniroute --restart unless-stopped \
  --env-file /opt/omniroute/.env \
  -p 20128:20128 \
  -v omniroute-data:/app/data \
  diegosouzapw/omniroute:latest

Duba rajistan ayyuka

docker logs -f omniroute          # Gudanarwa kai tsaye
docker logs omniroute --tail 50   # Layuka 50 na ƙarshe

Ajiyar bayanai ta hannu

# Kwafi bayanai daga volume zuwa host
docker cp omniroute:/app/data ./backup-$(date +%F)

# Ko a matse dukan volume
docker run --rm -v omniroute-data:/data -v $(pwd):/backup \
  alpine tar czf /backup/omniroute-data-$(date +%F).tar.gz /data

Maidowa daga ajiyar bayanai

docker stop omniroute
docker run --rm -v omniroute-data:/data -v $(pwd):/backup \
  alpine sh -c "rm -rf /data/* && tar xzf /backup/omniroute-data-YYYY-MM-DD.tar.gz -C /"
docker start omniroute

6. Tsaro na Ci-gaba

Ƙuntata nginx ga IP na Cloudflare

cat > /etc/nginx/cloudflare-ips.conf << 'CF'
# Jerin adiresoshin IPv4 na Cloudflare — sabunta lokaci-lokaci
# https://www.cloudflare.com/ips-v4/
set_real_ip_from 173.245.48.0/20;
set_real_ip_from 103.21.244.0/22;
set_real_ip_from 103.22.200.0/22;
set_real_ip_from 103.31.4.0/22;
set_real_ip_from 141.101.64.0/18;
set_real_ip_from 108.162.192.0/18;
set_real_ip_from 190.93.240.0/20;
set_real_ip_from 188.114.96.0/20;
set_real_ip_from 197.234.240.0/22;
set_real_ip_from 198.41.128.0/17;
set_real_ip_from 162.158.0.0/15;
set_real_ip_from 104.16.0.0/13;
set_real_ip_from 104.24.0.0/14;
set_real_ip_from 172.64.0.0/13;
set_real_ip_from 131.0.72.0/22;
real_ip_header CF-Connecting-IP;
CF

Ƙara waɗannan zuwa nginx.conf a cikin sashen http {}:

include /etc/nginx/cloudflare-ips.conf;

Shigar da fail2ban

apt install -y fail2ban
systemctl enable fail2ban
systemctl start fail2ban

# Duba matsayi
fail2ban-client status sshd

Toshe samun dama kai tsaye zuwa port na Docker

# Hana samun dama ta waje kai tsaye zuwa port 20128
iptables -I DOCKER-USER -p tcp --dport 20128 -j DROP
iptables -I DOCKER-USER -i lo -p tcp --dport 20128 -j ACCEPT

# Adana ƙa'idojin har abada
apt install -y iptables-persistent
netfilter-persistent save

7. Tura zuwa Cloudflare Workers (Na Zaɓi)

Don samun dama daga nesa ta hanyar Cloudflare Workers (ba tare da fallasa VM kai tsaye ba):

# A cikin ma'ajiyar lamba ta gida
cd omnirouteCloud
npm install
npx wrangler login
npx wrangler deploy

Duba kuma TUNNELS_GUIDE.md don jagorar Cloudflare Tunnel da ke cikin ma'ajiyar lambar. Ma'aikacin omnirouteCloud/ mai zaman kansa yana cikin wata ma'ajiyar lambar haɗin gwiwa ta daban.

Taƙaitaccen Bayanin Tashoshin Sadarwa

Tashar Sadarwa Sabis Samun Dama
22 SSH Na jama'a (tare da fail2ban)
80 nginx HTTP Turawa → HTTPS
443 nginx HTTPS Ta Cloudflare Proxy
20128 OmniRoute Localhost kawai (ta nginx)

Ingantawa don Ƙarancin Ƙwaƙwalwar Ajiya / Ƙaramin VPS

Don turawa a kan ƙananan VPS (RAM 1 GB ko ƙasa da haka):

  • Kashe sabis na bayan fage — saita OMNIROUTE_DISABLE_BACKGROUND_SERVICES=1 don tsallake mai tsara ayyuka, uwar garken MCP, da ayyukan kulawa na lokaci-lokaci. Duba docs/reference/ENVIRONMENT.md.
  • Yi amfani da yanayin SQLite WAL — ana kunna shi ta tsohuwa, kuma yana rage iyakar amfani da ƙwaƙwalwar ajiya yayin karantawa da yawa a lokaci guda.
  • Iyakance heap na V8 — saita OMNIROUTE_MEMORY_MB (misali 512) don kada runtime ya daidaita iyakar da ta fi ƙarfin VM. Duba docs/reference/ENVIRONMENT.md.
  • Karɓar manyan ayyuka na daidaita kansa bisa iyakar heap -- da zarar an saita OMNIROUTE_MEMORY_MB a sama, kasafin byte na shigarwa (OMNIROUTE_CHAT_MAX_INFLIGHT_BYTES) yana samo kansa daga wannan iyakar, don haka VM mai ƙarancin ƙwaƙwalwar ajiya zai riga ya sami ƙaramin kasafin buƙatun lokaci guda ba tare da ƙarin daidaitawa ba; buƙatun da suka wuce iyaka za su sami 503 mai yiwuwa a sake gwadawa tare da Retry-After, maimakon yin takara kan ƙwaƙwalwar ajiya. Saita tsohuwar iyakar ƙidayar buƙatu ta OMNIROUTE_CHAT_MAX_HEAVY_IN_FLIGHT kawai idan kana buƙatar tsayayyar iyaka a saman wannan.
  • Guji next build a kan VPS — yi ginin a na'urarka sannan ka tura fitarwar standalone (.next/standalone/).
  • Sa ido da top / free -m — OmniRoute yawanci yana amfani da RSS 200-400 MB lokacin da ba ya aiki a kan VM mai RAM 1 GB.