Inboxorcist

Deploy Inboxorcist on any Linux server. The binary deployment is recommended for its simplicity.

Prerequisites

Linux server (Ubuntu 22.04+ recommended)
SSH access with sudo privileges
Domain name (optional but recommended for HTTPS)

Option 1: Binary Deployment (Recommended)

The simplest way to deploy on a VPS. No Docker required.

Install the Binary

# Install Inboxorcist
curl -fsSL https://inboxorcist.com/install.sh | bash

The installer will:

Detect your architecture
Download the latest release to ~/.local/share/inboxorcist
Ask if you want to use SQLite or PostgreSQL

Database Options

The installer prompts you to choose:

SQLite (default) - No setup required. Data stored locally. Good for most use cases.
PostgreSQL - For cloud deployments or when you need to share data across instances.

Using External PostgreSQL:

If you have an existing PostgreSQL database (e.g., managed database from DigitalOcean, AWS RDS, Supabase):

# Edit .env after installation
nano ~/.local/share/inboxorcist/.env

# Add your database URL
DATABASE_URL=postgres://user:password@your-db-host:5432/inboxorcist

Configure as a Service

Create /etc/systemd/system/inboxorcist.service:

[Unit]
Description=Inboxorcist
After=network.target

[Service]
Type=simple
User=your-user
WorkingDirectory=/home/your-user/.local/share/inboxorcist
ExecStart=/home/your-user/.local/share/inboxorcist/inboxorcist
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target

Enable and start:

sudo systemctl daemon-reload
sudo systemctl enable inboxorcist
sudo systemctl start inboxorcist

Configure Reverse Proxy

Install nginx:

sudo apt install nginx -y

Create /etc/nginx/sites-available/inboxorcist:

server {
    listen 80;
    server_name yourdomain.com;

    location / {
        proxy_pass http://localhost:6616;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_cache_bypass $http_upgrade;
    }
}

Enable the site:

sudo ln -s /etc/nginx/sites-available/inboxorcist /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx

Add SSL with Let's Encrypt

sudo apt install certbot python3-certbot-nginx -y
sudo certbot --nginx -d yourdomain.com

Certbot automatically configures nginx for HTTPS.

Update Environment Variables

After setting up your domain, update .env:

APP_URL=https://yourdomain.com

Then update your Google Cloud Console OAuth redirect URI to https://yourdomain.com/auth/google/callback.

Restart:

sudo systemctl restart inboxorcist

Option 2: Docker Deployment

If you prefer Docker, you can use Docker Compose.

Install Docker

# Update packages
sudo apt update && sudo apt upgrade -y

# Install Docker
curl -fsSL https://get.docker.com | sudo sh

# Add your user to docker group
sudo usermod -aG docker $USER

# Install Docker Compose
sudo apt install docker-compose-plugin

# Log out and back in for group changes

Deploy with Docker

# Create directory
mkdir inboxorcist && cd inboxorcist

# Create docker-compose.yml with pre-built image
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
docker compose up -d

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

Check Status

docker compose ps
docker compose logs -f inboxorcist

Firewall Configuration

Allow HTTP/HTTPS traffic:

sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw enable

Updating

Binary Update

Re-run the install script to update:

curl -fsSL https://inboxorcist.com/install.sh | bash
sudo systemctl restart inboxorcist

Your data and configuration are preserved during updates.

Docker Update

cd /path/to/inboxorcist
docker compose pull
docker compose up -d

Backup

Binary (SQLite)

# Stop service to ensure consistency
sudo systemctl stop inboxorcist

# Copy database
cp ~/.local/share/inboxorcist/data/inboxorcist.db ~/backups/inboxorcist-$(date +%Y%m%d).db

# Restart
sudo systemctl start inboxorcist

Docker (PostgreSQL)

docker compose exec postgres pg_dump -U inboxorcist inboxorcist > backup-$(date +%Y%m%d).sql

Automated Backup Script (Binary)

Create ~/.local/share/inboxorcist/backup.sh:

#!/bin/bash
BACKUP_DIR="$HOME/backups/inboxorcist"
DATE=$(date +%Y%m%d_%H%M%S)

mkdir -p $BACKUP_DIR
cp ~/.local/share/inboxorcist/data/inboxorcist.db "$BACKUP_DIR/inboxorcist_$DATE.db"

# Keep only last 7 backups
ls -t $BACKUP_DIR/*.db | tail -n +8 | xargs -r rm

Add to crontab:

# Daily backup at 2 AM
0 2 * * * ~/.local/share/inboxorcist/backup.sh

Monitoring

View Logs (Binary)

sudo journalctl -u inboxorcist -f

View Logs (Docker)

docker compose logs -f

Health Check

curl http://localhost:6616/health

Troubleshooting

Permission Denied

Ensure correct ownership:

sudo chown -R www-data:www-data /opt/inboxorcist

Port Already in Use

Check what's using the port:

sudo lsof -i :6616

Service Won't Start

Check logs for errors:

sudo journalctl -u inboxorcist -n 50

nginx 502 Bad Gateway

Ensure the service is running:

curl http://localhost:6616/health

Custom VPS