dicodock

The preferred way to install the needed dictionaries is using the DICOD_INITDB variable. If, however, you prefer to install them manually, follow the instructions below:

• Freedict dictionaries

  These are free dictionaries available for download from https://download.freedict.org/dictionaries. Each dictionary is a tar archive named freedict-L1-L2-V.dictd.tar.xz, where L1 and L2 are language abbreviations and V is its version number.

  Download the needed dictionaries and untar them to the subdirectory freedict under DICOD_DB_VOL directory. For example, supposing that you use the default DICOD_DB_VOL directory and need to install Breton-French dictionary:

  mkdir dicod_db/freedict
  wget https://download.freedict.org/dictionaries/bre-fra/0.8.3/freedict-bre-fra-0.8.3.dictd.tar.xz
  tar -C dicod_db/freedict -xf freedict-bre-fra-0.8.3.dictd.tar.xz
  

• GCIDE

  The GNU Collaborative International Dictionary of English is available for download from https://ftp.gnu.org/gnu/gcide. Dicod will look for it in the subdirectory gcide of the database directory. So, to install it, do

  mkdir dicod_db/gcide
  wget https://ftp.gnu.org/gnu/gcide/gcide-0.53.tar.xz
  tar -C dicod_db/gcide --strip -xf gcide-0.53.tar.xz
  

• WordNet

  WordNet is a large lexical database of English, available from https://wordnet.princeton.edu/. Dicod will look for the WordNet dictionary database in the subdirectory wordnet of the database directory. You will need only database files, not the entire package. Download them from https://wordnet.princeton.edu/download/current-version and extract to the directory wordnet, e.g.:

  mkdir dicod_db/wordnet
  wget https://wordnetcode.princeton.edu/wn3.1.dict.tar.gz
  tar -C dicod_db/wordnet --strip -xf wn3.1.dict.tar.gz
  

If you plan to use another databases, write a configuration file that loads the necessary modules and declares your databases and place it in the custom configuration directory, indicated by the DICOD_INCLUDE_VOL variable. Make sure the file name ends with .conf.

The file .env in docker directory contains settings that affect basic functionality. These are:

• ANSI

  When set, the value of this variable is passed to docker compose with the --ansi option. In addition, if set to never the DOCKER_BUILDKIT environment variable is set to 0. Use this when debugging your configuration.

• DICOD_INITDB

  A list of dictionary databases to download and install at startup. This variable is consulted only if no dictionaries are installed in the database directory. Its value is a whitespace-delimited list of dictionary classes or the word all standing for all available dictionaries. For the list of valid dictionary classes, see the Dictionaries section, above.

• DICOWEB_HOST

  Canonical hostname of the dicoweb server. This variable must be defined.

• DICOWEB_PORT

  Port on which dicoweb HTTP server will be available on host machine. Defaults to 127.0.0.1:8080.

• DICOWEB_DEBUG

  Set this variable to any non-empty value to enable debugging of the dicoweb application. Don't use it on production servers.

• DICOWEB_ADMIN

  Email address of the the server administrator. Allowed formats:

  Ty Coon <coon@example.org>
  coon@example.org
  

  Default is: root@localhost. You are advised to always define this variable to an existing email address.

• DICOWEB_SECRET_KEY

  Secret key for the dicoweb application. Default: automatically generated.

• DICT_SERVER

  Name (and optionally, port number) of the dict server to use. This variable is used by the default settings_docker.py configuration file. It defaults to the internal hostname of the service running dicod. Use this variable if: (1) you use the default settings_docker.py (or a customized version thereof, which retains the default DICT_SERVERS setting), and (2) you want to use external dictionary server.

• DICOD_INCLUDE_VOL

  Name of the host directory or docker volume to mount to /etc/dicod/include directory in the dicod container. This directory is scanned for dico custom configuration files (dictionary database definitions and the like).

  Default is ./dicod_include.

• DICOD_DB_VOL

  Name of the host directory or docker volume to mount to /var/dicodb directory in the dicod container. This directory is supposed to keep dictionary databases.

  Default is ./dicod_db.

The file docker/docker-compose.override.yml extends the default docker-compose.yml and provides thus a mechanism for tuning all aspects of the system, including mounting host directories to containers.

Assume volume name dicod_db

Create a docker-compose.override.yml file with the following content:

volumes:
  dicod_db:

Add this definition to your .env file:

DICOD_DB_VOL=dicod_db

To keep dicod include directory in a volume, follow the steps above, but use the DICOD_INCLUDE_VOL variable instead.

