Upgrading

This guide covers upgrading Inboxorcist to a new version. Your data is safe during upgrades — database files and configuration are preserved automatically.

Data is never overwritten during upgrades. Your emails database, OAuth tokens, and configuration are stored separately from the application files.

What Gets Preserved

Upgrading Binary Installation

Using the Install Script (Recommended)

The install script automatically preserves your data directory and .env configuration.

# Re-run the install script - it will update the binary only
curl -fsSL https://inboxorcist.com/install.sh | bash

# Restart the application
~/.inboxorcist/inboxorcist

# Re-run the install script - it will update the binary only
curl -fsSL https://inboxorcist.com/install.sh | bash

# Restart the application (or restart the service)
~/.local/share/inboxorcist/inboxorcist

# Re-run the install script
irm inboxorcist.com/install.ps1 | iex

# Restart the application
& "$env:LOCALAPPDATA\Inboxorcist\inboxorcist.exe"

Manual Binary Upgrade

The data/ directory and .env file are not included in the release archive, so extracting the new version won't overwrite them.

Upgrading Docker Installation

Docker volumes persist your data across container updates.

Using Pre-built Images (Recommended)

cd ~/inboxorcist  # or wherever your docker-compose.yml is

# Pull the latest image
docker compose pull

# Recreate containers with new image
docker compose up -d

Using Git Repository

cd ~/inboxorcist

# Pull latest changes
git pull

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

Verify the Upgrade

# Check container is running
docker compose ps

# Check logs for any errors
docker compose logs -f inboxorcist

# Verify version (check the startup logs)
docker compose logs inboxorcist | head -20

Data Persistence

Docker volumes ensure your data survives upgrades:

To verify your volumes exist:

docker volume ls | grep inboxorcist

Upgrading Railway Deployment

Railway automatically deploys when you push to your connected branch.

If Deployed via Template

1. Go to your Railway project dashboard
2. Click on the Inboxorcist service
3. Go to Settings > Source
4. Click Check for Updates or Redeploy

If Deployed via GitHub

Simply push to your connected branch:

git pull origin main
git push

Railway will automatically build and deploy the new version.

Manual Redeploy

1. Go to Deployments tab
2. Click the ... menu on the latest deployment
3. Select Redeploy

Railway's PostgreSQL database persists independently of your app deployments. Your data is safe during redeployments.

Upgrading Other Cloud Platforms

Render / Fly.io / DigitalOcean App Platform

These platforms typically auto-deploy when you push to your connected repository:

git pull origin main
git push

Or trigger a manual redeploy from their respective dashboards.

VPS with Docker

Same as Docker installation:

docker compose pull
docker compose up -d

VPS with Binary

Re-run the install script:

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

Database Migrations

Inboxorcist automatically runs database migrations on startup. No manual intervention is required.

After upgrading, check the logs to confirm migrations ran successfully:

# Docker
docker compose logs inboxorcist | grep -i migration

# Binary
# Check terminal output on startup

Rollback

If you need to rollback to a previous version:

Binary Rollback

cd ~/.inboxorcist
# Download specific version
curl -LO https://github.com/inboxorcist/inboxorcist/releases/download/v0.2.1/inboxorcist-darwin-arm64.tar.gz
tar -xzf inboxorcist-darwin-arm64.tar.gz --strip-components=1
./inboxorcist

cd ~/.local/share/inboxorcist
# Download specific version
curl -LO https://github.com/inboxorcist/inboxorcist/releases/download/v0.2.1/inboxorcist-linux-x64.tar.gz
tar -xzf inboxorcist-linux-x64.tar.gz --strip-components=1
./inboxorcist

Docker Rollback

# Edit docker-compose.yml to use specific version
# image: ghcr.io/inboxorcist/inboxorcist:v0.2.1

docker compose pull
docker compose up -d

Railway Rollback

1. Go to Deployments
2. Find the previous working deployment
3. Click ... > Rollback

Troubleshooting

App Won't Start After Upgrade

1. Check logs for errors

   # Docker
   docker compose logs inboxorcist
   
   # Binary
   ./inboxorcist 2>&1 | head -50

2. Verify environment variables — New versions may require additional variables

3. Check database migrations — Look for migration errors in logs

Data Missing After Upgrade

Your data should never be lost during an upgrade. If data appears missing:

1. Verify data directory exists

   ls -la data/

2. Check Docker volumes

   docker volume inspect inboxorcist-data

3. Restore from backup if you created one before upgrading

OAuth Stops Working

If Google OAuth breaks after upgrade:

1. Verify APP_URL is set correctly in .env
2. Confirm redirect URI in Google Cloud Console matches ${APP_URL}/auth/google/callback
3. Check that GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET are still set