Docker Compose YAML 오류, 시놀로지에서 ‘들여쓰기’ 때문에 실행되지 않는 이유

시놀로지 NAS에서 Container Manager를 이용해 Docker Compose를 사용하다 보면 YAML 파일의 들여쓰기 오류 때문에 컨테이너가 생성되지 않거나 프로젝트 실행 자체가 실패하는 경우가 있습니다.

특히 Docker Compose를 처음 사용하는 경우에는 YAML 파일이 단순한 설정 파일처럼 보이기 때문에 공백 몇 칸이 실제 실행에 영향을 준다는 사실을 놓치기 쉽습니다.

하지만 YAML은 들여쓰기 자체가 데이터의 구조를 표현하는 문법입니다.

따라서 같은 내용이라도 들여쓰기 위치가 달라지면 전혀 다른 설정으로 해석되거나 YAML 문법 오류가 발생할 수 있습니다.

시놀로지 Container Manager에서 프로젝트를 생성할 때 다음과 같은 오류가 나타나는 경우가 대표적입니다.

YAML parse error

mapping values are not allowed here

did not find expected key

found character that cannot start any token

또는 Compose 프로젝트가 아예 실행되지 않는 경우도 있습니다.

이런 문제는 Docker 이미지 자체에 문제가 있는 것이 아니라 Compose 파일의 YAML 문법이 올바르지 않아서 발생하는 경우가 많습니다.

YAML에서 들여쓰기가 중요한 이유

YAML은 중괄호나 세미콜론 대신 들여쓰기 수준을 이용해 데이터의 계층 구조를 표현합니다.

예를 들어 다음과 같은 구조가 있다고 가정해 보겠습니다.

services:
  jellyfin:
    image: jellyfin/jellyfin

여기서는

services 아래에 jellyfin이 있고, jellyfin 아래에 image가 있는 구조입니다.

즉, 들여쓰기를 통해 다음과 같은 계층이 만들어집니다.

services

→ jellyfin

→ image

이 구조가 깨지면 Docker Compose가 설정 파일을 정상적으로 읽지 못할 수 있습니다.

공백 하나가 문제가 될 수 있다

YAML에서 중요한 것은 들여쓰기의 일관성입니다.

예를 들어 다음과 같이 작성했다고 가정하겠습니다.

services:
  jellyfin:
    image: jellyfin/jellyfin
    ports:
      - "8096:8096"

이것은 정상적인 계층 구조입니다.

그런데 다음처럼 ports의 위치가 잘못되면 문제가 발생할 수 있습니다.

services:
  jellyfin:
    image: jellyfin/jellyfin
  ports:
    - "8096:8096"

여기서는 ports가 jellyfin의 설정이 아니라 services 아래에 있는 별도의 항목처럼 해석될 수 있습니다.

즉, 단순히 줄을 한 칸 잘못 이동한 것처럼 보여도 Docker Compose에서는 의미가 달라집니다.

YAML에서는 Tab보다 Space를 사용하는 것이 안전하다

YAML 파일을 작성할 때 자주 발생하는 문제 중 하나가 Tab과 Space를 혼용하는 것입니다.

YAML에서는 일반적으로 들여쓰기에 Space를 사용해야 합니다.

특히 일부 편집기에서 Tab을 눌러 들여쓰기를 하면 YAML 파서에서 오류가 발생할 수 있습니다.

따라서 Compose 파일을 작성할 때는 가능하면 Space를 사용해 들여쓰기하는 것이 안전합니다.

많은 예제에서 2칸 들여쓰기를 사용하지만 중요한 것은 반드시 2칸이어야 한다는 것이 아니라 같은 계층에서 동일한 들여쓰기 기준을 유지하는 것입니다.

들여쓰기 깊이가 달라지면 구조가 바뀐다

예를 들어 다음과 같은 환경변수 설정이 있다고 하겠습니다.

environment:
  - TZ=Asia/Seoul

이 설정은 특정 서비스의 environment 항목에 들어가야 합니다.

따라서 일반적으로 다음과 같은 구조가 됩니다.

services:
  app:
    image: example/app
    environment:
      - TZ=Asia/Seoul

그런데 environment의 들여쓰기가 잘못되면 Compose 파일이 의도한 구조와 다르게 해석될 수 있습니다.

