설정 지침

Weblate 설치

설정과 경험에 따라 적절한 설치 방법을 선택하세요:

• Docker를 사용한 설치, 프로덕션 설정에 권장.

• Virtualenv 설치, 프로덕션 설정에 권장:

  • Debian 및 Ubuntu에 설치

  • SUSE 및 openSUSE에 설치

  • RedHat, Fedora 및 CentOS에 설치

  • macOS에 설치

• 소스에서 설치, 개발에 권장.

• OpenShift에 설치

• Kubernetes에 설치

아키텍처 개요

웹 서버

수신 HTTP 요청 처리 ( 정적 파일 제공 ).

Celery 워커

Celery를 사용한 백그라운드 작업 가 여기서 실행됩니다.

작업 부하에 따라 워커 수를 사용자 정의할 수 있습니다.

Weblate를 수평으로 확장할 때 전용 노드를 사용하세요.

Application server

A WSGI or ASGI server serving web pages to users.

Weblate를 수평으로 확장할 때 전용 노드를 사용하세요.

데이터베이스

모든 콘텐츠를 저장하는 PostgreSQL 데이터베이스 서버 ( Weblate 데이터베이스 설정 참조).

수억 개의 호스팅 단어가 있는 사이트에는 전용 데이터베이스 노드를 사용하세요.

데이터 저장소

캐시 및 작업 큐를 위한 Valkey 또는 Redis 서버와 같은 키/값 데이터 저장소 ( Celery를 사용한 백그라운드 작업 참조).

Weblate를 수평으로 확장할 때 전용 노드를 사용하세요.

파일 시스템

VCS 저장소와 업로드된 사용자 데이터를 저장하는 파일 시스템 저장소입니다. 모든 프로세스에서 공유됩니다.

Weblate를 수평으로 확장할 때 네트워크 저장소를 사용하세요.

이메일 서버

발신 이메일을 위한 SMTP 서버 ( 발신 이메일 설정 참조). 외부에서 제공할 수 있습니다.

힌트

Docker를 사용한 설치 는 PostgreSQL과 Valkey를 포함하여 설치를 쉽게 합니다.

소프트웨어 요구사항

운영 체제

Weblate는 Linux, FreeBSD 및 macOS에서 작동하는 것으로 알려져 있습니다. 다른 Unix 계열 시스템에서도 대부분 작동합니다.

Weblate는 Windows에서 지원되지 않습니다. 하지만 작동할 수 있으며 패치는 환영합니다.

더 보기

아키텍처 개요 에서 전체 Weblate 아키텍처와 필요한 서비스를 설명합니다.

Python 종속성

Weblate는 Python 으로 작성되었으며 Python 3.12 이상을 지원합니다. pip 또는 배포 패키지를 사용하여 종속성을 설치할 수 있으며, 전체 목록은 requirements.txt 에서 확인할 수 있습니다.

주요 종속성:

Django

https://www.djangoproject.com/

Celery

https://docs.celeryq.dev/

Translate Toolkit

https://toolkit.translatehouse.org/

translation-finder

https://github.com/WeblateOrg/translation-finder

Python Social Auth

https://python-social-auth.readthedocs.io/

Django REST Framework

https://www.django-rest-framework.org/

선택적 종속성

선택적 종속성 지정자	Python 패키지	Weblate 기능
amazon	boto3	Amazon 번역
asgi	granian	ASGI server for Weblate
gelf	logging-gelf	Graylog 로그 관리
gerrit	git-review	Gerrit 리뷰 요청
google	google-cloud-storage google-cloud-translate	용어집 지원이 포함된 Google Cloud Translation Advanced
google-errors	google-cloud-error-reporting	오류 보고 수집 및 성능 모니터링
ldap	django-auth-ldap	LDAP 인증
mercurial	mercurial	Mercurial
postgres	psycopg	PostgreSQL, Weblate 데이터베이스 설정 을 참조하세요
rollbar	rollbar	오류 보고 수집 및 성능 모니터링
saml	python3-saml xmlsec	SAML 인증
saml2idp	djangosaml2idp2	Weblate에 SAML 2 IDP 통합
sphinx	Sphinx	POT 파일 업데이트 (Sphinx) 에 필요합니다
wllegal	wllegal	Hosted Weblate 통합
wsgi	granian	WSGI server for Weblate
zxcvbn	django-zxcvbn-password-validator	비밀번호 인증

pip를 사용하여 설치할 때 원하는 기능을 직접 지정할 수 있음:

uv pip install "weblate[Postgres,Amazon,SAML]"

또는 모든 선택적 기능과 함께 Weblate를 설치할 수 있음:

uv pip install "weblate[all]"

또는 선택적 기능 없이 Weblate를 설치할 수 있음:

uv pip install weblate

pip 설치 문제 해결

ffi_prep_closure(): bad user_data (it seems that the version of the libffi library seen at runtime is different from the 'ffi.h' file seen at compile-time)

이것은 PyPI를 통해 배포된 바이너리 패키지와 배포판 간의 비호환성으로 인해 발생합니다. 이 문제를 해결하려면 시스템에서 패키지를 다시 빌드해야 함:

uv pip install --force-reinstall --no-binary :all: cffi

error: ‘xmlSecKeyDataFormatEngine’ undeclared (first use in this function); did you mean ‘xmlSecKeyDataFormat’?

이것은 xmlsec 패키지의 알려진 문제입니다. https://github.com/xmlsec/python-xmlsec/issues/314를 참조하세요.

lxml & xmlsec libxml2 library version mismatch

lxml 과 xmlsec 패키지는 동일한 libxml2 에 대해 빌드해야 합니다. 이 문제를 피하려면 로컬에서 빌드해야 함:

uv pip install --force-reinstall --no-binary xmlsec --no-binary lxml lxml xmlsec

기타 시스템 요구사항

다음 종속성을 시스템에 설치해야 함:

Git

https://git-scm.com/

git-review (Gerrit 지원을 위한 선택적 패키지)

git-review

git-svn (Subversion 지원을 위한 선택적 패키지)

https://git-scm.com/docs/git-svn

tesseract (시스템에서 tesserocr 바이너리 휠을 사용할 수 없는 경우에만 필요)

https://github.com/tesseract-ocr/tesseract

빌드 시 종속성

일부 Python 종속성 를 빌드하려면 해당 종속성을 설치해야 할 수 있습니다. 이것은 설치 방법에 따라 다르므로 개별 패키지의 문서를 참조하세요. pip 를 사용하여 미리 빌드된 Wheels 를 사용하거나 배포 패키지를 사용하는 경우 이것들은 필요하지 않습니다.

하드웨어 요구사항

Weblate는 모든 최신 하드웨어에서 문제없이 실행되어야 합니다. 다음은 단일 호스트(Weblate, 데이터베이스 및 웹 서버)에서 Weblate를 실행하는 데 필요한 최소 설정임:

• RAM 3GB

• CPU 코어 2개

• 저장 공간 1GB

참고

Weblate 설치의 실제 요구사항은 관리되는 번역의 크기에 따라 크게 달라집니다.

메모리 사용

메모리는 많을수록 좋습니다 - 모든 수준(파일 시스템, 데이터베이스 및 Weblate)에서 캐싱에 사용됩니다. 수백 개의 번역 구성요소의 경우 최소 4GB RAM이 권장됩니다.

힌트

권장보다 메모리가 적은 시스템에서는 단일 프로세스 Celery 설정 가 권장됩니다.

CPU 사용

많은 동시 사용자는 필요한 CPU 코어 수를 증가시킵니다.

저장공간 사용

일반적인 데이터베이스 저장 공간 사용량은 호스팅되는 단어 100만 개당 약 300MB입니다.

클론된 저장소에 필요한 저장 공간은 다양하지만, Weblate는 얕은 클론을 수행하여 크기를 최소화하려고 합니다.

Storage performance

Version control operations perform many filesystem metadata lookups. The vcs subdirectory in DATA_DIR therefore needs low read latency; storage with slow metadata access can make operations such as git status take a long time even when its bulk throughput is good. Keep CACHE_DIR on low-latency local or temporary storage when possible.

The deployment checks measure metadata lookup latency for both locations and warn when the median latency exceeds 10 milliseconds. This is an approximate point-in-time measurement affected by filesystem and system load. Rerun weblate check --deploy before changing the storage configuration.

노드

중소규모 사이트(호스팅되는 단어 수백만 개)의 경우 모든 Weblate 구성요소 ( 아키텍처 개요 참조)를 단일 노드에서 실행할 수 있습니다.

호스팅되는 단어가 수억 개로 늘어나면 데이터베이스 전용 노드를 두는 것이 권장됩니다 ( Weblate 데이터베이스 설정 참조).

Verifying release artifacts

