# Troubleshooting Docker Deployments

## Docker Prerequisite
- Armorer installs require Docker Engine and `docker compose`.
- Install docs: `https://docs.docker.com/get-docker/`
- Linux Engine docs: `https://docs.docker.com/engine/install/`
- Verify before install: `docker info` and `docker compose version`

## Container Exits Immediately
- Check logs: `docker compose logs --tail 50 <service>`
- Common causes:
  - Missing config file — the app needs a first-time setup (run `setup` or `init`).
  - Missing environment variable — check `.env` file or `docker-compose.yml`.
  - Permission denied on a volume mount — ensure host dirs are owned by the right user.
  - Wrong entrypoint — the image may expect a different command invocation.
- Fix: read the error message carefully, check the app's README for setup instructions.

## Permission Denied Errors
- Symptom: `EACCES: permission denied` or `Permission denied` in logs.
- Cause: Docker created the volume directory as `root:root`, but the container runs as
  a non-root user (e.g. `node`, UID 1000).
- Fix: `sudo chown -R $(id -u):$(id -g) ./path/to/volume`
- Prevention: Armorer pre-creates volume directories before starting containers.

## Port Already in Use
- Symptom: `bind: address already in use`
- Fix: find the process: `sudo lsof -i :<PORT>` or `ss -tlnp | grep <PORT>`
- Then stop the conflicting service or change the port mapping in docker-compose.yml.

## Image Not Found / Pull Errors
- Symptom: `manifest unknown` or `no matching manifest for linux/arm64`
- Cause: the image doesn't support the host architecture (common on Raspberry Pi / Apple Silicon).
- Fix: look for an ARM-compatible image variant (often suffixed with `-arm64` or using Alpine).
- Alternative: build from source using the repo's Dockerfile.

## "Run setup" or "Missing configuration"
- Many apps need a one-time setup step before they'll run properly.
- Pattern: the container exits with a message like "Run `app setup`" or "Config not found".
- Fix: `docker compose run --rm <cli-service> setup`
- If no CLI service exists, use the main service: `docker compose run --rm <service> sh -c "app setup"`
- After setup, restart: `docker compose up -d`

## Container Keeps Restarting
- Symptom: `Restarting (1)` in `docker compose ps`
- Cause: the container crashes on startup, and `restart: unless-stopped` keeps retrying.
- Fix: temporarily set `restart: "no"`, check logs, fix the underlying issue.
- Common: missing database, wrong credentials, config file syntax error.

## Cannot Connect to Service
- Check if the service is actually running: `docker compose ps`
- Check if the port is exposed: look for `ports:` in docker-compose.yml.
- From the host, try: `curl http://localhost:<PORT>` or `ws://localhost:<PORT>`.
- Inside the container: `docker compose exec <service> wget -qO- http://localhost:<PORT>`
- Firewall: on Linux, check `iptables` or `ufw` rules.

## Disk Space Issues
- Symptom: `no space left on device`
- Fix: clean up Docker: `docker system prune -af --volumes`
- Check disk: `df -h`
- For Raspberry Pi / SD card systems, move Docker data dir to external storage.

## DNS Resolution Failures
- Symptom: `Could not resolve host` or `EAI_AGAIN`
- Inside containers, Docker provides DNS. Check that the Docker daemon is running properly.
- Fix: restart Docker daemon: `sudo systemctl restart docker`
- If using custom DNS, set it in Docker daemon config or per-container with `dns:`.

## Agent Hallucinations & Loops
- **Symptom:** Agent reads `Dockerfile` or `docker-compose.yml` from the *root* directory and gets confused, or gets stuck rewriting the same plan file over and over.
- **Cause:** The agent has lost track of its scope. The root directory contains *Armorer's* own source code, not the target application.
- **Fix:**
  1. **STOP.** Do not read root files.
  2. **REDIRECT:** Force focus to `installed/<app_name>/`.
  3. **VERIFY:** If the app already has a `docker-compose.yml` (most do), do NOT plan a new one. Your job is to verify/fix the existing one, not reinvent it.
  4. **ONE-SHOT:** Write your plan/recommendation file *once*. If you feel the need to write it again, you are looping. Stop and submit your findings.
