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 :
Start PostgreSQL container first:
docker compose up -d postgres
Wait for PostgreSQL to be ready:
sleep 10
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 :
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
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 :
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
Check logs: docker logs <container-name>
Verify .env file configuration
Ensure all dependencies are running
Try recreating the container: docker compose up -d <service-name>
Database Connection Issues
Verify PostgreSQL is running: docker compose ps postgres
Check if app_user exists: docker exec -it omnivore-postgres psql -U postgres -d omnivore -c "\du"
Recreate app_user if needed (see Step 2 above)
MinIO Issues
Check MinIO logs: docker logs ominivore-minio-1
Verify bucket creation: docker logs ominivore-createbuckets-1
Manually create bucket if needed:docker exec ominivore-minio-1 mc alias set myminio http://localhost:9000 minio miniominio
Web Interface Not Loading
Check if web container is running: docker compose ps web
Verify API is healthy: docker compose ps api
Check network connectivity between containers
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
