Skip to main content

Local Deployment Troubleshooting

This guide covers troubleshooting issues specific to local test deployments on development machines and workstations.

Prerequisites Issues​

Docker Not Installed or Not Running​

Symptom​

docker ps
# Command 'docker' not found
# OR
# Cannot connect to the Docker daemon

Solution​

Linux:

# Install Docker
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh

# Add user to docker group
sudo usermod -aG docker $USER

# Log out and back in, then test
docker ps

macOS:

# Install via Homebrew
brew install --cask docker

# Or download Docker Desktop from docker.com
# Start Docker Desktop application

Windows:

  • Download and install Docker Desktop from docker.com
  • Ensure WSL 2 is installed and configured
  • Start Docker Desktop

Docker Compose Not Available​

Symptom​

docker compose version
# docker: 'compose' is not a docker command

Solution​

Docker Compose v2 (plugin):

# Linux
sudo apt-get update
sudo apt-get install docker-compose-plugin

# Verify
docker compose version

Docker Compose v1 (standalone):

# If v2 not available, use v1
sudo curl -L "https://github.com/docker/compose/releases/latest/download/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
sudo chmod +x /usr/local/bin/docker-compose

# Verify
docker-compose version

# Update run.sh to use docker-compose instead of docker compose

Missing jq or golang​

Symptom​

./run.sh -l
# bash: jq: command not found
# OR
# bash: go: command not found

Solution​

Ubuntu/Debian:

sudo apt-get update
sudo apt-get install -y jq golang-go

macOS:

brew install jq go

Fedora/RHEL:

sudo yum install -y jq golang

Certificate Issues​

mkcert Not Installed​

Symptom​

./run.sh -s opendso.local
# bash: mkcert: command not found

Solution​

Linux:

# Option 1: Install via package manager (if available)
sudo apt install mkcert

# Option 2: Install manually
cd /tmp
wget https://github.com/FiloSottile/mkcert/releases/latest/download/mkcert-v*-linux-amd64
chmod +x mkcert-v*-linux-amd64
sudo mv mkcert-v*-linux-amd64 /usr/local/bin/mkcert

# Verify
mkcert -version

macOS:

brew install mkcert
brew install nss  # For Firefox support

# Verify
mkcert -version

Certificate Generation Fails​

Symptom​

./run.sh -s opendso.local
# Error: failed to create CA
# OR
# mkcert: ERROR: no browsers found

Solution​

# Install mkcert root CA
mkcert -install

# Check CA location
mkcert -CAROOT

# If Firefox not recognizing:
# Install NSS tools
sudo apt-get install libnss3-tools  # Linux
brew install nss  # macOS

# Reinstall CA
mkcert -install

Browser Certificate Warning​

Symptom​

Browser shows "Your connection is not private" or "NET::ERR_CERT_AUTHORITY_INVALID"

Solution​

Chrome/Edge:

  1. Click "Advanced"
  2. Click "Proceed to opendso.local (unsafe)"
  3. Or: Ensure mkcert root CA is trusted 
    mkcert -install
  4. Restart browser

Firefox:

  1. Firefox uses its own certificate store
  2. Ensure NSS tools installed: 
    sudo apt-get install libnss3-tools  # Linux
    brew install nss  # macOS
  3. Reinstall CA: 
    mkcert -install
  4. Restart Firefox

Safari:

  • mkcert handles Safari automatically on macOS
  • If issues persist:
    1. Open Keychain Access
    2. Search for "mkcert"
    3. Double-click the certificate
    4. Expand "Trust"
    5. Set "When using this certificate" to "Always Trust"

Host File Configuration Issues​

Can't Edit Hosts File (Permission Denied)​

Symptom​

echo "127.0.0.1 opendso.local" >> /etc/hosts
# bash: /etc/hosts: Permission denied

Solution​

Linux/macOS:

# Use sudo
sudo nano /etc/hosts

# Add entries:
192.168.1.100 opendso.local
192.168.1.100 api.opendso.local
# ... etc

# Save and exit (Ctrl+X, Y, Enter)

# Verify
cat /etc/hosts | grep opendso.local

Windows:

  1. Open Notepad as Administrator
  2. File → Open → C:\Windows\System32\drivers\etc\hosts
  3. Add entries
  4. Save

DNS Not Resolving to Hosts File​

####Symptom

ping opendso.local
# ping: opendso.local: Name or service not known

Solution​

Check hosts file:

cat /etc/hosts | grep opendso.local

Flush DNS cache:

Linux:

sudo systemctl restart systemd-resolved
# OR
sudo systemd-resolve --flush-caches

macOS:

sudo dscacheutil -flushcache
sudo killall -HUP mDNSResponder

Windows:

ipconfig /flushdns

Test resolution:

nslookup opendso.local
getent hosts opendso.local  # Linux

Port Conflict Issues​

Port Already in Use​

Symptom​

docker compose logs api
# Error: listen EADDRINUSE: address already in use :::3000

Diagnosis​

# Check what's using the port
sudo netstat -tulpn | grep :3000
sudo lsof -i :3000

# Or with ss
ss -tulpn | grep :3000

# Check all listening ports
sudo netstat -tulpn | grep LISTEN

Solution​

Option 1: Stop the conflicting service

# Find the process
sudo lsof -i :3000
# Example output: node 12345 user ...

# Kill it
sudo kill 12345

# Or stop via systemctl if it's a service
sudo systemctl stop <service-name>

Common Port Conflicts​

PortCommon ServiceSolution
80System Nginx, ApacheStop system web server
443System Nginx, ApacheStop system web server
3000Node.js development serversStop other Node apps
8080Jenkins, TomcatStop conflicting service
4222Other NATS instancesStop other NATS
27017System MongoDBStop system MongoDB

