設定手順

Weblate のインストール

セットアップと経験に応じて、適切なインストール方法を選択する:

ソフトウェア要件

オペレーティング システム

Weblate は、Linux、FreeBSD、macOSで動作することが判明しています。他の Unix のようなシステムでも動作する可能性は高いでしょう。

Weblate は Windows には対応していません。しかし、それでも動作するかもしれないのでパッチは歓迎します。

その他のサービス

Weblate は他のサービスを利用しています。実行が必要なサービス:

Python の依存関係

Weblateは、Python で書かれており、Python 3.6 以降に対応しています。依存関係は pip を使ってのインストールも、ディストリビューションのパッケージからのインストールもできます。完全な一覧は requirements.txt にあります。

最も重要な依存関係:

Django

https://www.djangoproject.com/

Celery

https://docs.celeryproject.org/

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 フレームワーク

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

オプションの依存関係

Weblate の機能には、以下のモジュールを必要とするものがあります。これらはすべて 、requirements-optional.txt で確認できます。

Mercurial ( Mercurial リポジトリ対応用のオプション)

https://www.mercurial-scm.org/

phply (PHP 対応用のオプション)

https://github.com/viraptor/phply

tesserocr (スクリーンショットの OCR 用のオプション)

https://github.com/sirfz/tesserocr

akismet (提案のスパム保護用のオプション)

https://github.com/ubernostrum/akismet

ruamel.yamlYAML files 用のオプション)

https://pypi.org/project/ruamel.yaml/

ZeepMicrosoft Terminology Service 用のオプション)

https://docs.python-zeep.org/

aeidonSubtitle files 用のオプション)

https://pypi.org/project/aeidon/

バックエンドのデータベースの依存関係

Weblate は、PostgreSQL、MySQL および MariaDB に対応しています。詳細は Weblate のデータベース設定 およびバックエンドのドキュメントを確認してください。

その他のシステム要件

システムにインストールすることが必要な依存関係:

Git

https://git-scm.com/

Pango、Cairo および関連するヘッダ ファイルと gir イントロスペクション データー

https://cairographics.org/https://pango.gnome.org/、参照 Pango と Cairo

git-review (Gerrit 対応用のオプション)

https://pypi.org/project/git-review/

git-svn (Subversion 対応用のオプション)

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

tesseract とそのデーター(スクリーンショットの OCR 用のオプション)

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

licensee (コンポーネント作成時にライセンス確認するためのオプション)

https://github.com/licensee/licensee

ビルド時の依存関係

Python の依存関係 の一部をビルドするには、それらの依存関係をインストールすることが必要な場合があります。これはインストール方法によって異なりますので、個々のパッケージに関するドキュメントを確認してください。 pip を使用してインストールするときにビルド済みの Wheels を使用する場合、または配布パッケージを使用する場合には必要ありません。

Pango と Cairo

バージョン 3.7 で変更.

Weblateは、ビットマップ ウィジェットの表示(参照 Promoting the translation)と、検査結果の表示(参照 フォントの管理)に Pango と Cairo を使用します。それらの Python バインディングを適切にインストールするには、最初にシステム ライブラリのインストールが必要です。Cairo と Pango の両方が必要であり、次に GLib が必要です。これらはすべて、開発ファイルと GObject イントロスペクション データとともにインストールが必要です。

リリース署名の検証

Weblate のリリースは、リリースした開発者により署名は暗号化されています。現在は、Michal Čihař です。彼の PGP 鍵の指紋:

63CB 1DF1 EF12 CF2A C0EE 5A32 9C27 B313 42B7 511D

さらに、<https://keybase.io/nijel> からより多くの身元情報を得られます。

署名がダウンロードしたアーカイブと一致するかどうかの確認が必要です。これにより、リリースされたものと同じコードを使用していることを確認できます。また、署名の日付を確認して、最新バージョンをダウンロードしたかどうかも確認が必要です。

各アーカイブには、PGP 署名を含む .asc ファイルが付属しています。両方を同じフォルダに入れることで署名を確認できます。

$ gpg --verify Weblate-3.5.tar.xz.asc
gpg: assuming signed data in 'Weblate-3.5.tar.xz'
gpg: Signature made Ne 3. března 2019, 16:43:15 CET
gpg:                using RSA key 87E673AF83F6C3A0C344C8C3F4AA229D4D58C245
gpg: Can't check signature: public key not found

ご覧のとおり、GPG は公開鍵が分からないと苦情を言ってます。この時点で、どれかを実行することが必要な手順:

  • wkd を使用して鍵をダウンロードする:

