# 아웃포스트 배포

서버 또는 NAS에서 아웃포스트를 실행하여 선택한 이메일 폴더로부터 알림을 받으세요. 권장되는 Compose 설치를 위해서는 Docker와 Docker Compose v2가 필요합니다.

**이미지 가용성**: 사용 가능한 버전은 [GitHub 릴리스](https://github.com/mingzaily/mailwake/releases) 및 [GHCR](https://github.com/mingzaily/mailwake/pkgs/container/mailwake)에 나열되어 있습니다.

## 1. 설치 방법을 선택하세요

**Docker Compose를 권장합니다**: 설치, 업데이트, 백업에서 동일한 구성을 사용합니다. 이미지는 Linux amd64 / arm64의 경우 `ghcr.io/mingzaily/mailwake:latest` 입니다. `latest`는 안정 릴리스를 따릅니다. 버전을 고정하려면 `latest`를 릴리스의 게시된 태그로 바꾸세요.

서버 터미널에서:

```
mkdir -p ~/mailwake
cd ~/mailwake
```

이 전체 구성을 사용하여 해당 디렉터리에 `compose.yaml`를 만듭니다.

```
services:
  core:
    image: ghcr.io/mingzaily/mailwake:latest
    restart: unless-stopped
    ports:
      - "127.0.0.1:8080:8080"
    environment:
      MAILWAKE_LISTEN: "0.0.0.0:8080"
      MAILWAKE_DATA_DIR: "/data"
      MAILWAKE_RELAY_URL: "${MAILWAKE_RELAY_URL:-}"
    volumes:
      - core-data:/data
    read_only: true
    security_opt:
      - no-new-privileges:true
    cap_drop:
      - ALL
    stop_grace_period: 30s
volumes:
  core-data:
```

이미지를 가져와서 아웃포스트를 시작하세요.

```
docker compose pull core
docker compose up -d
docker compose ps
docker compose logs --tail=50 core
```

**결과 확인**: `core` 에는 `Up` / `running` 가 표시되고 로그에는 초기 설정 코드가 포함되어 있습니다. 다음 단계를 위해 터미널을 사용할 수 있도록 유지하세요. `~/mailwake` 에서 향후 Compose 명령을 실행하세요.

`core-data` Docker 볼륨은 `/data` 를 저장합니다. 이 디렉터리 이름을 사용하면 기본 Docker 이름은 `mailwake_core-data` 입니다. 컨테이너를 다시 생성하면 컨테이너가 보존됩니다. `docker compose down -v`는 볼륨과 해당 내용을 삭제합니다.

### 도커 실행

단일 명령을 선호하는 경우 이와 동등한 설치를 선택하십시오. 인스턴스에 하나의 설치 방법을 사용하십시오.

```
docker volume create mailwake-data
docker run -d \
  --name mailwake \
  --restart unless-stopped \
  --stop-timeout 30 \
  --read-only \
  --security-opt no-new-privileges:true \
  --cap-drop ALL \
  -p 127.0.0.1:8080:8080 \
  -v mailwake-data:/data \
  ghcr.io/mingzaily/mailwake:latest
docker logs --tail=50 mailwake
```

이 설치에서는 `mailwake-data` 볼륨을 사용합니다. 다음 관리 명령은 Compose를 사용합니다. 대안은 [Docker 실행 백업 지침](backup.md#docker-run-설치-백업)를 참조하세요.

## 2. 콘솔을 엽니다

**Docker 호스트에서**: <http://127.0.0.1:8080> 를 엽니다.

**원격 서버 또는 NAS에서**: 자신의 컴퓨터에서 이 명령을 실행하고 `user@server`를 서버의 SSH 사용자 및 주소로 바꿉니다.

```
ssh -L 18080:127.0.0.1:8080 user@server
```

연결을 열어두고 컴퓨터에서 <http://127.0.0.1:18080>를 방문하세요. 이것으로 초기 설정을 완료하기에 충분합니다. 도메인을 통해 지속적으로 액세스하려면 아래에서 HTTPS를 구성하세요.

**결과 확인**: Mailwake 설정 화면이 열립니다. 로그에 있는 설정 코드를 입력하고 12자 이상의 관리자 비밀번호를 만드세요. 설정하기 전에 아웃포스트를 다시 시작하면 새 설정 코드가 생성됩니다.

사서함과 알림 채널을 연결하려면 [첫 번째 알림](first-notification.md)를 계속 진행하세요.

## 3. HTTPS 구성

도메인이 서버를 가리키도록 하고 역방향 프록시가 `http://127.0.0.1:8080`로 전달되도록 구성합니다. 동일한 호스트에 설치된 Caddy의 경우 `Caddyfile`에 도메인을 추가합니다.

```
mail.example.org {
    reverse_proxy 127.0.0.1:8080
}
```

DNS를 확인하고 인바운드 포트 80/443을 허용한 다음 유효성을 검사하고 다시 로드합니다.

```
sudo caddy validate --config /etc/caddy/Caddyfile
sudo systemctl reload caddy
```

`https://mail.example.org` 를 열고 인증서가 유효한지 확인한 후 로그인하여 메일함을 열 수 있는지 확인하세요. Caddy를 설치하려면 [공식 캐디 설치 가이드](https://caddyserver.com/docs/install)를 참조하세요. Nginx Proxy Manager와 같은 프록시 패널에서 도메인과 전달 주소를 입력하고 패널에서 인증서를 요청합니다.

다른 컨테이너에 있는 프록시의 경우 이를 아웃포스트의 Docker 네트워크에 연결하고 `http://core:8080`로 전달합니다. `127.0.0.1`는 자신을 나타냅니다. 원래 호스트를 유지하고 `X-Forwarded-For` 를 설정합니다. 아웃포스트는 루프백 및 개인 네트워크로부터 프록시 정보를 받아들입니다. 포트 8080은 프록시와 신뢰할 수 있는 로컬 클라이언트에만 노출됩니다.

## 4. 아웃포스트 업데이트

[지원](backup.md) 를 완료한 후 Compose 디렉터리에서 실행합니다.

```
docker compose pull core
docker compose up -d
docker compose ps
docker compose logs --tail=50 core
```

고정 버전의 경우 먼저 `compose.yaml`에서 이미지 태그를 변경하세요. 콘솔을 열고 사서함 모니터링을 확인한 후 새 이메일을 보내 배달을 확인하세요. 업데이트 전 백업을 유지하세요. 롤백하려면 복원 튜토리얼을 사용하여 데이터와 일치하는 이미지를 모두 복원하세요.

## 5. 문제 해결

### 이미지를 가져올 수 없습니다.

GHCR에 요청된 버전이 포함되어 있는지 확인하세요. `manifest unknown`는 일반적으로 태그가 누락되었음을 의미합니다. `denied` 오류가 있는지 이미지 주소와 패키지 가시성을 확인하거나 시간 초과가 있는지 GHCR에 대한 서버 연결을 확인하세요.

### 콘솔이 열리지 않습니다

`127.0.0.1`는 귀하가 사용하고 있는 컴퓨터를 나타냅니다. 원격 설치에는 SSH 터널 또는 HTTPS 도메인을 사용하십시오. 먼저 `docker compose ps` 및 `docker compose logs --tail=50 core`를 확인하세요. 8080이 점유된 경우 매핑을 `127.0.0.1:18080:8080`로 변경하고 브라우저 및 역방향 프록시에서 호스트 포트 18080을 사용합니다.

### 관리자 비밀번호 재설정

Compose 디렉터리에서 실행하고 터미널 프롬프트에 새 비밀번호를 입력합니다.

```
docker compose stop core
docker compose run --rm -it core admin reset-password
docker compose start core
```

복구 명령은 데이터 디렉터리 잠금을 획득하므로 먼저 아웃포스트를 중지합니다. 비밀번호를 재설정하면 브라우저 세션이 취소되고 API 토큰, 메일함 및 대기열이 보존됩니다.

### 공식 앱과 Pro를 연결하세요

Free 웹 콘솔과 Bark/Pushover/Webhook 전달은 독립적으로 작동합니다. 공식 앱의 경우 HTTPS 및 페어링을 위해 [앱 통합](connect-app.md)를 따르세요.

소스 빌드 및 로컬 개발은 [개발 가이드](https://github.com/mingzaily/mailwake/blob/main/docs/development.md)에서 다룹니다.

## 소스 빌드 및 프로세스 설정

개발 빌드의 경우 [소스 저장소 README](https://github.com/mingzaily/mailwake#run-from-source) 및 [기여자 빌드 가이드](https://github.com/mingzaily/mailwake/blob/main/CONTRIBUTING.md)를 따르세요.

`MAILWAKE_LISTEN`는 Docker 외부에서 기본적으로 `127.0.0.1:8080`로 설정됩니다. 컨테이너는 `0.0.0.0:8080` 를 사용합니다. `MAILWAKE_DATA_DIR`의 기본값은 `data`입니다. 컨테이너는 `/data` 를 사용합니다. `MAILWAKE_RELAY_URL`의 기본값은 `https://notify.mailwake.oritx.com` 입니다. 다시 시작하고 업그레이드하는 동안 `secret.key` 를 포함한 전체 데이터 디렉터리를 유지합니다.

## 푸시 전달 환경 변경

프로덕션과 샌드박스는 별도의 페어링 ID를 사용합니다. 의도적으로 환경을 변경하려면 아웃포스트를 중지하고 기존 데이터 디렉터리 및 이전 푸시 전달 서비스의 저장된 주소에 대해 재설정을 실행합니다.

```sh
docker compose stop core
docker compose run --rm -it core admin reset-native-push
```

메시지가 나타나면 `reset-native-push`를 입력합니다. 이 명령은 이전 푸시 전달 서비스에서 페어링을 취소합니다. 해당 서비스에 연결할 수 없는 경우 이전 구성을 유지하고 서비스에 연결할 수 있을 때 다시 시도하세요. 해결되지 않은 대상이 없음을 확인한 후 새 `MAILWAKE_RELAY_URL` 를 설정하고 `docker compose up -d` 및 [다시 페어링](connect-app.md) 를 사용하여 아웃포스트를 다시 만듭니다. 이 명령은 아웃포스트 서명 ID와 일반 채널 기록을 보존합니다.