Enhance Docker Deployment: Logging Resilience and Named Log Volume

[TCMAD]

This update addresses critical Docker deployment issues by improving logging resilience and refining log volume management. Changes fix local deployment of the backend container, blocked by logs/ non-root ownership and the template .env.docker.example file not properly set with an optional parameter.

Key Changes:

1. Logging Resilience:

   • The backend application's logging mechanism is now more robust. It will gracefully fall back to console-only logging if file logging fails (e.g., due to unwritable /app/logs directories). This prevents application startup failures caused by logging configuration issues.
   • Container logs are now accessible via docker compose logs <service_name> (e.g., docker compose logs backend).

2. Log Volume Management:

   • The docker-compose.yml has been updated to use a named Docker volume (logs) for log storage, replacing the host bind mount (./logs).
   • This change resolves potential file ownership conflicts that can arise with host bind mounts, ensuring smoother deployments. Docker manages named volumes, providing a more reliable setup.

Impact on Deployment Issues:

• Log Ownership: The switch to a named volume for logs directly resolves issues related to file ownership and permissions within the container, ensuring logs can be written reliably.

---

Small Changes:

• Environment Variable Configuration: As highlighted in the README.md and .env.docker.example, proper environment variable setup is key to successful deployment. The TELEGRAM_API_ID in .env.docker.example was a string (' ') but is expected to be an integer. The user cannot deploy with this parameter set with nothing like the others

• Agent guide portability: Copy and update CLAUDE.md into a new file AGENTS.mdto introduce guidelines for multiples agents (Codex, Gemini CLI, etc.)

[sneg55]

Thanks for this — the console-fallback resilience is a good idea. A few things to address before merge:

1. Dropping log_dir.mkdir(exist_ok=True) is a regression for local dev

logs/ is gitignored, so on a fresh checkout the directory doesn't exist. With the mkdir removed, RotatingFileHandler now raises FileNotFoundError (an OSError) → _create_file_handler returns NullHandler → the documented logs/pingcrm.log (CLAUDE.md) silently disappears for anyone running uvicorn on the host.

Please keep directory creation and only fall back if it genuinely can't be written, e.g.:

try:
    log_dir.mkdir(parents=True, exist_ok=True)
except OSError as exc:
    _file_logging_error = str(exc)

That preserves the resilience you're adding without losing file logging in the normal case.

2. The named logs volume likely won't be writable by the container user

The backend runs as non-root (USER appuser, backend/Dockerfile:32) and the Dockerfile never creates /app/logs (it only mkdirs static/avatars). When a named volume is mounted onto a path that doesn't exist in the image, Docker creates the mountpoint root-owned — so appuser still can't write, the file handler falls back to NullHandler, and the logs volume stays empty. Net effect: logs only reach stdout (which is why docker compose logs backend works), and the named volume buys nothing.

If the goal is real file logs in the volume, add to the Dockerfile:

RUN mkdir -p /app/logs && chown appuser:appuser /app/logs

Otherwise, if stdout-only is acceptable in Docker, the volume change isn't needed at all. Could you confirm which you intend?

3. TELEGRAM_API_ID=0 — good catch

Empty string fails pydantic's int coercion at startup, and 0 matches the existing TELEGRAM_API_ID: int = 0 default, so this is a legitimate fix. 👍

4. Scope

This PR bundles three unrelated changes (logging resilience, named volume, .env.docker.example fix) plus a new AGENTS.md. The AGENTS.md content is accurate, but it's a near-duplicate of CLAUDE.md that will drift — and it's unrelated to the Docker-logging title. Consider splitting it (or the maintainer may prefer a symlink/single source). Not blocking, just flagging.