Introduction
One of the nicest aspects of of concrete5.org is its trial application. Visitors to the site can fill out a one-page form, and get their own concrete5 sandbox within 30 seconds. Each demonstration is a unique, isolated concrete5 instance, with its own files directory, while sharing 99% of its code with the other concrete5 demonstrations. Each demo account resolves to username.getconcrete5.com, where username can be chosen by the account holder.
While elegant, this application is not trivial. There are a number of components to the sandbox demo accounts hosted on concrete5.org.
- The container site (getconcrete5.com) must include several custom single pages, mail templates, libraries, controllers and models, which present the visitors with a form used to initiate the demo.
- The container site must have a modified configuration file (config/site.php) that contains some additional parameters used by the demo single pages/controllers.
- Setup your database to allow the creation of additional database users.
- A copy of the shared concrete5 core code base must be available at a certain location on the server.
- A copy of the per-site directory structure (the files/ directory, the config/ directory, etc...) must be available at a certain location on the server, referenced with the container site’s configuration file. This directory must contain a few custom files.
- The web server’s configuration file must be modified in several ways, to create a wildcard entry for the resulting accounts.
- Wildcard DNS must be enabled for the domain.
- Create the required groups in your container site.
- Install and enable the Demo cleanup job in your container site.
- Customize email templates accordingly.
The goal of this document is to present and explain all these requirements, in order to allow web hosting partners to create their own shared source, subdomain-based concrete5 demos. This document assumes an intermediate-to-advanced knowledge of concrete5 and server administration.
Step One: Integrate the required Single Pages, Libraries, Controllers, Jobs, Mail Templates and Model into your Container Site.
Included with this document are some files that will need to be added to your container website.
All files in the “container_site” directory within the included archive go into the root directories of your container website’s concrete5 install.
Make sure to create your /demo single page through the dashboard.
Step Two: Integrate configuration options into you site’s site.php file.
There are a number of constants which must defined to enable these demos. The config/site.php excerpt file included with this white paper contains these. Here is a description of each:
DEMO_BASE_TARGET_DIR
This is the constant that refers to where you demo accounts will live, in the filesystem. For example, if you’d like to setup your web server to serve testuser.yourdomain.com from /var/www/concrete5_demos/testuser/, you’ll want to set this to /var/www/ concrete5_demos.
DEMO_BASE_SOURCE_DIR
While most of concrete5 is centralized, each account (“testuser” in the example above) must have a few files associated with it. Fortunately, these files can live in one place, and will then be copied out each time a new account is made.
DEMO_DB_PREFIX
Every account in your demo system will have its own database. However here you can give them all a prefix.
DEMO_DB_SERVER
The database server that your demo databases will be contained within. Typically “localhost.”
DEMO_HOST
The host at which your demos will live. This does not include the subdomains. For a demo system that uses getconcrete5.com as its base, this option would be “getconcrete5.com”.
DEMO_CREATOR_DB_USER
DEMO_CREATOR_DB_PASS
DEMO_CREATOR_DB_SERVER
DEMO_CREATOR_DB_DATABASE
Information for a root-level database account that will be used to create databases, database user accounts, and create tables within the databases. Typically, this account must have very high access privileges.
The DEMO_CREATOR_DB_DATABASE is not used - but our database abstraction library requires a valid database when instantiating the database object. Typically, you can create an empty database (e.g. “tempdb”) and populate that here. No tables or information will be written to it - it is simply connected to initially.
DEMO_BASE_REMOVE_DIR
A directory on the server where expired demos will be moved to.
RECAPTCHA_PUP_KEY RECAPTCHA_PRI_KEY Information provided by Recaptcha, used for providing a captcha on the demo page. This is optional information, but the included code uses the recaptcha helper to cutdown on demo spam.
DEMO_CREATED_EMAIL
This is the email address that notifications about created demo accounts come from.
ENABLE_CACHE = false
Initially, we required the disabling of concrete5’s cache for the container website, but this may no longer be required.
Step Three: Setup your database to allow the creation of additional database users.
Create the account and temporary databases referenced in the DEMO_CREATOR_* constants above. Ensure that this account has full access to your MySQL server, including GRANT access.
Step Four: Setup the concrete5 core directory in a shared location.
Add your concrete5 shared code base to your server. For the purposes of this tutorial we will assume that the concrete5 shared code base (everything within the “concrete/” directory in a typical download) has been added to /usr/local/share/concrete5/ concrete5.4.0.5/concrete. For more information on utilizing a shared concrete5 code
base, see the white paper “Setting Up and Maintaining a Centralized concrete5 Installation.”
Step Five: Setup the root level of a concrete5 installation in a shared location.
The demo script is responsible for copying a shared set of concrete5 files into each demo account’s directory. These files are located at DEMO_BASE_SOURCE_DIR. These files should be viewable by the web server user. These files should typically be everything included in a typical concrete5 install except the concrete/ directory. Additionally, there are two items that need to be included in this directory, if you wish to add a notification bug to your demo. A notification bug can be useful to inform users that their demo will expire in a certain number of days. These files are:
starter_src/config/site_events.php
starter_src/models/demo_bug.php
The first file is responsible for modifying the concrete5 install to call a certain function when a page is rendered. The second is the class that contains this function, which computes the number of days left on the demo, and displays an HTML-based call to action.
Step Six: Modify the server’s configuration file.
This document assumes you will be running concrete5 on Apache. The following is an example of how we use Apache’s VirtualDocumentRoot directive to map these hostname-based demos to a particular directory on the server.
VirtualDocumentRoot "/var/www/concrete5_demos/%1/"
ServerAlias *.yourdomain.com
AliasMatch ^/concrete/(.*) /usr/local/share/concrete5/concrete5.4.0.5/concrete/$1
php_value include_path ".:/usr/local/share/concrete5/concrete5.4.0.5"
This is pretty straightforward. We’re creating a new virtual host that answers to any subdomain request on yourdomain.com. Whatever the requested subdomain, the request is routed to that subdomain’s directory in /var/www/concrete5_demos/. So testuser1.yourdomain.com would route to /var/www/concrete5_demos/testuser/. The AliasMatch and php_value lines setup our shared source directory, which is located within /usr/local/share/concrete5/.
Step Seven: Wildcard DNS must be activated and setup for the domain.
Make sure to add a wildcard (*) record to your DNS server, pointing to your server. Otherwise, you won’t be able to dynamically add new subdomains to your site, and have them automatically activate and respond in the correct place.
Step Eight: Create the required groups in your container site.
Your demo container site must have several user groups defined for optimum functionality. These groups are:
“Demo Users” “Demo Conversion”
The first group is one that all users who create a demo will automatically enter. The second is a group that adminstrators of your container site can use to separate those who have created a demo from those who have purchased or otherwise converted their demo instance to something else. Those in the Demo Conversion group will not have their accounts wiped.
Step Nine: Create the Required User Attribute(s)
In your container site, create a user attribute of the text type, with the handle "demo_password." This will then hold the password that the user chooses for their admin account in the demo.
Step Ten: Install and enabled the cleanup job in your container site.
An optional concrete5 job is included with this code. This job can be run at any time, and will remove all demo accounts that have been created passed the threshold defined within the job (15 days, by default.) MySQL data will be removed, and the demo account itself will be moved into the directory specified by the DEMO_BASE_REMOVE_DIR directory.
It is very strongly recommended that you test this job thoroughly before running it in a production environment. This job cannot be undone, and will remove MySQL data.
Step Eleven: Customize the demo email templates.
There are two email templates contained within the container_site/mail/ directory. These should be customized for your particular contact information and business purposes.
File Reference
The following is a list of all the files contained within the accompanying zip archive, and a brief overview of their purpose.
Container Site
Files located within the container_site/ directory ought to be placed within the root directory of the site presenting the “Create a Demo” form. config/site.php
This file contains the constants that you must add to your copy of config/site.php. These are described above.
controllers/demo.php
The controller for the /demo single page. This controller is responsible for validating the submission form (including calling the required recaptcha libraries), and redirecting successful demo requests to their accounts.
jobs/demo_expirations.php
A concrete5 job that, when run, will remove all demo accounts that are out of date. This is accomplished by checking the users in the container site’s “Demo Users” group who are not in the “Demo Conversion” group. Those who are within the “warning” threshold will have an email sent to them warning them that their account will soon be deleted. Otherwise the DemoModel::removeDemo() method will be run.
libraries/3rdparty/recaptchalib.php
A third-party library that contains functions used by the ReCaptcha library - which getconcrete5.com uses to cut down demo spam.
mail/demo_expire_soon.php
An email template that is emailed to users whose demos are due to expire soon. mail/demo_registered.php A notification email sent to users who have created a new demo account.
models/demo_account.php
A class that handles most of the behind-the-scenes demo creation work, including the copying of directories from the source to target directory; creating a new MySQL user for the new demo; running the concrete5 installation routine at the location of the new demo; and removing a demo when it is complete.
single_pages/demo.php
The single page template that the end user sees when they come to create a demo.
Starter Source
The following items must be present in the DEMO_BASE_SOURCE_DIR. These will be copied out to every demo directory.
starter_src/config/site_events.php
This file contains a special event that is run on the rendering of every page, in order to include the “Register Your Demo” HTML call to action.
starter_src/models/demo_bug.php
A file that is referenced by site_events.php above.
Introduction
One of the nicest aspects of of concrete5.org.com is its trial application. Visitors to the site can fill out a one-page form, and get their own concrete5 sandbox within 30 seconds. Each demonstration is a unique, isolated concrete5 instance, with its own files directory, while sharing 99% of its code with the other concrete5 demonstrations. Each demo account resolves to username.getconcrete5.com, where username can be chosen by the account holder.
While elegant, this application is not trivial. There are a number of components to the sandbox demo accounts hosted on getconcrete5.com.
- The container site (getconcrete5.com) must include several custom single pages, mail templates, libraries, controllers and models, which present the visitors with a form used to initiate the demo.
- The container site must have a modified configuration file (config/site.php) that contains some additional parameters used by the demo single pages/controllers.
- Setup your database to allow the creation of additional database users.
- A copy of the shared concrete5 core code base must be available at a certain location on the server.
- A copy of the per-site directory structure (the files/ directory, the config/ directory, etc...) must be available at a certain location on the server, referenced with the container site’s configuration file. This directory must contain a few custom files.
- The web server’s configuration file must be modified in several ways, to create a wildcard entry for the resulting accounts.
- Wildcard DNS must be enabled for the domain.
- Create the required groups in your container site.
- Install and enable the Demo cleanup job in your container site.
- Customize email templates accordingly.
The goal of this document is to present and explain all these requirements, in order to allow web hosting partners to create their own shared source, subdomain-based concrete5 demos. This document assumes an intermediate-to-advanced knowledge of concrete5 and server administration.
Step One: Integrate the required Single Pages, Libraries, Controllers, Jobs, Mail Templates and Model into your Container Site.
Included with this document are some files that will need to be added to your container website.
All files in the “container_site” directory within the included archive go into the root directories of your container website’s concrete5 install.
Make sure to create your /demo single page through the dashboard.
Step Two: Integrate configuration options into you site’s site.php file.
There are a number of constants which must defined to enable these demos. The config/site.php excerpt file included with this white paper contains these. Here is a description of each:
DEMO_BASE_TARGET_DIR
This is the constant that refers to where you demo accounts will live, in the filesystem. For example, if you’d like to setup your web server to serve testuser.yourdomain.com from /var/www/concrete5_demos/testuser/, you’ll want to set this to /var/www/ concrete5_demos.
DEMO_BASE_SOURCE_DIR
While most of concrete5 is centralized, each account (“testuser” in the example above) must have a few files associated with it. Fortunately, these files can live in one place, and will then be copied out each time a new account is made.
DEMO_DB_PREFIX
Every account in your demo system will have its own database. However here you can give them all a prefix.
DEMO_DB_SERVER
The database server that your demo databases will be contained within. Typically “localhost.”
DEMO_HOST
The host at which your demos will live. This does not include the subdomains. For a demo system that uses getconcrete5.com as its base, this option would be “getconcrete5.com”.
DEMO_CREATOR_DB_USER
DEMO_CREATOR_DB_PASS
DEMO_CREATOR_DB_SERVER
DEMO_CREATOR_DB_DATABASE
Information for a root-level database account that will be used to create databases, database user accounts, and create tables within the databases. Typically, this account must have very high access privileges.
The DEMO_CREATOR_DB_DATABASE is not used - but our database abstraction library requires a valid database when instantiating the database object. Typically, you can create an empty database (e.g. “tempdb”) and populate that here. No tables or information will be written to it - it is simply connected to initially.
DEMO_BASE_REMOVE_DIR
A directory on the server where expired demos will be moved to.
RECAPTCHA_PUP_KEY RECAPTCHA_PRI_KEY Information provided by Recaptcha, used for providing a captcha on the demo page. This is optional information, but the included code uses the recaptcha helper to cutdown on demo spam.
DEMO_CREATED_EMAIL
This is the email address that notifications about created demo accounts come from.
ENABLE_CACHE = false
Initially, we required the disabling of concrete5’s cache for the container website, but this may no longer be required.
Step Three: Setup your database to allow the creation of additional database users.
Create the account and temporary databases referenced in the DEMO_CREATOR_* constants above. Ensure that this account has full access to your MySQL server, including GRANT access.
Step Four: Setup the concrete5 core directory in a shared location.
Add your concrete5 shared code base to your server. For the purposes of this tutorial we will assume that the concrete5 shared code base (everything within the “concrete/” directory in a typical download) has been added to /usr/local/share/concrete5/ concrete5.4.0.5/concrete. For more information on utilizing a shared concrete5 code
base, see the white paper “Setting Up and Maintaining a Centralized concrete5 Installation.”
Step Five: Setup the root level of a concrete5 installation in a shared location.
The demo script is responsible for copying a shared set of concrete5 files into each demo account’s directory. These files are located at DEMO_BASE_SOURCE_DIR. These files should be viewable by the web server user. These files should typically be everything included in a typical concrete5 install except the concrete/ directory. Additionally, there are two items that need to be included in this directory, if you wish to add a notification bug to your demo. A notification bug can be useful to inform users that their demo will expire in a certain number of days. These files are:
starter_src/config/site_events.php
starter_src/models/demo_bug.php
The first file is responsible for modifying the concrete5 install to call a certain function when a page is rendered. The second is the class that contains this function, which computes the number of days left on the demo, and displays an HTML-based call to action.
Step Six: Modify the server’s configuration file.
This document assumes you will be running concrete5 on Apache. The following is an example of how we use Apache’s VirtualDocumentRoot directive to map these hostname-based demos to a particular directory on the server.
VirtualDocumentRoot "/var/www/concrete5_demos/%1/"
ServerAlias *.yourdomain.com
AliasMatch ^/concrete/(.*) /usr/local/share/concrete5/concrete5.4.0.5/concrete/$1
php_value include_path ".:/usr/local/share/concrete5/concrete5.4.0.5"
This is pretty straightforward. We’re creating a new virtual host that answers to any subdomain request on yourdomain.com. Whatever the requested subdomain, the request is routed to that subdomain’s directory in /var/www/concrete5_demos/. So testuser1.yourdomain.com would route to /var/www/concrete5_demos/testuser/. The AliasMatch and php_value lines setup our shared source directory, which is located within /usr/local/share/concrete5/.
Step Seven: Wildcard DNS must be activated and setup for the domain.
Make sure to add a wildcard (*) record to your DNS server, pointing to your server. Otherwise, you won’t be able to dynamically add new subdomains to your site, and have them automatically activate and respond in the correct place.
Step Eight: Create the required groups in your container site.
Your demo container site must have several user groups defined for optimum functionality. These groups are:
“Demo Users” “Demo Conversion”
The first group is one that all users who create a demo will automatically enter. The second is a group that adminstrators of your container site can use to separate those who have created a demo from those who have purchased or otherwise converted their demo instance to something else. Those in the Demo Conversion group will not have their accounts wiped.
Step Nine: Create the Required User Attribute(s)
In your container site, create a user attribute of the text type, with the handle "demo_password." This will then hold the password that the user chooses for their admin account in the demo.
Step Ten: Install and enabled the cleanup job in your container site.
An optional concrete5 job is included with this code. This job can be run at any time, and will remove all demo accounts that have been created passed the threshold defined within the job (15 days, by default.) MySQL data will be removed, and the demo account itself will be moved into the directory specified by the DEMO_BASE_REMOVE_DIR directory.
It is very strongly recommended that you test this job thoroughly before running it in a production environment. This job cannot be undone, and will remove MySQL data.
Step Eleven: Customize the demo email templates.
There are two email templates contained within the container_site/mail/ directory. These should be customized for your particular contact information and business purposes.
File Reference
The following is a list of all the files contained within the accompanying zip archive, and a brief overview of their purpose.
Container Site
Files located within the container_site/ directory ought to be placed within the root directory of the site presenting the “Create a Demo” form. config/site.php
This file contains the constants that you must add to your copy of config/site.php. These are described above.
controllers/demo.php
The controller for the /demo single page. This controller is responsible for validating the submission form (including calling the required recaptcha libraries), and redirecting successful demo requests to their accounts.
jobs/demo_expirations.php
A concrete5 job that, when run, will remove all demo accounts that are out of date. This is accomplished by checking the users in the container site’s “Demo Users” group who are not in the “Demo Conversion” group. Those who are within the “warning” threshold will have an email sent to them warning them that their account will soon be deleted. Otherwise the DemoModel::removeDemo() method will be run.
libraries/3rdparty/recaptchalib.php
A third-party library that contains functions used by the ReCaptcha library - which getconcrete5.com uses to cut down demo spam.
mail/demo_expire_soon.php
An email template that is emailed to users whose demos are due to expire soon. mail/demo_registered.php A notification email sent to users who have created a new demo account.
models/demo_account.php
A class that handles most of the behind-the-scenes demo creation work, including the copying of directories from the source to target directory; creating a new MySQL user for the new demo; running the concrete5 installation routine at the location of the new demo; and removing a demo when it is complete.
single_pages/demo.php
The single page template that the end user sees when they come to create a demo.
Starter Source
The following items must be present in the DEMO_BASE_SOURCE_DIR. These will be copied out to every demo directory.
starter_src/config/site_events.php
This file contains a special event that is run on the rendering of every page, in order to include the “Register Your Demo” HTML call to action.
starter_src/models/demo_bug.php
A file that is referenced by site_events.php above.