Nginx에서 사용자 정의 요소 웹 클라이언트를 호스팅하는 방법

Matrix 홈서버를 운영할 수 있지만 사용자들이 공개 Element 웹사이트에 의존하지 않도록 하려면 Element Web을 자체 Nginx 서버에 정적 사이트로 호스팅할 수 있습니다. 파일은 Nginx에서 제공되며, Matrix 홈서버는 계정, 채팅방, 메시지 및 연동 기능을 처리하는 별도의 서비스로 유지됩니다. 이러한 구분은 중요합니다. 웹 클라이언트가 Synapse를 가리키도록 설정하더라도 Synapse가 설치되거나 구성되지는 않습니다.

이 초보자용 안내서는 chat.example.orgElement 사이트와 matrix.example.org홈서버에 대해 설명합니다. 두 호스트 이름을 실제 호스트 이름으로 바꾸세요. 명령어는 데비안 또는 우분투 계열의 리눅스 서버를 기준으로 작성되었으며, 패키지 경로와 서비스 이름은 배포판에 따라 다를 수 있습니다.

시작하기 전에 필요한 것

서버 파일을 변경하기 전에 다음 항목들을 준비해 두십시오.

• 웹 클라이언트용 도메인 또는 서브도메인이며, DNS는 Nginx 호스트를 가리킵니다.
• HTTPS URL(예: )을 통해 접속 가능한 정상 작동하는 Matrix 홈서버 https://matrix.example.org.
• Nginx가 설치되어 있으며, 사이트 설정을 편집하고 서비스를 재시작할 수 있는 권한이 있습니다.
• 웹 클라이언트 호스트 이름에 대한 유효한 TLS 인증서가 필요합니다. 사용자는 브라우저가 자격 증명과 세션 토큰을 사이트로 전송하므로 HTTPS를 통해 로그인해야 합니다.
• 공식 프로젝트에서 제공하는 최신 안정 버전의 Element Web 릴리스 아카이브입니다. 개발용 소프트웨어를 실행할 목적으로만 개발 빌드를 공용 서비스에 배포하십시오.

Element Web은 정적 파일로 구성된 브라우저 애플리케이션입니다. 프로젝트의 현재 설치 지침에서는 릴리스 버전을 다운로드하고, 서버에 압축을 풀고, 웹 서버가 해당 파일들을 가리키도록 설정한 다음, 설정을 구성하도록 권장합니다 . Debian 및 config.jsonUbuntu에서는 웹 루트 디렉터리를 /etc/elementweb/element/web/element/config/element/ config /config/config/element .../usr/share/element-web/etc/element-web/config.json

Element Web의 설치 지침과 공식 릴리스를 검토한 후 버전을 선택하십시오. 데비안 패키지를 사용하는 경우, Nginx가 패키지에 명시된 웹 루트를 가리키도록 설정하고 패키지 구성 파일을 편집하십시오. 아래의 아카이브 경로는 변경하지 않고 그대로 복사하지 마십시오.

1. Element Web 파일을 다운로드하고 설치하세요.

문서 루트는 방문자가 사이트를 열 때 Nginx가 제공하는 디렉터리입니다. 전용 루트 디렉터리를 생성하고 해당 디렉터리에 릴리스 파일을 압축 해제하세요. 다운로드한 아카이브 및 디렉터리 이름은 실제 사용 환경에 맞게 변경해야 합니다. 릴리스 버전은 시간이 지남에 따라 변경될 수 있습니다.

sudo install -d -o root -g www-data -m 0755 /var/www/element
tar -xzf element-vX.Y.Z.tar.gz
ls

압축 파일은 일반적으로 버전이 지정된 디렉터리에 압축 해제됩니다. index.htmlJavaScript 번들, 글꼴, 이미지 및 샘플 구성 파일을 포함하여 해당 디렉터리의 내용을 Nginx 문서 루트에 복사하십시오. 예를 들어, 압축 해제된 디렉터리 이름이 다음과 같을 경우 element-vX.Y.Z:

