Skip to main content ↑ ↓
Recent Posts
3
Announcements / ElkArte 2.0 Beta 1
Last post by Spuds -
The ElkArte Community is pleased to announce the first beta release of ElkArte 2.0. This release is intended for broad testing and evaluation :: it is not recommended for production use at this stage.

ElkArte 2.0 :: Install & Upgrade Guide
Welcome, and thanks for using, or at least trying, ElkArte.

Important

Upgrading from 1.x? ElkArte 2.0 is not an in-place upgrade :: it must be installed in its own directory.
Scroll down to Upgrading from ElkArte 1.x to 2.0 for detailed instructions
New Installation Steps

  • Minimum requirements
  • Performance recommendations
  • Upload files
  • Set file permissions
  • Create a database and user
  • Run the installer
  • The installed.lock file
  • Finish up
  • Upgrading from 1.x to 2.0


Minimum installation requirements
Not sure if your server qualifies? Run the installer anyway, it catches most problems automatically.
  • Web server: Apache 2.4+ or Nginx 1.18+ (or any server with PHP support)
  • PHP 8.1+ with these php.ini settings:
    •   engine -> On
    •   session.save_path -> a valid, writable directory
    •   file_uploads -> On
    •   upload_tmp_dir -> a valid directory
  • Required PHP extensions: json, gd, curl, mysqli OR pgsql, fileinfo, exif, libxml, dom
  • Database (one of):
    •   MySQL 5.7+
    •   MariaDB 10.2+
    •   PostgreSQL 9.5+
  • Database user 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 the best performance
  • OS: Linux or another Unix-based 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)
  • Recommended extensions:
    • 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 all files to a new, URL-accessible directory on your server (e.g. /public_html/forum).
* After uploading, confirm these directories are present:

Code: [Select]
sources/ElkArte/
themes/default/
install/
Addons/

Tip

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 systems Addon Manager after you have installed ElkArte.

Files will be installed under sources/ElkArte/Languages/AREA/[language].php

Set file permissions
Use CHMOD to set permissions after uploading.
  • Files: 644, 664, or 666
  • Directories: 755, 775, or 777

The following paths must be writable by the web server:

Code: [Select]
/Addons
/attachments
/avatars
/avatars_user
/cache
/install
/packages
/smileys
/sources
/themes
db_last_error.txt
Settings.php
Settings_bak.php

Create a database and a database user
Before running the installer, create a database and a dedicated database user. Most shared hosting control panels include a MySQL Databases or Database Wizard tool for this. Required privileges are: SELECT, INSERT, UPDATE, DELETE, ALTER, CREATE, DROP, TRUNCATE, INDEX

Starting the installer
Just visit your forum's URL in a browser: https://www.yourdomain.com/forum/ ElkArte detects the installation state automatically:

ConditionResult
No installed.lock, no Settings.php, install directory presentRedirected to install/install.php
No installed.lock, valid Settings.php, install directory presentRedirected to install/upgrade.php
There is no need to navigate to these scripts directly.

Basic forum settings
SettingDescription
Forum NameYour forum's display name (default: My Community). Easily changed later.
Forum URLFull URL to the forum root, without a trailing slash.
Database SessionsMore reliable than file-based sessions, especially on shared hosting.
Database settings
SettingDescription
Database typemysqli (MySQL/MariaDB) or postgresql
Server nameUsually localhost
UsernameYour database user
PasswordYour database password
Database nameThe database you created
Table prefixDefault 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 a successful install or upgrade, 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

Tip

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
Once installation completes, remove the installer files, either using the built-in cleanup option or manually:

Code: [Select]
install/install.php
install/upgrade.php
install/install_2-0.php
install/upgrade_2-0.php

Removing the entire install/ directory is the safest option and is recommended.

That's it,  good luck with your new site!
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.
Overview of Steps
  • Back up your database and files
  • Install ElkArte 2.0 in a new, separate directory e.g. /var/www/elkarte2
  • Restore the database to a new database, e.g. elkarte20 (optional, but HIGHLY recommended)
  • Copy Settings.php from your 1.x root into the 2.0 root  e.g. /var/www/elkarte1/Settings.php -> /var/www/elkarte2/Settings.php
  • Confirm the 2.0 installation can access your existing 1.x avatars and attachments directory (or copy them if needed)
  • Delete any installed.lock from the 2.0 root
  • If you are upgrading a backup DB (step 1) you must EDIT your Settings.php file and enter the correct database name in e.g. $db_name=elkarte20
  • Run the upgrader by visiting the new forum URL, the system redirects to the upgrader automatically
  • Visit the new forum URL, make sure everything works, then update your web server to point to the new directory if needed
  • Clean up


