Get Started

There are two main options for installing Dropinbase.

Note, Dropinbase can also be installed on Shared Hosting Servers

Ready-made Docker Container

Docker is similar to a virtual machine, but is more efficient regarding resource use. Windows, Linux and macOS are supported. 
Using Docker has the advantage of a pre-configured Dropinbase setup that works "out of the box" and does not conflict with any existing applications.

Note for Windows users: Docker is supported for only specific versions of Windows.

Steps:

  1. Install the correct versions of Node.js and NPM if you haven't done so already:
    • See the "Install Node.js & NPM and optionally NVM" section under Install Angular
  2. Install Docker Desktop if you haven't done so already:
  3. Restart your machine.
  4. Open the Docker console and go to Settings -> General and enable WSL2 ("use the WSL2 based engine").
    • Windows only: If Docker does not run, you may need to install Hyper-V
  5. Open a terminal window (eg PowerShell in Windows), and run the following commands:
  6. npm install dropinbase -g [Enter] - this installs the Dropinbase package globally
  7. cd c:/projects/www - change to the directory of where the project must be installed
  8. dropinbase init myProject - create a new Dropinbase Client project with a name of your choice
    • If PowerShell/Windows responds saying that running scripts is disabled on the system, first run the following:
      • Set-ExecutionPolicy -ExecutionPolicy Unrestricted -Scope Process
    • More options here
  9. cd myProject - change to the directory of the project you just created
  10. Edit the docker-compose.yml file.
    • Change the container_name property to the name of your project, eg myProject.
    • Save and close the file.
  11. npm start - connect to the Dropinbase Docker container and start the services.
    • If any security messages appear, accept them.
  12. Open your web browser and visit https://localhost.
  13. If the system does not work, see the Troubleshooting Installation page.
  14. The Dropinbase Installer should open. Follow the on-screen installation steps.
    • These steps will guide you through installing a Dropinbase database that stores the design of your application.
    • If you are connecting to a database server on your local machine, use the following as host instead of localhost: host.docker.internal
    • The last step will configure the /index.php file to open your new Dropinbase installation instead of the Installer.
  15. To login, the default username is admin and the password is test.
  16. Update the admin password here: http://myapp.dib/nav/dibLoginForm?primary_id=1

Manual Setup

Top | Back

The following steps should lead to a stable system. If any errors occur, see Troubleshooting Installation.

  1. Ensure all the necessary Technology and Requirements are in place.
    1. On Windows you can install WAMP which is easy to manage, and installs some of the prequisites: MariaDb/PHP/Apache.
    2. WAMP installation steps (link my be outdated): http://forum.wampserver.com/read.php?2,138295
  2. Configure a custom URL / Virtual Host for the application (eg http://myapp.dib)
    1. Apache Settings. Remember to restart the webserver.
  3. Install Composer.
  4. Pull a copy of the Dropinbase Client from Github (or copy the files from a working system) to a folder under /www/, eg into /www/myProject/.
  5. Install the Dropinbase Core Framework and other default Composer packages under /vendor/:
    1. Option A (Composer):
      1. Open a terminal window (eg Powershell)
      2. cd to the /www/myProject folder
      3. type: composer install -vvv[Enter] (the -vvv option prints detailed debugging information should you need it).
    2. Option B (Git):
      1. Use Git to clone the Dropinbase Core Framework repository to /www/myProject/vendor/dropinbase/dropinbase: https://github.com/Dropinbase/framework
      2. Note, certain features like converting HTML to PDF documents, single-signon using SAML and sending emails etc. relies on other Composer libraries. See the /composer.json file for details.
    3. Option C (Multi-Tenant):
      1. This is convenient if you already have the Dropinbase Core Framework on your machine
      2. See Dropinbase Documentation for more info
  6. Install Angular:
    1. Note, this only affects the ability to create new containers. Dropinbase should start up without it.
    2. Install Angular
  7. Install a copy of the Dropinbase database:
    1. Option A (Installer):
      1. Ensure the following line in the /www/myProject/index.php file is uncommented (this is the default):
        require './installer.php'; die();
      2. Open a browser and enter your custom url configured above: eg http://myapp.dib/
      3. Ensure you have a database user with permissions to create a database (if not, see SQL under option B below).
      4. Use the Installer to complete the rest of the installation... 
    2. Option B (Manual):
      1. Create a database and a user with permissions to read/write records in all its tables, eg:
        • CREATE DATABASE IF NOT EXISTS `my_new_dib_database` DEFAULT CHARACTER SET = 'utf8mb4' DEFAULT COLLATE 'utf8mb4_unicode_520_ci';
        • CREATE USER 'my_dib_user'@'localhost' IDENTIFIED BY 'my_password';
        • GRANT SELECT, ALTER, CREATE, CREATE TEMPORARY TABLES, DELETE, INDEX, INSERT, UPDATE ON `my_new_dib_database`.* TO 'my_dib_user'@'localhost';
        • FLUSH PRIVILEGES;
      2. Edit the following SQL script, adding use my_new_dib_database; at the top:  /vendor/dropinbase/dropinbase/installer/dropinbase.sql.
      3. Run the script.
  8. Create/edit all the necessary configuration files in the /configs folder. See Dropinbase Documentation for more info.
  9. Delete the /runtime folder (it is recreated when the core framework receives any request).
  10. Navigate to your chosen url, eg http://myapp.dib
  11. To login, the default username is admin and the password is test.
  12. Update the admin password here: http://myapp.dib/nav/dibLoginForm?primary_id=1
  13. See Troubleshooting Installation if needed.

Shared Hosting Servers

Top | Back

Dropinbase works well on shared hosts :).

