Skip to main content
OJS for Everyone Logo
OJS for EveryoneThe Practical GuidebookRSYN Research LLP

Installing & Upgrading

Questions for site administrators handling fresh installs, upgrades, and server configuration.

Where can I find help upgrading OJS?​

The PKP Community Forum is the primary support channel for upgrade questions. It has a dedicated section for installation and upgrade issues, and many experienced OJS administrators actively help there. Before posting:

  • State your current OJS version and the target version you are upgrading to.
  • Describe the exact error message or symptom, including any output from the upgrade command.
  • Mention your server OS, PHP version, and database type and version.

For step-by-step upgrade instructions, the PKP Technical Upgrade Guide documents the process for each major version. Key steps for a typical upgrade are:

  1. Back up your database and files_dir before anything else.
  2. Replace the OJS codebase (keeping your config.inc.php and public/ directory).
  3. Run the upgrade script: php tools/upgrade.php upgrade
  4. Check the error log for any warnings after completion.
warning

Never skip major versions when upgrading. If you are on OJS 3.1 and want to move to 3.5, upgrade through each minor version series in sequence (3.1 → 3.2 → 3.3 → 3.4 → 3.5). Skipping versions can cause data migration errors that are difficult to recover from.

I get a database error after installation — "Table 'ojs.journals' doesn't exist" — why?​

This error means the OJS database tables were never created. It typically happens when the web-based installer could not connect to the database with write permissions, or when it did not complete the SQL import step successfully.

To recover:

  1. Restore a clean starting state — If config.inc.php was written but the database is empty or partially created, drop all tables in the database (or drop and recreate the database itself), then restore config.TEMPLATE.php by renaming it to config.inc.php so the installer treats the system as fresh.

  2. Re-run the installer — Navigate to your OJS URL in a browser. On the installer form, uncheck "Create new database" (the database should already exist and be empty) and fill in the correct database credentials.

  3. Use the Manual Install option — If the installer continues to fail, use the "Manual Install" link at the bottom of the installer page. This generates the full SQL schema which you can copy and run directly in phpMyAdmin, MySQL CLI, or psql. Then click "Complete Install" to write config.inc.php.

info

The most common cause of this error is a database user that lacks CREATE TABLE privileges. Confirm your database user has full privileges on the OJS database — GRANT ALL PRIVILEGES ON ojs_db.* TO 'ojs_user'@'localhost';

How should file permissions be set?​

File permission requirements vary by operating system and server configuration, but the general principle is: the web server process must be able to write to specific OJS directories.

The directories that need to be writable by the web server user (typically www-data on Debian/Ubuntu, apache on RHEL/CentOS) are:

  • files/ (or wherever files_dir points in your config.inc.php — this is the private uploads directory and must be outside the web root)
  • public/ (the publicly accessible uploads directory inside the web root)
  • cache/ (template and data cache)

A typical permission setup on a Linux server:

chown -R www-data:www-data files/ cache/
chmod -R 750 files/
chmod -R 755 public/ cache/
Files directory security

The files/ directory stores uploaded manuscripts and other sensitive content. Use 750 (not 755) so it is not world-readable. Only the web server user and your own user account need access. The exact permissions depend on your PHP execution model (mod_php shares the Apache user; PHP-FPM typically uses a dedicated user per site).

The PKP Admin Guide section on permissions describes the exact requirements and provides examples for different server configurations, including shared hosting environments where you may not control the web server user.

Further Reading​