Back up your data

Caution

Don't skip this. A full backup is your safety net if anything goes wrong.
Using phpMyAdmin: Select your forum database -> click Export -> follow the wizard.
Using a hosting control panel: Use your host's Backup or Backup Wizard tool to export the database.

Back up your files as well, at minimum the attachments/, avatars_user/, and smileys/ directories.


Upload ElkArte 2.0 to a new directory
Upload the 2.0 release package to a **new directory**, for example: /var/www/elkarte2/

Do not upload into your existing 1.x directory (e.g. /var/www/elkarte1/).

Set file permissions as described in [Set file permissions](#set-file-permissions).


Create a new database table for 2.0
Restore the database to a new database, e.g. elkarte20 (optional, but HIGHLY recommended)
This step is optional but strongly recommended. It allows you to test the upgrade process without risking your live data.


Copy Settings.php
Copy only Settings.php from your 1.x root into the 2.0 root: /var/www/elkarte1/Settings.php  ->  /var/www/elkarte2/Settings.php

The upgrader uses Settings.php to connect to your database.  Paths are updated automatically during the upgrade. No manual edits needed Unless you did the optional (and correct) step of creating a new database for the conversion.  If so you must update the file and change $db_name to the new database !!


Avatars, Smileys and attachments
User-uploaded files don't need to be moved if the 2.0 installation can already read and write to their current location. For example, if /var/www/elkarte2 can access /var/www/elkarte1/attachments, no copying is required, the existing paths in the database will keep working.

If the 2.0 directory can't reach the old paths (different server, permissions, or a reorganized document root), copy these directories manually:

Code: [Select]
/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/

Note

If your admin panel defines a custom attachment path (attachmentUploadDir) that points outside the forum root and remains accessible, no change is needed.

Note

If you moved files, and even not, its a good idea to run repair_settings.php to allow easy updates to various directory locations and other key settings.  Be sure to get the version that is for 2.0 (check the forum)

Custom add-ons

Warning

1.x add-ons are notcompatible with 2.0. Do not copy the 1.x Addons/ directory, install 2.0-compatible versions instead.

Delete installed.lock
The 2.0 package uses an installed.lock file. The upgrader won't run while it's present. Delete it from the 2.0 root: /var/www/elkarte2/installed.lock  <- delete this if present.


Run the upgrader
Visit your new forum URL in a browser: https://www.yourdomain.com/forum2/  ElkArte detects Settings.php without a lock file and redirects to the upgrader automatically.


Upgrade options
OptionDescription
Backup database with prefix backup_Copies all tables before modification
Maintenance modeLocks the forum during the upgrade, recommended for live sites
Extra debug outputVerbose logging, useful if the upgrade stalls or fails


Update your web server if needed
Once the upgrade completes, point your web server at the 2.0 directory.
  • Apache: Update DocumentRoot in your virtual host configuration or .htaccess
  • Nginx: Update the root directive in your server block

If $boardurl in Settings.php already points to the correct domain, only the server-side path needs updating.


Clean up
Remove the upgrade & install scripts from the server the installed.lock file is used to prevent access via ElkArte scripts, however removing the entire install/ directory is still the safest option.

Code: [Select]
install/install.php
install/install_2-0.php
install/upgrade.php
install/upgrade_1-0.php
install/upgrade_1-1.php
install/upgrade_2-0.php

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

Good luck! and Enjoy!
8
Support / Re: After trying to put the forum into maintenance mode, it “disappeared”
Last post by Steeley -
Quote from: Mrs. Chaos – Thanks for this long and detailed guide. I'm currently working my way through it.

Have you made any progress? Do you have any questions?

(I tend to write and speak assuming the reader is fluent in American English and take liberties with words and phrasing for amusement - "inner-mutant" for "intemittent" , "infuxion" for sickness or malfunction, malfuxion? - etcetera ad nauseum..), just to keep things light.. A good friend (login name on my forum -> "TooGreek") and I used to get carried away with "Pogo-izms" (aka "busterdizing") the language, confusing enough for those fluent in English, never mind "ESL". And that's just the words, "phrasing" is a whole 'nother kettle of worms.)

