This article is meant for developers that want to understand or debug the Galaxie Blog Installation process. 

First, if you are having any issues installing this software- please use the 'Menu - Contact' form at the top of the page to contact me. If you have time- also create an issue on the GitHub site. I can't guarantee that I can resolve every issue, but I will do everything I can to personally respond to you!

I may not be able to help you on some issues, such as installing this with Lucee or recommending a hosting provider, but t is important for me to try to enlist your help and notify me when things go awry.

Now to the technical details...

Where the site variable data are stored

The root Application.cfc variables, such as the site URL, are stored in two locations.

  • The blog.ini.cfm file stored in the org/camden/blog/ directory
  • In the Galaxie database

We need to use the .ini file to store variables as the database will not be set up prior to the blog installation. We are also storing the variables in the database after the initial installation as it is more efficient to capture the variables from the database rather than to read from the ini file. Once everything is installed we are also storing the variables in the ColdFusion application scope in order to have them available throughout the application. 

How the installation process works to set and extract these variables

When the blog URL is entered, the root Application.cfc template will determine if the blog is installed by reading the installed argument in the blog.ini file. The default value in the blog.ini file is set to installed=false, and once the Application encounters this it will try to include the 'installer/initial/index.cfm?notInstalled' template. This interface asks the user to fill out the site URL and user information. The interfaces save information that the user provides in the blog.ini file are all in the 'installer/initial/' directory. 

If your installation goes awry and you need to reinstall the application you can manually run this file by commenting out the logic surrounding the cfinclude or appending 'or 1 eq 1' at the end of the conditional logic. 

Once the initial installer is run the application will include the 'installer/insertData.cfm' template to configure the database and install the data. This process may take several minutes to complete as it is building the initial database objects, saves the data entered by the user, reads the text files stored in the /installer/dataFiles/ directory, and populates the initial data in the database. Depending upon memory and server settings this process may time out, potentially during a parseUri loop. If this occurs, refresh your browser. The application contains logic to make sure that the data is not duplicated and the application should resume the installation where it failed.

If you're manually reinstalling the database by forcing the initial installer to run, be sure to remove the code that you used to run the initial installer and force the insertData.cfm template to be run, again by either commenting out the code or by appending a 'or 1 eq 1' statement around the insertData.cfm template.

Why are we are sometimes requiring two manual changes to the file structure?

In two steps during the installation process, we are requiring the user to modify the ApplicationProxy.cfc template in the admin folder (if they are not installing the blog into the blog folder) and requiring the user to substitute 4 files (if they are not using SQL Server). It is an easy process as the installer guides you through the process and provides the exact string to enter into the application proxy template and shows the locations of the substituted files. However, I want to briefly explain the rationale for this manual process. 

First, we need to extend the application template in the admin folder. I have tried many different approaches, some work with CF2016 and fail with CF2021. I can't find a sure-fire way to extend the base application that works with all servers so I am asking the user to change the string within the extends argument in the application proxy. 

We are also asking the user to substitute the persistent ORM-related cfc's as we can't attach dynamic variables in the persistent cfcs. Certain database columns require a very long string, such as the Post.Body column. We are using database-specific language to set a max length and the database vendors have different data types for a long string (for example varchar(max) in SQL Server). We have added logic for many databases, but we have not had the time (nor the resources) to test every database server. If you are encountering problems please see the database vendor documentation for a long string (varchar(max), long text, text, etc).

If you have an idea to make this a fully automated process, please feel free to suggest any potential solutions. 

If you run into problems...

If you're running into an issue while installing the blog software, there are some tools built in the Application.cfc template that may also be used to debug your issues. There is a debug = false statement near the top of the root Application.cfc template. Set this argument to debug = true to print out all of the system variables.

Follow these steps if you want to start over with the reinstall:

  1. Locate the ini file that in the files that you downloaded at /org/camden/blog/blog.ini.cfm and re-upload the file. This file may have changed during an aborted installation attempt.
  2. Open the Application.cfc in the root directory and change the following lines near the very top of the template to true like so:
<cfset debug = true> 
        
<!--- Used for testing purposes. Setting these vars to true will allow you to re-run the installer --->
<cfset reinstallIni = true>
<cfset reinstallDb = true>
  1. Upload the Application.cfm file and try again.
  2. You should see the core application variables printed on the page along with the progress of the installer.

After everything is installed, you may run into a problem when the ColdFusion database logic, ORM, has a hiccup and there is an 'ORM is not configured' error. If this occurs, append /?reinit=1 at the end of the URL and refresh the page. You may run into one more 'uriPartNames' bug when this happens, simply run the /reinit=1 argument again and this problem should clear.

If there are other errors, please annotate the bug on the GitHub site, or make a comment on this site.

This is a final release candidate so I am sure that there are going to be a few bugs. However, please reach out to me or document the issue on the git hub site. I prefer that you document the issue so that others can also see what is going on. I spent a great deal of time developing this for the community and would like to be aware when something goes wrong.