Release archives can be verified using the signatures, attestations, and SBOMs published with GitHub release assets. See Verifying release artifacts.

파일 시스템 권한

Weblate 프로세스는 데이터를 보관하는 디렉터리 - DATA_DIR - 에 대한 읽기 및 쓰기 권한이 있어야 합니다. 이 디렉터리 내의 모든 파일은 모든 Weblate 프로세스 (일반적으로 WSGI와 Celery. 서버 실행 및 Celery를 사용한 백그라운드 작업 참조)를 실행하는 사용자가 소유하고 쓸 수 있어야 합니다.

기본 설정에서는 Weblate 소스와 같은 트리에 배치하지만, /var/lib/weblate 와 같은 더 나은 위치로 이동하는 것이 좋을 수 있습니다.

Weblate는 이러한 디렉터리를 자동으로 만들려고 시도하지만, 권한이 없으면 실패합니다.

구성된 CACHE_DIR 도 Weblate 프로세스가 쓸 수 있어야 하며 생성된 도우미 파일 실행을 허용해야 합니다. CACHE_DIR 를 noexec 옵션으로 마운트하지 마세요.

관리 명령어 를 실행할 때도 주의해야 합니다. Weblate 자체가 실행되는 것과 동일한 사용자로 실행해야 하며, 그렇지 않으면 일부 파일의 권한이 잘못될 수 있습니다.

Docker 컨테이너에서는 /app/data 볼륨의 모든 파일이 컨테이너 내부의 weblate 사용자 (UID 1000)가 소유해야 합니다.

더 보기

정적 파일 제공

Weblate 데이터베이스 설정

PostgreSQL 데이터베이스 서버와 함께 Weblate를 실행하는 것이 권장됩니다.

PostgreSQL 13 이상이 지원됩니다. PostgreSQL 15 이상이 권장됩니다.

더 보기

• 강력한 데이터베이스 엔진 사용

• Databases

• 다른 데이터베이스에서 PostgreSQL로 마이그레이션

데이터베이스 연결

기본 설정에서 각 Weblate 프로세스는 데이터베이스에 대한 지속 연결을 유지합니다. 지속 연결은 Weblate 응답성을 향상시키지만 데이터베이스 서버에 더 많은 자원이 필요할 수 있습니다. 자세한 내용은 CONN_MAX_AGE 및 Persistent connections 를 참조하세요.

Weblate는 최소한 다음 수의 연결이 필요함:

• Celery 프로세스용: \((4 \times \mathit{nCPUs}) + 2\)

• WSGI 워커용: \(\mathit{nCPUs} + 1\)

이것은 Docker 컨테이너 기본값과 이 문서에 제공된 예시 설정에 적용되지만, WSGI 워커 수를 사용자 정의하거나 Celery의 병렬성을 조정하면 숫자가 변경됩니다.

The actual limit for the number of database connections needs to be higher to account for the following situations:

• 관리 명령어 에도 연결이 필요합니다.

• If a process is killed (for example by OOM killer), it might block the existing connection until timeout.

더 보기

Celery를 사용한 백그라운드 작업, NGINX와 uWSGI를 위한 예시 설정, WEBLATE_WORKERS

PostgreSQL

PostgreSQL은 일반적으로 Django 기반 사이트에 가장 좋은 선택입니다. Django 데이터베이스 계층을 구현하는 데 사용되는 참조 데이터베이스입니다.

참고

Weblate는 경우에 따라 별도로 설치해야 하는 trigram 확장을 사용합니다. postgresql-contrib 또는 유사한 이름의 패키지를 찾으세요.

더 보기

PostgreSQL notes

PostgreSQL에서 데이터베이스 만들기

일반적으로 별도의 데이터베이스와 별도의 사용자 계정에서 Weblate를 실행하는 것이 좋음:

# If PostgreSQL was not installed before, set the main password
sudo -u postgres psql postgres -c "\password postgres"

# Create a database user called "weblate"
sudo -u postgres createuser --superuser --pwprompt weblate

# Create the database "weblate" owned by "weblate"
sudo -u postgres createdb -E UTF8 -O weblate weblate

힌트

Weblate 사용자를 PostgreSQL 슈퍼유저로 만들고 싶지 않으면 생략할 수 있습니다. 이 경우 Weblate가 사용할 스키마에서 PostgreSQL 슈퍼유저로 일부 마이그레이션 단계를 수동으로 수행해야 함:

CREATE EXTENSION IF NOT EXISTS pg_trgm;
CREATE EXTENSION IF NOT EXISTS btree_gin;
CREATE EXTENSION IF NOT EXISTS btree_gist;

Weblate에서 PostgreSQL 사용 설정

PostgreSQL용 settings.py 코드 조각:

DATABASES = {
    "default": {
        # Database engine
        "ENGINE": "django.db.backends.postgresql",
        # Database name
        "NAME": "weblate",
        # Database user
        "USER": "weblate",
        # Configures name of the PostgreSQL role to alter during the database migration
        # "ALTER_ROLE": "weblate",
        # Database password
        "PASSWORD": "password",
        # Set to empty string for localhost
        "HOST": "database.example.com",
        # Set to empty string for default
        "PORT": "",
        # Persistent connections
        "CONN_MAX_AGE": None,
        "CONN_HEALTH_CHECKS": True,
    }
}

데이터베이스 마이그레이션은 Weblate가 사용하는 데이터베이스 역할에 대해 ALTER ROLE 을 수행합니다. 대부분의 경우 역할 이름은 사용자 이름과 일치합니다. 더 복잡한 설정에서는 역할 이름이 사용자 이름과 다르며, 데이터베이스 마이그레이션 중 존재하지 않는 역할에 대한 오류가 발생합니다 (psycopg2.errors.UndefinedObject: role "weblate@hostname" does not exist). 이것은 Azure Database for PostgreSQL에서 발생하는 것으로 알려져 있지만 이 환경에 국한되지 않습니다. ALTER_ROLE 을 설정하여 데이터베이스 마이그레이션 중 Weblate가 변경해야 할 역할 이름을 변경하세요.

더 보기

데이터베이스 연결

기타 설정

발신 이메일 설정

Weblate는 계정 활성화 및 사용자가 구성한 다양한 알림 등 여러 경우에 이메일을 보냅니다. 이를 위해 SMTP 서버에 대한 접근이 필요합니다.

메일 서버 설정은 다음 설정을 사용하여 구성함: EMAIL_HOST, EMAIL_HOST_PASSWORD, EMAIL_USE_TLS, EMAIL_USE_SSL, EMAIL_HOST_USER 및 EMAIL_PORT. 이름 자체가 설명적이지만 Django 문서에서更多信息을 확인할 수 있습니다.

힌트

지원되지 않는 인증에 대한 오류가 발생하는 경우 (예: SMTP AUTH extension not supported by server), 보안이 적용되지 않은 연결을 사용하고 서버가 이 방식으로 인증을 거부하기 때문일 가능성이 높습니다. 이 경우 EMAIL_USE_TLS 를 활성화해 보세요.

더 보기

• Weblate에서 이메일을 받지 못함

• Docker 컨테이너에서 발신 이메일 설정

리버스 프록시 뒤에서 실행

Weblate의 여러 기능은 올바른 HTTP 헤더가 Weblate에 전달되어야 합니다. 리버스 프록시를 사용하는 경우 필요한 정보가 올바르게 전달되는지 확인하세요.

이 설정을 디버그하려면 성능 보고서 의 HTTP 환경 을 참조하세요.

클라이언트 IP 주소

속도 제한 또는 감사 로그 에 필요합니다.

Weblate는 WSGI 핸들러에 의해 설정된 REMOTE_ADDR 에서 IP 주소를 파싱합니다. 이것은 비어 있을 수 있습니다 (WSGI에 소켓을 사용하는 경우) 또는 리버스 프록시 주소를 포함할 수 있으므로, Weblate에는 클라이언트 IP 주소가 포함된 추가 HTTP 헤더가 필요합니다.

IP_BEHIND_REVERSE_PROXY 를 활성화하면 대부분의 일반적인 설정에서 충분하지만, IP_PROXY_HEADER 와 IP_PROXY_OFFSET 도 조정해야 할 수 있습니다 (Docker 컨테이너에서는 WEBLATE_IP_PROXY_HEADER 와 WEBLATE_IP_PROXY_OFFSET 를 사용).

The reverse proxy which connects to Weblate must overwrite the configured header or append a verified peer address at the position selected by IP_PROXY_OFFSET. Do not select a client-supplied address, and do not expose the application server through a path which bypasses the trusted proxy.

When using X-Forwarded-For with the Docker container, configure WEBLATE_TRUSTED_PROXY_ADDRESSES with the reverse proxies allowed to supply client addresses.

힌트