So if you need clarification or some discussion to understand what exactly I was suggesting in that post , let me know..  I'm really curious to learn what you discover that's hosed, or at least get rid of whatever it was..
(I feel your pain - I'm currently trying to figure out why the old php guestbook on my new server refuses to launch. The log tells me where in the code it fails, but why has me stumped..)

"M R Dux. ya 'ear"
10
Support / Re: After trying to put the forum into maintenance mode, it “disappeared”
Last post by Steeley -
OK, unless @Spuds  comes up with a better idea for troubleshooting the existing configuration, what I would do, now that we know the server appears to be functioning to "minimum requirements" that should support ElkArte, is to back up your entire current server and tuck it away on a really big local drive.  I'd use FileZilla or something similar, to get your entire server file structure copied down. Be patient, it will take awhile.. Pay attention to any corrupted file errors during transfer - them are potential clues!
Once copied down, set the properties on the copy to "read only".
Also, back up the database(s) locally - usually your server tools has that ability.  Make sure you have the June 1 Forum backup (last assumed-good copy) backed up locally too.

Then I would delete the ElkArte directories on the server entirely.

Next, I'd set my file manager on the server to show hidden directories (if not already) and scan through the server file structures. You'll probably see some hidden directories that replicate the file structure of the "unhidden" directories.  Delete any files that are in hidden directories named the same as the ElkArte directories.  (FileZilla shows the "hidden directories" auto-magically. BTW). 

(you might see something like ".hiddensomething/public_html/myforum/goodstuff/... with a file something like  "fubar.xyz" or whatever. Delete the file.) Be especially suspicious of files created or modified on the date/time you were attempting to deal with the suspected DoS attack.
 
You're trying to find and remove any latent 'klingons' spawned and hiding on the server.

Now restore your June 1 backup. and cross your fingers. (I assume the backup includes the database...)

Tell us what happened

If it works, you may not be out of the woods yet, but at least you've got something to work with.
(Work with it until you have the server working correctly, then remove the read-only flag on your local copy,, and delete it!)

And now build another local copy of the now "properly working" server using FileZilla, back up and download the database(s), and tuck them all away safely.

Pro-Tip: Get a directory/file comparison tool.. Later, if something goes awry, you can see what has changed from your last known "good server copy" on your currently malfunctioning one!

But if still no joy, the June 1 backup still doesn't work,  you'll have to decide what to do now.

Remember, you have a complete server backup locally..

(First thing is to ask your host what you need to avoid doing if you want to preserve existing email accounts .. more on that in a bit..)

Your options include:

  • Ask your host to wipe your structure (*), and then restore ONLY the currently working HTML parts of the directory structure from your "FileZilla" backup, and then install the latest ElkArte package and configure it from scratch. Or...


  • Ask your host to wipe your structure, and then restore the entire server from the FileZilla backup, included the database backup, then try to install v.1.1.9 over it and pray.
    (Note, you could try this now, after you've copied the server down locally as above, but if it doesn't work after the "upgrade" - and my bet is it won't - delete the forum structure from the server and the database and copy back the deleted directories and files from the backup copy using FileZilla, and the database from the locally-stored backup, and then go to the beginning of this post and follow it.). Or..


  • Ask your host to wipe your structure, and then restore the entire server from the FileZilla backup, and also include the database backup, and continue troubleshooting.. Again, pay attention to any corrupted file errors during transfer.

(* "Wipe the structure = host will probably just delete the domain entirely, and then recreate it fresh,  Ask if the current email accounts on the mail server will remain so when you copy the file structure back the account support files in your directory are already there, along with the passwords. If that isn't possible (if you delete the server or wipe it, the mail accounts vanish too?), and you have a lot of email accounts with stored messages in them, then don't wipe the server, just delete everything except the structure from the root directory relating to the mail accounts to keep the mail server from wiping out the accounts when the mail file structure disappears. Discuss this approach with your host for validity..)

Or, just wait until @Spuds provides a better idea.. :undecided: