Skip to content

InstallationGuideOJS

Jump to bottom
Eftychia Koukouraki edited this page Aug 25, 2022 · 9 revisions

This page describes how to install OJS for macOS and Linux. These are individually created instructions with an eye on developing OJS plugins. The official instructions can be found here:

Linux (Ubuntu 18.04)

0. Preparation

Check PHP

Open your terminal and type in:

php -v

If your PHP version is older than 7.4.x, then please update to it. For Ubuntu, you can follow this guide.

If you do not have PHP then install it with this command:

sudo apt-get install php

Make sure you have the PHP extensions xml, mbstring, intl, curl and zip installed. You can add extensions to PHP with the command:

sudo apt-get install php-<extension name>

(If this does not work for you try adding the php version, e.g. sudo apt-get install php7.4-xml.)

Check Apache

Your Apache version, it should be at least 1.3.2.

Other Tools

You also need the composer and npm command line tools. Tested with composer 2.3.10 and npm 16.13.1.


1. Fork and Clone the OJS Repository

Fork the OJS repository on github. Clone your fork to your local computer via git clone.

Change into the new repository with cd ojs.

Also change to the branch to stable-3_3_0 to avoid problems:

git checkout stable-3_3_0

In this folder run:

git submodule update --init --recursive

After the last command has finished running:

cp config.TEMPLATE.inc.php config.inc.php

2. PostgreSQL

There are two distinct approaches for PostgreSQL integration into OJS on Ubuntu.
You can do a native installation of PostgreSQL or run it in a docker container.
Both approaches are laid out in the following section.
But there some steps you have to do either way.

First you have to check if you have PostgreSQL installed and if the version is compatible with OJS. For this you open your terminal and type

psql -V

If you PostgreSQL is older than 9.1.5 please update to a newer one.

Also if you do not have PostgreSQL installed run this command:

sudo apt-get install postgresql

Now install the PostgreSQL extension for php:

sudo apt-get install php-pgsql

(If this does not work for you try adding the php version, e.g. sudo apt-get install php7.4-pgsql.)


2.A Native PostgreSQL Installation

Create a new a user in PostgreSQL with the following command:

sudo -u postgres createuser -P -d ojs

The username can be anything you like but we like to keep it simple :)

Then you are asked to create a password for this user. Again this can be anything you like but you need to remember it.

Finally create a database with the new user:

sudo -u postgres createdb -O ojs ojs_db

Back in the cloned repository folder open the new config.inc.php in your editor of choice. In the editor go the [database] section and enter your PostgreSQL data like so:

driver = postgres
host = localhost
username = ojs
password = ojs
name = ojs_db

2.B Docker Installation

Alternatively, you can also run PostgeSQL in a Docker container. Although, the native installation is recommended.

docker run --name ojs-dev-postgres -p 5432:5432 -e POSTGRES_USER=ojs -e POSTGRES_PASSWORD=ojs -v $(pwd)/postgres-data:/var/lib/postgresql/data postgres:13

This runs the latest release of PosgreSQL version 13 on the default port on the host machine, and creates a user ojs with the same password. Optionally, you can also mounts a local directory for persistent data storage.

Before starting the docker it is important to stop the native installation of PostgreSQL.

sudo service postgresql stop

If you want to start and stop the container, use

docker start ojs-dev-postgres
docker stop ojs-dev-postgres

Docker is also great to try out different versions or different databases.

To run configuration commands in a Docker container to the same effect, you can use the psql shell to connect to the database in the container and create the database:

psql -h localhost -U ojs

Then you have to enter your password, which we set to ojs at the creation of the container. In the now open prompt you enter:

CREATE DATABASE ojs_db;

In case of errors check if there is already a database by that name:

\l

If that is the case please delete that database:

DROP DATABASE ojs_db;

and run the CREATE DATABASE command again.

Now the database for OJS is ready.
You can quit the psql shell with the command:

\q

Back in the cloned repository folder open the new config.inc.php in your editor of choice. In the editor go the [database] section and enter your PostgreSQL data like so:

driver = postgres
host = localhost
username = ojs
password = ojs
name = ojs_db

3. Start OJS on localhost

Run the following commands consecutively in the ojs folder:

composer --working-dir=lib/pkp update
composer --working-dir=plugins/paymethod/paypal update
composer --working-dir=plugins/generic/citationStyleLanguage update

Install the JavaScript (development) dependencies and tools with npm:

npm install
npm run build

(If there are problems with the npm packages try npm audit fix.)

Start the server with:

php -S localhost:8000