$ gpg --auto-key-locate wkd --locate-keys michal@cihar.com
pub   rsa4096 2009-06-17 [SC]
      63CB1DF1EF12CF2AC0EE5A329C27B31342B7511D
uid           [ultimate] Michal Čihař <michal@cihar.com>
uid           [ultimate] Michal Čihař <nijel@debian.org>
uid           [ultimate] [jpeg image of size 8848]
uid           [ultimate] Michal Čihař (Braiins) <michal.cihar@braiins.cz>
sub   rsa4096 2009-06-17 [E]
sub   rsa4096 2015-09-09 [S]
$ gpg --import wmxth3chu9jfxdxywj1skpmhsj311mzm
  • 鍵サーバーの 1 つから鍵をダウンロードしてインポートする:

$ gpg --keyserver hkp://pgp.mit.edu --recv-keys 87E673AF83F6C3A0C344C8C3F4AA229D4D58C245
gpg: key 9C27B31342B7511D: "Michal Čihař <michal@cihar.com>" imported
gpg: Total number processed: 1
gpg:              unchanged: 1

これは状況を少し改善させます - この時点で、指定した鍵からの署名が正しいことを確認できますが、鍵で使用されている名前の信頼はできない:

$ gpg --verify Weblate-3.5.tar.xz.asc
gpg: assuming signed data in 'Weblate-3.5.tar.xz'
gpg: Signature made Ne 3. března 2019, 16:43:15 CET
gpg:                using RSA key 87E673AF83F6C3A0C344C8C3F4AA229D4D58C245
gpg: Good signature from "Michal Čihař <michal@cihar.com>" [ultimate]
gpg:                 aka "Michal Čihař <nijel@debian.org>" [ultimate]
gpg:                 aka "[jpeg image of size 8848]" [ultimate]
gpg:                 aka "Michal Čihař (Braiins) <michal.cihar@braiins.cz>" [ultimate]
gpg: WARNING: This key is not certified with a trusted signature!
gpg:          There is no indication that the signature belongs to the owner.
Primary key fingerprint: 63CB 1DF1 EF12 CF2A C0EE  5A32 9C27 B313 42B7 511D

ここでの問題は、誰でもこの名前で鍵を発行できることです。鍵が実際にその人物が所有しているかどうかの確認が必要です。 GNU プライバシー ハンドブックでは、Validating other keys on your public keyring の章でこの話題を扱っています。最も信頼できる方法は、開発者と直接会って鍵の指紋を交換することですが、信頼できる WEB に頼ることもできます。これにより、開発者に直接会った他の人の署名を使用して、鍵を関節的に信頼できます。

鍵が信頼されると、警告は発生しない:

$ gpg --verify Weblate-3.5.tar.xz.asc
gpg: assuming signed data in 'Weblate-3.5.tar.xz'
gpg: Signature made Sun Mar  3 16:43:15 2019 CET
gpg:                using RSA key 87E673AF83F6C3A0C344C8C3F4AA229D4D58C245
gpg: Good signature from "Michal Čihař <michal@cihar.com>" [ultimate]
gpg:                 aka "Michal Čihař <nijel@debian.org>" [ultimate]
gpg:                 aka "[jpeg image of size 8848]" [ultimate]
gpg:                 aka "Michal Čihař (Braiins) <michal.cihar@braiins.cz>" [ultimate]

署名が無効な場合(アーカイブ改ざん時)、鍵が信頼できるかどうかにかかわらず、表示される明確なエラー:

$ gpg --verify Weblate-3.5.tar.xz.asc
gpg: Signature made Sun Mar  3 16:43:15 2019 CET
gpg:                using RSA key 87E673AF83F6C3A0C344C8C3F4AA229D4D58C245
gpg: BAD signature from "Michal Čihař <michal@cihar.com>" [ultimate]

ファイル システムのアクセス権

Weblate プロセスは、データーを保持するディレクトリに対して読み書きできることが必要 - DATA_DIR 。このディレクトリ内のすべてのファイルは、すべての Weblat プロセス(通常は WSGI と Celery、参照 Running server および Background tasks using Celery)を実行しているユーザーが所有し、書き込み可能であることが必要です。

デフォルトの設定では、これらは Weblate のソースと同じ階層に配置されますが、より適切な場所に移動が可能: /var/lib/weblate

Weblate は、これらのディレクトリを自動的に作成を試みます。しかし、アクセス権がない場合は失敗します。

また、Management commands の実行時には注意が必要です。これは、Weblate 自体の実行と同じユーザーで実行することが必要なためです。そうでなければ、アクセス権を間違ったファイルがあります。

Docker コンテナでは、/app/data ボリューム内のすべてのファイルは、コンテナ内の weblate ユーザーが所有者であることが必要です(UID 1000)。

Weblate のデータベース設定

PostgreSQL データベース サーバーで Weblate を実行することをお勧めします。

PostgreSQL

通常、PostgreSQL は Django ベースのサイトに最適です。これは、Django データベース層の実装に使用する参照データベースです。

注釈

Weblate では、場合によっては個別にインストールすることが必要なトライグラム拡張機能を使用します。postgresql-contrib または同様の名前のパッケージを探してください。

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 -O weblate weblate

ヒント

Weblate ユーザーを PostgreSQL のスーパーユーザーにしたくない場合は、省略ができます。その場合、いくつかの移行手順をスキーマ Weblate の PostgreSQL スーパーユーザーとして手動で実行することが必要:

CREATE EXTENSION IF NOT EXISTS pg_trgm WITH SCHEMA weblate;

PostgreSQL を使用するための Webrate の設定

settings.py PostgreSQL 用のスニペット:

DATABASES = {
    "default": {
        # Database engine
        "ENGINE": "django.db.backends.postgresql",
        # Database name
        "NAME": "weblate",
        # Database user
        "USER": "weblate",
        # Name of role to alter to set parameters in PostgreSQL,
        # use in case role name is different than user used for authentication.
        # "ALTER_ROLE": "weblate",
        # Database password
        "PASSWORD": "password",
        # Set to empty string for localhost
        "HOST": "database.example.com",
        # Set to empty string for default
        "PORT": "",
    }
}

データベースの移行では、Weblate が使用するデータベース ロールに対して ALTER ROLE を実行します。ほとんどの場合、ロールの名前は username と一致します。より複雑な設定では、ロール名がユーザ名と異なり、データベース移行中に存在しないロールに関するエラーが発生します(psycopg2.errors.UndefinedObject: role "weblate@hostname" does not exist)。これは Azure Database for PostgreSQL で発生することが判明していますが、この環境に限定されません。データベースの移行中に Weblate で変更するロールの名前を変更するには、ALTER_ROLE と設定してください。

MySQL と MariaDB

ヒント

Weblate の機能の中には、PostgreSQL を使用するとパフォーマンスが向上するものがあります。これには、検索と翻訳メモリが含まれます。どちらもデータベースの全文機能を利用しており、PostgreSQL を実装する方が優れています。

Weblate は MySQL や MariaDB でも使用できます。Django を使用する際の注意事項については、MySQL notes および MariaDB notes を確認してください。制限があるため、新規インストールには PostgreSQL の使用をお勧めします。

Weblate には、MySQL 5.7.8 以上または MariaDB 10.2.7 以上が必要です。

Weblate で推奨する設定:

  • utf8mb4 文字セットを使用して、より高い Unicode プレーン(絵文字など)の表現を可能にする。

  • テキスト フィールドでより長いインデックスを使用できるように、innodb_large_prefix をサーバーに設定する。

  • 分離レベルを READ COMMITTED に設定する。

  • SQL モードは STRICT_TRANS_TABLES に設定が必要。

Below is an example /etc/my.cnf.d/server.cnf for a server with 8 GB of RAM. These settings should be sufficient for most installs. MySQL and MariaDB have tunables that will increase the performance of your server that are considered not necessary unless you are planning on having large numbers of concurrent users accessing the system. See the various vendors documentation on those details.

Weblate のインストールを開始する前に MySQL/MariaDB が再起動されるため、innodb_file_per_table を適切に設定してインストール時の問題を減らすことが非常に重要です。

[mysqld]
character-set-server = utf8mb4
character-set-client = utf8mb4
collation-server = utf8mb4_unicode_ci

datadir=/var/lib/mysql

log-error=/var/log/mariadb/mariadb.log

innodb_large_prefix=1
innodb_file_format=Barracuda
innodb_file_per_table=1
innodb_buffer_pool_size=2G
sql_mode=STRICT_TRANS_TABLES

ヒント

#1071 - Specified key was too long; max key length is 767 bytes というメッセージが表示された場合、上記の innodb 設定を含むように構成を更新し、インストールを再開してください。

MySQL/MariaDB を使用するための Weblate の設定

settings.py MySQL と MariaDB 用のスニペット:

