CMS Construction: Just After Basic Installation
A previous post worked through the basic installation of our example flat file CMS (Phile). A bit of bargain basement philosophizing about working arrangements followed. These steps will help to attain these goals.
The previous post already decided to move the canonical content files
to a user account, so that is the present mission.
By the way, the original idea was to keep the content files under
$MY_WwwRoot and create soft links in the user account.
That concept needs to be filed under "bad ideas to avoid".
It just doesn't compute.
Instead, the soft links are created under $MY_WwwRoot.
First Things First: Ensure MY Variables are Defined
The MY variables tip suggests that it is convenient to define shell variables for the current paths of interest:
$ MY_WwwRoot=/var/www
$ MY_CmsRoot="${MY_WwwRoot}"/phile
Create a CMS Testbed Branch and Stay In It
The CMS basic
installation post
left off
where a few simple changes had been made to the master branch.
The first item of business is go get a clean commit of this git branch:
$ cd "${MY_CmsRoot}"
MY_CmsRoot $ git status
nothing to commit (working directory clean)
The rebase procedure talks about this in the context of an entire CMS update procedure.
The next step is to create (-b) and check out a CMS branch.
Let's call it testbed:
MY_CmsRoot $ git checkout -b testbed
By the way, in git checkout does not check out files - it changes branches and checks out the files. This is a bit bewildering from a Subversion perspective.
The key point here is that almost all the changes made to the CMS
from this point on take place in this branch, with the rebasing
procedure used to update the CMS and replay those changes to the
testbed branch.
Decide What is Content vs. CMS infrastructure
The CMS directory contents are listed by the following:
MY_CmsRoot $ ls -lA
Here is the important question: of all those files, which ones really contain the web site content one will be developing, called the canonical content?
All files under content/ certainly qualify.
But all the files under themes/ are in fact web template files
and other necessary files like javascript stubs, so they qualify
as canonical content files.
Other files like fiducial.html, favicon.ico, and info.php are somewhat ambiguous, but they get tweaked, so they can be canonical files.
The files config.php and .htaccess are more ambiguous, but can be
considered canonical files for now, possibly to be reconsidered later on.
Anyway, the important thing is to select a set of files. The set can be tweaked later on.
Create a Canonical Content Directory in a User Account
If one has a container directory named e.g. ~/app/ for all their
work, a new directory ~/app/www/content/ makes sense:
$ cd ~/app
~/app $ mkdir www && cd www
~/app/www $ mkdir content
~/app/www $ MY_ContentRoot=~/app/www/content
At this point step 4 of the permissions procedure could be applied to the new directory, but the full procedure will probably be needed later.
Copy the Canonical Content Files
This can be done using the file manager.
Just copy the files and
directories of the above canonical file set to $MY_ContentRoot,
making sure to copy the entire contents of directories, and files
like .htaccess which tend to not show up in a file manager unless
some key is hit (try ctrl-h).
Delete the Content Files from the CMS and Commit
Don't just delete the canonical file set - use git rm with
a possible recurse option (-r) to remove them from version control:
MY_CmsRoot $ git rm -r content
MY_CmsRoot $ git rm .htaccess
etc....
MY_CmsRoot $ git status
The status command should show all the files as deleted.
By the way, it is possible to move the files in the above step
vs. copying the files - just use the --cached option in the
git rm command to remove the already missing working files from
version control.
It is convenient to commit all (-a) the changes at this time:
MY_CmsRoot $ git commit -a
MY_CmsRoot $ git status
nothing to commit (working directory clean)
It is always good to commit after increments of structural change.
Create Soft Links in the CMS and Commit
The idea here is to replace the items that were just deleted
with soft links (-s) to the copies that were just made:
MY_CmsRoot $ ln -s "${MY_ContentRoot}"/content content
MY_CmsRoot $ ln -s "${MY_ContentRoot}"/.htaccess .htaccess
etc...
MY_CmsRoot $ git status
MY_CmsRoot $ ls -lA
MY_CmsRoot $ git commit -a
MY_CmsRoot $ git status
nothing to commit (working directory clean)
The first status command should show the items as new files.
The ls command should not show any flashing colors indicating
bad links.
The permissions of soft links are all wide open to inherit
the permission of the referent file (i.e., file referred to).
The final status command should show a clean project.
Recheck Permissions of Canonical Content
Since the canonical content file tree is brand new and files were
moved into it, the safe course of action is to reapply the
file permissions procedure
with a $RootPath of $MY_ContentRoot.
That should make things such that when the content is changed,
the permissions stay correct.
Render testbed.com
The site should render as before using same same URL
http://testbed.com.
The big change is that the web content can keep growing while
the CMS stays unchanged.
Put the Canonical Content Under Version Control
First, create a fresh git repository in a brand new .git directory:
MY_ContentRoot $ git init
Now version control your files and directories:
MY_ContentRoot $ git add content
MY_ContentRoot $ git add .htaccess
etc...
Start a .gitignore file that tells git what files not under version
control are to be ignored, and version control this file:
MY_ContentRoot $ touch .gitignore && git add .gitignore
Now perform the first commit:
MY_ContentRoot $ git commit -a
MY_ContentRoot $ git status
The idea is that each commit leaves a clean project. The rest of the work consists of maintaining the project while the content evolves.
Congratulations
You should now have a decent working arrangement to start the actual web site development. Note that the CMS and canonical content git projects are completely separate -- that is, disentangled. As far as git is concerned, a soft link is just another file.
Later posts will show how words like canonical and disentangled are important, when site transformations come into play. For now, all the ingredients are in place to build a web site.
Intra-Site Links
[1]: Flat File CMS Installation: Phile (http://metasupes.com/blog/2016/2016-06-13)
[2]: A Bit of Strategy: The Working Arrangement (http://metasupes.com/blog/2016/2016-06-20)
[3]: Command Line Tip: Define Some Key Shell Variables (http://metasupes.com/comp/workflow/my-variables)
[4]: Procedure to Rebase a CMS to Maintain Local Changes (http://metasupes.com/webdev/tools/git/rebase-cms)
[5]: Apache File Permissions (http://metasupes.com/comp/tools/apache/www-permissions)