Password Pusher releases new versions frequently. Upgrading is typically straightforward, with automatic database migrations and backwards-compatible changes.

Overview

Password Pusher is designed to be backwards compatible, and in most cases, no manual upgrade steps are required. The upgrade process typically involves:

  1. Pulling the new Docker image (or updating source code)
  2. Restarting the container/application
  3. Automatic database migrations (if needed)

Important: Always backup your data before upgrading, especially in production environments.

Before Upgrading

Backup Your Data

Important: Yes, mounted volumes must be backed up. Named volumes are stored in Docker’s volume directory (not on your host filesystem), so they won’t be included in regular host backups. They contain all your persistent data including the database and uploaded files.

Before upgrading, ensure you have backups of:

  • Storage volume - Contains the SQLite3 database (storage/db/production.sqlite3 or db/db.sqlite3 for older installations) and all uploaded files
  • Configuration - Environment variables, settings.yml, .env files

Backing Up the Storage Volume

The docker-compose.yml uses a single named volume (pwpush-storage) that contains both the database and file storage. Here are reliable backup methods:

Backup from within the running container - this is the most reliable method:

# Backup storage volume (contains database and files)
docker compose exec pwpush tar czf /tmp/storage-backup-$(date +%Y%m%d).tar.gz -C /opt/PasswordPusher storage

# Copy backup from container to host
docker compose cp pwpush:/tmp/storage-backup-$(date +%Y%m%d).tar.gz ./storage-backup-$(date +%Y%m%d).tar.gz

# Clean up backup file in container
docker compose exec pwpush rm /tmp/storage-backup-$(date +%Y%m%d).tar.gz

This single backup includes:

  • Database files (storage/db/production.sqlite3 or db/db.sqlite3)
  • All uploaded files
  • Any other data stored in the storage directory

Method 2: Using volumes-from (Container stopped)

If the container is stopped, use --volumes-from to access the same volumes:

# Get the container ID (works even if stopped)
CONTAINER_ID=$(docker compose ps -q pwpush)

# Backup storage volume
docker run --rm \
  --volumes-from $CONTAINER_ID \
  -v $(pwd):/backup \
  alpine tar czf /backup/storage-backup-$(date +%Y%m%d).tar.gz -C /opt/PasswordPusher storage

Method 3: Using actual volume name

If you know the actual volume name (with Docker Compose prefix), you can mount it directly:

# First, find the actual volume name
docker volume ls | grep pwpush

# Backup using the actual volume name (replace with your actual volume name)
docker run --rm \
  -v pwpush_pwpush-storage:/opt/PasswordPusher/storage \
  -v $(pwd):/backup \
  alpine tar czf /backup/storage-backup-$(date +%Y%m%d).tar.gz -C /opt/PasswordPusher storage

Note: Docker Compose prefixes volume names with the project name (usually the directory name). The volume defined as pwpush-storage in docker-compose.yml is actually created as pwpush_pwpush-storage (or similar, depending on your project name). Method 1 (docker compose exec) is recommended as it automatically uses the correct volume and path.

Backing Up Bind Mounts

If you’re using bind mounts (host paths) instead of named volumes, backup the host directory directly:

# Backup storage directory (replace with your actual path)
tar czf storage-backup-$(date +%Y%m%d).tar.gz /host/path/to/storage

To check which method you’re using:

# View your docker-compose.yml volumes section
grep -A 3 "volumes:" docker-compose.yml

# Or check running container mounts
docker compose ps
docker inspect $(docker compose ps -q pwpush) | grep -A 10 Mounts

Check Release Notes

Review the GitHub releases page for:

  • Breaking changes
  • Deprecation notices
  • Required migration steps
  • New features or configuration options

Upgrading with Docker Compose

If you’re using docker-compose.yml, upgrading is straightforward:

Step 1: Pull the Latest Image

Pull the updated Docker image:

docker compose pull

This downloads the latest image for the tag specified in your docker-compose.yml (typically stable or latest).

Step 2: Stop the Current Container

Stop the running container:

docker compose down

Note: If you’re using named volumes (as recommended in docker-compose.yml), your data will persist. The down command only stops and removes containers, not volumes.

Step 3: Start with the New Image

Start the container with the updated image:

docker compose up -d

The container will:

  • Start with the new image
  • Automatically run database migrations (if needed)
  • Restart the application

Step 4: Verify the Upgrade

Check that the container is running and healthy:

# Check container status
docker compose ps

# View logs for any errors
docker compose logs -f pwpush

# Test the health endpoint
curl http://localhost:5100/up

Complete Upgrade Command Sequence

For a complete upgrade in one sequence:

# Pull latest image, stop old container, start new container
docker compose pull && docker compose down && docker compose up -d

# Check logs
docker compose logs -f pwpush

Updating to a Specific Version

If you want to upgrade to a specific version instead of stable or latest:

  1. Edit docker-compose.yml and change the image tag: 
    services:
  pwpush:
    image: docker.io/pglombardo/pwpush:v1.53.0  # Specific version
  2. Pull and restart: 
    docker compose pull
docker compose down
docker compose up -d

Switching Between Tags

