diff --git a/_data/versions.yml b/_data/versions.yml index a3ace97cccb9..dc7fc0dac19b 100644 --- a/_data/versions.yml +++ b/_data/versions.yml @@ -1,5 +1,6 @@ admin-guide: - 3.4: /admin-guide + 3.5: /admin-guide + 3.4: /admin-guide/3.4/en 3.3: /admin-guide/3.3/en api: ojs: diff --git a/_includes/cards/dev/admin-guide.md b/_includes/cards/dev/admin-guide.md index 53c42afed7fa..a7fba096d768 100644 --- a/_includes/cards/dev/admin-guide.md +++ b/_includes/cards/dev/admin-guide.md @@ -5,4 +5,4 @@ How to install and configure the application, import and export data, secure you --- -Versions: [3.4](/admin-guide/en), [3.3](/admin-guide/3.3/en/) ([Français](/admin-guide/3.3/fr/)) +Versions: [3.5](/admin-guide/en), [3.4](/admin-guide/3.4/en), [3.3](/admin-guide/3.3/en/) ([Français](/admin-guide/3.3/fr/)) diff --git a/admin-guide/3.3/en/data-import-and-export.md b/admin-guide/3.3/en/data-import-and-export.md index ea8dfa9386bb..7bf22742cb4f 100644 --- a/admin-guide/3.3/en/data-import-and-export.md +++ b/admin-guide/3.3/en/data-import-and-export.md @@ -154,10 +154,10 @@ If you are importing users into OJS, first create the XML import file. [See the Here are some things to consider: * Be sure to define the document type appropriately using ``. -* Your XML file should UTF8-encoded. +* Your XML file should be UTF8-encoded. * ``, `` and `` are mandatory. * If you allow the system to generate passwords for the users you are uploading, you can optionally allow the system to email the users with their account credentials. This option can be found on the Users XML Plugin Page \("Send a notification email to each imported user containing the user's username and password."\). -* You can require the user change their password when they next log in by setting the password attribute "change" to "true": ``myoldpassword`` +* You can require the user changes their password when they next log in by setting the password attribute "change" to "true": ``myoldpassword`` * The default password encryption is "plaintext" \(ie., none\). Encrypted assumes it was encrypted by `Validation::encryptCredentials()` and is using the same encryption algorithm used by the system. * If the imported file contains any usernames or email addresses that already exist in the system, the user data for those users will not be imported and any new roles to be created will be assigned to the existing users. diff --git a/admin-guide/3.3/en/email.md b/admin-guide/3.3/en/email.md index a245eb56b69e..d1ecfb231fd7 100644 --- a/admin-guide/3.3/en/email.md +++ b/admin-guide/3.3/en/email.md @@ -4,7 +4,7 @@ version: 3.3 --- # Email -This chapter explains how emails are sent in OJS, OMP, and OCS; the configuration options that are available; and how to troubleshoot email issues. +This chapter explains how emails are sent in OJS, OMP, and OPS; the configuration options that are available; and how to troubleshoot email issues. Mail in PKP software applications uses [the PHPMailer library](https://github.com/PHPMailer/PHPMailer). You can find out more about PHPMailer on [their wiki](https://github.com/PHPMailer/PHPMailer/wiki). Other code related to mail can be found in [the pkp-lib mail class](https://github.com/pkp/pkp-lib/tree/main/classes/mail). @@ -70,7 +70,7 @@ By default, PHPMailer will send mail through PHP's built-in `mail()` facility. On Windows, PHP needs to be configured to send email through a SMTP server \(running either on the same machine or on another machine\). -On other platforms such as Linux and Mac OS X, PHP will sent mail using the local sendmail client, so a local MTA such as Sendmail or Postfix must be running and configured to allow outgoing mail. +On other platforms such as Linux and Mac OS X, PHP will send mail using the local sendmail client, so a local MTA such as Sendmail or Postfix must be running and configured to allow outgoing mail. See [https://www.php.net/manual/en/function.mail.php](https://www.php.net/manual/en/function.mail.php) for more details on configuring PHP's mail functionality. @@ -96,9 +96,7 @@ Reloading templates will override any modifications that you may have made. To k All PKP applications require that primary and technical contacts are configured under Setup for proper daily operations. This is required for every journal, press, or conference in the system. -- In OJS 2.x, this can be done under _Setup Step 1_. -- In OCS 2.x, this can be done under _Website Management Step 1_. -- In OJS/OMP 3.x, this can be done under _Settings > Journal > Contact_. +In OJS/OMP/OPS 3.x, this can be done under _Settings > Journal/Press/Server > Contact_. ## Email Validation for New Users diff --git a/admin-guide/3.3/en/securing-your-system.md b/admin-guide/3.3/en/securing-your-system.md index 6d3ea4065802..77af6e164cb4 100644 --- a/admin-guide/3.3/en/securing-your-system.md +++ b/admin-guide/3.3/en/securing-your-system.md @@ -10,13 +10,13 @@ Please see [https://pkp.sfu.ca/ojs/README](https://pkp.sfu.ca/ojs/README), [http In general, the `files_dir` should not be web accessible and should be placed outside of the main software install directory. The software application will manage access to private submission files based on user roles and permissions \(i.e. Editors will have access to all submission files, whereas authors will only be able to access their own submission files\). -In addition, to ensure security the `files_dir` folder should not be readable by other users on the server. Only the webserver should have the necessary read/write permissions so that OJS, OMP, or OCS can read existing files and add new files to the folder, e.g. +In addition, to ensure security the `files_dir` folder should not be readable by other users on the server. Only the webserver should have the necessary read/write permissions so that OJS, OMP, or OPS can read existing files and add new files to the folder, e.g. `drwxrwx--- 6 ojs www 204B 11 Sep 2017 files/` The exact details of file permissions will depend on how your web server runs PHP scripts (this is called the "server API" or "SAPI"). For example, if it uses `mod_php`, all PHP scripts will run as the `www-data` user or similar (this is inherently not 100% secure on a multi-user server). If it uses CGI, FastCGI, FPM, or a similar mechanism, it will likely run under your user account. -It is recommended that you install an SSL certificate for your OJS, OMP, or OCS install and ensure that your site always uses the HTTPS protocol to manage user registration, login, and to present content to readers. Once your SSL certificate has been installed and is confirmed to be working \(i.e. you can access your site via [https://myjournal.org](https://myjournal.org/)\) you can configure your site to always use HTTPS by using the following setting in `config.inc.php`: +It is recommended that you install an SSL certificate for your OJS, OMP, or OPS install and ensure that your site always uses the HTTPS protocol to manage user registration, login, and to present content to readers. Once your SSL certificate has been installed and is confirmed to be working \(i.e. you can access your site via [https://myjournal.org](https://myjournal.org/)\) you can configure your site to always use HTTPS by using the following setting in `config.inc.php`: `; Force SSL connections site-wide force_ssl = On` @@ -37,16 +37,16 @@ salt = "sdlkjfhleiqwrfgbksdlkjgbelruywoeiyt7384gdqlywqvlwjf"` A secure deployment of PKP software can be best achieved by using the following recommendations, which are described in docs/README in every download of the software: -* Dedicate a database to OJS, OMP, and OCS; use unique credentials to access it. Configure this database to perform automated backups on a regular basis. Perform a manual backup when upgrading or performing maintenance. If you do not have access to your database contact your system administrator and ensure that database backups are taking place for your OJS. +* Dedicate a database to OJS, OMP, and OPS; use unique credentials to access it. Configure this database to perform automated backups on a regular basis. Perform a manual backup when upgrading or performing maintenance. If you do not have access to your database contact your system administrator and ensure that database backups are taking place for your OJS. * Configure the software (`config.inc.php`) to use SHA1 hashing rather than MD5. * Enable captcha or recaptcha in your `config.inc.php` file, and test that they are working. This will prevent most spam user registrations. * Configure the software (`config.inc.php`) to use `force_login_ssl` so that authenticated users communicate with the server via HTTPS. (You will also have to properly create and configure an SSL certificate to do this properly.) -* Install the software so that the files directory is NOT a subdirectory of the OJS, OMP, or OCS installation and cannot be accessed directly via the web server. +* Install the software so that the files directory is NOT a subdirectory of the OJS, OMP, or OPS installation and cannot be accessed directly via the web server. * Restrict file permissions as much as possible. * Deploy and test a proper backup mechanism. The backup mechanism should back up the database, the system files, and the file storage area (the `files_dir` parameter in `config.inc.php`). Ideally, you should make both on-site and off-site backups. * Ensure that your web server environment is regularly updated, in particular with any and all security patches. -If these steps are followed, you will substantially reduce the risk of falling prey to common hacking techniques. If already running OJS, OMP, or OCS, we strongly urge you to review your existing configurations and ensure these steps have been followed. +If these steps are followed, you will substantially reduce the risk of falling prey to common hacking techniques. If already running OJS, OMP, or OPS, we strongly urge you to review your existing configurations and ensure these steps have been followed. ### Secure File Management @@ -55,7 +55,7 @@ Authors, reviewers, and editors deal with submission files from people they don * Make sure you have antivirus software installed, and that it is up to date * Make sure your operating system and all software (especially Word and Excel) are kept up to date, ideally by turning on any auto-update features available to you * Make sure you have a backup solution available for your work computers -* Practice good password management: don’t use the same username/password in OJS, OMP, or OCS as you would for any other online account, and don’t use an easy to guess password +* Practice good password management: don’t use the same username/password in OJS, OMP, or OPS as you would for any other online account, and don’t use an easy to guess password * Treat everything that you get online with the knowledge that you received it from someone you don’t know, and act likewise. If a submission appears to be suspicious for any reason (strange email address, suspiciously generic title or abstract, etc.), treat the included files with an additional level of diligence. ## Encryption @@ -76,7 +76,7 @@ Google announced in 2014 that https [would be treated as a ranking signal](https ### Getting a Certificate -A certificate enables a secure connection from the user's Web browser to the server hosting your site. Installing a certificate for your site can not be done within the OJS, OMP, or OCS software and will require technical expertise or assistance at the server level. When considering a software host, determining their level of certificate support is an important consideration. +A certificate enables a secure connection from the user's Web browser to the server hosting your site. Installing a certificate for your site can not be done within the OJS, OMP, or OPS software and will require technical expertise or assistance at the server level. When considering a software host, determining their level of certificate support is an important consideration. A good start is asking your hosting service provider if they have an existing solution for supporting TLS or SSL certificates -- Your hosting provider may be able to create/issue an TLS or SSL certificate for you. If you do not have shell access to your installation this may be the only way to go about adding SSL/TLS protection for your site. @@ -126,7 +126,7 @@ Don’t forget to test this setup by registering a test account and confirming t ### Enable Account Validation -OJS, OMP, and OCS can be configured so that an email account validation step must be completed for all new user accounts before they can log in and interact with the system. To do this, uncomment and configure the following lines in `config.inc.php`: +OJS, OMP, and OPS can be configured so that an email account validation step must be completed for all new user accounts before they can log in and interact with the system. To do this, uncomment and configure the following lines in `config.inc.php`: ``` ; If enabled, email addresses must be validated before login is possible. diff --git a/admin-guide/3.3/en/single-signon.md b/admin-guide/3.3/en/single-signon.md index ed14c2b95caa..c5aecb694df7 100644 --- a/admin-guide/3.3/en/single-signon.md +++ b/admin-guide/3.3/en/single-signon.md @@ -4,7 +4,7 @@ version: 3.3 --- # User Authentication and Single Sign-on -For synchronizing user accounts across multiple applications, OJS and OCS support LDAP and Shibboleth, both of which have varying degrees of support in other applications including PhpBB, Drupal, WordPress, and other content management systems. +For synchronizing user accounts across multiple applications, OJS supports LDAP and Shibboleth, both of which have varying degrees of support in other applications including PhpBB, Drupal, WordPress, and other content management systems. *LDAP* (the Lightweight Directory Access Protocol), while not as powerful as Shibboleth (e.g. LDAP does not support single sign-on, where logging into one service automatically logs into all others), is a common choice for centralizing authentication on a server. A popular LDAP implementation is [OpenLDAP](https://www.openldap.org/) an open source implementation of the protocol. @@ -13,8 +13,6 @@ For synchronizing user accounts across multiple applications, OJS and OCS suppor ## Setting up Shibboleth -*Note*: Please note that Shibboleth support has not yet been ported to OCS. - Shibboleth is maintained by the [Internet2 Middleware Initiative](http://shibboleth.internet2.edu/), and as such their website provides a central location for downloads and documentation. Currently, they provide Shibboleth Service Provider 2.1 in binary form for all major operating systems, as well as providing source code. For further information on installing and setting up the Shibboleth Service Provider, please consult Internet2's support documentation. Once Shibboleth is set up on your system, integration with your PKP application requires the use of the [Shibboleth plugin](https://github.com/pkp/shibboleth) from the Plugin Gallery. After enabling this plugin, visit the plugin's Settings page for instructions on configuration. diff --git a/admin-guide/3.4/en/SUMMARY.md b/admin-guide/3.4/en/SUMMARY.md new file mode 100644 index 000000000000..6954b5aea535 --- /dev/null +++ b/admin-guide/3.4/en/SUMMARY.md @@ -0,0 +1,36 @@ +# Table of contents + +* [Introduction](./) +* [Getting Started](./getting-started) + * [Requirements](./getting-started#system-requirements) + * [Download](./getting-started#download) + * [Install](./getting-started#install) +* [Deployment](./deploy) + * [Configuration](./deploy#configuration) + * [Email](./deploy-email) + * [Jobs](./deploy-jobs) + * [Users](./deploy-users) + * [Multi-tenant](./deploy-multi-tenant) + * [Sandbox](./deploy-sandbox) +* [Import/Export](data-import-and-export) + * [REST API](data-import-and-export#rest-api) + * [Native XML](data-import-and-export#native-xml) + * [QuickSubmit](data-import-and-export#quicksubmit) + * [OAI](data-import-and-export#oai) + * [Users](data-import-and-export#users) + * [Export to Services](data-import-and-export#export-to-services) + * [CLI Tools](data-import-and-export#cli-tools) + * [Troubleshooting](data-import-and-export#troubleshooting) +* [Security](securing-your-system) + * [Checklist](securing-your-system#security-checklist) + * [File Permissions](securing-your-system#file-permissions) + * [SSL/Encryption](securing-your-system#sslencryption) +* [Statistics](statistics) + * [Settings](statistics#settings) + * [Download](statistics#download) + * [Recover Lost Data](statistics#recover-lost-data) + * [FAQ](statistics#frequently-asked-questions) +* [Troubleshooting](troubleshooting) + * [Permissions, File Access, Etc.](./troubleshooting.md#permissions-file-access-etc) + * [Character Encoding](./troubleshooting.md#character-encoding) + * [Error-reporting](./troubleshooting.md#error-reporting-blank-pages-diagnostics-etc) diff --git a/admin-guide/3.4/en/assets/install-complete.png b/admin-guide/3.4/en/assets/install-complete.png new file mode 100644 index 000000000000..32523d45a1ce Binary files /dev/null and b/admin-guide/3.4/en/assets/install-complete.png differ diff --git a/admin-guide/3.4/en/assets/install-start.png b/admin-guide/3.4/en/assets/install-start.png new file mode 100644 index 000000000000..fa641cc851ed Binary files /dev/null and b/admin-guide/3.4/en/assets/install-start.png differ diff --git a/admin-guide/3.4/en/assets/settings-wizard-context-switcher.png b/admin-guide/3.4/en/assets/settings-wizard-context-switcher.png new file mode 100644 index 000000000000..1fb81518bf11 Binary files /dev/null and b/admin-guide/3.4/en/assets/settings-wizard-context-switcher.png differ diff --git a/admin-guide/3.4/en/assets/settings-wizard.png b/admin-guide/3.4/en/assets/settings-wizard.png new file mode 100644 index 000000000000..10020fb37938 Binary files /dev/null and b/admin-guide/3.4/en/assets/settings-wizard.png differ diff --git a/admin-guide/3.4/en/data-import-and-export.md b/admin-guide/3.4/en/data-import-and-export.md new file mode 100644 index 000000000000..ad07fd51459e --- /dev/null +++ b/admin-guide/3.4/en/data-import-and-export.md @@ -0,0 +1,160 @@ +--- +title: Import and Export - Admin Guide - PKP Developer Docs +description: How to import and export articles, issues, books, preprints and users with OJS, OMP or OPS. +book: admin-guide +version: 3.4 +--- + +# Import and Export + +There are many ways to import and export data with OJS, OMP and OPS. To access these tools, you will need to have an account with administrator or manager privileges. Many of these tools are available from the [command line](#cli-tools). + +## REST API + +You can use the REST API to read and write some data in the application. See the [API documentation](https://docs.pkp.sfu.ca/dev/api). + +## Native XML + +> The Native XML format changes with each major version. You can not import an XML file generated with 3.2 into a 3.3 install. +{:.notice} + +The Native XML format is our XML schema to import and export submissions in OJS, OMP and OPS. This format is preferred for importing back issues, books or preprints, or moving submissions from one journal, press or preprint server to another. This format includes the submissions, their metadata, and all submission files. In OJS, it also includes issue metadata. When submissions are imported using this format, all imported issues, authors, users and files will be created. + +Follow these steps to import or export submissions using Native XML. + +1. Login as an administrator or manager. +2. Click **Tools** in the main navigation menu. +3. Click **Native XML Plugin**. +4. Click **Import** or **Export** and follow the steps. + +### Create a Native XML file for import + +> To create an import file, you will need to have a basic understanding of [XML](https://en.wikipedia.org/wiki/XML). +{:.notice} + +Before you can import data using this format, you will need to create a XML file that matches the format's schema. The following table includes the XML schemas along with sample XML import files. + +| Schema | Sample | Description | +| --- | --- | +| [native.xsd](https://github.com/pkp/pkp-lib/blob/stable-3_4_0/plugins/importexport/native/pkp-native.xsd) | | Base schema extended by all applications. | +| [native.xsd](https://github.com/pkp/ojs/blob/stable-3_4_0/plugins/importexport/native/native.xsd) | [sample.xml](https://github.com/pkp/datasets/blob/main/ojs/stable-3_4_0/mysql/native-export-sample.xml) | Issues and articles in OJS. | +| [native.xsd](https://github.com/pkp/omp/blob/stable-3_4_0/plugins/importexport/native/native.xsd) | [sample.xml](https://github.com/pkp/datasets/blob/main/omp/stable-3_4_0/mysql/native-export-sample.xml) | Book in OMP. | +| [native.xsd](https://github.com/pkp/ops/blob/stable-3_4_0/plugins/importexport/native/native.xsd) | [sample.xml](https://github.com/pkp/datasets/blob/main/ops/stable-3_4_0/mysql/native-export-sample.xml) | Preprint in OPS. | + +Consider the following when creating your XML import file. + +* Define the document type appropriately using ``. +* The XML file should be UTF8-encoded. +* Dates should be specified as YYYY-MM-DD. +* To import a file, you can use `` to place a file directly within your XML document, or use `` to link to one. +* If you use the `` tag you will have to base64-encode your files. +* When embedding files, the XML file may become very large. In such cases, you may need to import through the [CLI tools](#cli-tools) +* URLs using `` can link to remote or local files. +* Use local URLs if your galleys are already stored on the destination machine. For this to work, you need to [import from the command line](#cli-tools). +* Some elements can support HTML tags, such as the `abstract`. If you embed HTML within your document, remember to wrap the HTML within `` tags. +* If your journal supports more than one locale, you can include translated terms in a separate entry. +* If you make any typographical errors in the data you are trying to import, you may end up with duplicate or split entries: for example, if your journal already has a section "Articles" with the initials ART, but you mistype in your XML file `AR` instead of `ART`, a new journal section with the initials AR will be created, and that one article will be added to it. This is easier to fix before you run the import than it is to clean up after. +* Consider validating your XML file with an editor like Liquid XML Editor or Oxygen XML. It is easier to find validation errors in these editors than through the import UI in OJS, OMP or OPS. + +## QuickSubmit + +The QuickSubmit plugin is a useful tool for importing a small amount of back content. It provides a UI that managers can use to manually add a submission, assign it to an issue, and publish it. + +Learn more about how to use this plugin in [the QuickSubmit plugin guide](/quicksubmit/en/). + +## OAI + +Every journal, press or preprint server produces a public [OAI](https://www.openarchives.org/) (Open Archives Initiative) interface that can be used to access published content in the OAI XML format. + +To access it, visit the `/oai` page for any journal, press or preprint server. For example, if the homepage is accessed at `https://example.org/example-journal/`, visit `https://example.org/example-journal/oai`. + +To enable or disable the endpoint, change the `oai` setting in `config.inc.php`. + +## Users + +There are a few ways to import or export user accounts. User accounts control access to the application and are distinct from the contributor records of submissions. + +### REST API + +See the [API documentation](https://docs.pkp.sfu.ca/dev/api) to see what user data can be read or written with the REST API. + +### CSV + +User account information for each journal can be downloaded as a CSV file using the following steps. + +1. Login as an administrator or manager. +2. Go to **Statistics** > **Users** in the main navigation menu. +3. Click the **Export** button. +4. Select all the roles you want to include in the CSV file. +5. Click the **Export** button. + +It may take several minutes to generate the CSV file if you have a large user database. + +### XML + +> The Users XML format changes with each major version. You can not import an XML file generated with 3.2 into a 3.3 install. +{:.notice} + +The Users XML format is our XML schema to import and export users and their roles. This can be used to move user accounts between systems, and import from other systems or export to other systems. This format includes the user information and the roles they have in the system. + +Follow these steps to import or export users using the User XML. + +1. Login as an administrator or manager. +2. Click **Tools** in the main navigation menu. +3. Click **Users XML Plugin**. +4. Click **Import** or **Export** and follow the steps. + +### Create a Users XML file for import + +> To create an import file, you will need to have a basic understanding of [XML](https://en.wikipedia.org/wiki/XML). +{:.notice} + +Before you can import data using this format, you will need to create a XML file that matches the format's schema. The following table includes the XML schemas along with sample XML import files. + +| Schema | Sample | Description | +| --- | --- | +| [pkp-users.xsd](https://github.com/pkp/pkp-lib/blob/stable-3_4_0/plugins/importexport/users/pkp-users.xsd) | [sample.xml](https://github.com/pkp/ojs/blob/stable-3_4_0/plugins/importexport/users/sample.xml) | Example users for OJS | +| [pkp-users.xsd](https://github.com/pkp/pkp-lib/blob/stable-3_4_0/plugins/importexport/users/pkp-users.xsd) | [sample.xml](https://github.com/pkp/omp/blob/stable-3_4_0/plugins/importexport/users/sample.xml) | Example users for OMP | + +Consider the following when creating your xml import file. + +* Define the document type appropriately using ``. +* The XML file should be UTF8-encoded. +* `` and `` are mandatory. +* If you allow the system to generate passwords for the users you are uploading, you can optionally allow the system to email the users with their account credentials. This option can be found on the Users XML Plugin Page ("Send a notification email to each imported user containing the user's username and password."). +* You can require the user change their password when they next log in by setting the password attribute "change" to "true": `myoldpassword` +* The default password encryption is "plaintext" (ie., none). Encrypted assumes it was encrypted by `Validation::encryptCredentials()` and is using the same encryption algorithm used by the system. +* If the imported file contains any usernames or email addresses that already exist in the system, the user data for those users will not be imported and any new roles to be created will be assigned to the existing users. +* Consider validating your XML file with an editor like Liquid XML Editor or Oxygen XML. It is easier to find validation errors in these editors than through the import UI in OJS, OMP or OPS. + +## Export to Services + +Each application provides plugins to export published metadata to indexing services, such as Crossref, PubMed, DataCite, DOAJ, mEDRA and more. Some of these plugins deposit directly to the services. Others generate an export file according to the service's specifications. + +Go to **Settings** > **Website** > **Plugins** to install and configure these plugins. Our [user documentation hub](/) provides guidance for working with many of them. + +## CLI Tools + +Many of the import/export plugins can be run from the command line. This includes the official plugins for submissions (Native XML) and users that are included with every release. + +Run the following command from the root directory of the application to see which import/export tools are available. + +``` +php tools/importExport.php list +``` + +Run the following command to see how to use this tool. + +``` +php tools/importExport.php usage +``` + +## Troubleshooting + +> "I imported my XML file and I’m getting an error message." + +Did you validate your XML file before importing it? If you did not, run it through a validator in your XML editor or browser and the validator will indicate what is wrong with the file. + +> "When I click on the Export button I get a blank page instead of a list of data to export." + +Your server's error log should contain a more useful error message to help you track down the source of the problem. diff --git a/admin-guide/3.4/en/deploy-email.md b/admin-guide/3.4/en/deploy-email.md new file mode 100644 index 000000000000..36339f85fba8 --- /dev/null +++ b/admin-guide/3.4/en/deploy-email.md @@ -0,0 +1,111 @@ +--- +title: Email - Advanced Configuration - Admin Guide - PKP Developer Docs +description: Recommendations for configuring a reliable email server for Open Journal Systems (OJS), Open Monograph Press (OPS) or Open Preprint Systems (OPS). +book: admin-guide +version: 3.4 +--- + +# Email Configuration + +> Most hosting services will provide a configured email server. If you are unsure, contact your hosting provider to learn what they are able to offer. +{:.notice} + +This section describes the requirements for a properly configured email server and discusses some of the configuration options for sending email with OJS, OMP and OPS. If you know what you're doing, you may prefer to follow the quick setup instructions in our [configuration guide](/admin-guide/en/deploy#email-server). + +## SPF + +Your domain must be configured according to the [SPF](https://en.wikipedia.org/wiki/Sender_Policy_Framework) protocol. To comply with this protocol, your domain's DNS zone must include an appropriate `TXT` record. For example, if the application is hosted at `https://my-journals.com`, the domain `my-journals.com` must have a `TXT` record in it's DNS zone. + +Your hosting service should provide instructions on how to add the `TXT` record. + +## DMARC + +To comply with the [DMARC](https://en.wikipedia.org/wiki/Sender_Policy_Framework) framework, the application must be configured with an envelope sender. The envelope sender is an email address that the server has permission to send as. For example, if the application is hosted at https://my-journals.com, the envelope sender should be an email address `@my-journals.com`. + +When a user signs up to the application with the email address `example@gmail.com`, your email server does not have permission to send as `example@gmail.com`. The envelope sender acts as the "true" sender, and the email is sent "on behalf of" `example@gmail.com`. + +To configure the envelope sender, edit the following settings in the application's `config.inc.php` file: + +``` +allow_envelope_sender = On +default_envelope_sender = +force_default_envelope_sender = On +force_dmarc_compliant_from = On +``` + +The application uses these settings to reconfigure the `FROM` and `REPLY-TO` headers in all emails it sends. + +## Sendmail vs SMTP vs PHPMailer + +Most hosting services will provide the details the application should use to connect to a SMTP server for sending email. If you have those, follow the instructions in the [configuration guide](/admin-guide/en/deploy#email-server). + +If not, the server will probably be configured to send email through the `sendmail` application. In such cases, set the `default` sender to `sendmail` in the `config.inc.php`: + +``` +[email] +default = sendmail +``` + +If the `sendmail` binary is not at the usual location on the server, you may need to set the `sendmail_path`: + +``` +[email] +default = sendmail +sendmail_path = " -bs" +``` + +In rare cases, neither option is available and you must use `PHPMailer`. This mailer is not secure and we strongly discourage its use. However, if you need it, set the `default` to `phpmailer`: + +``` +[email] +default = phpmailer +``` + +## Gmail + +Use the following configuration settings to send email through a personal Gmail account: + +``` +smtp = On +smtp_server = smtp.gmail.com +smtp_port = 465 +smtp_auth = ssl +smtp_username = +smtp_password = +``` + +## Commercial Services + +You can use a third-party email service, such as MailGun, Amazon SES, or Postmark, to send email if you don't want to run your own email service. However, this is not officially supported so you may need to write a small amount of custom PHP code. + +Under-the-hood, all of our applications use Laravel's [Mail](https://laravel.com/docs/9.x/mail) library, which itself uses Symfony's [Mailer](https://symfony.com/doc/current/mailer.html). Transports are included for Mailgun, Amazon SES and Postmark, and these services can be used by writing a small plugin. See the example [Mailgun plugin](https://github.com/Vitaliy-1/mailgun/). + +Other transports can be be found by searching for "symfony mailer transport". A plugin would need to be written to import these transports and make use of them. If you write a transport for a service, please share it with [our community](https://forum.pkp.sfu.ca/). + +## Bounce Address + +Once you have set an `envelope_sender`, a new setting will appear under Settings > Workflow > Emails. This allows you to set a custom bounce address for each journal. + +Note that this option may require changes to the server’s mail server configuration so that the user the web server runs as (e.g. “www-data”) is trusted by the sendmail program; otherwise an “X-Warning” header will be added to outgoing messages. Consult your mail server’s documentation if outgoing mails include such a header. + +For example, Sendmail keeps a list of trusted users in `/etc/mail/trusted-users`. Other mail systems use similar files. + +The command-line option used to set the envelope sender is -f. + +## Troubleshooting Problems with Emails + +If you are facing problems with emails not being delivered, you should contact whoever runs your email server. This is usually your hosting service provider. + +We can not do much to help you troubleshoot problems with your email delivery. That's because our applications do not actually send the emails themselves. When an application wants to send an email, it sends a request to the email server to send and deliver the email. + +**Only your email server provider can say whether an email was sent and why.** + +If you run your own email server, you can ask for help in our [community forum](https://forum.pkp.sfu.ca/). Otherwise, we recommend contacting your web server provider to investigate the following: + +1. Contact your web server provider and ask them if emails are being sent that comply with the SPF and DMARC protocols. They'll be able to check the logs and see if the `FROM` and `REPLY-TO` headers of emails match the SPF and DMARC configuration. +2. All email servers keep a log of what emails were sent. Ask your email server provider to check if a specific email was sent. They'll want the recipient, date and time of an email that was supposed to be sent, but was never received. +3. Often, an email will be sent but the recipient's email server refused to receive it. In some cases, the recipient email server will reply with the reason it is refusing (or "bouncing") the email. Your email server provider may be able to check the logs to see if a sent email was bounced and why. + +--- + +Next, learn about how to improve performance with the [job runner](./deploy-jobs). diff --git a/admin-guide/3.4/en/deploy-jobs.md b/admin-guide/3.4/en/deploy-jobs.md new file mode 100644 index 000000000000..9ca6566c7566 --- /dev/null +++ b/admin-guide/3.4/en/deploy-jobs.md @@ -0,0 +1,225 @@ +--- +title: Jobs - Advanced Configuration - Admin Guide - PKP Developer Docs +description: Options to configure the job runner to improve performance with Open Journal Systems (OJS), Open Monograph Press (OPS) or Open Preprint Systems (OPS). +book: admin-guide +version: 3.4 +--- + +# Job Runner + +> These recommendations are for high-volume journal, press or preprint services. Low-volume services can use the built-in job runner with no configuration. +{:.notice} + +Each application makes use of a jobs queue to handle long-running tasks. Jobs are used to send bulk email notifications, compile statistics, deposit DOIs, update the search index, and more. + +On a high-volume site, these tasks may slow down the server while they are being completed. To solve this problem, server administrators can move these tasks to separate requests or even into separate threads on the server. + +Most sites will get by without too many problems by using a cron job or the built-in job runner. However, the larger your site is, the more risk there is of jobs causing the site to suddenly slow down during peak periods of activity. In such circumstances, it will be more important to configure the job runner well. + +## How to Run Jobs + +Every server should be configured with _one_ of the following methods for running jobs: workers, cron, or the built-in job runner. Enabling two methods will not improve the site's performance. + +To see all available command-line options, run: + +``` +php lib/pkp/tools/jobs.php usage +``` + +### Workers + +For large sites, we recommend using a worker to process jobs. The worker, when run as a daemon, will wait for jobs to be dispatched and then run them one-by-one in a separate process on the server. +System resources can be specifically allocated to the worker so that it will not cause spikes in resource usage that slow down the main site. + +The following command can be used to initialize a worker. + +``` +php lib/pkp/tools/jobs.php work +``` + +This command supports most of the options supported by Laravel's [queue:work](https://laravel.com/docs/9.x/queues#running-the-queue-worker). Pass the `--help` flag to learn more. + +``` +php lib/pkp/tools/jobs.php work --help +``` + +In a production environment, you should use a process monitor like [Supervisor](http://supervisord.org/index.html) to make sure the process stays up and running. Supervisor can be installed on Linux with the following command. + +``` +sudo apt-get install supervisor +``` + +Create a config file for supervisor, usually located at `/etc/supervisor/conf.d`. + +``` +[program:ojs-queue-monitor] +process_name=%(program_name)s +command=/php //lib/pkp/tools/jobs.php work +directory= +autostart=true +autorestart=true +redirect_stderr=true +stdout_logfile= +``` + +Replace the following variables in the configuration above with the correct paths in your system: + +| Variable | Description | +| --- | --- | +| `` | Absolute path on the server to the CLI PHP executable. This can be found on most Linux servers by running `which php`. | +| `` | Absolute path to the root directory of the application (OJS, OMP, OPS). | +| `` | Absolute path to a log file. If hosting in a cloud environment, you may want to [direct logs to stdout](https://stackoverflow.com/a/26897648/1723499). | + +> Take a special note that workers are long running process that loads the application in memory. As a result, any changes when workers are running will not reflect instantly without restarting the worker. +{:.notice} + +Restart Worker. + +``` +php lib/pkp/tools/jobs.php restart +``` + +The above command will quit the workers gracefully what is workers will get to complete the current job execution and then quit. Then the Supervisor will restart the workers. + +Restart Supervisor. + +``` +sudo service supervisor restart +``` + +You may need to run the following command to apply the configuration changes. + +``` +supervisorctl reread +``` + +> **Warning:** We strongly recommend to restart the Worker rather than Supervisor to reflect and consider the new changes pushed to production. Restarting Supervisor suddenly will cause the workers to quit abruptly and if the workers are in the middle of processing a job, it will not get the chance to complete the job which may cause undesired. +{:.warning} + +To configure Supervisor on other systems, or to learn more about monitoring processes, read the [Supervisor documentation](http://supervisord.org/index.html). + +Once you have set up the worker, turn the default job runner off in `config.inc.php`: + +``` +job_runner = Off +``` + +### Cron + +A [cron job](https://en.wikipedia.org/wiki/Cron) can be configured to process jobs at regular intervals, for example every 30 or 60 seconds. + +A cron job configured to run the following command will process all jobs in the queue. + +``` +php lib/pkp/tools/jobs.php run +``` + +A cron job configured to run the following command will process only one job. + +```php +php lib/pkp/tools/jobs.php run --once +``` + +Whether or not to process one or all jobs will depend on your environment. When **running all jobs at once**, a sudden batch of large, resource-intensive jobs could slow down your server. That's because the cron job will try to churn through everything all at once. + +When **running one job at a time**, the cron job will be less likely to consume a lot of server resources all at once. However, there is a risk that jobs will back up over time. If a bulk email is sent to 5,000 users, it may create 100 jobs. Processing one job every 60 seconds, it would take 100 minutes to send the email. + +Once you have set up a cron job, turn the default job runner off in `config.inc.php`: + +``` +job_runner = Off +``` + +We recommend using [workers](#workers) for large sites. Learn more about how to [monitor jobs](#how-to-monitor-jobs) to make sure they are not backing up. + +### Built-in Job Runner + +In some server environments, you may not have permission to configure workers or cron jobs. On these servers, the built-in job runner can be used to process jobs. + +The built-in job runner works by running jobs off the back of user requests to the server. When no one visits your site, no jobs are run. As a result, there is a greater risk of jobs causing sudden spikes in resource usage, which will result in delays loading the site. + +Turn the built-in job runner on in the `config.inc.php` file. + +``` +job_runner = On +``` + +To prevent the server's resources from being exhausted or hitting the server's execution timeouts, you can configure the built-in job runner with the following settings. + +``` +; The maximum number of jobs to run in a single request when using +; the built-in job runner. +job_runner_max_jobs = 30 + +; The maximum number of seconds the built-in job runner should spend +; running jobs in a single request. +; +; This should be less than the max_execution_time the server has +; configured for PHP. +; +; Lower this setting if jobs are failing due to timeouts. +job_runner_max_execution_time = 30 + +; The maximum consumerable memory that should be spent by the built-in +; job runner when running jobs. +; +; Set as a percentage, such as 80%: +; +; job_runner_max_memory = 80 +; +; Or set as a fixed value in megabytes: +; +; job_runner_max_memory = 128M +; +; When setting a fixed value in megabytes, this should be less than the +; memory_limit the server has configured for PHP. +job_runner_max_memory = 80 +``` + +We recommend staying within the default limits above, unless you know your server is capable of running with higher limits. + +## How to Monitor Jobs + +You can monitor pending and failed jobs through the CLI tool or the administration interface of the application. + +Run the following command to view pending jobs in the terminal. + +``` +php lib/pkp/tools/jobs.php list +``` + +Or view them in the administration interface by going to Administration > Jobs. + +Run the following command to view failed jobs in the terminal. + +``` +php lib/pkp/tools/jobs.php failed +``` + +Or view them in the administration interface by going to Administration > Failed Jobs. From the admin interface you can also retry failed jobs. + +Add the following setting to `config.inc.php` to automatically delete failed jobs after a certain period. + +``` +; Remove failed jobs from the database after the following number of days. +; Remove this setting to leave failed jobs in the database. +delete_failed_jobs_after = 180 +``` + +## Custom Drivers + +Laravel [Queues](https://laravel.com/docs/9.x/queues) are used to dispatch and process jobs. By default, the application uses the `database` driver to store and process jobs. + +[Custom drivers](https://laravel.com/docs/9.x/queues#driver-prerequisites) exist for handling jobs with Redis, Beanstalkd, and Amazon SQS. These drivers are not officially supported, but may be implemented with a little coding. + +If you use a custom driver, please share your findings with [our community](https://forum.pkp.sfu.ca/). + +## Troubleshooting + +The best way to troubleshoot failed jobs is through Administration > Failed Jobs in the application. The failed jobs table will provide information on what jobs failed, when, and with what exceptions. + +Jobs should never be run while the site is under maintenance, for example during an upgrade. + +--- + +Learn more about handling [user accounts](./deploy-users). diff --git a/admin-guide/3.4/en/deploy-multi-tenant.md b/admin-guide/3.4/en/deploy-multi-tenant.md new file mode 100644 index 000000000000..0bca595065b8 --- /dev/null +++ b/admin-guide/3.4/en/deploy-multi-tenant.md @@ -0,0 +1,52 @@ +--- +title: Multi-tenancy - Advanced Configuration - Admin Guide - PKP Developer Docs +description: Recommendations for running many separate journals, presses or preprint servers in one install with OJS, OMP or OPS. +book: admin-guide +version: 3.4 +--- + +# Multi-tenancy + +When OJS, OMP or OPS is used to run many independent journals, presses or preprint servers, we call it a "multi-tenant" install. These instances often need to provide unique domains to each tenant. + +## Domain Names + +The `base_url` setting in `config.inc.php` can support multiple domains. Use the following syntax for multiple base URLs. + +``` +base_url[] = +``` + +For example, if you had two journals with path names `lorem` and `ipsum`, you can route them to different domains like this. + +``` +# Homepage of the lorem journal +base_url[lorem] = https://journal-a.com + +# Homepage of the ipsum journal +base_url[ipsum] = https://journal-b.com +``` + +Use the path `index` to route requests to the site index. + +``` +base_url[index] = https://example.com +``` + +You will also need to rewrite URLs using `mod_rewrite` or a similar mechanism, in order to route requests to the application to the correct domain name. The correct rewrite rules vary depending on each setup. You may wish to review [past discussions](https://forum.pkp.sfu.ca/t/each-journal-with-its-own-domain-name/5720). + +## Privacy Statement + +By default, every journal, press or preprint server can configure their own privacy statement. As the controlling authority in a multi-tenant service, you may wish to enforce a privacy statement that meets the requirements of your legal jurisdiction. + +Set the following to `On` in `config.inc.php`. + +``` +sitewide_privacy_statement = On +``` + +Then add a privacy statement by logging in as an administrator and going to **Administration** > **Site Settings** > **Site Setup** > **Information**. This form is only available when you have more than one journal, press or preprint server. + +--- + +Learn how to prevent unwanted emails, deposits and other tasks from being run in a [sandboxed test installation](./deploy-sandbox). diff --git a/admin-guide/3.4/en/deploy-sandbox.md b/admin-guide/3.4/en/deploy-sandbox.md new file mode 100644 index 000000000000..d1538463e0b1 --- /dev/null +++ b/admin-guide/3.4/en/deploy-sandbox.md @@ -0,0 +1,98 @@ +--- +title: Sandbox - Advanced Configuration - Admin Guide - PKP Developer Docs +description: Safely sandbox an install of OJS, OMP or OPS, to block email sending, data deposits, and other unwanted tasks. +book: admin-guide +version: 3.4 +--- + +# Sandbox an Instance + +> Trying to upgrade? Check out our step-by-step guide on [how to upgrade](/dev/upgrade-guide/en/). +{:.notice} + +When testing or debugging a production instance, you may want to sandbox the application to prevent it from sending emails, depositing data with third-party services, or performing other unwanted tasks. This section will describe some tips to sandbox your install. + +## Enabling Sandbox mode + +Beginning with OJS, OMP, and OPS 3.4.0-4, there is a sandbox mode that can be enabled in `config.inc.php` in order to prevent interactions with external systems. + +To enable the sandbox mode for an installation, edit `config.inc.php` and find the `sandbox` setting in the `[general]` section. Setting it to `On` will have following impacts: + + - The email `default` driver will be set to `log`. As a result all emails will be routed to the server's error log and no emails will be delivered. + - Scheduled tasks that run at regular intervals to send out reminder emails, deposit data with third-party services, and perform other tasks will be disabled. This will also disable schedule task execution via `Acron` plugin. + - Job execution will be disabled. However, jobs will continue to be dispatched to the queue as usual. + - `Crossref` and `Datacite` deposits will be disabled. + - The `ORCiD` plugin will not have any interaction with orcid service. + - No payments will dispatched to or handled by Paypal (e.g. for subscription purchases). + +> **Warning:** Enabling the sandbox mode will disable job processing via the job runner, cron and worker mechanisms. However, if any worker process is already running prior to enabling sandbox mode, it will require separate manual intervention to restart/quit worker gracefully. See the [Job Deployment Guide](/admin-guide/en/deploy-jobs) for more details. +{:.warning} + +## Manual intervention for Sandboxing + +As an alternative to the sandbox mode described above, it is also possible to configure individual features with their own sandboxing options. See below for instructions on configuring the sandboxing of individual features. + +### Send emails to the log + +All emails sent by the application can be routed to the server's error log. When this is done, no emails will be sent out. + +Find and edit the following setting in the `[email]` section of `config.inc.php`. + +``` +default = log +``` + +### Disable scheduled tasks + +Scheduled tasks are run at regular intervals to send out reminder emails, deposit data with third-party services, and perform other tasks. They may be triggered in a couple different ways, depending how you configured them. + +If you have a **cron job** set up to run the following command, delete that cron job. + +``` +php tools/runScheduledTasks.php +``` + +If you have the **acron plugin** installed, remove it by running the following command in the root directory of the application. + +``` +rm -rf plugins/generic/acron +rm -rf lib/pkp/plugins/generic/acron +``` + +### Disable jobs + +Stop the job runner in order to prevent pending jobs like data deposits from being run. Turn the built-in job runner off in `config.inc.php`. + +``` +job_runner = Off +``` + +Depending on how you configured your server to run jobs, you may need to take additional steps. + +If you are using **workers** to [process jobs](./deploy-jobs#workers), kill those processes. You may need to disable [Supervisor](./deploy-jobs#workers) or any process monitor that will restart the workers. + +If you are using a **cron job** to run the following command, delete that cron job. + +``` +php lib/pkp/tools/jobs.php run +``` + +Disabling jobs will stop some functionality from running. For example, the search index will not be rebuilt when submissions are published or unpublished. Jobs will pile up without being processed. Read how to [monitor jobs](./deploy-jobs#how-to-monitor-jobs). + +### Anonymize user emails + +> **Warning:** These queries will permanently alter your data. Make sure you have a backup! +{:.warning} + +Run the following SQL query on the database to set all user account emails to a dummy account. + +```sql +UPDATE users SET email=CONCAT(username,'@mailinator.com'); +``` + +Run the following SQL query on the database to set all author account emails to a dummy account. + +```sql +UPDATE authors SET email = 'test@mailinator.com'; +``` + diff --git a/admin-guide/3.4/en/deploy-users.md b/admin-guide/3.4/en/deploy-users.md new file mode 100644 index 000000000000..ccf900d42e05 --- /dev/null +++ b/admin-guide/3.4/en/deploy-users.md @@ -0,0 +1,160 @@ +--- +title: User Accounts - Advanced Configuration - Admin Guide - PKP Developer Docs +description: Configuration options to manager users in Open Journal Systems (OJS), Open Monograph Press (OPS) or Open Preprint Systems (OPS). +book: admin-guide +version: 3.4 +--- + +# User Accounts + +This section describes the configuration options, plugins, and application settings available in the application to control user registrations, reduce unwanted bot accounts, integrate with third-party user authentication services, and more. + +## Spam/Bot Accounts + +If the application is publicly accessible on the web, it will attract the attention of automated bots. These bots will create user accounts and try to post unwanted material to advertise products or deface the website. Read on to learn how to restrict access to these accounts. + +### Account Validation + +We recommend all instances require validation of the email address associated with the account. New users will be unable to login until they validate their account by clicking on an email sent to their email address. + +Turn the following setting `On` in `config.inc.php`. + +``` +require_validation = On +``` + +### reCAPTCHA + +Google's [reCAPTCHA](https://www.google.com/recaptcha/) service can be enabled for the registration and login forms. This will reduce the number of bots that can sign up by requiring users to complete a task that is difficult for bots to perform during registration and login. + +You will need to [sign up](https://www.google.com/recaptcha/) for an account with Google to receive public and private keys. Then set the following options in `config.inc.php`. + +``` +;;;;;;;;;;;;;;;;;;;; +; Captcha Settings ; +;;;;;;;;;;;;;;;;;;;; + +[captcha] + +; Whether or not to enable ReCaptcha +recaptcha = On + +; Public key for reCaptcha (see http://www.google.com/recaptcha) +recaptcha_public_key = your_public_key + +; Private key for reCaptcha (see http://www.google.com/recaptcha) +recaptcha_private_key = your_private_key + +; Whether or not to use Captcha on user registration +captcha_on_register = on + +; Whether or not to use Captcha on user login +captcha_on_login = on + +; Validate the hostname in the ReCaptcha response +recaptcha_enforce_hostname = Off +``` + +Use of Google's reCAPTCHA service will send your visitors' data to Google's servers. You may be required to notify users of this depending on the privacy laws in your jurisdiction. + +### Honeypot + +The [pkp-formHoneypot](https://github.com/ulsdevteam/pkp-formHoneypot) plugin from the University of Pittsburgh implements a [honeypot](https://en.wikipedia.org/wiki/Honeypot_(computing)) mechanism to protect new user registrations from bots. This plugin is effective against most bots and does not send your visitor's data to any third parties. + +### Disable Registration + +It's possible to set up a journal, press or preprint server to disable user registration. When user registration is disabled, all users will have to be registered by an admin or manager. + +Follow these steps to disable user registration in a journal, press or preprint server. + +1. Login as an admin or manager. +2. Go to **Users & Roles** > **Roles**. +3. Click the **>** button next to the **Reader** role to expand the options. +4. Click **Edit**. +5. Under **Role Options**, uncheck **Allow user self-registration**. +6. Click **OK**. +7. Click the **Search** button. +8. Under *With permission level set to* select **Author**. +9. For each role, follow steps 3-7 to prevent user self-registration. +10. Repeat steps 7-8 with **Reviewer** selected for the permission level. +11. For each role, follow steps 3-7 to prevent user self-registration. + +Only reader, author and reviewer roles can allow user self-registration. User self-registration is always disabled for other roles. + +### Remove Accounts + +If you already have a large number of spam registrations, you may want to remove these accounts. User accounts can not be deleted. Instead, they must be merged to another account in order to ensure that any editorial data (such as submissions, reviews, etc) is maintained. + +Run the following command from the root directory of the application to merge a spam registration into another account. + +```bash +php tools/mergeUsers.php +``` + +Usually, the spam accounts are merged into one account created for this purpose. For example, you may create an account with the username `spamaccount`. If you want to remove `usernameOne`, run the following command. + +```bash +php tools/mergeUsers.php spamaccount usernameOne +``` + +Multiple users can be merged in a single command. + +```bash +php tools/mergeUsers.php spamaccount usernameOne UsernameTwo usernameThree [...] +``` + +A shortcut would be to collect the usernames you want to remove in a file. + +``` +usernameOne +usernameTwo +usernameThree +``` + +Then load the file into the the command. + +```bash +php tools/mergeUsers.php spamaccount $(cat usernames.txt) +``` + +## User Uploads + +By default, all users registered on the site can upload files to a personal user directory. These files can be used in the user's signature or biography. Managers and admins can use these files in journal settings. For example, if a manager uploads an image to the "About the Journal" section, this will use their user directory. + +You can disable all user uploads by setting the storage size of each user's directory to `0` in the `[files]` section of `config.inc.php`. + +``` +public_user_dir_size = 0 +``` + +The [controlPublicFiles](https://github.com/pkp/controlPublicFiles) plugin includes more fine-grained control over user uploads. + +## Single Sign-on + +Single sign-on allows users to register and login to your journal, press or preprint server using an account with another service. This may be an institutional account such as a university network, a scholarly infrastructure organization like ORCID, or a commercial service provider like Google, Microsoft or Apple. + +The following are different approaches to single sign-on that are in use by our community. + +### OpenID + +The [openid plugin](https://github.com/leibniz-psychology/openid) allows users to register and login using any [OpenID](https://en.wikipedia.org/wiki/OpenID) protocol. This protocol is supported by ORCID, Google, Microsoft, Apple and many others. + +The Leibniz Institute for Psychology (ZPID) has developed this plugin. + +### ORCID + +Users can register and login using their ORCID accounts. Use the [openid plugin](https://github.com/leibniz-psychology/openid). + +### Shibboleth + +[Shibboleth](http://shibboleth.internet2.edu/) offers account synchronization and single sign-on. The source code and binary of the service provider is available for all major operating systems. Read the documentation on their website to learn how to install and run the Shibboleth Service Provider. + +Once Shibboleth is set up on your system, install the [Shibboleth plugin](https://github.com/pkp/shibboleth) for OJS, OMP and OPS. Then visit the plugin's settings page for instructions on how to configure it. + +## Import/Export + +Learn how to import or export data about user accounts in the [Import/Export](./data-import-and-export) section. + +--- + +The next section describes best practices for running lots of independent journals, presses or preprint servers from one [multi-tenant install](./deploy-multi-tenant). \ No newline at end of file diff --git a/admin-guide/3.4/en/deploy.md b/admin-guide/3.4/en/deploy.md new file mode 100644 index 000000000000..71fe1d71b7a5 --- /dev/null +++ b/admin-guide/3.4/en/deploy.md @@ -0,0 +1,174 @@ +--- +title: Deployment Guide for OJS, OMP and OPS - Admin Guide - PKP Developer Docs +description: How to configure OJS, OMP and OPS and safely deploy these applications in a production environment. +book: admin-guide +version: 3.4 +--- + +# Deployment + +> Read the [Getting Started](./getting-started) guide first to learn how to download and install the software. +{:.notice} + +In a production environment, the software needs to be configured to send email, keep uploaded files private, and run regularly scheduled tasks. This guide describes the most important configuration steps that need to be taken before running a live, public instance of the software. + +## What you need to know + +In order to run this software securely, you will need to understand how to do the following: + +- Upload and edit files on your web server +- Modify file permissions on your web server +- Configure a cron job on your web server +- Manage file storage and memory limits on your web server +- Configure a SSL certificate for your domain + +If you are unfamiliar with some of these topics, you may be able to learn by following tutorials on the web. However, if you do not know how to deploy applications to a web server, we recommend that you find technical support for your project. This may be available through your research institution, a library publishing service, or a paid service provider like PKP's [Publishing Services](https://pkp.sfu.ca/hosting). + +## Configuration + +> The steps below describe how to use the command line to modify the files from a release package on a Linux web server. If you are not sure how to do this, or you run in a different environment, you may need to adapt the instructions to your server environment. We recommend speaking to your web hosting provider if you are not sure. +{:.notice} + +The configuration file is found in the root directory of the application. For example, if you installed the software to the directory `/var/www`, the configuration file would be located at `/var/www/config.inc.php`. + +Some of the settings in this file, like the database connection, are set during the installation process (see [Getting Started](./getting-started)). However, you will need to edit the file directly to configure other settings. + +Open the config file, find the `base_url` setting and change it to the web address of your install. + +``` +base_url = "" +``` + +Add this domain to your `allowed_hosts` list. + +``` +allowed_hosts = '[""]' +``` + +Two secret keys need to be set in order to safely encrypt secure tokens on your server. You can use the following command to generate a random key in most Linux and Mac environments. + +```bash +openssl rand -base64 32 +``` + +Use the string created by this command to set the `salt` and `api_key_secret` values in `config.inc.php`. Each config setting should have a different value. + +(We have not provided an example, because copying the example could compromise your site's security.) + +Set the `require_validation` in order to require new users to validate their email addresses before using a new account. + +``` +require_validation = On +``` + +## Secure Files Directory + +Every installation needs to have a secure files directory to ensure that private files, like unpublished submissions, can not be accessed by unauthorized users. + +The directory must be outside of the web root. This is the root directory that someone accesses when they visit your domain name. For example, if you installed the application to `/var/www`, the files directory should not be in `/var/www`. + +Check the `files_dir` setting in the `config.inc.php` file. If it is within the web root, create a directory outside of the web root and modify the configuration file to point to this directory. + +``` +files_dir = +``` + +## Email Server + +Most email will be blocked by spam filters unless you use a SMTP server with correctly configured [SPF](https://en.wikipedia.org/wiki/Sender_Policy_Framework) and [DMARC](https://en.wikipedia.org/wiki/DMARC) records. + +> Not sure what to do here? Learn more about how to [configure an email server](./deploy-email). +{:.notice} + +Turn SMTP on: + +``` +default = smtp +``` + +Set the SMTP settings for your email server. + +``` +smtp = On +smtp_server = # Domain of the SMTP server's domain. +smtp_port = # Port of the SMTP server, eg - 1025 +smtp_auth = # Authentication protocal. Usually ssl or tls +smtp_username = # Username for the SMTP server. +smtp_password = # Password for the SMTP server. +``` + +Set the envelope sender to an email address controlled by the `base_url`. For example, if your application is run at `https://my-site.com` you should use an email address like `journals@mysite.com`. + +``` +allow_envelope_sender = On +default_envelope_sender = # The email address of the envelope sender +force_default_envelope_sender = On +force_dmarc_compliant_from = On +``` + +Learn more about the [envelope sender](./deploy-email#dmarc). + +## User Validation + +Automated bots may register fake user accounts. To deter this, configure the software to require validation of the email address for all new user accounts. In the `[email]` section of `config.inc.php`, edit the following settings. + +``` +require_validation = On +validation_timeout = 14 +``` + +## SSL / HTTPS + +Every site should encrypt it's web traffic using a SSL certificate. This will make your site run from `https://` instead of `http://`. If you don't have a SSL certificate, you should [get one](./securing-your-system#sslencryption). + +Edit the `config.inc.php` file to force URLs to use SSL: + +``` +force_ssl = On +``` + +## Scheduled Tasks + +The software must run some tasks every day, such as compiling usage statistics. You should set up a cron job to run the following command once a day. + +``` +php tools/runScheduledTasks.php +``` + +If you are unable to configure this cron job, you must enable the Acron plugin after you have installed the software. + +## Job Runner + +No configuration is required to enable the built-in job runner. This is useful for test installations and small sites. However, in production we recommend using a worker daemon or cron job to process jobs. + +Learn more about how to configure the [job runner](./deploy-jobs). + +## Pretty URLs + +Enable URL rewriting on your server in order to drop the `index.php` from URLs. For example, instead of `https://example.org/index.php/publicknowledge`, the URL will be `https://example.org/publicknowledge`. + +The following is an example `.htaccess` file that can be used to enable `mod_rewrite` for Apache servers. This file should be placed in the web root. + +``` + + RewriteEngine On + RewriteBase / + RewriteRule ^api/v1(.*)$ /index.php/api/v1$1 [L,R=307] + RewriteCond %{REQUEST_FILENAME} !-f + RewriteRule ^(.*)$ /index.php/$1 [QSA,L] + +``` + +Then edit the `config.inc.php` file to turn on `restful_urls`. + +``` +restful_urls = On +``` + +## Other Settings + +The configuration file includes settings to control the default date formats, manage HTTP proxies, and more. Please read the `config.inc.php` file for an explanation of every setting. + +--- + +You've now configured all of the critical application functions. Next, you can learn how to conifigure your [email server](./deploy-email) to reliably deliver email. \ No newline at end of file diff --git a/admin-guide/3.4/en/download.md b/admin-guide/3.4/en/download.md new file mode 100644 index 000000000000..56e1f89b22f8 --- /dev/null +++ b/admin-guide/3.4/en/download.md @@ -0,0 +1,58 @@ +--- +title: Download - Admin Guide - PKP Developer Docs +description: How to download Open Journal Systems (OJS), Open Monograph Press (OPS) or Open Preprint Systems (OPS). +book: admin-guide +version: 3.4 +--- + +# Download + +You can download the latest stable release package (`.tar.gz`) — and all of our releases — from the PKP website. Download [OJS](https://pkp.sfu.ca/software/ojs/download), [OMP](https://pkp.sfu.ca/software/omp/download), or [OPS](https://pkp.sfu.ca/software/ops/download). + +## Upload Files + +> The steps below describe how to use the command line to upload the files to a Linux web server, but you can also use git or FTP. You can learn more about [how to use git](/dev/documentation/en/getting-started) in our technical documentation for contributors. +{:.notice} + +Upload the release package to your web server using `scp`. + +```bash +# The path to the release package on your local system +# Your username on the server +# The server's hostname, eg - myjournal.com + +scp @:~ +``` + +Or login to your server and download the file directly from PKP. + +```bash +# The URL to the release package, eg - https://pkp.sfu.ca/ojs/download/ojs-1.2.3-4.tar.gz +# Your username on the server +# The server's hostname, eg - myjournal.com + +ssh @ +wget +``` + +Login to your server and unpack the release package into the root web directory. + +```bash +# The path to the release package on your server +# The path to the web root on your server, eg - www/public_html + +tar -xvf --strip-components=1 -C +``` + +Change the file permissions of the following files and directories to allow them to be written by the web server. + +```bash +/config.inc.php +/public +/cache +/plugins +``` + +--- + +Next, set database credentials and other [configuration settings](./deploy). \ No newline at end of file diff --git a/admin-guide/3.4/en/getting-started.md b/admin-guide/3.4/en/getting-started.md new file mode 100644 index 000000000000..1000b4e7481d --- /dev/null +++ b/admin-guide/3.4/en/getting-started.md @@ -0,0 +1,89 @@ +--- +title: Getting Started with OJS, OMP or OPS - Admin Guide - PKP Developer Docs +description: A quick-start guide to install OJS, OMP or OPS in a test environment. +book: admin-guide +version: 3.4 +--- + +# Getting Started + +This is a quick-start guide to install and run OJS, OMP or OPS in a local test environment. Use this guide to try out the software on your own or to install it to a private, test environment. Before hosting the installation on a public server, you should read the [Deployment](./deploy) guide to learn how to safely configure the application. + +## System Requirements + +Your server — or your local development environment — must meet the following requirements in order to run the 3.4 release of OJS, OMP or OPS. + +- [PHP 8.0+](http://www.php.net/) with php-mbstring, php-xml, and php-intl enabled +- [MySQL 5.7.22+](http://www.mysql.com/), [MariaDB 4.1+](https://mariadb.org/) or [PostgreSQL 9.5+](http://www.postgresql.org/) +- Linux, or one of the following: BSD, Solaris, Mac OS X, Windows + +> **Older Versions**: Check the README.md file located in the download package of the version you want to install. + +## Download + +Download the latest stable release package (`.tar.gz`) from the PKP website. + +- [Open Journal Systems](https://pkp.sfu.ca/software/ojs/download) (OJS) +- [Open Monograph Press](https://pkp.sfu.ca/software/omp/download) (OMP) +- [Open Preprint Systems](https://pkp.sfu.ca/software/ops/download) (OPS) + +Use the `tar` command, or any archive software on your system, to unpack the `.tar.gz` file to a local directory. For example, if you downloaded the OJS 3.4.0 release package, you can use the following command to unpack the file. + +``` +tar -xvf ojs-3.4.0.tar.gz +``` + +This will create a directory for the software at `ojs-3.4.0`. Create another directory for file uploads. + +``` +mkdir ojs-files +``` + +> ⚠️ This creates the file uploads directory in which submission files are stored. When deploying the software to a public web server, make sure this directory is **not web-accessible** e.g. by placing it outside the web root. See the [Deployment](./deploy) guide for information on installing the application safely on a public web server. +{:.warning} + +Start PHP's built-in server from the release package's root directory. + +``` +cd ojs-3.4.0 +php -S localhost:8000 +``` + +## Install + +Open your browser and navigate to the installation page at the following URL. + +``` +http://localhost:8000 +``` + +You should see an installation screen like the one below. + + +![Screenshot of the installation screen of OJS](./assets/install-start.png) + +Complete the form to finish the installation, using the file uploads directory that you created. It may take a minute to install. You should see the following success screen when it is finished. + +![Screenshot of the install complete screen of OJS](./assets/install-complete.png) + +Once you have finished the install, login with the administrator account you set up to access the admin area. Depending on whether you installed OJS, OMP or OPS, you will be taken to a screen where you can create your first journal, press or preprint server. + +- In OJS, click the **Add Journal** button. +- In OMP, click the **Add Press** button. +- In OPS, click the **Add Server** button. + +Once you have created your first journal, press, or preprint server, you will be taken to it's Settings Wizard. + +![Screenshot of the settings wizard screen for a new journal](./assets/settings-wizard.png) + +Click the **Users** tab to create a new user for the Journal Manager, Press Manager, or Server Manager who will be responsible for managing the journal, press or preprint server. + +And you're done! You've successfully installed the software and created a manager user account. Login as the manager to explore the software as it will appear to the managing user of the journal, press or preprint server. This is usually a managing editor, an editor-in-chief, or a publishing assistant responsible for the day-to-day running of the journal. Or you can stay logged in as the administrator to see all of the features available to you as an admin. + +To explore the software further, click the small icon at the top to switch to your new journal, press or preprint server. + +![Screenshot of the journal switcher in OJS](./assets/settings-wizard-context-switcher.png) + +--- + +Congratulations! The software is now installed and you can begin testing it out. In a real environment, you will need to ensure your install is configured correctly and secured properly. Learn how to [deploy the software](./deploy). diff --git a/admin-guide/3.4/en/index.md b/admin-guide/3.4/en/index.md new file mode 100644 index 000000000000..0018d204f3db --- /dev/null +++ b/admin-guide/3.4/en/index.md @@ -0,0 +1,20 @@ +--- +title: Admin Guide for OJS, OMP and OPS - PKP Developer Docs +description: A guide for system administrators who want to install, deploy and maintain Open Journal Systems (OJS), Open Monograph Press (OMP) or Open Preprint Systems (OPS). +book: admin-guide +version: 3.4 +--- + +# Administrator's Guide + +This is a guide for system administrators who want to install, deploy and maintain [Open Journal Systems (OJS)](https://pkp.sfu.ca/software/ojs), [Open Monograph Press (OMP)](https://pkp.sfu.ca/software/omp) or [Open Preprint Systems (OPS)](https://pkp.sfu.ca/software/ops). It covers everything from getting started with your first test install to optimizing large production instances and importing and exporting data. + +- [Getting Started](./getting-started) — A quick-start guide to install the software locally or in a test server. Use this if you want to try out the software. +- [Deployment](./deploy) — Detailed instructions to configure the software correctly and run it securely in a production environment. Use this before you run a live instance of the software. +- [Import/Export](./data-import-and-export) — An overview of the options available to import and export data. Read this if you need to import a back catalogue or transfer data from or to another scholarly publishing system. +- [Security](./securing-your-system) — Best practices for running a secure server. Read this if you're not confident about securing your server. +- [Statistics](./statistics) — An overview of the statistics available in the system. Read this if you need to compile reports about readers, registered users, editorial activity or subscriptions. + +--- + +Ready to [get started](./getting-started)? diff --git a/admin-guide/3.4/en/securing-your-system.md b/admin-guide/3.4/en/securing-your-system.md new file mode 100644 index 000000000000..ecf6680c2aec --- /dev/null +++ b/admin-guide/3.4/en/securing-your-system.md @@ -0,0 +1,74 @@ +--- +title: Secure your System - Admin Guide - PKP Developer Docs +description: Best practices to set up a secure server when running OJS, OMP or OPS. +book: admin-guide +version: 3.4 +--- + +# Securing Your System + +> This section describes how to run a secure server. Before reading this section, make sure you have followed the [recommended configuration](./deploy) instructions to secure the application. +{:.warning} + +It's important to run OJS, OMP and OPS on a secure server environment. In addition to the security settings in the [recommended configuration](./deploy) of the application, you must ensure the server is secure where the application is run. + +This section makes a few recommendations for running secure servers. However, if you are unfamiliar with server administration, we strongly encourage you to use a professional hosting service or hire a professional system administrator. + +## Security Checklist + +- Follow the [recommended configuration](./deploy) instructions. +- Follow additional configuration recommendations to [reduce spam accounts](./deploy-users). +- Use a long, random value for each one of the `salt` and `api_secret_key` settings in `config.inc.php`. +- Make sure the `encryption` setting in `config.inc.php` is set to `sha1`. +- Restrict [file permissions](#file-permissions) as much as possible. +- Set up a [SSL certificate](#sslencryption) and configure the application to use `https://`. +- Make sure the `files_dir` folder [can not be accessed through the web](#file-permissions). +- Dedicate a database to the application. Do not share it with other applications on the server. +- Run antivirus software on the server to prevent users from uploading a compromised file. +- Configure your server to make automated backups of the database and `files_dir` at regular intervals. We recommend a backup for every day in the last 7 days, one per week for the last 4 weeks, and one per month for the last 12 months. View the [upgrade guide](/dev/upgrade-guide/en/) for more complete backup instructions. +- Keep the web server regularly updated with all security patches. +- Practice good password management: don’t use the same username/password to access the application as you would for any other online account, and don’t use an easy to guess password. +- Treat everything that you get online with the knowledge that you received it from someone you don’t know, and act likewise. If a submission appears to be suspicious for any reason (strange email address, suspiciously generic title or abstract, etc.), treat the included files with an additional level of diligence. + +## File Permissions + +The `files_dir` is where all private submission files are stored. If this directory is located in the web root, anyone will be able to download submission files. Once you have configured the `files_dir` outside of the web root, lock down access to that directory by setting the read/write permissions so that only the application can read, add, edit and delete files. + +The exact details of file permissions will depend on how your web server runs PHP scripts. Read more about [file permissions](./troubleshooting#configuring-file-permissions) + +## SSL/Encryption + +All web applications should be protected with SSL/TLS encryption, so that they can encrypt traffic through the server. Without encryption, user login credentials are passed in plain text, which allows anyone scanning the network to intercept them. + +The following section describes how to get a SSL certificate, enable it, and configure the server to update it. + +### Getting a Certificate + +A certificate enables a secure connection from the user's Web browser to the server hosting your site. Installing a certificate for your site can not be done within the OJS, OMP, or OPS software and will require technical expertise or assistance at the server level. When considering a software host, determining their level of certificate support is an important consideration. + +A good start is asking your hosting service provider if they have an existing solution for supporting TLS or SSL certificates -- Your hosting provider may be able to create/issue an TLS or SSL certificate for you. If you do not have shell access to your installation this may be the only way to go about adding SSL/TLS protection for your site. + +Purchasing a certificate may be an option available to you as well. Commercial businesses that provide certificates are called [Certificate Authorities](https://en.wikipedia.org/wiki/Certificate_authority) (CA). Wikipedia provides a listing of [CA providers](https://en.wikipedia.org/wiki/Certificate_authority#Providers) by market share. In addition to providing certificates that enable encryption, traditional CA issued certificates offer several advantages including customer vetting to help validate customer identity, and wildcard certificates. Depending on what features you select with your purchase, CA issued certificates can cost $100s per year and must be renewed before expiry. + +[Let’s Encrypt](https://letsencrypt.org/) is a popular option for obtaining subscription as well. Let’s Encrypt is a free, automated, and open certificate authority (CA), run for the public’s benefit. It is a service provided by the Internet Security Research Group (ISRG). Certificates are provided for free, with some limitations: + +* Only DV (Domain Validation) certificates are offered +* Slightly more technical, if your hosting provider does not already support you will need to generate from shell + +To test that your certificate is installed correctly, go to https://www.ssllabs.com/ssltest/index.html and enter your host name. If your grade is "B" or worse, your server may not be available to secure client software. + +### Enabling SSL (requires shell access): + +#### Generating CSR (Certificate Signing Request) + +Required step to generate a certificate if you are going to be purchasing a certificate from a CA that is not Let’s Encrypt. In terms of how to do this, this varies from one Linux distribution to the next, some common Linux examples can be found here: +* [Ubuntu](https://www.digitalocean.com/community/tutorials/how-to-create-a-ssl-certificate-on-apache-for-ubuntu-14-04) +* [CentOS/RHEL 7](https://www.digitalocean.com/community/tutorials/how-to-secure-apache-with-let-s-encrypt-on-centos-7) +* [Generating LetsEncrypt certificate using Certbot via Shell](https://certbot.eff.org/) (provides customized directions depending on hosting environment Apache, Nginx, etc.) +* [Guide to generating a .CSR in Apache](https://www.alphassl.com/support/create-csr/apache.html) + +#### Maintaining your Certificates + +When you purchase a certificate from a CA, you will typically purchase a certificate that lasts between 1 to 3 years. Certificates are set to expire and will need to be renewed resulting in a new expense at the time of renewal. Let’s Encrypt certificates expire every 90 days. The Let’s Encrypt software (certbot) can be configured to automatically renew certificates before they expire. Meaning once installed you should have minimal maintenance moving forward. Automation is done with `cron` or `systemd`. + +> Contributors: PKP staff, Kenton Good diff --git a/admin-guide/3.4/en/statistics.md b/admin-guide/3.4/en/statistics.md new file mode 100644 index 000000000000..ab3870fa2b8f --- /dev/null +++ b/admin-guide/3.4/en/statistics.md @@ -0,0 +1,288 @@ +--- +title: Statistics - Admin Guide - PKP Developer Docs +description: How to collect, process, restore and export usage statistics in OJS, OMP or OPS. +book: admin-guide +version: 3.4 +--- + +# Statistics + +Each application provides statistics for the number of times a visitor views and downloads content on the website. As an administrator, you can configure what stats are collected, how the data is compiled into daily or monthly totals, and whether or not to make some statistics publicly available. + +Requests to view and download files from the public website are recorded in a log file. This file is compiled into statistics on a daily basis. The application will try to filter out bots and double-clicks. Depending on the size and age of your site, the metrics tables in your database may consume a lot of disk space. You can reduce the size of these tables by configuring the application to only keep monthly data, and to record little or no geographic data. + +Read the sections below to learn how to configure the statistics for your site, how to view and download stats, and how to recover lost data. + +## Settings + +> To ensure that statistics are collected correctly, make sure you have [configured your application](./deploy) to run scheduled tasks and jobs. +{:.notice} + +As an administrator, you can restrict the type of statistics that will be collected. You may choose to do this to protect the privacy of visitors, comply with legal requirements in your jurisdiction, or reduce the disk space required for your database. + +Follow the steps below to set the statistics settings for all journals, presses or preprint servers on your site. + +1. Login as an administrator. +2. Go to **Administration**. +3. Go to **Site Management** > **Site Settings**. +4. Go to **Site Setup** > **Statistics**. + +A manager may configure some of these settings differently for each journal, press or preprint server they manage. In such cases, the site settings act as a "ceiling". For example, if the site has disabled geographic statistics, the manager will not be able to enable them for their journal, press or preprint server. If the site has enabled country-level statistics only, the manager will not be able to enable region and city statistics. + +However, the manager can turn off statistics even if the site has disabled them. For example, if the site has enabled geographic statistics for country, region and city, the manager will be able to turn geographic statistics off, or choose to collect only country and region data. + +## Download + +Statistics are collected for different kinds of data and can be accessed in several different formats. Some statistics can be viewed as tables and graphs in the application. Others can only be viewed by downloading a report in CSV or JSON. The CSV format can be opened in spreadsheet software, like Excel or LibreOffice Calc. + +| Type | Description | Web | CSV | JSON | +| ----------------------------------------- | -------------------------------------------------------------------------------------- | --- | --- | ---- | +| [Publications](#publications) | Views and downloads of articles, books and preprints, and their files. | ✔ | ✔ | ✔ | +| [Issues](#issues) | Views and downloads (OJS) | ✔ | ✔ | ✔ | +| [Homepage](#homepage) | Views of the homepage of the journal, press or preprint server. | ✔ | ✔ | ✔ | +| [Geography](#geography) | Views by country, region and city | ✔ | ✔ | ✔ | +| [COUNTER](#counter) | An industry-recognized format for distributing usage statistics. | ✘ | ✘ | ✔ | +| [Editorial Activity](#editorial-activity) | Number of submissions accepted and rejected, the average time to a decision, and more. | ✔ | ✘ | ✘ | +| [Users](#user) | User profiles and roles. | ✘ | ✔ | ✘ | +| [Reviews](#reviews) | Reviewer names, due dates, and comments for all review assignments | ✘ | ✔ | ✘ | +| [Submissions](#submissions) | Titles and metadata for all submissions | ✘ | ✔ | ✘ | +| [Subscriptions](#subscriptions) | Data on subscriptions (OJS) | ✘ | ✔ | ✘ | + +### Publications + +Follow these steps to get the number of views and downloads of articles, books and preprints, as well as their files. + +1. Login as an administrator or manager. +2. Click **Statistics** > **Articles** (or Books in OMP and Preprints in OPS). +3. Use the web interface to filter the statistics by date. In OJS you can filter by section and issue. +4. Click **Download Report** to download a report in CSV format. +5. Choose the type of report to download. + +Publication statistics can also be accessed in JSON format through the [REST API](/dev/api/). + +### Issues + +> This is only available in OJS. +{:.notice} + +Follow these steps to get the number of views and downloads of issues and issue galley files. + +1. Login as an administrator or manager. +2. Click **Statistics** > **Issues**. +3. Use the web interface to filter the statistics by date. +4. Click **Download Report** to download a report in CSV format. +5. Choose the type of report to download. + +Issue statistics can also be accessed in JSON format through the [REST API](/dev/api/). + +### Homepage + +Follow these steps to get the number of views of the homepage of the journal, press or preprint server. + +1. Login as an administrator or manager. +2. Click **Statistics** > **Journals** (or Presses in OMP and Servers in OPS). +3. Use the web interface to filter the statistics by date. +4. Click **Download Report** to download a report in CSV format. +5. Choose the type of report to download. + +Homepage statistics can also be accessed in JSON format through the [REST API](/dev/api/). + +### Geography + +> You must [enable geographic statistics](#settings) first. +{:.notice} + +Follow these steps to download a CSV file with the number of views and downloads for each city, region and country. + +1. Login as an administrator or manager. +2. Click **Statistics** > **Articles** (or Books in OMP and Preprints in OPS). +3. Use the web interface to filter the statistics by date. In OJS you can filter by section and issue. +4. Click **Download Report**. +5. Click **Download Geographic**. + +Geographic statistics can also be accessed in JSON format through the [REST API](/dev/api/). + +### COUNTER + +[COUNTER](https://www.projectcounter.org/) sets standards for our how usage statistics should be calculated and distributed. Statistics matching the [COUNTER 5 SUSHI](https://www.projectcounter.org/counter-sushi/) protocol can be downloaded through the [REST API](/dev/api). Statistics matching the [COUNTER 4](https://www.projectcounter.org/code-of-practice-sections/archived-code-of-practice-release-4/) protocol (Journal Report 1 and Article Report 1) can be downloaded by following these steps. + +1. Login as an administrator or manager. +2. Click **Statistics** > **Reports**. +3. Click **COUNTER Reports**. + +### Editorial Activity + +> Editorial statistics can change significantly depending on the selected date range. Read the recommendations below to avoid these pitfalls. +{:.warning} + +Follow these steps to view stats about the editorial activity of a journal, press or preprint server, such as the number of submissions accepted and rejected, the average time it takes to record a decision, and more. + +1. Login as an administrator or manager. +2. Click **Statistics** > **Editorial Activity**. +3. User the web interface to filter statistics by date. In OJS you can filter by section. + +These stats are based on editorial activity recorded by the system. If your editors routinely work outside of the system, stats may not be correct. For example, if an editor asks for a review by email and does not record it in the system, that review will not be counted in the editorial statistics. + +When selecting a date range, think carefully about the editoral activity you are interested in. For example, if you are looking at the last three months, the Acceptance Rate will be calculated only from submissions submitted in the last three months that have already received an accepted or declined decision. We recommend using a date range that accounts for the duration of your editorial review and ends at least 12 months ago. + +### Users + +Follow these steps to download a CSV report with the user profiles and their roles in each journal, press or preprint server. + +1. Login as an administrator or manager. +2. Click **Statistics** > **Users**. +3. Click **Export**. +4. Select the user groups you want to export +5. Click **Export**. + +There are other ways to [export user data](./data-import-and-export#users). + +### Reviews + +Follow these steps to download a CSV report about review assignments that includes the reviewer names, due dates, comments, and more. + +1. Login as an administrator or manager. +2. Click **Statistics** > **Reports**. +3. Click **Review Report**. + +### Submissions + +Follow these steps to download a CSV report about submissions that includes the titles, contributors and metadata. + +1. Login as an administrator or manager. +2. Click **Statistics** > **Reports**. +3. Click **Articles Report** (or Books Report in OMP and Preprints Report in OPS). + +There are many other ways to [export submission data](./data-import-and-export). + +### Subscriptions + +> The subscriptions report is only available in OJS when subscriptions are enabled. +{:.notice} + +Follow these steps to download a CSV report about subscriptions that includes the titles, contributors and metadata. + +1. Login as an administrator or manager. +2. Click **Statistics** > **Reports**. +3. Click **Subscriptions Report**. + +## Recover Lost Data + +> If the system is not recording any statistics, the application may not be configured correctly. Read the [configuration advice](#settings). +{:.notice} + +You may notice historical gaps in your statistics data. These can arise for several reasons. Often it is because the application was misconfigured, the server resources were limited, or an application error prevented the logs from being processed. This can leave historical gaps in statistics data if the problem goes unnoticed for a while. When this happens, it can be difficult to restore the data. But it may be possible. + +In order to recover the data, you will need to have log files that cover that period. These may be the application's [stats logs](/dev/documentation/en/statistics#understanding-the-log-files) or the Apache access log files. + +The sections below provide information to help you determine what log files are available and reprocess them to compile statistics. + +### Prepare the Log Files + +> You must [understand the log files](/dev/documentation/en/statistics.md#understanding-the-log-files) before continuing. +{:.notice} + +Before processing the logs, they must be in the format recognized by the application. A log file will typically have hundreds or thousands of lines in JSON format, like the one below. + +```json +{"time":"2023-02-27 11:41:14","ip":"87d8edf8ca58ab4d3e9421b03edcd9c5a2093a79c341964179b8e379faabd324","userAgent":"Mozilla\/5.0 (X11; Ubuntu; Linux x86_64; rv:109.0) Gecko\/20100101 Firefox\/110.0","canonicalUrl":"https:\/\/example.org\/publicknowledge\/index","assocType":256,"contextId":1,"submissionId":null,"representationId":null,"submissionFileId":null,"fileType":null,"country":null,"region":null,"city":null,"institutionIds":[],"version":"3.4.0.0","issueId":null,"issueGalleyId":null} +``` + +#### Using logs from older versions + +If your log file looks like the one below, it is a log file from an older version of the application. + +``` +127.0.0.1 bot 1 "2023-03-01 11:52:47" http://localhost/index.php/publicknowledge/index 200 "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) HeadlessChrome/110.0.5481.100 Safari/537.36" +``` + +To convert this log file to the correct format, move the log file into the `archive` directory and run the following command from the root directory of your application. + +``` +php lib/pkp/tools/convertUsageStatsLogFile.php +``` + +After conversion, the old log file will be renamed `_old.log`. For example, if the file was `usage_event_20230202.log`, the old log file will be named `usage_event_20230202_old.log`. + +#### Using Apache access logs + +If you use the [Apache](https://en.wikipedia.org/wiki/Apache_HTTP_Server) web server, you may have access logs from the period covering the historical gaps in your stats data. Run the following command to generate logs in the correct format. + +``` +php lib/pkp/tools/convertApacheAccessLogFile.php +``` + +A log file named `apache_usage_events_YYYYMMDD.log` will be created in the `archive` directory for each day with one or more log entries from that file. If several log files are created for the same day, you may need to manually combine them into one file. + +The command must be run by a user who has permission to read the Apache log files on the server. If you face any problems using this script, you may need to open `lib/pkp/tools/convertApacheAccessLogFile.php` and set the following variables to match your server configuration: `EGREP_PATH`, `PARSEREGEX`, `PHP_DATETIME_FORMAT`, `PHP_DATE_FORMAT`. + +### Reprocess Log Files + +Once you have identified the log files you want to reprocess, move them into the `stage` directory. Then run the following command, once for every month you want to reprocess. + +``` +php lib/pkp/tools/reprocessUsageStatsMonth.php YYYYMM +``` + +For example, if I had log files for 2022-10-01 to 2022-11-30, I would run the command twice: + +``` +php lib/pkp/tools/reprocessUsageStatsMonth.php 202210 +php lib/pkp/tools/reprocessUsageStatsMonth.php 202211 +``` + +If you want to have accurate monthly statistics, you will need to reprocess a whole month at a time. For example, if you are missing statistics from 2022-10-15 to 2022-11-12, you would need to reprocess logs for every day of both months in order to have accurate monthly stats for those months. + +### Things to know + +Keep the following in mind when working with the log files. + +- Never change the log file names. The system assumes they are called `usage_events_YYYYMMDD.log` or `apache_usage_events_YYYYMMDD.log`. +- If you run the application with `disable_path_info` set to `On` in `config.inc.php`, change the `PATH_INFO_DISABLED` variable to `true` in the log conversion scripts before running the commands. +- Any log files for the current month in the `stage` directory will be processed automatically. Do not move files in there unless you want them processed. + +## Frequently Asked Questions + +### I don't see any statistics + +Statistics are compiled once a day. No statistics will appear until 24 hours after a visitor has been logged. If you have visited the homepage of your journal, press or preprint server, waited more than 24 hours and still do not see those statistics, you may need to [configure scheduled tasks and jobs](./deploy). + +You can tell if the scheduled task is being run by looking in the log directory at `/usageStats`. Once a log file has been processed, it will be moved to the `archive` directory. Learn more about the [log files](/dev/documentation/en/statistics#understanding-the-log-files). + +If you see log files in the archive, but still do not have any statistics, inspect the URLs in the log entries. Does the URL in the log files exactly match the `base_url` in my configuration? Does it point to a published submission in a journal, press or preprint server? + +### I have enabled geographic statistics, but the geographic report doesn't include any data + +The application uses the visitor's IP address to determine their location. In order for this to work, the application must have a copy of the database that maps IPs to their location. This file will be located in `/usageStats/IPGeoDB.mmdb`. If you have properly [configured](./deploy) the application to run scheduled tasks, this will be updated monthly. + +### I upgraded from an old version of OJS and I want to have stats from a long time ago + +If you have been running the application for many years, you may have periods during which no stats were recorded. For example in versions of OJS 2. You may be able to recover these stats if you have the Apache access logs from this period. Read how to [convert log files](#recover-lost-data). + +### I’ve seen some OJS journals that display nice-looking article usage metrics on article landing pages. How do I configure that? + +This is a theme option. If you theme supports it, you can enable it at **Settings** > **Website** > **Appearance** > **Theme**. + +### If I replace a publication's file, will the download count reset to 0? + +The application collects statistics based on the IDs of these files. If you change the file without deleting the galley (OJS, OPS), the download counts will not be effected. However, if you delete the galley and upload the file to a new galley, the download counts will be effected. + +This will not effect the publication's overall download counts. It will only be reflected in the submission file itself, when download counts for each file are distinguished in the downloadable reports. + +### I’ve upgraded from a very old version (2.x) and now my usage stats seem to have gone down. They haven’t disappeared entirely, but they seem to trend lower. What’s going on? + +Since 3.x, the application filters views as per the COUNTER Project code of conduct. Specifically, when someone views or downloads a file more than once in 30 seconds, the application only registers one view or download. Also, known bots and crawlers are filtered out. + +This will result in lower overall usage metrics. The drop shouldn’t be significant, though it can be noticeable. The COUNTER Project is always adding new bots to their specification, and the application updates this specification in each release. + +### I’ve generated a report, and it doesn’t contain any data besides column titles. + +What to do when you [don't see any stats](#i-dont-see-any-statistics). + +### When I try to download a report, I get a blank page, a 500 error, or a PHP memory limit error, such as "Memory limit exhausted". + +This happens when the amount of data you are trying to download exceeds the server’s capacity to deliver it. This can be resolved by trying to download a smaller data set, for example reducing the date range, or by increasing the server's resource (for example PHP's `memory_limit` or `max_execution_time`). + +### I need to reprocess some log files, or troubleshoot a rejected log file. + +See the section on [recovering lost data](#recover-lost-data) diff --git a/admin-guide/3.4/en/troubleshooting.md b/admin-guide/3.4/en/troubleshooting.md new file mode 100644 index 000000000000..39b40c6debea --- /dev/null +++ b/admin-guide/3.4/en/troubleshooting.md @@ -0,0 +1,284 @@ +--- +title: Troubleshooting - Admin Guide - PKP Developer Docs +description: How to fix some common problems encountered when deploying OJS, OMP or OPS. +book: admin-guide +version: 3.4 +--- + +# Troubleshooting + +## Permissions, File Access, Etc. + +### Configuring File Permissions + +It is difficult to prescribe exact steps towards setting proper file permissions, as so much depends on the server's operating system, web server, and PHP setup. + +In general, you want your permissions set such that your webserver can read and write (recursively) to the `config.inc.php` `files_dir`, and to `cache/`, and `public/`. Optionally, for added features and reduced security, you can enable write to `config.inc.php`, to `plugins/` and perhaps to the locale `.xml` files. Your webserver should have read-only access to all other files and directories distributed in the package. + +Start by checking which server API PHP uses on your server. If OJS, OMP, or OPS is already installed, log in as Site Administrator, click "System Information", and at the bottom of the page, click "Extended PHP Information". Find the line that says "Server API". Depending on which API you are using (mod_php/SAPI or CGI/FastCGI), permissions should be set as follows. + +* mod_php/SAPI: In this configuration, all PHP scripts on the system typically execute as the same user (usually Apache's "nobody" or "www-data" accounts). Be warned that this may be insecure on a shared host. The `files_dir` (set in `config.inc.php`), the cache directory, the public directory, and all contents and subdirectories must be writable and readable by the web server user. The `config.inc.php` configuration file must be readable by the web server user. +* CGI/FastCGI: In this configuration, PHP scripts will typically run under your user account (though server configurations may vary). This can be a well-secured configuration. The `files_dir`(set in `config.inc.php`), the cache directory, the public directory, and all contents and subdirectories must be writable and readable by this user account. The `config.inc.php` configuration file must be readable by this account. + +#### How does Linux do this? + +In Linux, permissions are based both on a numeric access control mode, and on file ownership 63. Understanding this permissions scheme is a prerequisite. + +For example, ownership of `apache:www` with permissions of `750` (`rwxr-x---`) means that the apache user can read, write and execute; anyone with the `www` group can read or execute; and the file is protected against access by anyone else. Note that “execute” means two entirely different things for directories than for files! + +##### An Example (for dedicated hosting) + +Generally, the ownership of `cache/`, `public/`, and other web-writable directories should be your web user and the web-user’s primary group, for example `apache:www-data`. Permissions should probably be `750`. + +The ownership of the other non-web-writable directories should be your user, with either the web user’s group, or with public execute permissions. For example: + +`myuser:www-data` with `750` + +or + +`myuser:ourgroup` with `755` + +Web-writable files would be the same, but without the execute permission: + +`apache:www-data` with `640` + +Non-web-writable files would be perhaps: + +`myuser:www-data` with `640` + +or + +`myuser:ourgroup` with `644` + +#### But What About Shared Hosts? + +With some shared hosts (for example, if your only access is via cPanel or a similar web-based admin tool), you may not have the ability to change the file ownership, and your webserver is effectively running as your user. In that case, you may still have the ability to protect your files by making them non-writable by your own user (even though this sounds counter-intuitive). In a shared host, you will almost certainly want to deny world permissions to your files, but look to the documentation and support for your host in particular. + +#### A Note on Security Configurations + +Because security configurations can vary, and because of the volume of requests for support we receive regarding file permissions, we will only be able to provide limited help with these issues. Please be as specific as possible when posting about permissions issues. + +PHP Safe Mode is not a recommended configuration and may not function properly. This is because in some configurations it will cause PHP's `mkdir()` function to create directories that cannot thereafter be read or written because of file permissions. This is a limitation of Safe Mode and may prevent you from using OJS in a Safe Mode environment. + +### HTML Galleys don't display properly / files I upload aren't being identified properly + +This is most likely caused by your server incorrectly identifying your HTML file as something other than HTML. The quickest way to diagnose this is to check the Galley Edit page: if you have uploaded an HTML file and the Label field says something other than "HTML" (like "Untitled", for example), then the file has not been correctly identified as HTML and will most likely not display correctly. + +OJS/OMP/OPS use three methods to determine a filetype, in the following order: + +* PHP's mime_content_type function, which uses your system's magic.mime file (this method is deprecated) +* PHP's finfo_... suite of functions (which replaces mime_content_type as the preferred method) +* The external "file" tool, by executing the following: + +`file -bi [filename here]` + +Problems may occur if: + +* you are using the first option but your magic.mime file does not include enough information on the filetype you are attempting to identify; +* your server configuration does not support the first two options; +* you do not have sufficient permissions to run an external tool as in the third option. + +Additionally, you may be encountering problems due to malformed files. If you are having trouble having your HTML files recognized, you may want to run them through [HTML-Tidy](http://www.w3.org/People/Raggett/tidy/) or otherwise ensure that they are valid HTML. HTML files created by word processors in particular may have a hard time being recognized as HTML. + +You may also want to search the [forum](https://forum.pkp.sfu.ca) for the keywords "magic mime" or for "mimetype" -- many users have had this problem, and there are several discussions on how to solve it. + +### My CSS files aren't being identified properly + +This could be the result of the identification issue above, or it could be because your css file includes a comment on the first line, before any actual CSS. Try removing the comment(s) from the top of the file and re-uploading. + +Note that this situation often occurs when uploading a modified copy of the main CSS file. We don't recommend this approach -- it's better to upload a CSS file that only contains overrides for the styles that you wish to modify from the default layout, as the main stylesheet is applied before any custom CSS files. This will help to avoid stylesheet headaches on upgrade. + +## Character Encoding + +Character encoding issues mostly crop up in two situations: when journals are migrated from another platform to OJS; or (more commonly) when an OJS journal is migrated from another server to our servers. + +It’s often helpful to check the current database settings to ensure that you’re working in the character set that you think you’re working with. Once logged into MySQL, try the following: + +``` +show variables like 'char%'; +show variables like 'collation%'; +``` + +The goal of fixing character encoding problems is to ensure that the data stored in the database matches the character set settings of the database, i.e. that we’re storing utf8 data in a utf8 database. Once this has been achieved, we want to ensure that the OJS `config.inc.php` settings match the data and db settings, i.e. client, connection, database character set settings are all set to utf8 in `config.inc.php`. + +### Introduction to Character Sets and Encodings + +The following articles provide a good introduction to character sets and encodings: + +* [Character Encodings: Essential Concepts](https://www.w3.org/International/articles/definitions-characters/) +* [The Absolute Minimum Every Software Developer Absolutely, Positively Must Know About Unicode and Character Sets (No Excuses!)](https://www.joelonsoftware.com/2003/10/08/the-absolute-minimum-every-software-developer-absolutely-positively-must-know-about-unicode-and-character-sets-no-excuses/) +* [The Ultimate Guide To UTF-8 and MySQL](https://jonisalonen.com/2012/ultimate-guide-to-utf8-and-mysql) +* [Breaking out from the MySQL character-set hell](https://manish-demblani.medium.com/breaking-out-from-the-mysql-character-set-hell-24c6a306e1e5) + +### General Approach + +* Check the `config.inc.php` database settings: client, connection, database character sets +* Compare the `config.inc.php` database settings against actual settings in the database, i.e. + * `show variables like 'char%'` + * `show variables like 'collation%'` +* There's often a mismatch between 1. and 2. that provides the first mismatch clues +* Generate two db dumps: + * `mysqldump db --opt --default-character-set=latin1 result-file=latin1.sql` + * `mysqldump db --opt --default-character-set=utf8 result-file=utf8.sql` +* Explore each dump file in vim using its character encoding tools: [https://spin.atomicobject.com/2011/06/21/character-encoding-tricks-for-vim/](https://spin.atomicobject.com/2011/06/21/character-encoding-tricks-for-vim/) + +#### Common Problem #1: Latin1 table definitions with UTF8 data + +During migration from another institution you may receive a MySQL dump that includes table definitions that are set to latin1 (i.e. `CREATE TABLE access_keys … DEFAULT CHARSET=latin1`) even though the actual data saved in the tables is UTF8. You can check the `config.inc.php` on the original server to confirm if this is the case: if `client_charset = utf-8` in `config.inc.php` then data will be stored as UTF-8 in the database. + +By default, journals on our servers are correctly configured to use UTF8 settings throughout the database and `config.inc.php`. Importing a mismatched database with Latin1 table definitions and UTF8 data will result in character display issues in OJS. + +The following conversion steps and import process can be used to resolve these issues: + +##### Conversion steps + +* ask for a latin1 mysql dump with `--default-character-encoding=latin1 --result-file=dump.latin1.sql` +* open `dump.latin.sql` in vim +* remove 'SET NAMES latin1' from the top of the file +* replace latin1 table definitions with utf8 table definitions via `:%s/CHARSET=latin1/CHARSET=utf8/g` +* set the file encoding for the file to utf8 via `:set fileencoding=utf-8` +* save the file to a new filename via `:w dump.utf8.sql` + +##### Import steps + +* create a clean utf8 database: `CREATE DATABASE import_ojs DEFAULT CHARSET utf8;` +* switch to the new db: `USE import_ojs` +* set everything to utf8: `SET NAMES utf8;` +* import the converted dump: `SOURCE dump.utf8.sql;` + +... and so on, replacing "article_settings" with the table you need to clean up, and "setting_value" with the column in the table needing cleanup. + +#### Common Problem #2: double-quotes with encoding issue on DUMP files + +During migration/upgrade from lib-ojs server to sfulib MySQL dump files from former may present encoding characters issue related to double-quotes, e.g.: “learning,â€<9d> which should be “learning,” even using correct UTF8 collation to export from Database. + +This problem shows up when users copy-and-paste fancy/smart quotes from MS Word which uses the windows-1252 character set that doesn't match with anything in UTF8. Which results in this sequences that look like “learning,â€<9d>. + +The following steps can be used to resolve this encoding issue: + +* Install on your local machine [ftfy](https://ftfy.readthedocs.io/en/latest/), as it is a python tool it will require python3 as well +* Edit the command-line ftfy executable cli.py (it may be in a different path depending on your environment.): + `/usr/local/lib/python3.6/site-packages/ftfy/cli.py` +* Around line 100 (`$ vim +100 cli.py`) add an extra parameter 'uncurl_quotes=False' to the fix_file function. It will then look as follows: + +```python +for line in fix_file(file, encoding=encoding, + fix_entities=fix_entities, + normalization=normalization, + uncurl_quotes=False): +``` + +* Download to you local machine the DUMP file (i.e: client.orig.sql) and you will be able to run: + `$ ftfy --output=client.clean.sql client.orig.sql` + +#### Manual Workarounds (Last Resort) + +If you are running into strange characters like †/ â€" / ’ / etc., try the following SQL commands to search and replace them (taken from this [blog post](https://digwp.com/2011/07/clean-up-weird-characters-in-database/)): + +``` +UPDATE article_settings SET setting_value = REPLACE(setting_value, '“', '"'); +UPDATE article_settings SET setting_value = REPLACE(setting_value, '†', '"'); +UPDATE article_settings SET setting_value = REPLACE(setting_value, '’', '''); +UPDATE article_settings SET setting_value = REPLACE(setting_value, '‘', '"'); +UPDATE article_settings SET setting_value = REPLACE(setting_value, 'â€"', '"“'); +UPDATE article_settings SET setting_value = REPLACE(setting_value, 'â€"', '"”'); +UPDATE article_settings SET setting_value = REPLACE(setting_value, '†¢', '-'); +UPDATE article_settings SET setting_value = REPLACE(setting_value, '†¦', '"¦'); +``` + +If all else fails: + +Kurt has run the following dump command with some success, but without explaining exactly what it does: + +``` +mysqldump ocs-$USERNAME --opt --default-character-set=latin1 --skip-set-charset --single-transaction --ignore-table=ocs-$USERNAME.paper_search_keyword_list --ignore-table=ocs-$USERNAME.paper_search_object_keywords --ignore-table=ocs-$USERNAME.paper_search_objects --result-file=/tmp/$USERNAME.sql +``` + +## Error-reporting: Blank Pages, Diagnostics, etc. + +### When I click some button or follow some link, I'm left with a blank page. What do I do? + +#### Check your webserver error log + +Usually, this indicates that a PHP error has occurred and the message has been sent to your web server or system log file. Check there – e.g. `/var/log/apache/error.log`, although the exact location will depend on your server configuration – for further details. + +#### Check your file permissions + +If you haven’t installed OJS, OMP, or OPS yet, then the most likely cause is a problem with file permissions in your `cache/` or `cache/t_compile` directories. See docs/README for information on file permissions. + +#### Further troubleshooting + +If you don’t have access to your server log file, you can try adding the following near the top of index.php to cause error messages to be sent to the browser: + +`ini_set('display_errors', E_ALL);` + +If you happen to be running in a Windows IIS environment, you may also have to enable `fastcgi.impersonate=1` in your php.ini file. + +You may also want to temporarily modify (approximately) line 27 of file `lib/pkp/includes/functions.inc.php`, removing the @ operator, so it would look like this: + +`if((include_once BASE_SYS_DIR.'/'.$filePath) === false) {` + +Remember to revert that change afterwards. + +Sometimes a specific PHP script included in the software will fail to execute without any error message, e.g. due to a broken modification or a file permissions problem. To determine which script might be causing the problem, you can edit your `lib/pkp/includes/functions.inc.php` and find the following line: + +`function import($class) {` + +Add below it: + +`echo "Importing " . $class . " \n";` + +This will cause OJS, OMP, or OPS to list class files before importing them (for ANY viewer of the site). If you are having a problem with a particular file, it will be the last one listed. Double-check the file permissions on it and try running it through the PHP linter (php -l path/to/file.inc.php). + +Be sure to revert this change when you are finished. + +### What is a stacktrace and how do I display them in OxS? + +A stacktrace shows the route through the code taken to display the current page. When an error is displayed, a stacktrace is often helpful in helping to track down how the error is being caused, by letting the developer step through the code and see what route they must take to reproduce the error. + +To enable stacktracing on errors in OxS, turn on the 'show_stacktrace' option in `config.inc.php`. An example stacktrace will look like this: + +``` +DB Error: ERROR: invalid input syntax for integer: "" +Stack Trace: +File: /var/www/ojs/classes/article/ArticleGalleyDAO.inc.php line 76 +Function: DAO->retrieve("SELECT COUNT(*) FROM article_galleys WHERE public_galley_id = ? ...", Array(2)) +File: /var/www/ojs/classes/submission/form/ArticleGalleyForm.inc.php line 233 +Function: ArticleGalleyDAO->publicGalleyIdExists("pdf", "") +File: /var/www/ojs/pages/sectionEditor/SubmissionEditHandler.inc.php line 1459 +Function: ArticleGalleyForm->execute("layoutFile") +File: /var/www/ojs/pages/sectionEditor/SubmissionEditHandler.inc.php line 1314 +Function: SubmissionEditHandler::uploadGalley("layoutFile") +File: /var/www/ojs/pages/sectionEditor/SectionEditorHandler.inc.php line 469 +Function: SubmissionEditHandler::uploadLayoutFile() +File: (unknown) line (unknown) +Function: SectionEditorHandler::uploadLayoutFile(Array(0)) +File: /var/www/ojs/index.php line 88 +Function: call_user_func(Array(2), Array(0)) +File: /var/www/ojs/index.php line 99 +Function: handleRequest() +``` + +### I am receiving the following error: Fatal error: Allowed memory size of 8388608 bytes exhausted (etc.) + +Your PHP memory limit is most likely set too low. It's normally set at 8mb by default, but OJS, OMP, and OPS need at least 16mb set to run properly (and often more for occasional tasks like upgrading). You can find a `memory_limit` configuration directive in your server's `php.ini` config file. + +### After completing the install page, I receive a database error. What's going on? + +You are probably receiving an error similar to + +`DB Error: Table 'ojs.journals' doesn't exist` + +... where the 'ojs' part of the error is the name of your database as specified during install. What has most likely happened is that you have attempted to create your database and the installer has attempted to fill that database with the necessary data, but for some reason was unable to do so. Possible reasons for this include your database system (e.g. MySQL) not allowing web-based database creation; or otherwise not allowing large-scale table creation. The best solution is to: + +* restore your `config.inc.php` to the original (copying over `config.TEMPLATE.php` will do this); +* create your database manually via phpMyAdmin, CPanel, or similar, depending on what your service provider provides; +* restart the installation process by reloading your root OJS/OMP/OPS page; +* fill in all installation fields as appropriate, ensuring that you write in the correct name for your newly-created database; +* uncheck the "Create new Database" option; +* click the "Manual Install" option at the very bottom of the installation page. +* copy the database query from the resulting page, and run it against your database via phpMyAdmin or similar. + +Please note that when you click the Manual Install button, the resulting page will say that the OJS/OMP/OPS Install has completed successfully, but this isn't quite true: you still have to copy the SQL statements and add them to your database manually. + +**Note:** You may also be encountering a plugin bug. There have been plugin bugs in the past where plugins have attempted to access the "journals" table before the installer has created the table; these will result in a "Table 'ojs.journals' doesn't exist" message when someone attempts to load the installer page in the first place. In this case, you can narrow it down to a particular plugin by checking the stack trace. diff --git a/admin-guide/3.4/index.md b/admin-guide/3.4/index.md new file mode 100644 index 000000000000..b3d7da80bd11 --- /dev/null +++ b/admin-guide/3.4/index.md @@ -0,0 +1,16 @@ +--- +isBookIndex: true +book: admin-guide +version: 3.4 +--- +# PKP Administrator's Guide + +* [English](en/) + +The PKP Administrator's Guide provides guidance for administering PKP applications, including Open Journal Systems \(OJS\), Open Monograph Press \(OMP\) and Open Preprint Systems \(OPS\). It is written by and for systems administrators - those who are responsible for the installation, upgrading and general maintenance of the system. + +## Contributors + +Authors: James MacGregor, Amanda Stevens, PKP Documentation Interest Group + +Translators: Grace Davis, Jean Rodmond Junior Laguerre, Victor Kaberuka Shyaka, Rita Tlemcani diff --git a/admin-guide/en/SUMMARY.md b/admin-guide/en/SUMMARY.md index 6954b5aea535..c54eb8304ffa 100644 --- a/admin-guide/en/SUMMARY.md +++ b/admin-guide/en/SUMMARY.md @@ -8,6 +8,7 @@ * [Deployment](./deploy) * [Configuration](./deploy#configuration) * [Email](./deploy-email) + * [Scheduled Tasks](./deploy-scheduled-tasks) * [Jobs](./deploy-jobs) * [Users](./deploy-users) * [Multi-tenant](./deploy-multi-tenant) diff --git a/admin-guide/en/data-import-and-export.md b/admin-guide/en/data-import-and-export.md index ea30fc3428dc..a5178d7a4a8e 100644 --- a/admin-guide/en/data-import-and-export.md +++ b/admin-guide/en/data-import-and-export.md @@ -2,7 +2,7 @@ title: Import and Export - Admin Guide - PKP Developer Docs description: How to import and export articles, issues, books, preprints and users with OJS, OMP or OPS. book: admin-guide -version: 3.4 +version: 3.5 --- # Import and Export @@ -11,14 +11,14 @@ There are many ways to import and export data with OJS, OMP and OPS. To access t ## REST API -You can use the REST API to read and write some data in the application. See the [api documentation](https://docs.pkp.sfu.ca/dev/api). +You can use the REST API to read and write some data in the application. See the [API documentation](https://docs.pkp.sfu.ca/dev/api). ## Native XML -> The Native XML format changes with each major version. You can not import an XML file generated with 3.2 into a 3.3 install. +> The Native XML format changes with each major version. You can not import an XML file generated with 3.4 into a 3.5 install. {:.notice} -The Native XML format is our XML schema to import and export submissions in OJS, OMP and OPS. This format is preferred for importing back issues, books or preprints, or moving submissions from one journal, press or preprint server to another. This format includes the submissions, their metadata, and all submission files. In OJS, it also includes issue metadata. When submissions are imported using this format, all imported issues, authors, users and files will be created. +The Native XML format is our XML schema to import and export submissions in OJS, OMP, and OPS. This format is preferred for importing back issues, books, or preprints, or moving submissions from one journal, press, or preprint server to another. This format includes the submissions, their metadata, and all submission files. In OJS, it also includes issue metadata. When submissions are imported using this format, all imported issues, authors, users, and files will be created. Follow these steps to import or export submissions using Native XML. @@ -36,10 +36,10 @@ Before you can import data using this format, you will need to create a XML file | Schema | Sample | Description | | --- | --- | -| [native.xsd](https://github.com/pkp/pkp-lib/blob/main/plugins/importexport/native/pkp-native.xsd) | | Base schema extended by all applications. | -| [native.xsd](https://github.com/pkp/ojs/blob/main/plugins/importexport/native/native.xsd) | [sample.xml](https://github.com/pkp/datasets/blob/main/ojs/stable-3_4_0/mysql/native-export-sample.xml) | Issues and articles in OJS. | -| [native.xsd](https://github.com/pkp/omp/blob/main/plugins/importexport/native/native.xsd) | [sample.xml](https://github.com/pkp/datasets/blob/main/omp/stable-3_4_0/mysql/native-export-sample.xml) | Book in OMP. | -| [native.xsd](https://github.com/pkp/ops/blob/main/plugins/importexport/native/native.xsd) | [sample.xml](https://github.com/pkp/datasets/blob/main/ops/stable-3_4_0/mysql/native-export-sample.xml) | Preprint in OPS. | +| [native.xsd](https://github.com/pkp/pkp-lib/blob/stable-3_5_0/plugins/importexport/native/pkp-native.xsd) | | Base schema extended by all applications. | +| [native.xsd](https://github.com/pkp/ojs/blob/stable-3_5_0/plugins/importexport/native/native.xsd) | [sample.xml](https://github.com/pkp/datasets/blob/main/ojs/stable-3_5_0/mysql/native-export-sample.xml) | Issues and articles in OJS. | +| [native.xsd](https://github.com/pkp/omp/blob/stable-3_5_0/plugins/importexport/native/native.xsd) | [sample.xml](https://github.com/pkp/datasets/blob/main/omp/stable-3_5_0/mysql/native-export-sample.xml) | Book in OMP. | +| [native.xsd](https://github.com/pkp/ops/blob/stable-3_5_0/plugins/importexport/native/native.xsd) | [sample.xml](https://github.com/pkp/datasets/blob/main/ops/stable-3_5_0/mysql/native-export-sample.xml) | Preprint in OPS. | Consider the following when creating your XML import file. @@ -54,13 +54,13 @@ Consider the following when creating your XML import file. * Some elements can support HTML tags, such as the `abstract`. If you embed HTML within your document, remember to wrap the HTML within `` tags. * If your journal supports more than one locale, you can include translated terms in a separate entry. * If you make any typographical errors in the data you are trying to import, you may end up with duplicate or split entries: for example, if your journal already has a section "Articles" with the initials ART, but you mistype in your XML file `AR` instead of `ART`, a new journal section with the initials AR will be created, and that one article will be added to it. This is easier to fix before you run the import than it is to clean up after. -* Consider validating your XML file with an editor like Liquid XML Editor or Oxygen XML. It is easier to find validation errors in these editors than through the import UI in OJS, OMP or OPS. +* Consider validating your XML file with an editor like Liquid XML Editor or Oxygen XML. It is easier to find validation errors in these editors than through the import UI in OJS, OMP, or OPS. ## QuickSubmit The QuickSubmit plugin is a useful tool for importing a small amount of back content. It provides a UI that managers can use to manually add a submission, assign it to an issue, and publish it. -Learn more about how to use this plugin in [Learning OJS 3](/learning-ojs/en/tools). +Learn more about how to use this plugin in [the QuickSubmit plugin guide](/quicksubmit/en/). ## OAI @@ -76,7 +76,7 @@ There are a few ways to import or export user accounts. User accounts control ac ### REST API -See the [api documentation](https://docs.pkp.sfu.ca/dev/api) to see what user data can be read or written with the REST API. +See the [API documentation](https://docs.pkp.sfu.ca/dev/api) to see what user data can be read or written with the REST API. ### CSV @@ -92,7 +92,7 @@ It may take several minutes to generate the CSV file if you have a large user da ### XML -> The Users XML format changes with each major version. You can not import an XML file generated with 3.2 into a 3.3 install. +> The Users XML format changes with each major version. You can not import an XML file generated with 3.4 into a 3.5 install. {:.notice} The Users XML format is our XML schema to import and export users and their roles. This can be used to move user accounts between systems, and import from other systems or export to other systems. This format includes the user information and the roles they have in the system. @@ -113,10 +113,10 @@ Before you can import data using this format, you will need to create a XML file | Schema | Sample | Description | | --- | --- | -| [pkp-users.xsd](https://github.com/pkp/pkp-lib/blob/main/plugins/importexport/users/pkp-users.xsd) | [sample.xml](https://github.com/pkp/ojs/blob/main/plugins/importexport/users/sample.xml) | Example users for OJS | -| [pkp-users.xsd](https://github.com/pkp/pkp-lib/blob/main/plugins/importexport/users/pkp-users.xsd) | [sample.xml](https://github.com/pkp/omp/blob/main/plugins/importexport/users/sample.xml) | Example users for OMP | +| [pkp-users.xsd](https://github.com/pkp/pkp-lib/blob/stable-3_5_0/plugins/importexport/users/pkp-users.xsd) | [sample.xml](https://github.com/pkp/ojs/blob/stable-3_5_0/plugins/importexport/users/sample.xml) | Example users for OJS | +| [pkp-users.xsd](https://github.com/pkp/pkp-lib/blob/stable-3_5_0/plugins/importexport/users/pkp-users.xsd) | [sample.xml](https://github.com/pkp/omp/blob/stable-3_5_0/plugins/importexport/users/sample.xml) | Example users for OMP | -Consider the following when creating your xml import file. +Consider the following when creating your XML import file. * Define the document type appropriately using ``. * The XML file should be UTF8-encoded. @@ -125,11 +125,11 @@ Consider the following when creating your xml import file. * You can require the user change their password when they next log in by setting the password attribute "change" to "true": `myoldpassword` * The default password encryption is "plaintext" (ie., none). Encrypted assumes it was encrypted by `Validation::encryptCredentials()` and is using the same encryption algorithm used by the system. * If the imported file contains any usernames or email addresses that already exist in the system, the user data for those users will not be imported and any new roles to be created will be assigned to the existing users. -* Consider validating your XML file with an editor like Liquid XML Editor or Oxygen XML. It is easier to find validation errors in these editors than through the import UI in OJS, OMP or OPS. +* Consider validating your XML file with an editor like Liquid XML Editor or Oxygen XML. It is easier to find validation errors in these editors than through the import UI in OJS, OMP, or OPS. ## Export to Services -Each application provides plugins to export published metadata to indexing services, such as Crossref, PubMed, DataCite, DOAJ, MEDRA and more. Some of these plugins deposit directly to the services. Others generate an export file according to the service's specifications. +Each application provides plugins to export published metadata to indexing services, such as Crossref, PubMed, DataCite, DOAJ, mEDRA, and more. Some of these plugins deposit directly to the services. Others generate an export file according to the service's specifications. Go to **Settings** > **Website** > **Plugins** to install and configure these plugins. Our [user documentation hub](/) provides guidance for working with many of them. @@ -159,4 +159,3 @@ Did you validate your XML file before importing it? If you did not, run it thro > "When I click on the Export button I get a blank page instead of a list of data to export." Your server's error log should contain a more useful error message to help you track down the source of the problem. - diff --git a/admin-guide/en/deploy-email.md b/admin-guide/en/deploy-email.md index 7d169d2727da..930a961bf0d2 100644 --- a/admin-guide/en/deploy-email.md +++ b/admin-guide/en/deploy-email.md @@ -2,7 +2,7 @@ title: Email - Advanced Configuration - Admin Guide - PKP Developer Docs description: Recommendations for configuring a reliable email server for Open Journal Systems (OJS), Open Monograph Press (OPS) or Open Preprint Systems (OPS). book: admin-guide -version: 3.4 +version: 3.5 --- # Email Configuration @@ -20,7 +20,7 @@ Your hosting service should provide instructions on how to add the `TXT` record. ## DMARC -To comply with the the [DMARC](https://en.wikipedia.org/wiki/Sender_Policy_Framework) framework, the application must be configured with an envelope sender. The envelope sender is an email address that the server has permission to send as. For example, if the application is hosted at https://my-journals.com, the envelope sender should be an email address `@my-journals.com`. +To comply with the [DMARC](https://en.wikipedia.org/wiki/Sender_Policy_Framework) framework, the application must be configured with an envelope sender. The envelope sender is an email address that the server has permission to send as. For example, if the application is hosted at https://my-journals.com, the envelope sender should be an email address `@my-journals.com`. When a user signs up to the application with the email address `example@gmail.com`, your email server does not have permission to send as `example@gmail.com`. The envelope sender acts as the "true" sender, and the email is sent "on behalf of" `example@gmail.com`. @@ -37,7 +37,7 @@ The application uses these settings to reconfigure the `FROM` and `REPLY-TO` hea ## Sendmail vs SMTP vs PHPMailer -Most hosting services will provide the details the application should use to connect to a SMTP server for sending email. If you have those, follow the instructions in the [configuration guide](/admin-guide/en/deploy#email-server). +Most hosting services will provide the details the application should use to connect to an SMTP server for sending email. If you have those, follow the instructions in the [configuration guide](/admin-guide/en/deploy#email-server). If not, the server will probably be configured to send email through the `sendmail` application. In such cases, set the `default` sender to `sendmail` in the `config.inc.php`: @@ -78,9 +78,9 @@ smtp_password = You can use a third-party email service, such as MailGun, Amazon SES, or Postmark, to send email if you don't want to run your own email service. However, this is not officially supported so you may need to write a small amount of custom PHP code. -Under-the-hood, all of our applications use Laravel's [Mail](https://laravel.com/docs/9.x/mail) library, which itself uses Symfony's [Mailer](https://symfony.com/doc/current/mailer.html). Transports are included for Mailgun, Amazon SES and Postmark, and these services can be used by writing a small plugin. See the example [Mailgun plugin](https://github.com/Vitaliy-1/mailgun/). +Under-the-hood, all of our applications use [Laravel's Mail](https://laravel.com/docs/11.x/mail) library, which itself uses Symfony's [Mailer](https://symfony.com/doc/current/mailer.html). Transports are included for Mailgun, Amazon SES and Postmark, and these services can be used by writing a small plugin. See the example [Mailgun plugin](https://github.com/Vitaliy-1/mailgun/). -Other transports can be be found by searching for "symfony mailer transport". A plugin would need to be written to import these transports and make use of them. If you write a transport for a service, please share it with [our community](https://forum.pkp.sfu.ca/). +Other transports can be found by searching for "symfony mailer transport". A plugin would need to be written to import these transports and make use of them. If you write a transport for a service, please share it with [our community](https://forum.pkp.sfu.ca/). ## Bounce Address @@ -108,4 +108,4 @@ If you run your own email server, you can ask for help in our [community forum]( --- -Next, learn about how to improve performance with the [job runner](./deploy-jobs). +Next, learn how to manage your [scheduled tasks](./deploy-scheduled-tasks). diff --git a/admin-guide/en/deploy-jobs.md b/admin-guide/en/deploy-jobs.md index c38dfaf905ec..550ee67fdec0 100644 --- a/admin-guide/en/deploy-jobs.md +++ b/admin-guide/en/deploy-jobs.md @@ -2,7 +2,7 @@ title: Jobs - Advanced Configuration - Admin Guide - PKP Developer Docs description: Options to configure the job runner to improve performance with Open Journal Systems (OJS), Open Monograph Press (OPS) or Open Preprint Systems (OPS). book: admin-guide -version: 3.4 +version: 3.5 --- # Job Runner @@ -20,6 +20,12 @@ Most sites will get by without too many problems by using a cron job or the buil Every server should be configured with _one_ of the following methods for running jobs: workers, cron, or the built-in job runner. Enabling two methods will not improve the site's performance. +To see all available command-line options, run: + +``` +php lib/pkp/tools/jobs.php usage +``` + ### Workers For large sites, we recommend using a worker to process jobs. The worker, when run as a daemon, will wait for jobs to be dispatched and then run them one-by-one in a separate process on the server. @@ -31,7 +37,7 @@ The following command can be used to initialize a worker. php lib/pkp/tools/jobs.php work ``` -This command supports most of the options supported by Laravel's [queue:work](https://laravel.com/docs/9.x/queues#running-the-queue-worker). Pass the `--help` flag to learn more. +This command supports most of the options supported by Laravel's [queue:work](https://laravel.com/docs/11.x/queues#running-the-queue-worker). Pass the `--help` flag to learn more. ``` php lib/pkp/tools/jobs.php work --help @@ -58,16 +64,16 @@ stdout_logfile= Replace the following variables in the configuration above with the correct paths in your system: -| Variable | Description | -| --- | --- | -| `` | Absolute path on the server to the CLI PHP executable. This can be found on most Linux servers by running `which php`. | -| `` | Absolute path to the root directory of the application (OJS, OMP, OPS). | -| `` | Absolute path to a log file. If hosting in a cloud environment, you may want to [direct logs to stdout](https://stackoverflow.com/a/26897648/1723499). | +| Variable | Description | +|-----------------|--------------------------------------------------------------------------------------------------------------------------------------------------------| +| `` | Absolute path on the server to the CLI PHP executable. This can be found on most Linux servers by running `which php`. | +| `` | Absolute path to the root directory of the application (OJS, OMP, OPS). | +| `` | Absolute path to a log file. If hosting in a cloud environment, you may want to [direct logs to stdout](https://stackoverflow.com/a/26897648/1723499). | -> Take a special note that workers are long running process that loads the application in memory. As a result, any changes when workers are running will not reflect instantly without restarting the worker. +> Take note that workers are long-running processes that load the application in memory. As a result, any changes when workers are running will not reflect instantly without restarting the worker. {:.notice} -Restart Worker. +To restart the worker: ``` php lib/pkp/tools/jobs.php restart @@ -75,7 +81,7 @@ php lib/pkp/tools/jobs.php restart The above command will quit the workers gracefully what is workers will get to complete the current job execution and then quit. Then the Supervisor will restart the workers. -Restart Supervisor. +To restart Supervisor: ``` sudo service supervisor restart @@ -87,10 +93,10 @@ You may need to run the following command to apply the configuration changes. supervisorctl reread ``` -> **Warning:** We strongly recommend to restart the Worker rather than Supervisor to reflect and consider the new changes pushed to production. Restarting Supervisor suddenly will cause the workers to quit abruptly and if the workers are in the middle of processing a job, it will not get the chance to complete the job which may cause undesired. +> **Warning:** We strongly recommend restarting the Worker rather than Supervisor to reflect and consider the new changes pushed to production. Restarting Supervisor suddenly will cause the workers to quit abruptly, and if the workers are in the middle of processing a job, they will not complete the job which may cause undesired effects. {:.warning} -To configure Supervisor on other systems, or to learn more about monitoring processes, read the [Supervisor documentation](http://supervisord.org/index.html). +To configure Supervisor on other systems or to learn more about monitoring processes, read the [Supervisor documentation](http://supervisord.org/index.html). Once you have set up the worker, turn the default job runner off in `config.inc.php`: @@ -110,11 +116,11 @@ php lib/pkp/tools/jobs.php run A cron job configured to run the following command will process only one job. -```php +``` php lib/pkp/tools/jobs.php run --once ``` -Whether or not to process one or all jobs will depend on your environment. When **running all jobs at once**, a sudden batch of large, resource-intensive jobs could slow down your server. That's because the cron job will try to churn through everything all at once. +Whether to process one or all jobs will depend on your environment. When **running all jobs at once**, a sudden batch of large, resource-intensive jobs could slow down your server. That's because the cron job will try to churn through everything all at once. When **running one job at a time**, the cron job will be less likely to consume a lot of server resources all at once. However, there is a risk that jobs will back up over time. If a bulk email is sent to 5,000 users, it may create 100 jobs. Processing one job every 60 seconds, it would take 100 minutes to send the email. @@ -126,6 +132,18 @@ job_runner = Off We recommend using [workers](#workers) for large sites. Learn more about how to [monitor jobs](#how-to-monitor-jobs) to make sure they are not backing up. +### Run Jobs with Scheduled Tasks + +To process all jobs in the queue as part of [your operating system's task scheduler](./deploy-scheduled-tasks#cron), turn on the following setting in `config.inc.php`: + +``` +process_jobs_at_task_scheduler = On +``` + +This requires that both the `job_runner`and `task_runner` (under `[schedule]`) are set to `Off`. + +In this case, we also recommend using [workers](#workers) to process jobs. + ### Built-in Job Runner In some server environments, you may not have permission to configure workers or cron jobs. On these servers, the built-in job runner can be used to process jobs. @@ -154,7 +172,7 @@ job_runner_max_jobs = 30 ; Lower this setting if jobs are failing due to timeouts. job_runner_max_execution_time = 30 -; The maximum consumerable memory that should be spent by the built-in +; The maximum consumable memory that should be spent by the built-in ; job runner when running jobs. ; ; Set as a percentage, such as 80%: @@ -170,7 +188,7 @@ job_runner_max_execution_time = 30 job_runner_max_memory = 80 ``` -We recommend staying within the default limits above, unless you know your server is capable of running with higher limits. +We recommend staying within the default limits above unless you know your server is capable of running with higher limits. ## How to Monitor Jobs @@ -202,9 +220,9 @@ delete_failed_jobs_after = 180 ## Custom Drivers -Laravel [Queues](https://laravel.com/docs/9.x/queues) are used to dispatch and process jobs. By default, the application uses the `database` driver to store and process jobs. +[Laravel Queues](https://laravel.com/docs/11.x/queues) are used to dispatch and process jobs. By default, the application uses the `database` driver to store and process jobs. -[Custom drivers](https://laravel.com/docs/9.x/queues#driver-prerequisites) exist for handling jobs with Redis, Beanstalkd, and Amazon SQS. These drivers are not officially supported, but may be implemented with a little coding. +[Custom drivers](https://laravel.com/docs/11.x/queues#driver-prerequisites) exist for handling jobs with Redis, Beanstalkd, and Amazon SQS. These drivers are not officially supported, but may be implemented with a little coding. If you use a custom driver, please share your findings with [our community](https://forum.pkp.sfu.ca/). diff --git a/admin-guide/en/deploy-multi-tenant.md b/admin-guide/en/deploy-multi-tenant.md index 5e93f64f0c68..831b16dc611a 100644 --- a/admin-guide/en/deploy-multi-tenant.md +++ b/admin-guide/en/deploy-multi-tenant.md @@ -2,12 +2,12 @@ title: Multi-tenancy - Advanced Configuration - Admin Guide - PKP Developer Docs description: Recommendations for running many separate journals, presses or preprint servers in one install with OJS, OMP or OPS. book: admin-guide -version: 3.4 +version: 3.5 --- # Multi-tenancy -When OJS, OMP or OPS is used to run many independent journals, presses or preprint servers, we call it a "multi-tentant" install. These instances often need to provide unique domains to each tenant. +When OJS, OMP or OPS is used to run many independent journals, presses or preprint servers, we call it a "multi-tenant" install. These instances often need to provide unique domains to each tenant. ## Domain Names diff --git a/admin-guide/en/deploy-sandbox.md b/admin-guide/en/deploy-sandbox.md index d1538463e0b1..0cf365ffc52d 100644 --- a/admin-guide/en/deploy-sandbox.md +++ b/admin-guide/en/deploy-sandbox.md @@ -2,7 +2,7 @@ title: Sandbox - Advanced Configuration - Admin Guide - PKP Developer Docs description: Safely sandbox an install of OJS, OMP or OPS, to block email sending, data deposits, and other unwanted tasks. book: admin-guide -version: 3.4 +version: 3.5 --- # Sandbox an Instance @@ -18,12 +18,12 @@ Beginning with OJS, OMP, and OPS 3.4.0-4, there is a sandbox mode that can be en To enable the sandbox mode for an installation, edit `config.inc.php` and find the `sandbox` setting in the `[general]` section. Setting it to `On` will have following impacts: - - The email `default` driver will be set to `log`. As a result all emails will be routed to the server's error log and no emails will be delivered. - - Scheduled tasks that run at regular intervals to send out reminder emails, deposit data with third-party services, and perform other tasks will be disabled. This will also disable schedule task execution via `Acron` plugin. + - The email `default` driver will be set to `log`. As a result, all emails will be routed to the server's error log and no emails will be delivered. + - Scheduled tasks that run at regular intervals to send out reminder emails, deposit data with third-party services, and perform other tasks will be disabled. - Job execution will be disabled. However, jobs will continue to be dispatched to the queue as usual. - `Crossref` and `Datacite` deposits will be disabled. - - The `ORCiD` plugin will not have any interaction with orcid service. - - No payments will dispatched to or handled by Paypal (e.g. for subscription purchases). + - The application will not have any interaction with the ORCID service. + - No payments will be dispatched to or handled by PayPal (e.g. for subscription purchases). > **Warning:** Enabling the sandbox mode will disable job processing via the job runner, cron and worker mechanisms. However, if any worker process is already running prior to enabling sandbox mode, it will require separate manual intervention to restart/quit worker gracefully. See the [Job Deployment Guide](/admin-guide/en/deploy-jobs) for more details. {:.warning} @@ -46,22 +46,21 @@ default = log Scheduled tasks are run at regular intervals to send out reminder emails, deposit data with third-party services, and perform other tasks. They may be triggered in a couple different ways, depending how you configured them. -If you have a **cron job** set up to run the following command, delete that cron job. +To disable the built-in task runner, find and edit the following setting in the `[schedule]` section of `config.inc.php`. ``` -php tools/runScheduledTasks.php +task_runner = Off ``` -If you have the **acron plugin** installed, remove it by running the following command in the root directory of the application. +If you have a **cron job** set up to run the following command, delete that cron job. ``` -rm -rf plugins/generic/acron -rm -rf lib/pkp/plugins/generic/acron +php tools/runScheduledTasks.php ``` ### Disable jobs -Stop the job runner in order to prevent pending jobs like data deposits from being run. Turn the built-in job runner off in `config.inc.php`. +Stop the job runner to prevent pending jobs like data deposits from being run. Turn the built-in job runner off in `config.inc.php`. ``` job_runner = Off @@ -95,4 +94,3 @@ Run the following SQL query on the database to set all author account emails to ```sql UPDATE authors SET email = 'test@mailinator.com'; ``` - diff --git a/admin-guide/en/deploy-scheduled-tasks.md b/admin-guide/en/deploy-scheduled-tasks.md new file mode 100644 index 000000000000..0e50417f1aa6 --- /dev/null +++ b/admin-guide/en/deploy-scheduled-tasks.md @@ -0,0 +1,82 @@ +--- +title: Scheduled Tasks - Advanced Configuration - Admin Guide - PKP Developer Docs +description: Options to configure scheduled tasks with Open Journal Systems (OJS), Open Monograph Press (OPS) or Open Preprint Systems (OPS). +book: admin-guide +version: 3.5 +--- + +# Scheduled Tasks + +Scheduled tasks are used to perform periodic tasks or [dispatch jobs](./deploy-jobs) on a schedule, such as [processing statistics](./statistics), removing expired data, sending emails, or exporting data to third-party services (e.g. registering DOIs or exporting articles to DOAJ). + +To see available options, run: + +``` +php lib/pkp/tools/scheduler.php usage +``` + +To see all registered scheduled tasks, run: + +``` +php lib/pkp/tools/scheduler.php list +``` + +To run all pending scheduled tasks, run: + +``` +php lib/pkp/tools/scheduler.php run +``` + +To run a single specific scheduled task, which is particularly useful for development purposes, run: + +``` +php lib/pkp/tools/scheduler.php test +``` + +## Log Files + +Scheduled task logs are located in files directory under `/scheduledTaskLogs`. + +## Configuration + +### Scheduled Task Runner + +In 3.5 and later, the Acron plugin has been removed and a built-in task runner has been introduced. + +To enable the built-in task runner, set the following in the `[schedule]` section in `config.inc.php`: + +``` +task_runner = On +``` + +To adjust the interval at which the built-in task runner runs, adjust the following setting in `config.inc.php`. A smaller value may negatively impact application performance. + +``` +task_runner_interval = 60 +``` + +### Cron + +The built-in task runner may not be suitable for high-volume sites; in this case, we recommend using your operating system's task scheduler instead. The following is a sample crontab entry for *nix operating systems: + +``` +* * * * * php lib/pkp/tools/scheduler.php run >> /dev/null 2>&1 +``` + +Once the cron job has been set up, disable the built-in task runner. + +``` +task_runner = Off +``` + +### Notifications + +To receive an email notification only when a scheduled task fails, set the following in `config.inc.php`. Otherwise, all tasks will generate a notification. + +``` +scheduled_tasks_report_error_only = On +``` + +--- + +Next, learn about how to improve performance with the [job runner](./deploy-jobs). diff --git a/admin-guide/en/deploy-users.md b/admin-guide/en/deploy-users.md index e36f350ecbd1..9095384a5544 100644 --- a/admin-guide/en/deploy-users.md +++ b/admin-guide/en/deploy-users.md @@ -2,7 +2,7 @@ title: User Accounts - Advanced Configuration - Admin Guide - PKP Developer Docs description: Configuration options to manager users in Open Journal Systems (OJS), Open Monograph Press (OPS) or Open Preprint Systems (OPS). book: admin-guide -version: 3.4 +version: 3.5 --- # User Accounts @@ -11,7 +11,7 @@ This section describes the configuration options, plugins, and application setti ## Spam/Bot Accounts -If the application is pubicly accessible on the web, it will attract the attention of automated bots. These bots will create user accounts and try to post unwanted material to advertise products or deface the website. Read on to learn how to restrict access to these accounts. +If the application is publicly accessible on the web, it will attract the attention of automated bots. These bots will create user accounts and try to post unwanted material to advertise products or deface the website. Read on to learn how to restrict access to these accounts. ### Account Validation @@ -27,7 +27,9 @@ require_validation = On Google's [reCAPTCHA](https://www.google.com/recaptcha/) service can be enabled for the registration and login forms. This will reduce the number of bots that can sign up by requiring users to complete a task that is difficult for bots to perform during registration and login. -You will need to [sign up](https://www.google.com/recaptcha/) for an account with Google to receive public and private keys. Then set the following options in `config.inc.php`. +You will need to [sign up for a Google account](https://www.google.com/recaptcha/) to receive public and private keys. + +To enable reCAPTCHA, set the following options in `config.inc.php`. ``` ;;;;;;;;;;;;;;;;;;;; @@ -57,13 +59,41 @@ recaptcha_enforce_hostname = Off Use of Google's reCAPTCHA service will send your visitors' data to Google's servers. You may be required to notify users of this depending on the privacy laws in your jurisdiction. +### Altcha + +[ALTCHA](https://altcha.org/open-source-captcha/) is an open-source and self-hosted alternative to Google's reCAPTCHA. ALTCHA can be enabled to reduce spam activity on registration, login, and password reset forms. + +You will need to set up a self-hosted installation to create a private key. Review [the ALTCHA documentation](https://altcha.org/docs/v2/) for more information. + +Once you have a private key for ALTCHA, set the following options in `config.inc.php`: + +``` +; Whether or not to enable ALTCHA +altcha = on + +; Private key for ALTCHA +altcha_hmackey = 'Example key' + +; Whether or not to use ALTCHA on user registration +altcha_on_register = on + +; Whether or not to use ALTCHA on user login +altcha_on_login = on + +; Whether or not to use ALTCHA on user lost password +altcha_on_lost_password = on + +; The quantity of encryption cycles performed by the ALTCHA system +altcha_encrypt_number = 10000 +``` + ### Honeypot The [pkp-formHoneypot](https://github.com/ulsdevteam/pkp-formHoneypot) plugin from the University of Pittsburgh implements a [honeypot](https://en.wikipedia.org/wiki/Honeypot_(computing)) mechanism to protect new user registrations from bots. This plugin is effective against most bots and does not send your visitor's data to any third parties. ### Disable Registration -It's possible to set up a journal, press or preprint server to disable user registration. When user registration is disabled, all users will have to be registered by an admin or manager. +It's possible to set up a journal, press, or preprint server to disable user registration. When user registration is disabled, all users will have to be registered by an admin or manager. Follow these steps to disable user registration in a journal, press or preprint server. @@ -75,15 +105,15 @@ Follow these steps to disable user registration in a journal, press or preprint 6. Click **OK**. 7. Click the **Search** button. 8. Under *With permission level set to* select **Author**. -9. For each role, follow steps 3-7 to prevent user self-registration. -10. Repeat steps 7-8 with **Reviewer** selected for the permission level. +9. For each role, follow steps 3–7 to prevent user self-registration. +10. Repeat steps 7–8 with **Reviewer** selected for the permission level. 11. For each role, follow steps 3-7 to prevent user self-registration. -Only reader, author and reviewer roles can allow user self-registration. User self-registration is always disabled for other roles. +Only reader, author, and reviewer roles can allow user self-registration. User self-registration is always disabled for other roles. ### Remove Accounts -If you already have a large number of spam registrations, you may want to remove these accounts. User accounts can not be deleted. Instead, they must be merged to another account in order to ensure that any editorial data (such as submissions, reviews, etc) is maintained. +If you already have a large number of spam registrations, you may want to remove these accounts. User accounts cannot be deleted. Instead, they must be merged to another account to ensure that any editorial data (such as submissions, reviews, etc) is maintained. Run the following command from the root directory of the application to merge a spam registration into another account. @@ -111,12 +141,26 @@ usernameTwo usernameThree ``` -Then load the file into the the command. +Then load the file into the `mergeUsers` command. ```bash php tools/mergeUsers.php spamaccount $(cat usernames.txt) ``` +## User Invitations + +In version 3.5, a new Invitations toolset was introduced. This is used to implement three types of invitations: + +- The ability to request an email address change (and confirm it) +- The one-click reviewer access invitation +- The new GDPR-compliant user account creation process. + +You can change the number of days a user has to accept an invitation before it expires in the `[invitations]` section of `config.inc.php`. + +``` +expiration_days = 3 +``` + ## User Uploads By default, all users registered on the site can upload files to a personal user directory. These files can be used in the user's signature or biography. Managers and admins can use these files in journal settings. For example, if a manager uploads an image to the "About the Journal" section, this will use their user directory. @@ -131,7 +175,7 @@ The [controlPublicFiles](https://github.com/pkp/controlPublicFiles) plugin inclu ## Single Sign-on -Single sign-on allows users to register and login to your journal, press or preprint server using an account with another service. This may be an institutional account such as a university network, a scholarly infrastructure organization like ORCID, or a commercial service provider like Google, Microsoft or Apple. +Single sign-on allows users to register and login to your journal, press, or preprint server using an account with another service. This may be an institutional account such as a university network, a scholarly infrastructure organization like ORCID, or a commercial service provider like Google, Microsoft, or Apple. The following are different approaches to single sign-on that are in use by our community. @@ -139,11 +183,11 @@ The following are different approaches to single sign-on that are in use by our The [openid plugin](https://github.com/leibniz-psychology/openid) allows users to register and login using any [OpenID](https://en.wikipedia.org/wiki/OpenID) protocol. This protocol is supported by ORCID, Google, Microsoft, Apple and many others. -The Leibniz Institute for Psychology (ZPID) has developed this plugin. +The Leibniz Institute for Psychology (ZPID) originally developed this plugin, which is now maintained by the PKP team. ### ORCID -Users can register and login using their ORCID accounts. Use the [openid plugin](https://github.com/leibniz-psychology/openid). +Users can register and login using their ORCID accounts. Use the [OpenID plugin](https://github.com/pkp/openid). ### Shibboleth @@ -157,4 +201,4 @@ Learn how to import or export data about user accounts in the [Import/Export](./ --- -The next section describes best practices for running lots of independent journals, presses or preprint servers from one [multi-tenant install](./deploy-multi-tenant). \ No newline at end of file +The next section describes best practices for running lots of independent journals, presses or preprint servers from one [multi-tenant install](./deploy-multi-tenant). diff --git a/admin-guide/en/deploy.md b/admin-guide/en/deploy.md index 71fe1d71b7a5..d1660b9450ff 100644 --- a/admin-guide/en/deploy.md +++ b/admin-guide/en/deploy.md @@ -2,7 +2,7 @@ title: Deployment Guide for OJS, OMP and OPS - Admin Guide - PKP Developer Docs description: How to configure OJS, OMP and OPS and safely deploy these applications in a production environment. book: admin-guide -version: 3.4 +version: 3.5 --- # Deployment @@ -14,7 +14,7 @@ In a production environment, the software needs to be configured to send email, ## What you need to know -In order to run this software securely, you will need to understand how to do the following: +To run this software securely, you will need to understand how to do the following: - Upload and edit files on your web server - Modify file permissions on your web server @@ -31,9 +31,9 @@ If you are unfamiliar with some of these topics, you may be able to learn by fol The configuration file is found in the root directory of the application. For example, if you installed the software to the directory `/var/www`, the configuration file would be located at `/var/www/config.inc.php`. -Some of the settings in this file, like the database connection, are set during the installation process (see [Getting Started](./getting-started)). However, you will need to edit the file directly to configure other settings. +Some settings in this file, like the database connection, are set during the installation process (see [Getting Started](./getting-started)). However, you will need to edit the file directly to configure other settings. -Open the config file, find the `base_url` setting and change it to the web address of your install. +Open the config file, find the `base_url` setting, and change it to the web address of your installation. ``` base_url = "" @@ -45,7 +45,7 @@ Add this domain to your `allowed_hosts` list. allowed_hosts = '[""]' ``` -Two secret keys need to be set in order to safely encrypt secure tokens on your server. You can use the following command to generate a random key in most Linux and Mac environments. +Two secret keys need to be set to safely encrypt secure tokens on your server. You can use the following command to generate a random key in most Linux and Mac environments. ```bash openssl rand -base64 32 @@ -53,7 +53,7 @@ openssl rand -base64 32 Use the string created by this command to set the `salt` and `api_key_secret` values in `config.inc.php`. Each config setting should have a different value. -(We have not provided an example, because copying the example could compromise your site's security.) +(We have not provided an example because copying the example could compromise your site's security.) Set the `require_validation` in order to require new users to validate their email addresses before using a new account. @@ -61,6 +61,12 @@ Set the `require_validation` in order to require new users to validate their ema require_validation = On ``` +During the installation process, the `app_key` should be set automatically. If the key is missing, there is a command-line tool that can be used to generate it: + +```bash +php lib/pkp/tools/appKey.php +``` + ## Secure Files Directory Every installation needs to have a secure files directory to ensure that private files, like unpublished submissions, can not be accessed by unauthorized users. @@ -75,7 +81,7 @@ files_dir = ## Email Server -Most email will be blocked by spam filters unless you use a SMTP server with correctly configured [SPF](https://en.wikipedia.org/wiki/Sender_Policy_Framework) and [DMARC](https://en.wikipedia.org/wiki/DMARC) records. +Most email will be blocked by spam filters unless you use an SMTP server with correctly configured [SPF](https://en.wikipedia.org/wiki/Sender_Policy_Framework) and [DMARC](https://en.wikipedia.org/wiki/DMARC) records. > Not sure what to do here? Learn more about how to [configure an email server](./deploy-email). {:.notice} @@ -119,7 +125,7 @@ validation_timeout = 14 ## SSL / HTTPS -Every site should encrypt it's web traffic using a SSL certificate. This will make your site run from `https://` instead of `http://`. If you don't have a SSL certificate, you should [get one](./securing-your-system#sslencryption). +Every site should encrypt its web traffic using an SSL certificate. This will make your site run from `https://` instead of `http://`. If you don't have an SSL certificate, you should [get one](./securing-your-system#sslencryption). Edit the `config.inc.php` file to force URLs to use SSL: @@ -132,10 +138,10 @@ force_ssl = On The software must run some tasks every day, such as compiling usage statistics. You should set up a cron job to run the following command once a day. ``` -php tools/runScheduledTasks.php +php lib/pkp/tools/scheduler.php run ``` -If you are unable to configure this cron job, you must enable the Acron plugin after you have installed the software. +Learn more about [scheduled tasks](./deploy-scheduled-tasks). ## Job Runner @@ -145,7 +151,7 @@ Learn more about how to configure the [job runner](./deploy-jobs). ## Pretty URLs -Enable URL rewriting on your server in order to drop the `index.php` from URLs. For example, instead of `https://example.org/index.php/publicknowledge`, the URL will be `https://example.org/publicknowledge`. +Enable URL rewriting on your server to drop the `index.php` from URLs. For example, instead of `https://example.org/index.php/publicknowledge`, the URL will be `https://example.org/publicknowledge`. The following is an example `.htaccess` file that can be used to enable `mod_rewrite` for Apache servers. This file should be placed in the web root. @@ -171,4 +177,4 @@ The configuration file includes settings to control the default date formats, ma --- -You've now configured all of the critical application functions. Next, you can learn how to conifigure your [email server](./deploy-email) to reliably deliver email. \ No newline at end of file +You've now configured all the critical application functions. Next, you can learn how to configure your [email server](./deploy-email) to reliably deliver email. diff --git a/admin-guide/en/download.md b/admin-guide/en/download.md index 56e1f89b22f8..a0a7db9beb74 100644 --- a/admin-guide/en/download.md +++ b/admin-guide/en/download.md @@ -2,7 +2,7 @@ title: Download - Admin Guide - PKP Developer Docs description: How to download Open Journal Systems (OJS), Open Monograph Press (OPS) or Open Preprint Systems (OPS). book: admin-guide -version: 3.4 +version: 3.5 --- # Download diff --git a/admin-guide/en/getting-started.md b/admin-guide/en/getting-started.md index 1000b4e7481d..d6bc4c706f98 100644 --- a/admin-guide/en/getting-started.md +++ b/admin-guide/en/getting-started.md @@ -2,7 +2,7 @@ title: Getting Started with OJS, OMP or OPS - Admin Guide - PKP Developer Docs description: A quick-start guide to install OJS, OMP or OPS in a test environment. book: admin-guide -version: 3.4 +version: 3.5 --- # Getting Started @@ -11,9 +11,9 @@ This is a quick-start guide to install and run OJS, OMP or OPS in a local test e ## System Requirements -Your server — or your local development environment — must meet the following requirements in order to run the 3.4 release of OJS, OMP or OPS. +Your server — or your local development environment — must meet the following requirements in order to run the 3.5 release of OJS, OMP or OPS. -- [PHP 8.0+](http://www.php.net/) with php-mbstring, php-xml, and php-intl enabled +- [PHP 8.2+](http://www.php.net/) with php-mbstring, php-xml, and php-intl enabled - [MySQL 5.7.22+](http://www.mysql.com/), [MariaDB 4.1+](https://mariadb.org/) or [PostgreSQL 9.5+](http://www.postgresql.org/) - Linux, or one of the following: BSD, Solaris, Mac OS X, Windows @@ -27,13 +27,13 @@ Download the latest stable release package (`.tar.gz`) from the PKP website. - [Open Monograph Press](https://pkp.sfu.ca/software/omp/download) (OMP) - [Open Preprint Systems](https://pkp.sfu.ca/software/ops/download) (OPS) -Use the `tar` command, or any archive software on your system, to unpack the `.tar.gz` file to a local directory. For example, if you downloaded the OJS 3.4.0 release package, you can use the following command to unpack the file. +Use the `tar` command, or any archive software on your system, to unpack the `.tar.gz` file to a local directory. For example, if you downloaded the OJS 3.5.0 release package, you can use the following command to unpack the file. ``` -tar -xvf ojs-3.4.0.tar.gz +tar -xvf ojs-3.5.0.tar.gz ``` -This will create a directory for the software at `ojs-3.4.0`. Create another directory for file uploads. +This will create a directory for the software at `ojs-3.5.0`. Create another directory for file uploads. ``` mkdir ojs-files @@ -45,7 +45,7 @@ mkdir ojs-files Start PHP's built-in server from the release package's root directory. ``` -cd ojs-3.4.0 +cd ojs-3.5.0 php -S localhost:8000 ``` @@ -59,14 +59,13 @@ http://localhost:8000 You should see an installation screen like the one below. - ![Screenshot of the installation screen of OJS](./assets/install-start.png) Complete the form to finish the installation, using the file uploads directory that you created. It may take a minute to install. You should see the following success screen when it is finished. ![Screenshot of the install complete screen of OJS](./assets/install-complete.png) -Once you have finished the install, login with the administrator account you set up to access the admin area. Depending on whether you installed OJS, OMP or OPS, you will be taken to a screen where you can create your first journal, press or preprint server. +Once you have finished the installation, login with the administrator account you set up to access the admin area. Depending on whether you installed OJS, OMP or OPS, you will be taken to a screen where you can create your first journal, press or preprint server. - In OJS, click the **Add Journal** button. - In OMP, click the **Add Press** button. diff --git a/admin-guide/en/index.md b/admin-guide/en/index.md index 0018d204f3db..baf7d8422eb8 100644 --- a/admin-guide/en/index.md +++ b/admin-guide/en/index.md @@ -2,7 +2,7 @@ title: Admin Guide for OJS, OMP and OPS - PKP Developer Docs description: A guide for system administrators who want to install, deploy and maintain Open Journal Systems (OJS), Open Monograph Press (OMP) or Open Preprint Systems (OPS). book: admin-guide -version: 3.4 +version: 3.5 --- # Administrator's Guide diff --git a/admin-guide/en/securing-your-system.md b/admin-guide/en/securing-your-system.md index d2dbfab8db62..3b1caa9194dd 100644 --- a/admin-guide/en/securing-your-system.md +++ b/admin-guide/en/securing-your-system.md @@ -2,7 +2,7 @@ title: Secure your System - Admin Guide - PKP Developer Docs description: Best practices to set up a secure server when running OJS, OMP or OPS. book: admin-guide -version: 3.4 +version: 3.5 --- # Securing Your System @@ -10,7 +10,7 @@ version: 3.4 > This section describes how to run a secure server. Before reading this section, make sure you have followed the [recommended configuration](./deploy) instructions to secure the application. {:.warning} -It's important to run OJS, OMP and OPS on a secure server environment. In addition to the security settings in the [recommended configuration](./deploy) of the application, you must ensure the server is secure where the applicaiton is run. +It's important to run OJS, OMP and OPS in a secure server environment. In addition to the security settings in the [recommended configuration](./deploy) of the application, you must ensure the server is secure where the application is run. This section makes a few recommendations for running secure servers. However, if you are unfamiliar with server administration, we strongly encourage you to use a professional hosting service or hire a professional system administrator. @@ -21,13 +21,13 @@ This section makes a few recommendations for running secure servers. However, if - Use a long, random value for each one of the `salt` and `api_secret_key` settings in `config.inc.php`. - Make sure the `encryption` setting in `config.inc.php` is set to `sha1`. - Restrict [file permissions](#file-permissions) as much as possible. -- Set up a [SSL certificate](#sslencryption) and configure the application to use `https://`. +- Set up an [SSL certificate](#sslencryption) and configure the application to use `https://`. - Make sure the `files_dir` folder [can not be accessed through the web](#file-permissions). - Dedicate a database to the application. Do not share it with other applications on the server. - Run antivirus software on the server to prevent users from uploading a compromised file. - Configure your server to make automated backups of the database and `files_dir` at regular intervals. We recommend a backup for every day in the last 7 days, one per week for the last 4 weeks, and one per month for the last 12 months. View the [upgrade guide](/dev/upgrade-guide/en/) for more complete backup instructions. - Keep the web server regularly updated with all security patches. -- Practice good password management: don’t use the same username/password to access the application as you would for any other online account, and don’t use an easy to guess password. +- Practice good password management: don’t use the same username/password to access the application as you would for any other online account, and don’t use an easy-to-guess password, especially for accounts with administrative privileges. - Treat everything that you get online with the knowledge that you received it from someone you don’t know, and act likewise. If a submission appears to be suspicious for any reason (strange email address, suspiciously generic title or abstract, etc.), treat the included files with an additional level of diligence. ## File Permissions @@ -38,19 +38,19 @@ The exact details of file permissions will depend on how your web server runs PH ## SSL/Encryption -All web applications should be protected with SSL/TLS encryption, so that they can encrypt traffic through the server. Without encryption, user login credentials are passed in plain text, which allows anyone scanning the network to intercept them. +All web applications should be protected with SSL/TLS encryption so that they can encrypt traffic through the server. Without encryption, user login credentials are passed in plain text, which allows anyone scanning the network to intercept them. -The following section describes how to get a SSL certificate, enable it, and configure the server to update it. +The following section describes how to get an SSL certificate, enable it, and configure the server to update it. ### Getting a Certificate -A certificate enables a secure connection from the user's Web browser to the server hosting your site. Installing a certificate for your site can not be done within the OJS, OMP, or OCS software and will require technical expertise or assistance at the server level. When considering a software host, determining their level of certificate support is an important consideration. +A certificate enables a secure connection from the user's Web browser to the server hosting your site. Installing a certificate for your site can not be done within the OJS, OMP, or OPS software and will require technical expertise or assistance at the server level. When considering a software host, determining their level of certificate support is an important consideration. A good start is asking your hosting service provider if they have an existing solution for supporting TLS or SSL certificates -- Your hosting provider may be able to create/issue an TLS or SSL certificate for you. If you do not have shell access to your installation this may be the only way to go about adding SSL/TLS protection for your site. -Purchasing a certificate may be an option available to you as well. Commercial businesses that provide certificates are called [Certificate Authorities](https://en.wikipedia.org/wiki/Certificate_authority) (CA). Wikipedia provides a listing of [CA providers](https://en.wikipedia.org/wiki/Certificate_authority#Providers) by market share. In addition to providing certificates that enable encryption, traditional CA issued certificates offer several advantages including customer vetting to help validate customer identity, and wildcard certificates. Depending on what features you select with your purchase, CA issued certificates can cost $100s per year and must be renewed before expiry. +Purchasing a certificate may be an option available to you as well. Commercial businesses that provide certificates are called [Certificate Authorities](https://en.wikipedia.org/wiki/Certificate_authority) (CA). Wikipedia provides a listing of [CA providers](https://en.wikipedia.org/wiki/Certificate_authority#Providers) by market share. In addition to providing certificates that enable encryption, traditional CA-issued certificates offer several advantages including customer vetting to help validate customer identity, and wildcard certificates. Depending on what features you select with your purchase, CA issued certificates can cost $100s per year and must be renewed before expiry. -[Let’s Encrypt](https://letsencrypt.org/) is a popular option for obtaining subscription as well. Let’s Encrypt is a free, automated, and open certificate authority (CA), run for the public’s benefit. It is a service provided by the Internet Security Research Group (ISRG). Certificates are provided for free, with some limitations: +[Let’s Encrypt](https://letsencrypt.org/) is a popular option for obtaining certificates as well. Let’s Encrypt is a free, automated, and open certificate authority (CA), run for the public’s benefit. It is a service provided by the Internet Security Research Group (ISRG). Certificates are provided for free, with some limitations: * Only DV (Domain Validation) certificates are offered * Slightly more technical, if your hosting provider does not already support you will need to generate from shell @@ -72,4 +72,3 @@ Required step to generate a certificate if you are going to be purchasing a cert When you purchase a certificate from a CA, you will typically purchase a certificate that lasts between 1 to 3 years. Certificates are set to expire and will need to be renewed resulting in a new expense at the time of renewal. Let’s Encrypt certificates expire every 90 days. The Let’s Encrypt software (certbot) can be configured to automatically renew certificates before they expire. Meaning once installed you should have minimal maintenance moving forward. Automation is done with `cron` or `systemd`. > Contributors: PKP staff, Kenton Good - diff --git a/admin-guide/en/statistics.md b/admin-guide/en/statistics.md index e369870aa8b6..256f0bdc54cc 100644 --- a/admin-guide/en/statistics.md +++ b/admin-guide/en/statistics.md @@ -2,7 +2,7 @@ title: Statistics - Admin Guide - PKP Developer Docs description: How to collect, process, restore and export usage statistics in OJS, OMP or OPS. book: admin-guide -version: 3.4 +version: 3.5 --- # Statistics @@ -20,7 +20,7 @@ Read the sections below to learn how to configure the statistics for your site, As an administrator, you can restrict the type of statistics that will be collected. You may choose to do this to protect the privacy of visitors, comply with legal requirements in your jurisdiction, or reduce the disk space required for your database. -Follow the steps below to set the statistics settings for all journals, presses or preprint servers on your site. +Follow the steps below to set the statistics settings for all journals, presses, or preprint servers on your site. 1. Login as an administrator. 2. Go to **Administration**. @@ -29,19 +29,19 @@ Follow the steps below to set the statistics settings for all journals, presses A manager may configure some of these settings differently for each journal, press or preprint server they manage. In such cases, the site settings act as a "ceiling". For example, if the site has disabled geographic statistics, the manager will not be able to enable them for their journal, press or preprint server. If the site has enabled country-level statistics only, the manager will not be able to enable region and city statistics. -However, the manager can turn off statistics even if the site has disabled them. For example, if the site has enabled geographic statistics for country, region and city, the manager will be able to turn geographic statistics off, or choose to collect only country and region data. +However, the manager can turn off statistics even if the site has disabled them. For example, if the site has enabled geographic statistics for country, region, and city, the manager will be able to turn geographic statistics off, or choose to collect only country and region data. ## Download Statistics are collected for different kinds of data and can be accessed in several different formats. Some statistics can be viewed as tables and graphs in the application. Others can only be viewed by downloading a report in CSV or JSON. The CSV format can be opened in spreadsheet software, like Excel or LibreOffice Calc. | Type | Description | Web | CSV | JSON | -| ----------------------------------------- | -------------------------------------------------------------------------------------- | --- | --- | ---- | +|-------------------------------------------|----------------------------------------------------------------------------------------|-----|-----|------| | [Publications](#publications) | Views and downloads of articles, books and preprints, and their files. | ✔ | ✔ | ✔ | | [Issues](#issues) | Views and downloads (OJS) | ✔ | ✔ | ✔ | | [Homepage](#homepage) | Views of the homepage of the journal, press or preprint server. | ✔ | ✔ | ✔ | | [Geography](#geography) | Views by country, region and city | ✔ | ✔ | ✔ | -| [COUNTER](#counter) | An industry-recognized format for distributing usage statistics. | ✘ | ✘ | ✔ | +| [COUNTER](#counter) | An industry-recognized format for distributing usage statistics. | ✘ | ✘ | ✔ | | [Editorial Activity](#editorial-activity) | Number of submissions accepted and rejected, the average time to a decision, and more. | ✔ | ✘ | ✘ | | [Users](#user) | User profiles and roles. | ✘ | ✔ | ✘ | | [Reviews](#reviews) | Reviewer names, due dates, and comments for all review assignments | ✘ | ✔ | ✘ | @@ -89,10 +89,10 @@ Homepage statistics can also be accessed in JSON format through the [REST API](/ ### Geography -> You must [enable geographic statistics](#configure) first. +> You must [enable geographic statistics](#settings) first. {:.notice} -Follow these steps to download a CSV file with the number of views and downloads for each city, region and country. +Follow these steps to download a CSV file with the number of views and downloads for each city, region, and country. 1. Login as an administrator or manager. 2. Click **Statistics** > **Articles** (or Books in OMP and Preprints in OPS). @@ -115,7 +115,7 @@ Geographic statistics can also be accessed in JSON format through the [REST API] > Editorial statistics can change significantly depending on the selected date range. Read the recommendations below to avoid these pitfalls. {:.warning} -Follow these steps to view stats about the editorial activity of a journal, press or preprint server, such as the number of submissions accepted and rejected, the average time it takes to record a decision, and more. +Follow these steps to view stats about the editorial activity of a journal, press, or preprint server, such as the number of submissions accepted and rejected, the average time it takes to record a decision, and more. 1. Login as an administrator or manager. 2. Click **Statistics** > **Editorial Activity**. @@ -123,7 +123,7 @@ Follow these steps to view stats about the editorial activity of a journal, pres These stats are based on editorial activity recorded by the system. If your editors routinely work outside of the system, stats may not be correct. For example, if an editor asks for a review by email and does not record it in the system, that review will not be counted in the editorial statistics. -When selecting a date range, think carefully about the editoral activity you are interested in. For example, if you are looking at the last three months, the Acceptance Rate will be calculated only from submissions submitted in the last three months that have already received an accepted or declined decision. We recommend using a date range that accounts for the duration of your editorial review and ends at least 12 months ago. +When selecting a date range, think carefully about the editorial activity you are interested in. For example, if you are looking at the last three months, the Acceptance Rate will be calculated only from submissions submitted in the last three months that have already received an accepted or declined decision. We recommend using a date range that accounts for the duration of your editorial review and ends at least 12 months ago. ### Users @@ -147,7 +147,7 @@ Follow these steps to download a CSV report about review assignments that includ ### Submissions -Follow these steps to download a CSV report about submissions that includes the titles, contributors and metadata. +Follow these steps to download a CSV report about submissions that includes the titles, contributors, and metadata. 1. Login as an administrator or manager. 2. Click **Statistics** > **Reports**. @@ -160,7 +160,7 @@ There are many other ways to [export submission data](./data-import-and-export). > The subscriptions report is only available in OJS when subscriptions are enabled. {:.notice} -Follow these steps to download a CSV report about subscriptions that includes the titles, contributors and metadata. +Follow these steps to download a CSV report about subscriptions that includes the titles, contributors, and metadata. 1. Login as an administrator or manager. 2. Click **Statistics** > **Reports**. @@ -168,12 +168,12 @@ Follow these steps to download a CSV report about subscriptions that includes th ## Recover Lost Data -> If the system is not recording any statistics, the application may not be configured correctly. Read the [configuration advice](#configure). +> If the system is not recording any statistics, the application may not be configured correctly. Read the [configuration advice](#settings). {:.notice} You may notice historical gaps in your statistics data. These can arise for several reasons. Often it is because the application was misconfigured, the server resources were limited, or an application error prevented the logs from being processed. This can leave historical gaps in statistics data if the problem goes unnoticed for a while. When this happens, it can be difficult to restore the data. But it may be possible. -In order to recover the data, you will need to have log files that cover that period. These may be the application's [stats logs](/dev/documentation/en/statistics#understanding-the-log-files) or the Apache access log files. +To recover the data, you will need to have log files that cover that period. These may be the application's [stats logs](/dev/documentation/en/statistics#understanding-the-log-files) or the Apache access log files. The sections below provide information to help you determine what log files are available and reprocess them to compile statistics. @@ -218,7 +218,7 @@ The command must be run by a user who has permission to read the Apache log file ### Reprocess Log Files -Once you have identified the log files you want to reprocess, move them into the `stage` directory. Then run the following command, once for every month you want to reprocess. +Once you have identified the log files you want to reprocess, move them into the `stage` directory. Then run the following command once for every month you want to reprocess. ``` php lib/pkp/tools/reprocessUsageStatsMonth.php YYYYMM @@ -231,7 +231,7 @@ php lib/pkp/tools/reprocessUsageStatsMonth.php 202210 php lib/pkp/tools/reprocessUsageStatsMonth.php 202211 ``` -If you want to have accurate monthly statistics, you will need to reprocess a whole month at a time. For example, if you are missing statistics from 2022-10-15 to 2022-11-12, you would need to reprocess logs for every day of both months in order to have accurate monthly stats for those months. +If you want to have accurate monthly statistics, you will need to reprocess a whole month at a time. For example, if you are missing statistics from 2022-10-15 to 2022-11-12, you would need to reprocess logs for every day of both months to have accurate monthly stats for those months. ### Things to know @@ -249,7 +249,7 @@ Statistics are compiled once a day. No statistics will appear until 24 hours aft You can tell if the scheduled task is being run by looking in the log directory at `/usageStats`. Once a log file has been processed, it will be moved to the `archive` directory. Learn more about the [log files](/dev/documentation/en/statistics#understanding-the-log-files). -If you see log files in the archive, but still do not have any statistics, inspect the URLs in the log entries. Does the URL in the log files exactly match the `base_url` in my configuration? Does it point to a published submission in a journal, press or preprint server? +If you see log files in the archive, but still do not have any statistics, inspect the URLs in the log entries. Does the URL in the log files exactly match the `base_url` in my configuration? Does it point to a published submission in a journal, press, or preprint server? ### I have enabled geographic statistics, but the geographic report doesn't include any data @@ -257,11 +257,11 @@ The application uses the visitor's IP address to determine their location. In or ### I upgraded from an old version of OJS and I want to have stats from a long time ago -If you have been running the application for many years, you may have periods during which no stats were recorded. For example in versions of OJS 2. You may be able to recover these stats if you have the Apache access logs from this period. Read how to [convert log files](#recover-lost-data). +If you have been running the application for many years, you may have periods during which no stats were recorded. For example, in versions of OJS 2. You may be able to recover these stats if you have the Apache access logs from this period. Read how to [convert log files](#recover-lost-data). ### I’ve seen some OJS journals that display nice-looking article usage metrics on article landing pages. How do I configure that? -This is a theme option. If you theme supports it, you can enable it at **Settings** > **Website** > **Appearance** > **Theme**. +This is a theme option. If your theme supports it, you can enable it at **Settings** > **Website** > **Appearance** > **Theme**. ### If I replace a publication's file, will the download count reset to 0? @@ -281,7 +281,7 @@ What to do when you [don't see any stats](#i-dont-see-any-statistics). ### When I try to download a report, I get a blank page, a 500 error, or a PHP memory limit error, such as "Memory limit exhausted". -This happens when the amount of data you are trying to download exceeds the server’s capacity to deliver it. This can be resolved by trying to download a smaller data set, for example reducing the date range, or by increasing the server's resource (for example PHP's `memory_limit` or `max_execution_time`). +This happens when the amount of data you are trying to download exceeds the server’s capacity to deliver it. This can be resolved by trying to download a smaller data set, for example reducing the date range, or by increasing the server's resource (for example, PHP's `memory_limit` or `max_execution_time`). ### I need to reprocess some log files, or troubleshoot a rejected log file. diff --git a/admin-guide/en/troubleshooting.md b/admin-guide/en/troubleshooting.md index 39b40c6debea..388963a5d2e2 100644 --- a/admin-guide/en/troubleshooting.md +++ b/admin-guide/en/troubleshooting.md @@ -2,7 +2,7 @@ title: Troubleshooting - Admin Guide - PKP Developer Docs description: How to fix some common problems encountered when deploying OJS, OMP or OPS. book: admin-guide -version: 3.4 +version: 3.5 --- # Troubleshooting @@ -13,7 +13,7 @@ version: 3.4 It is difficult to prescribe exact steps towards setting proper file permissions, as so much depends on the server's operating system, web server, and PHP setup. -In general, you want your permissions set such that your webserver can read and write (recursively) to the `config.inc.php` `files_dir`, and to `cache/`, and `public/`. Optionally, for added features and reduced security, you can enable write to `config.inc.php`, to `plugins/` and perhaps to the locale `.xml` files. Your webserver should have read-only access to all other files and directories distributed in the package. +In general, you want your permissions set such that your webserver can read and write (recursively) to the `config.inc.php` `files_dir`, and to `cache/`, and `public/`. Optionally, for added features and reduced security, you can enable write to `config.inc.php`, to `plugins/` and perhaps to the locale `.po` files. Your webserver should have read-only access to all other files and directories distributed in the package. Start by checking which server API PHP uses on your server. If OJS, OMP, or OPS is already installed, log in as Site Administrator, click "System Information", and at the bottom of the page, click "Extended PHP Information". Find the line that says "Server API". Depending on which API you are using (mod_php/SAPI or CGI/FastCGI), permissions should be set as follows. @@ -52,7 +52,7 @@ or #### But What About Shared Hosts? -With some shared hosts (for example, if your only access is via cPanel or a similar web-based admin tool), you may not have the ability to change the file ownership, and your webserver is effectively running as your user. In that case, you may still have the ability to protect your files by making them non-writable by your own user (even though this sounds counter-intuitive). In a shared host, you will almost certainly want to deny world permissions to your files, but look to the documentation and support for your host in particular. +With some shared hosts (for example, if your only access is via cPanel or a similar web-based admin tool), you may not be able to change the file ownership, and your webserver is effectively running as your user. In that case, you may still be able to protect your files by making them non-writable by your own user (even though this sounds counter-intuitive). In a shared host, you will almost certainly want to deny world permissions to your files, but look to the documentation and support for your host in particular. #### A Note on Security Configurations @@ -90,7 +90,7 @@ Note that this situation often occurs when uploading a modified copy of the main ## Character Encoding -Character encoding issues mostly crop up in two situations: when journals are migrated from another platform to OJS; or (more commonly) when an OJS journal is migrated from another server to our servers. +Character encoding issues mostly crop up in two situations: when journals are migrated from another platform to OJS; or (more commonly) when an OJS journal is migrated between servers. It’s often helpful to check the current database settings to ensure that you’re working in the character set that you think you’re working with. Once logged into MySQL, try the following: @@ -150,13 +150,13 @@ The following conversion steps and import process can be used to resolve these i #### Common Problem #2: double-quotes with encoding issue on DUMP files -During migration/upgrade from lib-ojs server to sfulib MySQL dump files from former may present encoding characters issue related to double-quotes, e.g.: “learning,â€<9d> which should be “learning,” even using correct UTF8 collation to export from Database. +During migration or upgrade, MySQL dump files may present encoding characters issue related to double-quotes, e.g.: “learning,â€<9d> which should be “learning,” even using correct UTF8 collation to export from the database. -This problem shows up when users copy-and-paste fancy/smart quotes from MS Word which uses the windows-1252 character set that doesn't match with anything in UTF8. Which results in this sequences that look like “learning,â€<9d>. +This problem can appear when users copy-and-paste fancy/smart quotes from MS Word which uses the windows-1252 character set that doesn't match with anything in UTF8. Which results in this sequence that looks like “learning,â€<9d>. The following steps can be used to resolve this encoding issue: -* Install on your local machine [ftfy](https://ftfy.readthedocs.io/en/latest/), as it is a python tool it will require python3 as well +* Install on your local machine [ftfy](https://ftfy.readthedocs.io/en/latest/), which will require python3 as well * Edit the command-line ftfy executable cli.py (it may be in a different path depending on your environment.): `/usr/local/lib/python3.6/site-packages/ftfy/cli.py` * Around line 100 (`$ vim +100 cli.py`) add an extra parameter 'uncurl_quotes=False' to the fix_file function. It will then look as follows: @@ -234,7 +234,7 @@ Be sure to revert this change when you are finished. ### What is a stacktrace and how do I display them in OxS? -A stacktrace shows the route through the code taken to display the current page. When an error is displayed, a stacktrace is often helpful in helping to track down how the error is being caused, by letting the developer step through the code and see what route they must take to reproduce the error. +A stacktrace shows the route through the code taken to display the current page. When an error is displayed, a stacktrace is often helpful to track down how the cause of the error, by letting the developer step through the code and see what route they must take to reproduce the error. To enable stacktracing on errors in OxS, turn on the 'show_stacktrace' option in `config.inc.php`. An example stacktrace will look like this: diff --git a/admin-guide/index.md b/admin-guide/index.md index b3d7da80bd11..3c078db0df2c 100644 --- a/admin-guide/index.md +++ b/admin-guide/index.md @@ -1,13 +1,13 @@ --- isBookIndex: true book: admin-guide -version: 3.4 +version: 3.5 --- # PKP Administrator's Guide * [English](en/) -The PKP Administrator's Guide provides guidance for administering PKP applications, including Open Journal Systems \(OJS\), Open Monograph Press \(OMP\) and Open Preprint Systems \(OPS\). It is written by and for systems administrators - those who are responsible for the installation, upgrading and general maintenance of the system. +The PKP Administrator's Guide provides guidance for administering PKP applications, including Open Journal Systems (OJS), Open Monograph Press (OMP) and Open Preprint Systems (OPS). It is written by and for systems administrators - those who are responsible for the installation, upgrading and general maintenance of the system. ## Contributors diff --git a/faq/en/site-administration.md b/faq/en/site-administration.md index 7d3c9a3d0470..7bd094c27417 100644 --- a/faq/en/site-administration.md +++ b/faq/en/site-administration.md @@ -5,7 +5,7 @@ showPageTOC: true # Site Administration -For additional questions and answers, see the [source-code FAQ](https://raw.githubusercontent.com/pkp/ojs/main/docs/FAQ). +For more information about how to administer OJS, OMP, or OPS, see the [Administrator's Guide](/admin). ## How can I create a backup of my site? @@ -13,7 +13,7 @@ To properly backup an OJS, OMP, or OPS system, the following should be backed up * The OJS database, using the tools provided by your DBMS (e.g., `mysqldump` for MySQL, `pg_dump` for PostgreSQL) * The base OJS directory -* The non-public files directory (the directory specified by the `files_dir` configuration option), which is typically outside of the base OJS or OCS directory (this step does not apply to the PKP Harvester). +* The non-public files directory (the directory specified by the `files_dir` configuration option), which is typically outside of the base OJS/OMP/OPS directory (this step does not apply to the PKP Harvester). This backup procedure can be easily integrated into any automated backup mechanism. There is also a [Backup plugin](https://github.com/asmecher/backup) available in the Plugin Gallery for Site Administrators to generate and download of backups of an OJS/OMP/OPS 3.x installation. diff --git a/readme.md b/readme.md index ac7fb7b631ad..ee6c6763200e 100644 --- a/readme.md +++ b/readme.md @@ -155,7 +155,7 @@ Install [redoc-cli](https://www.npmjs.com/package/redoc-cli) globally if you don npm install -g redoc-cli ``` -From the root directory of the the docs repository, run the following command to build the docs. +From the root directory of the docs repository, run the following command to build the docs. ``` redoc-cli bundle ~/3.3.json --options=.redoc.json --output=dev/api/ojs/3.3.html