이 설정은 기본적으로 활성화할 수 없습니다. 적절하게 구성된 리버스 프록시가 없는 설치에서 IP 주소 스푸핑을 허용하기 때문입니다.

서버 호스트 이름

Host 헤더는 SITE_DOMAIN 에 설정된 것과 일치해야 합니다. 리버스 프록시에서 추가 설정이 필요할 수 있습니다 (예: Apache의 경우 ProxyPreserveHost On, nginx의 경우 proxy_set_header Host $host; 사용).

힌트

CSRF 확인 실패 오류는 Host 헤더와 설정된 SITE_DOMAIN 간의 불일치로 인해 자주 발생합니다.

클라이언트 프로토콜

올바른 프로토콜을 전달하지 않으면 Weblate가 클라이언트를 HTTPS로 업그레이드하려는 리디렉션 루프에 빠질 수 있습니다. 리버스 프록시에서 X-Forwarded-Proto 로 올바르게 노출되는지 확인하세요.

이 헤더는 SECURE_PROXY_SSL_HEADER (settings.py) 또는 WEBLATE_SECURE_PROXY_SSL_HEADER (Docker 환경)에 설정해야 합니다.

중요

설정에서 헤더 값은 대소문자를 구분하므로 WEBLATE_SECURE_PROXY_SSL_HEADER=HTTP_X_FORWARDED_PROTO,https 와 WEBLATE_SECURE_PROXY_SSL_HEADER=HTTP_X_FORWARDED_PROTO,HTTPS 는 서로 바꿔 사용할 수 없습니다.

힌트

브라우저에서 “Too many redirects” 오류가 발생하는 경우, 실제 프로토콜 (HTTPS)과 Weblate가 감지하는 것 간의 불일치가 원인일 가능성이 높습니다.

버전 5.13에서 변경: 기본 설정에서 프로토콜 프록시 헤더는 gunicorn 에 의해 자동으로 처리되지만, 다른 WSGI 서버는 더 안전한 설정을 가지며 이를 명시적으로 설정해야 합니다.

Weblate 5.13부터 Docker 컨테이너는 granian 을 사용하며, 이제 WEBLATE_SECURE_PROXY_SSL_HEADER 의 명시적 설정이 필요합니다.

더 보기

• SSL 종료 프록시

• 속도 제한

• 감사 로그

• NGINX와 Granian을 위한 예시 설정

• NGINX와 Gunicorn을 위한 예시 설정

• NGINX와 uWSGI를 위한 예시 설정

• Apache를 위한 예시 설정

• Apache와 Gunicorn을 위한 예시 설정

• IP_BEHIND_REVERSE_PROXY

• IP_PROXY_HEADER

• IP_PROXY_OFFSET

• SECURE_PROXY_SSL_HEADER

• WEBLATE_IP_PROXY_HEADER

• WEBLATE_TRUSTED_PROXY_ADDRESSES

• WEBLATE_IP_PROXY_OFFSET

HTTP 프록시

Weblate supports per-protocol HTTP proxy configuration for outbound HTTP requests and Git repositories. Define the proxy environment variables in settings.py:

import os

os.environ["http_proxy"] = "http://proxy.example.com:8080"
os.environ["https_proxy"] = "http://proxy.example.com:8080"

Only http_proxy and https_proxy are supported. Generic and bypass variables such as all_proxy and no_proxy, operating-system proxy configuration, and VCS-specific proxy configuration are not supported.

더 보기

Proxy environment variables

설정 조정

더 보기

샘플 설정

weblate/settings_example.py 를 weblate/settings.py 로 복사하고 설정에 맞게 조정하세요. 다음 옵션을 조정해야 할 수 있음:

ADMINS

무엇인가 잘못될 때 알림을 받을 사이트 관리자 목록입니다. 예를 들어 병합 실패 알림 또는 Django 오류 알림.

ADMINS_CONTACT 이 설정되지 않은 경우 문의 양식에서도 여기로 이메일을 보냅니다.

더 보기

• ADMINS

• ADMINS_CONTACT

• 관리자 올바르게 설정

ALLOWED_HOSTS

사이트가 서비스해야 하는 호스트 목록을 설정해야 합니다. 예시:

ALLOWED_HOSTS = ["demo.weblate.org"]

또는 와일드카드를 포함할 수 있음:

ALLOWED_HOSTS = ["*"]

더 보기

• ALLOWED_HOSTS

• WEBLATE_ALLOWED_HOSTS

• 허용 호스트 설정

SESSION_ENGINE

세션 저장 방식을 설정합니다. 기본 데이터베이스 백엔드 엔진을 유지하는 경우, 데이터베이스에서 오래된 세션 데이터를 제거하기 위해 weblate clearsessions 을 예약해야 합니다.

캐시로 Valkey 또는 Redis를 사용하는 경우 ( 캐시 설정 참조) 세션에도 이를 사용하는 것이 권장됨:

SESSION_ENGINE = "django.contrib.sessions.backends.cache"

더 보기

• Configuring the session engine

• SESSION_ENGINE

DATABASES

데이터베이스 서버 연결. 자세한 내용은 Django 문서를 참조하세요.

더 보기

• Weblate 데이터베이스 설정

• DATABASES

• Databases

DEBUG

프로덕션 서버에서는 반드시 비활성화하세요. 디버그 모드가 활성화되면 Django는 오류 발생 시 사용자에게 역추적 정보를 표시하며, 비활성화하면 오류가 이메일로 ADMINS 에게 전송됩니다 (위 참조).

디버그 모드는 Weblate를 느리게 하기도 합니다. 이 경우 Django가 내부적으로 훨씬 많은 정보를 저장하기 때문입니다.

더 보기

• DEBUG

• 디버그 모드 비활성화

DEFAULT_FROM_EMAIL

발신 이메일의 발신자 주소입니다. 예를 들어 등록 이메일 등.

더 보기

DEFAULT_FROM_EMAIL

SECRET_KEY

Django가 쿠키의 일부 정보를 서명하는 데 사용하는 키입니다. 자세한 내용은 Django 시크릿 키 을 참조하세요.

더 보기

SECRET_KEY

SERVER_EMAIL

관리자에게 이메일을 보낼 때 발신자 주소로 사용되는 이메일입니다. 예를 들어 병합 실패 알림 등.

더 보기

SERVER_EMAIL

데이터베이스 채우기

설정이 완료되면 migrate 를 실행하여 데이터베이스 구조를 만들 수 있습니다. 이제 관리 인터페이스를 사용하여 번역 프로젝트를 만들 수 있습니다.

완료한 후에는 관리 인터페이스의 성능 보고서 도 확인하세요. 사이트에서 잠재적으로 비최적화된 설정에 대한 힌트를 제공합니다.

더 보기

• 설정

• 권한 목록

프로덕션 설정

프로덕션 설정에서는 다음 섹션에 설명된 조정을 수행해야 합니다. 가장 중요한 설정은 경고를 트리거하며, 슈퍼유저로 로그인한 경우 상단 표시줄의 느낌표로 표시됩니다:

Django에 의해 트리거된 검사를 검토하는 것도 권장됩니다 (모두 수정할 필요는 없을 수 있습니다):

weblate check --deploy

관리 인터페이스 의 성능 보고서 에서도 동일한 목록을 확인할 수 있습니다.

더 보기

배포 전 체크리스트

디버그 모드 비활성화

다음으로 Django의 디버그 모드 ( DEBUG )를 비활성화하세요:

DEBUG = False

디버그 모드가 켜지면 Django는 모든 실행된 쿼리를 저장하고 사용자에게 오류의 역추적 정보를 표시합니다. 프로덕션 설정에서는 바람직하지 않습니다.

더 보기

설정 조정

관리자 올바르게 설정

Set the correct admin addresses to the ADMINS setting to define who will receive e-mails in case something goes wrong on the server, for example:

ADMINS = ("Your Name <your_email@example.com>",)

더 보기

설정 조정

올바른 사이트 도메인 설정

관리 인터페이스에서 사이트 이름과 도메인을 조정하세요. 그렇지 않으면 RSS 또는 등록 이메일의 링크가 작동하지 않습니다. 사이트 도메인 이름을 포함해야 하는 SITE_DOMAIN 을 사용하여 설정합니다.

버전 4.2에서 변경: 4.2 릴리스 이전에는 Django sites 프레임워크가 대신 사용되었습니다. “sites” 프레임워크 를 참조하세요.

더 보기

• 허용 호스트 설정

• HTTPS 올바르게 설정

• SITE_DOMAIN

• WEBLATE_SITE_DOMAIN

• ENABLE_HTTPS

HTTPS 올바르게 설정

암호화된 HTTPS 프로토콜을 사용하여 Weblate를 실행하는 것이 강력히 권장됩니다. 활성화한 후 설정에서 ENABLE_HTTPS 를 설정하세요:

ENABLE_HTTPS = True