특히 여러 서비스와 환경변수가 함께 들어가는 Compose 파일에서는 이런 실수가 쉽게 발생합니다.

services: 아래의 구조를 이해해야 한다

시놀로지에서 Docker Compose를 사용할 때 가장 먼저 이해해야 하는 부분이 services:입니다.

예를 들어 다음과 같은 구조가 있습니다.

services:
  app:
    image: example/app

  database:
    image: mariadb

여기서는 app과 database가 모두 services 아래에 있는 서로 다른 컨테이너 서비스입니다.

따라서 둘의 들여쓰기 수준이 동일해야 합니다.

다음처럼 작성하면 구조가 달라집니다.

services:
  app:
    image: example/app
    database:
      image: mariadb

이 경우 database가 별도의 서비스가 아니라 app 아래에 들어간 것으로 해석될 수 있습니다.

즉, 들여쓰기는 단순한 디자인이 아니라 Compose의 구조를 결정하는 문법입니다.

ports에서 들여쓰기 실수가 자주 발생한다

Docker Compose에서 포트 설정은 다음과 같이 작성합니다.

ports:
  - "8080:80"

여기서 -도 중요한 역할을 합니다.

YAML에서 -는 목록의 항목을 나타냅니다.

따라서 여러 개의 포트를 지정하면 다음처럼 작성합니다.

ports:
  - "8080:80"
  - "8443:443"

-의 위치가 잘못되거나 들여쓰기가 맞지 않으면 YAML 파싱 오류가 발생할 수 있습니다.

특히 인터넷에서 Compose 파일을 복사한 뒤 일부 설정만 수정할 때 이런 문제가 자주 발생합니다.

volumes에서도 같은 문제가 발생한다

볼륨 설정도 마찬가지입니다.

예를 들어

volumes:
  - /volume1/docker/app:/config

와 같은 형태를 사용합니다.

서비스 아래에서 작성한다면 일반적으로 다음과 같은 구조가 됩니다.

services:
  app:
    image: example/app
    volumes:
      - /volume1/docker/app:/config

여기서 volumes와 - /volume1/...의 들여쓰기 관계가 잘못되면 오류가 발생할 수 있습니다.

특히 시놀로지 NAS에서는 /volume1/ 같은 실제 경로가 포함되기 때문에 경로 자체의 오타와 YAML 들여쓰기 오류를 구분해서 확인하는 것이 중요합니다.

환경변수에서도 들여쓰기 오류가 발생한다

환경변수를 작성할 때도 주의해야 합니다.

예를 들어 다음과 같은 형태가 있습니다.

environment:
  TZ: Asia/Seoul
  PUID: "1026"
  PGID: "100"

이때 각각의 항목은 environment 아래에 있어야 합니다.

반대로 다음처럼 작성하면 구조가 달라질 수 있습니다.

environment:
  TZ: Asia/Seoul
    PUID: "1026"

이런 형태는 YAML 문법상 올바르지 않습니다.

환경변수가 많아질수록 들여쓰기 오류가 발생하기 쉬우므로 작성 후 전체 구조를 확인하는 것이 좋습니다.

콜론(:) 때문에 오류가 발생하기도 한다

YAML에서는 :가 특별한 의미를 가지고 있습니다.

예를 들어

image: example/app

에서 :는 키와 값을 구분합니다.

그런데 문자열 안에 콜론이 들어가는 경우에는 상황에 따라 문제가 발생할 수 있습니다.

특히 포트 설정에서

- 8080:80

처럼 콜론을 사용하는 경우가 있기 때문에 포트 값은 따옴표로 감싸서 작성하는 방식이 안전합니다.

- "8080:80"

이렇게 하면 YAML에서 해당 값을 문자열로 명확하게 처리할 수 있습니다.

따옴표 때문에 오류가 발생할 수도 있다

Compose 파일을 복사하면서 일반 따옴표가 아닌 특수 따옴표가 들어가는 경우도 있습니다.

예를 들어 문서 편집 프로그램에서 "문자열" 대신 스마트 따옴표가 삽입되면 YAML 파서가 정상적으로 인식하지 못할 수 있습니다.

따라서 YAML 파일을 작성할 때는 일반적인 ASCII 문자와 Space를 사용하는 것이 안전합니다.

