# Update Psono Pwned Passwords

The API Docker image and the password database are updated separately. The published database is updated only once a week. An API container with a local database never checks for or downloads database updates on startup.

# Update the database

Check before downloading

Always compare the published SHA-256 checksum with your existing database before downloading another copy. If the checksums match, do not download it again. The database is updated only once a week, and downloading the same large file again wastes bandwidth for your installation and Psono's download service.

Run these commands as root on the Docker host with curl and sha256sum installed. Allow space for two complete copies of the database while staging an update.

# 1. Check the published SHA-256

Request only the HTTP headers:

curl --fail --silent --show-error --head \
  https://storage.googleapis.com/static.psono.com/psono/psono-pwned-passwords/passwords.sqlite

Find the x-goog-meta-sha256 header. Its value is the SHA-256 checksum of the published SQLite file. This request does not download the database.

Calculate the checksum of your local database:

sha256sum /opt/docker/psono-pwned-passwords/passwords.sqlite

Compare the first value printed by sha256sum with x-goog-meta-sha256:

  • Same checksum: your database is current. Stop here; do not download it again.
  • Different checksum: a different published database is available. Continue below.

Calculating the local checksum reads your local file, but uses no download bandwidth.

# 2. Download the new database

curl --fail --location \
  --output /opt/docker/psono-pwned-passwords/passwords.sqlite.download \
  https://storage.googleapis.com/static.psono.com/psono/psono-pwned-passwords/passwords.sqlite

The API can continue using its existing database during the download. Wait for the transfer to finish successfully before proceeding. The .download file keeps the new database separate from the database in use.

# 3. Install the downloaded database

After the download finishes successfully, stop the API, replace the database, and start it again:

docker stop psono-pwned-passwords &&
mv /opt/docker/psono-pwned-passwords/passwords.sqlite.download \
   /opt/docker/psono-pwned-passwords/passwords.sqlite &&
docker start psono-pwned-passwords

Do not overwrite or replace the database while the API is running. The installation guide mounts the directory read-only, so the restarted process opens the newly installed file.

# 4. Check the service

curl --fail http://127.0.0.1:10600/healthcheck/
curl --fail https://pwned.example.com/range/5baa6
docker logs psono-pwned-passwords

# Update the Docker image

  1. Pull the current API image:

    docker pull psono/psono-pwned-passwords:latest
    
  2. Stop the existing container:

    docker stop psono-pwned-passwords
    
  3. Start the updated container with the existing database:

    docker run --name psono-pwned-passwords-new \
      -v /opt/docker/psono-pwned-passwords:/data:ro \
      -d --restart=unless-stopped \
      -p 127.0.0.1:10600:80 \
      psono/psono-pwned-passwords:latest
    

    Include any additional options from your original container.

  4. Verify the healthcheck, HTTPS range endpoint, and breach detection in the webclient. Then remove the old container and rename the new one:

    docker rm psono-pwned-passwords
    docker rename psono-pwned-passwords-new psono-pwned-passwords
    

If validation fails, remove the new container and start the previous container again. The database remains in the mounted host directory throughout the image update.