Use the Manual Setup (above) to get the whole system working on your local machine.

Then:

  1. Create the website folder on the shared host.
  2. Copy your project folder, which includes the /vendor folder, across to the new website's root folder.
    • The /vendor folder can be in any location, as long at the webserver can access it and the include_once() statement in the /index.php file references the new location.
  3. Create the dropinbase database, and any other databases you've installed locally, on the shared host.
  4. Edit the Conn.php file. Ensure connection details are correct and that the array indexes in the Conn.php file match the values of the 'id' fields in the pef_database table.

Some more notes:

  1. Follow the Troubleshooting Installation steps if there are any errors. Particularly check the contents of error logs and responses from network requests in the browser console.
  2. It may be necessary to set $CODEUSE<=2 in Dib.php initially to ensure all /dibCode files are created.
  3. Ensure folder permissions are set (see File System Settings for more info).

Technology and Requirements

Top | Back

A working Dropinbase installation requires the following to be in place:

Dropinbase Setup

  • Dropinbase database: hosts the app design in a MySQL-compatible database engine, eg MySQL / MariaDb / Aurora / etc. 
    It stores the design of the application. Use a copy of it for each application (preferred), or use one copy for multiple applications.
  • Secondary databases: hosts user data. Strictly optional since Dropinbase will work without.
    Can be in SQLite / PostgreSQL / SQL Server / MySQL compatible.
  • Dropinbase PHP Client : application-specific settings in PHP files, styling files, and your own custom code. The Client interfaces with (consumes) the Dropinbase Core Framework.
    Obtain from https://github.com/Dropinbase/dibclient.
    Location: /www/myProjectFolder.
    This is also where developers add their own code, and have the ability to overide /dropins in the Core Framework.
    Note, the /index.php file contains a require statement that loads the Dropinbase Core Framework. Ensure the path is specified correctly.
  • Composer and Third Party Extensions: Dropinbase uses Composer for certain features, and also for installing and updating the Dropinbase Core Framework (see below).
    It is not required to use Composer - you can manually check the Framework out with GIT, or install the files.
    The third party extensions are not required either, but some features like sending emails and creating PDF's won't work without them (Excel exports and imports are provided by DIB).
  • Dropinbase Core Framework: the core framework
    Install with Composer or obtain from https://github.com/Dropinbase/framework.
    Location: /www/myProjectFolder/vendor/dropinbase/dropinbase.
  • Configuraton File Settings: (this is part of Dropinbase PHP Client files) various settings that tie everything together. Especially the following:
    Database connection strings are stored in /projectFolder/configs/Conn.php.
    The index values in Conn.php must match the id values of records in the pef_database table.
    Also set the index values for $DIBDB, $LOGINDB etc in the /configs/DibTmpl.php file (note, this is a template file used to create the /configs/Dib.php file which is actually used).
    Hard-coded and generated file-paths in the /configs/Dib.php file must be correct.

Server Requirements

  • PHP 5.4 and above. .
  • Nginx, or Apache 2.4 and above. See Apache Settings
  • Node.js & NPM (correct versions are important) - necessary on development machines only.
    • Node.js will install npm which will be used to install Angular during installation of Dropinbase.
    • Install Angular - see the "Install Node.js & NPM and optionally NVM" section.
  • 4Gb server space (excl database system & user files).
  • Database system (various):
    • Dropinbase database: MySQL compatible, eg. MySQL/MariaDb/AuroraDb/SkySQL.
      • Ensure your my.ini file is configured for UTF-8 and the correct collation:
        • [mysql]
          • default_character_set=utf8mb4
        • [mysql]
          • character-set-server=utf8mb4
          • collation_server=utf8mb4_unicode_520_ci
    • User database(s):  MySQL compatible/PostgreSQL/SQL Server/Sqlite.
      • Creation of a module to support any other RDBMS is about 2 days work.

