Monday, July 27, 2015

Install a flat file blog in a subfolder in an existing Google App Engine website

 NOTICE:  This post is not very useful as a guide. It is documenting the failures I encountered trying to set up a flat file blog in a subfolder in GAE. Read for your pleasure, but don't try to follow it.

Google App Engine (GAE) allows you to set up a simple PHP website easily and for free with generous quotas - more than enough for a low traffic site. There are several guides on how to get one working. However, GAE works differently from traditional web hosting. Access is tightly controlled through app.yaml file; the static files and application files are separate from each other; and the application file system is not writable.

As WordPress requires a MySQL database (chargeable under Google Cloud SQL), I looked for a flat file blogging alternative.
  • Dropplets looks too simple and feature-poor. It doesn't have a comment system integration out-of-the-box, but Disqus can be added later. There is no rich text editor - plain text editing required in Markdown syntax. Google: 52,300 results
  • FlatPress looks too 90's and unattractive (sorry!). I'm sure you can build a modern look for it. It too doesn't have a ready comment system integration. No rich text editor - uses BBCode. Google: 252,000 results
  • HTMLy looks very promising and feature-rich while being simple. It's under very active development, and it's from South East Asia (Indonesia, to be precise). It doesn't look mature enough (began 2014). Google: 41,900 results
  • TextPress also looks promising, and it is mature (began 2012). The development has become less active as a result, and seems to mainly concentrate on bug fixes. This may be a more stable choice. Google: 312,000 results
  • PivotX supports both flat file and database, and it's very feature-rich to match. However, it looks like an overkill for a simple blog, with too much going on. Although open source, I couldn't find an online repository (like GitHub) for it. Google: 242,000 results
My requirement is to install the blog in a subfolder. Many blog installation tutorials do not cover subfolder installation, and assume the entire site is just the blog, and we will use the blog engine to maintain static pages (basically making it a CMS). However, my use case is different and I don't want that.

Also, since GAE prevents application from writing, I want a blogging platform that can tolerate not being to able to write in the server. HTMLy and TextPress 2.0 have caching system, but this can be disabled easily. What I plan to do is to run a local instance, compose posts, then deploy the changes into GAE.
TIP: Don't just test locally when developing in App Engine SDK. Things that work fine in local environment can break when deployed, and I had been hit in the head by this several times. Always do a test deployment first. Now I use a separate version: test copy where all changes are made and tested locally, then deployed and tested again in the test instance online. Once everything is working fine, then the changes are synced to production version's local copy and deployed to GAE production version.

Before we begin


To add posts and do other things in our blog admin panel, we need to be able to write to the file system. Since the SDK simulates a readonly file system locally, a configuration change is necessary to disable the simulation and set up the blog. Add the following configuration to php.ini file (create one if you don't have, next to app.yaml).

google_app_engine.disable_readonly_filesystem = 1

 NOTICE:  This post is not very useful as a guide. It is documenting the failures I encountered trying to set up a flat file blog in a subfolder in GAE. Read for your pleasure, but don't try to follow it.

HTMLy


HTMLy looked very promising as it's touted to be light, and it looks feature-rich. The readme does indicate the server file system should be writeable, and a cache is maintained. (I have not looked into disabling the cache.)

Obtain the latest release. You can get the ZIP file and extract, but since GAE SDK has OpenSSL extension in PHP, you can use the installer.php instead.

If you use installer.php, put this file in a subfolder called "blog". Add the following handler in app.yaml.
- url: /blog/installer
  script: blog/installer.php


Run the local instance and go to http://localhost:9081/blog/installer (your port may be different). Follow the wizard to set up the initial configuration of your blog. It will be installed in the subfolder "blog" and installer.php will self-destruct after redirecting you to http://localhost/blog/add/post.

Normally, you should get the add post page from the above redirect, but you will get a blank page in the GAE SDK. This is because we don't have a configuration for the URL in app.yaml. Also it is because the port was removed from the URL. Change the handler you had added earlier to the following (we don't need the original handler any more):

- url: /blog/system
  static_dir: blog/system
  application_readable: true

- url: /blog/themes
  static_dir: blog/themes
  application_readable: true

- url: /blog/.*
  script: blog/index.php


You will also need to change the value of site.url in the file blog/config/config.ini to the following (according to your subfolder name). This is to avoid locking the blog HTML into a particular domain and making it act relative to any domain.
site.url = "/blog/"

Now, navigate to http://localhost:9081/blog/ (adding the port back to the redirect URL).

At this point, I gave up as the blog does not work well with GAE restrictions. There are a lot of weird PHP warnings and errors, image upload failed, and the blog does not show my posts despite saving the .md files for them. If you can figure out how to fix them, please post a comment.

Moving on...

TextPress 2.0

TextPress 2.0 require a writeable file system by default as pages are not generated on the fly but cached. This can be changed to make TextPress work with GAE.

Download TextPress latest version. Extract it into the "blog" subfolder.

Set up handlers in app.yaml as follows:

- url: /blog/themes
  static_dir: blog/themes
  application_readable: true

- url: /blog/vendor
  static_dir: blog/vendor
  application_readable: true

- url: /blog/.*
  script: blog/index.php


Change three lines in the configuration in config/config.php as follows

    'site.baseurl'      => '/blog',   // Site URL (Global)
    'assets.prefix'     => '/blog', // prefix to be added with assets files
    'cache' => array(
        'enabled'   => false, // Enable/Disable cache


Start GAE SDK local instance and visit http://localhost:9081/blog/ (note that your port number may be different).

Unfortunately this is where the fun died. TextPress 2 was easier to set up than HTMLy and worked fine without spitting out PHP warning and errors. It even stayed clean without caching or trying to write a bunch of files. It showed all the sample article titles.

BUT: It wouldn't load the actual content of the sample articles, the links are broken. The config is confusing, and the download itself is messy with all the .DS_Store files and different versions from the GitHub version. There was also no admin configuration - it looks like the posts have to be manually added as text files.

Moving on...

PivotX


Extract. Edit app.yaml:

- url: /blog/images
  static_dir: blog/images
  application_readable: true

- url: /blog/pivotx
  static_dir: blog/pivotx
  application_readable: true

- url: /blog/.*
  script: blog/index.php
  #script: blog/pivotx/render.php # second try


Go to site.

Nothing happens - downloads "index.php" (not sure from where). Complete failure. Tried different app.yaml - now website keeps redirecting.

FlatPress


Extract. Edit app.yaml:

- url: /blog/(.*\.(css|gif|ico|jpg|js|png))$
  static_files: blog/\1
  upload: blog/.*\.(css|gif|ico|jpg|js|png)$

- url: /blog/?
  script: blog/index.php

- url: /blog/(.*)\.php$
  script: blog/\1.php

- url: /blog/(.*)
  script: blog/\1.php

Tip: By this point I figured out it's better to use static_files instead of static_dir to only open up the actual static resources rather than the entire directory contents. I should probably have done the same for previous attempts.
Go to site.

Blank page on navigating to blog/setup.php. Complete failure. Unable to determine cause due to unhelpful error message.

Dropplets


Extract. Edit app.yaml:

- url: /blog/(.*\.(css|eot|jpg|js|json|png|svg|ttf|woff))$
  static_files: blog/\1
  upload: blog/.*\.(css|eot|jpg|js|json|png|svg|ttf|woff)$

- url: /blog
  script: blog/redirect.php

- url: /blog/
  script: blog/index.php

- url: /blog/(.*)\.php$
  script: blog/\1.php

- url: /blog/(.*)
  script: blog/mod_rewrite.php


Also add mod_rewrite.php (change 'q' to 'filename') and redirect.php:

<?php
header("Location: blog/");
die();


Go to site.

Kind of worked. The blog-site fluidity appeared broken. Completely broke upon choosing a different template. No error message. Found this to be very light though, at just 238 KB (after deleting the unexplained dropplets.json file).

Conclusion


I have had the most success with TextPress 2, followed by HTMLy (which required a bit more of hacking), then by Dropplets. With FlatPress and PivotX I experienced complete failures.

I am thinking of forking either Dropplets (due to its simple code structure) or TextPress 2 (due to its higher success rate) and cleaning it up to work properly with a GAE-deployed multi-domain subfolder blog (ideally without ever knowing in advance which subfolder or domain it is in).

Or perhaps, Ghost with Node.js ... ?

4 comments:

  1. Hi ad,
    I love dropplets, it's already a good choice for me.
    can you help install dropplets on GAE.
    in your post i don't understand something.

    Also add mod_rewrite.php (change 'q' to 'filename') and redirect.php:

    (change 'q' to 'filename') ?
    can you help me?

    ReplyDelete
    Replies
    1. Just get the mod_rewrite.php script from the link, and edit this line:
      $_GET['q'] = $path;
      to be:
      $_GET['filename'] = $path;

      In any case, I haven't had 100% success with any blogging solution yet. Good luck, and if you made it work, please comment about what you did!

      Delete
    2. Great thank.
      it seem not work for me :) i still can't upload .md file to dropplets or change config.php via save.php.
      i'm opening issues on github. maybe i think we need change upload method with google guild. https://cloud.google.com/appengine/docs/php/googlestorage/user_upload

      I hope dropplets will work on GAE.
      nice to meet you.

      Delete
    3. Nice to meet you too! BTW, you attempted to do the above in your local instance, right? You have to access dropplets through the local instance (running via GAE SDK Launcher) and do the necessary configs and uploads (after you had disabled the readonly file system). After you have done the configs and uploads, then you can deploy into your GAE instance (hosted in Google Servers). But you cannot do any config in the GAE instance itself as GAE exposes a read-only file system to the application (dropplets).

      Delete

Comments are moderated, and are usually posted within 24 hours if approved. You must have a minimum of OpenID to post comments.

LinkWithin

Related Posts with Thumbnails