Omnivore Docker Setup Guide

Overview

This guide documents the complete setup process for running Omnivore using Docker Compose, including common issues and their solutions.

Prerequisites

• Docker and Docker Compose installed
• Debian GNU/Linux system
• sudo privileges

Initial Setup Steps

1. Pull Docker Images

docker compose pull

2. First Attempt to Start Services

docker compose up

Issues Encountered and Solutions

Issue 1: Database User Authentication Failed

Problem: The application services couldn’t connect to PostgreSQL because the app_user role didn’t exist.

Error Message:

error: password authentication failed for user "app_user"
FATAL: Role "app_user" does not exist

Solution:

1. Start PostgreSQL container first:

docker compose up -d postgres

2. Wait for PostgreSQL to be ready:

sleep 10

3. Create the required database user:

docker exec -it omnivore-postgres psql -U postgres -d omnivore -c "CREATE USER app_user WITH PASSWORD 'app_pass';"
docker exec -it omnivore-postgres psql -U postgres -d omnivore -c "GRANT ALL PRIVILEGES ON DATABASE omnivore TO app_user;"
docker exec -it omnivore-postgres psql -U postgres -d omnivore -c "ALTER USER app_user CREATEDB;"

Issue 2: MinIO Bucket Creation Failed

Problem: The createbuckets container was using an outdated MinIO client command syntax.

Error Message:

mc: <ERROR> `config` is not a recognized command. Get help using `--help` flag.

Solution:

1. Update the docker-compose.yml file to use the correct MinIO client syntax:

sed -i 's/mc config host add/mc alias set/g' docker-compose.yml

2. Remove and recreate the createbuckets container:

docker compose stop createbuckets
docker compose rm createbuckets
docker compose up -d createbuckets

Issue 3: Environment Variable Updates Not Taking Effect

Problem: After updating the .env file, changes weren’t reflected in running containers.

Solution: Complete rebuild of all containers and volumes:

# Stop and remove all containers and volumes
docker compose down -v

# Rebuild all containers from scratch
docker compose up --build -d

# If database authentication fails again, recreate the app_user:
docker exec -it omnivore-postgres psql -U postgres -d omnivore -c "CREATE USER app_user WITH PASSWORD 'app_pass';"
docker exec -it omnivore-postgres psql -U postgres -d omnivore -c "GRANT ALL PRIVILEGES ON DATABASE omnivore TO app_user;"
docker exec -it omnivore-postgres psql -U postgres -d omnivore -c "ALTER USER app_user CREATEDB;"

# Restart all services
docker compose up -d

Complete Working Setup Process

Step 1: Initial Deployment

# Pull latest images
docker compose pull

# Start all services
docker compose up -d

Step 2: Fix Database Authentication (if needed)

# Create database user manually
docker exec -it omnivore-postgres psql -U postgres -d omnivore -c "CREATE USER app_user WITH PASSWORD 'app_pass';"
docker exec -it omnivore-postgres psql -U postgres -d omnivore -c "GRANT ALL PRIVILEGES ON DATABASE omnivore TO app_user;"
docker exec -it omnivore-postgres psql -U postgres -d omnivore -c "ALTER USER app_user CREATEDB;"

# Restart services
docker compose restart api queue-processor

Step 3: Fix MinIO Bucket Creation (if needed)

# Update MinIO command syntax
sed -i 's/mc config host add/mc alias set/g' docker-compose.yml

# Recreate createbuckets container
docker compose stop createbuckets
docker compose rm createbuckets
docker compose up -d createbuckets

Step 4: Verify All Services

# Check status of all containers
docker compose ps

# Check for any exited containers
docker compose ps -a

For Environment Variable Updates

When you need to update the .env file:

# Stop and remove everything
docker compose down -v

# Rebuild from scratch
docker compose up --build -d

# Recreate database user (will be needed after volume reset)
docker exec -it omnivore-postgres psql -U postgres -d omnivore -c "CREATE USER app_user WITH PASSWORD 'app_pass';"
docker exec -it omnivore-postgres psql -U postgres -d omnivore -c "GRANT ALL PRIVILEGES ON DATABASE omnivore TO app_user;"
docker exec -it omnivore-postgres psql -U postgres -d omnivore -c "ALTER USER app_user CREATEDB;"

# Restart all services
docker compose up -d

Final Service Overview

After successful setup, you should have these services running:

Service	Container Name	Port	Status
Web Interface	omnivore-web	3000	Running
API Backend	omnivore-api	4000	Running (Healthy)
PostgreSQL	omnivore-postgres	5432	Running (Healthy)
Redis	omnivore-redis	6379	Running (Healthy)
MinIO	ominivore-minio-1	1010	Running (Healthy)
Content Fetch	omnivore-content-fetch	9090	Running
Image Proxy	omnivore-image-proxy	7070	Running
Mail Watcher	omnivore-mail-watch-server	4398	Running
Queue Processor	omnivore-queue-processor	–	Running

Completed Tasks (will show as Exited 0):

• omnivore-migrate (Database migration)
• ominivore-createbuckets-1 (MinIO bucket setup)

Access Information

• Web Application: http://localhost:3000 (or your configured domain)
• API Endpoint: http://localhost:4000 (or your configured domain)
• Demo Login:
  • Email: [email protected]
  • Password: demo_password

Common Commands

# Check container status
docker compose ps

# View logs for specific service
docker logs <container-name>

# Restart specific service
docker compose restart <service-name>

# Stop all services
docker compose down

# Stop and remove volumes (complete reset)
docker compose down -v

# Rebuild and start
docker compose up --build -d

Troubleshooting

Container Won’t Start

1. Check logs: docker logs <container-name>
2. Verify .env file configuration
3. Ensure all dependencies are running
4. Try recreating the container: docker compose up -d <service-name>

Database Connection Issues

1. Verify PostgreSQL is running: docker compose ps postgres
2. Check if app_user exists: docker exec -it omnivore-postgres psql -U postgres -d omnivore -c "\du"
3. Recreate app_user if needed (see Step 2 above)

MinIO Issues

1. Check MinIO logs: docker logs ominivore-minio-1
2. Verify bucket creation: docker logs ominivore-createbuckets-1
3. Manually create bucket if needed:
   

   docker exec ominivore-minio-1 mc alias set myminio http://localhost:9000 minio miniominio
   docker exec ominivore-minio-1 mc mb myminio/omnivore
   

   
   

Web Interface Not Loading

1. Check if web container is running: docker compose ps web
2. Verify API is healthy: docker compose ps api
3. Check network connectivity between containers
4. Verify port mappings in docker-compose.yml

---

Note: This guide was created based on the actual deployment experience on Debian GNU/Linux with Docker Compose. The issues and solutions documented here were encountered and resolved during the setup process.

Last Updated: June 12, 2025