Deploy ELG services locally

ELG-compatible services are Docker images running in the ELG infrastructure (See here for precision). The services do not communicate with the outside world directly but with the LT Service Execution Server which exposes the Public LT API specification. To deploy the ELG services locally, it is, therefore, necessary to deploy the Docker images of the services but also to deploy the LT Service Execution Server (also called REST server for simplicity).

⚠️ Not all the ELG services can be deployed locally. Please check the licences of the services before deploying them locally.

The deployment of the LT services and the REST server locally can be done using different tools. We choose Docker Compose for its simplicity but we may propose different deployment options such as Helm charts in the future.

The Python SDK helps you generate all the configuration files necessary to deploy ELG services locally. It covers most of the use cases (only the services using local storage are not compatible). Once the files are created, you will only need to run docker-compose up to run all the services.

The Python SDK covers different local installation setups. It is possible to deploy locally ELG-compatible services deployed in the live grid or ELG-compatible services not already deployed in the live grid using only the Docker image and the execution location. Also, you can deploy the Graphical User Interface (GUI) to interact with the services deployed locally directly from your browser.

⚠️ All the services deployed into the ELG are compatible with AMD64 CPUs but might not work with other CPUs like the new Apple M1 chip. This is the case for the OPUS-MT services for example.

Deploy ELG services from the grid locally with the GUI

This is probably the most common use-case: you want to deploy locally one or multiple ELG services that you found in the catalogue. You also want to have the same “Try out” widget that is available in the ELG but locally.

To do that, you will simply need to run:

elg local-installation ids 9192

This will generate the docker-compose.yml file and the configuration files to deploy the service with the id 9192 with the REST server and the GUI. After running docker-compose up from the correct folder, you can visit http://localhost:8080 and you should see the GUI:

Local installation of one ELG service

You can test the service as you would do in the live grid but both the service and the REST server are deployed locally.

It is also possible to call the service using the LT Public API exposed by the REST server locally. Using cURL:

curl -H "Content-Type: text/plain" --data "This is a test" http://localhost:8080/execution/process/opus-mt-eng-nld

Or using the Python SDK directly (don’t forget to set local to True):

from elg import Service

lt = Service.from_id(9192, local=True)
response = lt("This is a test")

In this first example, we deployed one service but it is possible to deploy multiple services from the grid (if their licences are compliant) using the same steps.

For example, we can deploy the English tweet sentiment analysis service in addition to the HelsinkiNLP - OPUS-MT (eng-gmw): English-Dutch machine translation service as before:

elg local-installation ids 9192 9269

The GUI for the two services are again accessible at http://localhost:8080:

Local installation of two ELG services

And you can use the LT Public API exposed by the REST server locally as before.

By default, the GUI used for the service is the /dev/gui-ie GUI. This GUI works for MT services, IE tools, ASRs tools, etc… but not for all the tools, e.g., dependency parsers and TTS services. If the service you want to deploy locally is using a different GUI, you can specify it when you generate the configuration files. For example, we can add a third service to our local installation which is a dependency parser using a different GUI:

elg local-installation ids 9192 9269 9496 \
  --gui_images \
    registry.gitlab.com/european-language-grid/usfd/gui-ie:latest \
    registry.gitlab.com/european-language-grid/usfd/gui-ie:latest \
    registry.gitlab.com/european-language-grid/cuni/gui-udpipe:latest

The GUI Docker images need to be in the same order as the service ids.

On http://localhost:8080/, we can see that the last service is using a different GUI:

Local installation of three ELG services

Deploy ELG services from the grid locally without the GUI

If you do not need the GUI, you can also generate the configuration files to deploy ELG services locally without the GUI. You only need to add the --no_gui parameter to the elg local-installation ids command.

For example, if we reuse the first example with only one service, it would be:

elg local-installation ids 9192 --no_gui

It is then possible to call the service using cURL or using the Python SDK as before:

Using cURL:

curl -H "Content-Type: text/plain" --data "This is a test" http://localhost:8080/execution/process/opus-mt-eng-nld

Or using the Python SDK directly:

from elg import Service

lt = Service.from_id(9192, local=True)
response = lt("This is a test")

Deploy ELG-compatible service from its Docker image

It is also possible to deploy any ELG-compatible service from its Docker image. It is useful to test an ELG-compatible service that is not deployed into the live grid yet for example.

