ARM64 아키텍처에서 Collabora CODE 컨테이너가 시작되지 않는 문제 해결

Collabora Online Development Edition(CODE) 컨테이너가 ARM64 시스템에서 즉시 종료되는 경우, 네트워킹, 인증서 또는 WOPI 설정을 변경하기 전에 아키텍처 호환성부터 확인하십시오. 2026년 10월 7일 기준으로 공식 저장소에는 현재 태그 및 버전 26.04.4.2.1을 포함한 최신 릴리스에 대한 collabora/code네이티브 변형이 나열되어 있습니다 . 즉, 최신 ARM64 호스트는 일반적으로 CODE를 실행하기 위해 x86 에뮬레이션이 필요하지 않습니다. 초보자에게 가장 유용한 워크플로는 호스트 아키텍처를 확인하고, 정확한 이미지 태그를 검사하고, 강제로 설정된 AMD64 설정을 제거하고, ARM64를 지원하는 이미지를 다운로드한 다음 애플리케이션 수준의 구성을 문제 해결하는 것입니다.linux/arm64latest

이 가이드는 시작 실패 자체에 초점을 맞추고 있습니다. 모든 ARM64 문제의 원인이 동일하다고 가정하지 않습니다. 컨테이너가 성공적으로 시작되었지만 Nextcloud, ownCloud 또는 다른 WOPI 호스트가 해당 컨테이너에 연결할 수 없는 경우, 이는 다른 차원의 문제 해결이 필요합니다.

변경하기 전에 알아야 할 사항

ARM64 는 64비트 ARM CPU 아키텍처입니다. Linux에서는 일반적으로 이를 `ARM64`로 표시하고 aarch64, Docker에서는 동일한 대상을 `AMD64`로 표시합니다 linux/arm64. AMD64 (x86-64라고도 함)는 다른 CPU 아키텍처입니다. 컨테이너 이미지는 하나 이상의 아키텍처용으로 빌드된 바이너리를 포함할 수 있으며, Docker는 이미지 태그에 호환되는 매니페스트가 제공된 경우에만 올바른 변형을 자동으로 선택할 수 있습니다.

멀티 플랫폼 이미지 는 레지스트리 매니페스트가 AMD64 및 ARM64와 같은 아키텍처용으로 별도의 이미지 빌드를 가리키는 단일 이미지 태그입니다. Docker 문서에 따르면 멀티 플랫폼 이미지를 가져올 때 호스트에 맞는 버전을 자동으로 선택합니다. 기본 동작에 대한 자세한 내용은 Docker의 멀티 플랫폼 이미지 문서를 참조하십시오.

특히 Collabora CODE의 경우, 오래된 튜토리얼에 의존하기보다는 Docker Hub의 공식 collabora/code 태그 목록을 확인하세요 . 이 글이 작성된 2026년 10월 7일 기준으로 latest, 해당 문서에는 전용 태그가 26.04.4.2.1포함되어 있었습니다. 하지만 이전 버전의 고정된 릴리스는 다를 수 있으므로, "Collabora가 ARM을 지원합니다"라는 일반적인 주장보다는 실제로 배포하는 태그가 더 중요합니다.linux/arm64latest-arm64

안전한 문제 해결 세션을 준비하세요

• docker-compose.yml현재 명령 또는 배포 명령 의 사본을 보관하십시오 .
• 사용 중인 Collabora 이미지 태그를 정확하게 기록해 두세요.
• 아키텍처 불일치를 진단하기 위해 애플리케이션 데이터나 리버스 프록시 구성을 삭제하지 마십시오.
• 실제 운영 환경에 배포하는 경우, 유지 관리 기간이나 스테이징 호스트에서 먼저 교체 태그를 테스트하십시오.

목표는 간단합니다. Docker는 ARM64 이미지를 가져와야 하고, 컨테이너는 즉시 종료되지 않고 계속 실행되어야 하며, 로그에는 아키텍처 오류로 실패하는 대신 Collabora의 정상적인 시작 과정이 기록되어야 합니다.

1단계: 호스트 및 Docker 아키텍처를 확인합니다.

Collabora 컨테이너가 실제로 실행되는 머신에서 다음 검사를 실행하십시오.

uname -m
docker info --format '{{.Architecture}}'
docker version

네이티브 64비트 ARM Linux 호스트에서는 uname -m일반적으로 를 반환하는 aarch64반면, Docker에서는 를 보고해야 합니다 arm64. 이 두 이름은 이 맥락에서 동일한 아키텍처 제품군을 나타냅니다.

물리적 머신이 ARM64임에도 불구하고 Docker에서 AMD64로 보고되는 경우, 원격 Docker 컨텍스트, 가상 머신 또는 다른 백엔드를 사용하는 Docker Desktop 중 어떤 환경을 사용하고 있는지 확인하십시오. 계속 진행하기 전에 이러한 모호성을 해결해야 합니다. 그렇지 않으면 배포하는 동안 한 시스템을 검사하게 될 수 있습니다.

아키텍처 불일치를 나타내는 오류는 무엇입니까?

일반적인 신호로는 레지스트리 메시지 나 명시적으로 구성된 Compose 서비스 등이 exec format error있습니다 . 이러한 메시지는 일반적인 "컨테이너가 종료되었습니다" 출력보다 플랫폼 불일치를 나타내는 더 강력한 증거입니다.no matching manifest for linux/arm64platform: linux/amd64

2단계: 이미지를 가져오기 전에 Collabora 이미지 태그를 정확히 확인하세요.

과거의 모든 태그가 현재의 태그와 동일한 플랫폼 지원을 제공한다고 가정하지 마십시오 latest. 배포 환경에서 해당 태그의 레지스트리 메타데이터를 검사하십시오.

docker buildx imagetools inspect collabora/code:latest

Docker의 `buildx imagetools inspect` 문서에는 이 명령이 레지스트리 이미지에 포함된 플랫폼을 표시하는 방법이 설명되어 있습니다. 또한 `docker install imagetools inspect` 명령을 사용할 수도 있습니다 . Docker는 매니페스트 검사 참조docker manifest inspect 에서 해당 명령에 대한 설명을 제공합니다 .

해당 태그가 표시 되면 linux/arm64멀티 플랫폼 태그를 사용하여 Docker가 올바른 이미지를 선택하도록 할 수 있습니다. 명확한 문제 해결 테스트를 위해 공식 저장소에도 해당 태그가 나열되어 있습니다 latest-arm64. 장기간 운영되는 프로덕션 환경의 경우, 새 릴리스가 게시될 때마다 태그가 변경되므로 latest테스트 를 거친 정확한 버전의 태그를 사용하는 것이 재현하기 더 쉽습니다.latest

고정된 태그에 ARM64가 포함되어 있지 않은 경우 다음 세 가지 선택 사항이 있습니다.

3단계: 실수로 설정된 AMD64 오버라이드를 제거하고 깔끔하게 다운로드합니다.

흔히 발생하는 오류는 Collabora 이미지 자체의 문제가 아니라, 잘못된 플랫폼을 강제로 지정하는 배포 파일 때문입니다. Docker Compose는 platform대상 운영 체제 및 아키텍처를 이미지 변형을 선택하는 데 사용하도록 정의합니다. Docker Compose 서비스 참조에는 다음과 같은 값이 나와 있습니다 linux/arm64/v8.

ARM64 호스트에서 이 설정은 의심스럽습니다.

services:
  collabora:
    image: collabora/code:latest
    platform: linux/amd64

에뮬레이션이 필요하지 않은 경우 해당 줄을 삭제하고 Docker가 호스트 네이티브 버전을 선택하도록 하십시오. 또는 platform: linux/arm64아키텍처를 명시적으로 지정하려는 경우 해당 줄을 지정하십시오.

그런 다음 실패한 컨테이너만 제거하고 이미지를 다시 다운로드하십시오. 특별한 이유가 없는 한 영구 데이터는 삭제하지 마십시오.

docker compose down
docker image rm collabora/code:latest 2>/dev/null || true
docker pull --platform linux/arm64 collabora/code:latest
docker compose up -d

진단 실행을 위해 전용 아키텍처 태그를 사용하는 경우, 해당 태그를 대체하십시오 collabora/code:latest-arm64. 배포가 정상적으로 작동하는 것을 확인한 후에는 프로덕션 시스템을 계속 이동하는 태그에 두는 대신, 테스트를 거친 26.04.x ​​태그와 같은 특정 릴리스를 고정하는 것을 고려하십시오.

4단계: 통합 문제 해결 전에 CODE가 시작되는지 확인하십시오.

컨테이너를 다시 생성한 후 상태와 로그를 확인하십시오.

docker compose ps
docker compose logs --tail=100 collabora

단일 컨테이너 배포의 경우, 이에 상응하는 명령은 docker ps -a와 입니다 docker logs --tail=100 <container-name>.

첫 번째 성공 기준은 컨테이너가 정상적으로 작동하고 매니페스트 또는 실행 파일 형식 오류로 더 이상 실패하지 않는 것입니다. 그 후에야 포트 9980 연결성, 리버스 프록시 설정, TLS, 허용된 WOPI 호스트 또는 애플리케이션 통합으로 넘어갈 수 있습니다. 현재 배포 매개변수를 확인하려면 Collabora의 공식 CODE Docker 문서를 참조하십시오.