힌트

HSTS도 설정할 수 있습니다. 자세한 내용은 SSL/HTTPS 을 참조하세요.

더 보기

• ENABLE_HTTPS

• 허용 호스트 설정

• 올바른 사이트 도메인 설정

SECURE_HSTS_SECONDS 올바르게 설정

사이트가 SSL을 통해 제공되는 경우, HTTP Strict Transport Security를 활성화하기 위해 settings.py 에서 SECURE_HSTS_SECONDS 의 값을 설정하는 것을 고려해야 합니다. 기본값은 아래와 같이 0으로 설정됩니다.

SECURE_HSTS_SECONDS = 0

0이 아닌 정수 값으로 설정하면 django.middleware.security.SecurityMiddleware 가 아직 없는 모든 응답에 HTTP Strict Transport Security 헤더를 설정합니다.

경고

이 설정을 잘못하면 사이트가 되돌릴 수 없게 (일정 기간 동안) 손상될 수 있습니다. 먼저 HTTP Strict Transport Security 문서를 읽으세요.

강력한 데이터베이스 엔진 사용

• 프로덕션 환경에서는 PostgreSQL을 사용하세요. 자세한 내용은 Weblate 데이터베이스 설정 을 참조하세요.

• 데이터베이스 서버를 인접한 위치에서 실행하세요. 그렇지 않으면 네트워크 성능 또는 안정성이 Weblate 경험을 손상시킬 수 있습니다.

• 데이터베이스 서버 성능을 확인하거나 설정을 조정하세요. 예를 들어 PGTune 을 사용하세요.

• Weblate deployment checks report non-finite PostgreSQL relation statistics. Run ANALYZE on the reported relations to rebuild corrupted statistics.

더 보기

• Weblate 데이터베이스 설정

• 다른 데이터베이스에서 PostgreSQL로 마이그레이션

• 설정 조정

• Databases

캐시 설정

가능한 경우 CACHES 설정 변수를 조정하여 Django에서 Valkey 또는 Redis를 사용하세요. 예시:

CACHES = {
    "default": {
        "BACKEND": "django_redis.cache.RedisCache",
        "LOCATION": "redis://127.0.0.1:6379/0",
        # If redis is running on same host as Weblate, you might
        # want to use unix sockets instead:
        # 'LOCATION': 'unix:///var/run/redis/redis.sock?db=0',
        "OPTIONS": {
            "CLIENT_CLASS": "django_redis.client.DefaultClient",
            "PARSER_CLASS": "redis.connection.HiredisParser",
        },
    }
}

힌트

캐시 설정을 변경하는 경우 Celery에 대해서도 조정해야 할 수 있습니다 ( Celery를 사용한 백그라운드 작업 참조).

더 보기

• 아바타 캐싱

• Django의 캐시 프레임워크

아바타 캐싱

Django 캐싱 외에도 Weblate는 아바타 캐싱을 수행합니다. 이 목적에는 별도의 파일 기반 캐시를 사용하는 것이 권장됨:

CACHES = {
    "default": {
        # Default caching backend setup, see above
        "BACKEND": "django_redis.cache.RedisCache",
        "LOCATION": "unix:///var/run/redis/redis.sock?db=0",
        "OPTIONS": {
            "CLIENT_CLASS": "django_redis.client.DefaultClient",
            "PARSER_CLASS": "redis.connection.HiredisParser",
        },
    },
    "avatar": {
        "BACKEND": "django.core.cache.backends.filebased.FileBasedCache",
        "LOCATION": os.path.join(DATA_DIR, "avatar-cache"),
        "TIMEOUT": 604800,
        "OPTIONS": {
            "MAX_ENTRIES": 1000,
        },
    },
}

더 보기

• ENABLE_AVATARS

• AVATAR_URL_PREFIX

• 아바타

• 캐시 설정

• Django의 캐시 프레임워크

이메일 전송 설정

Weblate는 여러 경우에 이메일을 보내야 하며, 이러한 이메일에는 올바른 발신자 주소가 있어야 합니다. 환경에 맞게 SERVER_EMAIL 과 DEFAULT_FROM_EMAIL 을 설정하세요. 예시:

SERVER_EMAIL = "admin@example.org"
DEFAULT_FROM_EMAIL = "weblate@example.org"

참고

Weblate의 이메일 전송을 비활성화하려면 EMAIL_BACKEND 를 django.core.mail.backends.dummy.EmailBackend 로 설정하세요.

이렇게 하면 등록 또는 비밀번호 재설정 이메일을 포함한 모든 이메일 전송이 비활성화됩니다.

더 보기

• 설정 조정

• 발신 이메일 설정

• EMAIL_BACKEND

• DEFAULT_FROM_EMAIL

• SERVER_EMAIL

허용 호스트 설정

Django는 사이트가 서비스할 수 있는 도메인 이름 목록을 ALLOWED_HOSTS 에 포함해야 합니다. 비워두면 모든 요청이 차단됩니다.

HTTP 서버에 맞게 설정되지 않은 경우 Invalid HTTP_HOST header: '1.1.1.1'. You may need to add '1.1.1.1' to ALLOWED_HOSTS. 와 같은 오류가 발생합니다

힌트

Docker 컨테이너에서는 WEBLATE_ALLOWED_HOSTS 로 사용할 수 있습니다.

더 보기

• ALLOWED_HOSTS

• WEBLATE_ALLOWED_HOSTS

• 올바른 사이트 도메인 설정

Django 시크릿 키

SECRET_KEY 설정은 Django가 쿠키를 서명하는 데 사용하며, 예시 설정의 것을 사용하기보다 자체 값을 생성해야 합니다.

Weblate에 포함된 weblate-generate-secret-key 를 사용하여 새 키를 생성할 수 있습니다.

더 보기

SECRET_KEY

유지보수 작업 실행

최적의 성능을 위해 백그라운드에서 일부 유지보수 작업을 실행하는 것이 좋습니다. 이것은 Celery를 사용한 백그라운드 작업 에 의해 자동으로 수행되며 다음 작업을 포함함:

• 설정 상태 확인 (매시간).

• 보류 중인 변경사항 커밋 (매시간, 지연 커밋 및 commit_pending 참조).

• 구성요소 알림 업데이트 (매일).

• 원격 브랜치 업데이트 (매일 밤, AUTO_UPDATE 참조).

• 번역 메모리 JSON 백업 (매일, dump_memory 참조).

• 전문 검색 및 데이터베이스 유지보수 작업 (매일 및 매주 작업, cleanuptrans 참조).

시스템 로케일 및 인코딩

시스템 로케일은 UTF-8을 지원하는 것으로 설정해야 합니다. 대부분의 Linux 배포판에서는 이것이 기본 설정입니다. 시스템에서 그렇지 않은 경우 로케일을 UTF-8 변형으로 변경하세요.

예를 들어 /etc/default/locale 을 편집하고 LANG="C.UTF-8" 을 설정합니다.

경우에 따라 개별 서비스에 별도의 로케일 설정이 있습니다. 이것은 배포판과 웹 서버에 따라 다르므로 웹 서버 패키지의 문서를 확인하세요.

Ubuntu의 Apache는 /etc/apache2/envvars 를 사용함:

export LANG='en_US.UTF-8'
export LC_ALL='en_US.UTF-8'

CentOS의 Apache는 /etc/sysconfig/httpd (또는 /opt/rh/httpd24/root/etc/sysconfig/httpd)를 사용함:

LANG='en_US.UTF-8'

사용자 정의 인증 기관 사용

Weblate verifies SSL certificates during HTTP requests. Requests made using HTTPX2 use the system certificate store, so install custom certificate authorities there.

Check your distribution documentation for more details. For example, on Debian this can be done by placing the CA certificate into /usr/local/share/ca-certificates/ and running update-ca-certificates.

힌트

Weblate 컨테이너에는 검색 경로에 포함되지 않으므로 전체 경로를 지정해야 합니다. 예시:

docker compose exec -u root weblate /usr/sbin/update-ca-certificates

Once this is done, Weblate HTTPX2 requests and system tools, including Git, will trust the certificate.

Some integrations, including OAuth and OpenID Connect authentication, use Requests, which does not use the system certificate store by default. When these integrations communicate with services using the custom certificate authority, configure Requests to use the system CA bundle by adding the following to settings.py (the path is Debian-specific):

import os

os.environ["REQUESTS_CA_BUNDLE"] = "/etc/ssl/certs/ca-certificates.crt"

서버 실행

힌트

아래 설명된 서비스에 경험이 없는 경우 Docker를 사용한 설치 를 시도해 보세요.

Weblate를 실행하려면 여러 서비스가 필요합니다. 권장 설정은 다음과 같음:

• 데이터베이스 서버 ( Weblate 데이터베이스 설정 참조)

• 캐시 서버 ( 캐시 설정 참조)

• 정적 파일 및 SSL 종료를 위한 프론트엔드 웹 서버 ( 정적 파일 제공 참조)

• 동적 콘텐츠를 위한 WSGI 서버 ( NGINX와 uWSGI를 위한 예시 설정 참조)

• 백그라운드 작업 실행을 위한 Celery ( Celery를 사용한 백그라운드 작업 참조)

참고

서비스 간에 일부 종속성이 있습니다. 예를 들어 Celery 또는 uwsgi 프로세스를 시작할 때 캐시와 데이터베이스가 실행 중이어야 합니다.

대부분의 경우 단일 (가상) 서버에서 모든 서비스를 실행하지만, 설치 환경에 부하가 큰 경우 서비스를 분할할 수 있습니다. 유일한 제한은 Celery와 WSGI 서버가 DATA_DIR 에 접근해야 한다는 것입니다.

참고

WSGI 프로세스는 Celery 프로세스와 동일한 사용자로 실행해야 합니다. 그렇지 않으면 DATA_DIR 의 파일이 혼합된 소유권으로 저장되어 런타임 문제가 발생합니다.

파일 시스템 권한 및 Celery를 사용한 백그라운드 작업 도 참조하세요.

웹 서버 실행

Weblate를 실행하는 것은 다른 Django 기반 프로그램을 실행하는 것과 다르지 않습니다. Django는 일반적으로 WSGI 또는 fcgi로 실행됩니다 (아래 다양한 웹 서버 예시 참조).

참고

아래에 표시된 예시 설정 파일은 Weblate 소스 트리의 weblate/examples/ 아래에서 관리됩니다. 소스 배포판과 이 문서에는 포함되어 있지만, Python 휠은 런타임 파일만 설치합니다. PyPI에서 Weblate를 설치하는 경우 이러한 예시를 복사하기 전에 일치하는 소스 배포판이나 소스 체크아웃을 가져오세요.

테스트 목적으로 Django의 내장 웹 서버를 사용할 수 있음:

weblate runserver

경고

이 서버를 프로덕션 환경에서 사용하지 마세요. 보안 감사 또는 성능 테스트를 거치지 않았습니다. runserver 에 대한 Django 문서도 참조하세요.

힌트

Django 내장 서버는 개발 전용이므로 DEBUG 가 활성화된 경우에만 정적 파일을 제공합니다. 프로덕션 사용에는 WSGI 설정을 참조하세요:

• NGINX와 Granian을 위한 예시 설정

• NGINX와 Gunicorn을 위한 예시 설정

• NGINX와 uWSGI를 위한 예시 설정

• Apache를 위한 예시 설정

• Apache와 Gunicorn을 위한 예시 설정

• 정적 파일 제공

정적 파일 제공

버전 5.15.2에서 변경: /media/ 는 더 이상 스크린샷 제공에 사용되지 않습니다.

Django needs to collect its static files in a single directory. To do so, execute weblate collectstatic --noinput. This will copy the static files into a directory specified by the STATIC_ROOT setting (this defaults to a static directory inside CACHE_DIR). Production installations use content hashes in collected filenames so that updated assets do not reuse stale browser or proxy caches.

웹 서버에서 직접 정적 파일을 제공하는 것이 권장됩니다. 다음 경로에 이를 사용해야 함:

/static/

Weblate와 관리 인터페이스의 정적 파일을 제공합니다 (STATIC_ROOT 에 정의된 위치에서).

/favicon.ico

Should be rewritten to serve /static/favicon.ico.

더 보기

• NGINX와 Granian을 위한 예시 설정

• NGINX와 Gunicorn을 위한 예시 설정

• NGINX와 uWSGI를 위한 예시 설정

• Apache를 위한 예시 설정

• Apache와 Gunicorn을 위한 예시 설정

• 장고를 배포하는 방법

• 정적 파일을 배포하는 방법

콘텐츠 보안 정책

기본 Weblate 설정은 Content-Security-Policy 또는 X-XSS-Protection 과 같은 보안 관련 HTTP 헤더를 설정하는 weblate.middleware.SecurityMiddleware 미들웨어를 활성화합니다. 이것들은 기본적으로 Weblate와 그 설정에서 작동하도록 설정되어 있지만, 환경에 따라 사용자 정의가 필요할 수 있습니다.

더 보기

• CSP_SCRIPT_SRC

• CSP_IMG_SRC

• CSP_CONNECT_SRC

• CSP_STYLE_SRC

• CSP_FONT_SRC

• CSP_FORM_SRC

NGINX와 Granian을 위한 예시 설정

The following configuration runs Weblate using Granian with the NGINX webserver:

weblate/examples/weblate.nginx.granian.conf

#
# nginx configuration for Weblate
#
# You will want to change:
#
# - server_name
# - change /home/weblate/weblate-env to location where Weblate Python environment is placed
# - change /home/weblate/data to match your DATA_DIR
# - change /home/weblate/data/cache to match your CACHE_DIR
# - change python3.12 to match your Python version
# - change weblate user to match your Weblate user
#
server {
    listen 80;
    server_name weblate;
    # Not used
    root /var/www/html;

    location ~ ^/favicon.ico$ {
        # CACHE_DIR/static/favicon.ico
        alias /home/weblate/data/cache/static/favicon.ico;
        expires 30d;
    }

    location /static/ {
        # CACHE_DIR/static/
        alias /home/weblate/data/cache/static/;
        expires 30d;
    }

    location / {
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header Host $http_host;
        proxy_pass http://127.0.0.1:8888;
        proxy_read_timeout 3600;
    }
}

더 보기

• Granian 시작을 위한 예시 설정

• https://github.com/emmett-framework/granian

• WSGI를 사용하여 배포하는 방법

NGINX와 Gunicorn을 위한 예시 설정

다음 설정은 NGINX 웹 서버 아래에서 Gunicorn으로 Weblate를 실행합니다(소스 트리의 weblate/examples/weblate.nginx.gunicorn.conf):

#
# nginx configuration for Weblate
#
# You will want to change:
#
# - server_name
# - change /home/weblate/weblate-env to location where Weblate Python environment is placed
# - change /home/weblate/data to match your DATA_DIR
# - change /home/weblate/data/cache to match your CACHE_DIR
# - change python3.12 to match your Python version
# - change weblate user to match your Weblate user
#
server {
    listen 80;
    server_name weblate;
    # Not used
    root /var/www/html;

    location ~ ^/favicon.ico$ {
        # CACHE_DIR/static/favicon.ico
        alias /home/weblate/data/cache/static/favicon.ico;
        expires 30d;
    }

    location /static/ {
        # CACHE_DIR/static/
        alias /home/weblate/data/cache/static/;
        expires 30d;
    }

    location / {
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header Host $http_host;
        proxy_pass http://unix:/run/gunicorn.sock;
        proxy_read_timeout 3600;
    }
}

더 보기

• Gunicorn 시작을 위한 예시 설정

• Gunicorn과 함께 django 사용방법

NGINX와 uWSGI를 위한 예시 설정

프로덕션 웹 서버를 실행하려면 Weblate와 함께 설치된 WSGI 래퍼를 사용하세요 (Python 환경 사용 시 ~/weblate-env/lib/python3.14/site-packages/weblate/wsgi.py 로 설치됩니다). Python 환경에 대한 Python 검색 경로도 설정하는 것을 잊지 마세요 (예: uWSGI에서 virtualenv = /home/user/weblate-env 사용).

다음 설정은 NGINX 웹 서버 아래에서 uWSGI로 Weblate를 실행합니다.

NGINX 설정(소스 트리의 weblate/examples/weblate.nginx.conf):

#
# nginx configuration for Weblate
#
# You will want to change:
#
# - server_name
# - change /home/weblate/weblate-env to location where Weblate Python environment is placed
# - change /home/weblate/data to match your DATA_DIR
# - change /home/weblate/data/cache to match your CACHE_DIR
# - change python3.12 to match your Python version
# - change weblate user to match your Weblate user
#
server {
    listen 80;
    server_name weblate;
    # Not used
    root /var/www/html;

    location ~ ^/favicon.ico$ {
        # CACHE_DIR/static/favicon.ico
        alias /home/weblate/data/cache/static/favicon.ico;
        expires 30d;
    }

    location /static/ {
        # CACHE_DIR/static/
        alias /home/weblate/data/cache/static/;
        expires 30d;
    }

    location / {
        include uwsgi_params;
        # Needed for long running operations in admin interface
        uwsgi_read_timeout 3600;
        # Adjust based to uwsgi configuration:
        uwsgi_pass unix:///run/uwsgi/app/weblate/socket;
        # uwsgi_pass 127.0.0.1:8080;
    }
}

uWSGI 설정(소스 트리의 weblate/examples/weblate.uwsgi.ini):