To switch from a versioned tag to stable or latest:

  1. Edit docker-compose.yml: 
    services:
  pwpush:
    image: docker.io/pglombardo/pwpush:stable  # or :latest
  2. Pull and restart: 
    docker compose pull
docker compose down
docker compose up -d

Upgrading with Docker Run

If you’re using docker run directly:

Using stable or latest Tags

If you’re using the stable or latest tag, pull the updated image and restart:

# Pull the latest image
docker pull pglombardo/pwpush:stable

# Stop and remove the old container
docker stop <container-name>
docker rm <container-name>

# Start a new container with the same configuration
docker run -d \
  --name pwpush \
  -p "80:80" -p "443:443" \
  -v pwpush-storage:/opt/PasswordPusher/storage \
  --env PWPUSH_MASTER_KEY='your-key' \
  pglombardo/pwpush:stable

Using Versioned Tags

If you’re using a versioned tag (e.g., v1.53.0):

Option 1: Update to a newer versioned tag

docker pull pglombardo/pwpush:v1.54.0
docker stop <container-name>
docker rm <container-name>
# Start with new version tag

Option 2: Switch to stable or latest

docker pull pglombardo/pwpush:stable
docker stop <container-name>
docker rm <container-name>
# Start with stable tag

Database Migrations

Password Pusher automatically runs database migrations on container startup. No manual intervention is required.

How it works:

  • On container start, the entrypoint script checks for pending migrations
  • Migrations are applied automatically
  • The application starts only after migrations complete successfully

Migration Logs: Check migration status in container logs:

docker compose logs pwpush | grep -i migration

Note: For large databases, migrations may take a few minutes. The container health check allows extra time for this.

Deprecation Notices

In rare cases, deprecation notices may appear in application logs or Docker container logs. These indicate that:

  • A feature or functionality is being removed
  • The feature will no longer be supported in future releases
  • You should migrate away from the deprecated feature

What to do:

  1. Review the deprecation notice in the logs
  2. Check the release notes for migration instructions
  3. Update your configuration or usage before the feature is removed

Troubleshooting Upgrades

Container Won’t Start

Symptoms: Container exits immediately or fails to start.

Solutions:

  1. Check logs: 
    docker compose logs pwpush

  2. Verify database connectivity: Ensure database is accessible and credentials are correct

  3. Check migration errors: Look for database migration failures in logs

  4. Verify volumes: Ensure volumes are properly mounted and accessible

Database Migration Errors

Symptoms: Migration fails, container won’t start.

Solutions:

  1. Check database permissions: Ensure the database user has necessary permissions

  2. Review migration logs: Look for specific error messages

  3. Restore from backup: If migration fails, restore from backup and check release notes

  4. Check database version: Some migrations may require specific database versions

Data Not Appearing After Upgrade

Symptoms: Data seems missing after upgrade.

Solutions:

  1. Verify volume: Check that the storage volume is properly mounted: 
    docker compose ps
docker volume inspect pwpush-storage
# Or check the actual volume name with prefix
docker volume ls | grep pwpush
  2. Check database path: The database may be in storage/db/production.sqlite3 (new) or db/db.sqlite3 (old). Verify which path is being used: 
    docker compose exec pwpush ls -la /opt/PasswordPusher/storage/db/
docker compose exec pwpush ls -la /opt/PasswordPusher/db/

  3. Check database connection: Verify DATABASE_URL is correct or let it auto-detect

  4. Review logs: Look for database connection errors in container logs

Health Check Failing

Symptoms: Container reports unhealthy status.

Solutions:

  1. Check startup time: Large databases may need more time for migrations
    • Increase start_period in healthcheck if needed
  2. Custom themes: If you’re using a custom theme (PWP__THEME), asset precompilation during startup can significantly increase boot time
    • Increase start_period in healthcheck to allow time for asset compilation
    • Asset precompilation typically adds 30-60 seconds to startup time
  3. Verify application is running: 
    docker compose exec pwpush curl http://localhost:5100/up
  4. Check resource limits: Ensure container has sufficient CPU/memory

Best Practices

Version Management

Recommended: Use the stable tag for production deployments:

  • Receives security updates and bug fixes
  • More stable than latest
  • Still gets regular updates

Alternative: Use specific version tags (e.g., v1.53.0) for:

  • Maximum control over when to upgrade
  • Testing specific versions before upgrading
  • Compliance requirements

Not Recommended: Using latest in production:

  • May include breaking changes from development
  • Less predictable upgrade path

Upgrade Schedule

  • Production: Test upgrades in staging first, then upgrade during maintenance windows
  • Development: Upgrade more frequently to test new features
  • Security Updates: Apply security updates promptly

Monitoring After Upgrade

After upgrading, monitor:

  • Application logs for errors or warnings
  • Container health status
  • Database migration completion
  • User-reported issues
  • Performance metrics

Release Information

GitHub Releases

All releases are published on the Password Pusher GitHub repository.

Release History

A comprehensive list of past and current releases is available on the GitHub releases page.

Docker Tags

Available Docker tags:

  • stable - Recommended for production (updated with stable releases)
  • latest - Latest release (may include development changes)
  • vX.Y.Z - Specific version tags (e.g., v1.53.0)

For more information, see the Docker Tags Reference.

See Also

Updated: