Skip to main content
This guide shows you how to set up, update, and maintain a self-hosted Sure application with Docker Compose.

​
Prerequisites

  • Docker Engine installed and running
  • Basic familiarity with the command line

​
Installation

​
Install Docker

  1. Follow the official Docker installation guide
  2. Start the Docker service on your machine
  3. Verify the installation:
docker run hello-world
If Docker is set up correctly, this command will succeed.

​
Create your application directory

Create a directory where your app will run: 
mkdir -p ~/docker-apps/sure
cd ~/docker-apps/sure

​
Download the Docker Compose file

Download the sample compose file from the Sure repository: 
curl -o compose.yml https://raw.githubusercontent.com/we-promise/sure/main/compose.example.yml
This creates a compose.yml file in your current directory with the default configuration.

​
Configuration

By default, the compose.example.yml file runs without any configuration. For production deployments or if you’re running outside of a local network, follow these steps to add security.

​
Create an environment file

Create a .env file where Docker will read environment variables: 
touch .env

​
Generate a secret key

Generate a secret key using one of these methods: With OpenSSL: 
openssl rand -hex 64
Without OpenSSL: 
head -c 64 /dev/urandom | od -An -tx1 | tr -d ' \n' && echo
Save the generated key for the next step.

​
Configure environment variables

Open the .env file in your text editor and add: 
SECRET_KEY_BASE="your-generated-secret-key-here"
POSTGRES_PASSWORD="your-database-password-here"
Replace the placeholder values with your generated secret key and a secure database password.

​
Running the application

​
Start the application

Start the app to verify everything is working: 
docker compose up
This pulls the official Docker image and starts the app. You’ll see logs in your terminal. Open your browser and navigate to http://localhost:3000. You should see the Sure login screen.

​
Create your account

On first run, register a new account:
  1. Click “Create your account” on the login page
  2. Enter your email
  3. Enter a password

​
Run in the background

To run Sure in the background:
  1. Stop the current process with Ctrl+C
  2. Start in detached mode:
docker compose up -d
Verify it’s running: 
docker compose ls
Your app is now accessible at http://localhost:3000.

​
Updating

The Docker image in your compose.yml file controls which version of Sure you’re running: 
image: ghcr.io/we-promise/sure:latest
  • ghcr.io/we-promise/sure:latest - Latest alpha release
  • ghcr.io/we-promise/sure:stable - Latest stable release
You can also pin to a specific version from the packages page.

​
Update to the latest version

Your app does not automatically update. To update: 
cd ~/docker-apps/sure
docker compose pull
docker compose build
docker compose up --no-deps -d web worker

​
Change update channel

To switch between update channels, edit the compose.yml file: 
image: ghcr.io/we-promise/sure:stable
Then restart the app: 
docker compose pull
docker compose build
docker compose up --no-deps -d web worker

​
Backup service

The Docker Compose configuration includes an optional backup service that automatically backs up your PostgreSQL database.

​
Enabling backups

The backup service uses Docker Compose profiles and is disabled by default. To enable it: 
docker compose --profile backup up -d

​
Configure backup settings

The backup service uses the following default settings:
  • Schedule: Daily at midnight
  • Retention: 7 daily backups, 4 weekly backups, 6 monthly backups
  • Location: /opt/sure-data/backups on your host machine
To customize these settings, edit the backup service in your compose.yml file: 
backup:
  profiles:
    - backup
  image: prodrigestivill/postgres-backup-local
  restart: unless-stopped
  volumes:
    - /your/custom/path:/backups  # Change this to your desired location
  environment:
    - POSTGRES_HOST=db
    - POSTGRES_DB=${POSTGRES_DB:-sure_production}
    - POSTGRES_USER=${POSTGRES_USER:-sure_user}
    - POSTGRES_PASSWORD=${POSTGRES_PASSWORD:-sure_password}
    - SCHEDULE=@daily              # Change schedule (e.g., @hourly, @weekly)
    - BACKUP_KEEP_DAYS=7           # Number of daily backups to keep
    - BACKUP_KEEP_WEEKS=4          # Number of weekly backups to keep
    - BACKUP_KEEP_MONTHS=6         # Number of monthly backups to keep

​
Backup schedule options

You can use cron syntax or these shortcuts:
  • @hourly - Every hour
  • @daily - Once per day at midnight
  • @weekly - Once per week
  • @monthly - Once per month
  • Custom cron: 0 2 * * * (2 AM daily)

​
Restoring from backup

To restore your database from a backup:
  1. Stop the application:
docker compose down
  1. Locate your backup file in the backup directory (e.g., /opt/sure-data/backups)
  2. Restore the backup: 
docker compose up -d db
docker compose exec -T db psql -U sure_user -d sure_production < /path/to/backup.sql
  1. Restart the application:
docker compose up -d

​
Verifying backups

Check that backups are running correctly: 
# View backup service logs
docker compose logs backup

# List backup files
ls -lh /opt/sure-data/backups

​
Troubleshooting

​
Database connection errors

If you encounter ActiveRecord::DatabaseConnectionError on first startup, Docker may have initialized the Postgres database with a different default role from a previous attempt.
The following commands will delete all existing data in your Sure database. Only proceed if you’re comfortable losing this data.
Reset the database: 
docker compose down
docker volume rm sure_postgres-data
docker compose up
docker compose exec db psql -U sure_user -d sure_development -c "SELECT 1;"
The last command verifies the issue is fixed.

​
Slow CSV imports

If CSV imports are processing rows slower than expected, check your worker logs for errors: 
docker compose logs worker
Look for connection timeouts or Redis communication failures. The sure-worker container requires Redis to process CSV imports.

​
Getting help

If you find bugs or have feature requests: