Instrukcje konfiguracji#

Instalacja Weblate#

Depending on your setup and experience, choose an appropriate installation method for you:

Architecture overview#

digraph architecture { graph [fontname="sans-serif", fontsize=10, newrank=true, rankdir=LR, splines=ortho ]; node [fontname="sans-serif", fontsize=10, height=0, margin=.15, shape=box ]; edge [fontname="sans-serif", fontsize=10 ]; subgraph cluster_thirdparty { graph [color=lightgrey, label="Third-party services", style=filled ]; mt [label="Machine translation", style=dotted]; sentry [label="Sentry\nError collection", style=dotted]; mail [label="E-mail server"]; auth [label="SSO\nAuthentication provider", style=dotted]; } subgraph cluster_ingress { graph [color=lightgrey, label=Ingress, style=filled ]; web [label="Web server", shape=hexagon]; } subgraph cluster_weblate { graph [color=lightgrey, label="Weblate code-base", style=filled ]; celery [fillcolor="#144d3f", fontcolor=white, label="Celery workers", style=filled]; wsgi [fillcolor="#144d3f", fontcolor=white, label="WSGI server", style=filled]; } subgraph cluster_services { graph [color=lightgrey, label=Services, style=filled ]; redis [label="Redis\nTask queue\nCache", shape=cylinder]; db [label="PostgreSQL\nDatabase", shape=cylinder]; fs [label=Filesystem, shape=cylinder]; } web -> wsgi; web -> fs; celery -> mt [style=dotted]; celery -> sentry [style=dotted]; celery -> mail; celery -> redis; celery -> db; celery -> fs; wsgi -> mt [style=dotted]; wsgi -> sentry [style=dotted]; wsgi -> auth [style=dotted]; wsgi -> redis; wsgi -> db; wsgi -> fs; }

Wymagania dotyczące oprogramowania#

System operacyjny#

Weblate is known to work on Linux, FreeBSD and macOS. Other Unix like systems will most likely work too.

Weblate is not supported on Windows. But it may still work and patches are happily accepted.

Inne usługi#

Weblate is using other services for its operation. You will need at least following services running:

Podpowiedź

Instalowanie za pomocą Dockera includes PostgreSQL and Redis, making the installation easier.

Zależności ythona#

Weblate is written in Python and supports Python 3.10 or newer. You can install dependencies using pip or from your distribution packages, full list is available in requirements.txt.

Najbardziej znaczące zależności:

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/

When installing using pip, you can directly specify desired features when installing:

pip install "Weblate[Postgres,Amazon,SAML]"

Lub możesz zainstalować Weblate ze wszystkimi opcjonalnymi funkcjami:

pip install "Weblate[all]"

Or you can install Weblate without any optional features:

pip install Weblate

Inne wymagania systemowe#

The following dependencies have to be installed on the system:

Git

https://git-scm.com/

Pango, Cairo and related header files and GObject introspection data

https://cairographics.org/, https://pango.gnome.org/, patrz Pango i Cairo

git-review (opcjonalnie dla obsługi Gerrit)

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

git-svn (opcjonalnie dla obsługi Subversion)

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

tesseract (needed only if tesserocr binary wheels are not available for your system)

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

licensee (optional for detecting license when creating component)

https://github.com/licensee/licensee

Zależność od czasu kompilacji#

To build some of the Zależności ythona you might need to install their dependencies. This depends on how you install them, so please consult individual packages for documentation. You won’t need those if using prebuilt Wheels while installing using pip or when you use distribution packages.

Pango i Cairo#

Weblate uses Pango and Cairo for rendering bitmap widgets (see Promowanie tłumaczenia) and rendering checks (see Zarządzanie czcionkami). To properly install Python bindings for those you need to install system libraries first - you need both Cairo and Pango, which in turn need GLib. All those should be installed with development files and GObject introspection data.

Weryfikowanie podpisów wersji#

Weblate release are cryptographically signed using Sigstore signatures. The signatures are attached to the GitHub release.

The verification can be performed using sigstore package. The following example verifies signature of the 5.4 release:

sigstore verify github  \
   --cert-identity https://github.com/WeblateOrg/weblate/.github/workflows/setup.yml@refs/tags/weblate-5.4 \
   --bundle Weblate-5.4-py3-none-any.whl.sigstore \
   Weblate-5.4-py3-none-any.whl

Uprawnienia systemu plików#

The Weblate process needs to be able to read and write to the directory where it keeps data - DATA_DIR. All files within this directory should be owned and writable by the user running all Weblate processes (typically WSGI and Celery, see Uruchamianie serwera and Zadania w tle korzystające z Celery).

The default configuration places them in the same tree as the Weblate sources, however you might prefer to move these to a better location such as: /var/lib/weblate.

Weblate tries to create these directories automatically, but it will fail when it does not have permissions to do so.

You should also take care when running Polecenia zarządzania, as they should be ran under the same user as Weblate itself is running, otherwise permissions on some files might be wrong.

In the Docker container, all files in the /app/data volume have to be owned by the weblate user inside the container (UID 1000).

Konfiguracja bazy danych dla Weblate#

It is recommended to run Weblate with a PostgreSQL database server.

PostgreSQL 12 and higher is supported. PostgreSQL 15 or newer is recommended.

MySQL i MariaDB is supported, but not recommended for new installs.

No other database servers are supported.

Database connections#

In the default configuration, each Weblate process keeps a persistent connection to the database. Persistent connections improve Weblate responsiveness, but might require more resources for the database server. Please consult CONN_MAX_AGE and Persistent connections for more info.

Weblate needs at least the following number of connections:

  • \((4 \times \mathit{nCPUs}) + 2\) for Celery processes

  • \(\mathit{nCPUs} + 1\) for WSGI workers

This applies to Docker container defaults and example configurations provided in this documentation, but the numbers will change once you customize the amount of WSGI workers or adjust parallelism of Celery.

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

  • Polecenia zarządzania need their connection as well.

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

PostgreSQL#

PostgreSQL is usually the best choice for Django-based sites. It’s the reference database used for implementing Django database layer.

Informacja

Weblate uses trigram extension which has to be installed separately in some cases. Look for postgresql-contrib or a similarly named package.

Zobacz także

PostgreSQL notes

Tworzenie bazy danych w PostgreSQL#

It is usually a good idea to run Weblate in a separate database, and separate user account:

# 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

Podpowiedź

If you don’t want to make the Weblate user a superuser in PostgreSQL, you can omit that. In that case you will have to perform some of the migration steps manually as a PostgreSQL superuser in schema Weblate will use:

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

Konfigurowanie Weblate do korzystania z PostgreSQL#

The settings.py snippet for 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": "",
        # Persistent connections
        "CONN_MAX_AGE": None,
        "CONN_HEALTH_CHECKS": True,
    }
}

The database migration performs ALTER ROLE on database role used by Weblate. In most cases the name of the role matches username. In more complex setups the role name is different than username and you will get error about non-existing role during the database migration (psycopg2.errors.UndefinedObject: role "weblate@hostname" does not exist). This is known to happen with Azure Database for PostgreSQL, but it’s not limited to this environment. Please set ALTER_ROLE to change name of the role Weblate should alter during the database migration.

Zobacz także

Database connections

MySQL i MariaDB#

Ostrzeżenie

While MySQL and MariaDB support is still maintained in Weblate, our primary focus is PostgreSQL. It is recommended to use PostgreSQL for new installs, and to migrate existing installs to PostgreSQL, see Migrating from other databases to PostgreSQL.

Some Weblate features will perform better with PostgreSQL. This includes searching and translation memory, which both utilize full-text features in the database and PostgreSQL implementation is superior.

Weblate can be also used with MySQL or MariaDB, please see MySQL notes and MariaDB notes for caveats using Django with those. Because of the limitations it is recommended to use PostgreSQL for new installations.

Weblate requires MySQL at least 8 or MariaDB at least 10.4.

Following configuration is recommended for Weblate:

  • Use the utf8mb4 charset to allow representation of higher Unicode planes (for example emojis).

  • Configure the server with innodb_large_prefix to allow longer indices on text fields.

  • Set the isolation level to READ COMMITTED.

  • The SQL mode should be set to STRICT_TRANS_TABLES.

MySQL 8.x, MariaDB 10.5.x or newer have reasonable default configuration so that no server tweaking should be necessary and all what is needed can be configured on the client side.

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.

It is absolutely critical to reduce issues when installing that the setting innodb_file_per_table is set properly and MySQL/MariaDB restarted before you start your Weblate install.

[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

Podpowiedź

In case you are getting #1071 - Specified key was too long; max key length is 767 bytes error, please update your configuration to include the innodb settings above and restart your install.

Podpowiedź

In case you are getting #2006 - MySQL server has gone away error, configuring CONN_MAX_AGE might help.

Zobacz także

Database connections

Konfigurowanie Weblate przy użyciu MySQL/MariaDB#

The settings.py snippet for MySQL and 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;

Zobacz także

Database connections

Inne konfiguracje#

Konfigurowanie poczty wychodzącej#

Weblate sends out e-mails on various occasions - for account activation and on various notifications configured by users. For this it needs access to an SMTP server.

The mail server setup is configured using these settings: EMAIL_HOST, EMAIL_HOST_PASSWORD, EMAIL_USE_TLS, EMAIL_USE_SSL, EMAIL_HOST_USER and EMAIL_PORT. Their names are quite self-explanatory, but you can find more info in the Django documentation.

Podpowiedź

In case you get error about not supported authentication (for example SMTP AUTH extension not supported by server), it is most likely caused by using insecure connection and server refuses to authenticate this way. Try enabling EMAIL_USE_TLS in such case.

Działanie za odwrotnym proxy#

Several features in Weblate rely on being able to get client IP address. This includes Ograniczenie szybkości, Ochrona przed spamem or Dziennik aktywności.

In default configuration Weblate parses IP address from REMOTE_ADDR which is set by the WSGI handler.

In case you are running a reverse proxy, this field will most likely contain its address. You need to configure Weblate to trust additional HTTP headers and parse the IP address from these. This can not be enabled by default as it would allow IP address spoofing for installations not using a reverse proxy. Enabling IP_BEHIND_REVERSE_PROXY might be enough for the most usual setups, but you might need to adjust IP_PROXY_HEADER and IP_PROXY_OFFSET as well.

Another thing to take care of is the Host header. It should match to whatever is configured as SITE_DOMAIN. Additional configuration might be needed in your reverse proxy (for example use ProxyPreserveHost On for Apache or proxy_set_header Host $host; with nginx).

HTTP proxy#

Weblate does execute VCS commands and those accept proxy configuration from environment. The recommended approach is to define proxy settings in settings.py:

import os

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

Dostosowywanie konfiguracji#

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.

Contact form sends e-mail on these as well unless ADMINS_CONTACT is configured.

ALLOWED_HOSTS

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

ALLOWED_HOSTS = ["demo.weblate.org"]

Alternatywnie można dołączyć symbol wieloznaczny:

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 Włączanie buforowania) 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.

DEFAULT_FROM_EMAIL

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

Zobacz także

DEFAULT_FROM_EMAIL

SECRET_KEY

Key used by Django to sign some info in cookies, see Tajny klucz Django for more info.

Zobacz także

SECRET_KEY

SERVER_EMAIL

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

Zobacz także

SERVER_EMAIL

Wypełnianie bazy danych#

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

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.

Instalacja produkcyjna#

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.webp

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 at Raport wydajności in the Interfejs zarządzania.

Wyłączenie trybu debugowania#

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.

Prawidłowe konfigurowanie administratorów#

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

Ustaw prawidłową domenę strony#

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.

Zmienione w wersji 4.2: Prior to the 4.2 release the Django sites framework was used instead, please see The „sites” framework.

Prawidłowa konfiguracja 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

Podpowiedź

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

Ustaw prawidłowo 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.

Ostrzeżenie

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

Użyj potężnego silnika bazy danych#

  • Please use PostgreSQL for a production environment, see Konfiguracja bazy danych dla Weblate for more info.

  • Use adjacent location for running the database server, otherwise the networking performance or reliability might ruin your Weblate experience.

  • Check the database server performance or tweak its configuration, for example using PGTune.

Włączanie buforowania#

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

Podpowiedź

In case you change Redis settings for the cache, you might need to adjust them for Celery as well, see Zadania w tle korzystające z Celery.

Pamięć podręczna awatarów#

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

Konfigurowanie wysyłania wiadomości e-mail#

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"

Informacja

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.

Konfiguracja dozwolonych hostów#

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.

Podpowiedź

On Docker container, this is available as WEBLATE_ALLOWED_HOSTS.

Tajny klucz Django#

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-generate-secret-key shipped with Weblate.

Zobacz także

SECRET_KEY

Uruchamianie zadań konserwacyjnych#

For optimal performance, it is good idea to run some maintenance tasks in the background. This is automatically done by Zadania w tle korzystające z Celery and covers following tasks:

  • Sprawdzanie kondycji konfiguracji (co godzinę).

  • Committing pending changes (hourly), see Leniwe zatwierdzenia and commit_pending.

  • Aktualizacja alertów komponentów (codziennie).

  • 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.

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. This varies between distribution and web servers, so check documentation of your web server packages for that.

Apache on Ubuntu uses /etc/apache2/envvars:

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

Apache on CentOS uses /etc/sysconfig/httpd (or /opt/rh/httpd24/root/etc/sysconfig/httpd):

LANG='en_US.UTF-8'

Korzystanie z niestandardowego urzędu certyfikacji#

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"

Kompresowanie zasobów klienta#

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

Podpowiedź

The official Docker image has this feature already enabled.

Uruchamianie serwera#

Podpowiedź

In case you are not experienced with services described below, you might want to try Instalowanie za pomocą Dockera.

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

Informacja

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.

Informacja

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 Uprawnienia systemu plików and Zadania w tle korzystające z Celery.

Uruchamianie serwer WWW#

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

Ostrzeżenie

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.

Podpowiedź

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, Przykładowa konfiguracja dla Apache, Sample configuration for Apache and Gunicorn, and Obsługa plików statycznych.

Obsługa plików statycznych#

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

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.

Polityka bezpieczeństwa treści#

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.9/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):

#
# nginx configuration for Weblate
#
# You will want to change:
#
# - server_name
# - change /home/weblate/weblate-env to location where Weblate virtualenv 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 /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):

#
# uWSGI configuration for Weblate
#
# You will want to change:
#
# - change /home/weblate/weblate-env to location where Weblate virtualenv 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

# 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

Przykładowa konfiguracja dla 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
#
# You will want to change:
#
# - ServerAdmin and ServerName
# - change /home/weblate/weblate-env to location where Weblate virtualenv 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>

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

Informacja

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

Use matching Python version to install Weblate.

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
#
# You will want to change:
#
# - ServerAdmin and ServerName
# - change /home/weblate/weblate-env to location where Weblate virtualenv 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>

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

Uruchamianie Weblate pod ścieżką#

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):

# Copyright © Michal Čihař <michal@weblate.org>
#
# SPDX-License-Identifier: GPL-3.0-or-later

#
# VirtualHost for Weblate, running under /weblate path
#
# You will want to change:
#
# - ServerAdmin and ServerName
# - change /home/weblate/weblate-env to location where Weblate virtualenv 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>

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

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

URL_PREFIX = "/weblate"

Zadania w tle korzystające z Celery#

Weblate uses Celery to execute regular and background tasks. You are supposed to run a Celery service that will execute these. For example, it is responsible for handling following operations (this list is not complete):

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

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

Informacja

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 Uprawnienia systemu plików and Uruchamianie serwera.

Executing Celery tasks in the WSGI using eager mode#

Informacja

This will have severe performance impact on the web interface, and will break features depending on regular trigger (for example committing pending changes, digest notifications, or backups).

For development, you might want to use eager configuration, which does process all tasks in place:

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

Uruchamianie Celery jako usługi systemowej#

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

Additional configuration to rotate Celery logs using logrotate to be placed as /etc/logrotate.d/celery:

# Copyright © Michal Čihař <michal@weblate.org>
#
# SPDX-License-Identifier: GPL-3.0-or-later

/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 Leniwe zatwierdzenia.

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.

Monitorowanie stanu Celery#

You can find current length of the Celery task queues in the Interfejs zarządzania or you can use celery_queues on the command-line. In case the queue will get too long, you will also get configuration error in the admin interface.

Ostrzeżenie

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 and monitoring performance.

Single-process Celery setup#

In case you have very limited memory, you might want to reduce number of Weblate processes. All Celery tasks can be executed in a single process using:

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

Ostrzeżenie

This will have a noticeable performance impact on Weblate.

Monitorowanie eblate#

Weblate provides the /healthz/ URL to be used in simple health checks, for example using Kubernetes. The Docker container has built-in health check using this URL.

For monitoring metrics of Weblate you can use GET /api/metrics/ API endpoint.

Collecting error reports and monitoring performance#

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

Sentry can be also used to monitor performance of Weblate by collecting traces and profiles for defined percentage of operations. This can be configured using SENTRY_TRACES_SAMPLE_RATE and SENTRY_PROFILES_SAMPLE_RATE.

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": "main",
    "root": "/absolute/path/to/code/root",
}

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

Informacja

Error logging also includes exceptions that were gracefully handled, but might indicate a problem - such as failed parsing of an uploaded file.

Migracja Weblate na inny serwer#

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.

Migrowanie bazy danych#

Depending on your database backend, you might have several options to migrate the database. The most straightforward approach is to use database native tools, as they are usually the most effective (e.g. mysqldump or pg_dump). Alternatively you can use replication in case your database supports it.

Zobacz także

Migrating between databases described in Migrating from other databases to PostgreSQL.

Migrowanie repozytoriów VCS#

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.

Inne uwagi#

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