sudo cp -a element-vX.Y.Z/. /var/www/element/
sudo find /var/www/element -type d -exec chmod 755 {} \;
sudo find /var/www/element -type f -exec chmod 644 {} \;
ls -l /var/www/element/index.html /var/www/element/config.sample.json

복사 명령에는 실제 버전이 지정된 디렉터리 이름을 사용하십시오. Nginx는 이러한 파일에 대한 읽기 권한이 필요하며 쓰기 권한은 필요하지 않습니다. 배포가 실패할 경우 복원할 수 있도록 업그레이드 전에 현재 릴리스 및 구성의 사본을 보관하십시오.

2. 클라이언트가 홈서버를 사용하도록 구성하십시오.

Element를 시작하려면 홈서버 주소가 필요합니다. 샘플 파일을 복사하고 Matrix 클라이언트 API 기본 URL을 설정하세요. 이 예에서 Synapse는 다음 주소에서 접속할 수 있습니다 https://matrix.example.org.

cd /var/www/element
sudo cp config.sample.json config.json
sudoedit /var/www/element/config.json

편집하여 /var/www/element/config.json유효한 JSON 객체와 default_server_config다음과 같은 항목이 포함되어 있는지 확인하십시오.

{
  "default_server_config": {
    "m.homeserver": {
      "base_url": "https://matrix.example.org"
    }
  }
}

이 설정은 Element에서 기본적으로 제공하는 서버를 지정합니다. Synapse 계정을 생성하거나 모든 사용자가 이 서버를 선택하도록 강제하지는 않습니다. 현재 Element 구성 가이드에서는 이 방법을 default_server_config홈서버 연결 정보를 제공하는 권장 방법으로 안내하고 있습니다. 이전 default_hs_url옵션은 더 이상 사용되지 않습니다. 사용자가 특정 서버만 사용하도록 제한하려면 Element에서 별도의 disable_custom_urls설정을 제공하므로, 해당 설정이 커뮤니티에 적합한지 판단한 후 활성화하십시오.

문서화된 요소 옵션을 사용하여 기본 테마 또는 특정 브랜딩 세부 정보와 같은 제한된 사용자 지정 설정을 구성할 수도 있습니다. 이는 완전한 화이트 라벨 교체와는 다릅니다. 프로젝트 문서에는 무제한 리브랜딩이 아닌 선택된 사용자 지정 설정이 명시되어 있습니다. 설치하려는 릴리스에서 지원하는 옵션은 구성 가이드를 참조하십시오. 다른 버전의 설정을 복사하기 전에 반드시 확인하십시오.

Element Web의 최신 구성 참조를 확인하세요 . develop프로젝트가 발전함에 따라 문서가 변경될 수 있으므로 배포하는 릴리스 버전에 맞춰 선택적 키를 확인하십시오.

3. 웹 클라이언트를 위해 Nginx 사이트를 추가합니다.

클라이언트 호스트 이름에 대한 사이트 구성을 생성합니다. 이 예제에서는 표시된 인증서 경로에 이미 인증서가 있다고 가정합니다 chat.example.org. 인증서 발급 방법은 호스트, DNS 공급자 및 기존 TLS 설정에 따라 달라지므로 이 예제에서는 인증서 발급 과정을 포함하지 않습니다.

server {
    listen 80;
    server_name chat.example.org;
    return 301 https://$host$request_uri;
}

server {
    listen 443 ssl;
    server_name chat.example.org;

    ssl_certificate     /etc/letsencrypt/live/chat.example.org/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/chat.example.org/privkey.pem;

    root /var/www/element;
    index index.html;

    # Revalidate the client files after deployments.
    add_header Cache-Control "no-cache" always;

    # Element Web hosting security headers.
    add_header X-Frame-Options "SAMEORIGIN" always;
    add_header X-Content-Type-Options "nosniff" always;
    add_header X-XSS-Protection "1; mode=block" always;
    add_header Content-Security-Policy "frame-ancestors 'self'" always;

    location / {
        try_files $uri $uri/ =404;
    }
}

