Docker Compose와 외부 Nginx 리버스 프록시를 활용한 Nextcloud AIO 설치 안내서

1. 서론: Nextcloud AIO 아키텍처 및 리버스 프록시 연동 심층 분석

Nextcloud AIO(All-in-One)는 Docker를 기반으로 복잡한 Nextcloud 환경을 간편하게 배포하고 유지보수할 수 있도록 설계된 공식 설치 방법이다. 그러나 그 편리함의 이면에는 다른 Docker 애플리케이션과는 구별되는 독특한 아키텍처가 존재하며, 이를 이해하는 것이 특히 외부 리버스 프록시와 연동할 때 성공의 열쇠가 된다.

1.1 Nextcloud AIO의 컨테이너 기반 구조 해부: 마스터 컨테이너의 역할과 서비스 컨테이너 관리 방식

Nextcloud AIO의 핵심은 ’마스터 컨테이너(mastercontainer)’에 있다.1 사용자가 docker-compose.yml 파일을 통해 실행하는 것은 오직 이 마스터 컨테이너 하나뿐이다. 이 컨테이너는 단순한 애플리케이션 컨테이너가 아니라, 전체 Nextcloud 스택을 관리하는 일종의 경량 컨테이너 오케스트레이터(Orchestrator) 역할을 수행한다.3

마스터 컨테이너는 호스트 시스템의 Docker 소켓(/var/run/docker.sock)에 직접 접근하여 Docker API를 제어한다.5 사용자가 웹 기반 관리 인터페이스(AIO Interface)에 접속하여 Nextcloud Office, Talk, 고성능 백엔드, 데이터베이스(PostgreSQL), 캐시(Redis) 등의 구성 요소를 선택하면, 마스터 컨테이너는 이 요청에 따라 필요한 Docker 이미지를 다운로드하고, 적절한 설정과 함께 각각의 서비스 컨테이너를 동적으로 생성, 시작, 연결 및 관리한다.1 이러한 방식은 설치 과정을 극도로 단순화시키지만, 일반적인 선언적(declarative) 방식의 Docker Compose 환경, 즉 docker-compose.yml 파일에 모든 서비스가 명시된 환경과는 근본적으로 다르다. AIO는 사용자의 상호작용에 따라 동적으로(dynamically) 시스템 상태를 변경하는 절차적(procedural) 모델을 따르기 때문에, 설치 과정 중 발생하는 문제의 원인을 파악하기 위해서는 이 동적 생성 메커니즘을 인지하고 있어야 한다.

1.2 외부 리버스 프록시 연동의 필요성 및 이점: SSL 오프로딩, 중앙 집중식 접근 제어, 다중 서비스 호스팅

사용자의 요구사항과 같이 이미 Nginx 리버스 프록시 서버와 SSL/TLS 인증서가 구축된 환경에서는 AIO를 기존 인프라에 통합하는 것이 표준적인 고성능 아키텍처 구성 방식이다. AIO 자체는 Caddy를 기반으로 한 자동 HTTPS 설정 기능을 내장하고 있지만, 외부 프록시를 사용함으로써 다음과 같은 이점을 얻을 수 있다.7

SSL/TLS 오프로딩(Offloading): 암호화 및 복호화에 따르는 연산 부하를 전문 프록시 서버에 위임하여 Nextcloud 애플리케이션 서버의 부담을 줄인다.
중앙 집중식 관리: 모든 웹 서비스의 접근 지점을 단일화하여 도메인 기반 라우팅, 접근 제어, 로깅, 보안 정책(예: 웹 방화벽, WAF)을 일관되게 적용할 수 있다.
유연성 및 확장성: Nextcloud 외 다른 여러 서비스를 동일한 서버와 도메인 체계 하에서 손쉽게 호스팅할 수 있다.

1.3 설치 과정의 핵심 과제: 도메인 유효성 검사 및 트래픽 흐름의 이해

외부 리버스 프록시 환경에서 Nextcloud AIO를 설치할 때 가장 큰 난관은 초기 ‘도메인 유효성 검사(Domain Validation)’ 단계에서 발생한다. 사용자가 AIO 인터페이스에 자신의 도메인을 입력하면, AIO는 해당 도메인을 통해 외부에서 실제로 서버에 접속할 수 있는지 확인하는 절차를 거친다. 이 검증을 위해 마스터 컨테이너는 nextcloud-aio-domaincheck라는 이름의 임시 컨테이너를 동적으로 실행시킨다.9

이때 Nginx 리버스 프록시는 외부로부터 들어오는 요청을 이 임시 domaincheck 컨테이너로 정확하게 전달해야만 한다. 검증이 성공적으로 완료되면, 이 임시 컨테이너는 자동으로 소멸하고, 이후 실제 Nextcloud 서비스 트래픽을 처리할 영구적인 nextcloud-aio-apache 컨테이너가 그 자리를 대신하게 된다. 따라서 설치 과정 동안 Nginx의 프록시 대상이 되는 내부 컨테이너가 변경된다는 점을 인지하고, 이 두 단계의 트래픽 흐름을 모두 처리할 수 있도록 Nginx를 올바르게 구성하는 것이 설치 성공의 가장 중요한 관건이다.

