Release notes

Upgrading from v3.1.x #

This release has no breaking changes for existing installs. Update as usual:

docker compose pull
docker compose up -d

Here is what happens automatically on first start:

• User migration - existing accounts from users.json are automatically migrated into a new SQLite database (config/better_auth.sqlite). All passwords continue to work.
• New SQLite file - config/better_auth.sqlite is created inside your existing config volume. No volume change needed.

Recommended: rename environment variables #

The authentication library changed from next-auth to better-auth. The old variable names still work as-is, but renaming them is recommended for clarity:

Note for fresh installs #

On a fresh install (no existing users.json), BorgWarehouse now redirects to /setup to create the admin account. The old default credentials (admin / admin) are no longer used.

What’s new #

• OAuth / OIDC sign-in - GitHub, Google, Microsoft, GitLab, and any OIDC provider. See the documentation →
• Session management - configurable session lifetime, session revocation script.
• Webhook notifications - built-in HTTP webhook alerts, no Apprise needed.
• Manual refresh button - trigger status & storage refresh from the UI without waiting for cron.
• Date format preference - users can choose their preferred date display format.
• Supercronic cron example - docker-compose.yml now includes a ready-to-use commented cron service.

Previous versions required the Docker image to be built with a specific UID and GID baked in at compile time. The official image on Docker Hub was built with 1001:1001, which meant anyone running a different user on their host had to rebuild the image themselves.

Starting with this version, the container handles user mapping at runtime. You set PUID and PGID in your .env file, and the container remaps its internal user to match on startup. No rebuild needed.

What you need to do #

1. Update your .env file - replace UID / GID with PUID / PGID:

- UID=1001
- GID=1001
+ PUID=1001
+ PGID=1001

2. Update your docker-compose.yml - remove the user: line and build args:

  borgwarehouse:
    container_name: borgwarehouse
-   build:
-     context: .
-     dockerfile: Dockerfile
-     args:
-       - UID=${UID}
-       - GID=${GID}
    image: borgwarehouse/borgwarehouse
-   user: '${UID}:${GID}'

3. Check volume permissions - host directories must be owned by PUID:PGID:

ls -ln ./config ./ssh ./ssh_host ./repos
# fix if needed:
chown -R YOUR_PUID:YOUR_PGID ./config ./ssh ./ssh_host ./repos

4. Reset your sshd_config - the old file has an outdated PidFile path:

rm ./ssh_host/sshd_config

5. Pull and restart:

docker compose pull
docker compose up -d

If something goes wrong, check the logs:

docker logs borgwarehouse

Breaking changes #

• API rewrite - fully REST compliant and idempotent. Check the API documentation and update your integrations.
• Repository identifier - repository name is now used instead of ID in all API endpoints.
• Cron endpoints renamed:
  • /api/cronjob/checkStatus → /api/v1/cron/status
  • /api/cronjob/getStorageUsed → /api/v1/cron/storage

Core changes #

• One unix user is now used for all backups. BorgWarehouse now complies with BorgBackup documentation recommendations.
• sudo permissions are no longer required at all.
• Repositories are now all in the same root folder.
• Inside repo.json, the repository key is replaced by repositoryName.
• All SSH public keys must be unique. BorgWarehouse will warn you if you try to use an already used key.
• All environment variables are now runtime variables (buildtime variables removed for Docker compatibility).

Features #

• 100% ready for Docker 🚀
• Added robots.txt.
• History of repo.json is now logged in config/versions/.

There is no automatic migration from v1 to v2. A manual migration guide will be added in a future update.