Let's assume you want dicod to be accessible on the standard port 2628. To do so, create the file docker-compose.override.yml with the following content:

services:
  dicod:
    ports:
      - 2628:2628

By default all diagnostic goes to container logs, which obviously is not well suited for production environment. To direct it to syslog instead, define the environment variable PIES_SYSLOG_SERVER to the IP address and UDP port number of your syslog server, e.g. in your .env file:

PIES_SYSLOG_SERVER=172.31.255.252:514

Notice, that the use of port number is suggested because (at least at the time of this writing) the GNU pies container lacks /etc/services file, which pies uses to deduce port numbers.

The above will make all daemons in the containers (dicod, uwsgy, lighttpd, etc.) send their diagnostics to this syslog server over UDP.

To additionally direct all service logging output to syslog, use the following technique. Create the docker-compose.override.yml file with the following:

x-dicoweb-logging:
  &dicoweb-logging
  driver: "syslog"
  options:
    syslog-address: udp://$PIES_SYSLOG_SERVER
    syslog-facility: local0
    tag: '{{if (index .ContainerLabels "com.docker.compose.project")}}{{index .ContainerLabels "com.docker.compose.project"}}/{{end}}{{if (index .ContainerLabels "com.docker.compose.service")}}{{index .ContainerLabels "com.docker.compose.service"}}/{{end}}{{.Name}}/{{.ID}}'

services:
  dicoweb:
    logging: *dicoweb-logging

Add logging: *dicoweb-logging stanza to each service definition in the services: section. This will make sure that everything that goes to standard output or standard error in each container will be sent to syslog with the tag composed of project name, service name, and container ID, delimited by slashes. If you run rsyslog, you can use that tag to route messages to the right place.

Please note, that at the time of this writing the nginx and memcached services do not support syslog logging directly, and the above technique should be used to log their diagnostics to syslog.

If your host runs an HTTP server (as opposed to proxy), you might wish it to handle incoming dicoweb requests and get rid of the HTTP service. To implement such setup, your HTTP server should serve static files itself and forward the rest of requests to the dicoweb container.

Dicoweb static assets reside in docker volumes dicoweb_static and dicoweb_run. To make sure your server is able to access them, you need to mount these volumes to suitable places in your file system hierarchy (since the default permissions of /var/lib/docker/volumes, where they are mounted by default, don't allow access to them). You will need local-persist docker storage plugin to do so.

First, create two directories for mapping to dicoweb_static and dicoweb_run volumes. Let's assume they are /mnt/dicoweb_static and /mnt/dicoweb_run:

mkdir /mnt/dicoweb_static /mnt/dicoweb_run

Then, create the file docker-compose.override.yml with the following content:

services:
  dicoweb:
    ports:
      - "127.0.0.1:${DICOWEB_PORT:-8080}:80"
volumes:
  dicoweb_static:
    driver: local-persist
    driver_opts:
  mountpoint: "/mnt/dicoweb_static"
  dicoweb_run:
    driver: local-persist
    driver_opts:
  mountpoint: "/mnt/dicoweb_run"

If using GNU Make, ensure that your .env file does not define PROFILE variable and start up the system. Otherwise, if using docker compose directly, start up the system as follows:

docker compose up -d

If you run Apache web server, modify your virtual host configuration as follows:

<VirtualHost *:80>
    ServerName    dicoweb.example.com
    ProxyPreserveHost On

    <Location />
	ProxyPass       http://127.0.0.1:8080/
    </Location>

    <Location /static>
	ProxyPass !
    </Location>
    Alias /static /home/gray/src/dico/dictdbtest/vol/static

    <Location /favicon.ico>
	ProxyPass !
    </Location>
    <Location /robots.txt>
	ProxyPass !
    </Location>
    Alias /favicon.ico /mnt/dicoweb_static/images/gnu-head-mini.png
    Alias /robots.txt /mnt/dicoweb_run/static/robots.txt

    <Directory /mnt/dicoweb_static>
	AllowOverride All
	Options None
	Require all granted
    </Directory>
    <Directory /mnt/dicoweb_run>
	AllowOverride All
	Options None
	Require all granted
    </Directory>
</VirtualHost>

To use an external dict server you need to supply its address to dicoweb and exclude the dicod container from the startup sequence.

The first part is achieved by setting the variable DICT_SERVER in your .env file, e.g.:

DICT_SERVER=dico.gnu.org.ua

The second part is achieved by modifying the dicod service in your docker-compose.override.yml as shown below:

services:
  dicod:
    profiles:
      - disabled

The actual profile name doesn't matter. What's important is that you are never going to use it in the --profile option when running docker compose.