Guide to installing your forum

esoBB is a fork of esoTalk that is lightweight, extensible and easy to set up. It is designed to work with Apache out of the box but can work with Nginx or your own web server while falling back to non-rewrite URLs, though anybody can change this behavior by configuring their web server.

Requirements

esoBB has a few basic requirements which must be met before you can install it. These requirements are standard to any PHP-MySQL-enabled web-forum application and may vary depending on your web server.

A web server or web hosting account running on any operating system with support for PHP.
PHP >=5.6 with the following extensions: gd, mysql, and mbstring
MySQL >=5.7 or another compatible SQL database system (such as MariaDB)
unzip (to unzip the latest release of esoBB)

The esoBB installer will check for many of these requirements and provide troubleshooting instructions if they are found to not be present. Some requirements, such as the PHP version, are vital for operation and may result in a fatal error if left outdated (below PHP 5.6) or beyond the scope of the particular forum version you are installing. esoBB 1.0.0d2 is compatible with PHP 8. The next version of esoBB (delta 3) will require PHP 5.6 or higher.

Example dependency installation

The commands you see below are an example of how you may install the dependencies listed above. Your operating system might require a different set of packages.

# Add "add-apt-repository" command.
apt -y install software-properties-common curl

# Add the main PPA for stable PHP versions so we can use PHP 5.6 and MariaDB.
LC_ALL=C.UTF-8 add-apt-repository -y ppa:ondrej/php
curl -sS https://downloads.mariadb.com/MariaDB/mariadb_repo_setup | sudo bash

# Update repositories...
apt update

# Add universe repository if you are on Ubuntu 18.04.
apt-add-repository universe

# Install the dependencies we need.
apt -y install php8.0 php8.0-{gd,mysql,mbstring} mariadb-server apache2
# If you want to install NGINX instead of Apache, run this command instead of the above one.
#apt -y install php8.0 php8.0-{fpm,gd,mysql,mbstring} mariadb-server nginx

Downloading the software

The first step in installing your forum is to create a folder where the files will be stored and then move them into that folder. Below is an example of how to perform this operation.

mkdir -p /var/www/eso
cd /var/www/eso

As such, the contents of your forum will go in /var/www/eso/ — the forum can be placed in the Apache webserver directory (/var/www/html/) but that isn’t a great solution if you ever plan on hosting multiple websites/forums going forward.

# Download the latest release of eso and unzip it.
wget https://github.com/geteso/eso/releases/download/1.0.0d2/1.0.0d2.tar.gz
tar -xvzf 1.0.0d2.tar.gz
mv 1.0.0d2/* .
rm -r 1.0.0d2 1.0.0d2.tar.gz

# Make a sessions folder (you'll need it for your web server configuration).
mkdir sessions

# Set permissions so that the webserver can read/write to the forum.
chown www-data:www-data avatars plugins skins config install upgrade sessions
chmod 755 avatars plugins skins config install upgrade sessions
cd ..
chown www-data:www-data eso
chmod 755 eso

Why the sessions folder?

By default, PHP saves session data in the /tmp directory. esoBB uses a session save path located in the web server directory in order to avoid issues with other PHP applications that use session data. It is not required to use a custom session save path and the forum should work fine without it in most cases.

Database configuration

You will need a database to store conversations, posts, and users on your forum. All you have to do is configure your database management system and create the database to be used by your forum.

The user and database created for your forum should be unique to this installation. If you are setting up a production forum, it would be wise to choose a strong password and save it for the time being as you will need to provide the credentials of this user in order to set up your forum.

mysql_secure_installation

mysql -u root -p

-- MySQL expects our password to be hashed.
-- You'll get a hash that begins with '*' and you can use this to create the user.
select password('myStrongPassword');

-- You can name your account whatever you want.  For this example, it's named "esoman".
CREATE USER 'esoman'@'localhost' IDENTIFIED BY 'myHashedPassword';

-- Create the database.
-- You can name your database whatever you want.  For this example, it's named "esodb".
CREATE DATABASE esodb;

-- Give the account you just created database privileges.
GRANT ALL PRIVILEGES ON esodb.* TO 'esoman'@'localhost';

-- You can exit the shell now.
-- You won't need to access the shell for the rest of this installation.
EXIT;

Web server configuration

Apache

The default Apache configuration needs to be disabled because we’re not going to be using it.

a2dissite 000-default.conf

The configuration below should be pasted in a file called eso.conf and placed in /etc/apache2/sites-available replacing <domain> with your domain name or IP address. If your forum has been installed in another directory than the example provided in this tutorial, you will need to modify parts of this configuration that reference the path /var/www/eso.

This configuration assumes that you have not yet created SSL certificates. For a production forum, it is recommended that you follow the tutorial on creating SSL certificates which includes a modified Apache configuration. If you are using another web server, you will have to consult the documentation of your software of choice.

<VirtualHost *:80>
	ServerName <domain>
	DocumentRoot "/var/www/eso"

	<IfModule mod_rewrite.c>
		RewriteEngine On
		RewriteCond %{REQUEST_FILENAME} !-f
		RewriteRule ^(.*)$ index.php/$1 [QSA,L]
	</IfModule>

	<IfModule mod_php.c>
		php_admin_value open_basedir /var/www/eso
		php_admin_value upload_tmp_dir /var/www/eso/sessions
		php_admin_value session.save_path /var/www/eso/sessions
	</IfModule>
	
	<Directory "/var/www/eso">
		Options Indexes FollowSymLinks MultiViews
		AllowOverride All
		Require all granted
	</Directory>
</VirtualHost>

Once you’ve created the file above, you may run the commands below in order to enable the configuration.

ln -s /etc/apache2/sites-available/eso.conf /etc/apache2/sites-enabled/eso.conf
a2enmod rewrite
systemctl reload apache2

Nginx

The instructions for configuring the Nginx web server are nearly identical to those for Apache, however the configuration file differs greatly. The default Nginx configuration needs to be disabled because we’re not going to be using it.

unlink /etc/nginx/sites-enabled/default

The configuration below should be pasted in a file called eso.conf and placed in /etc/nginx/sites-available replacing <domain> with your domain name or IP address. If your forum has been installed in another directory than the example provided in this tutorial, you will need to modify parts of this configuration that reference the path /var/www/eso.

If you intend to use the Nginx equivalent of mod rewrite (rewriting URLs so they don’t include “index.php”) then you may need to update your esoBB config.php file. In the config, the useModRewrite string should be changed to true otherwise URLs will not be rewritten. (This is because the esoBB installer will only enable the setting by default so long as the Apache mod_rewrite module exists, which of course requires the Apache web server.)

server {
		listen 80;
		listen [::]:80;
		server_name <domain>;

        root /var/www/eso;
        index index.php;

        location / {
                try_files $uri $uri/ /index.php?$query_string;
        }

        location ~ \.php$ {
                include snippets/fastcgi-php.conf;
                fastcgi_pass unix:/run/php/php8.0-fpm.sock;
				fastcgi_param PHP_VALUE "open_basedir=/var/www/forum";
                fastcgi_param PHP_VALUE "upload_tmp_dir=/var/www/forum/sessions";
                fastcgi_param PHP_VALUE "session.save_path=/var/www/forum/sessions";
        }
}