DATABASES = {
    "default": {
        # Database engine
        "ENGINE": "django.db.backends.mysql",
        # Database name
        "NAME": "weblate",
        # Database user
        "USER": "weblate",
        # Database password
        "PASSWORD": "password",
        # Set to empty string for localhost
        "HOST": "127.0.0.1",
        # Set to empty string for default
        "PORT": "3306",
        # In case you wish to use additional
        # connection options
        "OPTIONS": {},
    }
}

You should also create the weblate user account in MySQL or MariaDB before you begin the install. Use the commands below to achieve that:

GRANT ALL ON weblate.* to 'weblate'@'localhost' IDENTIFIED BY 'password';
FLUSH PRIVILEGES;

その他の設定

メール送信の設定

Weblate は、多くのタイミングでメールを送信します - アカウントの有効化やユーザーが設定した通知など。そのためには、SMTP サーバへの接続が必要です。

メール サーバーのセットアップは、次の設定を使用して設定する:django:EMAIL_HOSTEMAIL_HOST_PASSWORDEMAIL_USE_TLSEMAIL_USE_TLSEMAIL_HOST_USER および EMAIL_PORT。 名前は一目瞭然ですが、詳細については Django の資料を確認してください。

ヒント

対応していない認証方法に関するエラーが発生した場合(例 SMTP AUTH extension not supported by server)、安全でない接続を使用していることが原因である可能性が高く、サーバーはこの方法による認証を拒否します。このような場合は、EMAIL_USE_TLS を有効にしてみてください。

リバース プロキシの背後で実行

Weblate の複数の機能は、クライアントの IP アドレスを取得できることを前提にしています。これには、接続制限Spam protection または 監査ログ が含まれます。

デフォルト構成では、WEBlate は WSGI ハンドラーによって設定された REMOTE_ADDR から IP アドレスを解析します。

リバース プロキシーを実行している場合、このフィールドには通常、そのアドレスが含まれます。追加の HTTP ヘッダーを信頼し、これらから IP アドレスを解析するように Webrate を設定することが必要です。リバース プロキシを使用しないインストールでは IP アドレスのスプーフィングが許可されるため、デフォルトでは有効にできません。IP_BEHIND_REVERSE_PROXY を有効化するだけで通常の設定では十分ですが、IP_PROXY_HEADER および IP_PROXY_OFFSET の設定も調整が必要です。

HTTP プロキシ

Weblate は VCS コマンドを実行し、それらは環境からプロキシ設定を受け入れます。次の場所でプロキシ設定の設定をお勧めします settings.py:

import os

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

設定の調整

Copy weblate/settings_example.py to weblate/settings.py and adjust it to match your setup. You will probably want to adjust the following options:

ADMINS

List of site administrators to receive notifications when something goes wrong, for example notifications on failed merges, or Django errors.

参考

ADMINS

ALLOWED_HOSTS

You need to set this to list the hosts your site is supposed to serve. For example:

ALLOWED_HOSTS = ["demo.weblate.org"]

Alternatively you can include wildcard:

ALLOWED_HOSTS = ["*"]

SESSION_ENGINE

Configure how your sessions will be stored. In case you keep the default database backend engine, you should schedule: weblate clearsessions to remove stale session data from the database.

If you are using Redis as cache (see Enable caching) it is recommended to use it for sessions as well:

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

DATABASES

Connectivity to database server, please check Django's documentation for more details.

DEBUG

Disable this for any production server. With debug mode enabled, Django will show backtraces in case of error to users, when you disable it, errors will be sent per e-mail to ADMINS (see above).

Debug mode also slows down Weblate, as Django stores much more info internally in this case.

参考

DEBUG

DEFAULT_FROM_EMAIL

E-mail sender address for outgoing e-mail, for example registration e-mails.

SECRET_KEY

Key used by Django to sign some info in cookies, see Django secret key for more info.

参考

SECRET_KEY

SERVER_EMAIL

E-mail used as sender address for sending e-mails to the administrator, for example notifications on failed merges.

参考

SERVER_EMAIL

Filling up the database

After your configuration is ready, you can run weblate migrate to create the database structure. Now you should be able to create translation projects using the admin interface.

In case you want to run an installation non interactively, you can use weblate migrate --noinput, and then create an admin user using createadmin command.

Once you are done, you should also check the Performance report in the admin interface, which will give you hints of potential non optimal configuration on your site.

Production setup

For a production setup you should carry out adjustments described in the following sections. The most critical settings will trigger a warning, which is indicated by an exclamation mark in the top bar if signed in as a superuser:

../_images/admin-wrench.png

It is also recommended to inspect checks triggered by Django (though you might not need to fix all of them):

weblate check --deploy

You can also review the very same checklist from the Management interface.

Disable debug mode

Disable Django's debug mode (DEBUG) by:

DEBUG = False

With debug mode on, Django stores all executed queries and shows users backtraces of errors, which is not desired in a production setup.

Properly configure admins

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

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

Set correct site domain

Adjust site name and domain in the admin interface, otherwise links in RSS or registration e-mails will not work. This is configured using SITE_DOMAIN which should contain site domain name.

バージョン 4.2 で変更: Prior to the 4.2 release the Django sites framework was used instead, please see The “sites” framework.

Correctly configure HTTPS

It is strongly recommended to run Weblate using the encrypted HTTPS protocol. After enabling it, you should set ENABLE_HTTPS in the settings:

ENABLE_HTTPS = True

ヒント

You might want to set up HSTS as well, see SSL/HTTPS for more details.

Set properly SECURE_HSTS_SECONDS

If your site is served over SSL, you have to consider setting a value for SECURE_HSTS_SECONDS in the settings.py to enable HTTP Strict Transport Security. By default it's set to 0 as shown below.

SECURE_HSTS_SECONDS = 0

If set to a non-zero integer value, the django.middleware.security.SecurityMiddleware sets the HTTP Strict Transport Security header on all responses that do not already have it.

警告

Setting this incorrectly can irreversibly (for some time) break your site. Read the HTTP Strict Transport Security documentation first.

Use a powerful database engine

Please use PostgreSQL for a production environment, see Weblate のデータベース設定 for more info.

Enable caching

If possible, use Redis from Django by adjusting the CACHES configuration variable, for example:

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",
        },
    }
}

ヒント

In case you change Redis settings for the cache, you might need to adjust them for Celery as well, see Background tasks using Celery.

アバターのキャッシュ

In addition to caching of Django, Weblate performs caching of avatars. It is recommended to use a separate, file-backed cache for this purpose:

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,
        },
    },
}

Configure e-mail sending

Weblate needs to send out e-mails on several occasions, and these e-mails should have a correct sender address, please configure SERVER_EMAIL and DEFAULT_FROM_EMAIL to match your environment, for example:

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

注釈

To disable sending e-mails by Weblate set EMAIL_BACKEND to django.core.mail.backends.dummy.EmailBackend.

This will disable all e-mail delivery including registration or password reset e-mails.

Allowed hosts setup

Django requires ALLOWED_HOSTS to hold a list of domain names your site is allowed to serve, leaving it empty will block any requests.

In case this is not configured to match your HTTP server, you will get errors like Invalid HTTP_HOST header: '1.1.1.1'. You may need to add '1.1.1.1' to ALLOWED_HOSTS.

ヒント

On Docker container, this is available as WEBLATE_ALLOWED_HOSTS.

Django secret key

The SECRET_KEY setting is used by Django to sign cookies, and you should really generate your own value rather than using the one from the example setup.

You can generate a new key using weblate/examples/generate-secret-key shipped with Weblate.

参考

SECRET_KEY

Home directory

バージョン 2.1 で変更: This is no longer required, Weblate now stores all its data in DATA_DIR.

The home directory for the user running Weblate should exist and be writable by this user. This is especially needed if you want to use SSH to access private repositories, but Git might need to access this directory as well (depending on the Git version you use).

You can change the directory used by Weblate in settings.py, for example to set it to configuration directory under the Weblate tree:

os.environ["HOME"] = os.path.join(BASE_DIR, "configuration")

注釈

On Linux, and other UNIX like systems, the path to user's home directory is defined in /etc/passwd. Many distributions default to a non-writable directory for users used for serving web content (such as apache, www-data or wwwrun), so you either have to run Weblate under a different user, or change this setting.

Template loading

It is recommended to use a cached template loader for Django. It caches parsed templates and avoids the need to do parsing with every single request. You can configure it using the following snippet (the loaders setting is important here):

TEMPLATES = [
    {
        "BACKEND": "django.template.backends.django.DjangoTemplates",
        "DIRS": [
            os.path.join(BASE_DIR, "templates"),
        ],
        "OPTIONS": {
            "context_processors": [
                "django.contrib.auth.context_processors.auth",
                "django.template.context_processors.debug",
                "django.template.context_processors.i18n",
                "django.template.context_processors.request",
                "django.template.context_processors.csrf",
                "django.contrib.messages.context_processors.messages",
                "weblate.trans.context_processors.weblate_context",
            ],
            "loaders": [
                (
                    "django.template.loaders.cached.Loader",
                    [
                        "django.template.loaders.filesystem.Loader",
                        "django.template.loaders.app_directories.Loader",
                    ],
                ),
            ],
        },
    },
]

