🚀 Documentation Service Deployment Guide

Quick Deploy to docs.nextgiti.cloud

Option 1: Quick Deploy (Recommended)

cd /opt/cryptotel/enterprise/stacks/gitinext/gitinext-golang

# Build, push, and deploy in one command
make docs-deploy

# Verify
curl https://docs.nextgiti.cloud/health

Option 2: Step-by-Step

# 1. Build Docker image
make docs-build

# 2. Push to registry
make docs-push

# 3. Deploy via Docker Swarm
docker stack deploy -c docker-compose.yaml gitinext

# 4. Check status
docker service ls | grep docs

# 5. View logs
docker service logs -f gitinext_docs

# 6. Visit
open https://docs.nextgiti.cloud

---

🌐 DNS & TLS Configuration

DNS Record (Already Configured)

Type: A
Host: docs.nextgiti.cloud
Value: <your-server-ip>
TTL: Auto

TLS Certificate (Automatic via Traefik)

Traefik automatically requests Let’s Encrypt certificate for docs.nextgiti.cloud:

# In docker-compose.yaml
deploy:
  labels:
    - traefik.http.routers.docs.rule=Host(`docs.nextgiti.cloud`)
    - traefik.http.routers.docs.tls=true
    - traefik.http.routers.docs.tls.certresolver=letsencrypt

Certificate Storage: - Stored by Traefik in /letsencrypt/acme.json - Auto-renewal before expiry - No manual intervention needed

---

🔧 Configuration

Environment Variables

# .env file
REGISTRY=registry.nextgiti.cloud:5000
VERSION=latest

# Docs-specific (optional)
DOCS_PORT=8000
DOCS_PATH=/app/docs

Docker Compose

docs:
  image: ${REGISTRY}/docs:${VERSION}
  environment:
    - DOCS_PORT=8000
    - DOCS_PATH=/app/docs
  deploy:
    labels:
      - traefik.enable=true
      - traefik.http.routers.docs.rule=Host(`docs.nextgiti.cloud`)
      - traefik.http.routers.docs.tls.certresolver=letsencrypt
  networks:
    - net
    - traefik

---

✅ Verification

Health Check

curl https://docs.nextgiti.cloud/health
# Expected: {"status":"healthy"}

Homepage

curl https://docs.nextgiti.cloud
# Should return HTML

Specific Doc

curl https://docs.nextgiti.cloud/docs/overview/introduction
# Should return rendered markdown as HTML

---

🔄 Update Deployment

Update Docs Content Only

# No rebuild needed if only markdown changed
docker service update --force gitinext_docs

Update Service Code

# Rebuild and redeploy
make docs-deploy

---

🐛 Troubleshooting

Service Not Starting

# Check logs
docker service logs gitinext_docs

# Check service status
docker service ps gitinext_docs

# Check if image exists
docker images | grep docs

Certificate Not Working

# Check Traefik logs
docker service logs gitinext_traefik | grep docs.nextgiti.cloud

# Verify DNS resolves
nslookup docs.nextgiti.cloud

# Check certificate
openssl s_client -connect docs.nextgiti.cloud:443 -servername docs.nextgiti.cloud

404 Errors

# Verify docs directory is mounted
docker exec $(docker ps -q -f name=gitinext_docs) ls -la /app/docs

# Check file paths
docker exec $(docker ps -q -f name=gitinext_docs) cat /app/docs/index.md

---

📊 Monitoring

Service Health

# Check if service is running
docker service ps gitinext_docs

# View real-time logs
docker service logs -f gitinext_docs

Access Logs

The Go server logs all requests:

2025-10-06T10:30:00Z INFO Request GET /docs/overview/introduction 200 45ms
2025-10-06T10:30:05Z INFO Request GET /search?q=signer 200 12ms

---

✅ Complete Deployment Checklist

• [x] DNS record points to server
• [x] Traefik configured with letsencrypt
• [x] docker-compose.yaml updated with docs service
• [x] Makefile targets created
• [x] go.work includes docs service
• [x] Docker image built
• [x] Image pushed to registry
• [ ] Deploy to production: make docs-deploy
• [ ] Verify: curl https://docs.nextgiti.cloud/health
• [ ] Test: Visit https://docs.nextgiti.cloud in browser

---

Ready to deploy! Run make docs-deploy 🚀