Maintaining and improving PanLem

IntroductionUp

PanLem is written in Perl. It was implemented as a CGI script until 02016. In 02016 we converted it to a stand-alone HTTP server.

Localization

Improving PanLem’s localization is something that you can do even if you are not a programmer. If you are dissatisfied with PanLem’s localization in any language variety, you can improve the translations available to PanLem in that language variety, and your added translations will become available to PanLem the next day.

To do this, you can get 2 lists (with the “translation—every—see” command in PanLem):

  • A list of translations from PanLem into the desired language variety.
  • A list of translations from PanLem into a better-documented language variety (such as English).

If you add translations from the latter language variety into the former one, you will make them available to PanLem. For example, PanLem’s expression “pub” is translated into English as “publisher”. If there’s no distance-1 translation of it into the language variety you are working on, you can translate “publisher” from English into that language variety, and this will make your translation available to PanLem. Adding translations to the database is part of assimilation, which you can do with or without programming.

Code

The PanLem code is maintained in a repository at GitLab.

PanLem is defined as a “project” at GitLab. We have set its visibility level to “private”. We have also defined a PanLex “group” at GitLab, and we have shared the PanLem project with the PanLex group. As a result, members of the PanLex group have access to the PanLem project’s code, but the code is invisible to other GitLab users and the general public.

When PanLem is deployed on the PanLex server or any other host, it runs on code that has been checked out from a local copy of that repository on that host.

Deployment

Most of the deployment documentation for PanLem is maintained in the repository along with the code. It is in the README.md file, and GitLab displays it when you first visit the project.

Some facts about deployment that are not in the README.md file are documented below.

Server

PanLem is deployed on the PanLex server for production, as described in the repository documentation. The code is located in the directory /opt/data/panlem/40/. Paths to directories and files in the documentation are relative to that directory.

Local

To develop PanLem, you must also deploy PanLem locally (on your own computer). This permits you to make and test changes in the code without interfering with PanLem running on the server.

You can install PanLem locally in any directory that you have permission to read, write, and execute in. Installation creates a directory named panlem inside that directory.  That panlem directory is the one called the “PanLem directory” in the documentation, and paths to directories and files in the documentation are relative to that directory.

PanLem has some features that interact with Wrike, our task-management system. If you intend to include these features in your installation, select (or create) a directory into which to install required software. You can select any directory that you have permission to read, write, and execute in. Installation creates a directory named wrike inside that directory. That wrike directory is the one called the “Wrike directory” or the “PanLexBot directory” in the documentation.

Prerequisites

Before deploying PanLem locally, you need to perform the following additional installations and configurations, if you have not done so already. Some of these are identical to prerequisites for assimilation, and, in those cases, we refer you to that documentation for details.

  1. Install Perl.
  2. Install git.
  3. Execute the command git config --global pull.rebase true. This simplifies the logging of your modifications to the PanLem files in the repository.
  4. Create a .pgpass file in your local home directory, if it does not exist already. Insert a line with * for the database, hostname, and port, and the approriate username and password of the PostgreSQL user that PanLem will connect as. For full access to the database, the username should be apache. To get the password, ask the PanLex staff. (If you are already a user on the server, you can instead obtain apache’s password from the /opt/data/pgpass file.)
  5. Ask the PanLex staff to invite you to become a member of the PanLex group on GitLab. If you need only to install and run PanLem, the staff will make you a “Reporter” in the group. If you also need to make changes to the code and copy those changes into the repository, the staff will make you a “Developer” in the group.
  6. Create a GitLab account.
  7. Register your SSH public key (typically ~/.ssh/id_rsa.pub) on GitLab, so that you can authenticate with git. Do this by navigating to the “Profile Settings” panel and then to the “SSH Keys” menu.

Installation and configuration

To obtain PanLem, change your current working directory to the one where you want the PanLem directory to be created. Then get PanLem from its GitLab repository with the command:

git clone git@gitlab.com:panlex/panlem.git

This installs all of PanLem except any relatively referenced images. Such images’ alternate texts appear in your local PanLem interface.

Next, follow the deployment instructions for the development environment in the PanLem README.md file. This requires you, among other things, to set environment variables.

If you intend to develop and test PanLem’s Wrike features, change your current working directory to one where you want the Wrike directory to be created. Then get the Wrike code from its GitLab repository with the command:

git clone git@gitlab.com:panlex/wrike.git

Then follow the deployment instructions for the development environment in the Wrike README.md file.

Updates

To ensure that your local copy of PanLem (in git terms, your working tree) contains the latest version of PanLem, update it by making panlem your working directory and executing git pull. After you do so, you may find that you can no longer execute PanLem because of a missing required Perl module. This is due to an additional module having become required. To correct that, you can re-execute the statement in the README.md file that installs the required Perl modules.

After making changes in your working tree, testing them locally, and deciding that they are ready to be incorporated into the public version of PanLem, you can verify what you have changed with git status. You may see a list of changed files and also a list of added files not yet being tracked by git and deleted files still tracked by git. Amend that list with git add and git rm as necessary. Then commit your changes to your local repository with git commit -a. Finally, merge your saved changes into the remote (GitLab) repository with git push.

Changes you push to the GitLab repository are not incorporated into the production version of PanLem until you (or, if you cannot, someone with an account on the server) pulls those changes into the server’s repository and working tree with git pull and restarts PanLem with sudo supervisorctl restart panlem panlem_worker.