Installing using Docker

With dockerized Weblate deployment you can get your personal Weblate instance up and running in seconds. All of Weblate’s dependencies are already included. PostgreSQL is set up as the default database.

Hardware requirements

Weblate should run on all contemporary hardware without problems, the following is the minimal configuration required to run Weblate on a single host (Weblate, database and webserver):

  • 2 GB of RAM
  • 2 CPU cores
  • 1 GB of storage space

The more memory the better - it is used for caching on all levels (filesystem, database and Weblate).

Many concurrent users increases the amount of needed CPU cores. For hundreds of translation components at least 4 GB of RAM is recommended.

Note

Actual requirements for your installation of Weblate vary heavily based on the size of the translations managed in it.

Installation

The following examples assume you have a working Docker environment, with docker-compose installed. Please check the Docker documentation for instructions.

  1. Clone the weblate-docker repo:

    git clone https://github.com/WeblateOrg/docker-compose.git weblate-docker
    cd weblate-docker
    
  2. Create a docker-compose.override.yml file with your settings. See Docker environment variables for full list of environment variables.

    version: '3'
    services:
      weblate:
        ports:
          - 80:8080
        environment:
          WEBLATE_EMAIL_HOST: smtp.example.com
          WEBLATE_EMAIL_HOST_USER: user
          WEBLATE_EMAIL_HOST_PASSWORD: pass
          WEBLATE_SERVER_EMAIL: [email protected]
          WEBLATE_DEFAULT_FROM_EMAIL: [email protected]
          WEBLATE_ALLOWED_HOSTS: weblate.example.com,localhost
          WEBLATE_ADMIN_PASSWORD: password for the admin user
          WEBLATE_ADMIN_EMAIL: [email protected]
    

    Note

    If WEBLATE_ADMIN_PASSWORD is not set, the admin user is created with a random password shown on first startup.

    Append ‘,localhost’ to WEBLATE_ALLOWED_HOSTS to be able to access locally for testing.

    You may also need to edit the docker-compose.yml file and change the default port from 80 if you already have a web server running on your local machine.

  3. Start Weblate containers:

    docker-compose up
    

Enjoy your Weblate deployment, it’s accessible on port 80 of the weblate container.

Changed in version 2.15-2: The setup has changed recently, priorly there was separate web server container, since 2.15-2 the web server is embedded in the Weblate container.

Changed in version 3.7.1-6: In July 2019 (starting with the 3.7.1-6 tag), the containers is not running as a root user. This has lead to changed exposed port from 80 to 8080.

Docker container with HTTPS support

Please see Installation for generic deployment instructions, this section only mentions differences compared to it.

Using own SSL certificates

New in version 3.8-3.

In case you have own SSL certificate you want to use, simply place the files into the Weblate data volume (see Docker container volumes):

  • ssl/fullchain.pem containing the certificate including any needed CA certificates
  • ssl/privkey.pem containing the private key

Additionally, Weblate container will now accept SSL connections on port 4443, you will want to include the port forwarding for HTTPS in docker compose override:

version: '3'
services:
  weblate:
    ports:
      - 80:8080
      - 443:4443

Automatic SSL certificates using Let’s Encrypt

In case you want to use Let’s Encrypt automatically generated SSL certificates on public installation, you need to add a reverse HTTPS proxy an additional Docker container, https-portal will be used for that. This is made use of in the docker-compose-https.yml file. Then create a docker-compose-https.override.yml file with your settings:

version: '3'
services:
  weblate:
    environment:
      WEBLATE_EMAIL_HOST: smtp.example.com
      WEBLATE_EMAIL_HOST_USER: user
      WEBLATE_EMAIL_HOST_PASSWORD: pass
      WEBLATE_ALLOWED_HOSTS: weblate.example.com
      WEBLATE_ADMIN_PASSWORD: password for admin user
  https-portal:
    environment:
      DOMAINS: 'weblate.example.com -> http://weblate:8080'

Whenever invoking docker-compose you need to pass both files to it, and then do:

docker-compose -f docker-compose-https.yml -f docker-compose-https.override.yml build
docker-compose -f docker-compose-https.yml -f docker-compose-https.override.yml up

