By default, Password Pusher uses a persistent SQLite3 database stored in Docker volumes. However, there are scenarios where you want an ephemeral (temporary, non-persistent) database that is automatically discarded when the container stops or is removed.

What is an Ephemeral Database?

Ephemeral meaning: transitory, transient, fleeting, passing, short-lived, momentary, brief, short, cursory, temporary, impermanent, short-term; fading, evanescent, fugitive, fly-by-night. ANTONYMS long-lived, permanent.

An ephemeral database is stored entirely within the container’s filesystem and is not mounted to a Docker volume or host directory. When the container stops or is removed, all database data is permanently deleted.

Use Cases

Ephemeral databases are ideal for:

  • Security conferences and meetups - Temporary sharing setups where you want all data automatically deleted after the event
  • Demonstrations and presentations - Quick demos where you don’t want to leave any trace of shared secrets
  • Testing and development - Clean slate testing environments that reset on each container restart
  • Temporary sharing services - Short-term password sharing where data privacy is paramount
  • Workshops and training - Educational sessions where you want to ensure no sensitive data persists
  • One-time events - Conferences, hackathons, or temporary collaboration spaces

Warning: All data (pushes, users, settings) will be permanently deleted when the container stops or is removed. This cannot be reversed. Use only when you intentionally want temporary, disposable data storage.

How It Works

By default, the docker-compose.yml file mounts a persistent volume:

volumes:
  - pwpush-storage:/opt/PasswordPusher/storage  # This persists data

To make the database ephemeral, you need to:

  1. Remove the storage volume mount - Don’t mount any volume to the database location
  2. Ensure database is in container filesystem - The database will be stored inside the container
  3. Accept data loss on restart - All data is discarded when the container stops

Configuration

Using Docker Compose

To create an ephemeral database setup, remove or comment out the storage volume mount:

services:
  pwpush:
    image: docker.io/pglombardo/pwpush:stable
    restart: unless-stopped
    ports:
      - "80:80"
      - "443:443"
    # NO volumes section - database will be ephemeral
    environment:
      PWPUSH_MASTER_KEY: 'your-encryption-key-here'
      # Optional: Explicitly set database location inside container
      # DATABASE_URL: "sqlite3:db/db.sqlite3"

Complete ephemeral example:

services:
  pwpush:
    image: docker.io/pglombardo/pwpush:stable
    restart: unless-stopped
    ports:
      - "80:80"
      - "443:443"
    environment:
      PWPUSH_MASTER_KEY: 'your-encryption-key-here'
      TLS_DOMAIN: 'pwpush.example.com'
      # No volumes = ephemeral database

Note: If you need to persist file uploads but want an ephemeral database, you can mount only the file storage directory (not the database directory). However, this is an advanced configuration and not recommended for most use cases.

Using Docker Run

For docker run, simply don’t include any volume mounts for the database:

docker run -d \
  --name pwpush \
  -p "80:80" \
  -p "443:443" \
  -e PWPUSH_MASTER_KEY='your-encryption-key-here' \
  -e TLS_DOMAIN='pwpush.example.com' \
  pglombardo/pwpush:stable

With explicit database location:

docker run -d \
  --name pwpush \
  -p "80:80" \
  -p "443:443" \
  -e PWPUSH_MASTER_KEY='your-encryption-key-here' \
  -e DATABASE_URL='sqlite3:db/db.sqlite3' \
  pglombardo/pwpush:stable

Database Location

The database will be stored inside the container at:

  • Default location: /opt/PasswordPusher/storage/db/production.sqlite3

You can explicitly set the database location using DATABASE_URL:

environment:
  DATABASE_URL: "sqlite3:db/db.sqlite3"  # Inside container, not mounted

SQLite3 Database Files

When using an ephemeral database, these files are created inside the container and deleted when it stops:

  • .sqlite3 file: The core SQLite3 database file
  • .wal files: Write-ahead logging files for database consistency
  • .shm files: Shared memory files for multi-process access