Running maintenance tasks

For optimal performance, it is good idea to run some maintenance tasks in the background. This is now automatically done by Background tasks using Celery and covers following tasks:

  • Configuration health check (hourly).

  • Committing pending changes (hourly), see Lazy commits and commit_pending.

  • Updating component alerts (daily).

  • Update remote branches (nightly), see AUTO_UPDATE.

  • Translation memory backup to JSON (daily), see dump_memory.

  • Fulltext and database maintenance tasks (daily and weekly tasks), see cleanuptrans.

バージョン 3.2 で変更: Since version 3.2, the default way of executing these tasks is using Celery and Weblate already comes with proper configuration, see Background tasks using Celery.

System locales and encoding

The system locales should be configured to UTF-8 capable ones. On most Linux distributions this is the default setting. In case it is not the case on your system, please change locales to UTF-8 variant.

For example by editing /etc/default/locale and setting there LANG="C.UTF-8".

In some cases the individual services have separate configuration for locales. For example when using Apache you might want to set it in /etc/apache2/envvars:

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

Using custom certificate authority

Weblate does verify SSL certificates during HTTP requests. In case you are using custom certificate authority which is not trusted in default bundles, you will have to add its certificate as trusted.

The preferred approach is to do this at system level, please check your distro 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).

Once this is done, system tools will trust the certificate and this includes Git.

For Python code, you will need to configure requests to use system CA bundle instead of the one shipped with it. This can be achieved by placing following snippet to settings.py (the path is Debian specific):

import os

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

Compressing client assets

Weblate comes with a bunch of JavaScript and CSS files. For performance reasons it is good to compress them before sending to a client. In default configuration this is done on the fly at cost of little overhead. On big installations, it is recommended to enable offline compression mode. This needs to be done in the configuration and the compression has to be triggered on every Weblate upgrade.

The configuration switch is simple by enabling django.conf.settings.COMPRESS_OFFLINE and configuring django.conf.settings.COMPRESS_OFFLINE_CONTEXT (the latter is already included in the example configuration):

COMPRESS_OFFLINE = True

On each deploy you need to compress the files to match current version:

weblate compress

ヒント

The official Docker image has this feature already enabled.

Running server

You will need several services to run Weblate, the recommended setup consists of:

注釈

There are some dependencies between the services, for example cache and database should be running when starting up Celery or uwsgi processes.

In most cases, you will run all services on single (virtual) server, but in case your installation is heavy loaded, you can split up the services. The only limitation on this is that Celery and Wsgi servers need access to DATA_DIR.

注釈

The WSGI process has to be executed under the same user the Celery process, otherwise files in the DATA_DIR will be stored with mixed ownership, leading to runtime issues.

See also ファイル システムのアクセス権 and Background tasks using Celery.

Running web server

Running Weblate is not different from running any other Django based program. Django is usually executed as uWSGI or fcgi (see examples for different webservers below).

For testing purposes, you can use the built-in web server in Django:

weblate runserver

警告

DO NOT USE THIS SERVER IN A PRODUCTION SETTING. It has not gone through security audits or performance tests. See also Django documentation on runserver.

ヒント

The Django built-in server serves static files only with DEBUG enabled as it is intended for development only. For production use, please see wsgi setups in Sample configuration for NGINX and uWSGI, Sample configuration for Apache, Sample configuration for Apache and Gunicorn, and Serving static files.

Serving static files

バージョン 2.4 で変更: Prior to version 2.4, Weblate didn't properly use the Django static files framework and the setup was more complex.

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 DATA_DIR).

It is recommended to serve static files directly from your web server, you should use that for the following paths:

/static/

Serves static files for Weblate and the admin interface (from defined by STATIC_ROOT).

/media/

Used for user media uploads (e.g. screenshots).

/favicon.ico

Should be rewritten to rewrite a rule to serve /static/favicon.ico.

Content security policy

The default Weblate configuration enables weblate.middleware.SecurityMiddleware middleware which sets security related HTTP headers like Content-Security-Policy or X-XSS-Protection. These are by default set up to work with Weblate and its configuration, but this might need customization for your environment.

Sample configuration for NGINX and uWSGI

To run production webserver, use the wsgi wrapper installed with Weblate (in virtual env case it is installed as ~/weblate-env/lib/python3.7/site-packages/weblate/wsgi.py). Don't forget to set the Python search path to your virtualenv as well (for example using virtualenv = /home/user/weblate-env in uWSGI).

