Production Deployment

Listsome is designed to be deployed simply to any hardware you control. The goal is to bring ease of use to technology you control.

Prerequisites

A server running Linux (Raspberry Pi, VPS, or dedicated hardware)
just task runner installed locally (cargo install just or via package manager)
ARM64 cross-compilation support: rustup target add aarch64-unknown-linux-gnu
SSH access to your server

Configuration

Create a .justlocal file in the project root:

export LISTSOME_HOST="your-server.local"
export LISTSOME_USER="your-username"
export LISTSOME_PORT="3003"
export LISTSOME_PORT_TEST="3005"

Then source it before running just commands:

source .justlocal

Note: .justlocal is gitignored - never commit it.

Quick Start

First Time Setup

just deploy-init

This creates:

/opt/listsome/ with binary, static files, and database
/opt/listsome/.env with runtime configuration
Systemd service at /etc/systemd/system/listsome.service
Database file at /opt/listsome/db/listsome.db

Deploy Updates

just deploy

Builds ARM64 binary, copies to server, restarts service.

Cloudflare Tunnel Setup

Point your tunnel to localhost:3003 (or your configured port):

# ~/.cloudflared/config.yml
ingress:
  - hostname: yourdomain.com
    service: http://localhost:3003

Restart the tunnel: sudo systemctl restart cloudflared

First-Time Admin Setup

After deploying, visit https://yourdomain.com/setup to create your admin account.

Maintenance Commands

Production Management

just logs-prod          # View real-time logs
just status-prod        # Check service status
just restart-prod       # Restart service
just shell              # SSH to server

Binary Management

just binary-list        # List all versions with timestamps
just rollback-prod      # Interactive rollback to previous version
just binary-prune --keep 3  # Delete old versions, keep last 3

Database

just db-backup          # Backup to ~/.listsome/backups/

Test Deployment (Optional)

Deploy to a test instance before promoting to production:

just deploy-test-init   # First time test setup (port 3004)
just deploy-test      # Deploy to test

File Structure on Server

/opt/listsome/                    # Production
├── listsome                      # Current binary
├── listsome.v0.1.0             # Versioned backup
├── static/                       # Static assets
├── content/assets/              # User uploads
├── db/
│   └── listsome.db              # SQLite database
└── .env                         # Runtime config

/opt/listsome-test/              # Test (optional)
├── listsome
├── static/
├── content/assets/
├── db/
│   └── listsome.db
└── .env

Troubleshooting

Permission denied on database:

ssh your-user@your-server "sudo chown your-user:your-user /opt/listsome/db/listsome.db"

Service won’t start:

just logs-prod 100
just status-prod

Build fails:

rustup target add aarch64-unknown-linux-gnu

Security Notes

App runs as your user (not root)
Service is bound to specific port only
Database is in app directory, isolated per instance
Systemd hardening enabled (NoNewPrivileges, PrivateTmp, etc.)

Keyboard shortcuts

Listsome