Upgrading the Docker container

Usually it is good idea to only update the Weblate container and keep the PostgreSQL container at the version you have, as upgrading PostgreSQL is quite painful and in most cases does not bring many benefits.

You can do this by sticking with the existing docker-compose and just pull the latest images and then restart:

docker-compose stop
docker-compose pull
docker-compose up

The Weblate database should be automatically migrated on first startup, and there should be no need for additional manual actions.

Note

Upgrades across 3.0 are not supported by Weblate. If you are on 2.x series and want to upgrade to 3.x, first upgrade to the latest 3.0.1-x (at time of writing this it is the 3.0.1-7) image, which will do the migration and then continue upgrading to newer versions.

You might also want to update the docker-compose repository, though it’s not needed in most case. Please beware of PostgreSQL version changes in this case as it’s not straightforward to upgrade the database, see GitHub issue for more info.

Docker environment variables

Many of Weblate’s Configuration can be set in the Docker container using environment variables:

Generic settings

WEBLATE_DEBUG

Configures Django debug mode using DEBUG.

Example:

environment:
  WEBLATE_DEBUG: 1

See also

Disable debug mode.

WEBLATE_LOGLEVEL

Configures the logging verbosity.

WEBLATE_SITE_TITLE

Configures the site-title shown on the heading of all pages.

WEBLATE_ADMIN_NAME
WEBLATE_ADMIN_EMAIL

Configures the site-admin’s name and e-mail.

Example:

environment:
  WEBLATE_ADMIN_NAME: Weblate admin
  WEBLATE_ADMIN_EMAIL: [email protected]
WEBLATE_ADMIN_PASSWORD

Sets the password for the admin user. If not set, the admin user is created with a random password shown on first startup.

Changed in version 2.9: Since version 2.9, the admin user is adjusted on every container startup to match WEBLATE_ADMIN_PASSWORD, WEBLATE_ADMIN_NAME and WEBLATE_ADMIN_EMAIL.

WEBLATE_SERVER_EMAIL
WEBLATE_DEFAULT_FROM_EMAIL

Configures the address for outgoing e-mails.

WEBLATE_ALLOWED_HOSTS

Configures allowed HTTP hostnames using ALLOWED_HOSTS and sets sitename to the first one.

Example:

environment:
  WEBLATE_ALLOWED_HOSTS: weblate.example.com,example.com
WEBLATE_SECRET_KEY

Configures the secret used by Django for cookie signing.

Deprecated since version 2.9: The secret is now generated automatically on first startup, there is no need to set it manually.

WEBLATE_REGISTRATION_OPEN

Configures whether registrations are open by toggling REGISTRATION_OPEN.

Example:

environment:
  WEBLATE_REGISTRATION_OPEN: 0
WEBLATE_TIME_ZONE

Configures the used time zone in Weblate, see TIME_ZONE.

Note

To change the time zone of the Docker container itself, use the TZ environment variable.

Example:

environment:
  WEBLATE_TIME_ZONE: Europe/Prague
WEBLATE_ENABLE_HTTPS

Makes Weblate assume it is operated behind a reverse HTTPS proxy, it makes Weblate use HTTPS in e-mail and API links or set secure flags on cookies.

Note

This does not make the Weblate container accept HTTPS connections, you need to configure that as well, see Docker container with HTTPS support for examples.

Example:

environment:
  WEBLATE_ENABLE_HTTPS: 1
WEBLATE_IP_PROXY_HEADER

Lets Weblate fetch the IP address from any given HTTP header. Use this when using a reverse proxy in front of the Weblate container.

Enables IP_BEHIND_REVERSE_PROXY and sets IP_PROXY_HEADER.

Note

The format must conform to Django’s expectations. Django transforms raw HTTP header names as follows:

  • converts all characters to uppercase
  • replaces any hyphens with underscores
  • prepends HTTP_ prefix

So X-Forwarded-For would be mapped to HTTP_X_FORWARDED_FOR.

Example:

environment:
  WEBLATE_IP_PROXY_HEADER: HTTP_X_FORWARDED_FOR
WEBLATE_REQUIRE_LOGIN

Configures login required for the whole of the Weblate installation using LOGIN_REQUIRED_URLS.

Example:

environment:
  WEBLATE_REQUIRE_LOGIN: 1
WEBLATE_LOGIN_REQUIRED_URLS_EXCEPTIONS

Adds URL exceptions for login required for the whole Weblate installation using LOGIN_REQUIRED_URLS_EXCEPTIONS.

WEBLATE_GOOGLE_ANALYTICS_ID

Configures ID for Google Analytics by changing GOOGLE_ANALYTICS_ID.

WEBLATE_GITHUB_USERNAME

Configures GitHub username for GitHub pull-requests by changing GITHUB_USERNAME.

WEBLATE_GITLAB_USERNAME

Configures GitLab username for GitLab merge-requests by changing GITLAB_USERNAME

WEBLATE_SIMPLIFY_LANGUAGES

Configures the language simplification policy, see SIMPLIFY_LANGUAGES.

WEBLATE_AKISMET_API_KEY

Configures the Akismet API key, see AKISMET_API_KEY.

WEBLATE_GPG_IDENTITY

Configures GPG signing of commits, see WEBLATE_GPG_IDENTITY.

WEBLATE_URL_PREFIX

Configures URL prefix where Weblate is running, see URL_PREFIX.

Machine translation settings

WEBLATE_MT_DEEPL_KEY

Enables DeepL machine translation and sets MT_DEEPL_KEY

WEBLATE_MT_GOOGLE_KEY

Enables Google Translate and sets MT_GOOGLE_KEY

WEBLATE_MT_MICROSOFT_COGNITIVE_KEY

Enables Microsoft Cognitive Services Translator and sets MT_MICROSOFT_COGNITIVE_KEY

WEBLATE_MT_MYMEMORY_ENABLED
Enables MyMemory machine translation and sets MT_MYMEMORY_EMAIL to WEBLATE_ADMIN_EMAIL.

Example:

environment:
  WEBLATE_MT_MYMEMORY_ENABLED: 1
WEBLATE_MT_GLOSBE_ENABLED

Enables Glosbe machine translation.

environment:
  WEBLATE_MT_GLOSBE_ENABLED: 1
WEBLATE_MT_MICROSOFT_TERMINOLOGY_ENABLED

Enables Microsoft Terminology Service machine translation.

environment:
  WEBLATE_MT_MICROSOFT_TERMINOLOGY_ENABLED: 1
WEBLATE_MT_SAP_BASE_URL
WEBLATE_MT_SAP_SANDBOX_APIKEY
WEBLATE_MT_SAP_USERNAME
WEBLATE_MT_SAP_PASSWORD
WEBLATE_MT_SAP_USE_MT

Configures SAP Translation Hub machine translation.

environment:
    WEBLATE_MT_SAP_BASE_URL: "https://example.hana.ondemand.com/translationhub/api/v1/"
    WEBLATE_MT_SAP_USERNAME: "user"
    WEBLATE_MT_SAP_PASSWORD: "password"
    WEBLATE_MT_SAP_USE_MT: 1

Authentication settings

LDAP

WEBLATE_AUTH_LDAP_SERVER_URI
WEBLATE_AUTH_LDAP_USER_DN_TEMPLATE
WEBLATE_AUTH_LDAP_USER_ATTR_MAP
WEBLATE_AUTH_LDAP_BIND_DN
WEBLATE_AUTH_LDAP_BIND_PASSWORD

LDAP authentication configuration.

Example:

environment:
  WEBLATE_AUTH_LDAP_SERVER_URI: ldap://ldap.example.org
  WEBLATE_AUTH_LDAP_USER_DN_TEMPLATE: uid=%(user)s,ou=People,dc=example,dc=net
  # map weblate 'full_name' to ldap 'name' and weblate 'email' attribute to 'mail' ldap attribute.
  # another example that can be used with OpenLDAP: 'full_name:cn,email:mail'
  WEBLATE_AUTH_LDAP_USER_ATTR_MAP: full_name:name,email:mail

GitHub

