# NemoClaw Docker & Podman Install Guide: Troubleshooting Common Errors Deploying NemoClaw via containers provides a consistent, reproducible, and highly isolated environment. Containerization abstracts away the underlying operating system's quirks, ensuring that the software runs exactly as the developers intended. However, getting it running smoothly from the initial pull to a fully operational state can sometimes present a unique set of challenges, especially around networking, volume mounts, permission boundaries, and resource allocation. Whether you are using the traditional Docker daemon or the daemonless, rootless architecture of Podman, container engines introduce layers of abstraction that can complicate troubleshooting. This comprehensive guide covers the most frequent installation hurdles, the underlying architectural reasons why these errors occur, and exactly how to resolve them for a production-ready NemoClaw deployment. ## The Rise of Containerized NemoClaw Deployments Before diving into the specific errors and their remediations, it is crucial to understand why running NemoClaw in a containerized environment is the preferred method for modern infrastructure. NemoClaw comprises multiple internal services, dependency requirements, and stateful data stores. Historically, installing such complex applications directly onto a bare-metal server or a traditional virtual machine meant dealing with dependency hell. You might have incompatible libraries, conflicting runtime versions (like Python or Node.js), or environmental variables that bleed into other applications. Docker and Podman solve this by wrapping NemoClaw into an immutable image. Every time you deploy the container, you are booting an identical filesystem. This means that "it works on my machine" translates perfectly to "it works on the server." Furthermore, containerization allows for rapid rollbacks, easy scaling, and automated testing pipelines. However, this encapsulation means that when things go wrong—when the container cannot reach the host network, or when it lacks permission to write to the physical disk—the errors can be opaque. Understanding the bridge between the container's isolated world and your host operating system is the key to mastering NemoClaw deployments. ## Step-by-Step: The Ideal NemoClaw Container Setup To minimize the chances of encountering the errors detailed later in this guide, it is highly recommended to start with a standardized, declarative configuration using Docker Compose (or Podman Compose). This ensures all parameters, network settings, and volume mounts are explicitly defined and easily modifiable. **Step 1: Prepare the Host Environment** Create a dedicated directory on your host machine to store NemoClaw's configuration and persistent data. ```bash mkdir -p /opt/nemoclaw/{config,data,logs} Ensuring these directories exist before the container starts prevents the container engine from automatically creating them with root permissions, which is a common cause of permission denied errors. **Step 2: Draft the Compose File** Create a `docker-compose.yml` file in the `/opt/nemoclaw` directory. This file acts as the blueprint for your deployment. ```yaml version: '3.8' services: nemoclaw: image: nemosoft/nemoclaw:latest container_name: nemoclaw_core restart: unless-stopped ports: - "8080:8080" - "8443:8443" volumes: - ./config:/app/config - ./data:/app/data - ./logs:/app/logs environment: - TZ=UTC - LOG_LEVEL=info - MEMORY_MAX=4096m deploy: resources: limits: memory: 4G cpus: '2.0' **Step 3: Initialization and Validation** Run the deployment in detached mode. If you are using Podman, simply substitute `docker-compose` with `podman-compose`. ```bash docker-compose up -d ``` Immediately check the logs to ensure the bootstrap process is beginning correctly: ```bash docker logs -f nemoclaw_core ``` If the logs show the web server binding successfully and the database initializing, your baseline setup is solid. If the container crashes or loops, proceed to the troubleshooting sections below. ## 1. Network Bridge and Port Conflicts The most common issue when spinning up NemoClaw for the first time is port allocation. NemoClaw’s gateway requires specific ports to communicate with the outside world, typically port 8080 for HTTP traffic and 8443 for HTTPS traffic, along with internal ports for metric scraping or database connections. By default, Docker and Podman utilize a network bridge. The container believes it is binding to port 8080 on its own isolated interface, and the container engine maps that to a port on your host machine. **Symptom:** The container fails to start, immediately exiting. When you check the logs or the container engine output, you see a fatal error throwing an exception like `Bind for 0.0.0.0:8080 failed: port is already allocated` or `listen tcp 0.0.0.0:8080: bind: address already in use`. **Why it happens:** Your host machine is already running an application that is listening on the port you are trying to map to. This could be a web server like Nginx or Apache, a previously orphaned NemoClaw container, or another service entirely. Because a single network port on an IP address can only be bound by one process at a time, the container engine fails to establish the translation rule and aborts the container startup. **Fix:** You must map the container's internal port to an available, unused port on your host machine. You can identify what is using the port by running `sudo lsof -i -P -n | grep LISTEN` or `sudo netstat -tulpn | grep 8080` on the host. If you cannot stop the conflicting host service, adjust your `docker-compose.yml` or your run command to map to a different host port. The syntax is always `HOST_PORT:CONTAINER_PORT`. ```yaml ports: - "8081:8080" # Map host 8081 to container 8080 - "8444:8443" # Map host 8444 to container 8443 ``` If you are running from the command line: ```bash docker run -d -p 8081:8080 -p 8444:8443 nemosoft/nemoclaw:latest ``` After making this change, you will access NemoClaw via `http://YOUR_SERVER_IP:8081` instead of the default port. ## 2. Podman Rootless Permissions Podman’s rootless mode is excellent for security. By running containers without the host's root daemon, you drastically reduce the attack surface. If a malicious actor compromises the NemoClaw container, they are trapped within the limited privileges of the user that launched the container, rather than having unrestricted root access to the entire host machine. However, this security model means that NemoClaw might need to write to volumes mapped from the host, and User Namespace (userns) mapping complicates things. Furthermore, Linux distributions that utilize Podman (like RHEL, Fedora, or Rocky Linux) heavily rely on SELinux (Security-Enhanced Linux). **Symptom:** `Permission denied` or `EACCES` errors appear in the container logs when NemoClaw tries to write log files, save uploaded media, or initialize its internal state databases. The application might crash entirely, or it might stay alive but remain in a degraded, read-only state. **Why it happens:** There are two primary culprits. First, the UID (User ID) running the process *inside* the container does not have matching write permissions on the directory *outside* the container on the host. Second, SELinux policies prevent the container process from accessing the host filesystem, even if standard read/write/execute permissions look correct. **Fix:** To handle SELinux context correctly, you must instruct Podman to relabel the directory so the container is permitted to use it. Append the `:Z` (private unshared label) or `:z` (shared label) flag to your volume mounts. Use `:Z` if only this specific container needs access to the volume, which is best for NemoClaw's private data. ```bash podman run -v /my/host/dir:/app/data:Z -v /my/host/logs:/app/logs:Z ... ``` In a compose file: ```yaml volumes: - ./data:/app/data:Z - ./config:/app/config:Z ``` If the issue is purely UID/GID mapping in rootless mode, you might need to use `podman unshare` to assign the correct ownership to the host directories. `podman unshare` drops you into a shell with the same user namespace as the container, allowing you to `chown` the directories so they match what the container expects. ```bash podman unshare chown -R 1000:1000 /my/host/data ``` Replace `1000:1000` with the actual User ID and Group ID that the NemoClaw image runs under (consult the image documentation or run a quick `podman run --rm nemosoft/nemoclaw id` to find out). ## 3. Insufficient Resource Limits NemoClaw is a powerful application, and with that power comes a baseline requirement for compute resources. The application can be highly memory-intensive during specific lifecycle phases, such as initial startup, deep indexing of large datasets, compiling assets, or heavy concurrent task processing. **Symptom:** The container appears to be running fine, but suddenly exits unexpectedly. When you check the container status using `docker ps -a` or `podman ps -a`, the exit code is `137`. The container logs often abruptly stop without logging a clean shutdown or a specific stack trace. **Why it happens:** Exit code 137 is the universal container signal for `SIGKILL` specifically triggered by the Linux kernel's Out Of Memory (OOM) killer. The container engine monitors the cgroups (control groups) assigned to the container. If NemoClaw attempts to allocate more RAM than the limit defined for the container, the host OS steps in and instantly terminates the process to protect the stability of the entire system. Because this is a hard kill from the operating system, the application has no chance to catch the exception or write an error to the log. **Fix:** You must increase the memory limits available to the container, and optionally, adjust NemoClaw's internal configuration to be more conservative with memory usage. In Docker Desktop, you may need to adjust the global resource limits in the application settings (Settings > Resources > Advanced) to ensure the Docker VM has enough overall RAM to offer the containers. In compose files, explicitly define higher limits under the `deploy` block (for Docker Compose v3) or using standard container flags: ```yaml deploy: resources: limits: memory: 4G reservations: memory: 2G ``` Additionally, if NemoClaw is running on a JVM (Java Virtual Machine) or Node.js backend, you may need to pass environment variables to configure the internal garbage collector heap sizes, ensuring the application itself knows it has limits before the Linux kernel has to intervene. ```yaml environment: - NODE_OPTIONS="--max-old-space-size=3072" # Limit Node.js heap to ~3GB ``` ## 4. Managing Dependent Services and Startup Orders Modern applications rarely exist in a vacuum. A robust NemoClaw installation often relies on external databases (like PostgreSQL, MySQL, or MongoDB), caching layers (like Redis), or message brokers (like RabbitMQ or Kafka). **Symptom:** The NemoClaw container starts but constantly restarts in a crash-loop. The logs display errors like `Connection refused to database`, `Timeout waiting for Redis`, or `Failed to establish connection to cluster`. **Why it happens:** In a microservices or multi-container deployment, container engines start services simultaneously by default. If your NemoClaw container boots up in 2 seconds, but your PostgreSQL container takes 15 seconds to initialize its schemas and begin accepting connections, NemoClaw will try to connect, fail, crash, and restart. This creates a race condition upon every system boot. **Fix:** Utilize `depends_on` in your compose file coupled with health checks. Simple `depends_on` only waits for the dependent container to *start*, not for it to be *ready*. By adding a health check to the database, you force NemoClaw to wait until the database is fully operational. ```yaml services: database: image: postgres:14 healthcheck: test: ["CMD-SHELL", "pg_isready -U postgres"] interval: 10s timeout: 5s retries: 5 nemoclaw: image: nemosoft/nemoclaw:latest depends_on: database: condition: service_healthy ``` This configuration guarantees that NemoClaw will patiently wait in a pending state until `pg_isready` returns a success signal, entirely eliminating startup race conditions. ## 5. Handling DNS and Internal Communication Failures Sometimes the network issues are not about binding to the host, but about the containers talking to each other or reaching out to the public internet for updates, webhooks, or API validations. **Symptom:** NemoClaw runs, but features that require external API access fail. Logs show `EAI_AGAIN`, `getaddrinfo ENOTFOUND`, or `Temporary failure in name resolution`. Alternatively, NemoClaw cannot resolve the internal hostname of a database container defined in the same compose file. **Why it happens:** Docker and Podman implement their own internal DNS servers to provide automatic service discovery. When you type `database` as a host in your NemoClaw config, the container engine resolves that to the internal IP of the database container. If the containers are on the default bridge network instead of a custom user-defined bridge network, DNS resolution between containers is disabled by default. If the host machine has aggressive firewall rules, it might block the container's outbound UDP port 53 traffic, breaking external DNS. **Fix:** Always place your services on a custom network. The easiest way is to let Docker Compose create it by default, but you must ensure you are not explicitly setting `network_mode: bridge`. If external DNS is failing, you can explicitly pass DNS servers to the container. ```yaml services: nemoclaw: image: nemosoft/nemoclaw:latest networks: - nemoclaw_net dns: - 8.8.8.8 - 1.1.1.1 networks: nemoclaw_net: driver: bridge ``` This forces the container to use reliable public DNS resolvers (Google and Cloudflare) if the host's DNS proxy is misbehaving or blocked. ## Frequently Asked Questions (FAQ) **Q1: Should I use Docker or Podman for deploying NemoClaw?** Both are excellent choices, as they utilize the same underlying OCI (Open Container Initiative) standards. Docker is the industry standard and generally has an easier learning curve and slightly better third-party tooling integration. Podman is strictly daemonless and excels in rootless environments, making it superior for highly secure, multi-tenant Linux servers where you do not want an active root daemon running at all times. **Q2: How do I update my NemoClaw container without losing all my data?** Because container filesystems are ephemeral, all permanent data must be stored in volumes. As long as you have properly mapped your `/data` and `/config` directories to the host as detailed in the setup section, updating is trivial. Simply pull the latest image and recreate the container: ```bash docker pull nemosoft/nemoclaw:latest docker-compose up -d --force-recreate ``` The new container will boot, attach to the existing persistent data volumes, perform any necessary database migrations automatically, and resume operation. **Q3: Can I run multiple instances of NemoClaw on the same host machine?** Yes, but you must avoid resource collisions. Each instance requires its own unique host ports and its own unique data directories. In your compose files for the second instance, you would map `8082:8080`, define separate volume paths (e.g., `/opt/nemoclaw_instance2/data`), and ensure the container names are different (e.g., `nemoclaw_core_2`). **Q4: My container logs are showing "Database Locked" or "SQLite busy" errors. What is happening?** If you are using SQLite as the backing database for NemoClaw, mapping the SQLite file over certain types of network filesystems (like NFS, CIFS, or SMB) or through overly aggressive Docker Desktop virtualization layers (like VirtioFS on Mac) can break file locking mechanisms. SQLite requires strict POSIX locking to ensure data integrity during concurrent writes. Ensure your data volume is mapped to a local, high-performance filesystem on the host (like ext4 or xfs). If the instance is heavily trafficked, consider migrating the configuration to use a dedicated PostgreSQL or MySQL container instead of SQLite. **Q5: What is the best way to back up my containerized NemoClaw instance?** Do not attempt to snapshot the running container. Instead, back up the persistent volume data on the host machine. To ensure consistency and avoid corrupted backups from files being written while the backup is running, you should temporarily stop the container, archive the files, and start it again: ```bash docker-compose stop tar -czvf nemoclaw_backup_$(date +%F).tar.gz /opt/nemoclaw docker-compose start ``` For zero-downtime backups, you must utilize the backup features of your underlying database (like `pg_dump`) and perform an rsync of the file storage directories. ## Conclusion Running NemoClaw inside Docker or Podman transforms complex system administration into a predictable, manageable process. While the abstraction of containerization introduces unique challenges—from bridging network ports to navigating the strict boundaries of SELinux and kernel resource limitations—these hurdles are easily overcome with a solid understanding of how containers interact with the host operating system. By utilizing declarative Compose files, strictly managing your volume permissions, carefully monitoring your RAM allocation, and understanding how to orchestrate dependency startup orders, you can achieve a highly resilient architecture. Armed with the troubleshooting steps and architectural context outlined in this guide, you are well-equipped to maintain a stable, secure, and highly performant NemoClaw deployment capable of handling whatever workloads you throw at it. Keep an eye on your resource metrics, ensure your data is backed up regularly, and enjoy the streamlined experience of containerized operations.