All of these files are stored in the container’s filesystem and are discarded when the container is removed.

Data Lifecycle

Container Restart

When you restart the container (docker compose restart or docker restart), the data may persist if the container filesystem is preserved. However, this is not guaranteed and depends on Docker’s container lifecycle.

Container Stop and Remove

When you stop and remove the container:

docker compose down
# or
docker stop pwpush && docker rm pwpush

All database data is permanently deleted and cannot be recovered.

Container Recreate

When you recreate the container (pull new image, update configuration):

docker compose up -d --force-recreate

All database data is permanently deleted and a fresh database is created.

Best Practices

Security Considerations

  • Encryption keys: Even with ephemeral databases, ensure PWPUSH_MASTER_KEY is properly configured for encrypted pushes
  • TLS/SSL: Use TLS_DOMAIN for automatic certificate provisioning to protect data in transit
  • Container isolation: Ensure containers are properly isolated from other services

Operational Practices

  • Document the ephemeral nature: Clearly document that data is temporary
  • Set expectations: Inform users that data will be lost on container restart
  • Regular backups (if needed): If you need to preserve specific data, export it before container removal
  • Monitoring: Monitor container health to avoid unexpected restarts that would cause data loss

When to Use Ephemeral vs Persistent

Use Ephemeral when:

  • Temporary events (conferences, meetups, demos)
  • Testing and development
  • Maximum privacy is required
  • Data should not persist beyond session

Use Persistent when:

  • Production deployments
  • Long-term usage
  • User accounts and history are needed
  • Data recovery is important

Troubleshooting

Data Persists When It Shouldn’t

Symptoms: Data remains after container restart when it should be ephemeral.

Solutions:

  1. Check for volume mounts: 
    docker compose config | grep -A 5 volumes
# or
docker inspect <container_id> | grep -A 10 Mounts

  2. Verify no storage volumes: Ensure no volumes are mounted to /opt/PasswordPusher/storage or /opt/PasswordPusher/db

  3. Check Docker Compose file: Review your docker-compose.yml to ensure the volumes: section is removed or commented out

Container Won’t Start

Symptoms: Container fails to start with ephemeral configuration.

Solutions:

  1. Check logs: 
    docker compose logs pwpush

  2. Verify database path: Ensure DATABASE_URL points to a valid path inside the container

  3. Check permissions: The container user should have write permissions to the database directory

Unexpected Data Loss

Symptoms: Data disappears unexpectedly.

Solutions:

  1. Check container status: Verify the container wasn’t recreated 
    docker compose ps

  2. Review restart policy: Check if restart: unless-stopped is causing unexpected restarts

  3. Verify configuration: Ensure you intended ephemeral behavior and didn’t accidentally remove volume mounts

Complete Example

Here’s a complete docker-compose.yml for an ephemeral setup suitable for a security conference:

services:
  pwpush:
    image: docker.io/pglombardo/pwpush:stable
    restart: unless-stopped
    ports:
      - "80:80"
      - "443:443"
    environment:
      # Required: Encryption key
      PWPUSH_MASTER_KEY: 'your-generated-encryption-key-here'

      # Optional: Automatic TLS
      TLS_DOMAIN: 'pwpush.conference.example.com'

      # Optional: Explicit ephemeral database location
      DATABASE_URL: "sqlite3:db/db.sqlite3"

      # Optional: Customize expiration defaults for temporary use
      PWP__PW__EXPIRE_AFTER_DAYS_DEFAULT: "1"
      PWP__PW__EXPIRE_AFTER_VIEWS_DEFAULT: "1"

    # NO volumes section = ephemeral database
    # All data will be lost when container stops or is removed

To start:

docker compose up -d

To completely remove all data:

docker compose down -v  # -v removes any volumes (if accidentally created)

See Also

Updated: