Docker Compose를 사용하여 Ubuntu에 ownCloud Infinite Scale을 설치하는 방법

Docker Compose 설치를 완료하고 실행했는데도 docker compose up -downCloud에 접속할 수 없는 경우가 있습니다. 이는 Infinite Scale에서 가장 흔하게 발생하는 실제적인 오류 패턴입니다. 컨테이너는 존재하지만 DNS, TLS, 스토리지 경로 또는 필수 환경 변수 값 때문에 스택을 사용할 수 없는 상황입니다.

이 가이드는 ownCloud에서 제공하는 단일 서버 배포용 프로덕션 환경 지향 Docker Compose 방식을 사용합니다. 현재 ownCloud 문서 페이지는 9.0 개발 문서 아래에 게시되어 있지만, 다운로드 가능한 프로덕션 예제는 최신 안정 버전을 사용하며 현재 8.2 안정 브랜치를 가리킨다고 명시되어 있습니다. 이 차이점을 명확히 해야 합니다. 개발 빌드를 의도적으로 사용하려는 경우가 아니라면 개발 이미지 태그를 프로덕션 서버에 복사하지 마십시오.

아래 설정은 HTTPS를 사용하는 리버스 프록시 뒤에 하나의 Infinite Scale 인스턴스를 설치하려는 가정 및 소규모 조직에 적합합니다. 이 설정은 Ubuntu LTS, Docker Engine, Docker Compose 플러그인, 사용자가 관리하는 도메인, 그리고 서버 관리자 권한이 필요하다고 가정합니다. ownCloud의 프로덕션 예제에서는 기본적으로 활성화된 서비스에 약 4~6GB의 RAM을 권장하며, 최소한 ownCloud 도메인이 필요합니다. 선택적인 사무실 통합 기능을 사용하려면 별도의 서브도메인이 필요합니다.

시작하기 전에: 네트워크 및 스토리지 관련 문제를 먼저 해결하세요.

Compose 파일을 다운로드하는 것부터 시작하지 마십시오. 먼저 스택이 이미 실행된 후 수정하기 가장 어려운 항목들을 확인하십시오.

• DNS: 선택한 호스트 이름(예: ocis.example.com)은 서버의 공용 IP 주소로 확인되어야 합니다.
• 방화벽 및 NAT: 인터넷에 연결된 설치 환경에서는 리버스 프록시 및 인증서 흐름을 위해 TCP 80 및 443 포트에 접근 가능해야 합니다. 관리에는 일반적으로 TCP 22 포트의 SSH 연결이 필요합니다.
• 영구 저장소: Docker에서 관리하는 볼륨은 편리하지만, 프로덕션 시스템에서는 일반적으로 구성 및 사용자 데이터를 위한 명확한 경로를 설정하여 백업 및 용량 계획을 더 쉽게 수행할 수 있습니다.
• 이메일 발신자: ownCloud에서 제공하는 예제 이메일 발신자는 SMTP_SENDERSMTP 릴레이를 아직 구성하지 않았더라도 설정해야 합니다.

이러한 요구 사항은 ownCloud Infinite Scale 서버 공식 설치 가이드에 자세히 설명되어 있습니다 . Docker 자체의 경우, 오래된 배포판 패키지를 사용하는 대신 Docker의 최신 Ubuntu Engine 설치 지침 및 Compose 플러그인 지침을 따르십시오.

1. Docker 및 Docker Compose를 확인합니다.

서버에서 먼저 운영 체제를 업데이트한 다음 Docker Engine과 Compose 플러그인이 사용 가능한지 확인하십시오.

sudo apt-get update && sudo apt-get upgrade
docker --version
docker compose version

중요한 것은 이러한 명령에서 출력되는 특정 버전 번호가 아닙니다. 두 명령이 모두 성공적으로 실행되고 Compose가 사용 가능한 상태인지 확인하는 것입니다 docker compose. ownCloud의 가이드에서는 Ubuntu에 내장된 Docker 패키지에 의존하는 대신 Docker 자체 저장소에서 Docker를 설치할 것을 권장합니다. 내장 패키지는 업데이트가 지연될 수 있기 때문입니다.

2. 공식 안정 버전 Compose 예제를 다운로드하세요.

ownCloud는 관리자가 프로덕션 스택을 처음부터 구축하도록 요구하는 대신, 완전한 Compose 배포 예제를 제공합니다. 확인 당시 문서에 따르면 현재 프로덕션 다운로드는 stable-8.29.0 문서가 아직 개발 버전으로 표시되어 있기 때문에 해당 브랜치를 기반으로 합니다.

공식 워크플로는 deployments/examples/ocis_full디렉토리를 다운로드하고, 생성된 아카이브를 서버로 전송한 다음, 와 같은 경로에 압축을 해제합니다 /opt/compose/ocis/ocis_full. 정확한 아카이브 이름은 안정화 버전에서 변경될 수 있으므로, 이전 튜토리얼의 파일 이름을 하드코딩하는 대신 최신 ownCloud 문서에 나와 있는 다운로드 링크를 사용하세요.

압축 해제 후 배포 디렉토리로 이동하여 내용을 확인하십시오.

cd /opt/compose/ocis/ocis_full
ls -la

예제에서 제공하는 Compose 파일, 구성 디렉터리 및 파일을 확인할 수 있습니다 .env. 기존에 추출된 예제를 업데이트하는 경우, .env먼저 백업해 두세요. ownCloud는 새 패키지를 추출하면 기존 파일이 덮어쓰여질 수 있다고 경고합니다.

3. .env 파일을 신중하게 구성하십시오.

처음 시작할 때 발생하는 문제의 대부분은 환경 변수 파일에서 비롯됩니다. .env압축 해제한 디렉토리에서 환경 변수를 편집하고, 순서대로 설정을 조정하십시오.

공개 도메인을 설정하세요

OCIS_DOMAIN예를 들어 `/hostname`과 같이 이미 서버로 확인되는 호스트 이름으로 설정하십시오 . Collabora 또는 ONLYOFFICE를 활성화하는 경우 해당 서비스의 공식 호스트 이름도 구성하십시오. DNS 레코드와 다른 ocis.example.com도메인을 사용하지 마십시오 ..env

TLS를 준비합니다

인터넷에 노출되는 배포 환경의 경우, 공식 예제에서는 Traefik과 Let's Encrypt를 사용합니다. TRAEFIK_ACME_MAIL실제 본인이 관리하는 이메일 주소로 설정하세요. ownCloud는 먼저 Let's Encrypt 스테이징 CA를 사용하여 인증서 발급이 정상적으로 작동하는지 확인한 후 프로덕션 환경으로 전환할 것을 권장합니다. 이렇게 하면 문제 해결 중에 Let's Encrypt 사용량 제한에 걸릴 가능성을 줄일 수 있습니다.

데이터 및 구성 위치를 선택하십시오.

호스트 마운트 스토리지를 사용하려면 계획된 영구 경로를 설정하십시오 OCIS_CONFIG_DIR. OCIS_DATA_DIR기본 파일 시스템에 충분한 용량이 있는지 확인하고 백업 프로세스에 구성과 데이터가 모두 포함되도록 하십시오.

SMTP 발신자를 설정하세요

최소한 SMTP 설정을 정의하십시오 SMTP_SENDER. 알림을 보낼 준비가 되면 SMTP 호스트, 포트, 사용자 이름, 비밀번호, 인증 방법 및 보안 설정을 모두 추가할 수 있습니다.

4. Compose 구성을 검증한 다음 스택을 시작합니다.

컨테이너를 다운로드하고 시작하기 전에 Compose에게 조립된 구성을 렌더링하고 유효성을 검사하도록 요청하십시오.

docker compose config

이 방법이 실패하면 구문 오류나 누락된 변수를 수정하고 계속 진행하십시오. 이 검사는 배포가 부분적으로 시작된 경우 진단하는 것보다 훨씬 빠릅니다.

구성이 성공적으로 렌더링되면 분리 모드로 배포를 시작하십시오.

docker compose up -d

Compose는 필요한 이미지를 다운로드하고 예제에 정의된 서비스를 시작합니다. 처음 실행할 때는 이미지를 다운로드하고 인증서를 요청해야 하므로 시간이 더 오래 걸릴 수 있습니다.

처음 시동이 걸리지 않으면 가장 쉬운 문제부터 가장 어려운 문제 순으로 해결해 보세요.

컨테이너 상태를 확인하세요

어떤 서비스에 오류가 발생했는지 추측하기보다는 먼저 '작성하기' 화면에서 시작하세요.

docker compose ps -a --format "table {{.Service}}	{{.State}}	{{.ID}}"

서비스가 반복적으로 종료되는 현상은 브라우저 오류보다 더 유용합니다. 왜냐하면 문제가 특정 컨테이너에 국한되어 있음을 보여주기 때문입니다.

인증서 문제를 확인하려면 Traefik 로그를 읽으십시오.

ownCloud의 가이드에서는 HTTPS 연결이 작동하지 않을 경우 Traefik을 먼저 확인하도록 권장합니다. 일반적인 원인으로는 잘못된 ACME 연락처 이메일, 닫힌 포트 80/443, 또는 DNS 오류가 NXDOMAIN을 반환하거나 잘못된 IP 주소를 가리키는 경우 등이 있습니다. ACME 문제를 해결한 후에는 실패한 테스트 데이터가 포함된 인증서 볼륨만 삭제하는 공식 지침을 따르십시오. 모든 볼륨을 삭제하지 마십시오.

ownCloud 서비스 로그를 확인하세요

컨테이너 ID를 찾은 docker compose ps다음 해당 로그를 검사하십시오.

docker logs -f <container_id>

초기화 프로세스는 첫 실행 시 초기 구성을 생성할 수 있습니다. ownCloud는 ocis init || true; ocis serverCompose 배포에 대한 명령 패턴을 문서화하므로 구성이 이미 존재하는 경우 초기화가 건너뛰어집니다.

`docker compose down -v` 명령어를 함부로 사용하지 마십시오.

배포를 중지하려면 다음을 사용하십시오.

docker compose down --remove-orphans

-v의도적으로 볼륨을 제거하려는 경우가 아니라면 볼륨 을 추가하지 마십시오 . ownCloud는 볼륨을 추가하면 배포 데이터가 삭제될 수 있다고 명시적으로 경고합니다. TLS 문제 해결 중에 일회용 인증서 볼륨을 제거해야 하는 경우 해당 볼륨을 선택적으로 삭제하십시오.

설치가 실제로 완료되었는지 확인하는 방법

성공 여부 docker compose up -d는 단 한 번의 확인만으로 판단할 수 없습니다. 네 단계에 걸쳐 결과를 검증하십시오.

1. DNS: 공용 호스트 이름이 올바른 서버 주소로 확인됩니다.
2. TLS: 브라우저가 인증서 경고 없이 HTTPS를 통해 사이트에 접속합니다. Let's Encrypt 스테이징 CA를 의도적으로 사용한 경우, 먼저 스테이징 인증서를 확인한 후 문서에 설명된 대로 프로덕션 환경으로 전환하십시오.
3. 컨테이너: docker compose ps -a 서비스가 재시작되거나 종료되지 않고 예상대로 실행 중임을 보여줍니다.
4. 사용 방법: 설정된 ownCloud URL을 열고, 설정하거나 가져온 초기 관리자 자격 증명으로 로그인한 다음, 폴더를 생성하고 간단한 테스트 파일을 업로드할 수 있습니다.

새로 배포할 경우, 설명서에 따르면 기본 관리자 사용자 이름은 이며 admin, 암호는 구성 중에 수동으로 설정하거나 설명서에 나와 있는 시작 로그/재설정 절차를 통해 확인할 수 있습니다. 초기 암호는 즉시 변경하고, 알려진 기본 자격 증명을 사용하여 운영 환경을 구축하지 마십시오.

기본 파일 서비스가 제대로 작동하면 선택적으로 협업 구성 요소나 고급 통합 기능을 추가하세요. 핵심 배포가 안정적으로 완료된 후에 이러한 작업을 수행하면 문제 해결이 훨씬 쉬워집니다. 오피스 제품군, 외부 ID 공급자 또는 바이러스 백신 서비스의 오류가 기본 DNS 및 TLS 문제와 섞이지 않기 때문입니다.

안정적인 배포를 위한 유지 관리 참고 사항

업그레이드하기 전에 데이터와 구성을 백업하고 버전별 마이그레이션 참고 사항을 읽어보세요. ownCloud 설명서에서는 일반적인 이미지 업데이트와 구성 변경이 필요한 업그레이드를 구분하고 있습니다. 일반적인 유지 관리 절차는 스택을 중지하고 이미지를 가져온 다음, 불필요한 항목을 정리하면서 다시 시작하는 것이지만, 버전을 변경하기 전에 릴리스별 업그레이드 가이드를 확인하는 것이 좋습니다.

운영 환경에서는 디스크 사용량도 모니터링해야 합니다. Docker 관리 볼륨은 시작하기에는 간편하지만, 운영 체제와 사용자 파일이 동일한 파일 시스템을 공유하는 경우 저장 공간 증가 속도가 예상보다 빠를 수 있습니다. 상당한 양의 데이터가 예상되는 경우, 처음부터 전용 저장 경로를 사용하거나 문서화된 볼륨 관리 절차에 따라 컨테이너 사용자에게 올바른 소유권을 부여하여 데이터를 마이그레이션해야 합니다.