4. Finish your OJS installation

  1. Go to localhost:8000 in your browser. And follow the instructions on the page.

  2. Start the database with:

    Approach A Native Installation(might already be running):

    sudo service postgresql start

    Approach B Docker Installation:

    docker start ojs-dev-postgres
docker stop ojs-dev-postgres

  3. Check that all files under the "Pre-Installation" step are writable. There should be a Yes next to each file name. You can edit permissions with the chmod 777 <filename_or_foldername> command.

  4. Create an administrator account with username, password, and email.

  5. Set the locales and character sets.

  6. Create a folder for upload files which accessible to OJS and write the path into the specified field. It is standard location is as a directory called files at the same level as the cloned ojs folder.

  7. Make sure PostgreSQL is selected as the database driver. If it shows [PostgreSQL] OJS can not find your PGSQL installation. In that case check if you have PGSQL and the php-extension installed (view 0. Preparation).

  8. Enter your user and its password that you have created in Step 2 into the database form.

  9. For the database name you can enter the already existing database or you enter a new database name.

  10. Do not change the OAI settings.

  11. Press Install Open Journal Systems .


🎉 You are done 🎊

Typical pitfalls

  1. Only start the php -S localhost:8000 in the ojs folder. Otherwise the OJS server will not find its subdirectories.

  2. Plugins will only work if a journal is instituted!

  3. If have to setup a new installation, delete everything in your files directory. Otherwise this leeds to conflicts.



macOS (11.2.2)

0. Preparation

Check PHP

Open your terminal and type in:

php -v

If your php version is older than 7.4. please update or install it. You can follow this guide. Please note that there may be problems when using php 8.0, with 7.4 it should work.

Check PostgreSQL

Open your terminal and type in:

psql -V

If you PostgreSQL is older than 9.1.5 please update to a fitting one.

Also if you do not have PostgreSQL installed you can follow this guide to install the package manager Homebrew. Then you are able to install PostgreSQL via Homebrew by typing in:

brew install postgresql

Check Apache

Your apache version should be at least 1.3.2. If you do not have installed Apache you can follow this guide.

Other Tools

You also need the composer command line tool. In addition you need to have npm installed.


1. Fork and Clone the OJS Repository

Fork the OJS repository on github. Clone your fork to your local computer via git clone.

Change into the new repository with cd ojs.

In this folder run:

git submodule update --init --recursive

After the last command has finished run:

cp config.TEMPLATE.inc.php config.inc.php

2. Set up PostgreSQL

Start PostgreSQL:

brew services start postgresql

Get into the PostgreSQL environment:

psql postgres

Create a new a user in PostgreSQL with the following command:

CREATE ROLE ojs WITH PASSWORD 'ojs';

This can be anything you like but you need to remember it. :) You can control the created role by typing \du.

Finally create a database with the new user:

CREATE DATABASE ojs_db;

You can control the created database by typing \list.

Now you need to grant all rights on the created database, here ojs_db, to the user created above, here to the role ojs.

GRANT ALL PRIVILEGES ON DATABASE ojs_db TO ojs;

Back in the cloned repository folder open the new config.inc.php in your editor of choice. In the editor go to the [database] section and enter your PostgreSQL data like so:

driver = postgres
host = localhost
username = ojs
password = ojs
name = ojs_db

You can also later edit these settings during the installation process in the browser.


3. Get OJS on to localhost

Run the following commands consecutively in the ojs folder:

composer --working-dir=lib/pkp update

composer --working-dir=plugins/paymethod/paypal update

composer --working-dir=plugins/generic/citationStyleLanguage update

Install the dependencies with npm:

npm install
npm run build

(If there are problems with the npm packages try npm audit fix.)

Start the server with:

php -S localhost:8000

4. Finish your OJS installation

  1. Go to localhost:8000 in your browser. And follow the instructions on the page.

  2. Start PostgreSQL with (if it is not already started):

    brew services start postgresql

    Later on if you do not want to use ojs you can close it you can stop it with

    brw services stop postgresql

  3. Check that all files under Pre-Installations steps are writable. It should be a Yes next to the file name. You can edit permissions with the chmod 777 <filename_or_foldername> command. With ls -l you can check if the rights got adapted.

  4. Create an administrator account with username, password, and email.

  5. Set the locales and character sets.

  6. Create a folder for upload files which accessible to OJS and write the path into the specified field.

  7. Make sure PostgreSQL is selected as the database driver.

  8. Enter your user and its password that you have created in Step 2 into the database form.

  9. For the database name you can enter the already existing database or you enter a new database name.

  10. Do not change the OAI settings.

  11. Press Install Open Journal Systems .


🎉 You are done 🎊
Clone this wiki locally