Service Access Issues​

Can't Access Web Interface​

Symptom​

Browser can't reach https://api.opendso.local or other services

Checklist​

1. Verify hosts file:

cat /etc/hosts | grep opendso.local
# Should show: 192.168.1.YOUR_IP opendso.local

2. Check container is running:

docker ps | grep api
# Should show running container

3. Check container logs:

docker compose logs api
# Look for startup errors

4. Verify port mapping:

docker ps --format 'table {{.Names}}\t{{.Ports}}'
# Should show port mappings like 0.0.0.0:443->443/tcp

5. Test local connectivity:

# Test from host
curl -k https://localhost:443

# Test container directly
docker exec api curl -f http://localhost:3000/health

6. Check firewall:

# Linux
sudo ufw status
sudo iptables -L

# macOS
# System Preferences → Security & Privacy → Firewall

# Linux Temporarily disable firewall for testing
sudo ufw disable  # Re-enable after: sudo ufw enable

Service Returns 502 Bad Gateway​

Symptom​

Nginx or reverse proxy returns 502

Diagnosis​

# Check if backend service is running
docker ps | grep gms-api

# Check backend logs
docker-compose logs gms-api

# Test backend directly
docker exec gms-api curl http://localhost:3000/health

Solution​

# Restart backend service
docker compose restart gms-api

# Check depends_on in compose.yaml
services:
  reverse-proxy:
    depends_on:
      - api

# Ensure proper network connectivity
docker network inspect opendso

Resource Issues​

Out of Disk Space​

Symptom​

# Error: no space left on device
docker compose up -d

Diagnosis​

# Check disk space
df -h

# Check Docker usage
docker system df
docker system df -v

Solution​

# Clean up Docker resources
docker system prune -a --volumes

# Remove specific items
docker container prune  # Stopped containers
docker image prune -a    # Unused images
docker volume prune      # Unused volumes

# Check space again
df -h

Docker Desktop Out of Memory​

Symptom​

Containers crash or can't start, Docker Desktop shows memory warning

Solution​

Docker Desktop (Mac/Windows):

  1. Open Docker Desktop
  2. Settings → Resources
  3. Increase Memory limit (recommend 8GB minimum for full stack)
  4. Increase CPU limit if needed
  5. Apply & Restart

Linux:

# Check system memory
free -h

# Monitor Docker usage
docker stats

# Set container memory limits in compose.yaml
services:
  api:
    deploy:
      resources:
        limits:
          memory: 1G

Slow Performance​

Causes​

  • Insufficient Docker resources
  • Too many services running
  • Slow disk I/O
  • Background processes

Solutions​

# Check resource usage
docker stats

# Run only needed services
./run.sh -p nats -p api -c  # Instead of -p all

# Close other applications
# Restart Docker Desktop

# Check system resources
top
htop

Network Issues​

Docker Network Doesn't Exist​

Symptom​

docker compose up -d
# Error: network opendso_test not found

Solution​

# Check networks
docker network ls

# Create network manually if needed
docker network create opendso

# Or let compose create it
docker compose up -d

Containers Can't Communicate​

Symptom​

Service logs show connection errors to other services

Diagnosis​

# Check all containers are on same network
docker network inspect opendso

# Test connectivity
docker exec gms-api ping nats-main
docker exec gms-api nc -zv nats-main 4222

Solution​

# Ensure network is defined in compose.yaml
services:
  api:
    networks:
      - opendso
  nats:
    networks:
      - opendso

networks:
  opendso:
    name: opendso

# Recreate containers
./run.sh -p all -d
./run.sh -p all -c

Configuration Issues​

Environment File Not Found​

Symptom​

./run.sh -p all -c
# Error: Docker environment file does not exist; exiting execution

Solution​

# Check file exists
ls -la ../config/docker/.env

# If missing, clone config repo
cd ..
git clone https://github.com/openenergysolutions/circuit-config-docker-compose.git config

# Verify
ls -la config/docker/.env

Models Directory Empty​

Symptom​

./run.sh -p all -c
# Error: No feeders are present in ../models

Solution​

# Check models exist
ls -la ../models/circuit/

# If empty, clone models repo
cd ..
git clone https://github.com/openenergysolutions/circuit-docker-compose.git models

# Verify
ls -la models/circuit/recloser/

Reset and Clean Start​

Complete Reset​

If all else fails, start fresh:

# 1. Stop everything
cd opendso-docker-compose
./run.sh -p all -d -f

# 2. Remove volumes
docker volume prune -f

# 3. Remove network
docker network rm opendso

# 4. Clean Docker system
docker system prune -a --volumes

# 5. Remove certificates
rm -rf ../certs/

# 6. Regenerate certificates
./run.sh -s opendso.local

# 7. Update hosts file (manually)
sudo nano /etc/hosts
# Add displayed entries

# 8. Start services
./run.sh -p all -c

Browser-Specific Issues​

Caching Issues​

Symptom​

Frontend app (edo-adr) shows old version after update

Solution​

Chrome/Edge:

  1. Open DevTools (F12)
  2. Hard refresh (Ctrl+Shift+R)

Firefox:

  1. Open DevTools (F12)
  2. Hard refresh (Ctrl+Shift+R)

Quick Fixes Summary​

ProblemQuick Fix
Certificate warningmkcert -install and restart browser
Can't reach serviceCheck hosts file, verify container running
Port conflictsudo lsof -i :<port> and kill process
Out of diskdocker system prune -a --volumes
Slow performanceIncrease Docker Desktop resources
Network errordocker network inspect opendso_test
Container won't startdocker compose logs <service>

Next Steps​