ElkArte 2.0 Install & Upgrade Guide

ElkArte Forum

Welcome

Welcome, and thanks for using ElkArte!

If you run into trouble at any point, the community is available at:

https://www.elkarte.net/community/index.php

Important: Upgrading from ElkArte 1.x is not an in-place upgrade. ElkArte 2.0 must be installed in a separate directory. Jump to Upgrading from ElkArte 1.x to 2.0.

New Installation

  • Minimum requirements
  • Performance recommendations
  • Upload files
  • Set file permissions
  • Create database
  • Run installer
  • The installed.lock file
  • Finish up

Upgrading from 1.x

Minimum installation requirements

Not sure if your server qualifies? Run the installer anyway — it catches most problems automatically.

  • Web server: Apache 2.4+, Nginx 1.18+, or another PHP compatible server
  • PHP 8.1+ with:
    • engine = On
    • session.save_path valid directory
    • file_uploads = On
    • upload_tmp_dir valid directory
  • Required extensions: json, gd, curl, mysqli or pgsql, fileinfo, exif, libxml, dom
  • Database
    • MySQL 5.7+
    • MariaDB 10.2+
    • PostgreSQL 9.5+
  • Privileges: SELECT, INSERT, UPDATE, DELETE, ALTER, CREATE, DROP, TRUNCATE, INDEX
  • Storage: ~30 MB server space (more for attachments, avatars, and cache); 2 MB database minimum

Recommendations for best performance

  • OS: Linux or other Unix system
  • Web server: Apache 2.4+ with AcceptPathInfo enabled, or Nginx 1.18+ with a suitable try_files rewrite rule
  • PHP 8.2+ with:
    • memory_limit ≥ 128M
    • max_execution_time and max_input_time ≥ 30
    • post_max_size / upload_max_filesize sized to your attachment needs
    • session.use_trans_sid → Off
    • OPcache enabled (ext-zend-opcache)
Extension Purpose
ext-imagick (ImageMagick 3.x+) Superior image resizing and thumbnails, preferred over GD
ext-gd (GD 2.3+) Baseline image support; install even if ImageMagick is present (used for CAPTCHA and avatars)
ext-intl Improved Unicode and locale handling
ext-iconv Character set conversion
ext-mbstring Multibyte string functions
ext-zlib Gzip output compression
ext-apcu In-process data caching
ext-imap Email-to-post and notification processing
  • Database: MySQL 8.0+, MariaDB 10.6+, or PostgreSQL 14+

Upload files

Download the latest release from:

https://github.com/elkarte/Elkarte/releases

Upload the files to a new directory such as:

/public_html/forum

Verify these directories exist:


sources/ElkArte/
themes/default/
install/
Addons/
Some FTP clients silently skip files. If the installer reports missing components, check your transfer logs and re-upload as needed.

Additional languages

  1. Download language packs from https://translations.elkarte.net/
  2. Install them with the system's Addon Manager after you have installed ElkArte.

Files will be installed under:

sources/ElkArte/Languages/AREA/[language].php

Set file permissions

Set permissions using CHMOD.

  • Files: 644, 664, or 666
  • Directories: 755, 775, or 777

The following paths must be writable:


/Addons
/attachments
/avatars
/avatars_user
/cache
/install
/packages
/smileys
/sources
/themes
db_last_error.txt
Settings.php
Settings_bak.php

Create a database and user

Create a database and database user using your hosting control panel.

Required privileges:


SELECT
INSERT
UPDATE
DELETE
ALTER
CREATE
DROP
TRUNCATE
INDEX

Starting the installer

Open your forum URL in a browser:

https://www.yourdomain.com/forum/

ElkArte detects the installation state automatically:

Condition Result
No installed.lock, no Settings.php, install/ present Redirected to install/install.php
No installed.lock, valid Settings.php, install/ present Redirected to install/upgrade.php

No need to navigate to these scripts directly.

Basic forum settings

Setting Description
Forum Name Your forum's display name (default: My Community). Easily changed later.
Forum URL Full URL to the forum root, without a trailing slash.
Database Sessions More reliable than file-based sessions, especially on shared hosting.

Database settings

Setting Description
Database type mysqli (MySQL/MariaDB) or postgresql
Server name Usually localhost
Username Your database user
Password Your database password
Database name The database you created
Table prefix Default elk_, useful if multiple apps share one database

Administrator account

Enter a username, password, and email for the primary admin account. This account controls the Administration Center.

The installed.lock file

After installation ElkArte creates installed.lock in the forum root. This file:

  • Blocks install.php and upgrade.php from running again, preventing accidental reinstallation or data loss
  • Records the installed version and timestamp (plain text, safe to inspect)
  • Must be deleted before the upgrader can run — only do this when you intentionally want to upgrade
Removing the install/ directory entirely after installation is a best practice, but the lock file alone is enough to keep the installer from running.

Finishing everything up

Remove installer files when finished.


install/install.php
install/upgrade.php
install/install_2-0.php
install/upgrade_2-0.php

Removing the entire install/ directory is recommended.

Good luck with your new forum!

ElkArte Forum Contributors

Upgrading from ElkArte 1.x to 2.0

Warning: ElkArte 2.0 is not an in-place upgrade from 1.x. The directory and namespace structure changed entirely. Do not overwrite your 1.x files with 2.0.

Help is available at: https://www.elkarte.net/community/index.php.

Overview

  • Back up your database and files
  • Install ElkArte 2.0 in a new directory
  • Restore the database to a new database (recommended)
  • Copy Settings.php from the old install
  • Ensure avatars and attachments are accessible
  • Delete installed.lock if it exists
  • Run the upgrader
  • Verify the installation
  • Clean up

Back up your data

Caution: Do not skip this step. A full backup protects you if something goes wrong.

Using phpMyAdmin

  1. Select your forum database
  2. Click Export
  3. Follow the export wizard

Using a hosting control panel

Use your hosting provider's Backup or Backup Wizard tool.

Also back up these directories:


attachments/
avatars_user/
smileys/

Upload ElkArte 2.0 to a new directory

Upload the ElkArte 2.0 release to a new directory.


/var/www/elkarte2/

Do not upload into your existing 1.x directory.


/var/www/elkarte1/

Set file permissions as described in Set file permissions.

Restore the database

Restore your existing database to a new database, for example:


elkarte20

This step is optional but strongly recommended so you can test the upgrade safely.

Copy Settings.php

Copy only the Settings.php file from your 1.x installation.


/var/www/elkarte1/Settings.php
        ->
/var/www/elkarte2/Settings.php

The upgrader uses this file to connect to your existing database.

No manual editing is required; paths will be updated automatically.

Avatars and attachments

User uploaded files do not need to be moved if the new installation can access them.

Example:


/var/www/elkarte2/  ->  can read
/var/www/elkarte1/attachments

If the new directory cannot access the old files, copy them manually:


/var/www/elkarte1/avatars_user/ -> /var/www/elkarte2/avatars_user/
/var/www/elkarte1/attachments/  -> /var/www/elkarte2/attachments/
/var/www/elkarte1/smileys/      -> /var/www/elkarte2/smileys/
If attachmentUploadDir in your admin panel points outside the forum root and remains accessible, nothing needs to be changed.

Custom add-ons

1.x add-ons are not compatible with 2.0. Install new versions rather than copying the old Addons directory.

Delete installed.lock

The upgrader will not run if the lock file exists.

Delete it from the new installation:


/var/www/elkarte2/installed.lock

Run the upgrader

Open the new forum URL:


https://www.yourdomain.com/forum2/

ElkArte will automatically detect the upgrade state and start the upgrader.

Upgrade options

Option Description
Backup database with prefix backup_ Creates backup tables before modifying the database
Maintenance mode Locks the forum during the upgrade
Extra debug output Displays detailed logs if the upgrade encounters problems

Update your web server

After upgrading, update your web server to point to the new directory.

Apache

Update the DocumentRoot in your virtual host configuration.

Nginx

Update the root directive in the server block.

If $boardurl already points to the correct domain, only the filesystem path needs to change.

Clean up

Remove upgrade scripts from the server:


install/upgrade.php
install/upgrade_1-0.php
install/upgrade_1-1.php
install/upgrade_2-0.php

Removing the entire install/ directory is recommended.

Verify:

  • ✅ installed.lock exists in the new forum root. If it's missing, the upgrade didn't complete — check the upgrade log.
  • ✅ Your site loads correctly from the new directory.
  • ✅ Once verified, archive or remove the old 1.x directory.

Good luck!

ElkArte Forum Contributors