Docker Compose PUID PGID 설정 이유와 올바른 사용법
PUID와 PGID는 Docker 설정이 아닌 linuxserver.io 이미지의 관례입니다. 바인드 마운트 파일이 911:911 권한으로 생성되는 원인을 분석하고, id -u 및 id -g 명령어로 호스트의 정확한 사용자 ID를 확인하여 권한 문제를 해결하는 방법을 설명합니다.
PUID와 PGID의 실제 의미
PUID와 PGID는 특정 컨테이너 이미지가 시작 시점에 읽어 들이는 두 개의 환경 변수입니다. Docker 자체는 이 변수들을 확인하지 않습니다. 이는 linuxserver.io 이미지와 일부 다른 이미지에서 사용하는 관례일 뿐이며, 이를 읽도록 작성되지 않은 이미지는 해당 변수를 무시합니다.
linuxserver.io 이미지 내부에는 빌드 시점에 UID(사용자 ID) 911과 GID(그룹 ID) 911로 생성된 abc이라는 사용자가 존재합니다. 컨테이너는 root 권한으로 시작하여 초기화 스크립트를 실행하며, 이 스크립트 중 하나가 애플리케이션이 시작되기 전에 해당 사용자의 ID를 재설정합니다.
groupmod -o -g "${PGID}" abc
usermod -o -u "${PUID}" abc-o 플래그는 이미 다른 곳에서 사용 중인 ID를 허용합니다. 그 후 초기화 과정에서 권한을 낮추고 애플리케이션을 abc 권한으로 실행합니다. 즉, Docker는 PUID=1000를 다른 환경 변수와 마찬가지로 컨테이너 내부로 전달할 뿐이며, 이 변수에 따라 직접 동작하지는 않습니다. 이 변수는 애플리케이션 시작 전 컨테이너 내부의 사용자 ID를 변경하며, 이는 사용자 네임스페이스 재매핑(user namespace remapping)이 없는 표준 rootful 데몬 환경에서는 새로 생성된 파일의 소유자가 일반적으로 1000으로 설정됨을 의미합니다. 이미 존재하는 쓰기 가능한 파일을 수정해도 소유자는 변경되지 않습니다. Rootless Docker는 아래에서 설명하는 바와 같이 해당 번호를 이동시킵니다. PUID를 설정하지 않으면 abc는 911로 유지되며, 이것이 설정되지 않은 바인드 마운트(bind mount)에 911:911 소유의 파일이 가득 차는 이유입니다.
id를 사용하여 두 개의 번호 확인하기
데이터 디렉터리를 소유한 사용자로 호스트에서 다음 명령을 실행합니다.
iduid=1000(deploy) gid=1000(deploy) groups=1000(deploy),27(sudo),988(docker)uid은 PUID이며 gid는 PGID입니다. 스크립트의 경우 id -u 및 id -g를 사용하면 번호만 출력됩니다. 대부분의 신규 VPS 이미지에서 첫 번째 사용자 계정은 1000:1000이지만, 이를 당연하게 여기지 마십시오. 할당 번호는 존재하는 계정과 구성에 따라 달라집니다. 서버를 재구축하면 다시 1000이 할당될 수 있고, 나중에 생성된 계정은 더 높은 ID를 부여받습니다. 서비스가 로그인 사용자 대신 전용 서비스 계정으로 실행되는 경우, id thatuser를 실행하여 해당 번호를 확인하십시오.
파일 소유자가 911:911로 표시되는 이유
ls -l은 해당 ID와 일치하는 호스트 계정이 없을 때 이름 대신 숫자 ID를 출력합니다. 호스트에 UID 911과 일치하는 계정이 없으면 출력할 이름이 없습니다. 항상 숫자를 확인하고 모호함을 없애려면 ls -ln을 사용하십시오:
ls -ln /srv/appdata/sonarrdrwxr-xr-x 2 911 911 4096 Aug 7 09:12 Backups
-rw-r--r-- 1 911 911 512 Aug 7 09:12 config.xml이 출력은 컨테이너의 기본 설정과 일치하지만, 기존 파일만으로는 현재 애플리케이션이 어떤 사용자로 실행되는지 증명할 수 없습니다. 해당 목록에 있는 config.xml은 인증 설정을 담고 있는 파일이기도 하며, 웹 UI를 처음 열었을 때 Sonarr와 Radarr는 기본 사용자 이름이나 비밀번호 없이 제공됨을 확인해야 할 때 중요합니다. 추측하지 말고 컨테이너 내부에서 직접 확인하십시오:
docker exec sonarr id abc
docker compose logs sonarr | head -n 25linuxserver init은 시작 로그에 결과를 두 줄로 출력합니다:
User UID: 911
User GID: 911Compose 파일에서 PUID=1000를 설정했음에도 해당 줄에 911이 표시된다면, 실행 중인 컨테이너가 설정한 값을 사용하지 않는 것입니다. 일반적인 원인은 docker-compose.yml을 수정한 후 docker compose restart을 실행하여 기존 컨테이너를 원래 환경 그대로 재사용했기 때문입니다. 환경 변수 변경 사항을 적용하려면 컨테이너를 다시 생성하는 docker compose up -d가 필요합니다. 다른 원인은 의도적인 경우입니다. 이미지가 읽기 전용(read-only) 모드나 비루트(non-root) 모드로 실행될 때, init은 변수가 컨테이너 내부에 존재하더라도 번호 재지정 과정을 완전히 건너뜁니다. 읽기 전용 모드에서는 배너가 abc의 변경되지 않은 ID를 보고하며, 비루트 모드에서는 /run의 소유자를 보고합니다.
컨테이너가 생성한 파일을 삭제할 수 없는 이유
커널은 이름이 아닌 숫자를 비교합니다. 사용자의 셸은 UID 1000으로 실행되지만, 해당 파일은 UID 911의 소유입니다. 파일을 포함하는 디렉터리는 drwxr-xr-x이며 이 역시 911의 소유이므로, 그룹 및 기타 사용자는 읽기와 실행 권한만 가질 뿐 쓰기 권한은 없습니다. 파일을 삭제하려면 파일 자체가 아니라 해당 파일이 위치한 디렉터리에 대한 쓰기 권한이 필요합니다. 따라서 파일 자체는 문제가 없어 보여도 다음과 같은 오류가 발생합니다.
rm: cannot remove '/srv/appdata/sonarr/config.xml': Permission denied쓰기 작업을 수행하는 컨테이너도 반대편에서 동일한 문제에 직면합니다. 호스트 디렉터리가 755 모드로 사용자 소유이고 애플리케이션이 911로 실행되는 경우, 첫 번째 쓰기 시도부터 Permission denied 오류가 발생하며 애플리케이션은 이를 자체적인 메시지로 보고합니다. Sonarr나 Radarr 같은 .NET 애플리케이션에서는 이를 UnauthorizedAccessException: Access to the path '/data/downloads' is denied로 표시합니다. 파일 앞에 표시된 권한 문자열은 현재 어떤 권한 세트의 적용을 받고 있는지 알려주며, drwxr-xr-x를 올바르게 읽는 법을 익히면 이러한 오류를 명확하게 파악할 수 있습니다.
이는 특히 bind mount에서 발생하는 문제입니다. Docker가 빈 named volume을 생성하여 이미지 내에 존재하는 경로에 마운트할 때는, 해당 경로의 내용물과 소유권 및 권한 비트를 볼륨으로 복사하므로 애플리케이션은 이미 자신이 소유한 디렉터리를 찾게 됩니다. 반면 bind mount는 이러한 처리가 전혀 이루어지지 않습니다. Docker는 호스트 디렉터리를 있는 그대로 마운트하기 때문입니다. 이러한 차이는 bind mount가 named volume보다 유리한 경우와 그렇지 않은 경우를 알아야 하는 실질적인 이유 중 하나입니다.
이미 잘못된 디렉터리 수정하기
PUID와 PGID를 설정하면 애플리케이션의 향후 동작 방식이 변경됩니다. 하지만 이 설정이 디스크에 이미 존재하는 모든 파일의 소유권을 소급하여 수정하지는 않습니다. 다만, 아래에 설명된 특정 경로에 대해서는 초기화 과정에서 소유권이 수정됩니다. 스택을 중지하고 직접 소유권을 수정한 뒤 다시 시작하십시오.
docker compose down
sudo chown -R 1000:1000 /srv/appdata/sonarr
docker compose up -d숫자를 직접 입력하고 싶지 않다면 sudo chown -R "$(id -u):$(id -g)" /srv/appdata/sonarr를 사용하십시오. 컨테이너가 실행 중인 상태에서 재귀적인 chown을 수행하면 디렉터리 트리가 절반만 수정되거나 혼란스러운 오류가 추가로 발생할 수 있으므로, 반드시 컨테이너를 중지한 상태에서 작업하십시오.
PUID와 PGID로 해결되지 않는 문제
모든 설정을 올바르게 마친 사용자들도 이 부분에서 자주 어려움을 겪습니다. linuxserver 베이스 이미지의 사용자 설정 스크립트는 시작 시 /app, /config, /defaults 세 경로에 대해서만 chown을 수행합니다. 사용자의 미디어 마운트 경로는 이 목록에 포함되지 않습니다. /data, /downloads, /tv는 컨테이너 사용자에게 그대로 전달됩니다. 따라서 호스트 측 마운트 경로의 소유권이 컨테이너 사용자가 쓰기 작업을 할 수 없는 상태라면, 컨테이너는 정상적으로 시작되어 배너에 올바른 UID를 출력하더라도 첫 번째 가져오기(import) 작업에서 실패하게 됩니다.
이는 의도된 동작입니다. 컨테이너가 시작될 때마다 12TB 규모의 미디어 라이브러리 전체에 재귀적으로 chown을 수행하는 것은 재앙과 다름없기 때문입니다. 결과적으로 미디어 디렉터리의 권한 관리는 사용자의 몫이며, 실제로 권한 문제가 발생하는 지점도 바로 이 마운트 경로들입니다. 이러한 유형의 실패는 컨테이너가 정상적으로 보인 후 몇 시간이 지나 애플리케이션 로그에 조용히 나타나기 때문에, 자신의 VPS에서 ntfy를 실행하여 휴대폰으로 알림을 보내는 방식의 주기적인 쓰기 테스트를 구성해 두는 것이 좋습니다. 이를 통해 일주일 동안 에피소드가 누락되는 상황을 겪기 전에 미리 문제를 파악할 수 있습니다.
사용자 권한을 제어하는 세 가지 방법과 각 방법의 적용 시점
PUID 및 PGID 환경 변수
이 방식은 엔트리포인트가 해당 변수를 읽어들이는 이미지에서만 작동합니다. 컨테이너가 root 권한으로 시작하여 자체 설정을 수행하고 /config를 수정한 뒤에야 권한을 낮추기 때문에 널리 사용됩니다. Docker Mods와 사용자 정의 초기화 스크립트도 정상적으로 작동합니다. 단점은 플랫폼 기능이 아닌 관례에 의존하며, 프로젝트마다 변수 이름이 표준화되어 있지 않다는 점입니다.
Compose의 user: 키
이것은 실제 Docker 기능이며 모든 이미지에서 작동합니다. 컨테이너 런타임이 이미지의 코드가 실행되기 전에 이를 적용하기 때문입니다.
services:
sonarr:
image: lscr.io/linuxserver/sonarr:latest
user: "1000:1000"프로세스가 root로 실행되지 않으므로 보안상 확실한 이점이 있습니다. 반면, 엔트리포인트에서 root 권한이 필요한 모든 작업은 실패하게 됩니다. linuxserver 이미지의 경우, 프로젝트 측에서 테스트를 거친 이미지에 한해 합리적인 범위 내에서 이를 지원합니다. 주의할 점은 PUID와 PGID가 더 이상 작동하지 않으며, Docker Mods와 사용자 정의 서비스도 실행되지 않는다는 것입니다. 또한 마운트된 모든 볼륨의 권한 관리는 사용자의 책임이 됩니다. 문서화된 패턴에서는 이 플래그와 함께 쓰기 가능한 /run을 사용합니다.
user: 1000:1000
tmpfs:
- /run:uid=1000,gid=1000,exec
security_opt:
- no-new-privileges=true사용자들이 흔히 놀라는 부수적인 현상이 하나 있습니다. 컨테이너의 /etc/passwd에 대응하는 항목이 없는 숫자 형태의 user:을 사용하면 내부 도구들이 whoami: cannot find name for user ID 1000를 보고합니다. ID는 유효하며 파일 접근도 정상적으로 작동하지만, 이름 조회만 실패하는 것입니다.
Rootless Docker
Rootless Docker는 데몬 자체를 권한이 없는 일반 사용자로 실행하므로, 데몬과 컨테이너 모두 호스트의 root 권한 없이 실행됩니다. 이는 소유권 계산 방식을 완전히 바꿉니다. 컨테이너의 UID 0은 Rootless Docker를 실행하는 호스트 사용자의 UID로 매핑됩니다. 1 이상의 n을 가진 컨테이너 UID n은 subuid + (n - 1)로 매핑되는데, 여기서 subuid은 /etc/subuid에 할당된 범위의 시작점입니다. 그룹 ID도 /etc/subgid를 사용하여 동일한 규칙을 따릅니다. Docker는 해당 파일에 최소 65,536개의 하위 ID가 있을 것으로 예상합니다.
이 매핑 방식은 기존의 관례와 반대되므로 다시 확인해야 합니다. Rootless Docker 환경에서 컨테이너가 root로 파일을 생성하면 일반적으로 사용자 본인 소유의 파일이 생성됩니다. 반면 UID 1000으로 파일을 생성하면, 범위가 100000에서 시작할 경우 100999와 같은 하위 ID 소유의 파일이 생성됩니다. 셸의 접근 권한은 권한 설정 및 ACL에 따라 달라지며, 삭제는 일반적으로 포함된 디렉터리에 따라 결정되므로 본인이 제어하는 디렉터리 내의 파일은 삭제할 수 있습니다. 따라서 rootful 데몬에서 올바른 PUID 값이 여기서는 잘못된 값이 됩니다. 두 메커니즘은 서로 다른 계층에서 소유권을 변경하므로, 확인 없이 중첩해서 사용하면 마운트된 데이터에 쓰기 권한이 없을 수 있습니다. Rootless 환경으로 전환한다면 라이브러리를 마이그레이션하기 전에 서버에서 파일 하나를 생성하여 소유권을 먼저 테스트하십시오.
단일 VPS에서 운영하는 대부분의 셀프 호스팅 스택의 경우, rootful 데몬에서 PUID와 PGID를 사용하는 것이 실용적인 선택입니다. 이미지가 이를 위해 빌드되고 문서화되어 있기 때문입니다. user:은 이미지 README에 해당 기능이 테스트되었다고 명시된 경우나, PUID를 전혀 지원하지 않는 공식 업스트림 이미지를 사용할 때 선택하십시오. 단일 VPS의 셀프 호스팅 AFFiNE 인스턴스와 같은 문서 작업 공간이 후자에 해당합니다. 컨테이너 중 PUID를 읽는 것이 없으며, 데이터베이스 디렉터리와 업로드된 파일의 소유권은 환경 블록이 아닌 런타임에 의해 결정되기 때문입니다. 셀프 호스팅 Chatwoot 고객 지원 데스크도 마찬가지입니다. Rails 컨테이너와 Sidekiq 워커 모두 하나의 업로드 디렉터리에 쓰기를 수행하지만 PUID를 읽지 않으므로, 해당 디렉터리는 이미지가 실행되는 사용자와 일치해야 합니다. 새로운 스택에서도 이는 변하지 않으므로, 팀원 각자에게 샌드박스 처리된 OneCLI 에이전트 제공 시에도 개인별 작업 공간 디렉터리와 Postgres 데이터 디렉터리는 이미지가 실행되는 사용자 소유가 되며, 이는 PUID 문제가 아닌 user: 및 chown의 문제가 됩니다. Codex, Claude Code, Hermes 앞에 단일 셀프 호스팅 API 배치 시에도 엔트리포인트가 여러 ID를 관리합니다. 컨테이너는 root로 시작해야 하며, 콘솔과 게이트웨이는 권한 없는 사용자로 실행되고, 각 에이전트 세션은 개별 사용자로 실행됩니다. 해당 배포에 user:를 추가하지 마십시오. 엔트리포인트가 데이터 볼륨의 소유권을 처리합니다.
미디어 스택 사례: 컨테이너 간 그룹 공유
Sonarr, Radarr 및 다운로드 클라이언트를 포함한 arr 미디어 스택은 이 개념이 이론을 넘어 실제 적용되는 사례입니다. 다운로드 클라이언트는 완료된 파일을 /data/downloads에 기록합니다. 이후 Sonarr는 해당 파일을 /data/media로 하드링크하거나 이동합니다. 하드링크가 정상적으로 작동하려면 두 컨테이너 모두 동일한 디렉터리 트리에 대한 쓰기 권한이 있어야 합니다. 만약 다운로드 클라이언트는 1000번 사용자로, Sonarr는 1001번 사용자로 실행되는데 공유 그룹 쓰기 권한이 없다면, 한쪽은 파일을 소유하고 다른 쪽은 읽기만 할 수 있는 상황이 발생합니다.
이 문제를 해결하려면 스택 내의 모든 컨테이너가 PGID로 사용할 공유 그룹이 필요합니다.
sudo groupadd -g 13000 media
sudo usermod -aG media deploy
sudo chown -R deploy:media /srv/media
sudo find /srv/media -type d -exec chmod 2775 {} +
sudo find /srv/media -type f -exec chmod 0664 {} +2775의 맨 앞에 있는 2는 setgid 비트입니다. 디렉터리에 이 비트가 설정되면, 그 안에 생성되는 모든 새 파일과 하위 디렉터리는 생성자의 기본 그룹이 아닌 해당 디렉터리의 그룹인 media를 상속받습니다. 따라서 chown를 매번 다시 실행할 필요 없이 새로운 다운로드 파일에도 권한이 유지됩니다. 자신의 접근 권한을 확인하기 전에 로그아웃 후 다시 로그인하거나 newgrp media을 실행하십시오. usermod -aG으로 추가한 그룹은 이미 열려 있는 셸 세션에 즉시 반영되지 않습니다.
컨테이너 내부에서 groupmod -o -g 13000 abc은 abc 그룹의 번호를 13000으로 변경하므로, abc은 호스트의 media 그룹과 동일한 GID로 파일을 기록합니다. 이 트리에 접근하는 모든 linuxserver 컨테이너는 각자의 PUID를 유지하면서 하나의 PGID를 공유합니다. 여기에는 Jellyfin 자체와 같이 완성된 라이브러리를 읽기만 하는 하위 체인의 컨테이너도 포함됩니다. 90년대 비디오 대여점처럼 라이브러리를 탐색할 수 있게 해주는 Halcyon과 같은 프론트엔드는 HALCYON_JELLYFIN_URL를 사용하여 HTTP로 Jellyfin에 연결합니다. 이 서비스의 표준 배포 방식은 공유 미디어 PGID나 미디어 디렉터리 마운트가 필요하지 않습니다.
그다음 스택 내의 모든 linuxserver 컨테이너에 UMASK=002을 설정하십시오. 많은 사용자가 이 단계를 놓칩니다. 이 값을 설정하지 않으면 애플리케이션은 상속받은 umask를 그대로 사용하며, 이미지 README에 예시로 표시된 값은 보통 UMASK=022입니다. 유효 umask가 022일 때, 애플리케이션이 새 파일에 대해 0666 권한을 요청하면 기본 ACL이 없는 경우 0644 권한이 부여됩니다. 이 경우 그룹의 나머지 사용자는 파일을 읽을 수는 있지만 수정할 수 없으므로, 방금 설정한 공유 구성이 대부분 무용지물이 됩니다. 002을 사용하고 기본 ACL이 없으면, 애플리케이션이 파일에 대해 일반적인 0666, 디렉터리에 대해 0777을 요청할 때 각각 0664과 2775 권한이 부여되어 그룹 쓰기가 가능해집니다. umask는 비트를 제거하는 역할만 하므로, 0600을 요청하는 애플리케이션은 여전히 0600를 얻게 되며, 기본 ACL이 설정된 디렉터리는 umask를 완전히 무시합니다. PUID와 PGID 옆에 이 변수를 추가하십시오.
services:
sonarr:
image: lscr.io/linuxserver/sonarr:latest
container_name: sonarr
environment:
- PUID=${PUID}
- PGID=${PGID}
- UMASK=002
- TZ=Etc/UTC
volumes:
- /srv/appdata/sonarr:/config
- /srv/media:/data
restart: unless-stopped이 두 값은 Compose 파일 옆의 .env 파일에 두어 전체 스택이 하나의 정의를 읽도록 하는 것이 좋습니다.
PUID=1000
PGID=13000Compose는 ${PUID} 스타일 치환을 위해 해당 파일을 자동으로 읽으며, 이는 자격 증명을 관리할 때 사용하는 방식과 동일합니다. docker-compose.yml에서 값을 분리하여 .env 파일로 관리하는 습관은 여기에도 적용되지만, 이 두 숫자는 비밀 정보가 아니라는 점이 다릅니다.
설정을 맹신하지 말고 처음부터 끝까지 검증하십시오. 애플리케이션 사용자로 설정된 umask를 적용하여 새 파일을 작성하고, 호스트에서 이를 읽어 확인합니다. 기존에 없는 테스트 파일명을 사용하십시오.
docker exec --user abc sonarr sh -c 'umask "$UMASK" && touch /data/downloads/permtest'
ls -ln /srv/media/downloads/permtest정상적인 결과라면 소유자는 PUID, 그룹은 13000, 모드는 -rw-rw-r--로 표시되어야 합니다. 그룹 권한이 1000로 나온다면 ls -ldn /srv/media/downloads을 실행하십시오. 해당 디렉터리에 setgid 비트(drwxrwsr-x의 s)가 없거나, 디렉터리 자체가 media이 아닌 1000번 그룹에 속해 있을 가능성이 큽니다. 위의 chown 및 chmod 2775 명령으로 두 문제 모두 해결할 수 있습니다. 모드가 -rw-r--r--으로 나온다면 컨테이너의 UMASK 값과 디렉터리의 기본 ACL을 확인하십시오. 환경 설정이 오래되었다면 컨테이너를 다시 생성해야 합니다. 이 테스트는 설정된 마스크를 사용하여 abc로 파일을 생성하는 과정을 검증합니다. 애플리케이션 자체의 생성 모드와 유효 umask가 여전히 파일 권한을 결정합니다. 확인이 끝나면 rm /srv/media/downloads/permtest로 테스트 파일을 삭제하십시오.
어떤 이미지가 어떤 변수를 사용하는가
linuxserver.io 이미지는 PUID, PGID 및 UMASK을 사용합니다. Paperless-ngx는 동일한 개념에 대해 USERMAP_UID 및 USERMAP_GID이라는 다른 이름을 사용하며, 두 변수 모두 기본값은 1000입니다. 해당 문서에서는 id -u 및 id -g에서 이 값을 읽도록 안내합니다. 사진 서버도 이와 유사한 차이를 보입니다. PhotoPrism은 자체적인 PHOTOPRISM_UID 및 PHOTOPRISM_GID 쌍을 가지고 있는 반면, Immich는 이에 대응하는 변수가 없으며 컨테이너 사용자를 Docker의 user: 키에 맡깁니다. 따라서 PhotoPrism과 Immich 중 선택하기는 서버에서 가장 큰 라이브러리를 관리하기 위해 어떤 메커니즘을 유지할지 결정하는 과정이기도 합니다. 일반적인 데이터베이스 및 웹 서버 이미지를 포함한 많은 공식 업스트림 이미지는 고정된 내장 사용자를 포함하며, 사용자가 user:를 사용하거나 그대로 두기를 기대합니다. 소규모 단일 앱 배포 시에도 같은 문제가 발생합니다. 따라서 자체 호스팅 openGym 운동 추적기를 설치할 때는 바인드 마운트를 연결하기 전에 컨테이너가 실제로 어떤 사용자로 실행되는지 확인해야 합니다. 데이터베이스를 보관하는 디렉터리는 PUID 설정 여부와 관계없이 해당 사용자의 권한을 상속받기 때문입니다. 원격 액세스 릴레이도 같은 범주에 속합니다. 따라서 직접 RustDesk 릴레이 서버를 운영할 때 hbbs가 처음 시작 시 생성하는 Ed25519 키 쌍은 해당 이미지가 최종적으로 사용하는 사용자의 소유로 바인드 마운트에 저장됩니다. 이후 호스트 측에서 chown을 사용하여 이를 수정하거나, user: 키를 사용하여 사전에 ID를 선택할 수 있습니다. 해당 이미지는 자체 사용자를 설정하지 않으므로, 마운트된 디렉터리에 선택한 ID로 쓰기 권한만 있다면 문제가 없습니다. 이는 나중에 추가하는 인프라에도 동일하게 적용됩니다. 예를 들어 단일 로그인을 위해 앱 앞에 Authentik 배치를 수행할 경우, PUID를 전혀 읽지 않는 공식 authentik 및 Postgres 이미지를 실행하게 되며, 볼륨 소유권은 프로세스가 실행되는 사용자 및 엔트리포인트가 수행하는 설정에 따라 결정됩니다. Authentik은 2025.10 릴리스에서 Redis 의존성을 제거했습니다.
따라서 프로젝트 간에 환경 변수 블록을 복사하기 전에 각 이미지의 README를 확인하십시오. Docker는 내부에서 읽는지 여부와 관계없이 설정한 모든 환경 변수를 컨테이너로 전달합니다. 아무것도 사용하지 않는 PUID는 오류나 경고를 발생시키지 않으며 아무런 효과도 없습니다. 컨테이너는 Docker의 user: 설정이나 Dockerfile에 의해 선택된 사용자로 시작하며, 엔트리포인트는 애플리케이션을 시작하기 전에 권한을 낮출 수 있습니다. 자체 호스팅 open-kritt 보안 스캔 스택을 포함하여 새로운 항목을 서버에 추가하기 전에 해당 내용을 읽어보십시오. Compose 파일은 이미지가 PUID를 준수하는지, 아니면 마운트하는 디렉터리의 소유권이 이미지 자체에 의해 고정되는지 알려줍니다.
FAQ
내 Docker 파일의 소유자가 왜 911:911인가요?
911은 linuxserver.io 이미지에 내장된 abc 사용자의 UID 및 GID입니다. 이 값이 보이는 것은 내장된 기본값과 일치하기 때문이지만, 컨테이너의 PUID와 PGID를 변경한 후에도 파일이 해당 소유권을 유지할 수 있습니다. 호스트의 어떤 계정도 해당 ID와 일치하지 않으면 ls -l은 표시할 이름이 없으므로 원시 숫자를 보여줍니다. PUID와 PGID을 id의 출력값으로 설정하고, docker compose up -d를 사용하여 컨테이너를 다시 생성한 다음, 영향을 받는 디렉터리에서 sudo chown -R 1000:1000을 사용하여 기존 파일의 소유권을 수정하십시오.
PUID와 PGID는 모든 Docker 이미지에서 작동하나요?
아니요. 이는 Docker 기능이 아니며 Docker는 이를 읽지 않습니다. 이 변수들은 애플리케이션 시작 전 자체 엔트리포인트(entrypoint)가 이를 읽어 usermod와 groupmod를 호출하는 이미지에서만 작동하며, linuxserver.io 제품군과 이 패턴을 복사한 일부 프로젝트가 이에 해당합니다. 다른 프로젝트는 paperless-ngx의 USERMAP_UID 및 USERMAP_GID과 같이 다른 이름을 사용합니다. 두 변수 모두 읽지 않는 이미지에서는 해당 변수가 수용되지만 아무런 경고 없이 무시됩니다.
PUID와 PGID를 사용해야 하나요, 아니면 Docker Compose의 user: 키를 사용해야 하나요?
이미지가 지원하는 경우 PUID와 PGID을 사용하십시오. 엔트리포인트가 root 권한으로 충분히 오래 실행되어 /config을 수정하고 자체 서비스를 올바르게 시작할 수 있기 때문입니다. 이미지가 선택한 사용자에 대한 지원을 명시하는 경우 user:를 사용하십시오. PUID 지원이 없다고 해서 엔트리포인트가 root 없이 작동한다는 의미는 아닙니다. linuxserver 이미지에서 user:을 설정하면 PUID와 PGID가 무력화되고, Docker Mods와 사용자 지정 서비스 실행이 중단되며, 모든 마운트된 볼륨의 권한 관리는 사용자의 책임이 됩니다.
Sonarr의 PUID가 올바른데도 파일을 이동할 수 없습니다. 무엇이 문제인가요?
다음 세 가지를 순서대로 확인하십시오. 첫째, 미디어 마운트 자체입니다. 기본 이미지의 사용자 설정 스크립트는 /app, /config, /defaults의 소유권을 변경(chown)하므로, /data이나 /downloads은 호스트에 있는 기존 소유권을 그대로 유지합니다. 둘째, 공유 그룹입니다. 미디어 트리에 접근하는 컨테이너들에 동일한 PGID와 그룹 쓰기 권한을 부여하십시오. 셋째, umask입니다. 애플리케이션이 0666를 요청하고 기본 ACL이 적용되지 않을 때 유효 마스크가 022이면 0644 파일이 생성되므로, 그룹 내 다른 컨테이너들은 파일을 읽을 수는 있지만 수정할 수는 없습니다. UMASK을 설정하지 않는다고 해서 특정 마스크나 파일 모드가 보장되지는 않습니다. UMASK=002를 설정하고 chmod 2775를 사용하여 디렉터리에 setgid 비트를 설정하면 새 파일이 그룹을 상속받습니다. 0600을 요청하는 애플리케이션은 여전히 개인 파일을 생성하며, 기본 ACL은 생성 권한이 할당되는 방식을 변경합니다.