RAZARZ Frontend Deployment Guide

Overview

This guide covers the deployment of both Telegram Mini App (TMA) and Trusted Web App (TWA) with Traefik integration.

🏗️ Architecture

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   Traefik       │    │   TMA Stack     │    │   TWA Stack     │
│   (Load Balancer)│    │   (tma.nextgiti.cloud)│    │   (nextgiti.cloud)  │
└─────────────────┘    └─────────────────┘    └─────────────────┘
         │                       │                       │
         └───────────────────────┼───────────────────────┘
                                 │
                    ┌─────────────────┐
                    │   Backend API   │
                    │   (api.nextgiti.cloud)│
                    └─────────────────┘

📱 TMA (Telegram Mini App) - tma.nextgiti.cloud

Prerequisites

  • Docker Swarm enabled
  • Traefik network exists
  • Backend API running

Environment Setup

  1. Copy environment template:
cd ../gitinext-tma
cp env.example .env
  1. Configure .env:
# API Configuration
NEXT_PUBLIC_API_URL=https://api.nextgiti.cloud

# Telegram Mini App Configuration
NEXT_PUBLIC_TELEGRAM_BOT_TOKEN=7506518563:AAHdgHj9Zh1LKmZpbr9O4Qch-LIFtoxI28o
NEXT_PUBLIC_TELEGRAM_BOT_USERNAME=GitiNextWalletBot

# Development
NEXT_PUBLIC_IS_DEVELOPMENT=false

# Docker Configuration
VERSION=latest
REGISTRY=registry.nextgiti.cloud:5000
SERVICE_NAME=tma
STACK_NAME=gitinext-tma

Deployment Commands

From Backend Directory:

# Build and deploy TMA
make tma-build
make tma-push
make tma-deploy

# Update existing TMA
make tma-update

From TMA Directory:

cd ../gitinext-tma

# Build Docker image
make build

# Push to registry
make push

# Deploy stack
make deploy

# Update service
make update

# View logs
make logs

# Check status
make status

Traefik Configuration

The TMA is configured with:

  • Domain: tma.nextgiti.cloud
  • SSL: Automatic Let’s Encrypt
  • Port: 3000 (Next.js default)
  • Network: External Traefik network

🌐 TWA (Trusted Web App) - nextgiti.cloud

Prerequisites

  • Docker Swarm enabled
  • Traefik network exists
  • Backend API running

Environment Setup

  1. Copy environment template:
cd ../gitinext-twa
cp env.example .env
  1. Configure .env:
# API Configuration
NEXT_PUBLIC_API_URL=https://api.nextgiti.cloud

# TWA Configuration
NEXT_PUBLIC_TWA_ENABLED=true
NEXT_PUBLIC_APP_NAME=GitiNext Wallet

# Development
NEXT_PUBLIC_IS_DEVELOPMENT=false

# Docker Configuration
VERSION=latest
REGISTRY=registry.nextgiti.cloud:5000
SERVICE_NAME=twa
STACK_NAME=gitinext-twa

Deployment Commands

From Backend Directory:

# Build and deploy TWA
make twa-build
make twa-push
make twa-deploy

# Update existing TWA
make twa-update

From TWA Directory:

cd ../gitinext-twa

# Build Docker image
make build

# Push to registry
make push

# Deploy stack
make deploy

# Update service
make update

# View logs
make logs

# Check status
make status

Traefik Configuration

The TWA is configured with:

  • Domain: nextgiti.cloud
  • SSL: Automatic Let’s Encrypt
  • Port: 3000 (Next.js default)
  • Network: External Traefik network

🚀 Complete Deployment

Deploy All Frontends

# From backend directory
make frontend-build
make frontend-push
make frontend-deploy

Update All Frontends

# From backend directory
make frontend-update

🔧 Troubleshooting

Common Issues

1. Traefik Network Not Found

# Check if Traefik network exists
docker network ls | grep traefik

# If not found, create it (if you have Traefik running)
docker network create traefik

2. Service Not Starting

# Check service logs
make logs  # (from respective directory)

# Check service status
make status  # (from respective directory)

# Check Docker Swarm services
docker service ls

3. SSL Certificate Issues

# Check Traefik logs
docker service logs traefik_traefik

# Verify domain configuration
docker service inspect gitinext-tma_tma | grep -A 10 Labels
docker service inspect gitinext-twa_twa | grep -A 10 Labels

4. Build Issues

# Clean and rebuild
make clean
make build

# Check Docker build context
docker build --no-cache -t test .

Debugging Commands

Check Service Status

# List all services
docker service ls

# Inspect specific service
docker service inspect gitinext-tma_tma
docker service inspect gitinext-twa_twa

# Check service tasks
docker service ps gitinext-tma_tma
docker service ps gitinext-twa_twa

Check Networks

# List networks
docker network ls

# Inspect Traefik network
docker network inspect traefik

Check Logs

# TMA logs
docker service logs -f gitinext-tma_tma

# TWA logs
docker service logs -f gitinext-twa_twa

# Traefik logs
docker service logs -f traefik_traefik

📊 Monitoring

Health Checks

  • TMA: https://tma.nextgiti.cloud/health
  • TWA: https://nextgiti.cloud/health

Metrics

  • Service Status: docker service ls
  • Resource Usage: docker stats
  • Network Traffic: Traefik dashboard

🔒 Security

SSL/TLS

  • Automatic Let’s Encrypt certificates
  • HTTPS redirect enabled
  • Secure headers configured

Environment Variables

  • Sensitive data in .env files
  • No secrets in Docker images
  • Registry authentication required

📝 Maintenance

Regular Updates

# Update all frontends
make frontend-update

# Update individual services
make tma-update
make twa-update

Backup

# Backup environment files
cp ../gitinext-tma/.env ../gitinext-tma/.env.backup
cp ../gitinext-twa/.env ../gitinext-twa/.env.backup

Cleanup

# Clean Docker resources
make clean  # (from respective directory)

# Remove stacks
make clean-stack  # (from respective directory)

🎯 Success Criteria

TMA Deployment

  • ✅ Service running: docker service ls | grep gitinext-tma
  • ✅ Domain accessible: https://tma.nextgiti.cloud
  • ✅ SSL certificate valid
  • ✅ API integration working

TWA Deployment

  • ✅ Service running: docker service ls | grep gitinext-twa
  • ✅ Domain accessible: https://nextgiti.cloud
  • ✅ SSL certificate valid
  • ✅ API integration working

Integration Testing

  • ✅ Wallet creation works
  • ✅ Address copying works
  • ✅ Real wallet data displayed
  • ✅ Error handling works

This deployment guide ensures both TMA and TWA are properly deployed with Traefik integration, SSL certificates, and full backend connectivity.

© 2025 GitiNext - Enterprise Crypto Infrastructure | GitHub | Website