Self-hosting with Docker

Deploy Sure on your own infrastructure using Docker Compose

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.

Email configuration

To enable email notifications and password resets, configure SMTP settings in your .env file:

SMTP_ADDRESS=smtp.example.com
SMTP_PORT=587
SMTP_DOMAIN=example.com
SMTP_USERNAME=your-username
SMTP_PASSWORD=your-password
SMTP_AUTHENTICATION=plain
SMTP_ENABLE_STARTTLS_AUTO=true

SSL/TLS options

For SMTP servers with custom SSL certificates or self-signed certificates:

Skip TLS verification (not recommended for production):

SMTP_OPENSSL_VERIFY_MODE=none

Use custom CA certificate:

SSL_CA_FILE=/path/to/ca-certificate.pem

The SSL_CA_FILE option allows you to specify a custom CA certificate file for SSL verification when connecting to SMTP servers with self-signed or internal certificates.

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.

Optional: expose Sure with Cloudflare Tunnel

If you want to reach your self-hosted instance from the public internet without opening router ports, you can put a Cloudflare Tunnel in front of the web container.

1. Create a tunnel in Cloudflare Zero Trust and copy the tunnel token.
2. Add the token to your .env file:

CLOUDFLARE_TUNNEL_TOKEN="your-cloudflare-tunnel-token"

3. Edit compose.yml and set:

RAILS_ASSUME_SSL: "true"

This tells Sure to generate HTTPS URLs correctly when Cloudflare terminates TLS before forwarding traffic to the container over HTTP.

4. Add a cloudflared service to your compose.yml:

  cloudflared:
    image: cloudflare/cloudflared:latest
    restart: unless-stopped
    command: tunnel run
    environment:
      TUNNEL_TOKEN: ${CLOUDFLARE_TUNNEL_TOKEN}
    depends_on:
      - web
    networks:
      - sure_net

5. In the Cloudflare tunnel dashboard, add a public hostname such as sure.example.com and point it at the internal Docker service:

Service type: HTTP
URL: http://web:3000

6. Start the tunnel connector:

docker compose up -d cloudflared
docker compose logs cloudflared --tail 20

Look for a successful tunnel registration message in the logs, then open https://sure.example.com.

Cloudflare should connect to http://web:3000, not https://web:3000. Sure speaks plain HTTP inside Docker and relies on RAILS_ASSUME_SSL to know the original request was HTTPS.

If you enable passkeys or security keys on a public hostname, also set WEBAUTHN_RP_ID and WEBAUTHN_ALLOWED_ORIGINS in .env to match that hostname.

If you only want Cloudflare Tunnel access, do not leave port 3000 broadly exposed to the internet. Keep the host firewall closed or bind the published port more narrowly.

Import size variables

By default, Sure NDJSON imports are limited to a fixed maximum file size. Self-hosted admins can raise this limit with:

SURE_IMPORT_MAX_NDJSON_SIZE_MB=50

This applies to both the GUI upload and the API upload paths. If you do not set this variable, the default limit is used.

Market data provider variables

Sure supports multiple securities pricing providers. You can configure them through environment variables or in the UI under Settings > Self-Hosting. See market data providers for details on each provider.

# Comma-separated list of securities providers (e.g. yahoo_finance,tiingo,mfapi)
SECURITIES_PROVIDERS="yahoo_finance"

# Exchange rate provider (default: twelve_data)
EXCHANGE_RATE_PROVIDER="twelve_data"

# API keys (only needed for providers that require them)
TWELVE_DATA_API_KEY="your-key-here"
TIINGO_API_KEY="your-key-here"
EODHD_API_KEY="your-key-here"
ALPHA_VANTAGE_API_KEY="your-key-here"

Setting SECURITIES_PROVIDERS as an environment variable takes precedence over the UI setting. Leave it unset to manage providers from the UI only.

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

Restrict future signups

After creating your initial admin account, you can control how other people join your self-hosted instance from Settings > Self-Hosting > Onboarding.

• Open: Anyone can create an account from the registration page.
• Invite-only: Signups stay enabled, but a valid invite code is required.
• Closed: The registration page is disabled for new signups.

If you do not want additional self-service registrations, switch the instance to Closed after the initial setup.

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

Recommended images

• 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

2. Locate your backup file in the backup directory (e.g., /opt/sure-data/backups)