WEBLATE_SOCIAL_AUTH_GITHUB_KEY
WEBLATE_SOCIAL_AUTH_GITHUB_SECRET

Enables GitHub authentication.

BitBucket

WEBLATE_SOCIAL_AUTH_BITBUCKET_KEY
WEBLATE_SOCIAL_AUTH_BITBUCKET_SECRET

Enables Bitbucket authentication.

Facebook

WEBLATE_SOCIAL_AUTH_FACEBOOK_KEY
WEBLATE_SOCIAL_AUTH_FACEBOOK_SECRET

Enables Facebook OAuth 2.

Google

WEBLATE_SOCIAL_AUTH_GOOGLE_OAUTH2_KEY
WEBLATE_SOCIAL_AUTH_GOOGLE_OAUTH2_SECRET

Enables Google OAuth 2.

GitLab

WEBLATE_SOCIAL_AUTH_GITLAB_KEY
WEBLATE_SOCIAL_AUTH_GITLAB_SECRET
WEBLATE_SOCIAL_AUTH_GITLAB_API_URL

Enables GitLab OAuth 2.

Azure Active Directory

WEBLATE_SOCIAL_AUTH_AZUREAD_OAUTH2_KEY
WEBLATE_SOCIAL_AUTH_AZUREAD_OAUTH2_SECRET

Enables Azure Active Directory authentication, see Microsoft Azure Active Directory.

Azure Active Directory with Tenant support

WEBLATE_SOCIAL_AUTH_AZUREAD_TENANT_OAUTH2_KEY
WEBLATE_SOCIAL_AUTH_AZUREAD_TENANT_OAUTH2_SECRET
WEBLATE_SOCIAL_AUTH_AZUREAD_TENANT_OAUTH2_TENANT_ID

Enables Azure Active Directory authentication with Tenant support, see Microsoft Azure Active Directory.

Linux vendors

You can enable authentication using Linux vendors authentication services by setting following variables to any value.

WEBLATE_SOCIAL_AUTH_FEDORA
WEBLATE_SOCIAL_AUTH_OPENSUSE
WEBLATE_SOCIAL_AUTH_UBUNTU

Other authentication settings

WEBLATE_NO_EMAIL_AUTH

Disables e-mail authentication when set to any value.

PostgreSQL database setup

The database is created by docker-compose.yml, so these settings affect both Weblate and PostgreSQL containers.

POSTGRES_PASSWORD

PostgreSQL password.

POSTGRES_USER

PostgreSQL username.

POSTGRES_DATABASE

PostgreSQL database name.

POSTGRES_HOST

PostgreSQL server hostname or IP address. Defaults to database.

POSTGRES_PORT

PostgreSQL server port. Defaults to none (uses the default value).

POSTGRES_SSL_MODE

Configure how PostgreSQL handles SSL in connection to the server, for possible choices see SSL Mode Descriptions

Caching server setup

Using Redis is strongly recommended by Weblate and you have to provide a Redis instance when running Weblate in Docker.

See also

Enable caching

REDIS_HOST

The Redis server hostname or IP address. Defaults to cache.

REDIS_PORT

The Redis server port. Defaults to 6379.

REDIS_DB

The Redis database number, defaults to 1.

REDIS_PASSWORD

The Redis server password, not used by default.

REDIS_TLS

Enables using SSL for Redis connection.

REDIS_VERIFY_SSL

Can be used to disable SSL certificate verification for Redis connection.

Email server setup

To make outgoing e-mail work, you need to provide a mail server.

WEBLATE_EMAIL_HOST

Mail server, the server has to listen on port 587 and understand TLS.

See also

EMAIL_HOST

WEBLATE_EMAIL_PORT

Mail server port. Use if your cloud provider or ISP blocks outgoing connections on port 587.

See also

EMAIL_PORT

WEBLATE_EMAIL_HOST_USER

Email authentication user, do NOT use quotes here.

See also

EMAIL_HOST_USER

WEBLATE_EMAIL_HOST_PASSWORD

Email authentication password, do NOT use quotes here.

WEBLATE_EMAIL_USE_SSL