When creating the docker-compose.yml file and the configuration files, you need to precise the link to the Docker image and also the execution location of the service inside the Docker image:

elg local-installation docker \
  --image docker.io/helsinkinlp/tatoeba-mt:eng-gmw_opus1m_bt-2021-04-10 \
  --execution_location http://localhost:8888/elg/translate/eng/nld \
  --name mt-service

The name parameter can then be used to call the service.

Using cURL:

curl -H "Content-Type: text/plain" --data "This is a test" http://localhost:8080/execution/process/mt-service

Or using the Python SDK directly:

from elg import Service

lt = Service.from_local_installation("mt-service")
response = lt("This is a test")

It is also possible to deploy a GUI in this configuration. However, as the GUI path cannot be found in the metadata of the service, you will need to specify it:

elg local-installation docker \
  --image docker.io/helsinkinlp/tatoeba-mt:eng-gmw_opus1m_bt-2021-04-10 \
  --execution_location http://localhost:8888/elg/translate/eng/nld \
  --name mt-service \
  --gui \
  --gui_path "index-mt.html?srcdir=ltr&targetdir=ltr"

The GUI is also accessible on http://localhost:8080:

Local installation of one ELG-compatible service from a Docker image

And the service can still be called using the API.

Using cURL:

curl -H "Content-Type: text/plain" --data "This is a test" http://localhost:8080/execution/process/mt-service

Or using the Python SDK directly (don’t forget to set local to True):

from elg import Service

lt = Service.from_local_installation("mt-service")
response = lt("This is a test")

Advanced use cases

Even if most of the use cases should be covered by the examples given so far, the two commands (elg local-installation ids and elg local-installation docker) have more parameters to handle specific use cases you might have. To see all the parameters run:

> elg local-installation ids --help
usage: elg <command> [<args>] local-installation ids [-h] [--folder FOLDER] [--no_gui] [--domain DOMAIN] [--not_use_cache] [--cache_dir CACHE_DIR] [--expose_port EXPOSE_PORT] [--gui_images GUI_IMAGES [GUI_IMAGES ...]] [--gui_ports GUI_PORTS [GUI_PORTS ...]] ids [ids ...]

Create a Docker compose file to deploy a set of ELG services locally from their ids

positional arguments:
  ids                   ID of the service to deploy locally.

optional arguments:
  -h, --help            show this help message and exit
  --folder FOLDER       path to the folder where to save the Docker compose file
  --no_gui              use to not use the GUI
  --domain DOMAIN       ELG domain you want to use
  --not_use_cache       use to not use cache
  --cache_dir CACHE_DIR
                        path to the cache directory
  --expose_port EXPOSE_PORT
                        port used to publish to the host
  --gui_images GUI_IMAGES [GUI_IMAGES ...]
                        docker image of the GUI
  --gui_ports GUI_PORTS [GUI_PORTS ...]
                        port used by the GUI docker image

> elg local-installation docker --help
usage: elg <command> [<args>] local-installation docker [-h] --image IMAGE --execution_location EXECUTION_LOCATION [--sidecar_image SIDECAR_IMAGE] [--name NAME] [--full_name FULL_NAME] [--folder FOLDER] [--gui] [--expose_port EXPOSE_PORT] [--gui_image GUI_IMAGE] [--gui_path GUI_PATH]
                                                        [--gui_port GUI_PORT]

Create a Docker compose file to deploy an ELG compatible Docker image locally

optional arguments:
  -h, --help            show this help message and exit
  --image IMAGE         name of the Docker image
  --execution_location EXECUTION_LOCATION
                        endpoint of the Docker image where the service can be executed
  --sidecar_image SIDECAR_IMAGE
                        name of the sidecare Docker image
  --name NAME           name of the service to use for the REST server
  --full_name FULL_NAME
                        name of the service to display in the GUI
  --folder FOLDER       path to the folder where to save the Docker compose file
  --gui                 use to use the GUI
  --expose_port EXPOSE_PORT
                        port used to publish to the host
  --gui_image GUI_IMAGE
                        docker image of the GUI
  --gui_path GUI_PATH   path to the GUI
  --gui_port GUI_PORT   port used by the GUI docker image

For even more specific use cases, you can directly use the LocalInstallation class from elg.local_installation to create highly customized local installations. See the API definition to have more information.