3. Restore the backup:

docker compose up -d db
docker compose exec -T db psql -U sure_user -d sure_production < /path/to/backup.sql

4. 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

SSL certificate configuration

For self-hosted environments using self-signed certificates or custom certificate authorities, Sure provides SSL configuration options.

Environment variables

Add these variables to your .env file:

SSL_CA_FILE=/path/to/ca-bundle.pem
SSL_VERIFY=true

SSL_CA_FILE: Path to a custom CA certificate bundle (PEM format). Use this when:

• Your environment uses self-signed certificates
• You need to trust a custom certificate authority
• Corporate proxies inject their own certificates

SSL_VERIFY: Controls SSL certificate verification (default: true)

• Set to false to disable SSL verification (not recommended for production)
• Only disable verification in development or testing environments

If you’re using a custom CA bundle, mount it into your containers in compose.yml:

services:
  web:
    volumes:
      - /path/to/your/ca-bundle.pem:/path/to/your/ca-bundle.pem:ro
  worker:
    volumes:
      - /path/to/your/ca-bundle.pem:/path/to/your/ca-bundle.pem:ro

Restart the application after updating your configuration:

docker compose restart web worker

Optional: SSL/TLS Configuration

Sure supports additional SSL/TLS configuration options for secure email delivery and API connections.

Custom CA Certificate

If you’re using a custom Certificate Authority (CA) or self-signed certificates, you can specify a CA file:

SSL_CA_FILE="/path/to/your/ca-certificate.pem"

This is useful when:

• Running Sure in a corporate environment with internal CAs
• Using self-signed certificates for development
• Connecting to services with custom certificate chains

Skip TLS Verification for Email

For development or testing environments, you can disable TLS verification for the email mailer:

SMTP_ENABLE_STARTTLS_AUTO=false
SMTP_TLS_VERIFY=false

Only disable TLS verification in development or trusted environments. In production, always use proper TLS verification to ensure secure email delivery.

When to use this:

• Development environments with self-signed certificates
• Testing email functionality locally
• Internal mail servers with custom certificates

Production recommendations:

• Always use valid SSL/TLS certificates in production
• Use the SSL_CA_FILE option instead of disabling verification
• Ensure your SMTP server supports STARTTLS

Mailer SSL configuration

For SMTP connections, additional SSL options are available:

SMTP_ENABLE_STARTTLS_AUTO=true
SMTP_OPENSSL_VERIFY_MODE=none

SMTP_ENABLE_STARTTLS_AUTO: Enable STARTTLS for SMTP connections (default: true)

SMTP_OPENSSL_VERIFY_MODE: SSL verification mode for SMTP

• none: Skip SSL verification
• peer: Verify the server certificate (default)

Security considerations

Disabling SSL verification (SSL_VERIFY=false or SMTP_OPENSSL_VERIFY_MODE=none) exposes your application to man-in-the-middle attacks. Only use these settings in trusted networks or development environments.

For production deployments:

• Use properly signed certificates from a trusted CA
• Keep SSL_VERIFY=true
• Use SMTP_OPENSSL_VERIFY_MODE=peer
• If you must use self-signed certificates, provide a CA bundle via SSL_CA_FILE

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.

Turning on Active Record encryption after first boot

Self-hosted Sure can derive Active Record encryption keys from SECRET_KEY_BASE automatically. If you prefer dedicated keys, you can add:

ACTIVE_RECORD_ENCRYPTION_PRIMARY_KEY=...
ACTIVE_RECORD_ENCRYPTION_DETERMINISTIC_KEY=...
ACTIVE_RECORD_ENCRYPTION_KEY_DERIVATION_SALT=...

If you add those keys after your instance already has data, the normal app startup path is not enough to rewrite older plaintext values:

• db:prepare still runs automatically on startup for schema setup and migrations.
• New writes use encryption after the app boots with the keys.
• Existing rows are not automatically re-encrypted.

Run the backfill task once after the app is up:

# Safe preview first (dry-run is the default)
docker compose exec web bin/rails security:backfill_encryption

# Perform the rewrite
docker compose exec web env DRY_RUN=false bin/rails security:backfill_encryption

The task is idempotent, so it is safe to rerun if needed.

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:

• Read the contributing guide
• Ask in the Discord
• Open an issue