Whether to use an implicit TLS (secure) connection when talking to the SMTP server. In most e-mail documentation, this type of TLS connection is referred to as SSL. It is generally used on port 465. If you are experiencing problems, see the explicit TLS setting WEBLATE_EMAIL_USE_TLS.

See also

EMAIL_USE_SSL

WEBLATE_EMAIL_USE_TLS

Whether to use a TLS (secure) connection when talking to the SMTP server. This is used for explicit TLS connections, generally on port 587. If you are experiencing connections that hang, see the implicit TLS setting WEBLATE_EMAIL_USE_SSL.

See also

EMAIL_USE_TLS

Error reporting

It is recommended to collect errors from the installation systematically, see Collecting error reports.

To enable support for Rollbar, set the following:

ROLLBAR_KEY

Your Rollbar post server access token.

ROLLBAR_ENVIRONMENT

Your Rollbar environment, defaults to production.

To enable support for Sentry, set following:

SENTRY_DSN

Your Sentry DSN.

Changing enabled apps, checks, addons or autofixes

New in version 3.8-5.

The built in configuration of enabled checks, addons or autofixes can be adjusted by following variables:

WEBLATE_ADD_APPS
WEBLATE_REMOVE_APPS
WEBLATE_ADD_CHECK
WEBLATE_REMOVE_CHECK
WEBLATE_ADD_AUTOFIX
WEBLATE_REMOVE_AUTOFIX
WEBLATE_ADD_ADDONS
WEBLATE_REMOVE_ADDONS

For example:

Example:

environment:
  WEBLATE_REMOVE_AUTOFIX: weblate.trans.autofixes.whitespace.SameBookendingWhitespace
  WEBLATE_ADD_ADDONS: customize.addons.MyAddon,customize.addons.OtherAddon

Docker container volumes

There is single data volume exported by the Weblate container. The other service containers (PostgreSQL or Redis) have their data volumes as well, but those are not covered by this document.

The data volume is used to store Weblate persistent data such as cloned repositories or to customize Weblate installation.

The placement of the Docker volume on host system depends on your Docker configuration, but usually it is stored in /var/lib/docker/volumes/weblate-docker_weblate-data/_data/. In the container it is mounted as /app/data.

Further configuration customization

You can further customize Weblate installation in the data volume, see Docker container volumes.

Custom configuration files

You can additionally override the configuration in /app/data/settings-override.py (see Docker container volumes). This is executed after all environment settings are loaded, so it gets completely set up, and can be used to customize anything.

Replacing logo and other static files

New in version 3.8-5.

The static files coming with Weblate can be overridden by placing into /app/data/python/customize/static (see Docker container volumes). For example creating /app/data/python/customize/static/favicon.ico will replace the favicon.

Hint

The files are copied to correspoding location on container startup, so restart is needed after changing the volume content.

Alternatively you can also include own module (see Customizing Weblate) and add it as separate volume to the Docker container, for example:

weblate:
  volumes:
    - weblate-data:/app/data
    - ./weblate_customization/weblate_customization:/app/data/python/weblate_customization
  environment:
    WEBLATE_ADD_APPS: weblate_customization

Adding own Python modules

New in version 3.8-5.

You can place own Python modules in /app/data/python/ (see Docker container volumes) and they can be then loaded by Weblate, most likely by using Custom configuration files.

Hub setup

In order to use the GitHub’s pull-request feature, you must initialize hub configuration by entering the Weblate container and executing an arbitrary Hub command. For example:

docker-compose exec --user weblate weblate bash
cd
HOME=/app/data/home hub clone octocat/Spoon-Knife

The username passed for credentials must be the same as GITHUB_USERNAME.

Lab setup

In order to use GitLab’s merge-request feature, you must initialize lab configuration by entering the weblate contained and executing lab command. For example:

docker-compose exec --user weblate weblate bash
cd
HOME=/app/data/home lab

The access_token passed for lab configuratoin must be same as GITLAB_USERNAME.

Select your machine - local or cloud providers

With docker-machine you can create your Weblate deployment either on your local machine, or on any large number of cloud-based deployments on e.g. Amazon AWS, Greenhost, and many other providers.