This article is meant for developers who 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, create an issue on the GitHub site. I can't guarantee that I can resolve every problem, but I will do everything possible to respond to you personally!

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

Now for the technical details...

Table of Contents

Where are the Site Variables and Data Stored?

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

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

We must use the .ini file to store variables, as the database will not be set up before the blog installation. We also store the variables in the database after the initial installation, as capturing the variables from the database is more efficient than reading from the ini file. Once everything is installed, we also store the variables in the ColdFusion application scope to make 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 and install the database. This process may take several minutes to complete as it builds 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 ensure 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 by either commenting out the code or appending a 'or 1 eq 1' statement around the insertData.cfm template.

Why do we sometimes require 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 four files (if they are not using SQL Server). It is an easy process as the installer guides you through the process, provides the exact string to enter into the application proxy template, and shows the locations of the substituted files. However, I want to explain the rationale for this manual process briefly. 

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 encounter problems, please see the database vendor documentation for a long string (varchar(max), long text, text, etc).

If you have an idea for fully automating this process, please suggest any potential solutions. 

If You Run Into Problems...

If you're running into an issue while installing the blog software, some tools are 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 and the installer's progress.

After everything is installed, you may encounter a problem when the ColdFusion database logic, ORM, fails, causing an 'ORM is not configured' error. If this occurs, append /?reinit=1 at the end of the URL and refresh the page. You may encounter 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 comment.

This is a final release candidate, so I am sure there will be a few bugs. However, don't hesitate to contact me or document the issue on the git hub site. I prefer that you report the problem so that others can also see what is happening. I spent much time developing this for the community and would like to know when something goes wrong.