#
# uWSGI configuration for Weblate
#
# You will want to change:
#
# - change /home/weblate/weblate-env to location where Weblate Python environment is placed
# - change /home/weblate/data to match your DATA_DIR
# - change python3.12 to match your Python version
# - change weblate user to match your Weblate user
#
[uwsgi]
plugins       = python3
master        = true
protocol      = uwsgi
socket        = 127.0.0.1:8080
wsgi-file     = /home/weblate/weblate-env/lib/python3.12/site-packages/weblate/wsgi.py

# Add path to Weblate checkout if you did not install
# Weblate by pip
# python-path   = /path/to/weblate

# Path to the Python environment
virtualenv = /home/weblate/weblate-env

# Needed for OAuth/OpenID
buffer-size   = 8192

# Reload when consuming too much of memory
reload-on-rss = 250

# Increase number of workers for heavily loaded sites
workers       = 8

# Enable threads for Sentry error submission
enable-threads = true

# Child processes do not need file descriptors
close-on-exec = true

# Avoid default 0000 umask
umask = 0022

# Run as weblate user
uid = weblate
gid = weblate

# Enable harakiri mode (kill requests after some time)
# harakiri = 3600
# harakiri-verbose = true

# Enable uWSGI stats server
# stats = :1717
# stats-http = true

# Do not log some errors caused by client disconnects
ignore-sigpipe = true
ignore-write-errors = true
disable-write-exception = true

더 보기

uWSGI와 함께 django를 사용하는 방법

Apache를 위한 예시 설정

Weblate에서 WSGI를 사용할 때 prefork MPM을 사용하는 것이 권장됩니다.

다음 설정은 Weblate를 WSGI로 실행합니다. mod_wsgi 가 활성화되어 있어야 합니다(소스 트리의 weblate/examples/apache.conf):

#
# VirtualHost for Weblate
#
# You will want to change:
#
# - ServerAdmin and ServerName
# - change /home/weblate/weblate-env to location where Weblate Python environment is placed
# - change /home/weblate/data to match your DATA_DIR
# - change /home/weblate/data/cache to match your CACHE_DIR
# - change python3.12 to match Python version mod-wsgi is compiled for
# - change weblate user to match your Weblate user
#
<VirtualHost *:80>
    ServerAdmin admin@weblate.example.org
    ServerName weblate.example.org

    # CACHE_DIR/static/favicon.ico
    Alias /favicon.ico /home/weblate/data/cache/static/favicon.ico

    # CACHE_DIR/static/
    Alias /static/ /home/weblate/data/cache/static/
    <Directory /home/weblate/data/cache/static/>
        Require all granted
    </Directory>

    # Path to your Weblate Python environment
    WSGIDaemonProcess weblate python-home=/home/weblate/weblate-env user=weblate request-timeout=600
    WSGIProcessGroup weblate
    WSGIApplicationGroup %{GLOBAL}

    WSGIScriptAlias / /home/weblate/weblate-env/lib/python3.12/site-packages/weblate/wsgi.py process-group=weblate
    WSGIPassAuthorization On

    <Directory /home/weblate/weblate-env/lib/python3.12/site-packages/weblate/>
        <Files wsgi.py>
        Require all granted
        </Files>
    </Directory>

</VirtualHost>

참고

Weblate는 Python 3이 필요하므로 modwsgi의 Python 3 변형을 실행하고 있는지 확인하세요. 일반적으로 별도 패키지로 제공됩니다. 예: libapache2-mod-wsgi-py3.

Weblate를 설치하는 데 일치하는 Python 버전을 사용하세요.

더 보기

• 시스템 로케일 및 인코딩

• django와 아파치 사용법, mod_wsgi 사용법

Apache와 Gunicorn을 위한 예시 설정

다음 설정은 Gunicorn과 Apache 2.4에서 Weblate를 실행합니다(소스 트리의 weblate/examples/apache.gunicorn.conf):

#
# VirtualHost for Weblate using gunicorn on localhost:8000
#
# You will want to change:
#
# - ServerAdmin and ServerName
# - change /home/weblate/weblate-env to location where Weblate Python environment is placed
# - change /home/weblate/data to match your DATA_DIR
# - change /home/weblate/data/cache to match your CACHE_DIR
# - change weblate user to match your Weblate user
#
<VirtualHost *:443>
    ServerAdmin admin@weblate.example.org
    ServerName weblate.example.org

    # CACHE_DIR/static/favicon.ico
    Alias /favicon.ico /home/weblate/data/cache/static/favicon.ico

    # CACHE_DIR/static/
    Alias /static/ /home/weblate/data/cache/static/
    <Directory /home/weblate/data/cache/static/>
        Require all granted
    </Directory>

    SSLEngine on
    SSLCertificateFile /etc/apache2/ssl/https_cert.cert
    SSLCertificateKeyFile /etc/apache2/ssl/https_key.pem
    SSLProxyEngine On

    ProxyPass /favicon.ico !
    ProxyPass /static/ !

    ProxyPass / http://localhost:8000/
    ProxyPassReverse / http://localhost:8000/
    ProxyPreserveHost On
</VirtualHost>

더 보기

• Gunicorn 시작을 위한 예시 설정

• Gunicorn과 함께 django 사용방법

Granian 시작을 위한 예시 설정

Weblate에는 Granian 실행에 필요한 모든 것을 설치하는 wsgi 선택적 종속성이 있습니다 ( Python 종속성 참조). Weblate를 설치할 때 다음과 같이 지정할 수 있음:

uv pip install Weblate[all,wsgi]

Granian을 설치한 후 실행할 수 있습니다. 이것은 일반적으로 시스템 수준에서 수행됩니다. 다음 예시는 systemd를 통한 시작을 보여줌:

/etc/systemd/system/granian.service

[Unit]
Description=granian daemon
After=network.target

[Service]
User=weblate
Group=weblate
WorkingDirectory=/home/weblate/weblate-env/
Environment="DJANGO_SETTINGS_MODULE=weblate.settings"
RuntimeDirectory=granian
ExecStart=/home/weblate/weblate-env/bin/granian \
    --no-ws \
    --workers-max-rss 450 \
    --interface wsgi \
    --workers 2 \
    --blocking-threads 8 \
    --backlog 128 \
    --backpressure 16 \
    --runtime-mode mt \
    --port 8888 \
    weblate.wsgi:application

[Install]
WantedBy=multi-user.target

Granian uses worker processes for parallel Python execution, blocking threads for concurrent WSGI requests, and runtime threads for network I/O. The sample uses two workers with eight blocking threads each, limits each worker to 16 concurrent connections, and leaves the runtime threads at Granian’s default. Adjust the workers and blocking threads to the available memory, CPU cores, and database connection limit. Keep the backpressure equal to or higher than the number of blocking threads.

더 보기

• Sample configuration to start Granian with ASGI

• https://github.com/emmett-framework/granian

• WSGI를 사용하여 배포하는 방법

Sample configuration to start Granian with ASGI

Added in version 2026.8.

ASGI deployment is available as an opt-in alternative to WSGI. Install the asgi optional dependency:

uv pip install Weblate[all,asgi]

The following systemd unit runs the Django ASGI application:

/etc/systemd/system/granian-asgi.service

[Unit]
Description=granian ASGI daemon
After=network.target

[Service]
User=weblate
Group=weblate
WorkingDirectory=/home/weblate/weblate-env/
Environment="DJANGO_SETTINGS_MODULE=weblate.settings"
RuntimeDirectory=granian
ExecStart=/home/weblate/weblate-env/bin/granian \
    --no-ws \
    --workers-max-rss 450 \
    --interface asginl \
    --workers 2 \
    --backlog 128 \
    --backpressure 16 \
    --runtime-mode mt \
    --port 8888 \
    weblate.asgi:application

[Install]
WantedBy=multi-user.target

The sample uses Granian’s ASGI interface without lifespan or WebSocket support, because Weblate currently exposes HTTP only. Weblate’s middleware supports both deployment modes and uses thread-sensitive adapters where it still relies on synchronous Django APIs. The health check is asynchronous, but most Weblate views remain synchronous, and CPU-intensive or long-running work should still be handled by Celery를 사용한 백그라운드 작업.

WSGI remains the default deployment mode. Docker images can opt in to ASGI by setting WEBLATE_ASGI to 1. Adjust the worker count and backpressure to the available memory, CPU cores, and database connection limit.

더 보기

• Granian 시작을 위한 예시 설정

• https://github.com/emmett-framework/granian

• ASGI를 사용하여 배포하는 방법

Gunicorn 시작을 위한 예시 설정

Gunicorn은 별도로 설치해야 함:

uv pip install gunicorn

Gunicorn을 설치한 후 실행할 수 있습니다. 이것은 일반적으로 시스템 수준에서 수행됩니다. 다음 예시는 systemd를 통한 시작을 보여줌:

