Skip to main content

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 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...


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.


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.


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:

header("Location: blog/");

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).


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 ... ?


  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?

    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!

    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.

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

    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).


Post a Comment

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

Popular posts from this blog

Disable auto save in JetBrains IDE software (IntelliJ IDEA, PyCharm, PhpStorm)

JetBrains provides the following IDE software:
IntelliJ IDEAPhpStormPyCharmRubyMineWebStormAppCodeCLion Google also provides Android Studio which is powered by the IntelliJ platform.

If you come from a different IDE such as Eclipse, you will be unpleasantly surprised to find that JetBrains-branded IDEs automatically save everything the moment you look away. The proponents argue that as you work on your project, you should not have to worry about saving files. But to others, this auto-save behavior which is enabled by default is a curse that catches them by surprise, and a shocking departure from the workflow they are very much used to.

You can change the behavior by altering some settings.

Setting up a local Oracle XE database and importing DMP file

The experience of setting up a local Oracle Express Edition database is not a straight-forward as it should be. The following is supposed to outline what could go wrong and how to go about it the right way. It also includes importing a DMP file (a dump) from another system.
First of all, download the installer from Oracle website. You will need to sign-in to download - the account creation is free. Be sure to choose the correct bit as per your computer (x64 or x86).Extract the download and install XE by running DISK1\setup.exe (and feel nostalgic of the floppy disk era). During installation, you will need to choose a new password. There will also be some details displayed after you enter the new password, such as folders and ports.Be sure to save both password and details in a text file for future reference.I saved it as C:\oraclexe\details.txt.Save password only if it's generic and you are likely to forget. The installation will take a while, but usually, no restart is necessary.O…

Stop having to click Unblock on every downloaded file

CAUTION: The blocking of downloaded files in Windows is a security and safety feature to help prevent your computer from being infected by viruses and other malware. Only disable this feature if you know what you're doing.

I had been plagued by this annoyance since the days of Windows Vista. Any downloaded file, no matter what browser I use, gets tagged as "blocked" by Windows. You can open downloaded documents even though they are blocked, but when you run a downloaded application (such as a setup file) you're presented with a "Security Warning" before you're allowed to run it. It's worse if you extract a downloaded ZIP file with the Windows' built-in ZIP management. Every extracted file is blocked by default.

Being a geek who finds unnecessary "security" prompts annoying, the first thing I do in Windows is to disable the User Account Control (UAC). But I couldn't quite figure out how to disable blocking of downloaded files until …