해당 배포판에 맞는 사이트 파일에 블록을 넣고, 필요한 경우 해당 사이트를 활성화한 다음, 전역 Nginx 구성에서 표준 mime.types파일이 로드되는지 확인하십시오. Nginx는 MIME 유형을 사용하여 브라우저에 응답이 JavaScript, CSS, JSON 또는 다른 유형의 파일인지 알려줍니다. 경로는 root.이 포함된 디렉터리를 직접 가리켜야 합니다 index.html.

위의 no-cache 헤더는 배포에 편리한 간단한 기본 설정입니다. 브라우저는 업데이트 후 오래된 클라이언트 코드를 계속 사용하는 대신 파일의 유효성을 다시 검증합니다. Element의 호스팅 안내에서는 특히 `<filename>`, `<filename>`, `<filename>`을 캐시하지 않도록 요구하며 /config.*.json, /i18n사이트 /version루트 /index.html에 대해서는 유효성 재검증을 권장합니다. 나중에 대용량 정적 자산에 대해 장기간 캐시를 추가하는 경우, 해당 경로를 최신 상태로 유지하고 캐시 규칙을 생성하기 전에 릴리스의 자산 명명 규칙을 확인하세요.

Element의 웹 README에서는 자체 호스팅 사이트에 대해 프레임 방지 및 콘텐츠 유형 헤더를 권장합니다. 이미 다른 곳에서 콘텐츠 보안 정책(CSP)을 설정한 경우, frame-ancestors 'self'두 번째 CSP 헤더를 전송하는 대신 기존 정책에 추가하십시오. 제한적인 CSP는 필수 애플리케이션 스크립트를 차단할 수 있으므로, 배포된 클라이언트에서 테스트하지 않고는 포괄적인 정책을 복사하지 마십시오.

Element Web의 호스팅 및 캐싱 요구 사항 과 Nginx의 공식 코어 모듈 문서를root 참조하여 , try_files, 정적 파일 처리 동작을 확인 하십시오.

4. 구성을 검증하고 Nginx를 다시 로드합니다.

설정을 적용하기 전에 테스트하십시오. Nginx에서 오류가 보고되면 현재 프로세스를 계속 실행하면서 오류가 발생한 파일과 줄을 수정하십시오. 손상된 설정을 다시 로드하지 마십시오.

sudo nginx -t
sudo systemctl reload nginx
curl -I https://chat.example.org/
curl -I https://chat.example.org/config.json

테스트 결과는 구문이 올바르고 구성 테스트가 성공했음을 보여야 합니다. HTTPS 요청은 의도한 호스트에 도달하여 성공적인 응답을 반환해야 합니다. 구성 파일 자체도 유효한 JSON 형식인지 확인하십시오.

curl -fsS https://chat.example.org/config.json | python3 -m json.tool

그런 다음 브라우저에서 엽니다 https://chat.example.org. Matrix 홈서버가 기본값으로 설정된 Element 로그인 또는 환영 화면이 표시될 것입니다. 테스트 계정으로 접속하여 브라우저 개발자 도구에서 네트워크 요청 실패 여부를 확인하고, 로그인, 채팅방 목록 불러오기, 메시지 전송이 정상적으로 작동하는지 확인하십시오. 페이지가 성공적으로 로드되었다는 것은 Nginx가 웹 클라이언트에 서비스를 제공했다는 것을 의미할 뿐, 홈서버에 접속 가능하거나 올바르게 구성되었다는 것을 보장하는 것은 아닙니다.

5. 필요할 때 홈서버 검색 기능이 작동하도록 설정하십시오.

example.orgMatrix ID에 Synapse API 주소(예: `/matrix.js`) 와 같은 서버 이름이 사용되는 경우 matrix.example.org, Matrix 클라이언트는 해당 주소에서 클라이언트가 잘 알고 있는 응답을 사용하여 https://example.org/.well-known/matrix/clientAPI URL을 검색할 수 있습니다. 이 선택적 검색 엔드포인트는 Element 웹 클라이언트 호스트 이름이 아닌 Matrix ID의 도메인에 속해야 합니다. 최소한의 응답은 다음과 같습니다.

{
  "m.homeserver": {
    "base_url": "https://matrix.example.org"
  }
}

