Change a database password safely
Some apps come with their own MariaDB or PostgreSQL container. A database image sets its password only the first time it starts. If you change the password in .env or in a secret file, the password stored inside the database stays the same. The app then can’t log in. This page shows the safe order: change it inside the database first, then in your files, then recreate.
Before you start
Section titled “Before you start”- The app uses its own database container. It is named
APP-mariadborAPP-postgresql, for exampleimmich-postgresql. The standalone database apps are covered below the tables. Runsudo docker psto check. - You know where the app keeps its database password. Use the tables below.
- You have a few minutes where the app can be down.
Find your app
Section titled “Find your app”YOUR_DOCKER_FOLDER is the path to your Docker folder. HOSTNAME is your server’s hostname. See Docker folder layout. The database user and name are in YOUR_DOCKER_FOLDER/compose/HOSTNAME/APP-postgresql.yml or APP-mariadb.yml, on the POSTGRES_USER, POSTGRES_DB or MARIADB_USER lines.
PostgreSQL apps
Section titled “PostgreSQL apps”| App | Container | User | Database | Password kept in |
|---|---|---|---|---|
| Immich | immich-postgresql |
immich_db_user |
immich |
.env: IMMICH_POSTGRESQL_PASSWORD |
| Autobrr | autobrr-postgresql |
autobrr_db_user |
autobrr |
.env: AUTOBRR_POSTGRESQL_PASSWORD |
| GameVault | gamevault-postgresql |
gamevault_db_user |
gamevault |
.env: GAMEVAULT_POSTGRESQL_PASSWORD |
| Flowise | flowise-postgresql |
flowise_db_user |
flowise |
.env: FLOWISE_POSTGRESQL_PASSWORD |
| PdfDing | pdfding-postgresql |
pdfding_db_user |
pdfding |
.env: PDFDING_POSTGRESQL_PASSWORD |
| Dockhand | dockhand-postgresql |
dockhand_db_user |
dockhand |
.env: DOCKHAND_POSTGRESQL_PASSWORD |
| Authentik | authentik-postgresql |
authentik_db_user |
authentik |
secret: authentik_postgresql_password. Recreate both authentik and authentik-worker in step 5 |
| n8n | n8n-postgresql |
n8n_db_user |
n8n |
secret n8n_postgresql_password and the app’s compose file |
MariaDB apps
Section titled “MariaDB apps”| App | Container | User | Password kept in |
|---|---|---|---|
| Paperless-ngx | paperless-ngx-mariadb |
paperlessngx_db_user |
.env: PAPERLESSNGX_MARIADB_PASSWORD. Root: PAPERLESSNGX_MARIADB_ROOT_PASSWORD |
| Guacamole | guacamole-mariadb |
guacamole_db_user |
.env: GUACAMOLE_MARIADB_PASSWORD. Root: GUACAMOLE_MARIADB_ROOT_PASSWORD |
| Vikunja | vikunja-mariadb |
vikunja_db_user |
.env: VIKUNJA_MARIADB_PASSWORD. The same value is also the root password |
| BookStack | bookstack-mariadb |
bookstack_db_user |
.env: BOOKSTACK_MARIADB_PASSWORD. The same value is also the root password |
| Speedtest Tracker | speedtest-tracker-mariadb |
root (the app logs in as root) |
.env: SPEEDTEST_MARIADB_ROOT_PASSWORD |
| Nextcloud | nextcloud-mariadb |
nextcloud_db_user |
secrets: nextcloud_mariadb_password. Root: nextcloud_mariadb_root_password. Also config.php |
Dockhand also uses its password inside a connection URL, so use only letters and digits there.
The standalone database apps work the same way, with these names in steps 1, 3 and 5:
- MariaDB: container
mariadb, userroot, secretmariadb_root_password. - PostgreSQL: container
postgresql, the user you typed at the “Default PostgreSQL User” prompt (defaultpostgres), databasepostgres, secretpostgres_default_password.
-
Back up. Replace
YOUR_DOCKER_FOLDERandAPPand run each line:Terminal window sudo cp YOUR_DOCKER_FOLDER/.env YOUR_DOCKER_FOLDER/.env.baksudo cp -a YOUR_DOCKER_FOLDER/secrets YOUR_DOCKER_FOLDER/secrets.baksudo cp -a YOUR_DOCKER_FOLDER/appdata/APP-postgresql YOUR_DOCKER_FOLDER/appdata/APP-postgresql.bakUse the
APP-mariadbfolder for a MariaDB app. For a copy that is fully consistent, stop the database container first withsudo docker stop APP-postgresql, copy, then start it again. Also copy the app’s compose file fromcompose/HOSTNAME. For a bigger backup, see Back up and restore your Docker folder. -
Make a new password with letters and digits only:
Terminal window openssl rand -hex 24Copy the result. Characters such as
$,;and&can break.envvalues and connection URLs. See Edit .env values and secrets. -
Change the password inside the running database. Pick the block for your database type.
PostgreSQL. Replace
APP,DB_USER,DB_NAMEandNEW_PASSWORD. Keep the single quotes around the password:Terminal window sudo docker exec -it APP-postgresql psql -U DB_USER -d DB_NAME -c "ALTER USER DB_USER WITH PASSWORD 'NEW_PASSWORD';"It asks for no password. You should see
ALTER ROLE.MariaDB. Log in as root. Type the current root password from
.envor the root secret file when asked:Terminal window sudo docker exec -it APP-mariadb mariadb -u root -pAt the
MariaDB [(none)]>prompt, run:ALTER USER 'DB_USER'@'%' IDENTIFIED BY 'NEW_PASSWORD';FLUSH PRIVILEGES;Type
exitto leave.- To change the root password, do it last. Run
ALTER USER 'root'@'%' IDENTIFIED BY 'NEW_PASSWORD';andALTER USER 'root'@'localhost' IDENTIFIED BY 'NEW_PASSWORD';. - For Vikunja and BookStack, one value is both the user password and the root password. Change the user first, then root, both to the same new value.
- For Speedtest Tracker and the standalone MariaDB app, the password is the root password. Change root.
- To change the root password, do it last. Run
-
Put the same new value where the app keeps it (see the tables). Do not skip this. The next step reads these files.
.env: use the .env Editor, or edit the file by hand. See Edit .env values and secrets.- Secret file: use the Secrets Editor, or edit the file by hand. A secret file holds only the value.
- n8n: also open
YOUR_DOCKER_FOLDER/compose/HOSTNAME/n8n.ymland replace the value ofDB_POSTGRESDB_PASSWORDwith the new password. - Nextcloud: also open
YOUR_DOCKER_FOLDER/appdata/nextcloud/config/config.phpand replace thedbpasswordvalue. Nextcloud keeps a copy of the database password there after its first setup. This is how Nextcloud works, not something you can skip.
-
Recreate the app, then its database container. A plain restart does not read new values, and Manage Apps has no Recreate. Go to Tools > Stack Manager > Recreate (needs a Basic, Plus or Pro license). Under “Select an app to recreate:”, type the number of the app’s container. Run it again for the database container, and for Authentik also for
authentik-worker. See Stack Manager. Or, with the Deployrr bash aliases, run these. ReplaceAPPwith the app name:Terminal window dcrec APPdcrec APP-postgresqlUse
APP-mariadbfor a MariaDB app. See Restart, Recreate or Reinstall an app after a change.
Check it worked
Section titled “Check it worked”-
Open the app and sign in. Your data should still be there.
-
Read the app’s recent log lines. With the Deployrr bash aliases,
dlogs APPshows the last 50 lines and keeps following; press Ctrl+C to stop. Without them:Terminal window sudo docker logs APP --tail 50 -
Look for login errors, such as
password authentication failed for user(PostgreSQL) orAccess denied for user(MariaDB). If you see one, the value in your files and the value in the database don’t match. Fix the file, or run step 3 again with the value that is in the file. Then recreate the app.
To undo, run step 3 again with the old password, put the old value back in the files, and recreate. If the data is damaged, stop the app and restore your copy of the database folder.