특히 블로그나 문서에서 코드를 복사한 경우 눈에 보이지 않는 특수문자가 포함되지 않았는지도 확인해야 합니다.

시놀로지 Container Manager에서 오류가 발생하는 경우

시놀로지 Container Manager에서는 Docker Compose 프로젝트를 생성할 때 YAML 파일을 입력하거나 업로드할 수 있습니다.

이 과정에서 YAML 문법이 잘못되어 있으면 프로젝트 생성 단계에서 오류가 발생할 수 있습니다.

이때 중요한 것은 오류 메시지를 무작정 검색하기보다 오류가 발생한 줄 번호를 먼저 확인하는 것입니다.

오류 메시지에 특정 줄이나 열 번호가 표시된다면 해당 부분을 먼저 확인합니다.

다만 YAML 파서가 실제 오류가 발생한 위치보다 조금 앞이나 뒤의 줄을 가리키는 경우도 있습니다.

따라서 표시된 줄만 수정하기보다는 그 주변의 들여쓰기 구조를 함께 확인하는 것이 좋습니다.

한 줄만 수정했는데 다른 오류가 생기는 이유

YAML 파일은 계층 구조로 연결되어 있기 때문에 한 부분의 들여쓰기를 수정하면 다른 설정과의 관계가 달라질 수 있습니다.

예를 들어 volumes의 위치를 한 단계 이동했더니 YAML 문법 오류는 사라졌지만 컨테이너 실행 과정에서 다른 오류가 발생할 수 있습니다.

이는 문법은 정상적으로 바뀌었지만 Compose가 의도하지 않은 구조로 해석했기 때문일 수 있습니다.

따라서 단순히 “오류 메시지가 사라졌다”는 것만으로 정상적인 Compose 파일이라고 판단해서는 안 됩니다.

컨테이너가 실제로 원하는 설정으로 실행되는지 확인해야 합니다.

YAML 파일을 복사해서 사용할 때 주의할 점

Docker Compose 예제는 인터넷에서 쉽게 찾을 수 있습니다.

하지만 다른 사람이 사용하는 Compose 파일을 그대로 시놀로지 NAS에 적용하면 문제가 발생할 수 있습니다.

대표적으로 다음과 같은 차이가 있습니다.

NAS의 폴더 경로

사용자 UID/GID

포트 번호

Docker 이미지

환경변수

네트워크 구성

따라서 Compose 파일을 복사했다면 최소한 위 항목은 자신의 NAS 환경에 맞게 수정해야 합니다.

특히 여러 사이트의 예제를 조합하다 보면 들여쓰기 수준이 서로 다른 코드가 섞일 수 있습니다.

이 과정에서 YAML 오류가 발생하기 쉽습니다.

들여쓰기를 일정하게 유지하는 방법

Compose 파일을 작성할 때 가장 좋은 방법은 처음부터 일정한 규칙을 정하는 것입니다.

예를 들어 다음처럼 작성합니다.

services:
  app:
    image: example/app
    ports:
      - "8080:80"
    volumes:
      - /volume1/docker/app:/config
    environment:
      TZ: Asia/Seoul

여기서 중요한 것은 각 계층의 들여쓰기 수준이 일정하다는 것입니다.

services

→ app

→ image, ports, volumes, environment

→ ports와 volumes 아래의 목록

이런 계층을 머릿속으로 구분하면서 작성하면 실수를 줄일 수 있습니다.

YAML 오류를 수정할 때 전체를 다시 작성할 필요는 없다

YAML 오류가 발생했다고 Compose 파일 전체를 다시 작성할 필요는 없습니다.

먼저 오류 메시지와 줄 번호를 확인합니다.

그다음 해당 줄 주변에서 다음 항목을 확인합니다.

들여쓰기

Tab 사용 여부

콜론 위치

대괄호나 따옴표

- 목록 위치

부모 항목과 자식 항목의 관계

특히 오류가 발생한 줄 바로 위쪽에서 들여쓰기가 잘못된 경우가 많습니다.

Compose 파일의 기본 구조를 먼저 확인한다

복잡한 Compose 파일을 만들기 전에 기본 구조부터 확인하는 것도 좋은 방법입니다.

예를 들어 다음과 같은 형태입니다.