/etc/systemd/system/gunicorn.socket

[Unit]
Description=gunicorn socket

[Socket]
ListenStream=/run/gunicorn.sock

[Install]
WantedBy=sockets.target

/etc/systemd/system/gunicorn.service

[Unit]
Description=gunicorn daemon
Requires=gunicorn.socket
After=network.target

[Service]
User=weblate
Group=weblate
WorkingDirectory=/home/weblate/weblate-env/
Environment="DJANGO_SETTINGS_MODULE=weblate.settings"
ExecStart=/home/weblate/weblate-env/bin/gunicorn \
    --preload \
    --timeout 3600 \
    --graceful-timeout 3600 \
    --worker-class=gthread \
    --workers=2 \
    --threads=16 \
    --bind unix:/run/gunicorn.sock \
    weblate.wsgi:application

[Install]
WantedBy=multi-user.target

더 보기

Gunicorn과 함께 django 사용방법

경로 아래에서 Weblate 실행

Weblate에서 WSGI를 사용할 때 prefork MPM을 사용하는 것이 권장됩니다.

/weblate 아래에서 Weblate를 제공하는 Apache 예시 설정입니다. 역시 mod_wsgi 를 사용합니다(소스 트리의 weblate/examples/apache-path.conf):

#
# VirtualHost for Weblate, running under /weblate path
#
# You will want to change:
#
# - ServerAdmin and ServerName
# - change /home/weblate/weblate-env to location where Weblate Python environment is placed
# - change /home/weblate/data to match your DATA_DIR
# - change /home/weblate/data/cache to match your CACHE_DIR
# - change python3.12 to match Python version mod-wsgi is compiled for
# - change weblate user to match your Weblate user
#
<VirtualHost *:80>
    ServerAdmin admin@weblate.example.org
    ServerName weblate.example.org

    # CACHE_DIR/static/favicon.ico
    Alias /weblate/favicon.ico /home/weblate/data/cache/static/favicon.ico

    # CACHE_DIR/static/
    Alias /weblate/static/ /home/weblate/data/cache/static/
    <Directory /home/weblate/data/cache/static/>
        Require all granted
    </Directory>

    # Path to your Weblate Python environment
    WSGIDaemonProcess weblate python-home=/home/weblate/weblate-env user=weblate request-timeout=600
    WSGIProcessGroup weblate
    WSGIApplicationGroup %{GLOBAL}

    WSGIScriptAlias /weblate /home/weblate/weblate-env/lib/python3.12/site-packages/weblate/wsgi.py process-group=weblate
    WSGIPassAuthorization On

    <Directory /home/weblate/weblate-env/lib/python3.12/site-packages/weblate/>
        <Files wsgi.py>
        Require all granted
        </Files>
    </Directory>

</VirtualHost>

추가로 weblate/settings.py 를 조정해야 함:

URL_PREFIX = "/weblate"

Celery를 사용한 백그라운드 작업

Weblate는 정기 및 백그라운드 작업을 실행하기 위해 Celery를 사용합니다. 이러한 작업을 실행할 Celery 서비스를 실행해야 합니다. 예를 들어 다음 작업을 처리합니다 (이 목록은 완전하지 않습니다):

• 외부 서비스에서 웹훅 수신 ( 알림 후크 참조).

• 백업, 정리, 일일 애드온 또는 업데이트와 같은 정기 유지보수 작업 실행 ( Weblate 백업 및 이전, BACKGROUND_TASKS, 애드온 참조).

• 자동 번역 실행.

• 요약 알림 발송.

• WSGI 프로세스에서 무거운 작업을 오프로딩합니다.

• 보류 중인 변경사항 커밋 ( 지연 커밋 참조).

Valkey 또는 Redis를 백엔드로 사용하는 일반적인 설정은 다음과 같음:

CELERY_TASK_ALWAYS_EAGER = False
CELERY_BROKER_URL = "redis://localhost:6379"
CELERY_RESULT_BACKEND = CELERY_BROKER_URL

더 보기

Celery의 Redis 브로커 설정

작업을 처리하고 예약된 작업을 시작하려면 Celery 워커도 시작해야 합니다. 디버깅이나 개발 목적이라면 명령줄에서 직접 실행할 수 있습니다:

celery --app=weblate.utils worker --beat --queues=celery,notify,memory,translate,backup

To reduce startup memory usage, Celery workers do not repeat the Django system checks. The Weblate container runs the more comprehensive weblate check --deploy automatically during container startup. For other installation methods, run the command after installation, upgrades, or configuration changes. The checks are also available in the management interface.

참고

Celery 프로세스는 WSGI 프로세스와 동일한 사용자로 실행해야 합니다. 그렇지 않으면 DATA_DIR 의 파일이 혼합된 소유권으로 저장되어 런타임 문제가 발생합니다.

파일 시스템 권한 및 서버 실행 도 참조하세요.

이거(eager) 모드를 사용하여 WSGI에서 Celery 작업 실행

참고

이것은 웹 인터페이스에 심각한 성능 영향을 미치며, 정기적 트리거에 의존하는 기능 (예: 보류 중인 변경사항 커밋, 요약 알림 또는 백업)을 손상시킵니다.

개발의 경우 모든 작업을 제자리에서 처리하는 이거 설정을 사용할 수 있음:

CELERY_TASK_ALWAYS_EAGER = True
CELERY_BROKER_URL = "memory://"
CELERY_TASK_EAGER_PROPAGATES = True

시스템 서비스로 Celery 실행

대부분의 경우 Celery를 데몬으로 실행하려고 할 것이며, 이는 Daemonization 에서 다룹니다. systemd를 사용하는 가장 일반적인 Linux 설정에서는 아래 나열된 예시 파일을 조정하세요. 이러한 예시는 Weblate 소스 트리의 weblate/examples/ 아래에서 관리되며, Python 휠은 이 배포 예시를 설치하지 않습니다.

/etc/systemd/system/celery-weblate.service 로 배치할 systemd 유닛:

[Unit]
Description=Celery Service (Weblate)
After=network.target

[Service]
Type=forking
User=weblate
Group=weblate
EnvironmentFile=/etc/default/celery-weblate
WorkingDirectory=/home/weblate
RuntimeDirectory=celery
RuntimeDirectoryPreserve=restart
LogsDirectory=celery
ExecStart=/bin/sh -c '${CELERY_BIN} multi start ${CELERYD_NODES} \
  -A ${CELERY_APP} --pidfile=${CELERYD_PID_FILE} \
  --logfile=${CELERYD_LOG_FILE} --loglevel=${CELERYD_LOG_LEVEL} ${CELERYD_OPTS}'
ExecStop=/bin/sh -c '${CELERY_BIN} multi stopwait ${CELERYD_NODES} \
  --pidfile=${CELERYD_PID_FILE}'
ExecReload=/bin/sh -c '${CELERY_BIN} multi restart ${CELERYD_NODES} \
  -A ${CELERY_APP} --pidfile=${CELERYD_PID_FILE} \
  --logfile=${CELERYD_LOG_FILE} --loglevel=${CELERYD_LOG_LEVEL} ${CELERYD_OPTS}'

[Install]
WantedBy=multi-user.target

/etc/default/celery-weblate 로 배치할 환경 설정:

# Name of nodes to start
CELERYD_NODES="celery notify memory backup translate"

# Absolute or relative path to the 'celery' command:
CELERY_BIN="/home/weblate/weblate-env/bin/celery"

# App instance to use
# comment out this line if you don't use an app
CELERY_APP="weblate.utils"

# Extra command-line arguments to the worker. You might need to customize
# concurrency depending on the available resources and Weblate usage. Increase
# the concurrency if you get weblate.E019 error, decrease it if you are on a
# low-resource system. A higher prefetch multiplier can improve throughput for
# short tasks, but reserves more tasks in each worker. Command-line values
# override CELERY_WORKER_PREFETCH_MULTIPLIER from settings.py.
CELERYD_OPTS="--beat:celery --queues:celery=celery --concurrency:celery=2 --prefetch-multiplier:celery=1 \
    --queues:notify=notify --concurrency:notify=2 --prefetch-multiplier:notify=4 \
    --queues:memory=memory --concurrency:memory=2 --prefetch-multiplier:memory=1 \
    --queues:translate=translate --concurrency:translate=4 --prefetch-multiplier:translate=1 \
    --queues:backup=backup  --concurrency:backup=1 --prefetch-multiplier:backup=1"

# Logging configuration
# - %n will be replaced with the first part of the nodename.
# - %I will be replaced with the current child process index
#   and is important when using the prefork pool to avoid race conditions.
CELERYD_PID_FILE="/run/celery/weblate-%n.pid"
CELERYD_LOG_FILE="/var/log/celery/weblate-%n%I.log"
CELERYD_LOG_LEVEL="INFO"

