Inboxorcist

Deploy Inboxorcist on any machine with Docker. Use this if you prefer containerized deployments.

For simpler deployment, consider the Single Binary option which requires no Docker and supports both SQLite and PostgreSQL.

Prerequisites

Docker 20.10 or later
Docker Compose v2

Docker Image

Inboxorcist publishes official Docker images to GitHub Container Registry:

ghcr.io/inboxorcist/inboxorcist:latest

Available tags:

latest - Latest stable release
v1.0.0 - Specific version
1.0 - Major.minor version
1 - Major version only

Supported platforms: linux/amd64, linux/arm64

Quick Start

Option 1: SQLite (Simplest)

# Create a directory
mkdir inboxorcist && cd inboxorcist

# Create docker-compose.yml
cat > docker-compose.yml << 'EOF'
services:
  inboxorcist:
    image: ghcr.io/inboxorcist/inboxorcist:latest
    ports:
      - "6616:6616"
    environment:
      - JWT_SECRET=${JWT_SECRET}
      - ENCRYPTION_KEY=${ENCRYPTION_KEY}
    volumes:
      - inboxorcist-data:/usr/src/app/data

volumes:
  inboxorcist-data:
EOF

# Generate secrets
cat > .env << EOF
JWT_SECRET=$(openssl rand -base64 32)
ENCRYPTION_KEY=$(openssl rand -hex 32)
EOF

# Start Inboxorcist
docker compose up -d

Open http://localhost:6616/setup to configure Google OAuth credentials via the web UI.

Option 2: With Bundled PostgreSQL

# Create a directory
mkdir inboxorcist && cd inboxorcist

# Create docker-compose.yml
cat > docker-compose.yml << 'EOF'
services:
  postgres:
    image: postgres:16-alpine
    environment:
      POSTGRES_USER: inboxorcist
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:-inboxorcist_secret}
      POSTGRES_DB: inboxorcist
    volumes:
      - postgres-data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U inboxorcist"]
      interval: 10s
      timeout: 5s
      retries: 5

  inboxorcist:
    image: ghcr.io/inboxorcist/inboxorcist:latest
    ports:
      - "6616:6616"
    environment:
      - JWT_SECRET=${JWT_SECRET}
      - ENCRYPTION_KEY=${ENCRYPTION_KEY}
      - DATABASE_URL=postgres://inboxorcist:${POSTGRES_PASSWORD:-inboxorcist_secret}@postgres:5432/inboxorcist
    volumes:
      - inboxorcist-data:/usr/src/app/data
    depends_on:
      postgres:
        condition: service_healthy

volumes:
  inboxorcist-data:
  postgres-data:
EOF

# Generate secrets
cat > .env << EOF
JWT_SECRET=$(openssl rand -base64 32)
ENCRYPTION_KEY=$(openssl rand -hex 32)
POSTGRES_PASSWORD=$(openssl rand -base64 16)
EOF

# Start Inboxorcist
docker compose up -d

Option 3: External PostgreSQL

If you have an existing PostgreSQL database:

# Create a directory
mkdir inboxorcist && cd inboxorcist

# Create docker-compose.yml
cat > docker-compose.yml << 'EOF'
services:
  inboxorcist:
    image: ghcr.io/inboxorcist/inboxorcist:latest
    ports:
      - "6616:6616"
    environment:
      - JWT_SECRET=${JWT_SECRET}
      - ENCRYPTION_KEY=${ENCRYPTION_KEY}
      - DATABASE_URL=${DATABASE_URL}
    volumes:
      - inboxorcist-data:/usr/src/app/data

volumes:
  inboxorcist-data:
EOF

# Generate secrets and set database URL
cat > .env << EOF
JWT_SECRET=$(openssl rand -base64 32)
ENCRYPTION_KEY=$(openssl rand -hex 32)
DATABASE_URL=postgres://user:password@your-db-host:5432/inboxorcist
EOF

# Start Inboxorcist
docker compose up -d

Environment Variables

Create a .env file with the following variables:

# Required - Security (generate these, see below)
JWT_SECRET=your-jwt-secret-min-32-chars
ENCRYPTION_KEY=your-64-character-hex-encryption-key

# Optional - Google OAuth (can also be configured via /setup UI)
# GOOGLE_CLIENT_ID=your-client-id.apps.googleusercontent.com
# GOOGLE_CLIENT_SECRET=GOCSPX-your-secret

# Optional - App URL (for custom domains)
# APP_URL=https://your-domain.com

# Optional - PostgreSQL password (for bundled postgres)
POSTGRES_PASSWORD=your-secure-password

# Optional - External PostgreSQL (use with --profile external-db)
# DATABASE_URL=postgres://user:password@host:5432/inboxorcist

Google OAuth credentials are optional in .env. If not set, you can configure them via the web UI at /setup on first run.

Managing the Deployment

View Status

docker compose ps

View Logs

# All services
docker compose logs -f

# Specific service
docker compose logs -f inboxorcist

Stop Services

docker compose down

Update to Latest Version

git pull
docker compose build
docker compose up -d

Backup PostgreSQL Database

docker compose exec postgres pg_dump -U inboxorcist inboxorcist > backup.sql

Restore PostgreSQL Database

docker compose exec -T postgres psql -U inboxorcist inboxorcist < backup.sql

Custom Port Configuration

To use a different port, modify your .env:

APP_URL=http://localhost:8080

Then update the port mapping in docker-compose.yml accordingly (e.g., "8080:6616").

Health Checks

The container includes health checks:

# Check health status
docker inspect --format='{{.State.Health.Status}}' inboxorcist

# View health check logs
docker inspect --format='{{range .State.Health.Log}}{{.Output}}{{end}}' inboxorcist

Resource Limits

For production, consider adding resource limits in docker-compose.yml:

services:
  inboxorcist:
    deploy:
      resources:
        limits:
          cpus: '1'
          memory: 1G
        reservations:
          memory: 512M

Troubleshooting

Container Won't Start

Check the startup validation:

docker compose logs inboxorcist | head -50

Common issues:

Missing required environment variables
JWT_SECRET less than 32 characters
ENCRYPTION_KEY not 64 hex characters
Invalid APP_URL format (must start with http:// or https://)

Database Connection Failed

Ensure PostgreSQL is healthy:

docker compose ps postgres
docker compose logs postgres

Permission Issues

If you see permission errors, ensure the data directory is writable:

docker compose exec inboxorcist ls -la /usr/src/app/data

Docker

On this page