Bug: Multiple issues prevent successful Docker deployment when following the docs

[FK78]

Following the official Deploy with Docker guide results in a broken setup due to three separate gaps. None of these are obvious from the documentation.

---

1. app service is missing from docker-compose.yml

Problem: The guide says to run docker compose up -d to deploy Quackback, but the included docker-compose.yml only defines infrastructure services (postgres, minio, dragonfly, mailpit). There is no app service, so the Quackback application container is never started.

Steps to reproduce:

1. Clone the repository
2. Copy .env.example to .env and fill in values
3. Run docker compose up -d
4. All infrastructure containers start, but no quackback-app container is created

Suggested fix: Add an app service to docker-compose.yml. Since the rest of the compose file uses local builds (e.g. the postgres service), a local build should be the default, with the published image as an alternative:

  app:
    # Option A: build locally from source (consistent with the rest of this compose file)
    build:
      context: .
      dockerfile: apps/web/Dockerfile
    # Option B: use the published image
    # image: ghcr.io/quackbackio/quackback:latest
    container_name: quackback-app
    restart: unless-stopped
    ports:
      - '3000:3000'
    env_file: .env
    depends_on:
      postgres:
        condition: service_healthy
      dragonfly:
        condition: service_healthy
      minio:
        condition: service_healthy

---

2. .env.example uses quoted values, which breaks Docker's --env-file

Problem: .env.example wraps all values in double quotes (e.g. DATABASE_URL="postgresql://..."). Docker's --env-file does not strip quotes, they become literal characters in the value. This causes the postgres client to receive "postgresql://... as the URL, which fails to parse and throws:

TypeError: <redacted> cannot be parsed as a URL.
code: "ERR_INVALID_URL"

This affects both docker run --env-file and docker compose when using env_file.

Suggested fix: Remove quotes from all values in .env.example, or add a prominent warning in the docs that quotes must be omitted when using Docker.

---

3. No guidance on disabling MinIO when switching to an external S3 provider

Problem: The .env.example and environment variables reference explain how to configure AWS S3, Cloudflare R2, etc., but neither mentions that the minio and minio-init services in docker-compose.yml should be removed or commented out when using an external provider. This leaves users running an unused MinIO container.

Suggested fix: Add a note in .env.example and/or the Docker deploy guide along the lines of:

When using an external S3 provider, remove or comment out the minio and minio-init services from docker-compose.yml. Also ensure S3_ENDPOINT is empty and S3_FORCE_PATH_STYLE is false for AWS S3.

---

Environment

• Docker Compose v2
• macOS (Apple Silicon / arm64)
• Quackback cloned from main