File System Permissions

Client Browsers

  • JavaScript & HTML 5 compatible

File System Settings

Top | Back

NOTE: The Dropinbase Installer requires write permissions on the /projectFolder itself to overwrite the index.php file to comment out the line that runs the Installer.php file. If it fails it must be manually done.

On development machines, the webserver user (eg www-data) needs read/write permissions to files in the following folders, and all their subfolders:

  1. /runtime
  2. The various dropin /dibCode folders where files are created
  3. The folders that Angular uses for compiling files
  4. The folder identified by DIB::$USERSPATH in Dib.php - where user's store uploaded files. And any other custom folders in your project like this.
  5. If you intend using the "Add Event & PHP" link on the Designer, the webserver user will need rights to make changes to .php files in the /dropins/xxx/controllers/ folders. 

On production servers all folders should be set to read-only, except the /runtime and user folders (eg DIB::$USERSPATH).

Use the chown and chmod commands to set ownership and file permissions, eg:

  • chown -R yourlinuxuser:www-data /path/to/project

Folders: assign read and execute permissions on all folders to the owner (yourlinuxuser) and the group (webserver user). Execute permissions are needed to enter folders. Ensure these permissions are set on all folders, including the /vendor/dropinbase/dropinbase sub-folders:

  • find /path/to/project -type d -exec chmod 750 {} \;

Files: assign read and write to the owner (yourlinuxuser), and just read to the group (webserver user)

  • find /path/to/project -type f -exec chmod 640 {} \;

Assign read/write permissions to the following folders (-R sets it recursively for subfolders):

  • chmod -R 770 /path/to/project/runtime
  • chmod -R 770 /path/to/project/dropins/myDropin1/dibCode      (must be set to 750 on production server if all dibCode files exist)
  • chmod -R 770 /path/to/project/dropins/myDropin2/dibCode      (must be set to 750 on production server if all dibCode files exist)
  • etc

Assign read/write permissions to folders where Angular generates code (must be set to 750 on production server if all dibCode files exist)

  • cd /path/to/project/vendor/dropinbase/dropinbase/setNgxMaterial/angular
  • chmod -R 770 ./projects/plugins/src
  • mkdir ./src/assets/plugins     (if it does not yet exist)
  • chmod -R 770 ./src/assets/plugins

Assign read/write permissions to folders where users upload files (if applicable):

  • chmod -R 770 path/to/user/folder
  • etc.

Install Node.js and Angular

Top | Back

Install Node.js & NPM and optionally NVM

Install Angular (after installing Dropinbase)

Note, this only affects the ability to create/change containers. Dropinbase should start up without Angular being installed.
This step is not necessary if you are installing the Dropinbase Docker container.


NPM (above) is required to install Angular.
Run the following commands in a terminal window (eg PowerShell on Windows):

  1. cd /www/myProject/vendor/dropinbase/dropinbase/dropins/setNgxMaterial/angular
  2. ls (or dir on Windows) on to list files and folders. If the node_modules folder or the package-lock.json file exists, delete them:
    • rm -rf ./node_modules (or rmdir /s /q node_modules on Windows)
    • rm -rf ./package-lock.json
  3. npm install
  4. If there are any errors: npm audit fix --force

Start the Angular Compiler Watcher

This step is not necessary if you are installing the Dropinbase Docker container.
The Watcher is a Dropinbase script that runs in the background and watches for any Dropinbase containers to compile.
It speeds up the compilation process by avoiding the boostrapping process which runs otherwise each time.

The Watcher should start automatically, but if it doesn't, run the following commands in a terminal window:

  • cd /www/myProject/vendor/dropinbase/dropinbase/dropins/setNgxMaterial/angular - replace /www/myProject with your own.
  • npm run watch:modules

 

Apache Settings

Top | Back

Note, remember to save files and restart Apache for changes to take effect! 

Apache Modules

The following Apache modules must be enabled: 

  • mod_rewrite
  • mod_headers
  • mod_mime (normally enabled)

If you are enabling the /vendor/dropinbase/dropinbase/installer/configs/.htaccess.for.production file, the following modules must be enabled which allows cache files to be zipped:

  • mod_deflate
  • mod_filters
  • mod_expires
  • mod_setenvif

