Docker Issues

Container fails to start

Symptom: docker compose up exits immediately or the container restarts in a loop.

Diagnose:

docker compose logs nat-server

Common causes:

Fix permission issues:

# Ensure the data directory is writable by UID 1000 (the nat user)
sudo chown -R 1000:1000 /opt/nat/data

Dashboard is not accessible

Symptom: Browser shows "Connection refused" or "This site can't be reached".

Solutions:

1. Check the container is running and healthy:

   docker compose ps
   # Expected: nat-server   Up (healthy)
2. Check the port mapping:

   docker compose port nat-server 8080
   # Expected: 0.0.0.0:8080
3. If the container binds to 127.0.0.1:8080, it's only accessible from the host machine — use a reverse proxy for external access
4. Check firewall rules: sudo ufw status

Scan can't reach the target API

Symptom: Scans started from the NAT dashboard or API fail with connection errors when the target API is on a private/internal network.

Why this happens: The NAT container runs in Docker's network namespace and may not have access to your host network or private VPN.

Solutions:

1. Use host network mode (Linux only):

   services:
     nat-server:
       network_mode: host
2. Connect the container to the same Docker network as your target API:

   services:
     nat-server:
       networks:
         - api-network
    
   networks:
     api-network:
       external: true
       name: myapp_default
3. Set up a VPN client sidecar container that the NAT container routes through

Data not persisting between restarts

Symptom: Scan history disappears after restarting the container.

Solution: Ensure the data directory is mounted as a volume:

services:
  nat-server:
    image: natengine/nat:latest
    volumes:
      - ./data:/data    # Mount host directory
    environment:
      - NAT_DATA_DIR=/data

Or use a named Docker volume:

services:
  nat-server:
    volumes:
      - nat-data:/data
 
volumes:
  nat-data:     # Docker manages this volume

Container runs out of memory

Symptom: Container is killed with OOMKilled or similar.

Solutions:

1. Increase the memory limit in your Docker Compose file:

   deploy:
     resources:
       limits:
         memory: 4G
2. Reduce scan concurrency to lower memory usage:

   environment:
     - NAT_SCAN_CONCURRENCY=2
3. Ensure the host machine has sufficient RAM (minimum 2 GB, 4 GB recommended)

Image pull fails

Symptom: docker compose pull or docker pull natengine/nat fails.

Solutions:

1. Check internet connectivity from the server: curl https://registry-1.docker.io
2. If behind a proxy, configure Docker to use the proxy:

   # /etc/systemd/system/docker.service.d/http-proxy.conf
   [Service]
   Environment="HTTP_PROXY=http://proxy.example.com:8080"
   Environment="HTTPS_PROXY=http://proxy.example.com:8080"
3. If using a private registry mirror, configure it in Docker daemon settings

Upgrade broke something

Symptom: After upgrading the Docker image, the server behaves unexpectedly.

Solutions:

1. Check the Changelog for breaking changes in the new version
2. Roll back to the previous version:

   docker compose stop nat-server
   # Edit docker-compose.yml to pin to previous version: natengine/nat:1.x.x
   docker compose up -d nat-server
3. Check the server logs for migration errors:

   docker compose logs nat-server --tail 50

Checking container health

# View container status
docker compose ps
 
# View recent logs
docker compose logs nat-server --tail 50
 
# Open a shell inside the container (for advanced debugging)
docker compose exec nat-server sh
 
# Check the health endpoint directly
docker compose exec nat-server curl http://localhost:8080/health

Next steps

• Docker Deployment guide — Docker reference
• Deploy with Docker (how-to) — production deployment guide
• Connection Errors — network troubleshooting