Use a different Linux user after setup
Use this page if you want Deployrr to run as a different Linux user than the one you set up with, or if System Checks shows Username YOUR_USERNAME not found because the user was renamed. See Fix “Username not found” for the other causes of that message.
Prerequisites > Username only saves a name. It does not change anything you set up earlier. Your Docker folder, your apps and a few other steps keep the old user until you update them.
The simplest choice is to keep the user you set up with. Change it only if you have to.
In the commands below, NEW_USER, OLD_USER and DOCKER_FOLDER are values you fill in. DOCKER_FOLDER is the path to your Docker folder.
Before Environment
Section titled “Before Environment”If you have not run Prerequisites > Environment yet, run Username again and enter the new name. Nothing else needs to change.
After setup
Section titled “After setup”-
Back up the Docker folder. See Backups.
-
Go to Prerequisites > Username and enter the new name. Deployrr refuses
root. If the user does not exist, it asks “Do you want to create this user and add it to sudoers?”. You see “Username set to NEW_USER”, or “User NEW_USER has been created” if Deployrr created it. From now on, start Deployrr asNEW_USER. -
Get the user’s numeric IDs:
Terminal window id -u NEW_USERid -g NEW_USER -
Change four values in the
.envfile in your Docker folder:PUID(the first number),PGID(the second number),PRIMARY_USERNAME(the name) andUSERDIR(/home/NEW_USER). Use Tools > .env Editor (Pro) or edit by hand. See Edit .env values and secrets and Edit by hand without Pro. -
Give the new user the same folders the old user had. Don’t run a recursive
chownonappdataor the whole Docker folder. Some apps, such as pgAdmin, Mosquitto and n8n, own their folders with fixed IDs, and you would break them.Terminal window sudo chown NEW_USER:NEW_USER DOCKER_FOLDER DOCKER_FOLDER/appdatasudo chown -R NEW_USER:NEW_USER DOCKER_FOLDER/compose DOCKER_FOLDER/logssudo setfacl -m u:NEW_USER:rwX DOCKER_FOLDERsudo setfacl -dm u:NEW_USER:rwX DOCKER_FOLDERsudo setfacl -Rm u:NEW_USER:rwX DOCKER_FOLDER/appdata DOCKER_FOLDER/compose DOCKER_FOLDER/logssudo setfacl -Rdm u:NEW_USER:rwX DOCKER_FOLDER/appdata DOCKER_FOLDER/compose DOCKER_FOLDER/logsThese commands leave
secretsand.envalone. They stay owned by root and readable only by root.If your Docker folder is inside the old user’s home, for example
/home/OLD_USER/docker, the new user may not be allowed into that home folder. Check withsudo -u NEW_USER ls DOCKER_FOLDER. -
Run System Checks again.
-
Recreate your apps so they read the new
.envvalues. Use Tools > Stack Manager > Recreate and chooseall(Basic, Plus or Pro license). Without a license, use the Docker Compose command on that page. See Which one after which change. Restart does not pick up the change. -
Open each app and check that it works. Cloud Commander, Double Commander and VS Code show your files under
/data/NEW_USERnow.
If one app can’t write its files after this, give that app’s folder to the new user. Replace APP with the app’s name:
sudo chown -R NEW_USER:NEW_USER DOCKER_FOLDER/appdata/APPDon’t do this for apps that use fixed IDs, such as pgAdmin, Mosquitto and n8n. Restore from your backup if an app breaks.
Other steps that keep the old user
Section titled “Other steps that keep the old user”Redo these only if you use them:
- Bash Aliases are in the old user’s
~/.bashrc. With Username set to the new user, run Bash Aliases again (Basic, Plus or Pro license). It writes to the new user’s~/.bashrc, whoever you are logged in as. Then open a new session as the new user. See Turn on the aliases. - The Rclone mount runs as the old user. Its config is in
appdata/rclonein your Docker folder. The old user’s home only holds a link to it. Remove the mount service and run Automount again. See Change the mount folder, cache or NAS details. - Mail Relay maps the old user to your FROM address. Run System > Mail Relay again. See Change your SMTP details later.
- A Migration Package needs the same user on the new server. See Move to a new server.
Renaming the user
Section titled “Renaming the user”Deployrr expects the user’s home folder to be /home/USERNAME. The default Docker folder is inside it, at /home/USERNAME/docker. If you rename the user and move the home folder, the Docker folder moves too. Deployrr then looks for it in the wrong place.
If your Docker folder is in the old user’s home, don’t rename the user. Keep the old user, or create a new user and switch to it with the steps above. The Docker folder stays where it is.
Check it worked
Section titled “Check it worked”-
Show the saved values. The file is root-only, so use
sudo:Terminal window sudo grep -E '^(PUID|PGID|PRIMARY_USERNAME|USERDIR)=' DOCKER_FOLDER/.envThey should match the new user.
-
Open Prerequisites. The new username shows in green.
-
System Checks shows
DONE, and your apps start and write their files.
Remove the old user’s access (optional)
Section titled “Remove the old user’s access (optional)”When Deployrr created your Docker folder, it gave the old user read and write access to it with ACLs (access control lists). New files and folders inside get the same access. The commands above add access for the new user but don’t remove the old user’s access. If you are retiring the old account, remove it too.
Do this only after everything works as the new user, including the other steps you use. Skip it if your Docker folder is in the old user’s home and you keep that account.
-
Check the current entries on the Docker folder:
Terminal window getfacl DOCKER_FOLDERLook for
user:OLD_USER:rw-anddefault:user:OLD_USER:rw-. -
Remove the old user’s entries from every file and folder, then the default entries from every folder:
Terminal window sudo setfacl -R -x u:OLD_USER DOCKER_FOLDERsudo find DOCKER_FOLDER -type d -exec setfacl -x d:u:OLD_USER {} +This also clears the old entry from
secretsand.env. It had no effect there, because those stay readable only by root. -
Run
getfacl DOCKER_FOLDERagain. TheOLD_USERlines are gone. If you ran step 5 of After setup, theNEW_USERlines are still there. -
Open a few apps and check that they still work. If one breaks, give the old user access to that app’s folder again first. Replace
APPwith the app’s folder inappdata:Terminal window sudo setfacl -Rm u:OLD_USER:rwX DOCKER_FOLDER/appdata/APPThen restart the app. Restore the folder from your backup only as a last resort: the backup is from before the switch, so anything the app saved since then is lost.