Virtual Host

Adding entries to the virtual host file allows you to host multiple installations of Dropinbase applications on a machine, using a separate URL for each.

Example:

You have two Dropinbase projects, stored in the following two folders:

  • /www/project1/  - we want to use http://dib.net to access it.
  • /www/project2/  - we want to use http://project2.dib.net to access it.
  1. In the main Apache .conf file (eg httpd.conf), the virtual hosts file must be included by ensuring the following line is uncommented/exists:
    (note, the file location and even the name will differ between installations):
    • Windows:
      • Include conf/extra/httpd-vhosts.conf  
    • Linux:
      • IncludeOptional sites-enabled/*.conf
  2. Create a Virtual Host section in the file referenced above for each application. See the examples below...
  3. Note the Allow, Deny and Order directives in older versions of Apache are deprecated and should be avoided. See here for more info.
  4. Port 80 is being used. This setting must correspond with the port configured in httpd.conf
  5. See https://httpd.apache.org/docs/2.4/howto/access.html for more info about allowing and disallowing connections.
  6. AllowOverride all ensures that .htaccess can redirect URLs to the correct PHP files.
  7. Edit your hosts file if needed.
    • On Windows it is normally the following file C:\Windows\System32\drivers\etc\hosts. (Note: open Notepad with "Run as Administrator" in order to save this file).
    • Add lines that correspond with the URLs above, eg:
      • 127.0.0.1       dib.net
      • 127.0.0.1       project2.dib.net
  8. Again, ensure that mod_rewrite is enabled in Apache's extensions.

Virtual Host File Entry Examples

  • <VirtualHost *:80>
    • DocumentRoot "C:/wamp/www/project1"
    • ServerName dib.net
    • <directory "C:/wamp/www/project1">
      • Options -Indexes +FollowSymLinks
      • AllowOverride all
      • Require all granted
    • </directory>
  • </VirtualHost>
  • <VirtualHost *:80>
    • DocumentRoot "C:/wamp/www/project2"
    • ServerName project2.dib.net
    • <directory "C:/wamp/www/project2">
      • Options -Indexes +FollowSymLinks
      • AllowOverride all
      • Require all granted
    • </directory>
  • </VirtualHost>

Error Log

To enable error logging for Apache, ensure the following line is uncommented/exists in httpd.conf (replace the path with your own):

ErrorLog "c:/wamp/logs/apache_error.log"

It may be useful to log errors in Apache's log file for debugging purposes, but this file can become very large depending on the LogLevel parameter (see comments in httpd.conf).

 

Troubleshooting Installation

Top | Back

Note, after applying a fix below, delete the /www/projectFolder/runtime folder before testing further.

  1. Delete the /www/projectFolder/runtime folder
    • When either of the /configs/Dib.php or /runtime/deleteMeToInitDIB.dtxt files do not exist, Dropinbase goes through an initialization process where it creates missing files under /runtime and recreates all active permission entries (for more info, see the point below for Permission log entries).
    • Refresh the website. If there are still problems, continue working through these steps.
  2. Check error logs
    • Dropinbase stores errors in the pef_error_log table by default. If it cannot write to the table, errors are written to the /www/myProject/runtime/logs/error.log file instead.
    • Dropinbase stores permissions errors in the /runtime/logs/Permissions.log file (see section below).
    • Also check the webserver, PHP and operating system error logs.
    • Note: normally the first error listed is also the source of other errors.
  3. The webserver is not starting
    • Check whether another service on the current machine uses the same port (eg Skype could be using port 8080).
      • Check the webserver and the operating system's error/event logs for any indications.
      • Terminate any suspect service and try again.
      • If your webserver uses a custom port, eg 81, then edit the virtual host file entry to match this port. Remember to use the port in URL's, eg http://myapp.dib:81
    • The webserver configuration file has an error (eg httpd.conf for Apache and nginx.conf for Nginx)
      • Check the webserver and the operating system's error/event logs for any indications.
      • Attempt to restart the webserver with each change made.
    • A webserver module or PHP extension may not be properly configured or they may reference a file (eg a .dll) that does not match the operating system. 
      • Remove any references to suspect modules or extensions one-by-one and try starting the webserver again until the problem is found.
      • Consult search engines from there for your specific version of PHP and webserver.
  4. Can Dropinbase connect to the database server? 
    • The /runtime/logs/error.log file will list the error.
    • Check that the values of $DIBDB and $LOGINDB in the /configs/Dib.php file correspond with the id values in the pef_database table and with the index values in the /configs/Conn.php file.
    • See /configs/Example_Conn.php to check whether the syntax of entries in Conn.php are correct.
    • Check that the database server is running. Use a tool like HeidiSql to connect (www.heidisql.com) using the same credentials as setup in the /configs/Conn.php file.
    • Establish if the credentials used in /configs/Conn.php has rights to read/write the dropinbase database tables.
    • See Connecting to Databases in Dropinbase Help for more info.
  5. There are errors in /runtime/logs/Permissions.log (also available in the Designer).
    • You may have been logged out  - log in again.
    • A request was made that violates the permission rules. Most requests have a containerName parameter.
      If this container does not exist in the active permission tables (pef_perm_active and pef_perm_active_list), a permission error will result. 
      • Has the container been deleted? 
      • Rebuild all permissions (use the green button in the Designer) and try again.
    • If the above does not resolve the issue, this is normally an indication that Dropinbase could not populate the active permission tables.
      • Delete the /www/projectFolder/runtime folder (see the first main point above). This will recreate permission records for all containers, including containers in dropins of which the dibCode files exist, but not the original design records. Dropinbase ships with the dibCode files of the Designer and other admin pages, but not with their design records.
      • To identify the dropins that have these dibCode files (but not the design records) the pef_dropin_cache_db_id field in pef_dropin must be set. It references the database which these containers must be linked to (note, for the admin pages it is the main Dropinbase database). 
      • By default dibAdmin (setNgxMaterial) is listed, which means the permission records stored in the following file are incorporated: /vendor/dropinbase/dropinbase/dropins/setNgxMaterial/dibAdmin/dibCode/_permFiles/setNgxMaterial_dibAdmin.dtxt
      • Ensure this file (and others listed) exists, and contains all the necessary records.
      • Ensure the pef_dropin_cache_db_id field points to the main Dropinbase database record for the dibAdmin (setNgxMaterial) dropin record, and any other suppliers' records are also set.
      • Delete the /runtime folder and refresh the website and check again for errors in all the logs.
  6. Check the browser Developer Tools for any errors
    • In the browser, open the Developer Tools (press F12 on Chrome)
    • Refresh the website.
    • Check the Console-tab for errors.
    • Click on the Network-tab, and then on all the requests. For each, check the Preview-tab (under the Network-tab) for errors.
    • Except for errors, any missing requests may also indicate a problem.
  7. The website is not working properly
    • (Linux/Mac only): ensure the webserver has the necessary permissions to read/write files where needed (see File System Settings for more info).
    • Ensure that the virtual host file entry for dropinbase specifies the same port number (eg 80 or 81) that your webserver is using.
    • Restart the webserver.
    • Run the Dropinbase intialization process:
      • Ensure your/configs/DibTmpl.php file configuration is correct.
      • Delete the /www/myProject/runtime folder and refresh the website.
    • Check all the error logs (see above) for any clues.
    • Check that the necessary webserver and PHP settings are enabled and working:
      • If you have Composer installed, run the following in a terminal window (eg Powershell on Windows) to view installed PHP extensions: 
        • cd /www/myProject
        • composer show --platform
      • Alternatively:
        • Uncomment the following line in /www/myProject/index.php:  // phpinfo(); die();
        • Navigate to your site's url, eg http://myapp.dib/ or http://localhost/projectFolderName.
      • Review Apache Settings and check for any PHP errors.
      • Remember to undo any changes to index.php before commencing.
    • Check that the .htaccess file (in the root folder) and the webserver's virtual host file settings are in place and are correct.
    • (PHP <7.1): On Windows, libeay32.dll and ssleay32.dll needs to be accessible through the PATH environment variable for php_curl.dll to work. Add c:/php (your PHP folder) and restart Windows.
    • Use the latest long term stable releases of PHP and your webserver.
  8. The system fails to load after the Installer executed the installation steps:
    • Check that the dropinbase database has been created successfully. If not, you can manually create the database using the manual steps above.
    • Open /www/myProject/index.php
      • include_once("./installer.php"); die(); - line must be commented out.
      • include_once("./vendor/dropinbase/dropinbase/index.php"); die();  - line must be active.
    • Navigate to the application, eg http://myapp.dib  - if it does not work, continue with the troubleshooting procedure below.
  9. The webserver/Dropinbase cant read/write files or execute PHP scripts:
    • Certain folders don't have the necessary read/write permissions. Normally not a problem on Windows.
    • See File System Settings for more info. 
  10. Further help: if the problem is still unresolved, please make use of the Community Forum or official support on https://www.dropinbase.com.