The following configuration runs Weblate as uWSGI under the NGINX webserver.

Configuration for NGINX (also available as weblate/examples/weblate.nginx.conf):

# This example assumes Weblate is installed in virtualenv in /home/weblate/weblate-env
# and DATA_DIR is set to /home/weblate/data, please adjust paths to match your setup.
server {
    listen 80;
    server_name weblate;
    # Not used
    root /var/www/html;

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

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

    location /media/ {
        # DATA_DIR/media/
        alias /home/weblate/data/media/;
        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;
    }
}

Configuration for uWSGI (also available as weblate/examples/weblate.uwsgi.ini):

# This example assumes Weblate is installed in virtualenv in /home/weblate/weblate-env
# and DATA_DIR is set to /home/weblate/data, please adjust paths to match your setup.
[uwsgi]
plugins       = python3
master        = true
protocol      = uwsgi
socket        = 127.0.0.1:8080
wsgi-file     = /home/weblate/weblate-env/lib/python3.7/site-packages/weblate/wsgi.py

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

# In case you're using virtualenv uncomment this:
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

Sample configuration for Apache

It is recommended to use prefork MPM when using WSGI with Weblate.

The following configuration runs Weblate as WSGI, you need to have enabled mod_wsgi (available as weblate/examples/apache.conf):

#
# VirtualHost for Weblate
#
# This example assumes Weblate is installed in virtualenv in /home/weblate/weblate-env
# and DATA_DIR is set to /home/weblate/data, please adjust paths to match your setup.
#
<VirtualHost *:80>
    ServerAdmin admin@weblate.example.org
    ServerName weblate.example.org

    # DATA_DIR/static/favicon.ico
    Alias /favicon.ico /home/weblate/data/static/favicon.ico

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

    # DATA_DIR/media/
    Alias /media/ /home/weblate/data/media/
    <Directory /home/weblate/data/media/>
        Require all granted
    </Directory>

    # Path to your Weblate virtualenv
    WSGIDaemonProcess weblate python-home=/home/weblate/weblate-env user=weblate
    WSGIProcessGroup weblate
    WSGIApplicationGroup %{GLOBAL}

    WSGIScriptAlias / /home/weblate/weblate-env/lib/python3.7/site-packages/weblate/wsgi.py process-group=weblate request-timeout=600
    WSGIPassAuthorization On

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

</VirtualHost>

注釈

Weblate requires Python 3, so please make sure you are running Python 3 variant of the modwsgi. Usually it is available as a separate package, for example libapache2-mod-wsgi-py3.

Sample configuration for Apache and Gunicorn

The following configuration runs Weblate in Gunicorn and Apache 2.4 (available as weblate/examples/apache.gunicorn.conf):

#
# VirtualHost for Weblate using gunicorn on localhost:8000
#
# This example assumes Weblate is installed in virtualenv in /home/weblate/weblate-env
# and DATA_DIR is set to /home/weblate/data, please adjust paths to match your setup.
#
<VirtualHost *:443>
    ServerAdmin admin@weblate.example.org
    ServerName weblate.example.org

    # DATA_DIR/static/favicon.ico
    Alias /favicon.ico /home/weblate/data/static/favicon.ico

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

    # DATA_DIR/media/
    Alias /media/ /home/weblate/data/media/
    <Directory /home/weblate/data/media/>
        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 /media/ !

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

Running Weblate under path

バージョン 1.3 で変更: This is supported since Weblate 1.3.

It is recommended to use prefork MPM when using WSGI with Weblate.

A sample Apache configuration to serve Weblate under /weblate. Again using mod_wsgi (also available as weblate/examples/apache-path.conf):

#
# VirtualHost for Weblate, running under /weblate path
#
# This example assumes Weblate is installed in virtualenv in /home/weblate/weblate-env
# and DATA_DIR is set to /home/weblate/data, please adjust paths to match your setup.
#
<VirtualHost *:80>
    ServerAdmin admin@weblate.example.org
    ServerName weblate.example.org

    # DATA_DIR/static/favicon.ico
    Alias /weblate/favicon.ico /home/weblate/data/static/favicon.ico

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

    # DATA_DIR/media/
    Alias /weblate/media/ /home/weblate/data/media/
    <Directory /home/weblate/data/media/>
        Require all granted
    </Directory>

    # Path to your Weblate virtualenv
    WSGIDaemonProcess weblate python-home=/home/weblate/weblate-env user=weblate
    WSGIProcessGroup weblate
    WSGIApplicationGroup %{GLOBAL}

    WSGIScriptAlias /weblate /home/weblate/weblate-env/lib/python3.7/site-packages/weblate/wsgi.py process-group=weblate request-timeout=600
    WSGIPassAuthorization On

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

