Skip to content

Use a different Linux user after setup

How-toDeployrr v6.0+CurrentHost systemDockerInstall

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.

If you have not run Prerequisites > Environment yet, run Username again and enter the new name. Nothing else needs to change.

  1. Back up the Docker folder. See Backups.

  2. 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 as NEW_USER.

  3. Get the user’s numeric IDs:

    Terminal window
    id -u NEW_USER
    id -g NEW_USER
  4. Change four values in the .env file in your Docker folder: PUID (the first number), PGID (the second number), PRIMARY_USERNAME (the name) and USERDIR (/home/NEW_USER). Use Tools > .env Editor (Pro) or edit by hand. See Edit .env values and secrets and Edit by hand without Pro.

  5. Give the new user the same folders the old user had. Don’t run a recursive chown on appdata or 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/appdata
    sudo chown -R NEW_USER:NEW_USER DOCKER_FOLDER/compose DOCKER_FOLDER/logs
    sudo setfacl -m u:NEW_USER:rwX DOCKER_FOLDER
    sudo setfacl -dm u:NEW_USER:rwX DOCKER_FOLDER
    sudo setfacl -Rm u:NEW_USER:rwX DOCKER_FOLDER/appdata DOCKER_FOLDER/compose DOCKER_FOLDER/logs
    sudo setfacl -Rdm u:NEW_USER:rwX DOCKER_FOLDER/appdata DOCKER_FOLDER/compose DOCKER_FOLDER/logs

    These commands leave secrets and .env alone. 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 with sudo -u NEW_USER ls DOCKER_FOLDER.

  6. Run System Checks again.

  7. Recreate your apps so they read the new .env values. Use Tools > Stack Manager > Recreate and choose all (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.

  8. Open each app and check that it works. Cloud Commander, Double Commander and VS Code show your files under /data/NEW_USER now.

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:

Terminal window
sudo chown -R NEW_USER:NEW_USER DOCKER_FOLDER/appdata/APP

Don’t do this for apps that use fixed IDs, such as pgAdmin, Mosquitto and n8n. Restore from your backup if an app breaks.

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/rclone in 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.

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.

  1. Show the saved values. The file is root-only, so use sudo:

    Terminal window
    sudo grep -E '^(PUID|PGID|PRIMARY_USERNAME|USERDIR)=' DOCKER_FOLDER/.env

    They should match the new user.

  2. Open Prerequisites. The new username shows in green.

  3. System Checks shows DONE, and your apps start and write their files.

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.

  1. Check the current entries on the Docker folder:

    Terminal window
    getfacl DOCKER_FOLDER

    Look for user:OLD_USER:rw- and default:user:OLD_USER:rw-.

  2. 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_FOLDER
    sudo find DOCKER_FOLDER -type d -exec setfacl -x d:u:OLD_USER {} +

    This also clears the old entry from secrets and .env. It had no effect there, because those stay readable only by root.

  3. Run getfacl DOCKER_FOLDER again. The OLD_USER lines are gone. If you ran step 5 of After setup, the NEW_USER lines are still there.

  4. 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 APP with the app’s folder in appdata:

    Terminal window
    sudo setfacl -Rm u:OLD_USER:rwX DOCKER_FOLDER/appdata/APP

    Then 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.