2. 부: Docker Compose를 이용한 Nextcloud AIO 배포

본격적인 설치는 리버스 프록시 환경에 최적화된 docker-compose.yml 파일을 작성하는 것에서 시작한다. 이 파일은 Nextcloud AIO 마스터 컨테이너를 정의하고, 외부 Nginx와의 원활한 통신을 위한 필수 환경을 설정하는 역할을 한다.

2.1 `docker-compose.yml` 파일 작성: 리버스 프록시 환경에 최적화된 구성 파일 상세 분석

프로젝트를 위한 디렉토리를 생성하고, 그 안에 docker-compose.yml이라는 이름으로 아래 내용의 파일을 작성하라.

version: '3.8'

volumes:
nextcloud_aio_mastercontainer:
name: nextcloud_aio_mastercontainer

services:
nextcloud:
image: nextcloud/all-in-one:latest
container_name: nextcloud-aio-mastercontainer
restart: always
init: true

ports:
# AIO 관리 인터페이스 접속을 위한 포트.
# 호스트의 8080 포트가 사용 중이라면 왼쪽 포트 번호(예: 8181)를 변경할 수 있다.
- 8080:8080

environment:
# 리버스 프록시가 트래픽을 전달할 내부 Apache 컨테이너의 포트를 지정한다.
- APACHE_PORT=11000
# (선택 사항) Nextcloud 사용자 데이터를 저장할 호스트 경로를 지정한다.
# - NEXTCLOUD_DATADIR=/mnt/data/nextcloud
# Docker 소켓 경로가 기본값이 아닐 경우에만 설정한다.
# - WATCHTOWER_DOCKER_SOCKET_PATH=/var/run/docker.sock

volumes:
# AIO 마스터 컨테이너의 설정 데이터 볼륨. 절대 변경하지 말 것.
- nextcloud_aio_mastercontainer:/mnt/docker-aio-config
# 마스터 컨테이너가 다른 컨테이너를 제어하기 위해 Docker 소켓에 접근.
- /var/run/docker.sock:/var/run/docker.sock:ro

각 구성 요소의 역할은 다음과 같다.

services.nextcloud: 이 서비스는 AIO 스택 전체를 관리할 마스터 컨테이너를 정의한다.
image: nextcloud/all-in-one:latest: Nextcloud AIO의 공식 최신 이미지를 사용하도록 지정한다.2
container_name: nextcloud-aio-mastercontainer: 컨테이너의 이름을 명시적으로 지정한다. AIO의 내부 업데이트 및 관리 메커니즘이 이 이름에 의존하므로, 절대로 변경해서는 안 된다.2
init: true: 컨테이너 내에서 좀비 프로세스가 발생하는 것을 방지하여 안정성을 높이는 권장 옵션이다.2
ports: 외부 리버스 프록시를 사용하므로, AIO가 자체적으로 Let’s Encrypt 인증서를 발급받기 위해 필요한 80번과 8443번 포트는 노출할 필요가 없다. 오직 AIO 관리 인터페이스에 접속하기 위한 8080번 포트만 호스트에 노출시킨다.2 만약 호스트 시스템에서 8080 포트를 다른 서비스가 사용하고 있다면, 8181:8080과 같이 왼쪽의 호스트 포트 번호만 변경할 수 있다.10
volumes: 볼륨 설정은 AIO의 상태 유지와 기능 수행에 있어 매우 중요하다.
nextcloud_aio_mastercontainer:/mnt/docker-aio-config: 마스터 컨테이너의 모든 설정, 생성된 컨테이너들의 정보, 상태 데이터 등이 저장되는 핵심 볼륨이다. 내장된 백업 및 복원 기능이 이 볼륨 경로를 기준으로 동작하므로, 경로를 절대 변경해서는 안 된다.2
/var/run/docker.sock:/var/run/docker.sock:ro: 마스터 컨테이너가 호스트의 Docker 데몬과 통신하여 다른 컨테이너들을 생성하고 관리할 수 있도록 Docker 소켓 파일을 마운트한다. ro (read-only) 옵션을 추가하여 컨테이너가 소켓 파일을 수정할 수 없도록 제한함으로써 보안을 강화한다.5

2.2 핵심 환경 변수 설정 및 해설: 각 변수의 기능과 최적 값 설정 가이드

environment 섹션은 AIO 컨테이너의 동작을 제어하는 중요한 부분이다. 특히 리버스 프록시 연동 시에는 다음 변수들의 의미를 정확히 이해하고 설정해야 한다.