services:
  app:
    image: example/app
    ports:
      - "8080:80"
    volumes:
      - /volume1/docker/app:/config

여기서 하나씩 항목을 추가하면서 실행 여부를 확인하면 오류가 발생한 위치를 쉽게 찾을 수 있습니다.

반대로 처음부터 수십 개의 환경변수와 여러 컨테이너를 한꺼번에 추가하면 어느 부분에서 문제가 발생했는지 찾기가 어려워집니다.

Docker Compose 오류와 컨테이너 오류는 다르다

이 부분도 구분할 필요가 있습니다.

YAML 문법 오류는 Compose 파일을 해석하는 단계에서 발생하는 문제입니다.

반면 컨테이너가 생성된 후 실행되지 않는 문제는 이미지, 환경변수, 권한, 볼륨, 네트워크 등 다른 원인일 수 있습니다.

즉,

YAML 오류

→ Compose 파일을 읽지 못함

컨테이너 실행 오류

→ Compose는 읽었지만 컨테이너 실행 과정에서 문제가 발생함

으로 구분할 수 있습니다.

따라서 YAML 오류가 발생했다면 먼저 Docker 이미지나 컨테이너 권한을 수정하기보다 Compose 파일의 문법부터 확인하는 것이 순서입니다.

시놀로지에서 YAML 오류가 발생했을 때 확인 순서

Container Manager에서 Compose 프로젝트가 실행되지 않는다면 다음 순서로 확인하는 것이 좋습니다.

먼저 오류 메시지를 확인합니다.

오류에 표시된 줄 번호를 확인합니다.

해당 줄과 앞뒤 줄의 들여쓰기를 확인합니다.

Tab과 Space가 섞이지 않았는지 확인합니다.

services: 아래의 계층 구조를 확인합니다.

각 서비스의 image, ports, volumes, environment 위치를 확인합니다.

-로 시작하는 목록 항목의 들여쓰기를 확인합니다.

포트 값에 콜론이 있다면 따옴표 사용 여부를 확인합니다.

복사한 코드라면 특수문자나 스마트 따옴표가 들어갔는지 확인합니다.

마지막으로 자신의 시놀로지 환경에 맞는 경로와 환경변수를 확인합니다.

마무리

시놀로지 NAS에서 Docker Compose YAML 오류가 발생하면 Docker 자체의 문제라고 생각하기 쉽습니다.

하지만 실제로는 들여쓰기 하나 때문에 Compose 파일의 계층 구조가 잘못 해석되는 경우가 상당히 많습니다.

YAML에서는 HTML처럼 태그를 사용하거나 JSON처럼 중괄호로 구조를 표현하는 것이 아니라 들여쓰기 자체가 데이터 구조를 결정합니다.

따라서

services

↓

container

↓

image / ports / volumes / environment

와 같은 계층을 정확하게 유지해야 합니다.

특히 다음과 같은 부분에서 실수가 자주 발생합니다.

Tab과 Space 혼용

서비스별 들여쓰기 불일치

ports와 volumes의 목록 위치 오류

environment 항목의 구조 오류

콜론과 따옴표 사용 오류

인터넷에서 복사한 Compose 코드의 구조가 서로 다른 경우

Docker Compose 파일을 작성할 때는 화려한 설정을 추가하는 것보다 기본적인 YAML 구조를 정확하게 유지하는 것이 먼저입니다.

또한 시놀로지 NAS에서는 Compose 파일의 문법이 정상이라고 해도 NAS의 실제 폴더 경로, 권한, 포트, 네트워크 설정이 자신의 환경과 맞지 않으면 컨테이너 실행 과정에서 별도의 오류가 발생할 수 있습니다.

따라서 오류가 발생했을 때는

YAML 문법 확인 → Compose 구조 확인 → NAS 경로 확인 → 권한 확인 → 포트 및 네트워크 확인

순서로 문제를 분리해서 확인하는 것이 좋습니다.

결국 Docker Compose에서 들여쓰기는 단순히 보기 좋게 코드를 정리하기 위한 것이 아닙니다.

들여쓰기 자체가 Docker Compose의 설정 구조를 결정하는 문법이기 때문에, 시놀로지 Container Manager에서 YAML 오류가 발생했다면 가장 먼저 들여쓰기부터 확인하는 것이 좋습니다.