</VirtualHost>

Additionally, you will have to adjust weblate/settings.py:

URL_PREFIX = "/weblate"

Background tasks using Celery

バージョン 3.2 で追加.

Weblate uses Celery to process background tasks. A typical setup using Redis as a backend looks like this:

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

For development, you might want to use eager configuration, which does process all tasks in place, but this will have performance impact on Weblate:

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

You should also start the Celery worker to process the tasks and start scheduled tasks, this can be done directly on the command line (which is mostly useful when debugging or developing):

./weblate/examples/celery start
./weblate/examples/celery stop

注釈

The Celery process has to be executed under the same user as the WSGI process, otherwise files in the DATA_DIR will be stored with mixed ownership, leading to runtime issues.

See also ファイル システムのアクセス権 and Running server.

Running Celery as system service

Most likely you will want to run Celery as a daemon and that is covered by Daemonization. For the most common Linux setup using systemd, you can use the example files shipped in the examples folder listed below.

Systemd unit to be placed as /etc/systemd/system/celery-weblate.service:

[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

Environment configuration to be placed as /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,
# increase concurency if you get weblate.E019
CELERYD_OPTS="--beat:celery --queues:celery=celery --prefetch-multiplier:celery=4 \
    --queues:notify=notify --prefetch-multiplier:notify=10 \
    --queues:memory=memory --prefetch-multiplier:memory=10 \
    --queues:translate=translate --prefetch-multiplier:translate=4 \
    --concurrency:backup=1 --queues:backup=backup  --prefetch-multiplier:backup=2"

# 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"

# Internal Weblate variable to indicate we're running inside Celery
CELERY_WORKER_RUNNING="1"

Logrotate configuration to be placed as /etc/logrotate.d/celery:

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

Periodic tasks using Celery beat

Weblate comes with built-in setup for scheduled tasks. You can however define additional tasks in settings.py, for example see Lazy commits.

The tasks are supposed to be executed by Celery beats daemon. In case it is not working properly, it might not be running or its database was corrupted. Check the Celery startup logs in such case to figure out root cause.

Monitoring Celery status

You can use celery_queues to see current length of Celery task queues. In case the queue will get too long, you will also get configuration error in the admin interface.

警告

The Celery errors are by default only logged into Celery log and are not visible to user. In case you want to have overview on such failures, it is recommended to configure Collecting error reports.

Monitoring Weblate

Weblate provides the /healthz/ URL to be used in simple health checks, for example using Kubernetes.

Collecting error reports

Weblate, as any other software, can fail. In order to collect useful failure states we recommend to use third party services to collect such information. This is especially useful in case of failing Celery tasks, which would otherwise only report error to the logs and you won't get notified on them. Weblate has support for the following services:

Sentry

Weblate has built-in support for Sentry. To use it, it's enough to set SENTRY_DSN in the settings.py:

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

Rollbar

Weblate has built-in support for Rollbar. To use it, it's enough to follow instructions for Rollbar notifier for Python.

In short, you need to adjust 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",
    "client_token": "POST_CLIENT_ITEM_ACCESS_TOKEN",
    "environment": "development" if DEBUG else "production",
    "branch": "master",
    "root": "/absolute/path/to/code/root",
}

Everything else is integrated automatically, you will now collect both server and client side errors.

Migrating Weblate to another server

Migrating Weblate to another server should be pretty easy, however it stores data in few locations which you should migrate carefully. The best approach is to stop Weblate for the migration.

Migrating database

Depending on your database backend, you might have several options to migrate the database. The most straightforward one is to dump the database on one server and import it on the new one. Alternatively you can use replication in case your database supports it.

The best approach is to use database native tools, as they are usually the most effective (e.g. mysqldump or pg_dump). If you want to migrate between different databases, the only option might be to use Django management to dump and import the database:

# Export current data
weblate dumpdata > /tmp/weblate.dump
# Import dump
weblate loaddata /tmp/weblate.dump

Migrating VCS repositories

The VCS repositories stored under DATA_DIR need to be migrated as well. You can simply copy them or use rsync to do the migration more effectively.

Other notes

Don't forget to move other services Weblate might have been using like Redis, Cron jobs or custom authentication backends.