/etc/logrotate.d/celery 로 배치할 logrotate 를 사용한 Celery 로그 순환 추가 설정:

/var/log/celery/*.log {
        weekly
        missingok
        rotate 12
        compress
        notifempty
}

Celery beat를 사용한 주기적 작업

Weblate에는 예약된 작업을 위한 내장 설정이 있습니다. 작업 일정은 데이터베이스에 저장되며 작업은 Celery beat 데몬에 의해 실행됩니다.

힌트

settings.py 에서 추가 작업을 정의할 수 있습니다. 예시는 지연 커밋 를 참조하세요.

Celery 상태 모니터링

관리 인터페이스 에서 Celery 작업 큐의 현재 길이를 확인할 수 있으며, 명령줄에서 celery_queues 를 사용할 수도 있습니다. 큐가 너무 길어지면 관리 인터페이스에 설정 오류도 표시됩니다.

경고

Celery 오류는 기본적으로 Celery 로그에만 기록되며 사용자에게 보이지 않습니다. 이러한 실패에 대한 개요를 보려면 오류 보고 수집 및 성능 모니터링 를 설정하는 것이 권장됩니다.

더 보기

• Weblate 모니터링

• Weblate가 올바르게 설정되었는지 어떻게 확인할 수 있나요?

• Configuration and defaults

• Workers Guide

• Daemonization

• Monitoring and Management Guide

• 백그라운드 작업 내부 구조

• celery_queues

단일 프로세스 Celery 설정

메모리가 매우 제한적인 경우 Weblate 프로세스 수를 줄일 수 있습니다. 다음을 사용하여 모든 Celery 작업을 단일 프로세스에서 실행할 수 있음:

celery --app=weblate.utils worker --beat --queues=celery,notify,memory,translate,backup --pool=solo

Docker를 사용하는 설치에서는 CELERY_SINGLE_PROCESS 를 설정하여 단일 프로세스 Celery 설정을 사용하도록 구성할 수 있습니다.

경고

이것은 Weblate에 눈에 띄는 성능 영향을 미칩니다.

Weblate 모니터링

Weblate는 간단한 상태 확인에 사용할 수 있는 /healthz/ URL을 제공합니다 (예: Kubernetes 사용 시). Docker 컨테이너에는 이 URL을 사용하는 내장 상태 확인이 있습니다.

For monitoring metrics of Weblate you can use the GET /api/metrics/ API endpoint. Monitoring tools running locally can retrieve the same metrics using the metrics command.

더 보기

• Weblate가 올바르게 설정되었는지 어떻게 확인할 수 있나요?

• Celery 상태 모니터링

• Munin용 Weblate 플러그인

오류 보고 수집 및 성능 모니터링

Weblate는 다른 소프트웨어와 마찬가지로 실패할 수 있습니다. 유용한 실패 상태를 수집하기 위해 서드파티 서비스를 사용하여 이러한 정보를 수집하는 것이 권장됩니다. 이것은 특히 실패한 Celery 작업의 경우에 유용합니다. 그렇지 않으면 로그에만 오류가 보고되어 알림을 받지 못합니다. Weblate는 다음 서비스를 지원함:

이메일

기본 Weblate 설정은 django.utils.log.AdminEmailHandler 를 통해 서버 오류 시 이메일을 보내도록 Django를 설정합니다. 이것은 가장 간편한 설정이지만, 오류 이메일에 민감한 데이터가 포함될 수 있으므로 개인정보 보호를 위해 다른 옵션을 고려해야 합니다. 자세한 내용은 Security implications 에서 확인할 수 있습니다.

이 동작을 비활성화하려면 Weblate 설정의 LOGGING 에서 mail_admins 를 제거하거나 Docker 환경에서 WEBLATE_ADMIN_NOTIFY_ERROR 를 비활성화하세요.

Sentry

Weblate는 Sentry 를 기본적으로 지원합니다. 사용하려면 settings.py 에서 SENTRY_DSN 을 설정하면 됨:

SENTRY_DSN = "https://id@your.sentry.example.com/"

Sentry는 정의된 비율의 작업에 대한 트레이스와 프로필을 수집하여 Weblate의 성능을 모니터링하는 데에도 사용할 수 있습니다. SENTRY_TRACES_SAMPLE_RATE 및 SENTRY_PROFILES_SAMPLE_RATE 를 사용하여 설정할 수 있습니다.

더 보기

• Sentry 성능 모니터링

• Sentry Profiling

Google Cloud Error Reporting

Weblate는 처리된 서버 오류를 Google Cloud Error Reporting 에 보고할 수 있습니다. google-errors 확장 기능을 사용하여 Weblate를 설치하고, settings.py 파일에서 GOOGLE_CLOUD_ERROR_REPORTING 을 구성하세요:

GOOGLE_CLOUD_ERROR_REPORTING = {
    "project": "your-google-cloud-project",
}

Weblate는 weblate 서비스 아래에서 오류를 자동 보고하고, 보고되는 버전으로 현재 Weblate 버전 또는 Git 리비전을 사용합니다. 이 값은 GOOGLE_CLOUD_ERROR_REPORTING 에서 service 또는 version 을 지정하여 재정의할 수 있습니다.

OpenTelemetry

Weblate는 OpenTelemetry 를 사용하여 백엔드 추적을 내보낼 수 있습니다. HTTP 위의 OTLP를 사용하며 추적을 OpenTelemetry Collector 또는 호환 공급자 엔드포인트로 보낼 수 있습니다.

OPENTELEMETRY_ENABLED = True
OPENTELEMETRY_EXPORTER_OTLP_ENDPOINT = "https://collector.example.com/v1/traces"
OPENTELEMETRY_TRACES_SAMPLE_RATE = 0.1

이 통합은 Django 요청, Celery 작업, Redis, 발신 HTTP 요청, 데이터베이스 호출, Weblate 전용 span을 추적합니다. OPENTELEMETRY_ENABLED, OPENTELEMETRY_EXPORTER_OTLP_ENDPOINT, OPENTELEMETRY_TRACES_SAMPLE_RATE 로 구성하세요.

Rollbar

Weblate는 Rollbar 를 기본적으로 지원합니다. 사용하려면 Rollbar notifier for Python 의 지침을 따르면 됩니다.

간단히 settings.py 를 조정해야 함:

# Add rollbar as last middleware:
MIDDLEWARE = [
    # … other middleware classes …
    "rollbar.contrib.django.middleware.RollbarNotifierMiddleware",
]

# Configure client access
ROLLBAR = {
    "access_token": "POST_SERVER_ITEM_ACCESS_TOKEN",
    "environment": "development" if DEBUG else "production",
    "branch": "main",
    "root": "/absolute/path/to/code/root",
}

나머지는 자동으로 통합되며, 이제 서버와 클라이언트 측 오류를 모두 수집합니다.

참고

오류 로깅에는 우아하게 처리되었지만 문제를 나타낼 수 있는 예외도 포함됩니다 - 예: 업로드된 파일의 구문 분석 실패.

Graylog 로그 관리

Added in version 5.9.

Weblate는 GELF TCP 프로토콜을 사용하여 로깅하도록 설정할 수 있습니다. 이것은 Graylog 통합을 위해 개발되었지만 호환되는 모든 로깅 플랫폼에서 사용할 수 있습니다.

설정 보일러플레이트는 샘플 설정 에 포함되어 있으며, Docker에서는 WEBLATE_LOG_GELF_HOST 를 사용하여 설정할 수 있습니다.

Weblate를 다른 서버로 마이그레이션

Weblate를 다른 서버로 마이그레이션하는 것은 꽤 쉽지만, 데이터가 몇 곳에 저장되어 있으므로 주의 깊게 마이그레이션해야 합니다. 가장 좋은 방법은 마이그레이션을 위해 Weblate를 중지하는 것입니다.

데이터베이스 마이그레이션

가장 간단한 방법은 일반적으로 가장 효과적인 데이터베이스 기본 도구를 사용하는 것입니다 (예: pg_dump). 또는 데이터베이스가 지원하는 경우 복제를 사용할 수 있습니다.

더 보기

데이터베이스 간 마이그레이션은 다른 데이터베이스에서 PostgreSQL로 마이그레이션 에 설명되어 있습니다.

VCS 저장소 마이그레이션

DATA_DIR 아래에 저장된 VCS 저장소도 마이그레이션해야 합니다. 단순히 복사하거나 rsync 를 사용하여 보다 효과적으로 마이그레이션할 수 있습니다.

기타 참고사항

Weblate가 사용하고 있을 수 있는 Valkey, Redis, Cron 작업 또는 사용자 정의 인증 백엔드와 같은 다른 서비스를 이동하는 것을 잊지 마세요.