tailscale-custom/.agent/workflows/docker-deploy.md

description

description
Deploy any INS module to VPS with pre-flight connectivity checks, local build, and post-deploy verification

Docker VPS Release Workflow

RULE: Never build on VPS. Always publish locally and create Docker image with pre-built DLLs only.

// turbo-all

Prerequisites

• Docker Desktop running locally
• SSH access to VPS: root@36.50.176.30
• SSH key: ~/.ssh/id_rsa or ~/.ssh/id_ed25519

Phase 1: Pre-flight — Check VPS Infrastructure

1.1. SSH into VPS and check Docker network

ssh -o StrictHostKeyChecking=no root@36.50.176.30 "docker network ls --format 'table {{.Name}}\t{{.Driver}}\t{{.Scope}}'"

1.2. List all containers on app-network with health status

ssh -o StrictHostKeyChecking=no root@36.50.176.30 "docker ps -a --format 'table {{.Names}}\t{{.Status}}\t{{.Ports}}\t{{.Networks}}' | head -30"

1.3. Verify SSO container is running and healthy

ssh -o StrictHostKeyChecking=no root@36.50.176.30 "docker inspect sso-instratech --format '{{.State.Status}} | Health: {{.State.Health.Status}} | Network: {{range .NetworkSettings.Networks}}{{.IPAddress}} {{end}}' 2>/dev/null || echo 'SSO container NOT FOUND'"

1.4. Verify Redis is running

ssh -o StrictHostKeyChecking=no root@36.50.176.30 "docker exec ins-redis redis-cli ping 2>/dev/null || echo 'Redis NOT AVAILABLE'"

1.5. Verify inter-container DNS resolution (from a running container)

ssh -o StrictHostKeyChecking=no root@36.50.176.30 "docker exec sso-instratech sh -c 'getent hosts ins-redis && getent hosts ins-rabbitmq' 2>/dev/null || echo 'DNS resolution check failed'"

1.6. Check gRPC health on SSO (port 8082)

ssh -o StrictHostKeyChecking=no root@36.50.176.30 "curl -sf http://localhost:8082/health || echo 'gRPC health endpoint not responding'"

STOP: If SSO or Redis are NOT running/healthy, fix them FIRST before deploying any module.

---

Phase 2: Validate Configuration

2.1. Identify the correct appsettings file for the target module

Check the module's Dockerfile to see which CONFIG_FILE is used:

Select-String -Path "Dockerfile" -Pattern "CONFIG_FILE"

• appsettings.container.release.json → Production VPS (sso.instratech.net)
• appsettings.container.debug.json → Local Docker Desktop
• appsettings.container.json → Generic container mode

2.2. Verify appsettings has correct service hostnames

Review the release config and verify:

Get-Content "src\*Backend\appsettings.container.release.json" | Select-String -Pattern "ServerUrl|ConnectionString|Host|redis|rabbitmq|sso-instratech"

Expected hostnames inside Docker network:

Service	Hostname	Port
SSO (HTTP)	sso-instratech	8080
SSO (gRPC)	sso-instratech	8082
Redis	ins-redis or redis	6379
RabbitMQ	ins-rabbitmq or rabbitmq	5672
SQL Server	External IP (e.g., 203.167.14.22)	1433

CRITICAL: Connection strings MUST use Docker network hostnames, NOT localhost.

2.3. Verify startup order

Container startup dependencies:

1. Redis (ins-redis)          ← No dependencies
2. RabbitMQ (ins-rabbitmq)    ← No dependencies  
3. SSO (sso-instratech)       ← Depends on: Redis, RabbitMQ, SQL Server
4. INS.PRO (ins-pro)          ← Depends on: SSO, Redis, SQL Server
5. INS.CDE (ins-cde)          ← Depends on: SSO, Redis, SQL Server
6. INS.WJC (ins-wjc)          ← Depends on: SSO, Redis, SQL Server

All modules depend on SSO for gRPC token validation. SSO MUST be healthy before starting modules.

---

Phase 3: Build Locally (NEVER on VPS)

