EWE

To make EWE as widely useful as possible, EWE avoids HTML 5-specific features. You don't need any PHP extensions to run EWE, although some optional modules have additional requirements. The Admin Panel uses javascript but gracefully falls back to PHP if javascript is disabled. Thus, in secure environments, EWE will still work. However, enabling javascript is encouraged as it is more efficient and provides a better user experience. Javascript is used to validate data before leaving a page, but PHP code also validates data for cases when Javascript is disabled or malicious users try to bypass validation.

EWE documentation is organized in four sections: Installation (this file), the Administrator's Guide which describes basic EWE concepts and the Admin Panel user interface, Programmer's Guide which describes how to integrate EWE into your web site(s), and the Technical Information which describes technical details about EWE.

1. Installing EWE

Before Installing EWE

• Linux
• Apache2, Nginx, or IIS
• MySQL V8 or later. Note that EWE avoids using features not available in MySQL 5.6, and should work with 5.6 and 5.7. However, this has not been tested. You will need access to MySQL to create a database. If you do not, you may need your server administrator to do this for you. The administrator can also give you the information needed to configure the database if you don't know the access information. You will need to know the database host IP or URL, database name, database user, and database user password.
• PHP 7.0 or later (note: EWE will probably work with PHP 5.6 as we've avoided any PHP 7-specific features. However, this has not been tested, and besides you ought to be using at least PHP 7 for security sake).
• postfix (or other PHP-integrated mail service) is required if you are going to allow users to recover lost passwords, if you will have two-stage new user registration (recommended), or if you want to set up email alerts.

You have a choice of two zip files to download, depending on your needs.

• Normal install (ewe12.zip): Supports all EWE functionality, but exludes geolocation data.
• Full install (ewegeo12.zip): This option includes all features and capabilities, including geolocation data. The geolocation data that is provided is the MaxMind, Inc. GeoLite2 dataset, which is free under the Creative Commons Attribution 4.0 License. If you do not need geolocation services - or you are going to use the full MaxMind geolocation data (or other geolocation data) - you can download and install ewe12.zip and install the geolocation information later (see below). Note that the geolocation information requires an additional 298 Mb of disk space, and an equivalent amount of database space. EWE installation will also take much longer to complete if geolocation is included. Depending upon server capacity, the install process may take several hours to complete.

1. Download and extract ewe12.zip, and install EWE as described in the sections below.
2. If you are going to use the free geolocation data provided by EWE, download ewegeo12.zip, moving the provided geolocation folder to your EWE service in the existing EWE folder structure.
   Otherwise, download the full geolocation data from MaxMind (*.csv files only), and place them in the geolocation folder in your existing EWE folder structure.
   Note: if you are using other geolocation data, follow the instructions associated with that data set.
3. Go to the admin panel, Geolocation option, and choose Reload database.

1.1. Installing on a new server

1. Unzip ewe12.zip or ewegeo12.zip to your HTML document root folder.
2. Create a database for EWE in MySQL (e.g. "CREATE DATABASE ewe;"). The default name is "ewe", although this can be altered during the setup.
3. You can allow EWE to create the access information file for you or you can manually create it. This file is named "/base/_ewedb.php" on the server. If you manually create it, you should copy the first five lines (and only those lines) from _ewe.php into the new _ewedb.php file and put the appropriate information within the quoted string.
4. Use your web browser to navigate to /base/admin.php on your server. EWE will query you for your database access information and update/create the _ewedb.php file. Note that if directory/file permissions are too restrictive, EWE may not be able to update this file. In such a case, EWE will inform you and you can manually set up the file. Once you do, simply navigate to /base/admin.php to continue EWE setup.
5. EWE will next guide you through creation of an admin user that can access the EWE server settings.
6. EWE will next allow you to configure EWE server options and security defaults for sites you create later.

1. Using the admin panel, add your site and set up any other options according to your needs.
2. Integrate whatever EWE code you want into your existing landing page.
3. Run the security check (Server | Check Security) to check for potential configuration problems.

1.2. Installing on an existing web server

1.2.1 Installing on an existing web server - single site or multiple sites sharing the same document root

1. Do not unzip ewe12.zip or ewegeo12.zip to your HTML document root folder as this may overwrite existing files. Instead, unzip the file somewhere else and then copy the files and folders other than index.php to your HTML root folder. If one or more of these files or folders already exist, see section 1.3, below, for how to install EWE to a nonstandard location.
2. Create a database for EWE in MySQL (e.g. "CREATE DATABASE ewe;"). The default name is "ewe", although this can be altered during the setup.
3. You can allow EWE to create the access information file for you or you can manually create it. This file is named "/base/_ewedb.php" on the server. If you manually create it, you should copy the first five lines (and only those lines) from _ewe.php into the new _ewedb.php file and put the appropriate information within the quoted strings.
4. Use your web browser to navigate to /base/admin.php on your server. At one or more points during installation, your browser may be redirected to your existing landing page or to a 404 error. This is to be expected. When/if this happens, simply navigate to /base/admin.php again. When EWE set up is complete, you will be shown the EWE admin panel.
5. EWE will query you for your database access information and update the _ewedb.php file. Note that if directory/file permissions are too restrictive, EWE may not be able to update this file. In such a case, EWE will inform you and you can manually set up the file. Once you do, simply navigate to /base/admin.php to continue EWE setup.
6. EWE will next guide you through creation of an admin user that can access the EWE server settings.
7. EWE will next allow you to configure EWE server options and security defaults for sites you create later.
8. Integrate whatever EWE code you want into your existing landing page.

1. Using the admin panel, add your site and set up any other options according to your needs.
2. Integrate whatever EWE code you want into your existing landing page.
3. Have the server redirect errors to the appropriate page in the EWE root (eg 404.php).
4. Run the security check (Server | Check Security) to check for potential configuration problems.

1.2.2 Installing on an existing web server - multiple sites with separate document roots

1. Copy the EWE files and folders other than index.php from the initial site to the next site's HTML document root folder (you can skip the geolocation folder since geolocation was set up for the initial site). If one or more of these files or folders already exist, see section 1.3, below, for how to install EWE to a nonstandard location.
2. Copy the _ewedb.php from the initial site to the base folder of the new site.
3. Using the admin panel, add your site and set up any other options according to your needs.
4. Have the server redirect errors for this site to the appropriate page in the EWE root for this site (eg 404.php).
5. Integrate whatever EWE code you want into your existing landing page.

1.3. Installing EWE to a non-standard location

1. Copy _eweroot.php and getroot.php to the root HTML folder. _eweroot.php must be placed in the HTML root folder, regardless of where you want EWE installed.
2. Copy _eweroot.php to _ewecustom.php and edit _ewecustom.php by changing the line that looks like this:
   $eweroot='/';
   Replace the slash with the path to the EWE folder. This path should always start with a slash and will always be relative to the server's HTML document folder. For instance:
   $eweroot='/custom/ewe';
   
3. unzip or copy the EWE files to the location you indicated in the previous step.
4. Create a database for EWE in MySQL (e.g. "CREATE DATABASE ewe;"). The default name is "ewe", although this can be altered during the setup.
5. You can allow EWE to create the access information file for you or you can manually create it. This file is named "/base/_ewedb.php" on the server. If you manually create it, you should copy the first five lines (and only those lines) from _ewe.php into the new _ewedb.php file and put the appropriate information within the quoted strings.
6. Use your web browser to navigate to /base/admin.php on your server. At one or more points during installation, your browser may be redirected to your existing landing page or to a 404 error. This is to be expected. When/if this happens, simply navigate to /base/admin.php again. When EWE set up is complete, you will be shown the EWE admin panel.
7. EWE will query you for your database access information and update the _ewedb.php file. Note that if directory/file permissions are too restrictive, EWE may not be able to update this file. In such a case, EWE will inform you and you can manually set up the file. Once you do, simply navigate to /base/admin.php to continue EWE setup.
8. EWE will next guide you through creation of an admin user that can access the EWE server settings.
9. EWE will next allow you to configure EWE server options and security defaults for sites you create later.

1. If you are installing onto an existing web server, you will need to integrate whatever EWE code you want into your existing landing page.
2. Using the admin panel, add your site and set up any other options according to your needs.
3. Run the security check (Server | Check Security) to check for potential configuration problems.

1.4. Troubleshooting

It appears that you have not properly completed the install of EWE. See the document for details.
This indicates that one or more of the values in base/_ewedb.php is null. Verify that the base/_ewedb.php file contains the proper values.

Either the database is unreachable or the _ewedb.php file is incorrect. Please correct.
This message is accompanied by an error number and error text. This indicates that there was a problem connecting to the database, which could indicate that the values in _ewedb.php are incorrect, or that the database is not responding, or that there is some other problem with the connection between your server and the database. Correct the problem and try again.

Server error 404
As noted above, this can happen when you are installing EWE onto an existing server. Use your web browser to navigate to /base/admin.php on your server each time this happens until the Admin panel comes up. This should only need to be done a couple times.

Timeout
In some cases, such as shared hosting, a timeout may occur during installation. You only need to refresh your page in your browser for the install to continue from where it left off. Note that this situation is one in which you may wish to avoid loading extra data into your database, especially geolocation data, which can result in long delays that cause the timeout. If you've used a download, you should delete all *.txt files (except text.txt) from the classes and base folders and all of the files from the geolocation folder. Then refresh the page to continue the install. Failure to delete these files may result in timeout after timeout as only small parts of the data are loaded before the timeout occurs.

Server errors other than 404
If other errors come up (such as error 500), you can change the /base/_ewedb.php file to show error text. Change the line that looks like this:
$ewe_error_reporting=FALSE;
Change the line to:
$ewe_error_reporting=TRUE;
Once the problem is resolved, you should return the line to it's original value. Leaving this modified may possibly reveal information to the public that would allow attackers to compromise your system. Further, it may prevent some pages from operating properly after EWE installation is complete. If this doesn't provide you with useful information or you have server errors without it, you will have to examine the server error logs to determine the cause of the error. This is typically found in the "/var/log/apache2/error.log" file. However, you may need to check with your server administrator for access to this file.

Continue to the Administrator's Guide