APACHE_PORT=11000: 이 변수는 AIO가 내부적으로 생성할 nextcloud-aio-apache 웹 서버 컨테이너가 리스닝할 포트 번호를 지정한다. 외부 Nginx 리버스 프록시는 바로 이 포트로 트래픽을 전달(proxy_pass)해야 한다. 11000은 충돌 가능성이 낮아 관례적으로 널리 사용되는 포트 번호다.5
APACHE_IP_BINDING: 이 변수는 Apache 컨테이너가 어떤 IP 주소의 연결을 수신할지 결정한다.
만약 Nginx 리버스 프록시가 AIO 컨테이너와 동일한 호스트에서 Docker 컨테이너로 실행된다면, APACHE_IP_BINDING=127.0.0.1로 설정하여 로컬호스트로부터의 연결만 허용하는 것이 보안상 가장 안전하다.5
사용자의 경우처럼 Nginx가 별도의 서버에 위치하거나 호스트에 직접 설치된 경우에는, 이 변수를 설정하지 않거나 APACHE_IP_BINDING=0.0.0.0으로 설정하여 모든 네트워크 인터페이스로부터의 연결을 허용해야 한다. 이 가이드의 docker-compose.yml 예제는 후자의 경우를 가정하여 변수 자체를 생략하였다.
NEXTCLOUD_DATADIR=/path/on/host/data: 기본적으로 Nextcloud의 사용자 데이터는 Docker가 관리하는 볼륨 내에 저장된다. 만약 데이터를 호스트 시스템의 특정 경로(예: 대용량 스토리지 마운트 지점)에 직접 저장하고 관리하고 싶다면, 이 변수를 사용하여 절대 경로를 지정할 수 있다. 이 설정은 반드시 최초 설치 시에만 지정해야 하며, 한번 설치가 완료된 후에는 변경할 수 없으므로 신중하게 결정해야 한다.5

다음 표는 사용자의 환경에 맞춘 핵심 환경 변수를 요약한 것이다.

변수명	목적	권장 설정 (사용자 환경 기준)
`APACHE_PORT`	리버스 프록시가 트래픽을 전달할 내부 Apache 컨테이너의 포트.	`11000`
`APACHE_IP_BINDING`	Apache 컨테이너가 수신 대기할 IP 주소.	설정 안 함 (Nginx가 별도 서버이므로). 동일 호스트라면 `127.0.0.1`.
`NEXTCLOUD_DATADIR`	Nextcloud 사용자 데이터가 저장될 호스트의 절대 경로.	(선택 사항) 예: `/mnt/storage/nextcloud_data`
`SKIP_DOMAIN_VALIDATION`	초기 설정 시 도메인 연결성 검사를 건너뜀.	`false` 또는 설정 안 함 (정상적인 설치 권장).
`WATCHTOWER_DOCKER_SOCKET_PATH`	Docker 소켓 경로가 기본값이 아닐 경우 지정.	`/var/run/docker.sock` (대부분의 리눅스 환경)

이 변수들은 단순한 설정 값을 넘어, AIO의 동적 아키텍처가 외부 환경과 어떻게 상호작용할지를 결정하는 중요한 인터페이스다. 각 변수의 의미를 이해하고 설정하는 것은 문제 발생 시 원인을 추적하고 해결하는 능력을 크게 향상시킨다.

2.3 AIO 마스터 컨테이너 실행 및 초기 상태 확인

docker-compose.yml 파일 작성이 완료되었다면, 터미널에서 해당 파일이 위치한 디렉토리로 이동하여 다음 명령어를 실행한다.

sudo docker compose up -d

이 명령어는 백그라운드(-d)에서 Nextcloud AIO 마스터 컨테이너를 시작한다. 컨테이너가 정상적으로 시작되었는지 확인하기 위해 로그를 확인하는 것이 중요하다.

sudo docker compose logs -f

로그가 출력되면서 마지막 부분에 다음과 유사한 메시지가 나타나면 성공적으로 실행된 것이다.4

...
One last step: Please open the Nextcloud AIO Interface now on port 8080 of this server.
E.g. https://192.168.1.100:8080

Hint: You need to accept the self-signed certificate in order to proceed.

The initial password for the AIO interface is: [매우 긴 초기 암호 구문]

여기서 출력되는 [매우 긴 초기 암호 구문]은 3부에서 AIO 관리 인터페이스에 최초 로그인할 때 사용되므로 반드시 안전한 곳에 복사해 두어야 한다. 만약 이 로그를 놓쳤거나 분실했다면, 다음 명령어를 실행하여 언제든지 다시 확인할 수 있다.12

sudo docker exec nextcloud-aio-mastercontainer grep password /mnt/docker-aio-config/data/configuration.json

이제 마스터 컨테이너가 실행 준비를 마쳤으므로, 다음 단계인 Nginx 리버스 프록시 구성을 진행할 차례다.

3. 부: 기존 Nginx 리버스 프록시 서버 구성

이 단계에서는 이미 운영 중인 Nginx 리버스 프록시 서버에 Nextcloud AIO로 요청을 전달하기 위한 구성을 추가한다. 이 설정은 단순히 트래픽을 중계하는 것을 넘어, Nextcloud가 프록시 환경에서 올바르게 동작하는 데 필요한 중요 정보들을 함께 전달하는 역할을 한다.

3.1 Nginx 구성 파일(`server` 블록) 상세 지침

Nginx 서버에서 Nextcloud에 사용할 도메인의 server 블록 설정 파일을 연다. 일반적으로 /etc/nginx/sites-available/ 디렉토리에 위치하며, 사용자는 이미 SSL 설정(listen 443 ssl, ssl_certificate 등)이 완료된 기존 파일에 아래 내용을 추가하거나 수정하면 된다.

server {
listen 443 ssl http2;
listen [::]:443 ssl http2;
server_name nextcloud.your-domain.com; # 본인의 도메인으로 변경

# SSL 설정 (이미 구성되어 있을 것임)
ssl_certificate /path/to/your/fullchain.pem;
ssl_certificate_key /path/to/your/privkey.pem;
#... 기타 SSL 관련 설정...

# 보안 헤더 추가 (권장)
add_header Strict-Transport-Security "max-age=15552000; includeSubDomains" always;

location / {
# Nextcloud AIO 컨테이너가 실행 중인 호스트의 IP와 APACHE_PORT로 설정
proxy_pass http://<AIO_HOST_IP>:11000;

# 필수 프록시 헤더 설정
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header X-Forwarded-Host $host;
proxy_set_header X-Forwarded-Port $server_port;

# 대용량 파일 업로드를 위한 설정 (0은 무제한)
client_max_body_size 0;

# 타임아웃 설정 (필요 시 조정)
proxy_connect_timeout 60s;
proxy_send_timeout 600s;
proxy_read_timeout 600s;

# 웹소켓 지원을 위한 설정 (Nextcloud Talk, Office)
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
}

# CalDAV 및 CardDAV 자동 검색을 위한 리디렉션
location /.well-known/carddav {
return 301 $scheme://$host/remote.php/dav;
}

location /.well-known/caldav {
return 301 $scheme://$host/remote.php/dav;
}
}

각 지시어의 역할은 다음과 같다.

proxy_pass http://<AIO_HOST_IP>:11000;: 이 설정의 가장 핵심적인 부분이다. Nginx가 받은 모든 요청을 AIO 컨테이너가 실행 중인 Docker 호스트의 IP 주소(<AIO_HOST_IP>)와 docker-compose.yml에서 APACHE_PORT로 지정한 포트(11000)로 전달한다.9
proxy_set_header 지시어들: Nextcloud 애플리케이션이 자신이 리버스 프록시 뒤에서 동작하고 있음을 인지하고, 원래 클라이언트의 요청 정보를 정확히 파악하도록 돕는다.
Host $host;: 클라이언트가 최초에 요청한 도메인 이름(예: nextcloud.your-domain.com)을 그대로 전달한다.
X-Real-IP $remote_addr;: 요청을 보낸 클라이언트의 실제 IP 주소를 전달한다.
X-Forwarded-For $proxy_add_x_forwarded_for;: 클라이언트 IP와 프록시 서버의 IP를 포함한 전체 요청 경로를 전달한다.
X-Forwarded-Proto $scheme;: 원래 요청이 http였는지 https였는지 알려준다. Nginx에서 SSL을 종료(offloading)하고 내부적으로는 http로 통신하므로, 이 헤더가 없으면 Nextcloud는 모든 응답 URL을 http://로 생성하는 문제를 일으킨다.8
client_max_body_size 0;: Nextcloud의 핵심 기능인 파일 업로드를 위해 Nginx의 기본 업로드 용량 제한(보통 1MB)을 해제한다. 0은 제한 없음을 의미하며, 10G와 같이 특정 크기를 지정할 수도 있다.13
웹소켓(WebSocket) 지원 설정: Nextcloud Talk의 실시간 음성/영상 통화와 Collabora/OnlyOffice의 실시간 공동 편집 기능은 웹소켓 프로토콜을 사용한다. 위 설정은 웹소켓 연결을 정상적으로 프록시하기 위해 필수적이다.14

3.2 Nextcloud 특화 경로 재지정(Redirects): CalDAV 및 CardDAV 자동 검색을 위한 `.well-known` 경로 설정

location /.well-known/carddav와 location /.well-known/caldav 블록은 macOS, iOS, Thunderbird 등 다양한 클라이언트 애플리케이션이 사용자의 이메일 주소나 도메인만으로 캘린더(CalDAV) 및 주소록(CardDAV) 서버 설정을 자동으로 찾을 수 있도록 도와주는 표준 규약이다. 이 리디렉션을 설정하면 사용자가 수동으로 복잡한 서버 주소를 입력할 필요가 없어 편의성이 크게 향상된다.7

3.3 구성 파일 유효성 검사 및 Nginx 재시작

수정한 Nginx 구성 파일에 문법적 오류가 없는지 반드시 확인해야 한다. 터미널에서 다음 명령어를 실행한다.

sudo nginx -t

nginx: the configuration file /etc/nginx/nginx.conf syntax is ok 와 nginx: configuration file /etc/nginx/nginx.conf test is successful 메시지가 출력되면 정상이다. 오류가 발견되면 메시지를 참고하여 오타나 잘못된 지시어를 수정한 후 다시 검사한다.

검증이 완료되면, 변경된 설정을 Nginx에 적용하기 위해 다음 명령어를 실행한다.

sudo systemctl reload nginx

이제 Nginx는 nextcloud.your-domain.com으로 들어오는 모든 요청을 Nextcloud AIO 컨테이너로 전달할 준비를 마쳤다.

4. 부: Nextcloud AIO 웹 인터페이스 설정 단계별 가이드

마스터 컨테이너가 실행되고 Nginx 구성이 완료되었으므로, 이제 웹 브라우저를 통해 AIO 관리 인터페이스에 접속하여 실제 Nextcloud 인스턴스를 생성하고 초기화하는 과정을 진행한다.

4.1 AIO 관리 인터페이스 접속 및 초기 암호 구문(Passphrase) 확보

웹 브라우저를 열고 https://<DOCKER_HOST_IP>:8080 주소로 접속한다. <DOCKER_HOST_IP>는 1부에서 AIO 컨테이너를 실행한 서버의 IP 주소다. 이 인터페이스는 자체 서명된 SSL 인증서를 사용하므로, 브라우저에 “연결이 비공개로 설정되어 있지 않습니다“와 같은 보안 경고가 표시된다. 이는 정상적인 상황이며, ‘고급’ 또는 ‘계속 진행’ 등의 옵션을 선택하여 접속을 계속한다.1

접속하면 초기 화면에 매우 긴 암호 구문(passphrase)이 표시된다. 이 암호는 1.3 단계에서 docker compose logs를 통해 확인했던 것과 동일하다. 이 암호는 Nextcloud 관리자 암호가 아니라, AIO 관리 인터페이스 자체에 로그인하기 위한 것이다. 이 암호를 안전한 곳에 다시 한번 복사한 후, ‘Open Nextcloud AIO login’ 버튼을 클릭한다.4

표시되는 로그인 페이지에 방금 복사한 암호 구문을 붙여넣고 ‘Login’ 버튼을 클릭한다.

4.2 도메인 유효성 검사 단계 통과 전략

로그인에 성공하면, Nextcloud 인스턴스에서 사용할 도메인을 입력하는 화면이 나타난다. 여기에 2부에서 Nginx에 server_name으로 설정한 도메인(예: nextcloud.your-domain.com)을 정확하게 입력하고 ‘Submit’ 버튼을 클릭한다.17

이 버튼을 클릭하는 순간, AIO 백엔드에서는 중요한 작업이 시작된다. 마스터 컨테이너는 nextcloud-aio-domaincheck라는 임시 컨테이너를 실행시킨다. 이 컨테이너는 1부에서 설정한 APACHE_PORT(11000)를 리스닝하며, AIO 서버는 입력된 도메인을 통해 이 컨테이너에 실제로 HTTP 요청이 도달하는지 검사한다. 이 과정은 Nginx 리버스 프록시 설정, DNS 레코드, 방화벽 설정이 모두 올바르게 구성되었는지 종합적으로 테스트하는 단계다.

검증은 수십 초에서 몇 분까지 소요될 수 있다. 만약 “Domain does not point to this server“와 같은 오류 메시지와 함께 검증에 실패한다면, 이는 대부분 다음 문제 중 하나에 해당한다 9:

DNS A 또는 AAAA 레코드가 Nginx 서버의 공인 IP를 정확히 가리키고 있지 않다.
Nginx 서버 앞단의 방화벽이나 클라우드 보안 그룹에서 443 포트가 차단되어 있다.
Nginx의 proxy_pass 설정에 기재된 AIO 호스트 IP나 포트가 잘못되었다.
AIO 호스트의 방화벽이 Nginx 서버로부터의 11000 포트 접근을 차단하고 있다.

부록의 문제 해결 가이드를 참조하여 각 항목을 점검하고 문제를 해결한 후 다시 시도해야 한다.

4.3 컨테이너 생성 및 초기화

도메인 유효성 검사를 성공적으로 통과하면, 다음 설정 화면으로 이동한다. 여기서는 타임존(예: Asia/Seoul)을 설정하고, Nextcloud와 함께 설치할 추가 기능 컨테이너들을 선택할 수 있다.17

Nextcloud Office: Collabora 기반의 온라인 오피스 스위트.
High performance backend for Nextcloud Talk: Talk의 성능 향상을 위한 서버.
Imaginary: HEIC, TIFF 등 다양한 이미지 형식의 미리보기를 생성하는 도구.
ClamAV: 파일 업로드 시 바이러스를 검사하는 안티바이러스 엔진.
Fulltextsearch: 파일 내용 전체를 검색할 수 있는 강력한 검색 엔진.

필요한 구성 요소를 선택한 후 ‘Download and start containers’ 버튼을 클릭한다. 이 시점부터 마스터 컨테이너는 선택된 모든 서비스의 Docker 이미지를 다운로드하고, 컨테이너를 순서대로 실행하며, 데이터베이스를 초기화하는 등 복잡한 설치 과정을 자동으로 수행한다. 이 과정은 시스템 사양과 인터넷 속도에 따라 10분 이상 소요될 수 있으므로, 완료될 때까지 기다린다.4

4.4 최종 관리자 계정 정보 확인

모든 컨테이너의 다운로드, 시작, 초기화가 완료되면, AIO 인터페이스 화면이 갱신되면서 최종적으로 중요한 정보를 표시한다.

“Initial Nextcloud admin password”

이것이 바로 실제 Nextcloud 애플리케이션에 로그인할 때 사용할 admin 계정의 초기 비밀번호다.17 이 비밀번호는 매우 복잡하게 자동 생성되며, 일반적으로 이 화면에서만 한 번 표시되므로 반드시 복사하여 가장 안전한 곳(예: 비밀번호 관리자)에 저장해야 한다.

간혹 타이밍 문제나 브라우저 캐시 문제로 이 화면을 놓치거나, 이 비밀번호로 로그인이 되지 않는 경우가 보고되기도 한다. 그럴 경우, 브라우저 창을 새로고침하거나 닫았다가 다시 AIO 인터페이스에 접속하여 ‘Open your Nextcloud’ 버튼을 클릭한 후 로그인을 시도하면 해결될 수 있다.20

5. 부: 설치 후 검증 및 고급 설정

모든 설치 과정이 완료되었다. 이제 Nextcloud가 정상적으로 작동하는지 확인하고, 보안 설정을 검증하며, 장기적인 운영을 위한 백업 및 업데이트를 구성할 차례다.

5.1 Nextcloud 접속 및 기능 테스트

AIO 인터페이스의 ‘Open your Nextcloud’ 버튼을 클릭하거나, 웹 브라우저 주소창에 Nginx에 설정한 본인의 도메인(https://nextcloud.your-domain.com)을 직접 입력하여 접속한다.

Nextcloud 로그인 화면이 나타나면, 사용자 이름에는 admin을, 비밀번호에는 3.4 단계에서 확보한 초기 관리자 비밀번호를 입력하여 로그인한다. 성공적으로 로그인되면 Nextcloud 대시보드가 나타난다.

다음 항목들을 테스트하여 설치가 올바르게 완료되었는지 검증한다.

파일 업로드/다운로드: 데스크톱에서 샘플 파일을 드래그 앤 드롭하여 업로드해본다. 이후 해당 파일을 다시 다운로드하여 파일이 손상되지 않았는지 확인한다. 1GB 이상의 대용량 파일을 업로드하여 2.1 단계에서 설정한 Nginx의 client_max_body_size가 올바르게 적용되었는지 확인한다.
Talk/Office 기능: 만약 Talk이나 Office를 설치했다면, 해당 앱을 실행해본다. Talk에서 사용자 간 채팅이 실시간으로 이루어지는지, Office에서 새 문서를 생성하고 편집이 원활하게 되는지 확인하여 웹소켓 연결이 정상적으로 작동하는지 검증한다.
관리자 설정 확인: 우측 상단 프로필 아이콘을 클릭하여 ‘관리’ 메뉴로 이동한다. ‘개요’ 페이지에 보안 및 설정 관련 경고가 없는지 확인한다.

5.2 `config.php`의 `trusted_proxies` 설정 검증

리버스 프록시 환경에서 보안과 정확한 IP 로깅을 위해 trusted_proxies 설정은 매우 중요하다. 이 설정은 Nextcloud에게 어떤 IP 주소로부터 온 X-Forwarded-* 헤더를 신뢰할지를 알려주는 역할을 한다. AIO는 이 값을 자동으로 설정하려고 시도하지만, 올바르게 설정되었는지 수동으로 확인하는 것이 안전하다.

AIO가 실행 중인 Docker 호스트의 터미널에서 다음 명령어를 실행하여 config.php 파일의 내용을 확인한다.

sudo docker exec -it nextcloud-aio-nextcloud cat /var/www/html/config/config.php

출력된 내용 중에서 'trusted_proxies' 배열을 찾는다. 이 배열 안에는 Nginx 리버스 프록시 서버의 IP 주소가 포함되어 있어야 한다.7

잘못된 예: 172.18.0.2 와 같이 Docker 내부 네트워크의 IP가 기재된 경우.

올바른 예: Nginx 서버의 실제 IP 주소(예: 192.168.0.5)가 기재된 경우.

만약 이 값이 잘못 설정되어 있다면, Nextcloud는 클라이언트의 실제 IP를 제대로 인식하지 못하고 모든 접속을 프록시 서버로부터 온 것으로 기록하게 된다. 이는 로그인 시도 실패 감지 등 보안 기능의 오작동을 유발할 수 있다. trusted_proxies 설정이 잘못된 경우, AIO 인터페이스나 occ 명령어를 통해 수정해야 한다. 이 설정이 올바르지 않으면 악의적인 사용자가 X-Forwarded-For 헤더를 위조하여 IP 주소를 속이는 ‘IP 스푸핑’ 공격에 취약해질 수 있다.7

5.3 백업 설정 및 자동 업데이트 구성

Nextcloud AIO의 가장 강력한 기능 중 하나는 BorgBackup 기반의 통합 백업 및 자동 업데이트 시스템이다.1 다시 AIO 관리 인터페이스(https://<DOCKER_HOST_IP>:8080)에 접속하여 이를 설정한다.

백업 위치 지정: 인터페이스의 ‘Backup and restore’ 섹션으로 이동한다. 백업 파일을 저장할 호스트 시스템의 절대 경로를 입력한다 (예: /mnt/backups/nextcloud). 이 경로는 컨테이너 내부가 아닌, 실제 호스트의 물리적 경로여야 하며, 해당 디렉토리에 Docker가 접근할 수 있는 권한이 있어야 한다.
백업 실행 및 암호 보관: 수동으로 첫 백업을 실행하여 설정이 올바른지 테스트한다. 백업 데이터는 암호화되어 저장되며, 이때 사용된 암호화 키(encryption password)가 화면에 표시된다. 이 키는 백업 데이터를 복원하는 데 필수적이므로, Nextcloud 관리자 비밀번호와는 별도로 가장 안전한 곳에 보관해야 한다.21
자동 백업 및 업데이트 설정: ‘Daily backup and automatic updates’ 섹션에서 매일 백업을 수행할 시간을 설정한다 (예: 04:00). 자동 업데이트 옵션을 활성화하면, AIO는 매일 지정된 시간에 자동으로 백업을 수행한 후, Nextcloud 및 모든 관련 컨테이너를 최신 안정 버전으로 안전하게 업데이트한다. 이 기능은 시스템을 항상 최신 상태로 유지하고 보안 취약점을 최소화하는 데 큰 도움이 된다.2

6. 부록: 문제 해결 가이드(Troubleshooting)

Nextcloud AIO와 리버스 프록시 연동은 여러 구성 요소가 상호작용하기 때문에 다양한 문제가 발생할 수 있다. 다음은 가장 흔하게 발생하는 문제들과 그 해결 방안이다.

6.1 사례 1: 502 Bad Gateway 오류

증상: Nextcloud 도메인에 접속했을 때 Nginx가 “502 Bad Gateway” 오류 페이지를 표시한다.
원인 분석: 이 오류는 Nginx가 proxy_pass에 지정된 백엔드 서버(이 경우 nextcloud-aio-apache 컨테이너)에 성공적으로 연결하지 못했음을 의미한다.
해결 방안:

컨테이너 상태 확인: sudo docker ps 명령을 실행하여 nextcloud-aio-apache 컨테이너가 Up 상태로 정상 실행 중인지 확인한다. 만약 컨테이너가 없다면 AIO 설치 과정이 완료되지 않은 것이다.18
IP 및 포트 확인: Nginx 설정 파일의 proxy_pass에 기재된 AIO 호스트 IP 주소와 포트 번호(11000)가 정확한지 다시 한번 확인한다.
방화벽 확인: AIO가 실행 중인 Docker 호스트의 방화벽(예: ufw, firewalld)이 Nginx 프록시 서버의 IP로부터 오는 11000번 포트로의 TCP 연결을 허용하고 있는지 확인한다.

6.2 사례 2: 무한 로그인 루프 또는 인증 실패

증상: 올바른 아이디와 비밀번호를 입력해도 로그인이 되지 않고 로그인 페이지로 다시 돌아오거나, “잘못된 암호” 메시지가 계속 표시된다.
원인 분석: 리버스 프록시가 클라이언트의 요청 정보를 제대로 전달하지 못해 Nextcloud의 세션 처리 메커니즘에 혼란이 생기는 경우에 주로 발생한다.
해결 방안:

Nginx 헤더 설정 검토: 2.1 단계에서 설명한 모든 proxy_set_header 지시어들(Host, X-Forwarded-For, X-Forwarded-Proto 등)이 Nginx 설정 파일에 빠짐없이 정확하게 기재되어 있는지 확인한다.8 특히

X-Forwarded-Proto가 누락되면 이 문제가 발생하기 쉽다.

config.php 확인: Nextcloud의 config.php 파일에 불필요한 overwrite 관련 설정(예: overwritehost, overwriteprotocol)이 있는지 확인한다. 올바른 프록시 헤더 설정이 있다면 이 값들은 대부분 필요 없으며, 오히려 충돌을 일으킬 수 있다.7
브라우저 캐시 삭제: 문제 해결 과정에서 브라우저의 캐시와 쿠키를 완전히 삭제하고 다시 시도하면 문제가 해결되는 경우가 있다.20

6.3 사례 3: 도메인 유효성 검사 실패

증상: 3.2 단계에서 도메인을 입력하고 제출했을 때, “Domain does not point to this server“와 같은 오류가 발생하며 다음 단계로 진행되지 않는다.
원인 분석: AIO의 domaincheck 컨테이너가 외부 인터넷을 통해 해당 도메인으로 접근할 수 없는 상태다.
해결 방안:

DNS 레코드 확인: nslookup nextcloud.your-domain.com 또는 dig nextcloud.your-domain.com 명령을 사용하여 도메인의 A/AAAA 레코드가 Nginx 리버스 프록시 서버의 공인 IP 주소를 정확히 가리키고 있는지 확인한다.
포트 포워딩 및 방화벽 확인: Nginx 서버 앞단의 인터넷 공유기나 클라우드 방화벽에서 TCP 443 포트가 Nginx 서버로 올바르게 포워딩 또는 허용되었는지 확인한다.
Nginx 로그 분석: Nginx의 access.log와 error.log를 실시간으로 확인하면서 도메인 검증을 다시 시도해보라. AIO 서버로부터의 요청이 어떻게 처리되는지, 또는 어떤 오류가 발생하는지 단서를 찾을 수 있다.
최후의 수단: 모든 네트워크 설정을 확인했음에도 문제가 지속된다면, docker-compose.yml 파일의 environment 섹션에 - SKIP_DOMAIN_VALIDATION=true를 추가하여 이 단계를 임시로 건너뛸 수 있다. 하지만 이는 근본적인 네트워크 문제를 해결하는 것이 아니므로 권장되지 않는다.5

6.4 사례 4: 대용량 파일 업로드 실패

증상: 작은 파일은 잘 업로드되지만, 수백 MB 이상의 대용량 파일을 업로드하면 중간에 실패하거나 “Request Entity Too Large“와 같은 오류가 발생한다.
원인 분석: Nginx의 기본 업로드 용량 제한이 작거나 프록시 타임아웃 시간이 짧기 때문이다.
해결 방안:

client_max_body_size 설정 확인: Nginx 설정 파일의 location / 블록 또는 server 블록에 client_max_body_size 0; 또는 client_max_body_size 10G; 와 같이 충분히 큰 값이 설정되어 있는지 확인한다.15
타임아웃 값 조정: 대용량 파일은 업로드하는 데 시간이 오래 걸릴 수 있다. Nginx 설정 파일에 proxy_read_timeout, proxy_send_timeout 등의 값을 3600s 와 같이 충분히 길게 설정하는 것을 고려한다.15
YAML 파일 문법 검사: docker-compose.yml 파일 작성 시 웹사이트 등에서 내용을 복사-붙여넣기 하는 과정에서 눈에 보이지 않는 특수 문자가 포함되거나 들여쓰기가 잘못될 수 있다. 이로 인해 환경 변수가 제대로 적용되지 않을 수 있으므로, YAML 유효성 검사기(validator)를 사용하여 파일의 문법적 무결성을 확인하는 것이 좋다.24

7. 참고 자료

nextcloud/all-in-one - Docker Image, https://hub.docker.com/r/nextcloud/all-in-one
nextcloud/all-in-one: The official Nextcloud installation method. Provides easy deployment and maintenance with most features included in this one Nextcloud instance. - GitHub, https://github.com/nextcloud/all-in-one
Additional instructions for setting up AIO - ℹ️ Support - Nextcloud community, https://help.nextcloud.com/t/additional-instructions-for-setting-up-aio/214415
How to Install the Nextcloud All-in-One on Linux, https://nextcloud.com/blog/how-to-install-the-nextcloud-all-in-one-on-linux/
docker-compose examples for reverse proxies and other guides …, https://github.com/nextcloud/all-in-one/discussions/588
Nextcloud AIO docker reverse proxy in separate container, https://help.nextcloud.com/t/nextcloud-aio-docker-reverse-proxy-in-separate-container/162500
Reverse proxy — Nextcloud latest Administration Manual latest documentation, https://docs.nextcloud.com/server/latest/admin_manual/configuration_server/reverse_proxy_configuration.html
Nextcloud AIO behind Nginx Proxy Manager, questions for Security measures, real IP, https://help.nextcloud.com/t/nextcloud-aio-behind-nginx-proxy-manager-questions-for-security-measures-real-ip/184273
Guide: Setup - Nextcloud AIO and Nginx Proxy Manager #4240 - GitHub, https://github.com/nextcloud/all-in-one/discussions/4240
Reverse proxy setup for an absolute beginner - ℹ️ Support - Nextcloud community, https://help.nextcloud.com/t/reverse-proxy-setup-for-an-absolute-beginner/213883
Nextcloud AIO Interface not accepting admin pass phrase, https://help.nextcloud.com/t/nextcloud-aio-interface-not-accepting-admin-pass-phrase/164867
How to re-obtain/retreive the Nextcloud AIO passphrase? · nextcloud …, https://github.com/nextcloud/all-in-one/discussions/1786
Is it possible to deploy the NextCloud AIO behind NGINX Proxy Manager? - Reddit, https://www.reddit.com/r/unRAID/comments/1j0dz24/is_it_possible_to_deploy_the_nextcloud_aio_behind/
Nextcloud AIO and Nginx reverse proxy on a different machine - Reddit, https://www.reddit.com/r/NextCloud/comments/127uokz/nextcloud_aio_and_nginx_reverse_proxy_on_a/
NGINX configuration — Nextcloud latest Administration Manual latest documentation, https://docs.nextcloud.com/server/latest/admin_manual/installation/nginx.html
Setting up NextCloud AIO - Thomas Wilde Tech, https://thomaswildetech.com/blog/2025/04/25/setting-up-nextcloud-aio/
Initialise Nextcloud AIO - School IT Expert, https://schoolitexpert.com/web/nextcloud/initialise-nextcloud-aio
Setting up AIO with existing reverse proxy - ℹ️ Support - Nextcloud community, https://help.nextcloud.com/t/setting-up-aio-with-existing-reverse-proxy/195222
AIO default user and password for first login - ℹ️ Support - Nextcloud community, https://help.nextcloud.com/t/aio-default-user-and-password-for-first-login/179171
Initial admin Login Fails : r/NextCloud - Reddit, https://www.reddit.com/r/NextCloud/comments/1i25f5y/initial_admin_login_fails/
Nextcloud AIO docker is asking for borg password - Reddit, https://www.reddit.com/r/NextCloud/comments/11f8x9n/nextcloud_aio_docker_is_asking_for_borg_password/
Is it possible to use the Nextcloud aio docker with swag as a reverse proxy - Reddit, https://www.reddit.com/r/NextCloud/comments/192epks/is_it_possible_to_use_the_nextcloud_aio_docker/
nextcloud - Official Image - Docker Hub, https://hub.docker.com/_/nextcloud/
Nextcloud AIO Docker setup - reverse proxy fail - Reddit, https://www.reddit.com/r/NextCloud/comments/z3y3gw/nextcloud_aio_docker_setup_reverse_proxy_fail/