브라우저 기반 클라이언트에 필요한 CORS 헤더를 포함하여 JSON 형식으로 제공하세요. Synapse 설치 문서에는 Nginx 예제가 나와 있으며, public_baseurl클라이언트가 Synapse에 접속하는 데 사용하는 URL과 일치해야 한다고 명시되어 있습니다. Element 설정에서 홈서버 URL을 직접 설정하고 사용자가 해당 클라이언트별 설정을 입력하는 경우, 기본적인 설정에서는 검색이 필요하지 않을 수 있습니다.

Synapse의 고객 안내에 따라 최종 URL을 테스트한 curl후 사용자 ID 검색 기능이 제대로 작동하는지 확인하십시오. 보안 격리를 위해 Synapse의 보안 지침에서는 가능하면 민감한 웹 애플리케이션과 다른 등록 도메인에 홈 서버를 호스팅할 것을 권장합니다. 별도의 서브도메인을 사용하는 것도 어느 ​​정도 보호 효과가 있지만, 별도의 등록 도메인을 사용하는 것이 더 강력한 권장 사항입니다.

흔히 발생하는 문제점을 피하는 것이 중요합니다

• Nginx에서 403 오류가 발생했습니다. 파일 및 디렉터리의 읽기 권한을 확인하고 Nginx 워커가 각 상위 디렉터리에 접근할 수 있는지 확인하십시오.
• 페이지가 비어 있거나 JavaScript에서 404 오류가 발생하는 경우, 압축 해제된 릴리스 디렉터리 내용을 가리키는지, 상위 또는 하위 디렉터리를 가리키는지 확인하십시오 root. Nginx 오류 및 액세스 로그를 확인하세요.
• base_url요소는 로드되지만 연결 또는 로그인할 수 없습니다. 홈서버의 HTTPS 인증서, 방화벽 액세스 권한, Synapse 측 CORS 또는 리버스 프록시 구성을 확인하십시오 config.json. CORS는 브라우저에서 적용되므로 Nginx 정적 사이트는 홈서버의 오리진 정책 문제를 자체적으로 해결할 수 없습니다.
• 최근 변경 사항이 표시되지 않는 경우, 캐시 헤더에서 /, /index.html, /config.json, /version, 및 를 확인한 /i18n다음, 배포된 파일이 교체되었는지 확인하고 브라우저를 새로 고침하세요.
• 로그인 페이지는 HTTP에서만 작동합니다. TLS 설정을 완료하고 HTTP를 HTTPS로 리디렉션한 후 사용자가 로그인하도록 안내하십시오.

최종 배포 체크리스트

• Element 웹 호스트 이름은 Nginx 서버로 확인되며 유효한 HTTPS 인증서를 보유하고 있습니다.
• 문서 루트에는 릴리스의 index.html, 자산 및 유효한 가 포함되어 있습니다 config.json.
• JSON 데이터는 m.homeserver.base_urlMatrix 홈서버에 접속 가능한 HTTPS 클라이언트 API를 가리킵니다.
• sudo nginx -t통과하고, Nginx는 홈페이지와 config.jsonHTTPS를 통한 페이지 모두를 제공합니다.
• 브라우저는 인증서, CORS 또는 파일 누락 오류 없이 홈서버에 로그인하고 실제 요청을 보낼 수 있습니다.
• 캐시 규칙을 설정하면 업그레이드 후 새 클라이언트 파일과 구성이 적용됩니다.

이러한 검사를 통과하면 사용자 지정 Element Web 클라이언트가 Nginx를 통해 서비스되고 Matrix 홈서버와 통신할 수 있습니다. Element Web을 최신 상태로 유지하고, 이전 릴리스 및 구성의 롤백 복사본을 보관하고, 업그레이드 후 홈서버 URL과 브라우저 네트워크 요청을 다시 확인하십시오.

공식 참고 자료

• Element Web 설치 설명서
• Element Web 구성 가이드
• Element 웹 호스팅, 보안 헤더 및 캐싱 가이드
• Synapse 클라이언트의 잘 알려진 URI 문서
• Synapse 보안 지침
• Nginx 코어 모듈 문서