Running CLI on Digital Ocean

Running psi on a Digital Ocean Droplet is useful when your database is hosted in Digital Ocean Spaces and you want to avoid the latency of running commands over a long-distance network connection. For example, if your Spaces bucket is in a data center in Sydney, running psi verify from a computer in Brisbane adds significant round-trip overhead for every file checked. The same command from a Droplet in Sydney (in the same data center) is much faster.

When to use a Droplet

• Verify reads every file in the database; extremely sensitive to network latency over long distances.
• Replicate to local disk copies the database from Spaces to the Droplet's local disk before running an upgrade, re-encrypting, or other operations that benefit from fast local I/O, then replicate the result back to Spaces.

Choosing a region

Provision a Droplet in the same region as your Spaces bucket. Match the datacenter to your Space's region:

Space region	Datacenter to use
NYC3	New York (NYC)
SFO3	San Francisco (SFO)
AMS3	Amsterdam (AMS)
SGP1	Singapore (SGP)
FRA1	Frankfurt (FRA)
SYD1	Sydney (SYD)

Recommended Droplet size

psi loads the full merkle tree and database records into memory before starting verification tasks. For very large databases this can be several hundred MB. If the process is OOM-killed, upgrade to a larger Droplet. As a rough guide:

• Minimum: 4 GB RAM (small databases only)
• Recommended: 8 GB RAM
• Large databases (100k+ assets): 16 GB RAM

It is costs more to run a bigger Droplet for a few hours, but that's better than spending your own time diagnosing memory issues.

Creating a Droplet

Control panel

1. In the Digital Ocean control panel, go to Droplets then Create Droplet.
2. Choose the region that matches your Spaces bucket (see table above).
3. Select Ubuntu as the image.
4. Choose a size that meets the RAM requirements above.
5. Under Authentication, add your SSH key or set a root password.
6. Click Create Droplet, then SSH in once it is ready:

ssh root@<droplet-ip>

CLI (doctl)

With an SSH key:

doctl compute droplet create psi-runner \
  --region syd1 \
  --size s-2vcpu-8gb \
  --image ubuntu-24-04-x64 \
  --ssh-keys <your-key-id>

Get your SSH key ID with doctl compute ssh-key list.

With a password, pass a cloud-init script to set the root password and enable password login:

doctl compute droplet create psi-runner \
  --region syd1 \
  --size s-2vcpu-8gb \
  --image ubuntu-24-04-x64 \
  --user-data $'#cloud-config\nssh_pwauth: true\nchpasswd:\n  list: |\n    root:your-password\n  expire: false'

Once the Droplet is ready, SSH in:

doctl compute ssh psi-runner

Setting up the Droplet

1. Install psi

Download the Linux binary from the GitHub releases page:

# Download the latest release
wget https://github.com/ashleydavis/photosphere/releases/latest/download/photosphere-cli-linux-x64.tar.gz
tar -xzf photosphere-cli-linux-x64.tar.gz
chmod +x psi
sudo mv psi /usr/local/bin/

Verify the installation:

psi --version

2. Configure credentials

Set your credentials as environment variables:

export AWS_ACCESS_KEY_ID=your-access-key
export AWS_SECRET_ACCESS_KEY=your-secret-key
export AWS_REGION=us-east-1
export AWS_ENDPOINT=https://syd1.digitaloceanspaces.com   # match your region

export PSI_ENCRYPTION_KEY=your-encryption-key    # if your database is encrypted
export GOOGLE_API_KEY=your-google-api-key        # if using reverse geocoding

These are only needed for the current session. Since the Droplet is destroyed after use, there is no need to persist them to disk.

Running commands

Once set up, use psi exactly as you would locally. The commands run against Spaces directly from the Droplet.

# Verify database integrity
psi verify --db s3:my-bucket/my-photos

# Full verification (re-hashes every file)
psi verify --db s3:my-bucket/my-photos --full

# Replicate to a second bucket
psi replicate --db s3:my-bucket/my-photos --dest s3:my-backup-bucket/my-photos

What to do if the process is OOM-killed

If psi is killed mid-run, choose one of the options below.

Reduce worker threads

By default psi spawns one worker thread per CPU core. Reducing this lowers peak memory at the cost of speed:

psi verify --db s3:my-bucket/my-photos --workers 2

Resize the Droplet

Increase the Droplet's memory (e.g. 4 GB to 8 GB, 8 GB to 16 GB) via the control panel or:

doctl compute droplet-action resize <droplet-id> --size s-2vcpu-16gb --wait

Then reboot and retry.

Keeping the session alive

For long-running operations (verify on a large database can take hours), use screen or tmux so the command continues if your SSH connection to the Droplet drops.

screen

# Start a screen session
screen -S psi

# Run your command inside screen
psi verify --db s3:my-bucket/my-photos --full

# Detach with Ctrl+A then D
# Reattach later with:
screen -r psi

tmux

# Start a tmux session
tmux new -s psi

# Run your command inside tmux
psi verify --db s3:my-bucket/my-photos --full

# Detach with Ctrl+B then D
# Reattach later with:
tmux attach -t psi

Cleaning up

Once the command is complete, destroy the Droplet to stop incurring charges. This can be done from the control panel or via the CLI:

doctl compute droplet delete <droplet-id>

Related documentation

• Getting-Started-CLI - general CLI usage
• Configuration-Digital-Ocean-Spaces - setting up Digital Ocean Spaces
• Managing-Secrets - storing credentials in the vault
• Managing-Databases - registering databases by name
• Command-Reference - full list of psi commands and options