3.1. Clean previous publish output

Remove-Item -Path "publish" -Recurse -ErrorAction SilentlyContinue

3.2. Publish with Release configuration (no debug symbols)

dotnet publish src\<MODULE>.Backend\<MODULE>.Backend.csproj -c Release -o publish/backend /p:DebugType=none /p:DebugSymbols=false

3.3. Build Docker image with production config

docker build -t <image-name>:latest --build-arg CONFIG_FILE=appsettings.container.release.json -f Dockerfile .

3.4. Save image as .tar for transfer

$ts = Get-Date -Format 'yyyyMMdd-HHmmss'; docker save -o "<image-name>-$ts.tar" <image-name>:latest

---

Phase 4: Deploy to VPS

4.1. Upload .tar to VPS

scp -o StrictHostKeyChecking=no "<image-name>-*.tar" "root@36.50.176.30:/tmp/"

4.2. Load image and deploy on VPS

ssh -o StrictHostKeyChecking=no root@36.50.176.30 "docker load -i /tmp/<image-name>-*.tar && docker stop <container-name> 2>/dev/null; docker rm <container-name> 2>/dev/null; docker run -d --name <container-name> --network app-network --restart unless-stopped -p <host-port>:<container-port> -e ASPNETCORE_ENVIRONMENT=Production -e DOTNET_RUNNING_IN_CONTAINER=true --health-cmd 'curl -f http://localhost:<container-port>/health/ready || exit 1' --health-interval 30s --health-timeout 10s --health-retries 3 --health-start-period 60s <image-name>:latest && rm -f /tmp/<image-name>-*.tar"

4.3. Clean up local .tar

Remove-Item -Path "<image-name>-*.tar" -Force -ErrorAction SilentlyContinue

---

Phase 5: Post-Deploy Verification

5.1. Check container health status

ssh -o StrictHostKeyChecking=no root@36.50.176.30 "docker ps --filter name=<container-name> --format 'table {{.Names}}\t{{.Status}}\t{{.Ports}}'"

5.2. Check startup connectivity report in logs

ssh -o StrictHostKeyChecking=no root@36.50.176.30 "docker logs <container-name> 2>&1 | grep -A 20 'Connectivity Report'"

Must see: All ✅ in the report. If any ❌, the container will crash and restart.

5.3. Deep health check via HTTP

ssh -o StrictHostKeyChecking=no root@36.50.176.30 "curl -s http://localhost:<host-port>/health/ready | python3 -m json.tool 2>/dev/null || curl -s http://localhost:<host-port>/health/ready"

Expected: "status": "Healthy" with all checks passing.

5.4. Verify container-to-container connectivity

ssh -o StrictHostKeyChecking=no root@36.50.176.30 "docker exec <container-name> sh -c 'getent hosts sso-instratech && getent hosts ins-redis' 2>/dev/null || echo 'DNS resolution FAILED'"

5.5. Test gRPC connectivity from new container to SSO

ssh -o StrictHostKeyChecking=no root@36.50.176.30 "docker exec <container-name> sh -c 'curl -sf http://sso-instratech:8082/health' 2>/dev/null || echo 'gRPC SSO unreachable from container'"

DEPLOYMENT IS COMPLETE only when ALL Phase 5 checks pass.

---

Module Reference

Module	Image	Container	Port	Config
SSO	sso-instratech	sso-instratech	8080, 8082	appsettings.container.release.json
PRO	ins-pro	ins-pro	8000	appsettings.container.release.json
CDE	ins-cde	ins-cde	8090	appsettings.container.release.json
WJC	ins-wjc	ins-wjc	8070	appsettings.container.release.json

Troubleshooting

Symptom	Cause	Fix
Container keeps restarting	Critical dependency unreachable	Check Phase 5.2 logs for ❌
health/ready returns 503	gRPC/Redis/SQL down	Fix dependency first, container will self-heal
DNS resolution fails	Container not on app-network	docker network connect app-network <name>
30s request timeouts	gRPC SSO unreachable	Check SSO container + network alias