Docker for PKP

A docker image generator for PKP tools (aka. OJS, OMP, OPS).

This project is a refactoring of previous projects, following the work plan outlined in "pkpContainers: A Proposal for Unification".

You can use this project to RUN and learn about the official images, or to BUILD your own.

Features of the images:

• Able to generate images for different PKP tools.
• Multi-stage approach.
• Alpine-based Apache/PHP 8.5 runtime for the current local build.
• Building from tarball.
• Updated list of php modules and OS libraries.
• Multiple helper scripts.
• PHP extensions installed from the Alpine package repositories.
• Rootless ready.
• MariaDB/MySQL/PostgreSQL support.
• Monitor security using Docker Scout (or Snyk or Trivy).

Security findings that cannot be fixed without an OJS upgrade, and the audit requirements for persistent plugin volumes, are documented in Documentation.

Howto

You can RUN the official images we publish and maintain on DockerHub, or BUILD your own.
The process is driven by the variables in your .env file, so it is important to adjust them according to your needs.
Your docker compose up -d will perform different actions (RUN or BUILD) depending on the value of IMAGE_SOURCE.

Managing multiple local OJS projects

The Dockerfile and runtime are shared between projects such as TupJ and TuLJ. Project-specific settings should be kept in separate, ignored environment files rather than in the image or in the repository:

.env.example       # safe template; commit this
.env.tupj.local    # TupJ values; do not commit
.env.tulj.local    # TuLJ values; do not commit

Create a project file from the template:

cp .env.example .env.tupj.local
cp .env.example .env.tulj.local

At minimum, set these values separately for each project:

DB_NAME
DB_PASS
DB_DUMP_FILE
OJS_CONFIG_FILE
COMPOSE_PROJECT_NAME
PROJECT_DOMAIN
SERVERNAME

The shared values normally include PKP_TOOL, PKP_VERSION, WEB_SERVER, BUILD_PKP_APP_OS, and WEB_PATH. Database passwords, OJS configuration files, and SQL dumps are intentionally excluded from Git. The current Compose file uses DB_DUMP_FILE to select the project-specific initialization dump and OJS_CONFIG_FILE to select the project-specific OJS configuration.

For example, the project environment files can point to different local configurations:

# .env.tupj.local
OJS_CONFIG_FILE="./volumes/config/tupj.config.inc.php"

# .env.tulj.local
OJS_CONFIG_FILE="./volumes/config/tulj.config.inc.php"

The selected file must exist before starting Compose. It is mounted into the container at /var/www/html/ojs/config.inc.php. If OJS_CONFIG_FILE is omitted, Compose keeps the existing default path ./volumes/config/pkp.config.inc.php.

Use the selected environment file for every Compose operation through the Makefile:

make ENV_FILE=.env.tupj.local up
make ENV_FILE=.env.tulj.local up

If you invoke Compose directly, provide ENV_FILE as well as --env-file because the selected file is also injected into the containers:

ENV_FILE=.env.tupj.local docker compose --env-file .env.tupj.local up -d

The included Makefile provides the same workflow with shorter commands:

make ENV_FILE=.env.tupj.local build
make ENV_FILE=.env.tupj.local up
make ENV_FILE=.env.tupj.local scheduled
make ENV_FILE=.env.tupj.local jobs
make ENV_FILE=.env.tupj.local logs

The Makefile does not parse or include the environment file itself; Docker Compose loads it. This avoids making passwords part of Make's variable-processing layer.

To RUN images from dockerHub:

git clone https://github.com/tulibraries/ojs-containers.git journalName
vim .env                         					# Set the IMAGE_SOURCE=docker-io [modify the rest of variables as desired]
source .env && wget "https://github.com/pkp/${PKP_TOOL}/raw/${PKP_VERSION}/config.TEMPLATE.inc.php" -O ./volumes/config/pkp.config.inc.php
sudo chown 33:33 ./volumes -R && sudo chown 999:999 ./volumes/db -R	    # Ensure folders got the proper permissions
docker compose up -d

Now, you only need to open your browser to visit your new site and finish the installation with the variables you defined. Check your .env file to know the SERVERNAME, the HTTP_PORT, the DB parameters...

You can find more detailed instructions on how to RUN the official images in this document.

To BUILD your own image:

git clone https://github.com/tulibraries/ojs-containers.git
vim .env                         					# Set the IMAGE_SOURCE=local [modify the rest of variables as desired]
# Run your own image:
docker compose up -d

And again, you will need to reach your https://SERVERNAME:$HTTPS_PORT and finish your installation.

Alternatively, instead of editing your .env variables, you can override them in the build call as follows:

docker compose build --build-arg IMAGE_SOURCE=local --build-arg BUILD_PKP_TOOL=omp --build-arg BUILD_LABEL=$(date "+%Y%m%d-%H%M%S") --no-cache

Take in consideration that docker won't read your .env variables, so you should use docker compose instead.

Tag Naming Conventions

The general syntax for referencing a PKP image is as follows:

docker.io/pkpofficial/[pkpTool]:[TAG]
  │            │          │       │
  │            │          │       └─ Tag: Specific image (ie: 3_3_0-17-php82-mod-050829.0235)
  │            │          └─ Image: ojs, omp, ops.
  │            └─ Repository: pkpofficial
  └─ Registry host: local, docker.io, ...

All current images are relased with at least two tags:

• Explicit: A unique tag including the tool version, PHP version/handler, and the last 4 digits of the image buildingDate (e.g., pkpofficial/ojs:3_3_0-17-php82-mod-050829.0235).
• Implicit: A short alias named as the PKP release tag (e.g., pkpofficial/ojs:3_3_0-17), always pointing to the latest build of that version.

Additional aliases are also provided: latest (most recent release), lts (long-term support version), and stable (stable branch releases).

This table summarizes all available tags:

Type	Description	Example
Current	For every release, with both an implicit (compact PKP name) and an explicit tag (unique name)	explicit: 3_3_0-17-php82-3b94 implicit: 3_3_0-17
Stable	Latest release for each maintained stable branch	stable-3_3_0
LTS	Latest long-term support release	lts-3_3
Latest	Most recent release overall (for development only)	latest

Which image should I use?

The one that fits better with your needs, but if you have doubts, use the last LTS (or ask in pkp's forum explaining your specific needs).

You need to keep in mind that only these three aliases and the most recently released image (current) are subject to security checks and maintenance, so...

• If you want to "pin" an exact build that will never change, use the explicit tag and update manually on each release.
• If you prefer a tag that automatically receives security patches and minor fixes, use the implicit tag.
• If you have more relaxed needs, you may also use stable or lts.
• The latest tag will always be unstable, intended for development, and should never be used in production.

This naming convention is still under discussion and may change based on feedback in the Discussions area.

ToDo

List of tasks that need to be done:

• Logs on stderr.
• OxS installation from commandline.
• PHP variants (mod and fpm).
• gitHub Actions to build images based on commits (and autopush to DockerHub).
• Dockerfile and docker-compose created from templates.
• Build and publish images for all versions.
• Create a DEV image built from git repos.
• Move from debian to debian-slim.
• Add old "docker-ojs" project feature requests (see issues).
• Nginx variant.
• Extend image with DEV tools.
• Add and test "OPS" images.

Issues and Disclaimer

Notice
This project evolves over time, and criteria may have changed or may change in the future.
For example, images were initially built from git on Alpine; now we use the released tarball on Debian.
In any case, changes are always kept to a minimum to help ensure backward compatibility.
An example of this is the nomenclature described in this README (with explicit tags and multiple aliases) will apply starting with versions 3.3.0-22, 3.4.0-10, and 3.5.0-2, while the ‘implicit’ nomenclature (equivalent to PKP's, e.g., ojs:3_2_0-6) has remained consistent since its inception and will continue to do so in the future.

If you have questions, improvements or you find any bug, you can report them in this repository's issue tracker.

This project is maintained by community members in their spare time, so support is limited and no detailed roadmap is available. Assistance is only provided for problems with the official images, not for general Docker usage or installation-specific issues.

Attribution and License

This repository is derived from the Public Knowledge Project containers repository.

The original project is Copyright © Public Knowledge Project and contributors and is licensed under the GNU General Public License, version 3 (GPL-3.0).

This repository contains modifications maintained by Temple University Libraries, including the Alpine/PHP 8.5 runtime, project-specific configuration support, scheduled-task handling, and local development tooling.

See LICENSE for the full license text.