Merge pull request #1091 from NateWr/i1090_quick_start

#1090 Add Quick Start to admin guide and change config to Deployment …

_includes/cards/ojs3/developer-docs.md

@@ -5,7 +5,7 @@ Guides to host and deploy OJS, write themes and plugins, and contribute new feat
 
 ---
 
-- [Administrator's Guide](/admin-guide/)
+- [Administrator's Guide](/admin-guide/en/)
 - [How to Upgrade](/dev/upgrade-guide/en/)
 - [Main Documentation](/dev/documentation/en/)
 - [Theming Guide](/pkp-theming-guide/)

_includes/cards/omp3/developer-docs.md

@@ -5,9 +5,9 @@ Guides to host and deploy OJS, write themes and plugins, and contribute new feat
 
 ---
 
-- [Administrator's Guide](/admin-guide/)
-- [How to Upgrade](/dev/upgrade-guide/)
-- [Main Documentation](/dev/documentation/)
+- [Administrator's Guide](/admin-guide/en/)
+- [How to Upgrade](/dev/upgrade-guide/en/)
+- [Main Documentation](/dev/documentation/en/)
 - [Theming Guide](/pkp-theming-guide/)
-- [Plugin Guide](/dev/plugin-guide/)
+- [Plugin Guide](/dev/plugin-guide/en/)
 - ... and [more](/dev/)

_includes/cards/ops3/developer-docs.md

@@ -5,9 +5,9 @@ Guides to host and deploy OJS, write themes and plugins, and contribute new feat
 
 ---
 
-- [Administrator's Guide](/admin-guide/)
-- [How to Upgrade](/dev/upgrade-guide/)
-- [Main Documentation](/dev/documentation/)
+- [Administrator's Guide](/admin-guide/en/)
+- [How to Upgrade](/dev/upgrade-guide/en/)
+- [Main Documentation](/dev/documentation/en/)
 - [Theming Guide](/pkp-theming-guide/)
-- [Plugin Guide](/dev/plugin-guide/)
+- [Plugin Guide](/dev/plugin-guide/en/)
 - ... and [more](/dev/)

admin-guide/en/SUMMARY.md

@@ -1,16 +1,17 @@
 # Table of contents
 
-* [Getting Started](./)
-  * [Requirements](./requirements)
-  * [Download](./download)
-  * [Configure](./configure)
-  * [Install](./install)
-* [Advanced Configuration](./advanced)
-  * [Email](./advanced-email)
-  * [Jobs](./advanced-jobs)
-  * [Users](./advanced-users)
-  * [Multi-tenant](./advanced-multi-tenant)
-  * [Sandbox](./advanced-sandbox)
+* [Introduction](./)
+* [Getting Started](./getting-started)
+  * [Requirements](./getting-started#system-requirements)
+  * [Download](./getting-started#download)
+  * [Install](./getting-started#install)
+* [Deployment](./deploy)
+  * [Configuration](./deploy#configure)
+  * [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)

admin-guide/en/advanced-email.md → admin-guide/en/deploy-email.md

@@ -10,7 +10,7 @@ version: 3.4
 > 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/configure#email-server).
+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
 
@@ -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/configure#email-server).
+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`:
 
@@ -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](./advanced-jobs).
+Next, learn about how to improve performance with the [job runner](./deploy-jobs).

admin-guide/en/advanced-jobs.md → admin-guide/en/deploy-jobs.md

@@ -201,4 +201,4 @@ Jobs should never be run while the site is under maintenance, for example during
 
 ---
 
-Learn more about handling [user accounts](./advanced-users).
+Learn more about handling [user accounts](./deploy-users).

admin-guide/en/advanced-multi-tenant.md → admin-guide/en/deploy-multi-tenant.md

@@ -49,4 +49,4 @@ Then add a privacy statement by logging in as an administrator and going to **Ad
 
 ---
 
-Learn how to prevent unwanted emails, deposits and other tasks from being run in a [sandboxed test installation](./advanced-sandbox).
+Learn how to prevent unwanted emails, deposits and other tasks from being run in a [sandboxed test installation](./deploy-sandbox).

admin-guide/en/advanced-sandbox.md → admin-guide/en/deploy-sandbox.md

@@ -49,15 +49,15 @@ 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](./advanced-jobs#workers), kill those processes. You may need to disable [Supervisor](./advanced-jobs#workers) or any process monitor that will restart the workers.
+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](./advanced-jobs#how-to-monitor-jobs).
+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
 

admin-guide/en/advanced-users.md → admin-guide/en/deploy-users.md

@@ -157,4 +157,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](./advanced-multi-tenant).
+The next section describes best practices for running lots of independent journals, presses or preprint servers from one [multi-tenant install](./deploy-multi-tenant).

admin-guide/en/configure.md → admin-guide/en/deploy.md

@@ -1,24 +1,39 @@
 ---
-title: Configure - Admin Guide - PKP Developer Docs
-description: A guide to the configuration settings for Open Journal Systems (OJS), Open Monograph Press (OPS) or Open Preprint Systems (OPS).
+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
 ---
 
-# Configure
+# Deployment
 
-The configuration file is where you will connect the application to a database, email server and domain. There are dozens of configuration settings to customize your install. This guide will only cover the most important.
+> Read the [Getting Started](./getting-started) guide first to learn how to download and install the software.
+{:.notice}
 
-Edit the configuration file on your server.
+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.
 
-```bash
-# Don't want to use vim?
-# Use any text editor you prefer
+## What you need to know
 
-vim <web-root>/config.inc.php
-```
+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.
 
-Find the `base_url` setting in the file 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 install.
 
 ```
 base_url = "<url>"
@@ -30,25 +45,15 @@ Add this domain to your `allowed_hosts` list.
 allowed_hosts = '["<url>"]'
 ```
 
-Set your database credentials.
-
-```
-driver = mysqli
-host = localhost
-username = <username>
-password = <password>
-name = <database-name>
-```
-
-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.
+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 copy-pasting 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.
 
@@ -62,7 +67,7 @@ Every installation needs to have a secure files directory to ensure that private
 
 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`.
 
-Create the directory and change the permissions to allow the web server to write files and directories to it. Then edit the `config.inc.php` with the absolute path to the `files_dir`.
+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 = <path>
@@ -72,7 +77,7 @@ files_dir = <path>
 
 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](./advanced-email).
+> Not sure what to do here? Learn more about how to [configure an email server](./deploy-email).
 {:.notice}
 
 Turn SMTP on:
@@ -101,7 +106,7 @@ force_default_envelope_sender = On
 force_dmarc_compliant_from = On
 ```
 
-Learn more about the [envelope sender](./advanced-email#dmarc).
+Learn more about the [envelope sender](./deploy-email#dmarc).
 
 ## User Validation
 
@@ -114,9 +119,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 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:
 
@@ -138,11 +141,11 @@ If you are unable to configure this cron job, you must enable the Acron plugin a
 
 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](./advanced-jobs).
+Learn more about how to configure the [job runner](./deploy-jobs).
 
 ## Pretty URLs
 
-Enable URL rewriting on your server in order to change ugly URLs like `?journal=publicknowledge&page=article&op=view` into user-friendly URLs like `/publicknowledge/articles/view/1`.
+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.
 
@@ -156,13 +159,7 @@ The following is an example `.htaccess` file that can be used to enable `mod_rew
 </IfModule>
 ```
 
-Then edit the `config.inc.php` file to turn off `disable_path_info`.
-
-```
-disable_path_info = Off
-```
-
-And turn on `restful_urls`.
+Then edit the `config.inc.php` file to turn on `restful_urls`.
 
 ```
 restful_urls = On
@@ -174,4 +171,4 @@ The configuration file includes settings to control the default date formats, ma
 
 ---
 
-Once you have configured everything, you are ready to [run the install](./install).
+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.

admin-guide/en/download.md

@@ -55,4 +55,4 @@ Change the file permissions of the following files and directories to allow them
 
 ---
 
-Next, set database credentials and other [configuration settings](./configure).
+Next, set database credentials and other [configuration settings](./deploy).