초보자들이 흔히 저지르는 실수들을 피하는 방법

공식 이미지를 확인하기 전에 QEMU를 설치하세요.

소프트웨어가 다른 CPU 아키텍처용으로만 존재하는 경우 에뮬레이션이 유용할 수 있지만, 현재 Collabora CODE 이미지에는 ARM64 변형이 포함되어 있습니다. 에뮬레이션을 먼저 추가하면 실제 문제를 가릴 수 있고 고려해야 할 요소가 하나 더 추가됩니다. 필요한 CODE 버전에서 ARM64 네이티브 버전을 제공하는 경우 네이티브 ARM64를 사용하는 것이 좋습니다.

"최신"과 오래된 고정 태그를 동일하다고 가정합니다.

플랫폼 지원 여부는 특정 이미지 태그 및 매니페스트에 따라 결정됩니다. 최신 태그는 ARM64를 지원하지만 이전 릴리스는 지원하지 않을 수 있습니다. Compose 파일에서 정확한 참조를 확인하십시오.

이전 가이드에서 플랫폼을 linux/amd64로 설정했기 때문에 강제로 플랫폼을 linux/amd64로 지정합니다.

이로 인해 네이티브 ARM64 이미지가 존재하더라도 ARM64 호스트가 x86-64 변형을 가져올 수 있습니다. 에뮬레이션을 사용해야 하는 명확한 이유가 있고 이를 검증받은 경우가 아니라면 오버라이드를 제거하십시오.

프로세스가 실행되기 전에 WOPI, SSL 또는 프록시 설정을 변경하는 것

exec format errorCollabora가 대부분의 애플리케이션 수준 구성을 의미 있게 처리하기 전에 문제가 발생합니다. 먼저 아키텍처 선택을 수정하십시오. 네트워킹 및 WOPI 문제 해결은 나중에 진행하십시오 .

진단 중 볼륨 삭제

아키텍처 불일치가 발생하는 경우 일반적으로 영구 데이터를 삭제할 필요는 없습니다. 롤백이 용이하도록 수정 범위를 좁게 유지하십시오.

ARM64 이미지 파일이 여전히 존재한다면 어떻게 해야 할까요?

매니페스트에 해당 변형이 명확하게 포함되어 있고 linux/arm64Docker가 해당 변형을 가져오는 경우, 아키텍처는 더 이상 주요 원인이 아닙니다. 그 시점에서 캡처를 수행하세요.

• docker compose ps또는docker ps -a
• 마지막 100~200개 로그 라인
• 정확한 코드 태그
• Docker Engine 및 Compose 버전
• Compose 서비스 정의의 비공개 부분

그런 다음 실제 로그 메시지에 따라 권한, 마운트된 경로, 보안 프로필, 메모리 부족, 포트 충돌, 인증서 또는 WOPI 구성을 조사하십시오. 실행 중인 이미지가 ARM64임을 확인한 후에는 아키텍처를 반복적으로 변경하지 마십시오.

실질적인 의사결정 경로

1. 호스트가 ARM64가 아닌 경우 ARM64 전용 수정 사항 사용을 중단하고 실제 플랫폼을 진단하십시오.
2. 호스트가 ARM64이지만 선택한 CODE 태그에 ARM64 매니페스트가 없는 경우, 지원되는 네이티브 태그로 이동하거나 의도적으로 다른 호스팅 전략을 선택하십시오.
3. 태그가 ARM64를 지원하지만 Compose에서 AMD64를 강제로 사용하도록 설정하는 경우, 해당 platform설정을 제거하거나 수정하십시오.
4. 만약 올바른 ARM64 이미지가 여전히 존재한다면, CPU 아키텍처를 탓하기보다는 일반적인 Collabora 시작 문제로 간주하고 로그를 확인하십시오.

결론적으로

최신 ARM64 시스템에서 권장되는 해결 방법은 일반적으로 에뮬레이션이 아닙니다. 2026년 10월 7일 기준으로 확인된 바와 같이, 현재 Collabora의 공식 CODE 태그에는 네이티브 ARM64 이미지가 포함되어 있습니다. 호스트에서 aarch64/를 확인하고 arm64, 정확한 이미지 매니페스트를 검사하고, 오래되었거나 강제로 사용된 AMD64 참조를 제거하고, ARM64 호환 이미지를 다시 다운로드한 후 컨테이너가 계속 실행되는지 확인하십시오. 이 절차를 따르면 초보자도 쉽게 문제를 해결할 수 있으며, 관련 없는 SSL, 프록시 또는 WOPI 변경 사항으로 인해 기본적인 플랫폼 불일치가 가려지는 것을 방지할 수 있습니다.